FMOD Engine User Manual 2.03

6. Studio API Reference | Studio::Bus

Represents a global mixer bus.

Playback Control:

Playback Properties:

Core:

Profiling:

General:

Studio::Bus::getChannelGroup

Retrieves the core ChannelGroup.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::getChannelGroup(
  ChannelGroup **group
);
FMOD_RESULT FMOD_Studio_Bus_GetChannelGroup(
  FMOD_STUDIO_BUS *bus,
  FMOD_CHANNELGROUP **group
);
RESULT Studio.Bus.getChannelGroup(
  out FMOD.ChannelGroup group
);
Bus.getChannelGroup(
  group
);
group Out
Core ChannelGroup. (ChannelGroup)

By default the ChannelGroup will only exist when it is needed; see Signal Paths for details. If the ChannelGroup does not exist, this function will return FMOD_ERR_STUDIO_NOT_LOADED.

See Also: Studio::Bus::lockChannelGroup

Studio::Bus::getCPUUsage

Retrieves the bus CPU usage data.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::getCPUUsage(
  unsigned int *exclusive,
  unsigned int *inclusive
);
FMOD_RESULT FMOD_Studio_Bus_GetCPUUsage(
  FMOD_STUDIO_BUS *bus,
  unsigned int *exclusive,
  unsigned int *inclusive
);
RESULT Studio.Bus.getCPUUsage(
  out uint exclusive,
  out uint inclusive
);
Studio.Bus.getCPUUsage(
    exclusive,
    inclusive
);
exclusive OutOpt

CPU time spent processing the events of this bus.

  • Units: Microseconds
inclusive OutOpt

CPU time spent processing the events and all input buses of this bus.

  • Units: Microseconds

FMOD_INIT_PROFILE_ENABLE with System::init is required to call this function.

Studio::Bus::getID

Retrieves the GUID.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::getID(
  FMOD_GUID *id
);
FMOD_RESULT FMOD_Studio_Bus_GetID(
  FMOD_STUDIO_BUS *bus,
  FMOD_GUID *id
);
RESULT Studio.Bus.getID(
  out Guid id
);
Bus.getID(
  id
);
id Out
GUID. (FMOD_GUID)

Studio::Bus::getMemoryUsage

Retrieves memory usage statistics.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::getMemoryUsage(
  FMOD_STUDIO_MEMORY_USAGE *memoryusage
);
FMOD_RESULT FMOD_Studio_Bus_GetMemoryUsage(
  FMOD_STUDIO_BUS *bus,
  FMOD_STUDIO_MEMORY_USAGE *memoryusage
);
RESULT Studio.Bus.getMemoryUsage(
  out MEMORY_USAGE memoryusage
);

Not supported for JavaScript.

memoryusage Out
Memory usage. (FMOD_STUDIO_MEMORY_USAGE)

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

Studio::Bus::getMute

Retrieves the mute state.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::getMute(
  bool *mute
);
FMOD_RESULT FMOD_Studio_Bus_GetMute(
  FMOD_STUDIO_BUS *bus,
  FMOD_BOOL *mute
);
RESULT Studio.Bus.getMute(
  out bool mute
);
Bus.getMute(
  mute
);
mute Out

Mute state. True if the bus is muted.

  • Units: Boolean

See Also: Studio::Bus::setMute

Studio::Bus::getPath

Retrieves the path.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::getPath(
  char *path,
  int size,
  int *retrieved
);
FMOD_RESULT FMOD_Studio_Bus_GetPath(
  FMOD_STUDIO_BUS *bus,
  char *path,
  int size,
  int *retrieved
);
RESULT Studio.Bus.getPath(
  out string path
);
Bus.getPath(
  path,
  size,
  retrieved
);
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.

Studio::Bus::getPaused

Retrieves the pause state.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::getPaused(
  bool *paused
);
FMOD_RESULT FMOD_Studio_Bus_GetPaused(
  FMOD_STUDIO_BUS *bus,
  FMOD_BOOL *paused
);
RESULT Studio.Bus.getPaused(
  out bool paused
);
Bus.getPaused(
  paused
);
paused Out

Pause state. True if the bus is paused.

  • Units: Boolean

See Also: Studio::Bus::setPaused

Studio::Bus::getPortIndex

Retrieves the port index assigned to the bus.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::getPortIndex(
  FMOD_PORT_INDEX *index
);
FMOD_RESULT FMOD_Studio_Bus_GetPortIndex(
  FMOD_STUDIO_BUS *bus,
  FMOD_PORT_INDEX *index
);
RESULT Studio.Bus.getPortIndex(
  out ulong index
);
Bus.getPortIndex(
  index
);
index Out
The port index assigned to the bus. (FMOD_PORT_INDEX)

See Also: Studio::Bus::setPortIndex

Studio::Bus::getVolume

Retrieves the volume level.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::getVolume(
  float *volume,
  float *finalvolume = nullptr
);
FMOD_RESULT FMOD_Studio_Bus_GetVolume(
  FMOD_STUDIO_BUS *bus,
  float *volume,
  float *finalvolume
);
RESULT Studio.Bus.getVolume(
  out float volume
);
RESULT Studio.Bus.getVolume(
  out float volume,
  out float finalvolume
);
Bus.getVolume(
  volume,
  finalvolume
);
volume OutOpt
Volume set via Studio::Bus::setVolume.
finalvolume OutOpt
Final combined volume.

The finalvolume value is calculated by combining the volume set via Studio::Bus::setVolume with the bus's default volume and any snapshots or VCAs that affect the bus. Volume changes are processed in the Studio system update, so finalvolume will be the value calculated by the last update.

