Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   Namespace Members   Compound Members  

PLMMixer Class Reference

Audio output class. More...

#include <PLMMixer.hpp>

Inheritance diagram for PLMMixer:

Inheritance graph
[legend]
List of all members.

Public Types

enum  {
  AUDIO_STOPPED = SDL_AUDIO_STOPPED, AUDIO_PAUSED = SDL_AUDIO_PAUSED, AUDIO_PLAYING = SDL_AUDIO_PLAYING, ANY_CHANNEL = PLM::INDEX_ERROR,
  DEF_CHANNELS = 8, MAX_CHANNELS = 64, LOOP_INF = 255, PAN_FULL = 127,
  MAX_VOLUME = SDL_MIX_MAXVOLUME, FORMAT_U8 = AUDIO_U8, FORMAT_S8 = AUDIO_S8, FORMAT_U16L = AUDIO_U16LSB,
  FORMAT_U16B = AUDIO_U16MSB, FORMAT_U16 = AUDIO_U16, FORMAT_S16L = AUDIO_S16LSB, FORMAT_S16B = AUDIO_S16MSB,
  FORMAT_S16 = AUDIO_S16
}

Public Methods

bool Init (int format, int freq, int samples=0, bool stereo=true, u32 nbchannels=DEF_CHANNELS)
int State () const
void Exit ()
int Format () const
int Freq () const
bool Stereo () const
int Channels () const
u32 NbChannels () const
u32 ActiveChannels () const
bool DriverName (char *buf, int len) const
void Pause ()
void Unpause ()
bool IsPaused () const
u32 PlaySound (PLMSound *snd, u32 channel=ANY_CHANNEL, u8 volume=100, u8 loop=1, int pan=0)
u32 PlayMusic (PLMMusic *mus, u32 channel=ANY_CHANNEL, u8 volume=100, u8 loop=1, int pan=0)
u32 ChGetPos (u32 channel) const
bool ChSeek (u32 channel, u32 pos)
int ChState (u32 channel, int *volume=NULL, int *loop=NULL, int *pan=NULL) const
void ChPause (u32 channel, bool pause=true)
void ChStop (u32 channel)
u8 ChVolume (u32 channel, u8 volume)
u8 ChLoop (u32 channel, u8 loop)
int ChPan (u32 channel, int pan)
bool SameFormat (PLMSound *snd) const
bool SameFormat (PLMMusic *mus) const
void PrintInfo () const
u32 NbInstances ()
u32 SDLState ()

Static Public Methods

PLMMixer * Singleton ()

Detailed Description

Audio output class.

Description:

  • this object is bound to the audio hardware, so only one instance can exist at a time, get it with Singleton()
  • you can delete the pointer returned by Singleton() when you do not need the mixer any more (or to shut it down), but it will then become unavailable for the whole application
  • set the main parameters with Init() (can be called more than once)
  • init parameters are not guaranteed even if Init() returns true, check their value with Format(), Freq(), Stereo(), Channels()
  • note that Init() set the mixer in Pause mode, call Unpause() when ready to play sounds.
  • can handle a variable number of audio channels, i.e. the number of sounds that can be mixed together simultaneously (set by Init()) this is different from the number of channels in a sound, which means monaural (mono) if 1, and stereo if 2.
  • all playing channels are mixed in the same single pass
  • each channel can be paused (then restarted) or stopped (remove sound), it also have its own volume level, panning position and number of loops.
  • these values can be changed at any time while playing
  • while there is two different methods to add sounds and musics, all other operations can be performed 'by channel', whatever type it can be (sound or music), so these methods begins by 'Ch' and need a channel index.
  • ranges :
    • number of channels : 2 .. MAX_CHANNELS
    • volume : 0 .. MAX_VOLUME
    • panning (meaningfull only if stereo is enabled): (-100) (left) ... 0 (center) ... +100 (right), PAN_FULL for 100% volume on both left and right (instead of 50%/50%).


Member Enumeration Documentation

anonymous enum
 

Mixer constants for Init() and PlaySound().

