343 lines
43 KiB
HTML
343 lines
43 KiB
HTML
<html>
|
|
<head>
|
|
<title>White Papers | Transitioning from FMOD Ex</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><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 class="manual-current-chapter manual-active-chapter"><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 | Transitioning from FMOD Ex</h1>
|
|
<div class="toc">
|
|
<ul>
|
|
<li><a href="#transitioning-between-fmod-ex-and-fmod-studio">Transitioning between FMOD Ex and FMOD Studio</a><ul>
|
|
<li><a href="#studio-api-versus-fmod-designer-api">Studio API Versus FMOD Designer API</a><ul>
|
|
<li><a href="#eventsystem-and-eventsystem_create">EventSystem and EventSystem_Create</a></li>
|
|
<li><a href="#eventproject">EventProject</a></li>
|
|
<li><a href="#fev-and-fsb-files">FEV and FSB Files</a></li>
|
|
<li><a href="#eventgroup">EventGroup</a></li>
|
|
<li><a href="#event">Event</a></li>
|
|
<li><a href="#retrieving-events">Retrieving Events</a></li>
|
|
<li><a href="#eventparameter">EventParameter</a></li>
|
|
<li><a href="#sustain-points-and-key-off">Sustain Points and Key Off</a></li>
|
|
<li><a href="#eventcategory">EventCategory</a></li>
|
|
<li><a href="#eventreverb">EventReverb</a></li>
|
|
<li><a href="#eventqueue-and-eventqueueentry">EventQueue and EventQueueEntry</a></li>
|
|
<li><a href="#musicsystem-and-musicprompt">MusicSystem and MusicPrompt</a></li>
|
|
<li><a href="#neteventsystem">NetEventSystem</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#fmod-studios-core-api-versus-fmod-exs-core-api">FMOD Studio's Core API Versus FMOD Ex's Core API</a><ul>
|
|
<li><a href="#new-features">New features</a><ul>
|
|
<li><a href="#no-more-recommended-startup-sequence">No more 'recommended startup sequence'</a></li>
|
|
<li><a href="#added-new-dsp-effects">Added new DSP effects</a></li>
|
|
<li><a href="#new-file-format-support">New file format support</a></li>
|
|
<li><a href="#dolby-atmos-support">Dolby Atmos support</a></li>
|
|
<li><a href="#new-dsp-mixing-engine">New DSP mixing engine</a></li>
|
|
<li><a href="#added-plug-in-info-helper-function">Added plug-in info helper function</a></li>
|
|
<li><a href="#added-background-suspension-support">Added background suspension support</a></li>
|
|
<li><a href="#channelgroups-volume-and-panning-are-now-dsp-based-rather-than-reaching-down-to-the-channels-of-the-child-channelgroups">ChannelGroups volume and panning are now DSP based, rather than reaching down to the Channels of the child ChannelGroups.</a></li>
|
|
<li><a href="#added-additional-output-streams">Added additional output streams</a></li>
|
|
<li><a href="#added-sound-helper-function">Added Sound helper function</a></li>
|
|
<li><a href="#added-sample-volume-control">Added sample volume control</a></li>
|
|
<li><a href="#added-utf8-support">Added UTF8 support</a></li>
|
|
<li><a href="#added-concept-of-a-fader-dsp-per-channel-and-channelgroup">Added concept of a 'fader' DSP per Channel and ChannelGroup</a></li>
|
|
<li><a href="#new-dspconnection-types-supported">New DSPConnection types supported</a></li>
|
|
<li><a href="#new-dsp-parameter-types">New DSP parameter types</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#changes">Changes</a><ul>
|
|
<li><a href="#fmod_hardware-support">FMOD_HARDWARE support</a></li>
|
|
<li><a href="#fmod-ex-had-channels-and-channelgroups-now-it-seems-they-are-merged-into-channelcontrol">FMOD Ex had Channels and ChannelGroups, now it seems they are merged into 'ChannelControl'?</a></li>
|
|
<li><a href="#converting-fmod-reverb-parameters">Converting FMOD Reverb parameters</a></li>
|
|
<li><a href="#system_set3dspeakerposition-renamed">System::set3DSpeakerPosition renamed</a></li>
|
|
<li><a href="#fmod_channel_free-fmod_channel_reuse-removed-default-channelgroup-now-passed-to-playsound-if-needed">FMOD_CHANNEL_FREE / FMOD_CHANNEL_REUSE removed. Default ChannelGroup now passed to playSound if needed</a></li>
|
|
<li><a href="#cdrom-cdda-support-removed">CDROM / CDDA support removed</a></li>
|
|
<li><a href="#system_getspectrum-and-system_getwavedata-removed">System::getSpectrum and System::getWaveData removed</a></li>
|
|
<li><a href="#w-function-wide-char-support-removed">'W' function wide char support removed</a></li>
|
|
<li><a href="#system_setreverbambientproperties-removed">System::setReverbAmbientProperties removed</a></li>
|
|
<li><a href="#system_getdspclock-removed">System::getDSPClock removed</a></li>
|
|
<li><a href="#getmemoryinfo-functions-have-been-removed-from-all-classes">getMemoryInfo functions have been removed from all classes</a></li>
|
|
<li><a href="#sound_setvariations-and-sound_getvariations-have-been-removed">Sound::setVariations and Sound::getVariations have been removed</a></li>
|
|
<li><a href="#sound_setsubsoundsentence-has-been-removed">Sound::setSubSoundSentence has been removed</a></li>
|
|
<li><a href="#setdelay-and-clock-functions-now-use-64bit-long-long-type-rather-than-than-32bit-hi-and-32bit-low-part-parameters">setDelay and clock functions now use 64bit 'long long' type rather than than 32bit hi and 32bit low part parameters.</a></li>
|
|
<li><a href="#channel_setspeakermix-channel_setspeakerlevels-channel_setinputchannelmix-channel_getpan-channel_getspeakermix-and-channel_getspeakerlevels-removed">Channel::setSpeakerMix, Channel::setSpeakerLevels, Channel::setInputChannelMix, Channel::getPan, Channel::getSpeakerMix and Channel::getSpeakerLevels removed</a></li>
|
|
<li><a href="#dspconnection_setlevelsgetlevels-have-been-removed">DSPConnection::setLevels/getLevels have been removed.</a></li>
|
|
<li><a href="#channel_set3dpanlevel-misnomer-renamed">Channel::set3DPanLevel misnomer renamed</a></li>
|
|
<li><a href="#override-functions-removed-from-channelgroup-class">'override' functions removed from ChannelGroup class</a></li>
|
|
<li><a href="#system_adddsp-removed-from-the-system-api">System::addDSP removed from the System API</a></li>
|
|
<li><a href="#dsp_remove-removed-from-the-dsp-api">DSP::remove removed from the DSP API</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<h2 id="transitioning-between-fmod-ex-and-fmod-studio"><a href="#transitioning-between-fmod-ex-and-fmod-studio">Transitioning between FMOD Ex and FMOD Studio</a></h2>
|
|
<p>This section describes the differences between FMOD Ex and <a href="glossary.html#fmod-studio">FMOD Studio</a>.</p>
|
|
<h3 id="studio-api-versus-fmod-designer-api"><a href="#studio-api-versus-fmod-designer-api">Studio API Versus FMOD Designer API</a></h3>
|
|
<p>The Studio API is conceptually similar to the old FMOD Designer API, but most classes have been renamed, and some have been removed or split up.</p>
|
|
<h4 id="eventsystem-and-eventsystem_create"><a href="#eventsystem-and-eventsystem_create">EventSystem and EventSystem_Create</a></h4>
|
|
<p>The <a class="apilink" href="studio-api-system.html">Studio::System</a> class is analogous to the old EventSystem class. The static <a class="apilink" href="studio-api-system.html#studio_system_create">Studio::System::create</a> function is analogous to the old EventSystem_Create function.</p>
|
|
<h4 id="eventproject"><a href="#eventproject">EventProject</a></h4>
|
|
<p>The <a class="apilink" href="studio-api-bank.html">Studio::Bank</a> class is analogous to the old EventProject class.</p>
|
|
<h4 id="fev-and-fsb-files"><a href="#fev-and-fsb-files">FEV and FSB Files</a></h4>
|
|
<p>Each FMOD Designer project produced a single .fev file and multiple .fsb files. In contrast, an FMOD Studio project produces multiple .bank files, which contain event metadata as well as sample data. See the <a class="apilink" href="studio-api-system.html#studio_system_loadbankfile">Studio::System::loadBankFile</a>, <a class="apilink" href="studio-api-bank.html#studio_bank_loadsampledata">Studio::Bank::loadSampleData</a>, and <a class="apilink" href="studio-api-eventdescription.html#studio_eventdescription_loadsampledata">Studio::EventDescription::loadSampleData</a> functions. The core API still supports loading .fsb files directly.</p>
|
|
<h4 id="eventgroup"><a href="#eventgroup">EventGroup</a></h4>
|
|
<p>FMOD Studio doesn't have the concept of EventGroups. Events can be placed in folders, but this has no significance at runtime. To achieve the loading control formerly provided by EventGroups, events can be placed in different banks.</p>
|
|
<h4 id="event"><a href="#event">Event</a></h4>
|
|
<p>The old Event class has been split into two classes: <a class="apilink" href="studio-api-eventdescription.html">Studio::EventDescription</a> and <a class="apilink" href="studio-api-eventinstance.html">Studio::EventInstance</a>. <a class="apilink" href="studio-api-eventdescription.html">Studio::EventDescription</a> holds the static data that describes an event, while <a class="apilink" href="studio-api-eventinstance.html">Studio::EventInstance</a> is a playable instance of an event. These two classes correspond to old Event objects retrieved by calling getEvent with or without the FMOD_EVENT_INFOONLY flag.</p>
|
|
<p>The FMOD Designer API used to create a fixed number of event instances when you first called getEvent without FMOD_EVENT_INFOONLY, whereas the Studio API creates a single instance each time you call <a class="apilink" href="studio-api-eventdescription.html#studio_eventdescription_createinstance">Studio::EventDescription::createInstance</a>. This gives you more control over the memory usage for each event.</p>
|
|
<h4 id="retrieving-events"><a href="#retrieving-events">Retrieving Events</a></h4>
|
|
<p>Events can be retrieved by ID (using <a class="apilink" href="studio-api-system.html#studio_system_geteventbyid">Studio::System::getEventByID</a>) or by path (using <a class="apilink" href="studio-api-system.html#studio_system_getevent">Studio::System::getEvent</a>).</p>
|
|
<p>Event IDs are <a href="glossary.html#guid">GUIDs (globally unique identifiers)</a>, and stay the same even if the event is renamed or moved around in the project. IDs can be parsed from a string using <a class="apilink" href="studio-api-common.html#studio_parseid">Studio::parseID</a>, or looked up from a path using <a class="apilink" href="studio-api-system.html#studio_system_lookupid">Studio::System::lookupID</a> if the "Master Bank.strings.bank" file is loaded.</p>
|
|
<p>Event paths consist of the string "event:/", followed by the the path to the event within the project's folder structure. To retrieve events by path, the "Master Bank.strings.bank" file must be loaded.</p>
|
|
<h4 id="eventparameter"><a href="#eventparameter">EventParameter</a></h4>
|
|
<p>There is no class analogous to the old EventParameter class. Instead use the parameter getting and setting functions in <a class="apilink" href="studio-api-eventinstance.html">Studio::EventInstance</a>: <a class="apilink" href="studio-api-eventinstance.html#studio_eventinstance_getparameterbyid">Studio::EventInstance::getParameterByID</a>, <a class="apilink" href="studio-api-eventinstance.html#studio_eventinstance_getparameterbyname">Studio::EventInstance::getParameterByName</a>, <a class="apilink" href="studio-api-eventinstance.html#studio_eventinstance_setparameterbyid">Studio::EventInstance::setParameterByID</a>, <a class="apilink" href="studio-api-eventinstance.html#studio_eventinstance_setparameterbyname">Studio::EventInstance::setParameterByName</a>, <a class="apilink" href="studio-api-eventinstance.html#studio_eventinstance_setparametersbyids">Studio::EventInstance::setParametersByIDs</a>.</p>
|
|
<h4 id="sustain-points-and-key-off"><a href="#sustain-points-and-key-off">Sustain Points and Key Off</a></h4>
|
|
<p>The old EventParameter class had a keyOff function to move past the next sustain point. In FMOD Studio and the Studio API, this behavior is implemented via a built-in KeyOff that can be triggered via <a class="apilink" href="studio-api-eventinstance.html#studio_eventinstance_keyoff">Studio::EventInstance::keyOff</a>.</p>
|
|
<h4 id="eventcategory"><a href="#eventcategory">EventCategory</a></h4>
|
|
<p>Event categories have been replaced in FMOD Studio by buses and VCAs, which provide much more functionality to the sound designer. In the Studio API, buses and VCAs are accessed via the <a class="apilink" href="studio-api-bus.html">Studio::Bus</a> and <a class="apilink" href="studio-api-vca.html">Studio::VCA</a> classes.</p>
|
|
<h4 id="eventreverb"><a href="#eventreverb">EventReverb</a></h4>
|
|
<p>The EventReverb class has been removed. Similar functionality can be implemented using events with <a href="glossary.html#automatic-parameter">automatic</a> distance parameters controlling reverb snapshots.</p>
|
|
<h4 id="eventqueue-and-eventqueueentry"><a href="#eventqueue-and-eventqueueentry">EventQueue and EventQueueEntry</a></h4>
|
|
<p>FMOD Studio doesn't have the concept of event queues.</p>
|
|
<h4 id="musicsystem-and-musicprompt"><a href="#musicsystem-and-musicprompt">MusicSystem and MusicPrompt</a></h4>
|
|
<p>Interactive music in FMOD Studio is implemented inside the event editor, so the MusicSystem and MusicPrompt classes have been removed.</p>
|
|
<h4 id="neteventsystem"><a href="#neteventsystem">NetEventSystem</a></h4>
|
|
<p>Whereas the old network tweaking API was implemented as a separate fmod_event_net library, the FMOD Studio live update system is built into the main API library, and can be enabled by passing <a class="apilink" href="studio-api-system.html#fmod_studio_init_liveupdate">FMOD_STUDIO_INIT_LIVEUPDATE</a> to <a class="apilink" href="studio-api-system.html#studio_system_initialize">Studio::System::initialize</a>.</p>
|
|
<h2 id="fmod-studios-core-api-versus-fmod-exs-core-api"><a href="#fmod-studios-core-api-versus-fmod-exs-core-api">FMOD Studio's Core API Versus FMOD Ex's Core API</a></h2>
|
|
<h3 id="new-features"><a href="#new-features">New features</a></h3>
|
|
<h4 id="no-more-recommended-startup-sequence"><a href="#no-more-recommended-startup-sequence">No more 'recommended startup sequence'</a></h4>
|
|
<p>The FMOD Engine now handles the speaker mode automatically. Starting the Core API is as simple as calling <a class="apilink" href="core-api-system.html#system_init">System::init</a>, and does not require querying caps or speaker modes to make the FMOD Engine's software mixer match that of the operating system. If you want the software mixer to be forced into a certain speaker mode, disregarding the operating system, use <a class="apilink" href="core-api-system.html#system_setsoftwareformat">System::setSoftwareFormat</a>. The FMOD Engine will automatically downmix or upmix this mode if the user's system is not the same speaker mode as the one selected for the software engine. Where possible, Dolby or internal downmixing will be used to achieve better surround effect.</p>
|
|
<h4 id="added-new-dsp-effects"><a href="#added-new-dsp-effects">Added new DSP effects</a></h4>
|
|
<p>The following new <a href="glossary.html#dsp-effect">DSP effects</a> are added. (From fmod_dsp_effects.h)</p>
|
|
<div class="highlight language-cpp"><pre><span></span><span class="n">FMOD_DSP_TYPE_SEND</span><span class="p">,</span> <span class="cm">/* This unit sends a copy of the signal to a return DSP anywhere in the DSP tree. */</span>
|
|
<span class="n">FMOD_DSP_TYPE_RETURN</span><span class="p">,</span> <span class="cm">/* This unit receives signals from a number of send DSPs. */</span>
|
|
<span class="n">FMOD_DSP_TYPE_HIGHPASS_SIMPLE</span><span class="p">,</span> <span class="cm">/* This unit filters sound using a simple highpass with no resonance, but has flexible cutoff and is fast. Deprecated and will be removed in a future release (see FMOD_DSP_HIGHPASS_SIMPLE remarks for alternatives). */</span>
|
|
<span class="n">FMOD_DSP_TYPE_PAN</span><span class="p">,</span> <span class="cm">/* This unit pans the signal, possibly upmixing or downmixing as well. */</span>
|
|
<span class="n">FMOD_DSP_TYPE_THREE_EQ</span><span class="p">,</span> <span class="cm">/* This unit is a three-band equalizer. */</span>
|
|
<span class="n">FMOD_DSP_TYPE_FFT</span><span class="p">,</span> <span class="cm">/* This unit simply analyzes the signal and provides spectrum information back through getParameter. */</span>
|
|
<span class="n">FMOD_DSP_TYPE_LOUDNESS_METER</span><span class="p">,</span> <span class="cm">/* This unit analyzes the loudness and true peak of the signal. */</span>
|
|
<span class="n">FMOD_DSP_TYPE_CONVOLUTIONREVERB</span><span class="p">,</span> <span class="cm">/* This unit implements convolution reverb. */</span>
|
|
<span class="n">FMOD_DSP_TYPE_CHANNELMIX</span><span class="p">,</span> <span class="cm">/* This unit provides per signal channel gain, and output channel mapping to allow 1 multi-channel signal made up of many groups of signals to map to a single output signal. */</span>
|
|
<span class="n">FMOD_DSP_TYPE_TRANSCEIVER</span><span class="p">,</span> <span class="cm">/* This unit 'sends' and 'receives' from a selection of up to 32 different slots. It is like a send/return but it uses global slots rather than returns as the destination. It also has other features. Multiple transceivers can receive from a single channel, or multiple transceivers can send to a single channel, or a combination of both. */</span>
|
|
<span class="n">FMOD_DSP_TYPE_OBJECTPAN</span><span class="p">,</span> <span class="cm">/* This unit sends the signal to a 3d object encoder like Dolby Atmos. Supports a subset of the FMOD_DSP_TYPE_PAN parameters. */</span>
|
|
<span class="n">FMOD_DSP_TYPE_MULTIBAND_EQ</span><span class="p">,</span> <span class="cm">/* This unit is a flexible five band parametric equalizer. */</span>
|
|
</pre></div>
|
|
|
|
<p>Note FMOD's convolution reverb also has the option to be GPU accelerated for big performance wins.</p>
|
|
<h4 id="new-file-format-support"><a href="#new-file-format-support">New file format support</a></h4>
|
|
<p><a class="apilink" href="core-api-sound.html#fmod_sound_type_fadpcm">FMOD_SOUND_TYPE_FADPCM</a> is a new highly optimized, branchless ADPCM variant which has higher quality than IMA ADPCM, and better performance. Great for mobiles.</p>
|
|
<h4 id="dolby-atmos-support"><a href="#dolby-atmos-support">Dolby Atmos support</a></h4>
|
|
<p>Through the FMOD object panner, sounds can be positioned spherically in 3d space to support Dolby Atmos. This includes height speakers.</p>
|
|
<h4 id="new-dsp-mixing-engine"><a href="#new-dsp-mixing-engine">New DSP mixing engine</a></h4>
|
|
<p>The FMOD Engine's software mixing engine is more flexible than that of FMOD Ex, with support for changing channel formats and speaker modes as the signal flows through the mix. THe FMOD Engine's software mixing engine also has better custom DSP support, with branch idling, silence detection, sends and returns, side-chaining, circular connections and more.</p>
|
|
<h4 id="added-plug-in-info-helper-function"><a href="#added-plug-in-info-helper-function">Added plug-in info helper function</a></h4>
|
|
<p><a class="apilink" href="core-api-system.html#system_getdspinfobyplugin">System::getDSPInfoByPlugin</a> has been added to plug the gap between loading a plug-in, and getting its <a class="apilink" href="plugin-api-dsp.html#fmod_dsp_description">FMOD_DSP_DESCRIPTION</a> structure so that it can be passed to <a class="apilink" href="core-api-system.html#system_createdsp">System::createDSP</a>.</p>
|
|
<h4 id="added-background-suspension-support"><a href="#added-background-suspension-support">Added background suspension support</a></h4>
|
|
<p>For mobile devices, <a class="apilink" href="core-api-system.html#system_mixersuspend">System::mixerSuspend</a> and <a class="apilink" href="core-api-system.html#system_mixerresume">System::mixerResume</a> allows you to halt FMODs cpu mixer and thread before sleeping or answering a call or any other interruption event.</p>
|
|
<h4 id="channelgroups-volume-and-panning-are-now-dsp-based-rather-than-reaching-down-to-the-channels-of-the-child-channelgroups"><a href="#channelgroups-volume-and-panning-are-now-dsp-based-rather-than-reaching-down-to-the-channels-of-the-child-channelgroups">ChannelGroups volume and panning are now DSP based, rather than reaching down to the Channels of the child ChannelGroups.</a></h4>
|
|
<p>ChannelGroups in FMOD Ex were a way to scale and modify the pan and volume of the <a class="apilink" href="core-api-channel.html">Channel</a>s in the <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a>s below. The FMOD Engine now modifies pan and volume on a DSP basis using the <a href="effects-reference.html#fader">fader DSP unit</a>. A fader unit can be repositioned in its own effect list, allowing effects to be either post- or pre-fader effects.</p>
|
|
<h4 id="added-additional-output-streams"><a href="#added-additional-output-streams">Added additional output streams</a></h4>
|
|
<p><a class="apilink" href="core-api-system.html#system_attachchannelgrouptoport">System::attachChannelGroupToPort</a> and <a class="apilink" href="core-api-system.html#system_detachchannelgroupfromport">System::detachChannelGroupFromPort</a> allows signals to be sent to alternate sound outputs like headsets, controllers with speakers, and console based multi speaker arrays that are not the standard surround sound speaker output.</p>
|
|
<h4 id="added-sound-helper-function"><a href="#added-sound-helper-function">Added Sound helper function</a></h4>
|
|
<p>Added the ability for a child sound (subsound) to query for its parent via <a class="apilink" href="core-api-sound.html#sound_getsubsoundparent">Sound::getSubSoundParent</a>.</p>
|
|
<h4 id="added-sample-volume-control"><a href="#added-sample-volume-control">Added sample volume control</a></h4>
|
|
<p><a class="apilink" href="core-api-channelcontrol.html#channelcontrol_addfadepoint">ChannelControl::addFadePoint</a>, <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_removefadepoints">ChannelControl::removeFadePoints</a> and <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_getfadepoints">ChannelControl::getFadePoints</a> give the ability to set up a volume fade or ramp between any 2 clock points is possible. Link up multiple fade points to create envelopes. All fading is clock accurate and compensated for when pitch is changed. <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_setvolumeramp">ChannelControl::setVolumeRamp</a> / <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_getvolumeramp">ChannelControl::getVolumeRamp</a> can be used when queuing sounds up and for other reasons, it can be desirable to turn off ramping of volume changes, so the ability has been added to turn volume ramping (declicking) off or on per <a class="apilink" href="core-api-channel.html">Channel</a>/<a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a>.</p>
|
|
<h4 id="added-utf8-support"><a href="#added-utf8-support">Added UTF8 support</a></h4>
|
|
<p>Functions such as System::getDriverInfoW have been removed in favour of UTF8 support.</p>
|
|
<h4 id="added-concept-of-a-fader-dsp-per-channel-and-channelgroup"><a href="#added-concept-of-a-fader-dsp-per-channel-and-channelgroup">Added concept of a 'fader' DSP per Channel and ChannelGroup</a></h4>
|
|
<p>Each <a class="apilink" href="core-api-channel.html">Channel</a> and <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a> has a built in 'fader' (<a class="apilink" href="core-api-common-dsp-effects.html#fmod_dsp_type_fader">FMOD_DSP_TYPE_FADER</a>). This also acts as the DSP 'head' of the <a class="apilink" href="core-api-channel.html">Channel</a> or <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a> by default.<br />
|
|
This can of course be changed later. If you add an effect, you can position it to be the head, and the fader will be before that in the signal chain.<br />
|
|
A fader DSP simply adjusts volume of the signal for a mix, and also supports sample accurate volume fade points, for envelopes and fade ins / fade outs.<br />
|
|
A panner is a separate entity which can pan a sound in mono, stereo and surround using a variety of parameters including position/direction/extent/rotation/axis control and 3d position control.<br />
|
|
The order of processing of a fader and panner can be controlled using <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_setdspindex">ChannelControl::setDSPIndex</a>, and it can be positioned into an effect chain so that panning comes before an effect or after, with fading coming at a different position in the effect chain.</p>
|
|
<h4 id="new-dspconnection-types-supported"><a href="#new-dspconnection-types-supported">New DSPConnection types supported</a></h4>
|
|
<p><a class="apilink" href="core-api-dsp.html#dsp_addinput">DSP::addInput</a> now has a new optional parameter to describe the connection's behavior between 2 DSP units. <a class="apilink" href="core-api-dspconnection.html#fmod_dspconnection_type">FMOD_DSPCONNECTION_TYPE</a> has been added to tell an input DSP that it should mix to a 'sidechain' buffer, which is a special buffer for DSP units that want to process a sidechain (for example a compressor) through a DSP unit's <a class="apilink" href="plugin-api-dsp.html#fmod_dsp_state">FMOD_DSP_STATE</a> structure. This signal is not audible but is used to affect behavior within the DSP. <a class="apilink" href="core-api-dspconnection.html#fmod_dspconnection_type_sidechain">FMOD_DSPCONNECTION_TYPE_SIDECHAIN</a> would be used here.<br />
|
|
It should only consume existing data, not execute the input to generate that data. <a class="apilink" href="core-api-dspconnection.html#fmod_dspconnection_type_send">FMOD_DSPCONNECTION_TYPE_SEND</a> would be used here. This can be useful for graph dependency reasons, so that an input is not executed before it should be.</p>
|
|
<h4 id="new-dsp-parameter-types"><a href="#new-dsp-parameter-types">New DSP parameter types</a></h4>
|
|
<p>In FMOD Ex, only float parameters were supported. Now Int, Bool and Data parameters are supported. <br />
|
|
Use:</p>
|
|
<ul>
|
|
<li><a class="apilink" href="core-api-dsp.html#dsp_setparameterfloat">DSP::setParameterFloat</a>, <a class="apilink" href="core-api-dsp.html#dsp_getparameterfloat">DSP::getParameterFloat</a></li>
|
|
<li><a class="apilink" href="core-api-dsp.html#dsp_setparameterint">DSP::setParameterInt</a>, <a class="apilink" href="core-api-dsp.html#dsp_getparameterint">DSP::getParameterInt</a></li>
|
|
<li><a class="apilink" href="core-api-dsp.html#dsp_setparameterbool">DSP::setParameterBool</a>, <a class="apilink" href="core-api-dsp.html#dsp_getparameterbool">DSP::getParameterBool</a></li>
|
|
<li><a class="apilink" href="core-api-dsp.html#dsp_setparameterdata">DSP::setParameterData</a>, <a class="apilink" href="core-api-dsp.html#dsp_getparameterdata">DSP::getParameterData</a></li>
|
|
</ul>
|
|
<h3 id="changes"><a href="#changes">Changes</a></h3>
|
|
<h4 id="fmod_hardware-support"><a href="#fmod_hardware-support">FMOD_HARDWARE support</a></h4>
|
|
<p>The FMOD Engine's software mixing is sufficiently advanced that it can do things that would be impossible with the limited features of hardware voices. Today, when multicore processors are common even on mobile platforms, hardware voice support provides no real advantage; not when the FMOD Engine can be faster, better quality, and more flexible. As such, all sounds and voices handled by the FMOD Engine are software mixed.</p>
|
|
<p>API changes:</p>
|
|
<ul>
|
|
<li>System::setHardwareChannels is removed</li>
|
|
<li>System::getDriverCaps is removed. systemrate, speakermode, speakermodechannels parameters have been added to <a class="apilink" href="core-api-system.html#system_getdriverinfo">System::getDriverInfo</a> to provide the information which may be important to the developer. Similarly, System::getRecordDriverCaps has been removed, in favour of <a class="apilink" href="core-api-system.html#system_getrecorddriverinfo">System::getRecordDriverInfo</a>.</li>
|
|
<li>System::setSpeakerMode and System::getSpeakerMode are removed, and instead are now moved into <a class="apilink" href="core-api-system.html#system_setsoftwareformat">System::setSoftwareFormat</a> because 'speakermode' now only affects the internal mixer, and the operating system speaker mode is matched at runtime through matrix upmixing or downmixing (automatically).</li>
|
|
</ul>
|
|
<h4 id="fmod-ex-had-channels-and-channelgroups-now-it-seems-they-are-merged-into-channelcontrol"><a href="#fmod-ex-had-channels-and-channelgroups-now-it-seems-they-are-merged-into-channelcontrol">FMOD Ex had Channels and ChannelGroups, now it seems they are merged into 'ChannelControl'?</a></h4>
|
|
<p><a class="apilink" href="core-api-channel.html">Channel</a>s and <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a>s had some similar functionality in FMOD Ex (ie setVolume, setPaused), but the FMOD Engine takes it even further. The FMOD Engine is designed so that <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a>s can have a lot more control, including allowing pausing and muting at the DSP node level, adding effects, and positioning in 3D.</p>
|
|
<h4 id="converting-fmod-reverb-parameters"><a href="#converting-fmod-reverb-parameters">Converting FMOD Reverb parameters</a></h4>
|
|
<p>The FMOD Engine handles reverb parameters differently to FMOD Ex. Use this table to convert from FMOD Ex parameters to FMOD Engine parameters.</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>FMOD Engine property</th>
|
|
<th align="center">Range</th>
|
|
<th>FMOD Ex property / conversion formula to create FMOD Engine value</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>DecayTime (ms)</td>
|
|
<td align="center">100 to 20000</td>
|
|
<td>DecayTime * 1000</td>
|
|
</tr>
|
|
<tr>
|
|
<td>EarlyDelay (ms)</td>
|
|
<td align="center">0 to 300</td>
|
|
<td>ReflectionsDelay * 1000</td>
|
|
</tr>
|
|
<tr>
|
|
<td>LateDelay (ms)</td>
|
|
<td align="center">0 to 100</td>
|
|
<td>ReverbDelay * 1000</td>
|
|
</tr>
|
|
<tr>
|
|
<td>HFReference (Hz)</td>
|
|
<td align="center">20 to 20000</td>
|
|
<td>HFReference</td>
|
|
</tr>
|
|
<tr>
|
|
<td>HFDecayRatio (%)</td>
|
|
<td align="center">0 to 100</td>
|
|
<td>DecayHFRatio * 100</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Diffusion (%)</td>
|
|
<td align="center">0 to 100</td>
|
|
<td>Diffusion</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Density (%)</td>
|
|
<td align="center">0 to 100</td>
|
|
<td>Density</td>
|
|
</tr>
|
|
<tr>
|
|
<td>LowShelfFrequency (Hz)</td>
|
|
<td align="center">20 to 1000</td>
|
|
<td>LFReference</td>
|
|
</tr>
|
|
<tr>
|
|
<td>LowShelfGain (dB)</td>
|
|
<td align="center">-48 to 12</td>
|
|
<td>RoomLF / 100</td>
|
|
</tr>
|
|
<tr>
|
|
<td>HighCut (Hz)</td>
|
|
<td align="center">20 to 20000</td>
|
|
<td>IF RoomHF < 0 THEN HFReference / sqrt((1-HFGain) / HFGain) ELSE 20000</td>
|
|
</tr>
|
|
<tr>
|
|
<td>EarlyLateMix (%)</td>
|
|
<td align="center">0 to 100</td>
|
|
<td>IF Reflections > -10000 THEN LateEarlyRatio/(LateEarlyRatio + 1) * 100 ELSE 100</td>
|
|
</tr>
|
|
<tr>
|
|
<td>WetLevel (dB)</td>
|
|
<td align="center">-80 to 20</td>
|
|
<td>10 * log10(EarlyAndLatePower) + Room / 100</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p>Note: Clamp all values to maximum (after conversion) as some conversions may exceed the new parameter range.</p>
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Intermediate variables used in conversion</th>
|
|
<th>Formulas</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>LateEarlyRatio</td>
|
|
<td>pow(10, (Reverb - Reflections) / 2000)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>EarlyAndLatePower</td>
|
|
<td>pow(10, Reflections / 1000) + pow(10, Reverb / 1000)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>HFGain</td>
|
|
<td>pow(10, RoomHF / 2000)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h4 id="system_set3dspeakerposition-renamed"><a href="#system_set3dspeakerposition-renamed">System::set3DSpeakerPosition renamed</a></h4>
|
|
<p><a class="apilink" href="core-api-system.html#system_setspeakerposition">System::setSpeakerPosition</a> is a minor name change to denote that 3d and 2d positioning is affected by speaker location.</p>
|
|
<h4 id="fmod_channel_free-fmod_channel_reuse-removed-default-channelgroup-now-passed-to-playsound-if-needed"><a href="#fmod_channel_free-fmod_channel_reuse-removed-default-channelgroup-now-passed-to-playsound-if-needed">FMOD_CHANNEL_FREE / FMOD_CHANNEL_REUSE removed. Default ChannelGroup now passed to playSound if needed</a></h4>
|
|
<p><a class="apilink" href="core-api-system.html#system_playsound">System::playSound</a> and <a class="apilink" href="core-api-system.html#system_playdsp">System::playDSP</a> now do not take a 'channel' parameter. All channels behave the same way as FMOD_CHANNEL_FREE would have in FMOD Ex.<br />
|
|
Seeing as a parameter was removed from playSound/playDSP, a new one was added to remove the overhead of disconnecting and reconnecting DSP graph nodes after playSound was called, so that they could be hooked up to a new ChannelGroup other than the master ChannelGroup. Consider this addition a performance optimization, and a simplification in API calls.</p>
|
|
<h4 id="cdrom-cdda-support-removed"><a href="#cdrom-cdda-support-removed">CDROM / CDDA support removed</a></h4>
|
|
<p>Legacy support for CDROM redbook audio playback has been removed due to lack of interest and issues with maintaining said code.</p>
|
|
<h4 id="system_getspectrum-and-system_getwavedata-removed"><a href="#system_getspectrum-and-system_getwavedata-removed">System::getSpectrum and System::getWaveData removed</a></h4>
|
|
<p>Add a custom DSP unit to capture DSP wavedata from the output stage. Use the master <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a>'s DSP head with <a class="apilink" href="core-api-system.html#system_getmasterchannelgroup">System::getMasterChannelGroup</a> and <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_getdsp">ChannelControl::getDSP</a>.<br />
|
|
Add a built in <a href="effects-reference.html#fft">FFT DSP unit</a> type to capture spectrum data from the output stage. Create a built in FFT unit with <a class="apilink" href="core-api-system.html#system_createdspbytype">System::createDSPByType</a> and <a class="apilink" href="core-api-common-dsp-effects.html#fmod_dsp_type_fft">FMOD_DSP_TYPE_FFT</a>, then add the effect to the master <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a> with <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_adddsp">ChannelControl::addDSP</a>. Use <a class="apilink" href="core-api-dsp.html#dsp_getparameterdata">DSP::getParameterData</a> to get the raw spectrum data or use <a class="apilink" href="core-api-dsp.html#dsp_getparameterfloat">DSP::getParameterFloat</a> to get the dominant frequency from the signal.</p>
|
|
<h4 id="w-function-wide-char-support-removed"><a href="#w-function-wide-char-support-removed">'W' function wide char support removed</a></h4>
|
|
<p>Functions such as System::getDriverInfoW have been removed in favour of UTF8 support.</p>
|
|
<h4 id="system_setreverbambientproperties-removed"><a href="#system_setreverbambientproperties-removed">System::setReverbAmbientProperties removed</a></h4>
|
|
<p>The 'background' ambient reverb for a 3d reverb system is now just the standard reverb set with <a class="apilink" href="core-api-system.html#system_setreverbproperties">System::setReverbProperties</a>.</p>
|
|
<h4 id="system_getdspclock-removed"><a href="#system_getdspclock-removed">System::getDSPClock removed</a></h4>
|
|
<p>Use the <a href="glossary.html#dsp-clock">DSP clock</a> of the master <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a> instead with <a class="apilink" href="core-api-system.html#system_getmasterchannelgroup">System::getMasterChannelGroup</a> and <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_getdspclock">ChannelControl::getDSPClock</a>.</p>
|
|
<h4 id="getmemoryinfo-functions-have-been-removed-from-all-classes"><a href="#getmemoryinfo-functions-have-been-removed-from-all-classes">getMemoryInfo functions have been removed from all classes</a></h4>
|
|
<p>Due to the unreliability of the function in FMOD Ex due to caching, threads, and shared memory throwing results out, the function has been removed. Alternate memory tracking methods will be added later. FMOD::Memory_GetStats and logging is the best way to track memory at the moment.</p>
|
|
<h4 id="sound_setvariations-and-sound_getvariations-have-been-removed"><a href="#sound_setvariations-and-sound_getvariations-have-been-removed">Sound::setVariations and Sound::getVariations have been removed</a></h4>
|
|
<p>Due to this being a 'helper' function that can easily be achieved in user code, this was deemed not necessary and removed.</p>
|
|
<h4 id="sound_setsubsoundsentence-has-been-removed"><a href="#sound_setsubsoundsentence-has-been-removed">Sound::setSubSoundSentence has been removed</a></h4>
|
|
<p>This function has been removed in favour of the extremely precise and more reliable <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_setdelay">ChannelControl::setDelay</a> functionality. 2 or more sounds can be queued up to play end to end using this function, with the added benefit of cross fades and overlaps.</p>
|
|
<h4 id="setdelay-and-clock-functions-now-use-64bit-long-long-type-rather-than-than-32bit-hi-and-32bit-low-part-parameters"><a href="#setdelay-and-clock-functions-now-use-64bit-long-long-type-rather-than-than-32bit-hi-and-32bit-low-part-parameters">setDelay and clock functions now use 64bit 'long long' type rather than than 32bit hi and 32bit low part parameters.</a></h4>
|
|
<p>Due to the complexity of working in fixed point, and seeing as there is a consistent 64bit type for all compilers in long long that FMOD supports, we have switched to this type.<br />
|
|
1 32bit value would wrap around in 24 hours at 48khz, so 64bit values will last for 12 million years which should be enough to avoid in game clock wrap around.</p>
|
|
<h4 id="channel_setspeakermix-channel_setspeakerlevels-channel_setinputchannelmix-channel_getpan-channel_getspeakermix-and-channel_getspeakerlevels-removed"><a href="#channel_setspeakermix-channel_setspeakerlevels-channel_setinputchannelmix-channel_getpan-channel_getspeakermix-and-channel_getspeakerlevels-removed">Channel::setSpeakerMix, Channel::setSpeakerLevels, Channel::setInputChannelMix, Channel::getPan, Channel::getSpeakerMix and Channel::getSpeakerLevels removed</a></h4>
|
|
<p>A cleaner replacement has been made for these functions,</p>
|
|
<ul>
|
|
<li><a class="apilink" href="core-api-channelcontrol.html#channelcontrol_setmixlevelsoutput">ChannelControl::setMixLevelsOutput</a> (float frontleft, float frontright, float center, float lfe, float surroundleft, float surroundright, float backleft, float backright);</li>
|
|
<li><a class="apilink" href="core-api-channelcontrol.html#channelcontrol_setmixlevelsinput">ChannelControl::setMixLevelsInput</a> (float *levels, int numlevels);</li>
|
|
<li><a class="apilink" href="core-api-channelcontrol.html#channelcontrol_setmixmatrix">ChannelControl::setMixMatrix</a> (float *matrix, int outchannels, int inchannels, int inchannel_hop = 0);</li>
|
|
<li><a class="apilink" href="core-api-channelcontrol.html#channelcontrol_getmixmatrix">ChannelControl::getMixMatrix</a> (float <em>matrix, int </em>outchannels, int *inchannels, int inchannel_hop = 0);</li>
|
|
</ul>
|
|
<p>Note that because setPan, setMixLevelsOutput and setMixLevelsInput all affect a final pan matrix, only getMixMatrix is available as the 'getter'. There is no more exclusive mode for the panning technique like there was in FMOD Ex. All 3 functions can now affect the final matrix. The setMixMatrix function now allows instant setting of a full matrix for performance reasons, rather than calling setSpeakerLevels each time for each speaker.</p>
|
|
<h4 id="dspconnection_setlevelsgetlevels-have-been-removed"><a href="#dspconnection_setlevelsgetlevels-have-been-removed">DSPConnection::setLevels/getLevels have been removed.</a></h4>
|
|
<p>As above, new functionality is available to produce the same result. Rather than setting output levels row by row, a full 2 dimensional matrix is supplied with <a class="apilink" href="core-api-dspconnection.html#dspconnection_setmixmatrix">DSPConnection::setMixMatrix</a>.</p>
|
|
<h4 id="channel_set3dpanlevel-misnomer-renamed"><a href="#channel_set3dpanlevel-misnomer-renamed">Channel::set3DPanLevel misnomer renamed</a></h4>
|
|
<p>The FMOD Ex function did not actually only affect pan, it also affected doppler and distance attenuation so to call it 'pan' level was not really correct. THe FMOD Engine corrects this with <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_set3dlevel">ChannelControl::set3DLevel</a>.</p>
|
|
<h4 id="override-functions-removed-from-channelgroup-class"><a href="#override-functions-removed-from-channelgroup-class">'override' functions removed from ChannelGroup class</a></h4>
|
|
<p>Because volume/pitch/muting/reverb properties and pausing has been added as a <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a> concept at the DSP level, <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a>s no longer rely on their 'channels' to do pausing and muting type logic. The <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a>'s DSP itself will directly mute/pause etc, thanks to the removal of FMOD_HARDWARE support.</p>
|
|
<h4 id="system_adddsp-removed-from-the-system-api"><a href="#system_adddsp-removed-from-the-system-api">System::addDSP removed from the System API</a></h4>
|
|
<p>Rather than using the 'system' to add a DSP to, the user must use <a class="apilink" href="core-api-system.html#system_getmasterchannelgroup">System::getMasterChannelGroup</a> which gets the top level <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a>, then use <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_adddsp">ChannelControl::addDSP</a> to add the DSP to it, which effectively puts at the end of the signal chain.</p>
|
|
<h4 id="dsp_remove-removed-from-the-dsp-api"><a href="#dsp_remove-removed-from-the-dsp-api">DSP::remove removed from the DSP API</a></h4>
|
|
<p>Effects that are added with <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_adddsp">ChannelControl::addDSP</a> are owned by the ChannelControl that added it, and therefore must be removed with <a class="apilink" href="core-api-channelcontrol.html#channelcontrol_removedsp">ChannelControl::removeDSP</a>, instead of having the DSP removing itself. This helps the <a class="apilink" href="core-api-channelgroup.html">ChannelGroup</a> or <a class="apilink" href="core-api-channel.html">Channel</a> manage resources.</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>
|