event_description

Event Description

FMOD Object: Studio::EventDescription

This module holds functionality related to descriptions of FMOD Studio Events.

Event descriptions belong to banks and can be queried after the relevant bank has been loaded. Event descriptions may be retrieved via path or GUID lookup, or by enumerating all descriptions in a bank.

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.

• fmod_studio_event_description_create_instance
• fmod_studio_event_description_get_instance_count
• fmod_studio_event_description_get_instance_list
• fmod_studio_event_description_release_all_instances
• fmod_studio_event_description_load_sample_data
• fmod_studio_event_description_unload_sample_data
• fmod_studio_event_description_get_sample_loading_state
• fmod_studio_event_description_is_3d
• fmod_studio_event_description_is_doppler_enabled
• fmod_studio_event_description_is_oneshot
• fmod_studio_event_description_is_snapshot
• fmod_studio_event_description_is_stream
• fmod_studio_event_description_has_sustain_point
• fmod_studio_event_description_get_min_max_distance
• fmod_studio_event_description_get_sound_size
• fmod_studio_event_description_get_parameter_description_by_name
• fmod_studio_event_description_get_parameter_description_by_id
• fmod_studio_event_description_get_parameter_description_by_index
• fmod_studio_event_description_get_parameter_description_count
• fmod_studio_event_description_get_parameter_label_by_name
• fmod_studio_event_description_get_parameter_label_by_id
• fmod_studio_event_description_get_parameter_label_by_index
• fmod_studio_event_description_get_user_property
• fmod_studio_event_description_get_user_property_by_index
• fmod_studio_event_description_get_user_property_count
• fmod_studio_event_description_get_id
• fmod_studio_event_description_get_length
• fmod_studio_event_description_get_path
• fmod_studio_event_description_set_callback
• fmod_studio_event_description_set_user_data
• fmod_studio_event_description_get_user_data
• fmod_studio_event_description_is_valid

---

Back To Top

fmod_studio_event_description_create_instance

FMOD Function: Studio::EventDescription::createInstance

This function creates a playable instance, returning a handle to the new EventInstance object.

When an event instance is created, any required non-streaming sample data is loaded asynchronously.

Use fmod_studio_event_description_get_sample_loading_state to check the loading status.

Sample data can be loaded ahead of time with fmod_studio_event_description_load_sample_data or fmod_studio_bank_load_sample_data. See Sample Data Loading for more information.

Syntax:

fmod_studio_event_description_create_instance(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Real

---

Back To Top

fmod_studio_event_description_get_instance_count

FMOD Function: Studio::EventDescription::getInstanceCount

This function retrieves the number of instances in the EventDescription.

May be used in conjunction with fmod_studio_event_description_get_instance_list to enumerate the instances of this event.

Syntax:

fmod_studio_event_description_get_instance_count(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Real

---

Back To Top

fmod_studio_event_description_get_instance_list

FMOD Function: Studio::EventDescription::getInstanceList

This function retrieves an array containing the instances in the given EventDescription.

May be used in conjunction with fmod_studio_event_description_get_instance_count to enumerate the instances of this event.

Syntax:

fmod_studio_event_description_get_instance_list(event_descriptor_ref)

Argument	Type	Description
event_descriptor_ref	Real	A reference to an EventDescription.

Returns:

Array of Real

---

Back To Top

fmod_studio_event_description_release_all_instances

FMOD Function: Studio::EventDescription::releaseAllInstances

This function immediately stops and releases all instances of the event.

Syntax:

fmod_studio_event_description_release_all_instances(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

N/A

---

Back To Top

fmod_studio_event_description_load_sample_data

FMOD Function: Studio::EventDescription::loadSampleData

This function will load all non-streaming sample data required by the event and any referenced events.

Sample data is loaded asynchronously, fmod_studio_event_description_get_sample_loading_state may be used to poll the loading state.

Syntax:

fmod_studio_event_description_load_sample_data(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

N/A

---

Back To Top

fmod_studio_event_description_unload_sample_data

FMOD Function: Studio::EventDescription::unloadSampleData

This function unloads all non-streaming sample data.

Sample data will not be unloaded until all instances of the event are released.

Syntax:

fmod_studio_event_description_unload_sample_data(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

N/A

---

Back To Top

fmod_studio_event_description_get_sample_loading_state

FMOD Function: Studio::EventDescription::getSampleLoadingState

This function retrieves the sample data loading state.

If the event is invalid, then the state is set to FMOD_STUDIO_LOADING_STATE.UNLOADED and this results in FMOD_RESULT.ERR_INVALID_HANDLE (in the next fmod_last_result call).

Syntax:

fmod_studio_event_description_get_sample_loading_state(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

FMOD_STUDIO_LOADING_STATE

---

Back To Top

fmod_studio_event_description_is_3d

FMOD Function: Studio::EventDescription::is3D

This function retrieves the event's 3D status. For more info, see Studio::EventDescription::is3D.

This will return true if the event is 3D and false if not.

Syntax:

fmod_studio_event_description_is_3d(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Boolean

---

Back To Top

fmod_studio_event_description_is_doppler_enabled

FMOD Function: Studio::EventDescription::isDopplerEnabled

This function retrieves the event's doppler status.

This will return true if doppler is enabled, and false if not.

Note: If the event was built to a bank using versions of FMOD Studio prior to 2.01.09, then this function will return false regardless of the event's doppler state.

Syntax:

fmod_studio_event_description_is_doppler_enabled(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Boolean

---

Back To Top

fmod_studio_event_description_is_oneshot

FMOD Function: Studio::EventDescription::isOneshot

This function retrieves the event's oneshot status.

This will return true if the event is a oneshot event, and false if not.

An event is considered oneshot if it is guaranteed to terminate without intervention in bounded time after being started. Instances of such events can be played in a fire-and-forget fashion by calling fmod_studio_event_instance_start immediately followed by fmod_studio_event_instance_release.

Note: If the event contains nested events built to separate banks and those banks have not been loaded then this function may fail to correctly determine the event's oneshot status.

Syntax:

fmod_studio_event_description_is_oneshot(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Boolean

---

Back To Top

fmod_studio_event_description_is_snapshot

FMOD Function: Studio::EventDescription::isSnapshot

This function retrieves the event's snapshot status.

This will return true if the event is a snapshot and false if not.

Syntax:

fmod_studio_event_description_is_snapshot(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Boolean

---

Back To Top

fmod_studio_event_description_is_stream

FMOD Function: Studio::EventDescription::isStream

This function retrieves the event's stream status, returning true if the event contains one or more streamed sounds, otherwise false.

Note: If the event contains nested events built to separate banks and those banks have not been loaded then this function may fail to correctly determine the event's stream status.

Syntax:

fmod_studio_event_description_is_stream(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Boolean

---

Back To Top

fmod_studio_event_description_has_sustain_point

FMOD Function: Studio::EventDescription::hasSustainPoint

This function retrieves whether the event has any sustain points (true or false).

Syntax:

fmod_studio_event_description_has_sustain_point(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Boolean

---

Back To Top

fmod_studio_event_description_get_min_max_distance

FMOD Function: Studio::EventDescription::getMinMaxDistance

This function retrieves the minimum and maximum distances for 3D attenuation, as a struct.

Syntax:

fmod_studio_event_description_get_min_max_distance(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

FmodMinMaxDistance

---

Back To Top

fmod_studio_event_description_get_sound_size

FMOD Function: Studio::EventDescription::getSoundSize

This function retrieves the sound size for 3D panning.

Retrieves the largest Sound Size value of all Spatializers and 3D Object Spatializers on the event's master track. Returns 0 if there are no Spatializers or 3D Object Spatializers.

Syntax:

fmod_studio_event_description_get_sound_size(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Real

---

Back To Top

fmod_studio_event_description_get_parameter_description_by_name

FMOD Function: Studio::EventDescription::getParameterDescriptionByName

This function retrieves an event parameter description by name.

Syntax:

fmod_studio_event_description_get_parameter_description_by_name(event_descriptor_ref, name)

Argument	Type	Description
event_descriptor_ref	Real	A reference to an EventDescription.
name	String	Parameter name (case-insensitive, UTF-8 string).

Returns:

FmodStudioParameterDescription

---

Back To Top

fmod_studio_event_description_get_parameter_description_by_id

FMOD Function: Studio::EventDescription::getParameterDescriptionByID

This function retrieves an event parameter description by ID.

Syntax:

fmod_studio_event_description_get_parameter_description_by_id(event_descriptor_ref, parameter_id)

Argument	Type	Description
event_descriptor_ref	Real	A reference to an EventDescription.
parameter_id	FmodStudioParameterId	The parameter ID struct.

Returns:

FmodStudioParameterDescription

---

Back To Top

fmod_studio_event_description_get_parameter_description_by_index

FMOD Function: Studio::EventDescription::getParameterDescriptionByIndex

This function retrieves an event parameter description by index.

May be used in combination with fmod_studio_event_description_get_parameter_description_count to enumerate event parameters.

Syntax:

fmod_studio_event_description_get_parameter_description_by_index(event_descriptor_ref, parameter_index)

Argument	Type	Description
event_descriptor_ref	Real	A reference to an EventDescription.
parameter_index	Real	The parameter index.

Returns:

FmodStudioParameterDescription

---

Back To Top

fmod_studio_event_description_get_parameter_description_count

FMOD Function: Studio::EventDescription::getParameterDescriptionCount

This function retrieves the number of parameters in the event.

May be used in conjunction with fmod_studio_event_description_get_parameter_description_by_index to enumerate event parameters.

Syntax:

fmod_studio_event_description_get_parameter_description_count(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Real

---

Back To Top

fmod_studio_event_description_get_parameter_label_by_name

FMOD Function: Studio::EventDescription::getParameterLabelByName

This function retrieves an event parameter label by name or path.

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.

Syntax:

fmod_studio_event_description_get_parameter_label_by_name(event_description_ref, name, label_index)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.
name	String	Parameter name (UTF-8 string).
label_index	Real	Label index to retrieve.

Returns:

String

---

Back To Top

fmod_studio_event_description_get_parameter_label_by_id

FMOD Function: Studio::EventDescription::getParameterLabelByID

This function retrieves an event parameter label by ID.

Syntax:

fmod_studio_event_description_get_parameter_label_by_id(event_descriptor_ref, parameter_id, label_index)

Argument	Type	Description
event_descriptor_ref	Real	A reference to an EventDescription.
parameter_id	FmodStudioParameterId	The parameter ID struct.
label_index	Real	The label index to retrieve.

Returns:

String

---

Back To Top

fmod_studio_event_description_get_parameter_label_by_index

FMOD Function: Studio::EventDescription::getParameterLabelByIndex

This function retrieves an event parameter label by index.

May be used in combination with fmod_studio_event_description_get_parameter_description_count to enumerate event parameters.

Syntax:

fmod_studio_event_description_get_parameter_label_by_index(event_description_ref, index, label_index)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.
index	Real	The parameter index.
label_index	Real	The label index to retrieve.

Returns:

String

---

Back To Top

fmod_studio_event_description_get_user_property

FMOD Function: Studio::EventDescription::getUserProperty

This function retrieves a user property by name.

Syntax:

fmod_studio_event_description_get_user_property(event_description_ref, name)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.
name	String	The user property name (UTF-8 string).

Returns:

FmodStudioUserProperty

---

Back To Top

fmod_studio_event_description_get_user_property_by_index

FMOD Function: Studio::EventDescription::getUserPropertyByIndex

This function retrieves a user property by index.

May be used in combination with fmod_studio_event_description_get_user_property_count to enumerate event user properties.

Syntax:

fmod_studio_event_description_get_user_property_by_index(event_description_ref, index)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.
index	Real	The user property index.

Returns:

FmodStudioUserProperty

---

Back To Top

fmod_studio_event_description_get_user_property_count

FMOD Function: Studio::EventDescription::getUserPropertyCount

This function retrieves the number of user properties attached to the event.

May be used in combination with fmod_studio_event_description_get_user_property_by_index to enumerate event user properties.

Syntax:

fmod_studio_event_description_get_user_property_count(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Real

---

Back To Top

fmod_studio_event_description_get_id

FMOD Function: Studio::EventDescription::getID

This function retrieves the GUID of the EventDescription.

Syntax:

fmod_studio_event_description_get_id(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

String

---

Back To Top

fmod_studio_event_description_get_length

FMOD Function: Studio::EventDescription::getLength

This function retrieves the length of the timeline in milliseconds.

A timeline's length is the largest of any logic markers, transition leadouts and the end of any trigger boxes on the timeline.

Syntax:

fmod_studio_event_description_get_length(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Real

---

Back To Top

fmod_studio_event_description_get_path

FMOD Function: Studio::EventDescription::getPath

This function retrieves the path of the EventDescription.

The strings bank must be loaded prior to calling this function, otherwise FMOD_RESULT.ERR_EVENT_NOTFOUND is returned in the next call to fmod_last_result.

Syntax:

fmod_studio_event_description_get_path(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

String

---

Back To Top

fmod_studio_event_description_set_callback

FMOD Function: Studio::EventDescription::setCallback

This function enables a user callback which will be assigned to all event instances subsequently created from the event. The callback for individual instances can be set with fmod_studio_event_instance_set_callback.

This callback is triggered as an 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_description_set_callback(event_description_ref, type)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.
type	FMOD_STUDIO_EVENT_CALLBACK	The 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_description_set_user_data

FMOD Function: Studio::EventDescription::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_description_set_user_data(event_description_ref, data)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.
data	Real	The real value to attach.

Returns:

N/A

---

Back To Top

fmod_studio_event_description_get_user_data

FMOD Function: Studio::EventDescription::getUserData

This function retrieves the real value attached to the object in fmod_studio_event_description_set_user_data.

Returns NaN when no attached value is found.

Syntax:

fmod_studio_event_description_get_user_data(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Real

---

Back To Top

fmod_studio_event_description_is_valid

FMOD Function: Studio::EventDescription::isValid

This function checks that the EventDescription reference is valid.

Syntax:

fmod_studio_event_description_is_valid(event_description_ref)

Argument	Type	Description
event_description_ref	Real	A reference to an EventDescription.

Returns:

Boolean