Struct Sound

Source

pub struct Sound { /* private fields */ }

Implementations§

Source §

impl Sound

Source

pub fn get_open_state(&self) -> Result<(OpenState, c_uint, bool, bool)>

Retrieves the state a sound is in after being opened with the non blocking flag, or the current state of the streaming buffer.

When a sound is opened with FMOD_NONBLOCKING, it is opened and prepared in the background, or asynchronously. This allows the main application to execute without stalling on audio loads. This function will describe the state of the asynchronous load routine i.e. whether it has succeeded, failed or is still in progress.

If ‘starving’ is true, then you will most likely hear a stuttering/repeating sound as the decode buffer loops on itself and replays old data. With the ability to detect stream starvation, muting the sound with ChannelControl::setMute will keep the stream quiet until it is not starving any more.

§Note: Always check `OpenState` to determine the state of the sound.

Do not assume that if this function returns Ok then the sound has finished loading.

Source §

impl Sound

Source

pub fn set_3d_cone_settings( &self, inside_angle: c_float, outside_angle: c_float, outside_volume: c_float, ) -> Result<()>

Sets the angles and attenuation levels of a 3D cone shape, for simulated occlusion which is based on direction.

When ChannelControl::set3DConeOrientation is used and a 3D ‘cone’ is set up, attenuation will automatically occur for a sound based on the relative angle of the direction the cone is facing, vs the angle between the sound and the listener.

If the relative angle is within the inside_angle, the sound will not have any attenuation applied.
If the relative angle is between the inside_angle and outside_angle, linear volume attenuation (between 1 and outside_volume) is applied between the two angles until it reaches the outside_angle.
If the relative angle is outside of the outside_angle the volume does not attenuate any further.

Source

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

Retrieves the inside and outside angles of the 3D projection cone and the outside volume.

Source

pub unsafe fn set_3d_custom_rolloff(&self, points: &mut [Vector]) -> Result<()>

Sets a custom roll-off shape for 3D distance attenuation.

Must be used in conjunction with [Mode::CUSTOM_ROLLOFF] flag to be activated.

If [Mode::CUSTOM_ROLLOFF] is set and the roll-off shape is not set, FMOD will revert to [Mode::INVERSE_ROLLOFF] roll-off mode.

When a custom roll-off is specified a [Channel] or [ChannelGroup]’s 3D ‘minimum’ and ‘maximum’ distances are ignored.

The distance in-between point values is linearly interpolated until the final point where the last value is held.

If the points are not sorted by distance, an error will result.

§Safety

This function does not duplicate the memory for the points internally. The memory you pass to FMOD must remain valid while in use.

Source

pub fn get_3d_custom_rolloff(&self) -> Result<Vec<Vector>>

Retrieves the current custom roll-off shape for 3D distance attenuation.

Source

pub fn set_3d_min_max_distance(&self, min: c_float, max: c_float) -> Result<()>

Sets the minimum and maximum audible distance for a 3D sound.

The distances are meant to simulate the ‘size’ of a sound. Reducing the min distance will mean the sound appears smaller in the world, and in some modes makes the volume attenuate faster as the listener moves away from the sound. Increasing the min distance simulates a larger sound in the world, and in some modes makes the volume attenuate slower as the listener moves away from the sound.

max will affect attenuation differently based on roll-off mode set in the mode parameter of System::createSound, System::createStream, Sound::setMode or ChannelControl::setMode.

For these modes the volume will attenuate to 0 volume (silence), when the distance from the sound is equal to or further than the max distance:

FMOD_3D_LINEARROLLOFF
FMOD_3D_LINEARSQUAREROLLOFF

For these modes the volume will stop attenuating at the point of the max distance, without affecting the rate of attenuation:

FMOD_3D_INVERSEROLLOFF
FMOD_3D_INVERSETAPEREDROLLOFF

For this mode the max distance is ignored:

FMOD_3D_CUSTOMROLLOFF

Source

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

