Trait Backend 

pub trait Backend {
    type Sound;
    type Loading;
    type Playing;

    // Required methods
    fn load_sound(
        &mut self,
        bytes: &[u8],
    ) -> impl Future<Output = Result<Self::Sound, String>>;
    fn load_music(&mut self, path: &str) -> Self::Loading;
    fn poll_music(
        &mut self,
        loading: &mut Self::Loading,
    ) -> Option<Result<Self::Sound, String>>;
    fn length(&self, sound: &Self::Sound) -> Option<f64>;
    fn play(
        &mut self,
        sound: &Self::Sound,
        volume: f32,
        looped: bool,
    ) -> Self::Playing;
    fn set_volume(&mut self, sound: &Self::Sound, volume: f32);
    fn stop(&mut self, sound: &Self::Sound);
    fn set_playing_volume(&mut self, playing: &Self::Playing, volume: f32);
    fn stop_playing(&mut self, playing: Self::Playing);

    // Provided methods
    fn load_sound_file(
        &mut self,
        file: &str,
        files: &Files<'_>,
    ) -> impl Future<Output = Result<Self::Sound, String>> { ... }
    fn pause(&mut self, playing: &Self::Playing) -> Result<(), Unsupported> { ... }
    fn resume(&mut self, playing: &Self::Playing) -> Result<(), Unsupported> { ... }
    fn set_rate(
        &mut self,
        sound: &Self::Sound,
        rate: u32,
    ) -> Result<(), Unsupported> { ... }
    fn add_sound(
        &mut self,
        samples: &SharedSamples,
    ) -> Result<Self::Sound, String> { ... }
    fn remove_sound(&mut self, sound: Self::Sound) { ... }
    fn hold_output(&mut self, on: bool) { ... }
    fn warn(&mut self, _line: &str) { ... }
}

What playing audio needs from the platform: all a backend writes for the sound of a game (ADR-0063).

A feature some backends lack is a provided method, whose default does nothing and says Unsupported, so that adding one breaks no backend.

Required Associated Types

type Sound

A decoded sound or track.

type Loading

A music track or voice clip being loaded.

type Playing

One playback of a sound, which stops alone.

Required Methods

fn load_sound( &mut self, bytes: &[u8], ) -> impl Future<Output = Result<Self::Sound, String>>

Decodes a sound file’s bytes.

fn load_music(&mut self, path: &str) -> Self::Loading

Starts loading and decoding the music or voice file at path.

fn poll_music( &mut self, loading: &mut Self::Loading, ) -> Option<Result<Self::Sound, String>>

The track, once loading has finished (called once per frame).

fn length(&self, sound: &Self::Sound) -> Option<f64>

How long sound plays, in seconds, if that is known: it is for an OGG file loaded with load_music.

fn play( &mut self, sound: &Self::Sound, volume: f32, looped: bool, ) -> Self::Playing

Plays sound from the start at volume (0–1): this playback.

fn set_volume(&mut self, sound: &Self::Sound, volume: f32)

Changes the volume of sound wherever it plays.

fn stop(&mut self, sound: &Self::Sound)

Stops sound.

fn set_playing_volume(&mut self, playing: &Self::Playing, volume: f32)

Changes the volume of playing alone.

fn stop_playing(&mut self, playing: Self::Playing)

Stops playing alone: other copies of its sound play on.

Provided Methods

fn load_sound_file( &mut self, file: &str, files: &Files<'_>, ) -> impl Future<Output = Result<Self::Sound, String>>

Readies the sound file file of the manifest. By default it reads the file with files and decodes it with load_sound; a device that loads a sound from its own path says so here.

fn pause(&mut self, playing: &Self::Playing) -> Result<(), Unsupported>

Stops playing so that resume goes on from where it was. Without it the player mutes the sound, which runs on silently.

fn resume(&mut self, playing: &Self::Playing) -> Result<(), Unsupported>

Goes on with playing from where pause stopped it.

fn set_rate( &mut self, sound: &Self::Sound, rate: u32, ) -> Result<(), Unsupported>

Sets how fast sound plays from its next play, in 16.16 fixed point (RATE_ONE plays it as recorded). Without it the sound plays at 1.0.

fn add_sound(&mut self, samples: &SharedSamples) -> Result<Self::Sound, String>

Readies samples, samples a game made at run time, as a sound to play like one loaded from a file. By default it can’t, and the cue plays nothing, with a warning in the log.

fn remove_sound(&mut self, sound: Self::Sound)

Lets go of sound, which add_sound made: it stops wherever it plays and its memory is freed. By default it is stopped and dropped.

fn hold_output(&mut self, on: bool)

The system suspends the game (on) or has resumed it: a backend whose output can stop stops it here, after the player has held what sounds.

fn warn(&mut self, _line: &str)

Says a problem of the player’s in the backend’s log, by default nowhere.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors