Sample

Inherits: Resource < Reference < Object

Category: Core

Brief Description

Audio sample (sound) class.

Member Functions

void create ( int format, bool stereo, int length )
RawArray get_data ( ) const
int get_format ( ) const
int get_length ( ) const
int get_loop_begin ( ) const
int get_loop_end ( ) const
int get_loop_format ( ) const
int get_mix_rate ( ) const
bool is_stereo ( ) const
void set_data ( RawArray data )
void set_loop_begin ( int pos )
void set_loop_end ( int pos )
void set_loop_format ( int format )
void set_mix_rate ( int hz )

Numeric Constants

  • FORMAT_PCM8 = 0 — 8-bits signed PCM audio.
  • FORMAT_PCM16 = 1 — 16-bits signed little endian PCM audio.
  • FORMAT_IMA_ADPCM = 2 — IMA-ADPCM Audio.
  • LOOP_NONE = 0 — No loop enabled.
  • LOOP_FORWARD = 1 — Forward looping (when playback reaches loop end, goes back to loop begin).
  • LOOP_PING_PONG = 2 — Ping-pong looping (when playback reaches loop end, plays backward until loop begin). Not available in all platforms.

Description

Sample provides an audio sample class, containing audio data, together with some information for playback, such as format, mix rate and loop. It is used by sound playback routines.

Member Function Description

  • void create ( int format, bool stereo, int length )

Create new data for the sample, with format (see FORMAT_* constants), stereo hint, and length in samples (not bytes).

Calling this method overrides previously existing data. Stereo samples are interleaved pairs of left and right points (in that order), but count as one sample for length purposes.

Return sample data as little endian.

  • int get_format ( ) const

Return the sample format.

  • int get_length ( ) const

Return the sample length in samples. Stereo samples count as one, even if they are made of a left and a right sample.

  • int get_loop_begin ( ) const

Return the loop begin position.

  • int get_loop_end ( ) const

Return the loop end position.

  • int get_loop_format ( ) const

Return the loop format.

  • int get_mix_rate ( ) const

Return the mix rate for the sample.

  • bool is_stereo ( ) const

Return whether the current sample was created as stereo.

Set sample data. Data must be little endian, no matter the host platform, and exactly as long as to fit all samples. The length of this array can be calculated as follows:

Get the sample length (get_length).

If the sample format is FORMAT_PCM16, multiply it by 2.

If the sample format is FORMAT_IMA_ADPCM, divide it by 2 (rounding any fraction up), then add 4.

If the sample is stereo (is_stereo), multiply it by 2.

  • void set_loop_begin ( int pos )

Set the loop begin position. It must be a valid frame and less than the loop end position.

  • void set_loop_end ( int pos )

Set the loop end position. It must be a valid frame and greater than the loop begin position.

  • void set_loop_format ( int format )

Set the loop format (use LOOP_* constants as argument).

  • void set_mix_rate ( int hz )

Set the mix rate for the sample (expected playback frequency).