OSDL::Audio Namespace Reference

Classes
class	AudibleException
	Mother class for all exceptions raised by Audible instances. More...
class	Audible
	Mother class of all audible content, including sound and music. More...
class	AudioModule
	Root module for all audio services. More...
class	AudioChannelException
	Exceptions raised by AudioChannel instances. More...
class	AudioChannel
	Corresponds to a mixing audio channel. More...
class	AudioException
	Mother class for all audio exceptions. More...
class	MusicException
	Exceptions raised by Music instances. More...
class	Music
	Music is continuous audible content, as opposed to sound. More...
class	MusicManagerException
	Exceptions raised by MusicManager instances. More...
class	MusicPlaybackSetting
	Describes all information needed for the playback of a music. More...
class	MusicManager
	A music manager has for role to drive the playback of musics, based on a playlist. More...
class	SoundException
	Exceptions raised by Sound instances. More...
class	Sound
	Sound is punctual audible content, as opposed to music. More...
Typedefs
typedef Ceylan::Sint32	PlaybackCount
	Stores the number of times an Audible should be played.
typedef Ceylan::Uint32	BufferSize
	For buffer sizes, in bytes (prefer full 32-bit words, faster).
typedef Ceylan::Uint16	SampleFormat
typedef Ceylan::Uint16	ChannelFormat
typedef Ceylan::Uint16	ChannelNumber
typedef Ceylan::Uint32	ChunkSize
	Describes the size, in bytes, of a sample chunk.
typedef Ceylan::Uint8	ListenerDistance
	Describes the distance between an audio source and the listener.
typedef Ceylan::Sint16	ListenerAngle
	Describes the direction, the angle between the listener and an audio source, from 0 to 360 degrees.
typedef Ceylan::Uint8	Volume
	Describes the volume for the playback of an audible.
typedef ::_Mix_Music	LowLevelMusic
	Low-level music being used internally.
typedef Ceylan::Uint32	MusicPosition
	Describes a position in a music.
typedef Ceylan::Uint8	BitrateType
	Bitrate types, for formats that use them (ex: MP3).
typedef Ceylan::CountedPointer < Music >	MusicCountedPtr
	Music counted pointer.
typedef ::Mix_Chunk	LowLevelSound
	Low-level sound being used internally.
typedef Ceylan::CountedPointer < Sound >	SoundCountedPtr
	Sound counted pointer.
Enumerations
enum	FadingStatus { In, Out, None }
	Describes a fading status. More...
enum	MusicType { Wave, MOD, MIDI, OggVorbis, MP3, CommandBased, NoMusic, Unknown }
	Describes all the known music types. More...
Functions
std::string	sampleFormatToString (SampleFormat format)
	Returns a textual description of the specified sample format.
std::string	channelFormatToString (ChannelFormat format)
	Returns a textual description of the specified channel format.
OSDL_DLL AudioModule &	getExistingAudioModule ()
	This function is intended to be the usual means of getting a reference to the audio module, which must already exist.
OSDL_DLL MusicManager &	getExistingMusicManager ()
	This function is intended to be the usual means of getting a reference to the music manager, which must already exist.
Variables
OSDL_DLL const PlaybackCount	Loop = -1
	This playback count corresponds to an infinite loop, unlimited repetitions (its value is -1).
OSDL_DLL const Volume	MinVolume = 0
	The minimum volume level (zero).
OSDL_DLL const Volume	MaxVolume = 128
	The maximum volume level (depends on the platform, 127 or 128).
OSDL_DLL const BitrateType	CBR = 1
	Implementation notes:
OSDL_DLL const BitrateType	VBR = 2

Typedef Documentation

typedef Ceylan::Uint8 OSDL::Audio::BitrateType

Bitrate types, for formats that use them (ex: MP3).

Definition at line 298 of file OSDLMusic.h.

typedef Ceylan::Uint32 OSDL::Audio::BufferSize

For buffer sizes, in bytes (prefer full 32-bit words, faster).

Definition at line 70 of file OSDLAudioCommon.h.

typedef Ceylan::Uint16 OSDL::Audio::ChannelFormat

Definition at line 97 of file OSDLAudioCommon.h.

typedef Ceylan::Uint16 OSDL::Audio::ChannelNumber

Definition at line 109 of file OSDLAudioCommon.h.

typedef Ceylan::Uint32 OSDL::Audio::ChunkSize

Describes the size, in bytes, of a sample chunk.

Definition at line 117 of file OSDLAudioCommon.h.

typedef Ceylan::Sint16 OSDL::Audio::ListenerAngle

