-
Notifications
You must be signed in to change notification settings - Fork 3
event_instance
FMOD Object: Studio::EventInstance
This module holds functionality related to instances of an FMOD Studio Event.
This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.
- fmod_studio_event_instance_start
- fmod_studio_event_instance_stop
- fmod_studio_event_instance_get_playback_state
- fmod_studio_event_instance_set_paused
- fmod_studio_event_instance_get_paused
- fmod_studio_event_instance_keyoff
- fmod_studio_event_instance_set_pitch
- fmod_studio_event_instance_get_pitch
- fmod_studio_event_instance_set_property
- fmod_studio_event_instance_get_property
- fmod_studio_event_instance_set_timeline_position
- fmod_studio_event_instance_get_timeline_position
- fmod_studio_event_instance_set_volume
- fmod_studio_event_instance_get_volume
- fmod_studio_event_instance_is_virtual
- fmod_studio_event_instance_set_3d_attributes
- fmod_studio_event_instance_get_3d_attributes
- fmod_studio_event_instance_set_listener_mask
- fmod_studio_event_instance_get_listener_mask
- fmod_studio_event_instance_get_min_max_distance
- fmod_studio_event_instance_set_parameter_by_name
- fmod_studio_event_instance_set_parameter_by_name_with_label
- fmod_studio_event_instance_get_parameter_by_name
- fmod_studio_event_instance_set_parameter_by_id
- fmod_studio_event_instance_set_parameter_by_id_with_label
- fmod_studio_event_instance_get_parameter_by_id
- fmod_studio_event_instance_get_channel_group
- fmod_studio_event_instance_set_reverb_level
- fmod_studio_event_instance_get_reverb_level
- fmod_studio_event_instance_get_cpu_usage
- fmod_studio_event_instance_get_memory_usage
- fmod_studio_event_instance_set_callback
- fmod_studio_event_instance_set_user_data
- fmod_studio_event_instance_get_user_data
- fmod_studio_event_instance_get_description
- fmod_studio_event_instance_release
- fmod_studio_event_instance_is_valid
FMOD Function: Studio::EventInstance::start
This function starts playback.
If the instance was already playing then calling this function will restart the event.
Generally it is a best practice to call fmod_studio_event_instance_release on event instances immediately after starting them, unless you want to play the event instance multiple times or explicitly stop it and start it again later.
Syntax:
fmod_studio_event_instance_start(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
N/A
FMOD Function: Studio::EventInstance::stop
This function stops playback.
Syntax:
fmod_studio_event_instance_stop(event_instance_ref, mode)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| mode | FMOD_STUDIO_STOP_MODE | The stop mode to use. |
Returns:
N/A
FMOD Function: Studio::EventInstance::getPlaybackState
This function retrieves the playback state of the EventInstance.
If the instance is invalid, this will return FMOD_STUDIO_PLAYBACK_STATE.STOPPED.
Syntax:
fmod_studio_event_instance_get_playback_state(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::setPaused
This function sets the pause state of the EventInstance.
Syntax:
fmod_studio_event_instance_set_paused(event_instance_ref, pause)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| pause | Real |
true to pause, false to unpause |
Returns:
N/A
FMOD Function: Studio::EventInstance::getPaused
This function returns the pause state of the EventInstance (true if paused, otherwise false).
Syntax:
fmod_studio_event_instance_get_paused(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::keyOff
This function allows an event to continue past a sustain point.
Multiple sustain points may be bypassed ahead of time and the key off count will be decremented each time the timeline cursor passes a sustain point.
This results in FMOD_RESULT.ERR_EVENT_NOTFOUND (in the next call to fmod_last_result) if the event has no sustain points.
Syntax:
fmod_studio_event_instance_keyoff(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
N/A
FMOD Function: Studio::EventInstance::setPitch
This function sets the pitch multiplier.
The pitch multiplier is used to modulate the event instance's pitch. The pitch multiplier can be set to any value greater than or equal to zero but the final combined pitch is clamped to the range [0, 100] before being applied.
Syntax:
fmod_studio_event_instance_set_pitch(event_instance_ref, pitch)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| pitch | Real | Pitch multiplier, range: (0, inf), default: 1 |
Returns:
N/A
FMOD Function: Studio::EventInstance::getPitch
This function retrieves the pitch multiplier assigned to the EventInstance.
Syntax:
fmod_studio_event_instance_get_pitch(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::setProperty
This function sets the value of a built-in property.
This will override the value set in Studio. Using the default FMOD_STUDIO_EVENT_PROPERTY value (e.g. -1) will revert back to the default values set in Studio.
An FMOD spatializer or object spatializer may override the values set for FMOD_STUDIO_EVENT_PROPERTY.MINIMUM_DISTANCE and FMOD_STUDIO_EVENT_PROPERTY.MAXIMUM_DISTANCE.
Syntax:
fmod_studio_event_instance_set_property(event_instance_ref, property, value)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| property | FMOD_STUDIO_EVENT_PROPERTY | Property type to set. |
| value | Real | Property value to set. |
Returns:
N/A
FMOD Function: Studio::EventInstance::getProperty
This function retrieves the value of a built-in property.
A default FMOD_STUDIO_EVENT_PROPERTY value means that the Instance is using the value set in Studio and it has not been overridden using fmod_studio_event_instance_set_property.
Syntax:
fmod_studio_event_instance_get_property(event_instance_ref, property)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| property | FMOD_STUDIO_EVENT_PROPERTY | Property type to get the value of. |
Returns:
FMOD Function: Studio::EventInstance::setTimelinePosition
This function sets the timeline cursor position.
Syntax:
fmod_studio_event_instance_set_timeline_position(event_instance_ref, position)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| position | Real | The timeline position in milliseconds. |
Returns:
N/A
FMOD Function: Studio::EventInstance::getTimelinePosition
This function retrieves the timeline cursor position.
Syntax:
fmod_studio_event_instance_get_timeline_position(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::setVolume
This function sets the volume level.
This volume is applied as a scaling factor for the event volume. It does not override the volume level set in FMOD Studio, nor any internal volume automation or modulation.
Syntax:
fmod_studio_event_instance_set_volume(event_instance_ref, volume)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| volume | Real | Volume, Range: (0, inf), Default: 1 |
Returns:
N/A
FMOD Function: Studio::EventInstance::getVolume
This function retrieves the volume level.
Syntax:
fmod_studio_event_instance_get_volume(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::isVirtual
This function checks whether an event instance has been virtualized due to the polyphony limit being exceeded (true or false).
Syntax:
fmod_studio_event_instance_is_virtual(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::set3DAttributes
This function sets the 3D attributes for the given EventInstance.
An event's 3D attributes specify its position, velocity and orientation. The 3D attributes are used to calculate 3D panning, doppler and the values of automatic distance and angle parameters.
Syntax:
fmod_studio_event_instance_set_3d_attributes(event_instance_ref, attributes)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| attributes | Fmod3DAttributes | The 3D attributes struct. |
Returns:
N/A
FMOD Function: Studio::EventInstance::get3DAttributes
This function retrieves the 3D attributes struct for the given EventInstance.
Syntax:
fmod_studio_event_instance_get_3d_attributes(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::setListenerMask
This function sets the listener mask.
The listener mask controls which listeners are considered when calculating 3D panning and the values of listener relative automatic parameters.
To create the mask you must perform bitwise OR and shift operations, the basic form is 1 << listener_index OR'd together with other required listener indices.
For example to create a mask for listener index 0 and 2 the calculation would be mask = (1 << 0) | (1 << 2), to include all listeners use the default mask of 0xFFFFFFFF.
Syntax:
fmod_studio_event_instance_set_listener_mask(event_instance_ref, mask)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| mask | Real | Listener mask (default: 0xFFFFFFFF) |
Returns:
N/A
FMOD Function: Studio::EventInstance::getListenerMask
This function retrieves the listener mask.
Syntax:
fmod_studio_event_instance_get_listener_mask(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::getMinMaxDistance
This function retrieves the minimum and maximum distances for 3D attenuation as an FmodMinMaxDistance struct.
Syntax:
fmod_studio_event_instance_get_min_max_distance(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::setParameterByName
This function sets a parameter value by name.
The value will be set instantly regardless of ignoreseekspeed when the Event playback state is FMOD_STUDIO_PLAYBACK_STATE.STOPPED.
If the specified parameter is read only, is an automatic parameter or is not of type FMOD_STUDIO_PARAMETER_TYPE.GAME_CONTROLLED then FMOD_RESULT.ERR_INVALID_PARAM is returned in the next fmod_last_result call.
If the event has no parameter matching name then FMOD_RESULT.ERR_EVENT_NOTFOUND is returned in the next fmod_last_result call.
Syntax:
fmod_studio_event_instance_set_parameter_by_name(event_instance_ref, name, value, ignore_seek_speed=false)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| name | String | Parameter name (case-insensitive, UTF-8 string). |
| value | Real | Value for given name. |
| ignore_seek_speed | Boolean | Whether to ignore the parameter's seek speed and set the value immediately. |
Returns:
N/A
FMOD Function: Studio::EventInstance::setParameterByNameWithLabel
This function sets a parameter value by name, looking up the value label.
The value will be set instantly regardless of ignoreseekspeed when the Event playback state is FMOD_STUDIO_PLAYBACK_STATE.STOPPED.
If the specified parameter is read only, is an automatic parameter or is not of type FMOD_STUDIO_PARAMETER_TYPE.GAME_CONTROLLED then FMOD_RESULT.ERR_INVALID_PARAM is returned in the next fmod_last_result call.
If the event has no parameter matching name then FMOD_RESULT.ERR_EVENT_NOTFOUND is returned in the next fmod_last_result call.
If the specified label is not found, FMOD_RESULT.ERR_EVENT_NOTFOUND is returned in the next fmod_last_result call. This lookup is case sensitive.
Syntax:
fmod_studio_event_instance_set_parameter_by_name_with_label(event_instance_ref, name, label, ignore_seek_speed=false)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| name | String | Parameter name (case-insensitive, UTF-8 string). |
| label | String | Labeled value for the given name. |
| ignore_seek_speed | Boolean | Whether to ignore the parameter's seek speed and set the value immediately. |
Returns:
N/A
FMOD Function: Studio::EventInstance::getParameterByName
This function retrieves a parameter value by name.
Syntax:
fmod_studio_event_instance_get_parameter_by_name(event_instance_ref, name)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| name | String | Parameter name (case-insensitive, UTF-8 string). |
Returns:
FMOD Function: Studio::EventInstance::setParameterByID
This function sets a parameter value by unique identifier.
The value will be set instantly regardless of ignoreseekspeed when the Event playback state is FMOD_STUDIO_PLAYBACK_STATE.STOPPED.
If the specified parameter is read only, is an automatic parameter or is not of type FMOD_STUDIO_PARAMETER_TYPE.GAME_CONTROLLED then FMOD_RESULT.ERR_INVALID_PARAM is returned in the next fmod_last_result call.
Syntax:
fmod_studio_event_instance_set_parameter_by_id(event_instance_ref, parameter_id, value, ignore_seek_speed=false)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| parameter_id | FmodStudioParameterId | Parameter identifier. |
| value | Real | Value for given identifier. |
| ignore_seek_speed | Boolean | Whether to ignore the parameter's seek speed and set the value immediately. |
Returns:
N/A
FMOD Function: Studio::EventInstance::setParameterByIDWithLabel
This function sets a parameter value by unique identifier, looking up the value label.
The value will be set instantly regardless of ignoreseekspeed when the Event playback state is FMOD_STUDIO_PLAYBACK_STATE.STOPPED.
If the specified parameter is read only, is an automatic parameter or is not of type FMOD_STUDIO_PARAMETER_TYPE.GAME_CONTROLLED then FMOD_RESULT.ERR_INVALID_PARAM is returned in the next fmod_last_result call.
If the specified label is not found, FMOD_RESULT.ERR_EVENT_NOTFOUND is returned in the next fmod_last_result call. This lookup is case sensitive.
Syntax:
fmod_studio_event_instance_set_parameter_by_id_with_label(event_instance_ref, parameter_id, label, ignore_seek_speed=false)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| parameter_id | FmodStudioParameterId | Parameter identifier. |
| label | String | Labeled value for given name. |
| ignore_seek_speed | Boolean | Whether to ignore the parameter's seek speed and set the value immediately. |
Returns:
N/A
FMOD Function: Studio::EventInstance::getParameterByID
This function retrieves a parameter value by unique identifier.
Syntax:
fmod_studio_event_instance_get_parameter_by_id(event_instance_ref, parameter_id)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| parameter_id | FmodStudioParameterId | The parameter identifier. |
Returns:
FMOD Function: Studio::EventInstance::getChannelGroup
This function retrieves the core ChannelGroup corresponding to the master track.
Until the event instance has been fully created this function will result in FMOD_RESULT.ERR_STUDIO_NOT_LOADED (in the next fmod_last_result call).
Syntax:
fmod_studio_event_instance_get_channel_group(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::setReverbLevel
This function sets the core reverb send level.
This controls the send level for the signal from the event instance to a core reverb instance.
Syntax:
fmod_studio_event_instance_set_reverb_level(event_instance_ref, index, level)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| index | Real | Core reverb instance index, Range: [0, 3] |
| level | Real | Reverb send level, Linear, Range: [0, 1], Default: 0| |
Returns:
N/A
FMOD Function: Studio::EventInstance::getReverbLevel
This function retrieves the core reverb send level.
Syntax:
fmod_studio_event_instance_get_reverb_level(event_instance_ref, index)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| index | Real | Core reverb instance index, Range: [0, 3] |
Returns:
FMOD Function: Studio::EventInstance::getCPUUsage
This function retrieves the event CPU usage data.
FMOD_INIT.PROFILE_ENABLE with fmod_system_init is required to call this function.
Syntax:
fmod_studio_event_instance_get_cpu_usage(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::getMemoryUsage
This function retrieves memory usage statistics.
Memory usage statistics are only available in logging builds, in release builds the struct will contain zero for all values.
Syntax:
fmod_studio_event_instance_get_memory_usage(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::setCallback
This function enables the user callback in the Async Social event.
This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.
Syntax:
fmod_studio_event_instance_set_callback(event_instance_ref, type)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| type | FMOD_STUDIO_EVENT_CALLBACK | Bitfield specifying which callback types are required. |
Returns:
N/A
Triggers:
| Key | Type | Description |
|---|---|---|
| type | String | The value "fmod_studio_event_description_set_callback"
|
| kind | FMOD_STUDIO_EVENT_CALLBACK | The callback type passed into the original function. |
| event_instance_ref | Real | Handle of the EventInstance that has changed state. |
| name | String | Valid when kind=FMOD_STUDIO_EVENT_CALLBACK.CREATE_PROGRAMMER_SOUND or FMOD_STUDIO_EVENT_CALLBACK.DESTROY_PROGRAMMER_SOUND or FMOD_STUDIO_EVENT_CALLBACK.TIMELINE_MARKER
|
| sub_sound_index | Real | Valid when kind=FMOD_STUDIO_EVENT_CALLBACK.CREATE_PROGRAMMER_SOUND or FMOD_STUDIO_EVENT_CALLBACK.DESTROY_PROGRAMMER_SOUND
|
| sound_ref | Real | Valid when kind=FMOD_STUDIO_EVENT_CALLBACK.CREATE_PROGRAMMER_SOUND or FMOD_STUDIO_EVENT_CALLBACK.DESTROY_PROGRAMMER_SOUND
|
| position | Real | Valid when kind=FMOD_STUDIO_EVENT_CALLBACK.TIMELINE_MARKER or FMOD_STUDIO_EVENT_CALLBACK.TIMELINE_BEAT or FMOD_STUDIO_EVENT_CALLBACK.NESTED_TIMELINE_BEAT
|
| bar | Real | Valid when kind=FMOD_STUDIO_EVENT.CALLBACK_TIMELINE_BEAT or FMOD_STUDIO_EVENT_CALLBACK.NESTED_TIMELINE_BEAT
|
| beat | Real | Valid when kind=FMOD_STUDIO_EVENT.CALLBACK_TIMELINE_BEAT or FMOD_STUDIO_EVENT_CALLBACK.NESTED_TIMELINE_BEAT
|
| tempo | Real | Valid when kind=FMOD_STUDIO_EVENT.CALLBACK_TIMELINE_BEAT or FMOD_STUDIO_EVENT_CALLBACK.NESTED_TIMELINE_BEAT
|
| time_signature_lower | Real | Valid when kind=FMOD_STUDIO_EVENT.CALLBACK_TIMELINE_BEAT or FMOD_STUDIO_EVENT_CALLBACK.NESTED_TIMELINE_BEAT
|
| time_signature_upper | Real | Valid when kind=FMOD_STUDIO_EVENT.CALLBACK_TIMELINE_BEAT or FMOD_STUDIO_EVENT_CALLBACK.NESTED_TIMELINE_BEAT
|
| event_id | Real | Valid when kind=FMOD_STUDIO_EVENT_CALLBACK.NESTED_TIMELINE_BEAT
|
FMOD Function: Studio::EventInstance::setUserData
This allows a real value to be attached to this object. See User Data for an example of how to get and set user data.
Syntax:
fmod_studio_event_instance_set_user_data(event_instance_ref, data)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
| data | Real | The real value to attach. |
Returns:
N/A
FMOD Function: Studio::EventInstance::getUserData
This function retrieves the real value attached to this object in fmod_studio_event_instance_set_user_data.
Returns NaN if no attached user data is found.
Syntax:
fmod_studio_event_instance_get_user_data(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::getDescription
This function retrieves a handle to the EventDescription for the given EventInstance.
Syntax:
fmod_studio_event_instance_get_description(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
FMOD Function: Studio::EventInstance::release
This function marks the event instance to be released. Event instances marked for release are destroyed by the asynchronous update when they are in the stopped state (FMOD_STUDIO_PLAYBACK_STATE.STOPPED).
Generally it is a best practice to release event instances immediately after calling fmod_studio_event_instance_start, unless you want to play the event instance multiple times or explicitly stop it and start it again later. It is possible to interact with the instance after calling release(), however if the sound has stopped FMOD_RESULT.ERR_INVALID_HANDLE will be returned in the next fmod_last_result call.
Syntax:
fmod_studio_event_instance_release(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
N/A
FMOD Function: Studio::EventInstance::isValid
This function checks whether the EventInstance reference is valid (true) or not (false).
Syntax:
fmod_studio_event_instance_is_valid(event_instance_ref)
| Argument | Type | Description |
|---|---|---|
| event_instance_ref | Real | A reference to an EventInstance. |
Returns:
YoYoGames 2024