English中文
Studio API Reference | Studio::System

FMOD API User Manual 2.00

6. Studio API Reference | Studio::System

The main system object for FMOD Studio.

Initializing the FMOD Studio System object will also initialize the core System object.

Lifetime:

Update:

Banks:

Listeners:

Buses:

Events:

Parameters:

VCAs:

Advanced settings:

Command capture and replay:

Profiling:

Plugins:

System callback:

Sound table:

General:

FMOD_STUDIO_ADVANCEDSETTINGS

Settings for advanced features like configuring memory and cpu usage.

C
C++
C#
JS

typedef struct FMOD_STUDIO_ADVANCEDSETTINGS {
  int            cbsize;
  unsigned int   commandqueuesize;
  unsigned int   handleinitialsize;
  int            studioupdateperiod;
  int            idlesampledatapoolsize;
  unsigned int   streamingscheduledelay;
  const char*    encryptionkey;
} FMOD_STUDIO_ADVANCEDSETTINGS;
cbsize
Size of this structure in bytes. Must be set to sizeof(FMOD_STUDIO_ADVANCEDSETTINGS) before calling Studio::System::setAdvancedSettings or Studio::System::getAdvancedSettings.
commandqueuesize

Command queue size for studio async processing.

  • Units: Bytes
  • Default: 32768
handleinitialsize

Initial size to allocate for handles. Memory for handles will grow as needed in pages.

  • Units: Bytes
  • Default: 8192 * sizeof(void*)
studioupdateperiod

Update period of Studio when in async mode, in milliseconds. Will be quantized to the nearest multiple of mixer duration.

  • Units: Milliseconds
  • Default: 20
idlesampledatapoolsize

Size in bytes of sample data to retain in memory when no longer used, to avoid repeated disk I/O. Use -1 to disable.

  • Units: Bytes
  • Default: 262144
streamingscheduledelay

Specify the schedule delay for streams, in samples. Lower values can reduce latency when scheduling events containing streams but may cause scheduling issues if too small.

  • Units: Samples
  • Default: 8192
encryptionkey
Specify the key for loading sounds from encrypted banks. (UTF-8 string)

When calling Studio::System::setAdvancedSettings any member other than cbsize may be set to zero to use the default value for that setting.

FMOD_STUDIO_BANK_INFO

Information for loading a bank using user callbacks.

C
C++
C#
JS

typedef struct FMOD_STUDIO_BANK_INFO {
  int                        size;
  void                      *userdata;
  int                        userdatalength;
  FMOD_FILE_OPEN_CALLBACK    opencallback;
  FMOD_FILE_CLOSE_CALLBACK   closecallback;
  FMOD_FILE_READ_CALLBACK    readcallback;
  FMOD_FILE_SEEK_CALLBACK    seekcallback;
} FMOD_STUDIO_BANK_INFO;
size
Size of this structure in bytes. Must be set to sizeof(FMOD_STUDIO_BANK_INFO).
userdata Opt
User data to be passed to the file callbacks.
userdatalength
Length of user data in bytes. If non-zero the userdata will be copied internally.
opencallback
Callback for opening the bank file. (FMOD_FILE_OPEN_CALLBACK)
closecallback
Callback for closing the bank file. (FMOD_FILE_CLOSE_CALLBACK)
readcallback
Callback for reading from the bank file. (FMOD_FILE_READ_CALLBACK)
seekcallback
Callback for seeking within the bank file. (FMOD_FILE_SEEK_CALLBACK)

See Also: Studio::System::loadBankCustom

FMOD_STUDIO_BUFFER_INFO

Information for a single buffer in FMOD Studio.

C
C++
C#
JS

typedef struct FMOD_STUDIO_BUFFER_INFO {
  int     currentusage;
  int     peakusage;
  int     capacity;
  int     stallcount;
  float   stalltime;
} FMOD_STUDIO_BUFFER_INFO;
currentusage
Current buffer usage in bytes.
peakusage
Peak buffer usage in bytes.
capacity
Buffer capacity in bytes.
stallcount
Cumulative number of stalls due to buffer overflow.
stalltime
Cumulative amount of time stalled due to buffer overflow, in seconds.

See Also: FMOD_STUDIO_BUFFER_USAGE

FMOD_STUDIO_BUFFER_USAGE

Information for FMOD Studio buffer usage.

C
C++
C#
JS

typedef struct FMOD_STUDIO_BUFFER_USAGE {
  FMOD_STUDIO_BUFFER_INFO   studiocommandqueue;
  FMOD_STUDIO_BUFFER_INFO   studiohandle;
} FMOD_STUDIO_BUFFER_USAGE;
studiocommandqueue
Information for the Studio Async Command buffer. (FMOD_STUDIO_BUFFER_INFO)
studiohandle
Information for the Studio handle table. (FMOD_STUDIO_BUFFER_INFO)

See Also: Studio::System::getBufferUsage

FMOD_STUDIO_COMMANDCAPTURE_FLAGS

Flags controling command capture.

C
C++
C#
JS

#define FMOD_STUDIO_COMMANDCAPTURE_NORMAL             0x00000000
#define FMOD_STUDIO_COMMANDCAPTURE_FILEFLUSH          0x00000001
#define FMOD_STUDIO_COMMANDCAPTURE_SKIP_INITIAL_STATE 0x00000002
FMOD_STUDIO_COMMANDCAPTURE_NORMAL
Use default options.
FMOD_STUDIO_COMMANDCAPTURE_FILEFLUSH
Call file flush on every command.
FMOD_STUDIO_COMMANDCAPTURE_SKIP_INITIAL_STATE
Normally the initial state of banks and instances is captured, unless this flag is set.

See Also: Studio::System::startCommandCapture

FMOD_STUDIO_COMMANDREPLAY_FLAGS

Flags controlling command replay.

C
C++
C#
JS