Describes the direction, the angle between the listener and an audio source, from 0 to 360 degrees.

It goes clockwise, starting at: directly in front.

So an angle of 0 means that the source is directly in front of the listener, 90 means the source is directly to his right, 180 directly behind him, 270 directly to its left.

Definition at line 142 of file OSDLAudioCommon.h.

typedef Ceylan::Uint8 OSDL::Audio::ListenerDistance

Describes the distance between an audio source and the listener.

Ranges from 0 (closest possible) to 255 (far).

Definition at line 127 of file OSDLAudioCommon.h.

typedef ::_Mix_Music OSDL::Audio::LowLevelMusic

Low-level music being used internally.

Definition at line 83 of file OSDLMusic.h.

typedef ::Mix_Chunk OSDL::Audio::LowLevelSound

Low-level sound being used internally.

Definition at line 65 of file OSDLSound.h.

typedef Ceylan::CountedPointer<Music> OSDL::Audio::MusicCountedPtr

Music counted pointer.

Definition at line 314 of file OSDLMusic.h.

typedef Ceylan::Uint32 OSDL::Audio::MusicPosition

Describes a position in a music.

For MOD musics, it is used as a pattern number in the module. Passing zero is similar to rewinding the music.

For OGG musics, it is used to jump to position seconds from the beginning of the music.

For MP3 musics, it is used to jump to position seconds from the current position in the music. One may use the rewind method to start from the beginning.

Definition at line 197 of file OSDLMusic.h.

typedef Ceylan::Sint32 OSDL::Audio::PlaybackCount

Stores the number of times an Audible should be played.

A value of Loop (-1) means forever (infinite loop). Values below -1 have no meaning and are ignored.

Definition at line 68 of file OSDLAudible.h.

typedef Ceylan::Uint16 OSDL::Audio::SampleFormat

Definition at line 82 of file OSDLAudioCommon.h.

typedef Ceylan::CountedPointer<Sound> OSDL::Audio::SoundCountedPtr

Sound counted pointer.

Definition at line 118 of file OSDLSound.h.

typedef Ceylan::Uint8 OSDL::Audio::Volume

Describes the volume for the playback of an audible.

Ranges from MinVolume to MaxVolume.

Definition at line 152 of file OSDLAudioCommon.h.

Enumeration Type Documentation

enum OSDL::Audio::FadingStatus

Describes a fading status.

Enumerator:

In
Out
None

Definition at line 157 of file OSDLAudioCommon.h.

enum OSDL::Audio::MusicType

Describes all the known music types.

Enumerator:

Wave	Waveform audio format (WAVE/RIFF). Usual extension is .wav. See also: http://en.wikipedia.org/wiki/WAV
MOD	Soundtrack Module. Usual extension is .mod. See also: http://en.wikipedia.org/wiki/MOD_(file_format)
MIDI	Musical Instrument Digital Interface. Usual extension is .mid. See also: http://en.wikipedia.org/wiki/Midi
OggVorbis	Vorbis encoding over Ogg container. Usual extension is .ogg. See also: http://en.wikipedia.org/wiki/Vorbis
MP3	MPEG-1 Audio Layer 3. Usual extension is .mp3. See also: http://en.wikipedia.org/wiki/MP3
CommandBased	Music managed externally by a third-party player, triggered by a command-line call.
NoMusic	To be used to mean no music is available, hence no type can be used (ex: when wanting to know the type of the current music being played while none is playing).
Unknown	Unknown music type.

Definition at line 206 of file OSDLMusic.h.

Function Documentation

std::string OSDL::Audio::channelFormatToString ( ChannelFormat format )

Returns a textual description of the specified channel format.

Exceptions:

AudioException

if the format is not known.

Definition at line 234 of file OSDLAudio.cc.

References OSDL::Audio::AudioModule::Mono, OSDL::Audio::AudioModule::Stereo, and OSDL::Video::Pixels::toString().

AudioModule & OSDL::Audio::getExistingAudioModule ( )

This function is intended to be the usual means of getting a reference to the audio module, which must already exist.

This friend function is intended to be the usual means of getting a reference to the audio module, which must already exist.

If not, an exception will be thrown.

Note:: This function is mainly useful for the OSDL internals, if sub-modules, such as the event module, needed access to the common module.

See also:: hasCommonModule()

Note:: This method is not static to avoid pitfalls of static initializer ordering.

Definition at line 1341 of file OSDLAudio.cc.

References OSDL::CommonModule::getAudioModule(), and OSDL::getExistingCommonModule().

Referenced by OSDL::Audio::AudioChannel::HandleFinishedPlaybackCallback().

