FMOD Engine User Manual 2.03
The description for an FMOD Studio event.
Event descriptions belong to banks, and so an event description can only be queried if the relevant bank is loaded. Event descriptions may be retrieved via path or GUID lookup, or by enumerating all descriptions in a bank.
Instances:
Sample Data:
Attributes:
Parameters:
User Properties:
General:
See Also:
Creates a playable instance.
FMOD_RESULT Studio::EventDescription::createInstance(
Studio::EventInstance **instance
);
FMOD_RESULT FMOD_Studio_EventDescription_CreateInstance(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_STUDIO_EVENTINSTANCE **instance
);
RESULT Studio.EventDescription.createInstance(
out EventInstance instance
);
Studio.EventDescription.createInstance(
instance
);
When an event instance is created, any required non-streaming sample data is loaded asynchronously.
Use Studio::EventDescription::getSampleLoadingState to check the loading status.
Sample data can be loaded ahead of time with Studio::EventDescription::loadSampleData or Studio::Bank::loadSampleData. See Sample Data Loading for more information.
See Also: Studio::EventInstance::release
Retrieves the GUID associated with the event.
FMOD_RESULT Studio::EventDescription::getID(
FMOD_GUID *id
);
FMOD_RESULT FMOD_Studio_EventDescription_GetID(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_GUID *id
);
RESULT Studio.EventDescription.getID(
out Guid id
);
Studio.EventDescription.getID(
id
);
Retrieves the number of instances.
FMOD_RESULT Studio::EventDescription::getInstanceCount(
int *count
);
FMOD_RESULT FMOD_Studio_EventDescription_GetInstanceCount(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
int *count
);
RESULT Studio.EventDescription.getInstanceCount(
out int count
);
Studio.EventDescription.getInstanceCount(
count
);
May be used in conjunction with Studio::EventDescription::getInstanceList to enumerate the instances of this event.
Retrieves a list of the instances.
FMOD_RESULT Studio::EventDescription::getInstanceList(
Studio::EventInstance **array,
int capacity,
int *count
);
FMOD_RESULT FMOD_Studio_EventDescription_GetInstanceList(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_STUDIO_EVENTINSTANCE **array,
int capacity,
int *count
);
RESULT Studio.EventDescription.getInstanceList(
out EventInstance[] array
);
Studio.EventDescription.getInstanceList(
array,
capacity,
count
);
array
.array
.This function returns a maximum of capacity
instances. If more than capacity
instances have been created then additional instances will be silently ignored.
May be used in conjunction with Studio::EventDescription::getInstanceCount to enumerate the instances of this event.
Retrieves the length of the timeline.
FMOD_RESULT Studio::EventDescription::getLength(
int *length
);
FMOD_RESULT FMOD_Studio_EventDescription_GetLength(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
int *length
);
RESULT Studio.EventDescription.getLength(
out int length
);
Studio.EventDescription.getLength(
length
);
Timeline length.
A timeline's length is the largest of any logic markers, transition leadouts and the end of any trigger boxes on the timeline.
See Also: Studio::EventInstance::getTimelinePosition, Studio::EventInstance::setTimelinePosition
Retrieves the minimum and maximum distances for 3D attenuation.
FMOD_RESULT Studio::EventDescription::getMinMaxDistance(
float *min,
float *max
);
FMOD_RESULT FMOD_Studio_EventDescription_GetMinMaxDistance(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
float *min,
float *max
);
RESULT Studio.EventDescription.getMinMaxDistance(
out float min,
out float max
);
Studio.EventDescription.getMinMaxDistance(
min,
max
);
Minimum distance.
Maximum distance.
See Also: Studio::EventInstance::getMinMaxDistance
Retrieves an event parameter description by id.
FMOD_RESULT Studio::EventDescription::getParameterDescriptionByID(
FMOD_STUDIO_PARAMETER_ID id,
FMOD_STUDIO_PARAMETER_DESCRIPTION *parameter
);
FMOD_RESULT FMOD_Studio_EventDescription_GetParameterDescriptionByID(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_STUDIO_PARAMETER_ID id,
FMOD_STUDIO_PARAMETER_DESCRIPTION *parameter
);
RESULT Studio.EventDescription.getParameterDescriptionByID(
PARAMETER_ID id,
out PARAMETER_DESCRIPTION parameter
);
Studio.EventDescription.getParameterDescriptionByID(
id,
parameter
);
Retrieves an event parameter description by index.
FMOD_RESULT Studio::EventDescription::getParameterDescriptionByIndex(
int index,
FMOD_STUDIO_PARAMETER_DESCRIPTION *parameter
);
FMOD_RESULT FMOD_Studio_EventDescription_GetParameterDescriptionByIndex(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
int index,
FMOD_STUDIO_PARAMETER_DESCRIPTION *parameter
);
RESULT Studio.EventDescription.getParameterDescriptionByIndex(
int index,
out PARAMETER_DESCRIPTION parameter
);
Studio.EventDescription.getParameterDescriptionByIndex(
index,
parameter
);
May be used in combination with Studio::EventDescription::getParameterDescriptionCount to enumerate event parameters.
The order of parameters is not necessarily the same as what is shown in the FMOD Studio event editor.
Retrieves an event parameter description by name, including the path if needed.
FMOD_RESULT Studio::EventDescription::getParameterDescriptionByName(
const char *name,
FMOD_STUDIO_PARAMETER_DESCRIPTION *parameter
);
FMOD_RESULT FMOD_Studio_EventDescription_GetParameterDescriptionByName(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
const char *name,
FMOD_STUDIO_PARAMETER_DESCRIPTION *parameter
);
RESULT Studio.EventDescription.getParameterDescriptionByName(
string name,
out PARAMETER_DESCRIPTION parameter
);
Studio.EventDescription.getParameterDescriptionByName(
name,
parameter
);
Retrieves the number of parameters in the event.
FMOD_RESULT Studio::EventDescription::getParameterDescriptionCount(
int *count
);
FMOD_RESULT FMOD_Studio_EventDescription_GetParameterDescriptionCount(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
int *count
);
RESULT Studio.EventDescription.getParameterDescriptionCount(
out int count
);
Studio.EventDescription.getParameterDescriptionCount(
count
);
May be used in conjunction with Studio::EventDescription::getParameterDescriptionByIndex to enumerate event parameters.
Retrieves an event parameter label by ID.
FMOD_RESULT Studio::EventDescription::getParameterLabelByID(
FMOD_STUDIO_PARAMETER_ID id,
int labelindex,
char *label,
int size,
int *retrieved
);
FMOD_RESULT FMOD_Studio_EventDescription_GetParameterLabelByID(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_STUDIO_PARAMETER_ID id,
int labelindex,
char *label,
int size,
int *retrieved
);
RESULT Studio.EventDescription.getParameterLabelByID(
PARAMETER_ID id,
int labelindex,
out string label
);
Studio.EventDescription.getParameterLabelByID(
id,
labelindex,
label,
size,
retrieved
);
Label index to retrieve.
label
is null.If the label 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 label.
Retrieves an event parameter label by index.
FMOD_RESULT Studio::EventDescription::getParameterLabelByIndex(
int index,
int labelindex,
char *label,
int size,
int *retrieved
);
FMOD_RESULT FMOD_Studio_EventDescription_GetParameterLabelByIndex(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
int index,
int labelindex,
char *label,
int size,
int *retrieved
);
RESULT Studio.EventDescription.getParameterLabelByIndex(
int index,
int labelindex,
out string label
);
Studio.EventDescription.getParameterLabelByIndex(
index,
labelindex,
label,
size,
retrieved
);
Label index to retrieve.
label
is null.If the label 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 label.
May be used in combination with Studio::EventDescription::getParameterDescriptionCount to enumerate event parameters.
The order of parameters is not necessarily the same as what is shown in the FMOD Studio event editor.
Retrieves an event parameter label by name, including the path if needed.
FMOD_RESULT Studio::EventDescription::getParameterLabelByName(
const char *name,
int labelindex,
char *label,
int size,
int *retrieved
);
FMOD_RESULT FMOD_Studio_EventDescription_GetParameterLabelByName(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
const char *name,
int labelindex,
char *label,
int size,
int *retrieved
);
RESULT Studio.EventDescription.getParameterLabelByName(
string name,
int labelindex,
out string label
);
Studio.EventDescription.getParameterLabelByName(
name,
labelindex,
label,
size,
retrieved
);
Label index to retrieve.
label
is null.name
can be the short name (such as 'Wind') or the full path (such as 'parameter:/Ambience/Wind'). Path lookups only succeed if the strings bank has been loaded.
If the label 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 label.
Retrieves the path.
FMOD_RESULT Studio::EventDescription::getPath(
char *path,
int size,
int *retrieved
);
FMOD_RESULT FMOD_Studio_EventDescription_GetPath(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
char *path,
int size,
int *retrieved
);
RESULT Studio.EventDescription.getPath(
out string path
);
Studio.EventDescription.getPath(
path,
size,
retrieved
);
path
is null.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.
Retrieves the sample data loading state.
FMOD_RESULT Studio::EventDescription::getSampleLoadingState(
FMOD_STUDIO_LOADING_STATE *state
);
FMOD_RESULT FMOD_Studio_EventDescription_GetSampleLoadingState(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_STUDIO_LOADING_STATE *state
);
RESULT Studio.EventDescription.getSampleLoadingState(
out LOADING_STATE state
);
Studio.EventDescription.getSampleLoadingState(
state
);
If the event is invalid, then the state is set to FMOD_STUDIO_LOADING_STATE_UNLOADED and this function returns FMOD_ERR_INVALID_HANDLE.
See Also: Studio::EventDescription::loadSampleData, Studio::Bank::loadSampleData, Studio::EventDescription::createInstance, Sample Data Loading
Retrieves the sound size for 3D panning.
FMOD_RESULT Studio::EventDescription::getSoundSize(
float *size
);
FMOD_RESULT FMOD_Studio_EventDescription_GetSoundSize(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
float *size
);
RESULT Studio.EventDescription.getSoundSize(
out float size
);
Studio.EventDescription.getSoundSize(
size
);
Retrieves the largest Sound Size value of all Spatializers and 3D Object Spatializers on the event's master track. Returns zero if there are no Spatializers or 3D Object Spatializers.
See Also: Studio::EventDescription::is3D
Retrieves the event user data.
FMOD_RESULT Studio::EventDescription::getUserData(
void **userdata
);
FMOD_RESULT FMOD_Studio_EventDescription_GetUserData(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
void **userdata
);
RESULT Studio.EventDescription.getUserData(
out IntPtr userdata
);
Studio.EventDescription.getUserData(
userdata
);
This function allows arbitrary user data to be retrieved from this object. See the User Data section of the glossary for an example of how to get and set user data.
Retrieves a user property by name.
FMOD_RESULT Studio::EventDescription::getUserProperty(
const char *name,
FMOD_STUDIO_USER_PROPERTY *property
);
FMOD_RESULT FMOD_Studio_EventDescription_GetUserProperty(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
const char *name,
FMOD_STUDIO_USER_PROPERTY *property
);
RESULT Studio.EventDescription.getUserProperty(
string name,
out USER_PROPERTY property
);
Studio.EventDescription.getUserProperty(
name,
property
);
See Also: Studio::EventDescription::getUserPropertyCount, Studio::EventDescription::getUserPropertyByIndex
Retrieves a user property by index.
FMOD_RESULT Studio::EventDescription::getUserPropertyByIndex(
int index,
FMOD_STUDIO_USER_PROPERTY *property
);
FMOD_RESULT FMOD_Studio_EventDescription_GetUserPropertyByIndex(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
int index,
FMOD_STUDIO_USER_PROPERTY *property
);
RESULT Studio.EventDescription.getUserPropertyByIndex(
int index,
out USER_PROPERTY property
);
Studio.EventDescription.getUserPropertyByIndex(
index,
property
);
May be used in combination with Studio::EventDescription::getUserPropertyCount to enumerate event user properties.
See Also: Studio::EventDescription::getUserProperty
Retrieves the number of user properties attached to the event.
FMOD_RESULT Studio::EventDescription::getUserPropertyCount(
int *count
);
FMOD_RESULT FMOD_Studio_EventDescription_GetUserPropertyCount(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
int *count
);
RESULT Studio.EventDescription.getUserPropertyCount(
out int count
);
Studio.EventDescription.getUserPropertyCount(
count
);
May be used in combination with Studio::EventDescription::getUserPropertyByIndex to enumerate event user properties.
See Also: Studio::EventDescription::getUserProperty
Retrieves whether the event has any sustain points.
FMOD_RESULT Studio::EventDescription::hasSustainPoint(
bool *sustainPoint
);
FMOD_RESULT FMOD_Studio_EventDescription_HasSustainPoint(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_BOOL *sustainPoint
);
RESULT Studio.EventDescription.hasSustainPoint(
out bool sustainPoint
);
Studio.EventDescription.hasSustainPoint(
sustainPoint
);
Sustain point status. True if the event has one or more sustain points.
Retrieves the event's 3D status.
FMOD_RESULT Studio::EventDescription::is3D(
bool *is3d
);
FMOD_RESULT FMOD_Studio_EventDescription_Is3D(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_BOOL *is3d
);
RESULT Studio.EventDescription.is3D(
out bool is3d
);
Studio.EventDescription.is3D(
is3d
);
3D status. True if the event is 3D.
An event is considered 3D if any of these conditions are met:
If the event contains any nested event built to a different bank than the parent event using any version of FMOD Studio prior to 2.00.10, and any of the nested events' banks are not loaded, this function may fail to correctly determine the event's 3D status.
If an event contains a Scatterer, the event is considered 3D regardless of the contents of the Scatterer's playlist. This includes cases where the Scatterer instrument's playlist only contains 2D events.
Retrieves the event's doppler status.
FMOD_RESULT Studio::EventDescription::isDopplerEnabled(
bool *doppler
);
FMOD_RESULT FMOD_Studio_EventDescription_IsDopplerEnabled(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_BOOL *doppler
);
RESULT Studio.EventDescription.isDopplerEnabled(
out bool doppler
);
Studio.EventDescription.isDopplerEnabled(
doppler
);
Doppler status. True if doppler is enabled for the event.
Note: If the event is in a bank built using any version of FMOD Studio older than 2.01.09, this function returns false regardless of the event's doppler state.
Retrieves the event's oneshot status.
FMOD_RESULT Studio::EventDescription::isOneshot(
bool *oneshot
);
FMOD_RESULT FMOD_Studio_EventDescription_IsOneshot(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_BOOL *oneshot
);
RESULT Studio.EventDescription.isOneshot(
out bool oneshot
);
Studio.EventDescription.isOneshot(
oneshot
);
oneshot status. True if the event is a oneshot event.
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 Studio::EventInstance::start immediately followed by Studio::EventInstance::release.
If the event contains any nested event built to a different bank than the parent event, and any of the nested events' banks are not loaded, this function may fail to correctly determine the event's oneshot status.
Retrieves the event's snapshot status.
FMOD_RESULT Studio::EventDescription::isSnapshot(
bool *snapshot
);
FMOD_RESULT FMOD_Studio_EventDescription_IsSnapshot(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_BOOL *snapshot
);
RESULT Studio.EventDescription.isSnapshot(
out bool snapshot
);
Studio.EventDescription.isSnapshot(
snapshot
);
Snapshot status. True if the event is a snapshot.
Retrieves the event's stream status.
FMOD_RESULT Studio::EventDescription::isStream(
bool *isStream
);
FMOD_RESULT FMOD_Studio_EventDescription_IsStream(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_BOOL *isStream
);
RESULT Studio.EventDescription.isStream(
out bool isStream
);
Studio.EventDescription.isStream(
isStream
);
Stream status. True if the event contains one or more streamed sounds.
If the event contains any nested event built to a different bank than the parent event, and any of the nested events' banks are not loaded, this function may fail to correctly determine the event's stream status.
Checks that the EventDescription reference is valid.
bool Studio::EventDescription::isValid()
bool FMOD_Studio_EventDescription_IsValid(FMOD_STUDIO_EVENTDESCRIPTION *eventdescription)
bool Studio.EventDescription.isValid()
Studio.EventDescription.isValid()
Loads non-streaming sample data used by the event.
FMOD_RESULT Studio::EventDescription::loadSampleData();
FMOD_RESULT FMOD_Studio_EventDescription_LoadSampleData(FMOD_STUDIO_EVENTDESCRIPTION *eventdescription);
RESULT Studio.EventDescription.loadSampleData();
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, Studio::EventDescription::getSampleLoadingState may be used to poll the loading state.
See Also: Studio::EventDescription::unloadSampleData, Sample Data Loading
Releases all instances.
FMOD_RESULT Studio::EventDescription::releaseAllInstances();
FMOD_RESULT FMOD_Studio_EventDescription_ReleaseAllInstances(FMOD_STUDIO_EVENTDESCRIPTION *eventdescription);
RESULT Studio.EventDescription.releaseAllInstances();
Studio.EventDescription.releaseAllInstances();
This function immediately stops and releases all instances of the event.
See Also: Studio::EventInstance::release
Sets the user callback.
FMOD_RESULT Studio::EventDescription::setCallback(
FMOD_STUDIO_EVENT_CALLBACK callback,
FMOD_STUDIO_EVENT_CALLBACK_TYPE callbackmask = FMOD_STUDIO_EVENT_CALLBACK_ALL
);
FMOD_RESULT FMOD_Studio_EventDescription_SetCallback(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
FMOD_STUDIO_EVENT_CALLBACK callback,
FMOD_STUDIO_EVENT_CALLBACK_TYPE callbackmask
);
RESULT Studio.EventDescription.setCallback(
EVENT_CALLBACK callback,
EVENT_CALLBACK_TYPE callbackmask = EVENT_CALLBACK_TYPE.ALL
);
Studio.EventDescription.setCallback(
callback,
callbackmask
);
This function sets 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 Studio::EventInstance::setCallback.
See Event Callbacks for more information about when callbacks occur.
See Also: Callback Behavior
Sets the event user data.
FMOD_RESULT Studio::EventDescription::setUserData(
void *userdata
);
FMOD_RESULT FMOD_Studio_EventDescription_SetUserData(
FMOD_STUDIO_EVENTDESCRIPTION *eventdescription,
void *userdata
);
RESULT Studio.EventDescription.setUserData(
IntPtr userdata
);
Studio.EventDescription.setUserData(
userdata
);
This function allows arbitrary user data to be attached to this object. See the User Data section of the glossary for an example of how to get and set user data.
See Also: Studio::EventDescription::getUserData
Unloads all non-streaming sample data.
FMOD_RESULT Studio::EventDescription::unloadSampleData();
FMOD_RESULT FMOD_Studio_EventDescription_UnloadSampleData(FMOD_STUDIO_EVENTDESCRIPTION *eventdescription);
RESULT Studio.EventDescription.unloadSampleData();
Studio.EventDescription.unloadSampleData();
Sample data will not be unloaded until all instances of the event are released.
See Also: Studio::EventDescription::loadSampleData, Sample Data Loading
Describes a user property.
typedef struct FMOD_STUDIO_USER_PROPERTY {
const char *name;
FMOD_STUDIO_USER_PROPERTY_TYPE type;
union
{
int intvalue;
FMOD_BOOL boolvalue;
float floatvalue;
const char *stringvalue;
}
} FMOD_STUDIO_USER_PROPERTY;
struct USER_PROPERTY
{
StringWrapper name;
USER_PROPERTY_TYPE type;
int intvalue;
bool boolvalue;
float floatvalue;
string stringvalue;
}
FMOD_STUDIO_USER_PROPERTY
{
name,
type,
intvalue,
boolvalue,
floatvalue,
stringvalue,
};
Boolean value. Only valid when type is FMOD_STUDIO_USER_PROPERTY_TYPE_BOOLEAN.
See Also: Studio::EventDescription::getUserProperty
User property types.
typedef enum FMOD_STUDIO_USER_PROPERTY_TYPE {
FMOD_STUDIO_USER_PROPERTY_TYPE_INTEGER,
FMOD_STUDIO_USER_PROPERTY_TYPE_BOOLEAN,
FMOD_STUDIO_USER_PROPERTY_TYPE_FLOAT,
FMOD_STUDIO_USER_PROPERTY_TYPE_STRING
} FMOD_STUDIO_USER_PROPERTY_TYPE;
enum USER_PROPERTY_TYPE
{
INTEGER,
BOOLEAN,
FLOAT,
STRING,
}
STUDIO_USER_PROPERTY_TYPE_INTEGER
STUDIO_USER_PROPERTY_TYPE_BOOLEAN
STUDIO_USER_PROPERTY_TYPE_FLOAT
STUDIO_USER_PROPERTY_TYPE_STRING
See Also: FMOD_STUDIO_USER_PROPERTY