#define FMOD_STUDIO_COMMANDREPLAY_NORMAL         0x00000000
#define FMOD_STUDIO_COMMANDREPLAY_SKIP_CLEANUP   0x00000001
#define FMOD_STUDIO_COMMANDREPLAY_FAST_FORWARD   0x00000002
#define FMOD_STUDIO_COMMANDREPLAY_SKIP_BANK_LOAD 0x00000004
FMOD_STUDIO_COMMANDREPLAY_NORMAL
Use default options.
FMOD_STUDIO_COMMANDREPLAY_SKIP_CLEANUP
Do not free resources at the end of playback.
FMOD_STUDIO_COMMANDREPLAY_FAST_FORWARD
Play back at maximum speed, ignoring the timing of the original replay.
FMOD_STUDIO_COMMANDREPLAY_SKIP_BANK_LOAD
Skip commands related to bank loading.

See Also: Studio::System::loadCommandReplay

FMOD_STUDIO_CPU_USAGE

Performance information for FMOD Studio and core systems.

C
C++
C#
JS

typedef struct FMOD_STUDIO_CPU_USAGE {
  float   dspusage;
  float   streamusage;
  float   geometryusage;
  float   updateusage;
  float   studiousage;
} FMOD_STUDIO_CPU_USAGE;
dspusage
Returns the % CPU time taken by DSP processing on the core mixer thread.
streamusage
Returns the % CPU time taken by stream processing on the core stream thread.
geometryusage
Returns the % CPU time taken by geometry processing on the core geometry thread.
updateusage
Returns the % CPU time taken by core update, called as part of the studio update.
studiousage
Returns the % CPU time taken by studio update, called from the studio thread. Does not include core update time.

See Also: Studio::System::getCPUUsage

FMOD_STUDIO_INITFLAGS

Studio System initialization flags.

C
C++
C#
JS

#define FMOD_STUDIO_INIT_NORMAL                0x00000000
#define FMOD_STUDIO_INIT_LIVEUPDATE            0x00000001
#define FMOD_STUDIO_INIT_ALLOW_MISSING_PLUGINS 0x00000002
#define FMOD_STUDIO_INIT_SYNCHRONOUS_UPDATE    0x00000004
#define FMOD_STUDIO_INIT_DEFERRED_CALLBACKS    0x00000008
#define FMOD_STUDIO_INIT_LOAD_FROM_UPDATE      0x00000010
#define FMOD_STUDIO_INIT_MEMORY_TRACKING       0x00000020
FMOD_STUDIO_INIT_NORMAL
Use defaults for all initialization options.
FMOD_STUDIO_INIT_LIVEUPDATE
Enable live update.
FMOD_STUDIO_INIT_ALLOW_MISSING_PLUGINS
Load banks even if they reference plugins that have not been loaded.
FMOD_STUDIO_INIT_SYNCHRONOUS_UPDATE
Disable asynchronous processing and perform all processing on the calling thread instead.
FMOD_STUDIO_INIT_DEFERRED_CALLBACKS
Defer timeline callbacks until the main update. See Studio::EventInstance::setCallback for more information.
FMOD_STUDIO_INIT_LOAD_FROM_UPDATE
No additional threads are created for bank and resource loading. Loading is driven from Studio::System::update.
FMOD_STUDIO_INIT_MEMORY_TRACKING
Enables detailed memory usage statistics. Increases memory footprint and impacts performance. See Studio::Bus::getMemoryUsage and Studio::EventInstance::getMemoryUsage for more information. Implies FMOD_INIT_MEMORY_TRACKING.

See Also: Studio::System::initialize

FMOD_STUDIO_LOAD_BANK_FLAGS

Flags to controlling bank loading.

C
C++
C#
JS

#define FMOD_STUDIO_LOAD_BANK_NORMAL             0x00000000
#define FMOD_STUDIO_LOAD_BANK_NONBLOCKING        0x00000001
#define FMOD_STUDIO_LOAD_BANK_DECOMPRESS_SAMPLES 0x00000002
#define FMOD_STUDIO_LOAD_BANK_UNENCRYPTED        0x00000004
FMOD_STUDIO_LOAD_BANK_NORMAL
Standard behavior.
FMOD_STUDIO_LOAD_BANK_NONBLOCKING
Bank loading occurs asynchronously rather than occurring immediately.
FMOD_STUDIO_LOAD_BANK_DECOMPRESS_SAMPLES
Force samples to decompress into memory when they are loaded, rather than staying compressed.
FMOD_STUDIO_LOAD_BANK_UNENCRYPTED
Ignore the encryption key specified by Studio::System::setAdvancedSettings when loading sounds from this bank (assume the sounds in the bank are not encrypted).

See Also: Studio::System::loadBankFile, Studio::System::loadBankMemory, Studio::System::loadBankCustom

FMOD_STUDIO_LOAD_MEMORY_ALIGNMENT

Required memory alignment of banks in user memory.

C
C++
C#
JS

#define FMOD_STUDIO_LOAD_MEMORY_ALIGNMENT   32

See Also: Studio::System::loadBankMemory

FMOD_STUDIO_LOAD_MEMORY_MODE

Specifies how to use the memory buffer passed to Studio::System::loadBankMemory.

C
C++
C#
JS

typedef enum FMOD_STUDIO_LOAD_MEMORY_MODE {
  FMOD_STUDIO_LOAD_MEMORY,
  FMOD_STUDIO_LOAD_MEMORY_POINT
} FMOD_STUDIO_LOAD_MEMORY_MODE;
FMOD_STUDIO_LOAD_MEMORY
Memory buffer is copied internally.
FMOD_STUDIO_LOAD_MEMORY_POINT
Memory buffer is used directly in user memory.

See Also: Studio::System::loadBankMemory

FMOD_STUDIO_SOUND_INFO

Describes a sound in the audio table.

C
C++
C#
JS

