Firelight Technologies FMOD Studio API
Studio::EventInstance::getChannelGroup
Retrieves the Low Level ChannelGroup for the event instance.
C++ Syntax
FMOD_RESULT Studio::EventInstance::getChannelGroup(
FMOD::ChannelGroup **group
);
C Syntax
FMOD_RESULT FMOD_Studio_EventInstance_GetChannelGroup(
FMOD_STUDIO_EVENTINSTANCE *eventinstance,
FMOD_CHANNELGROUP **group
);
C# Syntax
RESULT Studio.EventInstance.getChannelGroup(
out FMOD.ChannelGroup group
);
JavaScript Syntax
EventInstance.getChannelGroup(
group // writes value to group.val
);
Parameters
- group
- Address of a variable to receive the ChannelGroup.
Return Values
If the function succeeds then the return value is FMOD_OK.
If the function fails then the return value will be one of the values defined in the FMOD_RESULT enumeration.
Remarks
The retrieved ChannelGroup corresponds to the master track of the event instance.
It is not possible to get the ChannelGroup until the event instance has finished being created. When Studio has been initialized in asynchronous mode, this function will return FMOD_ERR_STUDIO_NOT_LOADED until the Studio::EventDescription::createInstance command has been executed in the async thread. When Studio has been initialized with FMOD_STUDIO_INIT_SYNCHRONOUS_UPDATE, the ChannelGroup will be available after the next Studio::System::update call.
To safely obtain the ChannelGroup, you can do one of the following:
- Call Studio::System::flushCommands to ensure the instance has finished being created.
- Set up callback to receive FMOD_STUDIO_EVENT_CALLBACK_CREATED and obtain the channelgroup there.
- Keep trying to obtain the channelgroup from the instance each frame until it succeeds.
- If running in synchronous mode, call Studio::System::update before you get the ChannelGroup.
Also note that the when the event instance is destroyed, the underlying ChannelGroup will become invalid. To make sure the ChannelGroup is remains valid, you can do one of the following:
- Do not call Studio::EventInstance::release until you have stopped accessing the ChannelGroup.
- After calling Studio::EventInstance::release, only access the ChannelGroup from within the event callbacks.
- If running in synchronous mode, the ChannelGroup will become invalid during Studio::System::update.
See Also
Version 1.10.03 Built on Feb 1, 2018