cmake windows
This commit is contained in:
antpoms
parent
f698a38c7e
commit
2ace28d941
387 changed files with 96179 additions and 1 deletions
|
|
@ -0,0 +1,90 @@
|
|||
<html>
|
||||
<head>
|
||||
<title>White Papers | Studio API 3D Events</title>
|
||||
<link rel="stylesheet" href="style/docs.css">
|
||||
<link rel="stylesheet" href="style/code_highlight.css">
|
||||
<script type="text/javascript" src="scripts/language-selector.js"></script></head>
|
||||
<body>
|
||||
<div class="docs-body">
|
||||
<div class="manual-toc">
|
||||
<p>FMOD Engine User Manual 2.03</p>
|
||||
<ul>
|
||||
<li><a href="welcome.html">Welcome to the FMOD Engine</a></li>
|
||||
<li><a href="studio-guide.html">Studio API Guide</a></li>
|
||||
<li><a href="core-guide.html">Core API Guide</a></li>
|
||||
<li><a href="platforms.html">Platform Details</a></li>
|
||||
<li class="manual-current-chapter manual-inactive-chapter"><a href="white-papers.html">White Papers</a><ul class="subchapters"><li><a href="white-papers-getting-started.html">Getting Started</a></li><li><a href="white-papers-3d-reverb.html">3D Reverb</a></li><li><a href="white-papers-3d-sounds.html">3D Sounds</a></li><li><a href="white-papers-asynchronous-io.html">Asynchronous I/O</a></li><li><a href="white-papers-cpu-performance.html">CPU Performance</a></li><li><a href="white-papers-dsp-architecture.html">DSP Architecture and Usage</a></li><li><a href="white-papers-dsp-plugin-api.html">DSP Plug-in API</a></li><li><a href="white-papers-handle-system.html">Handle System</a></li><li><a href="white-papers-memory-management.html">Memory Management</a></li><li><a href="white-papers-non-blocking-sound-creation.html">Non-blocking Sound Creation</a></li><li><a href="white-papers-spatial-audio.html">Spatial Audio</a></li><li class="manual-current-chapter manual-active-chapter"><a href="white-papers-studio-3d-events.html">Studio API 3D Events</a></li><li><a href="white-papers-studio-threads.html">Studio API Threads</a></li><li><a href="white-papers-threads.html">Threads and Thread Safety</a></li><li><a href="white-papers-transitioning-from-fmodex.html">Transitioning from FMOD Ex</a></li><li><a href="white-papers-using-multiple-reverbs.html">Using Multiple Reverbs</a></li><li><a href="white-papers-virtual-voices.html">Virtual Voices</a></li></ul></li>
|
||||
<li><a href="studio-api.html">Studio API Reference</a></li>
|
||||
<li><a href="core-api.html">Core API Reference</a></li>
|
||||
<li><a href="fsbank-api.html">FSBank API Reference</a></li>
|
||||
<li><a href="plugin-api.html">Plug-in API Reference</a></li>
|
||||
<li><a href="effects-reference.html">Effects Reference</a></li>
|
||||
<li><a href="troubleshooting.html">Troubleshooting</a></li>
|
||||
<li><a href="glossary.html">Glossary</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="manual-content api">
|
||||
<h1>5. White Papers | Studio API 3D Events</h1>
|
||||
<div class="toc">
|
||||
<ul>
|
||||
<li><a href="#studio-3d-events">Studio 3D Events</a><ul>
|
||||
<li><a href="#coordinate-systems-and-handedness">Coordinate Systems and Handedness</a></li>
|
||||
<li><a href="#updating-orientations">Updating orientations</a></li>
|
||||
<li><a href="#fmod-spatializer">FMOD Spatializer</a></li>
|
||||
<li><a href="#fmod-object-spatializer">FMOD Object Spatializer</a></li>
|
||||
<li><a href="#automatic-parameters">Automatic Parameters</a></li>
|
||||
<li><a href="#multiple-listeners">Multiple Listeners</a><ul>
|
||||
<li><a href="#studio-spatialization-for-multiple-listeners">Studio Spatialization for Multiple Listeners</a></li>
|
||||
<li><a href="#studio-spatialization-for-listener-weights">Studio Spatialization for Listener Weights</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a href="#listener-mask">Listener Mask</a></li>
|
||||
<li><a href="#doppler">Doppler</a></li>
|
||||
<li><a href="#automatic-parameters-and-multiple-listeners">Automatic Parameters and Multiple Listeners</a></li>
|
||||
<li><a href="#interface-with-core-api">Interface with Core API</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<h2 id="studio-3d-events"><a href="#studio-3d-events">Studio 3D Events</a></h2>
|
||||
<p>This section will introduce you to using 3D sound with <a href="glossary.html#fmod-studio">FMOD Studio</a> events.</p>
|
||||
<h3 id="coordinate-systems-and-handedness"><a href="#coordinate-systems-and-handedness">Coordinate Systems and Handedness</a></h3>
|
||||
<p>FMOD Studio shares the same coordinate system as the core API. See the <a href="white-papers-3d-sounds.html">3D Sounds</a> white paper for details.</p>
|
||||
<h3 id="updating-orientations"><a href="#updating-orientations">Updating orientations</a></h3>
|
||||
<p>The programmer needs to call <a class="apilink" href="studio-api-system.html#studio_system_setlistenerattributes">Studio::System::setListenerAttributes</a> once per frame for the listener, and to update 3D events with <a class="apilink" href="studio-api-eventinstance.html#studio_eventinstance_set3dattributes">Studio::EventInstance::set3DAttributes</a>. It is important to update all orientations before calling <a class="apilink" href="studio-api-system.html#studio_system_update">Studio::System::update</a>. If some orientations are set before <a class="apilink" href="studio-api-system.html#studio_system_update">Studio::System::update</a> and some are set afterwards, then some frames may end up having old positions relative to others. This is particularly important when both the listener and the events are moving fast and together - if there are frames where the listener moves but the event does not it becomes very noticeable.</p>
|
||||
<h3 id="fmod-spatializer"><a href="#fmod-spatializer">FMOD Spatializer</a></h3>
|
||||
<p>FMOD Studio supports spatializing events by placing an <a href="effects-reference.html#pan">FMOD spatializer effect</a> on the event master track. It is possible to use other sorts of spatializers by replacing the FMOD spatializer with a different type of <a href="glossary.html#effect">effect</a>, for example a third party spatializer.</p>
|
||||
<h3 id="fmod-object-spatializer"><a href="#fmod-object-spatializer">FMOD Object Spatializer</a></h3>
|
||||
<p>The <a href="effects-reference.html#object-panner">object spatializer</a> is a special type of spatializer that interfaces with object-based output modes such as Dolby Atmos. These output modes accept mono <a href="glossary.html#signal">signals</a> with a 3D position and do their own spatialization and mixing to the final speaker configuration. To use object spatializers, the programmer has to specify an output mode that supports object based spatialization, otherwise the signal will be mixed down at the final stage by FMOD.</p>
|
||||
<p>The benefit of the object spatializer is that it allows the sound designer to leverage object-based technologies. It does come at a cost, however, as the signal leaves the mix at the object spatializer and does not receive the benefit of <a href="glossary.html#dsp-effect">DSP effects</a> on parent buses like signals run though normal spatializers do. The object spatializer automatically bases its volume on the combined volumes of parent buses for basic mixing, but no complex effects can be used. For this reason, the mix has to be set up very carefully with knowledge of the limitations of the object spatialization.</p>
|
||||
<p>It is possible for the sound designer to use a mixture of normal 3D spatialized events and object-spatialized 3D events. Normal events will have signal going through the mixer hierarchy, and object-based events will have signal that leaves the mix at the master track. As far as the programming API goes, both kinds of events are treated exactly the same.</p>
|
||||
<h3 id="automatic-parameters"><a href="#automatic-parameters">Automatic Parameters</a></h3>
|
||||
<p>FMOD Studio supports setting automations based on parameters that automatically update based on position. For example, the sound designer could add a volume automation based on Distance, with a 2D panning that is automated on the Direction parameter. The event is still considered 3D in that case, even if it has no spatializer on the master track.</p>
|
||||
<p>An event may have both a spatializer on the master track, as well as an automation based on a Distance parameter. As the event and listener moves, both the spatializer and the automation will be updated.</p>
|
||||
<h3 id="multiple-listeners"><a href="#multiple-listeners">Multiple Listeners</a></h3>
|
||||
<p>FMOD Studio supports multiple listeners. Call <a class="apilink" href="studio-api-system.html#studio_system_setnumlisteners">Studio::System::setNumListeners</a> to set the number of listeners, and use <a class="apilink" href="studio-api-system.html#studio_system_setlistenerattributes">Studio::System::setListenerAttributes</a> to set the orientations for listeners, with an index for the listener.</p>
|
||||
<h4 id="studio-spatialization-for-multiple-listeners"><a href="#studio-spatialization-for-multiple-listeners">Studio Spatialization for Multiple Listeners</a></h4>
|
||||
<p>Consider the case of an event with three nearby listeners. In this case, listener A is slightly closer to the event than B, and C is the furthest away, outside the max distance of the event.</p>
|
||||
<p>The Studio spatializer will take listener A and B into account. The gain will be based off the closest listener distance (in this case, the distance to listener A). Listener B will have an effect on the spatialization. However, both A and B agree that the event is to the front, so the final pan matrix will be towards the front speakers. Listener C has no effect on the calculation since it is out of range.</p>
|
||||
<p><img alt="Multiple listeners" src="images/3d-studio-1.png" /></p>
|
||||
<p>Consider this case where listener A and B have moved and now the event is to the right of A and to the left of B. In this case, the gain will be based of the closest listener distance (which is B), but the pan matrix will have signal out of both the left and the right since both listeners have an effect on the mix. If A moved further away then the contribution of A would diminish and to the signal would start to come more out of the left speakers. If A moved further enough away, the signal would smoothly interpolate to just B having an influence on the spatialization.</p>
|
||||
<p><img alt="Multiple listeners" src="images/3d-studio-2.png" /></p>
|
||||
<h4 id="studio-spatialization-for-listener-weights"><a href="#studio-spatialization-for-listener-weights">Studio Spatialization for Listener Weights</a></h4>
|
||||
<p>Listener weights can be set using <a class="apilink" href="studio-api-system.html#studio_system_setlistenerweight">Studio::System::setListenerWeight</a>. This allows listeners to fade in and out of existence, as well as to allow cross-fading of listeners to a new position. In the following picture, we have 4 listeners. Listener C is out of range so it has no influence, and listener D has 0% weighting so it has no influence either. The remaining two listeners have a weight of 40% and 60%. In this example, perhaps the camera is teleporting to a new position and the game is smoothly interpolating to a new orientation.</p>
|
||||
<p>The gain is a weighted average between A and B, so it is equivalent to having a distance somewhere between the two listeners. The spatialization of the signal is a mixture of A and B. A is further away and has a lower weight, so the biggest contribution is due to B, meaning the signal sounds mostly in the front speakers. If you imagine blending from A to B, the signal will smoothly interpolate from the back speakers to the front and get louder when the weights scale from A to B.</p>
|
||||
<p><img alt="Multiple listener weights" src="images/3d-studio-3.png" /></p>
|
||||
<h3 id="listener-mask"><a href="#listener-mask">Listener Mask</a></h3>
|
||||
<p>Events can have a mask that specifies which listeners are active for that event. By default all listeners apply to all events. By calling <a class="apilink" href="studio-api-eventinstance.html#studio_eventinstance_setlistenermask">Studio::EventInstance::setListenerMask</a>, some listeners can be disabled for that event so that they have no influence on the panning. This could be used to group some events and listeners together and have that set only affected by that one listener. When performing the calculation above, any listener not included in the mask is ignored and is as if it does not exist for that event. It is an error to set a combination of mask and weight such that no listener is active for an event.</p>
|
||||
<h3 id="doppler"><a href="#doppler">Doppler</a></h3>
|
||||
<p>FMOD events support doppler. The sound designer specifies doppler on a per event basis with a scale, so some events may be affected less than others. Doppler is calculated using listener and event velocities; it is up to the programmer to correctly specify velocity values using <a class="apilink" href="studio-api-eventinstance.html#studio_eventinstance_set3dattributes">Studio::EventInstance::set3DAttributes</a> and <a class="apilink" href="studio-api-system.html#studio_system_setlistenerattributes">Studio::System::setListenerAttributes</a>. The scale of doppler can be specified at initialization time using <a class="apilink" href="core-api-system.html#system_set3dsettings">System::set3DSettings</a>.</p>
|
||||
<p>For the case of multiple listeners, the doppler is based on the closest listener. If listener has a weight then it is a combination of the closest listeners up to 100%. For example if there were three listeners at increasing distance with weight of 60%, 60% and 60%, then the doppler would be calculated from 60% of the first listener, 40% of the second, and 0% of the third.</p>
|
||||
<h3 id="automatic-parameters-and-multiple-listeners"><a href="#automatic-parameters-and-multiple-listeners">Automatic Parameters and Multiple Listeners</a></h3>
|
||||
<p>If there are multiple listeners, an FMOD Studio event's automatic parameters are based on the closest listener. If the closest listener has a weight, then the event's automatic parameters instead use a combination of the closest listeners, up to a total weight of 100%. For example, if there are three listeners at increasing distance with weights of 60%, 60% and 60%, then the automatic parameters would be calculated from 60% of the first listener, 40% of the second, and 0% of the third.</p>
|
||||
<h3 id="interface-with-core-api"><a href="#interface-with-core-api">Interface with Core API</a></h3>
|
||||
<p>When calling <a class="apilink" href="studio-api-system.html#studio_system_setnumlisteners">Studio::System::setNumListeners</a> and <a class="apilink" href="studio-api-system.html#studio_system_setlistenerattributes">Studio::System::setListenerAttributes</a>, there is no need to call the equivalent Core API functions <a class="apilink" href="core-api-system.html#system_set3dnumlisteners">System::set3DNumListeners</a> and <a class="apilink" href="core-api-system.html#system_set3dlistenerattributes">System::set3DListenerAttributes</a>, as FMOD Studio passes the information into the Core API automatically. This means it is possible to have a mixture of FMOD Studio 3D events and Core API 3D <a class="apilink" href="core-api-channel.html">Channel</a>s playing at the same time.</p></div>
|
||||
|
||||
<p class="manual-footer">FMOD Engine User Manual 2.03.07 (2025-04-02). © 2025 Firelight Technologies Pty Ltd.</p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
</div>
|
||||
Loading…
Add table
Add a link
Reference in a new issue