typedef struct FMOD_STUDIO_SOUND_INFO {
  const char              *name_or_data;
  FMOD_MODE                mode;
  FMOD_CREATESOUNDEXINFO   exinfo;
  int                      subsoundindex;
} FMOD_STUDIO_SOUND_INFO;
name_or_data
The filename (UTF-8 string) or memory buffer that contains the sound.
mode
Mode flags required for loading the sound. (FMOD_MODE)
exinfo
Extra information required for loading the sound. (FMOD_CREATESOUNDEXINFO)
subsoundindex
Subsound index for loading the sound.

See Also: Studio::System::getSoundInfo

FMOD_STUDIO_SYSTEM_CALLBACK

Callback for Studio system events.

C
C++
C#
JS

FMOD_RESULT F_CALLBACK FMOD_STUDIO_SYSTEM_CALLBACK(
  FMOD_STUDIO_SYSTEM *system,
  FMOD_STUDIO_SYSTEM_CALLBACK_TYPE type,
  void *commanddata,
  void *userdata
);
system
Studio system. (Studio::System)
type
Callback type. (FMOD_STUDIO_SYSTEM_CALLBACK_TYPE)
commanddata
Data specific to callback type.
userdata
User data set with Studio::System::setUserData.

system can be cast to Studio::System *.

See Also: Callback Behavior

FMOD_STUDIO_SYSTEM_CALLBACK_TYPE

Callback types for the Studio System callback.

C
C++
C#
JS

#define FMOD_STUDIO_SYSTEM_CALLBACK_PREUPDATE   0x00000001
#define FMOD_STUDIO_SYSTEM_CALLBACK_POSTUPDATE  0x00000002
#define FMOD_STUDIO_SYSTEM_CALLBACK_BANK_UNLOAD 0x00000004
#define FMOD_STUDIO_SYSTEM_CALLBACK_ALL         0xFFFFFFFF
FMOD_STUDIO_SYSTEM_CALLBACK_PREUPDATE
Called at the start of the main Studio update. For async mode this will be on its own thread.
FMOD_STUDIO_SYSTEM_CALLBACK_POSTUPDATE
Called at the end of the main Studio update. For async mode this will be on its own thread.
FMOD_STUDIO_SYSTEM_CALLBACK_BANK_UNLOAD
Called when bank has just been unloaded, after all resources are freed. The commanddata argument will be the bank handle.
FMOD_STUDIO_SYSTEM_CALLBACK_ALL
Pass this mask to Studio::System::setCallback to receive all callback types.

See Also: Callback Behavior, FMOD_STUDIO_SYSTEM_CALLBACK, Studio::System::setCallback

Studio::System::create

FMOD Studio System creation function.

C
C++
C#
JS

static FMOD_RESULT Studio::System::create(
  Studio::System **system,
  unsigned int headerversion = FMOD_VERSION
);
system Out
Studio System object. (Studio::System)
headerversion
Expected FMOD Studio API version.

Pass FMOD_VERSION in headerversion to ensure the library and header versions being used match.

Call Studio::System::release to free the Studio System.

Studio::System::create and Studio::System::release are not thread-safe. Calling either of these functions concurrently with any FMOD Studio API function (including these two functions) may cause undefined behavior. External synchronization must be used if calls to Studio::System::create or Studio::System::release could overlap other FMOD Studio API calls. All other FMOD Studio API functions are thread safe and may be called freely from any thread unless otherwise documented.

See Also: Creating the Studio System

Studio::System::flushCommands

Block until all pending commands have been executed.

C
C++
C#
JS

FMOD_RESULT Studio::System::flushCommands();

This function blocks the calling thread until all pending commands have been executed and all non-blocking bank loads have been completed.

This is equivalent to calling Studio::System::update and then sleeping until the asynchronous thread has finished executing all pending commands.

See Also: Studio::System::initialize, Studio::System::update, Studio::System::flushSampleLoading

Studio::System::flushSampleLoading

Block until all sample loading and unloading has completed.

C
C++
C#
JS

FMOD_RESULT Studio::System::flushSampleLoading();

This function may stall for a long time if other threads are continuing to issue calls to load and unload sample data, e.g. by creating new event instances.

See Also: Studio::System::flushCommands, Sample Data Loading

Studio::System::getAdvancedSettings

Retrieves advanced settings.

C
C++
C#
JS

FMOD_RESULT Studio::System::getAdvancedSettings(
  FMOD_STUDIO_ADVANCEDSETTINGS *settings
);
settings Out
Studio System advanced settings. (FMOD_STUDIO_ADVANCEDSETTINGS)

See Also: Studio::System::setAdvancedSettings

Studio::System::getBank

Retrieves a loaded bank.

C
C++
C#
JS

FMOD_RESULT Studio::System::getBank(
  const char *path,
  Studio::Bank **bank
);
path
The bank path or the ID string that identifies the bank. (UTF-8 string)
bank Out
Bank object. (Studio::Bank)

path may be a path, such as bank:/Weapons or an ID string such as {793cddb6-7fa1-4e06-b805-4c74c0fd625b}.

Note that path lookups will only succeed if the strings bank has been loaded.

See Also: Studio::System::getBankByID

Studio::System::getBankByID

Retrieves a loaded bank.

C
C++
C#
JS

FMOD_RESULT Studio::System::getBankByID(
  const FMOD_GUID *id,
  Studio::Bank **bank
);
id
Bank GUID. (FMOD_GUID)
bank Out
Bank object. (Studio::Bank)

See Also: Studio::parseID, Studio::System::lookupID, Studio::System::getBank

Studio::System::getBankCount

Retrieves the number of loaded banks.

C
C++
C#
JS

FMOD_RESULT Studio::System::getBankCount(
  int *count
);
count Out
Number of loaded banks.

May be used in conjunction with Studio::System::getBankList to enumerate the loaded banks.

Studio::System::getBankList

Retrieves the loaded Banks.

C
C++
C#
JS

