Struct EventInstance

pub struct EventInstance { /* private fields */ }

Available on crate feature studio only.

An instance of an FMOD Studio event.

Implementations

impl EventInstance

pub fn set_3d_attributes(&self, attributes: Attributes3D) -> Result<()>

Sets the 3D attributes.

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.

pub fn get_3d_attributes(&self) -> Result<Attributes3D>

Retrieves the 3D attributes.

pub fn set_listener_mask(&self, mask: c_uint) -> Result<()>

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.

pub fn get_listener_mask(&self) -> Result<c_uint>

Retrieves the listener mask.

pub fn get_min_max_distance(&self) -> Result<(c_float, c_float)>

Retrieves the minimum and maximum distances for 3D attenuation.

impl EventInstance

pub fn set_userdata(&self, userdata: *mut c_void) -> Result<()>

Sets the event instance user data.

pub fn get_userdata(&self) -> Result<*mut c_void>

Retrieves the event instance user data.

pub fn set_callback<C: EventInstanceCallback>( &self, mask: EventCallbackMask, ) -> Result<()>

Sets the user callback.

impl EventInstance

pub fn get_channel_group(&self) -> Result<ChannelGroup>

Retrieves the core ChannelGroup.

Until the event instance has been fully created this function will return FMOD_RESULT::FMOD_ERR_STUDIO_NOT_LOADED.

pub fn set_reverb_level(&self, index: c_int, level: c_float) -> Result<()>

Sets the core reverb send level.

This function controls the send level for the signal from the event instance to a core reverb instance.

pub fn get_reverb_level(&self, index: c_int) -> Result<c_float>

Retrieves the core reverb send level.

impl EventInstance

pub fn get_description(&self) -> Result<EventDescription>

Retrieves the event description.

pub fn release(&self) -> Result<()>

Marks the event instance for 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 (PlaybackState::Stopped).

Generally it is a best practice to release event instances immediately after calling EventInstance::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 falling EventInstance::release, however if the sound has stopped FMOD_RESULT::FMOD_ERR_INVALID_HANDLE will be returned.

pub fn is_valid(&self) -> bool

Checks that the EventInstance reference is valid.

pub fn get_system(&self) -> Result<System>

Available on fmod_2_3 only.

Retrieves the FMOD Studio System.

impl EventInstance

pub fn set_parameter_by_name( &self, name: &Utf8CStr, value: c_float, ignore_seek_speed: bool, ) -> Result<()>

Sets a parameter value by name.

The value will be set instantly regardless of ignore_seek_speed when the Event playback state is PlaybackState::Stopped.

If the specified parameter is read only, is an automatic parameter or is not of type ParameterKind::GameControlled then FMOD_RESULT::FMOD_ERR_INVALID_PARAM is returned.

If the event has no parameter matching name then FMOD_RESULT::FMOD_ERR_EVENT_NOTFOUND is returned.

pub fn set_parameter_by_name_with_label( &self, name: &Utf8CStr, label: &Utf8CStr, ignore_seek_speed: bool, ) -> Result<()>

Sets a parameter value by name, looking up the value label.

The label will be set instantly regardless of ignore_seek_speed when the Event playback state is PlaybackState::Stopped.

If the specified parameter is read only, is an automatic parameter or is not of type ParameterKind::GameControlled then FMOD_RESULT::FMOD_ERR_INVALID_PARAM is returned.

If the event has no parameter matching name then FMOD_RESULT::FMOD_ERR_EVENT_NOTFOUND is returned.

If the specified label is not found, FMOD_RESULT::FMOD_ERR_EVENT_NOTFOUND is returned. This lookup is case sensitive.

pub fn get_parameter_by_name( &self, name: &Utf8CStr, ) -> Result<(c_float, c_float)>

Retrieves a parameter value by name.

Automatic parameters always return value as 0 since they can never have their value set from the public API.

The second returned tuple field is the final value of the parameter after applying adjustments due to automation, modulation, seek speed, and parameter velocity to value. This is calculated asynchronously when the Studio system updates.

pub fn set_parameter_by_id( &self, id: ParameterID, value: c_float, ignore_seek_speed: bool, ) -> Result<()>

Sets a parameter value by unique identifier.

The value will be set instantly regardless of ignore_seek_speed when the Event playback state is PlaybackState::Stopped.

If the specified parameter is read only, is an automatic parameter or is not of type ParameterKind::GameControlled then FMOD_RESULT::FMOD_ERR_INVALID_PARAM is returned.

pub fn set_parameter_by_id_with_label( &self, id: ParameterID, label: &Utf8CStr, ignore_seek_speed: bool, ) -> Result<()>

Sets a parameter value by unique identifier, looking up the value label.

The label will be set instantly regardless of ignore_seek_speed when the Event playback state is PlaybackState::Stopped.

If the specified parameter is read only, is an automatic parameter or is not of type ParameterKind::GameControlled then FMOD_RESULT::FMOD_ERR_INVALID_PARAM is returned.