Enumeration values:
AUDIO_STOPPED  The mixer is not initialised, or Init() has failed.
AUDIO_PAUSED  The mixer is paused (globally), all channels are stopped.
AUDIO_PLAYING  The mixer is correctly initialised and playing.
ANY_CHANNEL  Let the mixer choose the first channel available.
DEF_CHANNELS  Default number of channels:1 for music + 4 for sounds.
MAX_CHANNELS  Maximum number of channels.
LOOP_INF  loop infinitely (for PlaySound())
PAN_FULL  play sound centered with full volume on left and right channels
MAX_VOLUME  Maximum global volume (for PlaySound()).
FORMAT_U8  8 bits, unsigned
FORMAT_S8  8 bits, signed
FORMAT_U16L  16 bits, unsigned, little endian (intel)
FORMAT_U16B  16 bits, unsigned, big endian (sun, motorola)
FORMAT_U16  16 bits, unsigned, system default endianness
FORMAT_S16L  16 bits, signed, little endian
FORMAT_S16B  16 bits, signed, big endian
FORMAT_S16  16 bits, signed, system default endianness


Member Function Documentation

PLMMixer* PLMMixer::Singleton   [static]
 

Get an instance of the global mixer.

bool PLMMixer::Init int    format,
int    freq,
int    samples = 0,
bool    stereo = true,
u32    nbchannels = DEF_CHANNELS
 

(Re)Initialize the mixer.

Notes:

  • The mixer is set in pause by default, call Unpause() to start playing.
  • All the submitted PLMSound and PLMMusic will have to use the same format as defined by this method (data format, frequency, stereo). You may have to convert them before calling PlaySound().
  • Note that even if it returns true, the parameters may have been modified to match hardware limitations.
Parameters:
format  sound data format, use FORMAT_* enums,
freq  frequency (usually 11025, 22050 or 44100)
samples  size of the internal buffer in number of samples. 0 = let the mixer choose the best default value based on other settings. Usual sizes: 1024, 2048, 4096. Lower sizes give a better latency, but bigger sizes give much better stability.
stereo  false will use only one output channel, true will use different channels for left and right speakers.
nbchannels  set the maximum number of channels that can be played simultneously (both for sounds and musics).
Returns:
true on success. You can also check its state with State().

int PLMMixer::State   [inline]
 

Return current mixer state.

  • AUDIO_STOPPED : the mixer is not initialised,
    • AUDIO_PAUSED : the mixer is properly initialised but currently paused,
    • AUDIO_PLAYING : the mixer is properly initialised.

void PLMMixer::Exit  
 

Stop all channels, and shut the mixer down.

All is down until Init() is called.

int PLMMixer::Format   [inline]
 

Get current sound format (see FORMAT_ enums for a description).

int PLMMixer::Freq   [inline]
 

Get current mixer frequency.

bool PLMMixer::Stereo   [inline]
 

Check if mixer is stereo (= different data for left and right speakers).

int PLMMixer::Channels   [inline]
 

Get the current number of output channels (1 = mono, 2 = stereo).

u32 PLMMixer::NbChannels  
 

Get the maximum number of channels (allocated).

This is the maximum number of sounds that can be played at the same time.

u32 PLMMixer::ActiveChannels  
 

Get the current number of active channels (playing or paused).

bool PLMMixer::DriverName char *    buf,
int    len
const [inline]
 

Get the name of the current audio driver.

Parameters:
buf  an allocated buffer of at least len bytes
len  the size of the buffer
Returns:
false on error (mixer not initialised).

void PLMMixer::Pause  
 

Main control to pause all channels.

See also:
Unpause(), IsPaused().

void PLMMixer::Unpause  
 

Main control to restart all channels.

See also:
Pause(), IsPaused().

bool PLMMixer::IsPaused   [inline]
 

Check if the mixer is paused (global state).

See also:
Pause(), Unpause().

u32 PLMMixer::PlaySound PLMSound   snd,
u32    channel = ANY_CHANNEL,
u8    volume = 100,
u8    loop = 1,
int    pan = 0
 

Add a new sound to play.

Parameters:
snd  the sound object to play
channel  the channel index to use, if a sound is already using that channel, it is stopped and removed first. Use ANY_CHANNEL to let the mixer select the first channel available (may fail if none available).
volume  volume for this sound [0=silence ... MAX_VOLUME].
loop  how to play this sound,
  • 0 : play the sound only one time, but set the channel in pause, use ChPause(false) to start playing,
  • n > 0 : number of times to play the sound (loops), start immediately
  • LOOP_INF : play the sound repeatedly until ChPause() or ChStop().
Parameters:
pan  if stereo is enabled, set the channel pan position linearly (-100 = full left ... 0 = center ... +100 = full right), use PAN_FULL to set 100% volume on both left and right channels (instead of 50/50).
Returns:
the channel index used to play the sound, or PLM::INDEX_ERROR on error (invalid snd, no more channel available).

u32 PLMMixer::PlayMusic PLMMusic   mus,
u32    channel = ANY_CHANNEL,
u8    volume = 100,
u8    loop = 1,
int    pan = 0
 