Studio::Bus::isValid

Checks that the Bus reference is valid.

C
C++
C#
JS

bool Studio::Bus::isValid()
bool FMOD_Studio_Bus_IsValid(FMOD_STUDIO_BUS *bus)
bool Studio.Bus.isValid()
Studio.Bus.isValid()

Studio::Bus::lockChannelGroup

Locks the core ChannelGroup.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::lockChannelGroup();
FMOD_RESULT FMOD_Studio_Bus_LockChannelGroup(FMOD_STUDIO_BUS *bus);
RESULT Studio.Bus.lockChannelGroup();
Bus.lockChannelGroup();

This function forces the system to create the ChannelGroup and keep it available until Studio::Bus::unlockChannelGroup is called. See Signal Paths for details.

The ChannelGroup may not be available immediately after calling this function. When Studio has been initialized in asynchronous mode, the ChannelGroup will not be created until the command has been executed in the async thread. When Studio has been initialized with FMOD_STUDIO_INIT_SYNCHRONOUS_UPDATE, the ChannelGroup will be created in the next Studio::System::update call.

You can call Studio::System::flushCommands to ensure the ChannelGroup has been created. Alternatively you can keep trying to obtain the ChannelGroup via Studio::Bus::getChannelGroup until it is ready.

Studio::Bus::setMute

Sets the mute state.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::setMute(
  bool mute
);
FMOD_RESULT FMOD_Studio_Bus_SetMute(
  FMOD_STUDIO_BUS *bus,
  FMOD_BOOL mute
);
RESULT Studio.Bus.setMute(
  bool mute
);
Bus.setMute(
  mute
);
mute

Mute state. True to mute the bus.

  • Units: Boolean

Mute is an additional control for volume, the effect of which is equivalent to setting the volume to zero.

An individual mute state is kept for each bus. Muting a bus will override the mute state of its inputs (meaning they return true from Studio::Bus::getMute), while unmuting a bus will cause its inputs to obey their individual mute state. The mute state is processed in the Studio system update, so Studio::Bus::getMute will return the state as determined by the last update.

Studio::Bus::setPaused

Sets the pause state.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::setPaused(
  bool paused
);
FMOD_RESULT FMOD_Studio_Bus_SetPaused(
  FMOD_STUDIO_BUS *bus,
  FMOD_BOOL paused
);
RESULT Studio.Bus.setPaused(
  bool paused
);
Bus.setPaused(
  paused
);
paused

Pause state. True to pause the bus.

  • Units: Boolean

This function allows pausing/unpausing of all audio routed into the bus.

An individual pause state is kept for each bus. Pausing a bus will override the pause state of its inputs (meaning they return true from Studio::Bus::getPaused), while unpausing a bus will cause its inputs to obey their individual pause state. The pause state is processed in the Studio system update, so Studio::Bus::getPaused will return the state as determined by the last update.

Studio::Bus::setPortIndex

Sets the port index to use when attaching to an output port.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::setPortIndex(
  FMOD_PORT_INDEX index
);
FMOD_RESULT FMOD_Studio_Bus_SetPortIndex(
  FMOD_STUDIO_BUS *bus,
  FMOD_PORT_INDEX index
);
RESULT Studio.Bus.setPortIndex(
  ulong index
);
Bus.setPortIndex(
  index
);
index
Port index to use when attaching to an output port. (FMOD_PORT_INDEX)

When a bus which is an output port is instantiated it is connected to an output port based on the port type set in FMOD Studio. For some port types, a platform-specific port index is required to connect to the correct output port. For example, if the output port type is a speaker in a controller, then a platform-specific port index may be required to specify which controller the bus is to attach to. In such a case, call this function passing the platform specific port index.

There is no need to call this function for port types which do not require an index.

This function may be called at any time after a bank containing the bus has been loaded.

See Also: Studio::Bus::getPortIndex, FMOD_PORT_TYPE

Studio::Bus::setVolume

Sets the volume level.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::setVolume(
  float volume
);
FMOD_RESULT FMOD_Studio_Bus_SetVolume(
  FMOD_STUDIO_BUS *bus,
  float volume
);
RESULT Studio.Bus.setVolume(
  float volume
);
Bus.setVolume(
  volume
);
volume

Volume level. Negative level inverts the signal.

  • Units: Linear
  • Range: (-inf, inf)
  • Default: 1

This volume is applied as a scaling factor to the volume level set in FMOD Studio.

See Also: Studio::Bus::getVolume

Studio::Bus::stopAllEvents

Stops all event instances that are routed into the bus.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::stopAllEvents(
  FMOD_STUDIO_STOP_MODE mode
);
FMOD_RESULT FMOD_Studio_Bus_StopAllEvents(
  FMOD_STUDIO_BUS *bus,
  FMOD_STUDIO_STOP_MODE mode
);
RESULT Studio.Bus.stopAllEvents(
  STOP_MODE mode
);
Bus.stopAllEvents(
  mode
);
mode
Stop mode. (FMOD_STUDIO_STOP_MODE)

See Also: Studio::EventInstance::stop

Studio::Bus::unlockChannelGroup

Unlocks the core ChannelGroup.

C
C++
C#
JS

FMOD_RESULT Studio::Bus::unlockChannelGroup();
FMOD_RESULT FMOD_Studio_Bus_UnlockChannelGroup(FMOD_STUDIO_BUS *bus);
RESULT Studio.Bus.unlockChannelGroup();
Bus.unlockChannelGroup();

This function allows the system to destroy the ChannelGroup when it is not needed. See Signal Paths for details.

See Also: Studio::Bus::lockChannelGroup