Skip to content

event_instance

Jump to bottom
Francisco Dias edited this page Feb 22, 2024 · 3 revisions

Event Instance

FMOD Object: Studio::EventInstance


This module holds functionality related to instances of an FMOD Studio Event.

Functions

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.


Back To Top

fmod_studio_event_instance_start

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



Back To Top

fmod_studio_event_instance_stop

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



Back To Top

fmod_studio_event_instance_get_playback_state

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_STUDIO_PLAYBACK_STATE



Back To Top

fmod_studio_event_instance_set_paused

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



Back To Top

fmod_studio_event_instance_get_paused

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:

Boolean



Back To Top

fmod_studio_event_instance_keyoff

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



Back To Top

fmod_studio_event_instance_set_pitch

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



Back To Top

fmod_studio_event_instance_get_pitch

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:

Real



Back To Top

fmod_studio_event_instance_set_property

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



Back To Top

fmod_studio_event_instance_get_property

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:

Real



Back To Top

fmod_studio_event_instance_set_timeline_position

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



Back To Top

fmod_studio_event_instance_get_timeline_position

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:

Real



Back To Top

fmod_studio_event_instance_set_volume

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



Back To Top

fmod_studio_event_instance_get_volume

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:

FmodStudioEventInstanceVolume



Back To Top

fmod_studio_event_instance_is_virtual

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:

Boolean



Back To Top

fmod_studio_event_instance_set_3d_attributes

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



Back To Top

fmod_studio_event_instance_get_3d_attributes

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:

Fmod3DAttributes



Back To Top

fmod_studio_event_instance_set_listener_mask

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



Back To Top

fmod_studio_event_instance_get_listener_mask

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:

Real



Back To Top

fmod_studio_event_instance_get_min_max_distance

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:

FmodMinMaxDistance



Back To Top

fmod_studio_event_instance_set_parameter_by_name

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



Back To Top

fmod_studio_event_instance_set_parameter_by_name_with_label

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



Back To Top

fmod_studio_event_instance_get_parameter_by_name

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:

FmodStudioParameter



Back To Top

fmod_studio_event_instance_set_parameter_by_id

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



Back To Top

fmod_studio_event_instance_set_parameter_by_id_with_label

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



Back To Top

fmod_studio_event_instance_get_parameter_by_id

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:

FmodStudioParameter



Back To Top

fmod_studio_event_instance_get_channel_group

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:

Real



Back To Top

fmod_studio_event_instance_set_reverb_level

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



Back To Top

fmod_studio_event_instance_get_reverb_level

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:

Real



Back To Top

fmod_studio_event_instance_get_cpu_usage

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:

FmodCPUUsage



Back To Top

fmod_studio_event_instance_get_memory_usage

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:

FmodStudioMemoryUsage



Back To Top

fmod_studio_event_instance_set_callback

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:

Social Async Event

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


Back To Top

fmod_studio_event_instance_set_user_data

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



Back To Top

fmod_studio_event_instance_get_user_data

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:

Real



Back To Top

fmod_studio_event_instance_get_description

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:

Real



Back To Top

fmod_studio_event_instance_release

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



Back To Top

fmod_studio_event_instance_is_valid

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:

Boolean



YoYoGames 2024

FMOD Extension

Guides

FMOD Core Reference

FMOD Studio Reference

Extras

Clone this wiki locally