Add a new music to play (streamed sound).

Parameters:
mus  the music object to play
channel  the channel index to use, if a sound is already using that channel, it is stopped and removed first. Use ANY_CHANNEL to let the mixer select the first channel available (may fail if none available).
volume  volume for this music [0=silence ... MAX_VOLUME].
loop  how to play this music,
  • 0 : play the music only one time, but set the channel in pause, use ChPause(false) to start playing,
  • n > 0 : number of times to play the music (loops), start immediately
  • LOOP_INF : play the music repeatedly until ChPause() or ChStop().
Parameters:
pan  if stereo is enabled, set the channel pan position linearly (-100 = full left ... 0 = center ... +100 = full right), use PAN_FULL to set 100% volume on both left and right channels (instead of 50/50).
Returns:
the channel index used to play the sound, or PLM::INDEX_ERROR on error (invalid mus, no more channel available).

u32 PLMMixer::ChGetPos u32    channel const
 

Get the current playing position of a channel.

Parameters:
channel  the channel to modify.
Returns:
an offset representing the current position in the sound buffer, in samples. Return PLM::INDEX_ERROR if the channel is empty.

bool PLMMixer::ChSeek u32    channel,
u32    pos
 

Set the current playing position of a sound.

Parameters:
channel  the index of the channel to modify.
pos  the new position, in samples.
Returns:
true on success, false if the channel is empty.

int PLMMixer::ChState u32    channel,
int *    volume = NULL,
int *    loop = NULL,
int *    pan = NULL
const
 

Check if a specific channel is currently playing, and get its current settings.

Parameters:
channel  the index of the channel
volume  if not NULL, the place to return the current volume
loop  if not NULL, the place to return the number of loops
pan  if not NULL, the place to return the current panning position See PlaySound() to get more details on their possible values.
Returns:
  • AUDIO_STOPPED if the channel is stopped or empty (variables are not updated),
  • AUDIO_PAUSED if the channel is paused (not empty),
  • AUDIO_PLAYING if the channel is playing (not empty and not paused).

void PLMMixer::ChPause u32    channel,
bool    pause = true
 

Stop / restart a specific channel.

When paused, the channel does not play anymore, but its internal state and position are not saved, and restored when unpaused.

Parameters:
channel  the channel to pause / unpause
pause  use true to pause the channel and false to restart from where it was paused

void PLMMixer::ChStop u32    channel
 

Stop a specific channel, and make it free for reuse.

The associated sound or music is not deleted, but the channel is then considered as empty.

u8 PLMMixer::ChVolume u32    channel,
u8    volume
 

Change the volume of a specific channel.

Values allowed: from 0 (silence) to MAX_VOLUME.

Returns:
the previous value on success, 0 if channel is not valid.

u8 PLMMixer::ChLoop u32    channel,
u8    loop
 

Change how many times the sound/music should be played.

Parameters:
channel  the index of the channel to modify
loop  how to play this channel,
  • 0 or 1 : play the sound/music only one time, does not change the position if it is playing, but this channel will stop when the end is reached.
  • n > 1 : number of times to play the sound/music (loops), it restarts immediately when the end is reached, and n is decreased until 0.
  • LOOP_INF : keep on playing repeatedly until ChPause() or ChStop() is called.
Returns:
the previous value on success, 0 if channel is not valid.

int PLMMixer::ChPan u32    channel,
int    pan
 

Set the pan position of a specific channel.

Nothing is modified if the mixer in not in stereo mode.

Parameters:
channel  the index of the channel to modify
pan  the panning position (linearly).
  • (-100) is full left
  • (-10) is a little bit more on left than right
  • 0 means centered (50% left, 50% right)
  • (+100) is full right
  • PAN_FULL, centered like 0 but set 100% on both left and right channels.
Returns:
the previous value on success, 0 if channel is not valid.

bool PLMMixer::SameFormat PLMSound   snd const
 

Check if the given sound is in the mixer format.

bool PLMMixer::SameFormat PLMMusic   mus const
 

Check if the given music is in the mixer format.

void PLMMixer::PrintInfo  
 

Print some information on current log.

u32 PLMSDLMgr::NbInstances   [inline, inherited]
 

Get the current number of instances (classes using SDL).

u32 PLMSDLMgr::SDLState   [inline, inherited]
 

Get the current value of SDL flags (initialized sub-systems).


The documentation for this class was generated from the following file:
  • PLMMixer.hpp

Generated by Doxygen 1.2.18 on Tue Oct 26 12:07:44 2004.