Retrieve the minimum and maximum audible distance for a 3D sound.

Source

pub fn set_defaults(&self, frequency: c_float, priority: c_int) -> Result<()>

Sets a sound’s default playback attributes.

When the Sound is played it will use these values without having to specify them later on a per Channel basis.

Source

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

Retrieves a sound’s default playback attributes.

Source

pub fn set_mode(&self, mode: Mode) -> Result<()>

Sets or alters the mode of a sound.

When calling this function, note that it will only take effect when the sound is played again with System::playSound. This is the default for when the sound next plays, not a mode that will suddenly change all currently playing instances of this sound.

Flags supported:

If Mode::IGNORE_GEOMETRY_3D is not specified, the flag will be cleared if it was specified previously.

Changing mode on an already buffered stream may not produced desired output. See Streaming Issues.

Source

pub fn get_mode(&self) -> Result<Mode>

Retrieves the mode of a sound.

The mode will be dependent on the mode set by a call to System::createSound, System::createStream or Sound::set_mode.

Source

pub fn set_loop_count(&self, loop_count: c_int) -> Result<()>

Sets the sound to loop a specified number of times before stopping if the playback mode is set to looping.

Changing loop count on an already buffered stream may not produced desired output. See Streaming Issues.

Source

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

Retrieves the sound’s loop count.

Unlike the Channel loop count function, this function simply returns the value set with Sound::setLoopCount. It does not decrement as it plays (especially seeing as one sound can be played multiple times).

Source

pub fn set_loop_points( &self, loop_start: c_uint, start_type: TimeUnit, loop_end: c_uint, end_type: TimeUnit, ) -> Result<()>

Sets the loop points within a sound.

The values used for loop_start and loopend are inclusive, which means these positions will be played.

If a loop_end is smaller or equal to loopstart an error will be returned. The same will happen for any values that are equal or greater than the length of the sound.

Changing loop points on an already buffered stream may not produced desired output. See Streaming Issues.

The Sound’s mode must be set to Mode::LOOP_NORMAL or Mode::LOOP_BIDI for loop points to affect playback.

Source

pub fn get_loop_points( &self, start_type: TimeUnit, end_type: TimeUnit, ) -> Result<(c_uint, c_uint)>

Retrieves the loop points for a sound.

The values returned are inclusive, which means these positions will be played.

Source §

impl Sound

Source

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

Frees a sound object.

This will stop any instances of this sound, and free the sound object and its children if it is a multi-sound object. If the sound was opened with FMOD_NONBLOCKING and hasn’t finished opening yet, it will block. Additionally, if the sound is still playing or has recently been stopped, the release may stall, as the mixer may still be using the sound. Using Sound::getOpenState and checking the open state for FMOD_OPENSTATE_READY and FMOD_OPENSTATE_ERROR is a good way to avoid stalls.

Source

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

Source

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

Source

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

Retrieves the parent System object.

Source §

pub fn get_name(&self) -> Result<Utf8CString>

Retrieves the name of a sound.

If FMOD_LOWMEM has been specified in System::createSound, this function will return “(null)”.

Source

pub fn get_format(&self) -> Result<(SoundType, SoundFormat, c_int, c_int)>

Returns format information about the sound.

Source

pub fn get_length(&self, unit: TimeUnit) -> Result<c_uint>

Retrieves the length using the specified time unit.

A length of 0xFFFFFFFF means it is of unlimited length, such as an internet radio stream or MOD/S3M/XM/IT file which may loop forever.

Note: Using a VBR (Variable Bit Rate) source that does not have metadata containing its accurate length (such as un-tagged MP3 or MOD/S3M/XM/IT) may return inaccurate length values. For these formats, use FMOD_ACCURATETIME when creating the sound. This will cause a slight delay and memory increase, as FMOD will scan the whole during creation to find the correct length. This flag also creates a seek table to enable sample accurate seeking.

Source

pub fn get_tag_count(&self) -> Result<(c_int, c_int)>