FMOD_RESULT Studio::System::getBankList(
  Studio::Bank **array,
  int capacity,
  int *count
);
array Out
Array to receive the list. (Studio::Bank)
capacity
Capacity of array.
count OutOpt
Number of banks written to array.

May be used in conjunction with Studio::System::getBankCount to enumerate the loaded banks.

Studio::System::getBufferUsage

Retrieves buffer usage information.

C
C++
C#
JS

FMOD_RESULT Studio::System::getBufferUsage(
  FMOD_STUDIO_BUFFER_USAGE *usage
);
usage Out
Buffer usage information. (FMOD_STUDIO_BUFFER_USAGE)

Stall count and time values are cumulative. They can be reset by calling Studio::System::resetBufferUsage.

Stalls due to the studio command queue overflowing can be avoided by setting a larger command queue size with Studio::System::setAdvancedSettings.

Studio::System::getBus

Retrieves a loaded bus.

C
C++
C#
JS

FMOD_RESULT Studio::System::getBus(
  const char *path,
  Studio::Bus **bus
);
path
The bus path or the ID string that identifies the bus. (UTF-8 string)
bus Out
Bus object. (Studio::Bus)

This function allows you to retrieve a handle for any bus in the global mixer.

path may be a path, such as bus:/SFX/Ambience, or an ID string, such as {d9982c58-a056-4e6c-b8e3-883854b4bffb}.

Note that path lookups will only succeed if the strings bank has been loaded.

See Also: Studio::System::getBusByID

Studio::System::getBusByID

Retrieves a loaded bus.

C
C++
C#
JS

FMOD_RESULT Studio::System::getBusByID(
  const FMOD_GUID *id,
  Studio::Bus **bus
);
id
Bus GUID. (FMOD_GUID)
bus Out
Bus object. (Studio::Bus)

This function allows you to retrieve a handle for any bus in the global mixer.

See Also: Studio::System::getBus

Studio::System::getCoreSystem

Retrieves the Core System.

C
C++
C#
JS

FMOD_RESULT Studio::System::getCoreSystem(
  System **system
);
system Out
Core System object. (System)

The Core System object can be retrieved before initializing the Studio System object to call additional core configuration functions.

See Also: System::setFileSystem, System::setDSPBufferSize, System::setSoftwareChannels, System::setSoftwareFormat, System::setAdvancedSettings, System::setCallback

Studio::System::getCPUUsage

Retrieves performance information.

C
C++
C#
JS

FMOD_RESULT Studio::System::getCPUUsage(
  FMOD_STUDIO_CPU_USAGE *usage
);
usage Out
Performance information. (FMOD_STUDIO_CPU_USAGE)

Studio::System::getEvent

Retrieves an EventDescription.

C
C++
C#
JS

FMOD_RESULT Studio::System::getEvent(
  const char *path,
  Studio::EventDescription **event
);
path
The path or the ID string that identifies the event or snapshot. (UTF-8 string)
event Out
EventDescription object. (Studio::EventDescription)

This function allows you to retrieve a handle to any loaded event description.

path may be a path, such as event:/UI/Cancel or snapshot:/IngamePause, or an ID string, such as {2a3e48e6-94fc-4363-9468-33d2dd4d7b00}.

Note that path lookups will only succeed if the strings bank has been loaded.

See Also: Studio::parseID, Studio::System::lookupID, Studio::System::getEventByID, Studio::EventDescription::isSnapshot, Studio::EventDescription::createInstance

Studio::System::getEventByID

Retrieves an EventDescription.

C
C++
C#
JS

FMOD_RESULT Studio::System::getEventByID(
  const FMOD_GUID *id,
  Studio::EventDescription **event
);
id
Event or snapshot GUID. (FMOD_GUID)
event Out
EventDescription object. (Studio::EventDescription)

This function allows you to retrieve a handle to any loaded event description.

See Also: Studio::System::getEvent

Studio::System::getListenerAttributes

Retrieves listener 3D attributes.

C
C++
C#
JS

FMOD_RESULT Studio::System::getListenerAttributes(
  int listener,
  FMOD_3D_ATTRIBUTES *attributes
);
listener
Listener index.
attributes Out
3D attributes. (FMOD_3D_ATTRIBUTES)

See Also: Studio::EventInstance::get3DAttributes, Studio::System::getNumListeners, Studio::System::setListenerAttributes

Studio::System::getListenerWeight

Retrieves listener weighting.

C
C++
C#
JS

FMOD_RESULT Studio::System::getListenerWeight(
  int listener,
  float *weight
);
listener
Listener index.
weight Out
Weighting value.

See Also: Studio::System::setListenerWeight, Studio::System::setNumListeners, Studio::System::getListenerAttributes

Studio::System::getMemoryUsage

Retrieves memory usage statistics.

C
C++
C#
JS

FMOD_RESULT Studio::System::getMemoryUsage(
  FMOD_STUDIO_MEMORY_USAGE *memoryusage
);
memoryusage Out
Memory usage. (FMOD_STUDIO_MEMORY_USAGE)

The memory usage sampledata value for the system is the total size of non-streaming sample data currently loaded.

Memory usage statistics are only available in logging builds, in release builds memoryusage will contain zero for all values after calling this function.

Studio::System::getNumListeners

Retrieves the number of listeners.

C
C++
C#
JS

FMOD_RESULT Studio::System::getNumListeners(
  int *numlisteners
);
numlisteners Out
Number of listeners.

See Also: Studio::System::setNumListeners

Studio::System::getParameterByID

Retrieves a global parameter value by unique identifier.

C
C++
C#
JS

FMOD_RESULT Studio::System::getParameterByID(
  FMOD_STUDIO_PARAMETER_ID id,
  float *value,
  float *finalvalue = nullptr
);
id
Parameter identifier. (FMOD_STUDIO_PARAMETER_ID)
value OutOpt
Parameter value as set from the public API.
finalvalue OutOpt
Final combined value.