If the specified label is not found, FMOD_RESULT::FMOD_ERR_EVENT_NOTFOUND is returned. This lookup is case sensitive.

pub fn get_parameter_by_id(&self, id: ParameterID) -> Result<(c_float, c_float)>

Retrieves a parameter value by unique identifier.

Automatic parameters always return value as 0 since they can never have their value set from the public API.

The second returned tuple field is the final value of the parameter after applying adjustments due to automation, modulation, seek speed, and parameter velocity to value. This is calculated asynchronously when the Studio system updates.

pub fn set_parameters_by_ids( &self, ids: &[ParameterID], values: &mut [c_float], ignore_seek_speed: bool, ) -> Result<()>

Sets multiple parameter values by unique identifier.

All values will be set instantly regardless of ingore_seek_speed when the Event playback state is PlaybackState::Stopped.

If any ID is set to all zeroes then the corresponding value will be ignored.

Panics

This function will panic if ids.len() != values.len().

impl EventInstance

pub fn start(&self) -> Result<()>

Starts playback.

If the instance was already playing then calling this function will restart the event.

Generally it is a best practice to call EventInstance::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.

pub fn stop(&self, mode: StopMode) -> Result<()>

Stops playback.

pub fn get_playback_state(&self) -> Result<PlaybackState>

Retrieves the playback state.

You can poll this function to track the playback state of an event instance.

If the instance is invalid, then the state will be set to PlaybackState::Stopped.

pub fn set_paused(&self, paused: bool) -> Result<()>

Sets the pause state.

This function allows pausing/unpausing of an event instance.

pub fn get_paused(&self) -> Result<bool>

Retrieves the paused state.

pub fn key_off(&self) -> Result<()>

Allow 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 function returns FMOD_RESULT::FMOD_ERR_EVENT_NOTFOUND if the event has no sustain points.

impl EventInstance

pub fn set_pitch(&self, pitch: c_float) -> Result<()>

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.

pub fn get_pitch(&self) -> Result<(c_float, c_float)>

Retrieves the pitch multiplier.

The final combined value returned in second tuple field combines the pitch set using EventInstance::set_pitch with the result of any automation or modulation. The final combined pitch is calculated asynchronously when the Studio system updates.

pub fn set_property( &self, property: EventProperty, value: c_float, ) -> Result<()>

Sets the value of a built-in property.

This will override the value set in Studio. Using the default EventProperty value will revert back to the default values set in Studio.

An FMOD spatializer or object spatializer may override the values set for EventProperty::MinimumDistance and EventProperty::MaximumDistance].

pub fn get_property(&self, property: EventProperty) -> Result<c_float>

Retrieves the value of a built-in property.

A default EventProperty value means that the Instance is using the value set in Studio and it has not been overridden using EventInstance::set_property. Access the default property values through the EventDescription.

pub fn set_timeline_position(&self, position: c_int) -> Result<()>

Sets the timeline cursor position.

pub fn get_timeline_position(&self) -> Result<c_int>

Retrieves the timeline cursor position.

pub fn set_volume(&self, volume: c_float) -> Result<()>

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.

pub fn get_volume(&self) -> Result<(c_float, c_float)>

Retrieves the volume level.

The value returned in the second tuple field combines the volume set using the public API with the result of any automation or modulation. The final combined volume is calculated asynchronously when the Studio system updates.

pub fn is_virtual(&self) -> Result<bool>

Retrieves the virtualization state.

This function checks whether an event instance has been virtualized due to the polyphony limit being exceeded.

impl EventInstance

pub fn get_cpu_usage(&self) -> Result<(c_uint, c_uint)>

Retrieves the event CPU usage data.

crate::InitFlags::PROFILE_ENABLE with crate::SystemBuilder::build is required to call this function.

pub fn get_memory_usage(&self) -> Result<MemoryUsage>

Retrieves memory usage statistics.

Memory usage statistics are only available in logging builds, in release builds the return value will contain zero for all values this function.

impl EventInstance

pub unsafe fn from_ffi(value: *mut FMOD_STUDIO_EVENTINSTANCE) -> Self

Safety

value must be a valid pointer either aquired from Self::as_ptr or FMOD.

Panics

Panics if value is null.

pub fn as_ptr(self) -> *mut FMOD_STUDIO_EVENTINSTANCE

Converts self into its raw representation.

Trait Implementations

impl Clone for EventInstance

fn clone(&self) -> EventInstance

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EventInstance

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<EventInstance> for *mut FMOD_STUDIO_EVENTINSTANCE

fn from(value: EventInstance) -> Self

Converts to this type from the input type.

impl Hash for EventInstance

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for EventInstance

fn eq(&self, other: &EventInstance) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for EventInstance

impl Eq for EventInstance

impl Send for EventInstance

Available on non-crate feature thread-unsafe only.

impl StructuralPartialEq for EventInstance

impl Sync for EventInstance

Available on non-crate feature thread-unsafe only.