MusicManager & OSDL::Audio::getExistingMusicManager ( )

This function is intended to be the usual means of getting a reference to the music manager, which must already exist.

If not, a fatal error will be triggered (not an exception to avoid handling it in all user methods).

Note:: This function is mainly useful for the OSDL internals; This method is not static to avoid pitfalls of static initializer ordering.

Definition at line 554 of file OSDLMusicManager.cc.

Referenced by OSDL::Audio::MusicManager::HandleMusicPlaybackFinishedCallback().

std::string OSDL::Audio::sampleFormatToString ( SampleFormat format )

Returns a textual description of the specified sample format.

Exceptions:

AudioException

if the format is not known.

Definition at line 173 of file OSDLAudio.cc.

References OSDL::Audio::AudioModule::BigSint16SampleFormat, OSDL::Audio::AudioModule::BigUint16SampleFormat, OSDL::Audio::AudioModule::IMAADPCMSampleFormat, OSDL::Audio::AudioModule::LittleSint16SampleFormat, OSDL::Audio::AudioModule::LittleUint16SampleFormat, OSDL::Audio::AudioModule::Sint8SampleFormat, OSDL::Video::Pixels::toString(), and OSDL::Audio::AudioModule::Uint8SampleFormat.

Variable Documentation

const BitrateType OSDL::Audio::CBR = 1

Implementation notes:

Before, when SDL_mixer was to operate on filenames rather than directly on SDL_rwops, on all PC-like platforms (including Windows and most UNIX), the supported formats were WAVE, MOD, MIDI, OGG, and MP3. OGG and, to a lesser extent, WAVE, were recommended for musics.

Now, we want to be able to read musics from opaque archives (using EmbeddedFile instances, thus PhysicsFS), and SDL_mixer just allows the OGG (OggVorbis) file format to be used with the underlying SDL_rwops (MikMod could be supported as well).

So, on the PC, one should only use OggVorbis-based musics now.

See also:: Mix_LoadMUS_RW

with SDL_mixer: Mix_SetMusicCMD, Mix_HookMusic, Mix_GetMusicHookData not used, as no need felt.

with the DS:

MP3-encoded data is read from file (using libfat), on the ARM9, in a double buffer whose halves are located in memory one after the other.

When a playback is requested, the ARM9 sends to the ARM7 an IPC command that specify the address of this encoded buffer, which contains MP3 frames.

As soon as the ARM7 starts reading a half buffer, it triggers back to the ARM9 an IPC command, so that the ARM9 starts refilling the other buffer at once (actually the ARM9 performs it asynchronously, as I/O operations should not be done in an IRQ handler, thus the handler just sets a bit that will be read and taken into account from the ARM9 main loop).

The ARM7 reads whole chunks of memory (one MP3 frame after the other), and one has to ensure that, when arriving at the end of the second half buffer, it will be still able to read a whole frame, as encoded data is read without knowing the boundaries of the MP3 frames (which are not fixed-size). Thus the ARM7 must stop reading no later than: (end of buffer)-(delta) with delta = max size of an MP3 frame. Looking at Helix example: https://helixcommunity.org/viewcvs/datatype/mp3/codec/fixpt/testwrap/main.c?view=markup

they retain delta = 2*MAINBUF_SIZE, with MAINBUF_SIZE defined in mp3dec.h as 1940, thus delta = 3880. So as long as the read pointer in encoding buffer is below boundary B = (end of buffer)-(delta), at least one more frame can be decoded. As soon as the delta boundary is crossed, the remaining bytes R = (end of buffer) - (last position + last frame size) with R < delta cannot be assumed to contain a whole frame, thus they have to be copied back to the beginning at the encoded buffer. To do so, the first half must have been refilled not from the buffer start, but from S = (buffer start) + delta. The actual buffer start will be A = (buffer start) + delta - R. The move of R bytes must be as fast as possible, as it is directly in the critical path, R must thus be minimized.

Definition at line 147 of file OSDLMusic.cc.

Referenced by OSDL::Audio::Music::DescribeBitrateType().

const PlaybackCount OSDL::Audio::Loop = -1

This playback count corresponds to an infinite loop, unlimited repetitions (its value is -1).

Definition at line 54 of file OSDLAudible.cc.

Referenced by OSDL::Audio::Audible::GetLoopsForPlayCount(), OSDL::Audio::MusicPlaybackSetting::MusicPlaybackSetting(), OSDL::Audio::Music::play(), OSDL::Audio::Music::playWithFadeIn(), and OSDL::Audio::MusicPlaybackSetting::toString().