finalvalue is the final value of the parameter after applying adjustments due to automation, modulation, seek speed, and parameter velocity to value. This is calculated asynchronously when the Studio system updates.

See Also: Studio::System::setParameterByID

Studio::System::getParameterByName

Retrieves a global parameter value by name.

C
C++
C#
JS

FMOD_RESULT Studio::System::getParameterByName(
  const char *name,
  float *value,
  float *finalvalue = nullptr
);
name
Parameter name (case-insensitive). (UTF-8 string)
value OutOpt
Parameter value as set from the public API.
finalvalue OutOpt
Final combined value.

finalvalue is the final value of the parameter after applying adjustments due to automation, modulation, seek speed, and parameter velocity to value. This is calculated asynchronously when the Studio system updates.

See Also: Studio::System::setParameterByName

Studio::System::getParameterDescriptionByID

Retrieves a global parameter by ID.

C
C++
C#
JS

FMOD_RESULT Studio::System::getParameterDescriptionByID(
  FMOD_STUDIO_PARAMETER_ID id,
  FMOD_STUDIO_PARAMETER_DESCRIPTION *parameter
);
id
Parameter ID. (FMOD_STUDIO_PARAMETER_ID)
parameter Out
Parameter description. (FMOD_STUDIO_PARAMETER_DESCRIPTION)

Studio::System::getParameterDescriptionByName

Retrieves a global parameter by name or path.

C
C++
C#
JS

FMOD_RESULT Studio::System::getParameterDescriptionByName(
  const char *name,
  FMOD_STUDIO_PARAMETER_DESCRIPTION *parameter
);
name
Parameter name. (UTF-8 string)
parameter Out
Parameter description. (FMOD_STUDIO_PARAMETER_DESCRIPTION)

name can be the short name (such as 'Wind') or the full path (such as 'parameter:/Ambience/Wind'). Path lookups will only succeed if the strings bank has been loaded.

Studio::System::getParameterDescriptionCount

Retrieves the number of global parameters.

C
C++
C#
JS

FMOD_RESULT Studio::System::getParameterDescriptionCount(
  int *count
);
count Out
Global parameter count.

See Also: Studio::System::getParameterDescriptionList

Studio::System::getParameterDescriptionList

Retrieves a list of global parameters.

C
C++
C#
JS

FMOD_RESULT Studio::System::getParameterDescriptionList(
  FMOD_STUDIO_PARAMETER_DESCRIPTION *array,
  int capacity,
  int *count
);
array Out
Global parameters. (FMOD_STUDIO_PARAMETER_DESCRIPTION)
capacity
Capacity of array.
count Out
Number of parameters written to array.

See Also: Studio::System::getParameterDescriptionCount

Studio::System::getSoundInfo

Retrieves information for loading a sound from the audio table.

C
C++
C#
JS

FMOD_RESULT Studio::System::getSoundInfo(
  const char *key,
  FMOD_STUDIO_SOUND_INFO *info
);
key
The key that identifies the sound. (UTF-8 string)
info Out
Sound loading information. (FMOD_STUDIO_SOUND_INFO)

The FMOD_STUDIO_SOUND_INFO structure contains information to be passed to System::createSound (which will create a parent sound), along with a subsound index to be passed to Sound::getSubSound once the parent sound is loaded.

The user is expected to call System::createSound with the given information. It is up to the user to combine in any desired loading flags, such as FMOD_CREATESTREAM, FMOD_CREATECOMPRESSEDSAMPLE or FMOD_NONBLOCKING with the flags in FMOD_STUDIO_SOUND_INFO::mode.

When the banks have been loaded via Studio::System::loadBankMemory, the mode will be returned as FMOD_OPENMEMORY_POINT. This won't work with the default FMOD_CREATESAMPLE mode. For memory banks, you should add in the FMOD_CREATECOMPRESSEDSAMPLE or FMOD_CREATESTREAM flag, or remove FMOD_OPENMEMORY_POINT and add FMOD_OPENMEMORY to decompress the sample into a new allocation.

Studio::System::getUserData

Retrieves the user data.

C
C++
C#
JS

FMOD_RESULT Studio::System::getUserData(
  void **userdata
);
userdata Out
User data.

See Also: Studio::System::setUserData

Studio::System::getVCA

Retrieves a loaded VCA.

C
C++
C#
JS

FMOD_RESULT Studio::System::getVCA(
  const char *path,
  Studio::VCA **vca
);
path
The path or the ID string that identifies the VCA. (UTF-8 string)
vca Out
VCA object. (Studio::VCA)

This function allows you to retrieve a handle for any VCA in the global mixer.

path may be a path, such as vca:/MyVCA, or an ID string, such as {d9982c58-a056-4e6c-b8e3-883854b4bffb}.

Note that path lookups will only succeed if the strings bank has been loaded.

See Also: Studio::System::getVCAByID

Studio::System::getVCAByID

Retrieves a loaded VCA.

C
C++
C#
JS

FMOD_RESULT Studio::System::getVCAByID(
  const FMOD_GUID *id,
  Studio::VCA **vca
);
id
VCA GUID. (FMOD_GUID)
vca Out
VCA object. (Studio::VCA)

This function allows you to retrieve a handle for any VCA in the global mixer.

See Also: Studio::System::getVCA

Studio::System::initialize

Initializes the Studio System.

C
C++
C#
JS

FMOD_RESULT Studio::System::initialize(
  int maxchannels,
  FMOD_STUDIO_INITFLAGS studioflags,
  FMOD_INITFLAGS flags,
  void *extradriverdata
);
maxchannels
The maximum number of channels to be used in FMOD.
studioflags
Studio system initialization flags. (FMOD_STUDIO_INITFLAGS)
flags
Core system initialization flags. (FMOD_INITFLAGS)
extradriverdata Opt
Driver specific data to be passed to the output plugin.