Retrieves the number of metadata tags.

‘Tags’ are metadata stored within a sound file. These can be things like a song’s name, composer etc.

The second tuple field could be periodically checked to see if new tags are available in certain circumstances. This might be the case with internet based streams (i.e. shoutcast or icecast) where the name of the song or other attributes might change.

Source

pub fn get_tag(&self, name: Option<&Utf8CStr>, index: c_int) -> Result<Tag>

Retrieves a metadata tag.

‘Tags’ are metadata stored within a sound file. These can be things like a song’s name, composer etc.

The number of tags available can be found with Sound::getNumTags.

The way to display or retrieve tags can be done in 3 different ways:

All tags can be continuously retrieved by looping from 0 to the numtags value in Sound::getNumTags - 1. Updated tags will refresh automatically, and the ‘updated’ member of the FMOD_TAG structure will be set to true if a tag has been updated, due to something like a netstream changing the song name for example.
Tags can be retrieved by specifying -1 as the index and only updating tags that are returned. If all tags are retrieved and this function is called the function will return an error of FMOD_ERR_TAGNOTFOUND.
Specific tags can be retrieved by specifying a name parameter. The index can be 0 based or -1 in the same fashion as described previously.

Note with netstreams an important consideration must be made between songs, a tag may occur that changes the playback rate of the song. It is up to the user to catch this and reset the playback rate with Channel::setFrequency. A sample rate change will be signalled with a tag of type FMOD_TAGTYPE_FMOD.

 while let Ok(tag) = sound->getTag(None, -1)
 {
   if matches!(tag.type, TagType::Fmod) {
     // When a song changes, the sample rate may also change, so compensate here.
     if tag.name == "Sample Rate Change" && channel {
       let TagDataType::Float(frequency) = tag.data else {
         break
       };
       result = channel.set_frequency(frequency)?;
     }
   }
 }

Source §

impl Sound

Source

pub fn get_music_channel_count(&self) -> Result<i32>

Gets the number of music channels inside a MOD/S3M/XM/IT/MIDI file.

Source

pub fn set_music_channel_volume( &self, channel: c_int, volume: c_float, ) -> Result<()>

Sets the volume of a MOD/S3M/XM/IT/MIDI music channel volume.

Source

pub fn get_music_channel_volume(&self, channel: c_int) -> Result<c_float>

Retrieves the volume of a MOD/S3M/XM/IT/MIDI music channel volume.

Source

pub fn set_music_speed(&self, speed: c_float) -> Result<()>

Sets the relative speed of MOD/S3M/XM/IT/MIDI music.

Source

pub fn get_music_speed(&self) -> Result<c_float>

Gets the relative speed of MOD/S3M/XM/IT/MIDI music.

Source §

impl Sound

Source

pub fn set_sound_group(&self, group: SoundGroup) -> Result<()>

Moves the sound from its existing SoundGroup to the specified sound group.

By default, a sound is located in the ‘master sound group’. This can be retrieved with System::getMasterSoundGroup.

Source

pub fn sound_group(&self) -> Result<SoundGroup>

Retrieves the sound’s current sound group.

Source

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

Retrieves the number of subsounds stored within a sound.

A format that has subsounds is a container format, such as FSB, DLS, MOD, S3M, XM, IT.

Source

pub fn get_sub_sound(&self, index: c_int) -> Result<Sound>

Retrieves a handle to a Sound object that is contained within the parent sound.

If the sound is a stream and FMOD_NONBLOCKING was not used, then this call will perform a blocking seek/flush to the specified subsound.

If FMOD_NONBLOCKING was used to open this sound and the sound is a stream, FMOD will do a non blocking seek/flush and set the state of the subsound to FMOD_OPENSTATE_SEEKING.

The sound won’t be ready to be used when FMOD_NONBLOCKING is used, until the state of the sound becomes FMOD_OPENSTATE_READY or FMOD_OPENSTATE_ERROR.

Source