Struct tetra::audio::Sound

pub struct Sound { /* fields omitted */ }

Sound data that can be played back.

All of the playback methods on this type return a SoundInstance that can be used to control the sound after it has started. If you just want to ‘fire and forget’ a sound, you can discard it - the sound will continue playing regardless.

Supported Formats

Various file formats are supported, and can be enabled or disabled via Cargo features:

Format	Cargo feature	Enabled by default?
WAV	audio_wav	Yes
OGG Vorbis	audio_vorbis	Yes
MP3	audio_mp3	Yes
FLAC	audio_flac	No

Performance

Creating a Sound is a fairly cheap operation, as the data is not decoded until playback begins.

Cloning a Sound is a very cheap operation, as the underlying data is shared between the original instance and the clone via reference-counting.

Examples

The audio example demonstrates how to play several different kinds of sound.

Implementations

impl Sound

pub fn new<P>(path: P) -> Result<Sound> where
    P: AsRef<Path>, 

Creates a new sound from the given file.

Note that the data is not decoded until playback begins, so this function will not validate that the data being read is formatted correctly.

Errors

• TetraError::FailedToLoadAsset will be returned if the file could not be loaded.

pub fn from_file_data(data: &[u8]) -> Sound

Creates a new sound from a slice of binary data, encoded in one of Tetra’s supported file formats.

This is useful in combination with include_bytes, as it allows you to include your audio data directly in the binary.

Note that the data is not decoded until playback begins, so this function will not validate that the data being read is formatted correctly.

pub fn play(&self, ctx: &Context) -> Result<SoundInstance>

Plays the sound.

Errors

• TetraError::NoAudioDevice will be returned if no audio device is active.
• TetraError::InvalidSound will be returned if the sound data could not be decoded.

pub fn repeat(&self, ctx: &Context) -> Result<SoundInstance>

Plays the sound repeatedly.

Errors

• TetraError::NoAudioDevice will be returned if no audio device is active.
• TetraError::InvalidSound will be returned if the sound data could not be decoded.

pub fn spawn(&self, ctx: &Context) -> Result<SoundInstance>

Spawns a new instance of the sound that is not playing yet.

Errors

• TetraError::NoAudioDevice will be returned if no audio device is active.
• TetraError::InvalidSound will be returned if the sound data could not be decoded.

pub fn play_with(
    &self,
    ctx: &Context,
    volume: f32,
    speed: f32
) -> Result<SoundInstance>

Plays the sound, with the provided settings.

Errors

• TetraError::NoAudioDevice will be returned if no audio device is active.
• TetraError::InvalidSound will be returned if the sound data could not be decoded.

pub fn repeat_with(
    &self,
    ctx: &Context,
    volume: f32,
    speed: f32
) -> Result<SoundInstance>

Plays the sound repeatedly, with the provided settings.

Errors

• TetraError::NoAudioDevice will be returned if no audio device is active.
• TetraError::InvalidSound will be returned if the sound data could not be decoded.

pub fn spawn_with(
    &self,
    ctx: &Context,
    volume: f32,
    speed: f32
) -> Result<SoundInstance>

Spawns a new instance of the sound that is not playing yet, with the provided settings.

Errors

• TetraError::NoAudioDevice will be returned if no audio device is active.
• TetraError::InvalidSound will be returned if the sound data could not be decoded.

Trait Implementations

impl Clone for Sound

fn clone(&self) -> Sound

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Sound

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

Formats the value using the given formatter.

impl PartialEq<Sound> for Sound

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl StructuralPartialEq for Sound