The core system used by the studio system is initialized at the same time as the studio system.

The flags and extradriverdata parameters are passed to System::init to initialize the core.

See Also: Creating the Studio System

Studio::System::isValid

Checks that the System reference is valid and has been initialized.

C
C++
C#
JS

bool Studio::System::isValid()

Studio::System::loadBankCustom

Loads the metadata of a Studio bank using custom read callbacks.

C
C++
C#
JS

FMOD_RESULT Studio::System::loadBankCustom(
  const FMOD_STUDIO_BANK_INFO *info,
  FMOD_STUDIO_LOAD_BANK_FLAGS flags,
  Studio::Bank **bank
);
info
Information for loading the bank. (FMOD_STUDIO_BANK_INFO)
flags
Flags to control bank loading. (FMOD_STUDIO_LOAD_BANK_FLAGS)
bank Out
Bank object. (Studio::Bank)

Sample data must be loaded separately see Sample Data Loading for details.

By default this function will block until the load finishes and return the FMOD_RESULT indicating the result. If the load fails then bank will contain NULL.

Using the FMOD_STUDIO_LOAD_BANK_NONBLOCKING flag will cause the bank to be loaded asynchronously. In that case this function will always return FMOD_OK and bank will contain a valid bank handle. Load errors for asynchronous banks can be detected by calling Studio::Bank::getLoadingState. Failed asynchronous banks should be released by calling Studio::Bank::unload.

If a bank has been split, separating out assets and optionally streams from the metadata bank, all parts must be loaded before any APIs that use the data are called. It is recommended you load each part one after another (order is not important), then proceed with dependent API calls such as Studio::Bank::loadSampleData or Studio::System::getEvent.

See Also: Studio::System::loadBankFile, Studio::System::loadBankMemory

Studio::System::loadBankFile

Loads the metadata of a Studio bank from file.

C
C++
C#
JS

FMOD_RESULT Studio::System::loadBankFile(
  const char *filename,
  FMOD_STUDIO_LOAD_BANK_FLAGS flags,
  Studio::Bank **bank
);
filename
Name of the file on disk. (UTF-8 string)
flags
Flags to control bank loading. (FMOD_STUDIO_LOAD_BANK_FLAGS)
bank Out
Bank object. (Studio::Bank)

Sample data must be loaded separately see Sample Data Loading for details.

By default this function will block until the file load finishes and return the FMOD_RESULT indicating the result. If the load fails then bank will contain NULL.

Using the FMOD_STUDIO_LOAD_BANK_NONBLOCKING flag will cause the bank to be loaded asynchronously. In that case this function will always return FMOD_OK and bank will contain a valid bank handle. Load errors for asynchronous banks can be detected by calling Studio::Bank::getLoadingState. Failed asynchronous banks should be released by calling Studio::Bank::unload.

If a bank has been split, separating out assets and optionally streams from the metadata bank, all parts must be loaded before any APIs that use the data are called. It is recommended you load each part one after another (order is not important), then proceed with dependent API calls such as Studio::Bank::loadSampleData or Studio::System::getEvent.

See Also: Studio::System::loadBankCustom, Studio::System::loadBankMemory

Studio::System::loadBankMemory

Loads the metadata of a Studio bank from memory.

C
C++
C#
JS

FMOD_RESULT Studio::System::loadBankMemory(
  const char *buffer,
  int length,
  FMOD_STUDIO_LOAD_MEMORY_MODE mode,
  FMOD_STUDIO_LOAD_BANK_FLAGS flags,
  Studio::Bank **bank
);
buffer
Memory buffer.
length
Length of the memory buffer.
mode
Loading mode to use. (FMOD_STUDIO_LOAD_MEMORY_MODE)
flags
Flags to control bank loading. (FMOD_STUDIO_LOAD_BANK_FLAGS)
bank Out
Bank object. (Studio::Bank)

Sample data must be loaded separately see Sample Data Loading for details.

When mode is FMOD_STUDIO_LOAD_MEMORY FMOD will allocate an internal buffer and copy the data from the passed in buffer before using it. When used in this mode there are no alignment restrictions on buffer and the memory pointed to by buffer may be cleaned up at any time after this function returns.

When mode is FMOD_STUDIO_LOAD_MEMORY_POINT FMOD will use the passed memory buffer directly. When using this mode the buffer must be aligned to FMOD_STUDIO_LOAD_MEMORY_ALIGNMENT and the memory must persist until the bank has been fully unloaded, which can be some time after calling Studio::Bank::unload to unload the bank. You can ensure the memory is not being freed prematurely by only freeing it after receiving the FMOD_STUDIO_SYSTEM_CALLBACK_BANK_UNLOAD callback.

By default this function will block until the load finishes and return the FMOD_RESULT indicating the result. If the load fails then bank will contain NULL.

Using the FMOD_STUDIO_LOAD_BANK_NONBLOCKING flag will cause the bank to be loaded asynchronously. In that case this function will always return FMOD_OK and bank will contain a valid bank handle. Load errors for asynchronous banks can be detected by calling Studio::Bank::getLoadingState. Failed asynchronous banks should be released by calling Studio::Bank::unload.

This function is not compatible with FMOD_STUDIO_ADVANCEDSETTINGS::encryptionkey, using them together will cause an error to be returned.

If a bank has been split, separating out assets and optionally streams from the metadata bank, all parts must be loaded before any APIs that use the data are called. It is recommended you load each part one after another (order is not important), then proceed with dependent API calls such as Studio::Bank::loadSampleData or Studio::System::getEvent.

See Also: Studio::System::loadBankFile, Studio::System::loadBankCustom, Studio::System::setCallback

Studio::System::loadCommandReplay

Load a command replay.

C
C++
C#
JS

