| |
Main Page Namespace List Class Hierarchy Alphabetical List Compound List Namespace Members Compound Members
PLMMixer Class ReferenceAudio output class.
More...
#include <PLMMixer.hpp>
Inheritance diagram for PLMMixer:
[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
|
|
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.
|
|
|
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::Unpause |
( |
|
) |
|
|
| bool PLMMixer::IsPaused |
( |
|
) |
[inline] |
|
| 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:
Generated by
Doxygen 1.2.18 on Tue Oct 26 12:07:38 2004.
|