FMOD_RESULT Studio::System::loadCommandReplay(
  const char *filename,
  FMOD_STUDIO_COMMANDREPLAY_FLAGS flags,
  Studio::CommandReplay **replay
);
filename
The name of the file from which to load the command replay. (UTF-8 string)
flags
Flags that control the command replay. (FMOD_STUDIO_COMMANDREPLAY_FLAGS)
replay Out
Command replay. (Studio::CommandReplay)

See Also: Studio::System::startCommandCapture, Studio::System::stopCommandCapture, Studio::CommandReplay::start, Studio::CommandReplay::stop, Studio::CommandReplay::release

Studio::System::lookupID

Retrieves the ID for a bank, event, snapshot, bus or VCA.

C
C++
C#
JS

FMOD_RESULT Studio::System::lookupID(
  const char *path,
  FMOD_GUID *id
);
path
Path. (UTF-8 string)
id Out
GUID. (FMOD_GUID)

The strings bank must be loaded prior to calling this function, otherwise FMOD_ERR_EVENT_NOTFOUND is returned.

The path can be copied to the system clipboard from FMOD Studio using the "Copy Path" context menu command.

See Also: Studio::System::lookupPath

Studio::System::lookupPath

Retrieves the path for a bank, event, snapshot, bus or VCA.

C
C++
C#
JS

FMOD_RESULT Studio::System::lookupPath(
  const FMOD_GUID *id,
  char *path,
  int size,
  int *retrieved
);
id
GUID. (FMOD_GUID)
path OutOpt
Buffer to receive the path. (UTF-8 string)
size
Size of the path buffer in bytes. Must be 0 if path is null.
retrieved OutOpt
Length of the path in bytes, including the terminating null character.

The strings bank must be loaded prior to calling this function, otherwise FMOD_ERR_EVENT_NOTFOUND is returned.

If the path is longer than size then it is truncated and this function returns FMOD_ERR_TRUNCATED.

The retrieved parameter can be used to get the buffer size required to hold the full path.

See Also: Studio::System::lookupID

Studio::System::registerPlugin

Registers a plugin DSP.

C
C++
C#
JS

FMOD_RESULT Studio::System::registerPlugin(
  const FMOD_DSP_DESCRIPTION *description
);
description
The description of the DSP. (FMOD_DSP_DESCRIPTION)

Plugin DSPs used by an event must be registered using this function before loading the bank containing the event.

See Also: Studio::System::unregisterPlugin

Studio::System::release

Shut down and free the Studio System object.

C
C++
C#
JS

FMOD_RESULT Studio::System::release();

This function will free the memory used by the Studio System object and everything created under it.

Studio::System::create and Studio::System::release are not thread-safe. Calling either of these functions concurrently with any FMOD Studio API function (including these two functions) may cause undefined behavior. External synchronization must be used if calls to Studio::System::create or Studio::System::release could overlap other FMOD Studio API calls. All other FMOD Studio API functions are thread safe and may be called freely from any thread unless otherwise documented.

All handles or pointers to objects associated with a Studio System object become invalid when the Studio System object is released. The FMOD Studio API attempts to protect against stale handles and pointers being used with a different Studio System object but this protection cannot be guaranteed and attempting to use stale handles or pointers may cause undefined behavior.

See Also: Creating the Studio System

Studio::System::resetBufferUsage

Resets memory buffer usage statistics.

C
C++
C#
JS

FMOD_RESULT Studio::System::resetBufferUsage();

This function resets the buffer usage data tracked by the FMOD Studio System.

See Also: FMOD_STUDIO_BUFFER_USAGE, Studio::System::getBufferUsage

Studio::System::setAdvancedSettings

Sets advanced settings.

C
C++
C#
JS

FMOD_RESULT Studio::System::setAdvancedSettings(
  FMOD_STUDIO_ADVANCEDSETTINGS *settings
);
settings
Studio System advanced settings. (FMOD_STUDIO_ADVANCEDSETTINGS)
encryptionkey C#
Specify the key for loading sounds from encrypted banks. (UTF-8 string)

This function must be called prior to Studio initialization.

See Also: Studio::System::getAdvancedSettings, Studio::System::initialize

Studio::System::setCallback

Sets a callback for the FMOD Studio System.

C
C++
C#
JS

FMOD_RESULT Studio::System::setCallback(
  FMOD_STUDIO_SYSTEM_CALLBACK callback,
  FMOD_STUDIO_SYSTEM_CALLBACK_TYPE callbackmask = FMOD_STUDIO_SYSTEM_CALLBACK_ALL
);
callback
System callback function. (FMOD_STUDIO_SYSTEM_CALLBACK)
callbackmask
A bitfield specifying which callback types are required. Defaults to FMOD_STUDIO_SYSTEM_CALLBACK_ALL. (FMOD_STUDIO_SYSTEM_CALLBACK_TYPE)

The system callback function is called for a variety of reasons, use the callbackmask to choose which callbacks you are interested in.

Some callbacks are called on the game thread when Studio::System::update is called and others are called asynchronously from the Studio System update thread. See the FMOD_STUDIO_SYSTEM_CALLBACK_TYPE for details.

See Also: Callback Behavior, Studio::System::setUserData

Studio::System::setListenerAttributes

Sets the 3D attributes of the listener.

C
C++
C#
JS

FMOD_RESULT Studio::System::setListenerAttributes(
  int listener,
  const FMOD_3D_ATTRIBUTES *attributes
);
listener
Listener index.
attributes
3D attributes. (FMOD_3D_ATTRIBUTES)

See Also: Studio::System::getListenerAttributes

Studio::System::setListenerWeight

Sets the listener weighting.

C
C++
C#
JS

FMOD_RESULT Studio::System::setListenerWeight(
  int listener,
  float weight
);
listener
Listener index.
weight

Weighting value.

  • Range: [0, 1]
  • Default: 1

Listener weighting is a factor which determines how much the listener influences the mix. It is taken into account for 3D panning, doppler, and the automatic distance event parameter. A listener with a weight of 0 has no effect on the mix.

Listener weighting can be used to fade in and out multiple listeners. For example to do a crossfade, an additional listener can be created with a weighting of 0 that ramps up to 1 while the old listener weight is ramped down to 0. After the crossfade is finished the number of listeners can be reduced to 1 again.

The sum of all the listener weights should add up to at least 1. It is a user error to set all listener weights to 0.

See Also: Studio::System::getListenerWeight, Studio::System::setNumListeners

Studio::System::setNumListeners

Sets the number of listeners in the 3D sound scene.

C
C++
C#
JS

FMOD_RESULT Studio::System::setNumListeners(
  int numlisteners
);
numlisteners

Number of listeners.

If the number of listeners is set to more than 1 then FMOD uses a 'closest sound to the listener' method to determine what should be heard.

See Also: Studio::System::getNumListeners, Studio::System::setListenerAttributes, Studio::System::setListenerWeight

Studio::System::setParameterByID

Sets a global parameter value by unique identifier.

C
C++
C#
JS

FMOD_RESULT Studio::System::setParameterByID(
  FMOD_STUDIO_PARAMETER_ID id,
  float value,
  bool ignoreseekspeed = false
);
id
Parameter identifier. (FMOD_STUDIO_PARAMETER_ID)
value
Value for given identifier.
ignoreseekspeed

Specifies whether to ignore the parameter's seek speed and set the value immediately.

  • Units: Boolean

See Also: Studio::System::setParameterByName, Studio::System::setParametersByIDs, Studio::System::getParameterByID, Studio::System::getParameterByName

Studio::System::setParameterByName

Sets a global parameter value by name.

C
C++
C#
JS

FMOD_RESULT Studio::System::setParameterByName(
  const char *name,
  float value,
  bool ignoreseekspeed = false
);
name
Parameter name (case-insensitive). (UTF-8 string)
value
Value for given name.
ignoreseekspeed

Specifies whether to ignore the parameter's seek speed and set the value immediately.

  • Units: Boolean

See Also: Studio::System::setParameterByID, Studio::System::setParametersByIDs, Studio::System::getParameterByID, Studio::System::getParameterByName

Studio::System::setParametersByIDs

Sets multiple global parameter values by unique identifier.

C
C++
C#
JS

FMOD_RESULT Studio::System::setParametersByIDs(
  const FMOD_STUDIO_PARAMETER_ID *ids,
  float *values,
  int count,
  bool ignoreseekspeed = false
);
ids
Array of parameter identifiers. (FMOD_STUDIO_PARAMETER_ID)
values
Array of values for each given identifier.
count

Number of items in the given arrays.

  • Range: [1, 32]
ignoreseekspeed

Specifies whether to ignore the parameter's seek speed and set the value immediately.

  • Units: Boolean

If any ID is set to all zeroes then the corresponding value will be ignored.

See Also: Studio::System::setParameterByID, Studio::System::setParameterByName, Studio::System::getParameterByID, Studio::System::getParameterByName

Studio::System::setUserData

Sets the user data.

C
C++
C#
JS

FMOD_RESULT Studio::System::setUserData(
  void *userdata
);
userdata
User data to store within the system.

The user data is passed to the system callback.

See Also: Studio::System::getUserData, Studio::System::setCallback

Studio::System::startCommandCapture

Recording Studio commands to a file.

C
C++
C#
JS

FMOD_RESULT Studio::System::startCommandCapture(
  const char *filename,
  FMOD_STUDIO_COMMANDCAPTURE_FLAGS flags
);
filename
The name of the file to which the recorded commands are written. (UTF-8 string)
flags
Flags that control command capturing. (FMOD_STUDIO_COMMANDCAPTURE_FLAGS)

The commands generated by the FMOD Studio API can be captured and later replayed for debug and profiling purposes.

Unless the FMOD_STUDIO_COMMANDCAPTURE_SKIP_INITIAL_STATE flag is specified, the command capture will first record the set of all banks and event instances that currently exist.

See Also: Studio::System::stopCommandCapture, Studio::System::loadCommandReplay

Studio::System::stopCommandCapture

Stop recording Studio commands.

C
C++
C#
JS

FMOD_RESULT Studio::System::stopCommandCapture();

See Also: Studio::System::startCommandCapture, Studio::System::loadCommandReplay

Studio::System::unloadAll

Unloads all currently loaded banks.

C
C++
C#
JS

FMOD_RESULT Studio::System::unloadAll();

See Also: Studio::System::loadBankFile, Studio::System::loadBankMemory, Studio::System::loadBankCustom

Studio::System::unregisterPlugin

Unregisters a plugin DSP.

C
C++
C#
JS

FMOD_RESULT Studio::System::unregisterPlugin(
  const char *name
);
name
The name of the DSP. This must match the description passed to Studio::System::registerPlugin.

See Also: Studio::System::registerPlugin

Studio::System::update

Update the FMOD Studio System.

C
C++
C#
JS

FMOD_RESULT Studio::System::update();

When Studio is initialized in the default asynchronous processing mode this function submits all buffered commands for execution on the Studio Update thread for asynchronous processing. This is a fast operation since the commands are not processed on the calling thread. If Studio is initialized with FMOD_STUDIO_INIT_DEFERRED_CALLBACKS then any deferred callbacks fired during any asynchronous updates since the last call to this function will be called. If an error occurred during any asynchronous updates since the last call to this function then this function will return the error result.

When Studio is initialized with FMOD_STUDIO_INIT_SYNCHRONOUS_UPDATE queued commands will be processed immediately when calling this function, the scheduling and update logic for the Studio system are executed and all callbacks are fired. This may block the calling thread for a substantial amount of time.

See Also: Studio System Processing

FMOD API User Manual 2.00.22 (2021-12-20). © 2021 Firelight Technologies Pty Ltd.

     

© 2026 Firelight Technologies Pty Ltd | Made in Melbourne