CRM64Pro GDK  v0.94
A free cross-platform game development kit built on top of SDL 2.0
Classes | Functions
Sound

Classes

class  CRM64Pro::SoundObj
 
class  CRM64Pro::SoundMgr
 

Functions

Sint32 CRM64Pro::SoundObj::info (Sint32 iMode=0)
 
Sint32 CRM64Pro::SoundObj::getName (string &sName)
 
Uint32 CRM64Pro::SoundObj::getID ()
 
Sint32 CRM64Pro::SoundObj::info (string *sType, AudioInfo *AI)
 
Sint32 CRM64Pro::SoundObj::play (Sint32 iChannel=-1, Sint32 iLoop=0)
 
Sint32 CRM64Pro::SoundObj::fadeIn (Sint32 iTime=1000, Sint32 iChannel=-1, Sint32 iLoop=0)
 
Sint32 CRM64Pro::SoundObj::saveToFile (const string &sFile)
 
Sint32 CRM64Pro::SoundObj::save (const string &sFileCDC)
 
Sint32 CRM64Pro::SoundObj::save (Sint32 idCDC)
 
Sint32 CRM64Pro::SoundMgr::info (Sint32 idSnd=0)
 
Sint32 CRM64Pro::SoundMgr::close (Sint32 idSnd)
 
Sint32 CRM64Pro::SoundMgr::getNum ()
 
Sint32 CRM64Pro::SoundMgr::setName (Sint32 idSnd, const string &sName)
 
SoundObj * CRM64Pro::SoundMgr::get (Sint32 idSnd=0)
 
Sint32 CRM64Pro::SoundMgr::stop (Sint32 iChannel)
 
Sint32 CRM64Pro::SoundMgr::pause (Sint32 iChannel)
 
Sint32 CRM64Pro::SoundMgr::resume (Sint32 iChannel)
 
Sint32 CRM64Pro::SoundMgr::status (Sint32 iChannel)
 
Sint32 CRM64Pro::SoundMgr::fadeOut (Sint32 iChannel, Sint32 iTime=1000)
 
Sint32 CRM64Pro::SoundMgr::panning (Sint32 iChannel=-1, Uint8 iLeft=255, Uint8 iRight=255)
 
Sint32 CRM64Pro::SoundMgr::distance (Sint32 iChannel=-1, Uint8 iDistance=0)
 
Sint32 CRM64Pro::SoundMgr::position (Sint32 iChannel=-1, Sint16 iAngle=0, Uint8 iDistance=0)
 
Sint32 CRM64Pro::SoundMgr::loadFromFile (const string &sFile, const string &sName="")
 
Sint32 CRM64Pro::SoundMgr::load (const string &sFileCDC, const string &sName)
 
Sint32 CRM64Pro::SoundMgr::load (const Sint32 idCDC, const string &sName)
 
Sint32 CRM64Pro::SoundMgr::remove (const Sint32 idCDC, const string &sName)
 

Detailed Description

Once the audio system is initialized using ConfigMgr::audioInit() or ConfigMgr::load(), using this manager you can load sound files from external files or from a CDC file and play them.
By default as a minimum value, there are 8 mixing channels, each of one can play a sound at the same time. It can be dinamically modified up to 128 mixing channels so 128 different sound can be played at the same time.
Actions that can be done on a sound object:


Supported sound formats:


This is a sharing manager: it has the ability of sharing a sound id to a group of owners when they request to open an already opened object based on the name as the key. When the last one of them closes the sound id, it will be effectively closed.

Only a single instance of the Sound Manager exists which is created once Main is instantiated.
You can get a reference to this manager using Main::ISoundMgr() method.

Note
The Sound Manager is automatically released when Main::Terminate() is called.
At this time, if any resource is still loaded, it will be released avoding a resource leak.

Function Documentation

Sint32 CRM64Pro::SoundObj::info ( Sint32  iMode = 0)

Request Sound object information.

For displaying the information, it uses the default log.

Parameters
iModeunused for the time being.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::SoundObj::getName ( string &  sName)

Get the name.

Parameters
sNamea string containing the Sound object name.
Returns
0 on success or a negative error code on failure.
Uint32 CRM64Pro::SoundObj::getID ( )

Get the ID.

Returns
the object ID.
Sint32 CRM64Pro::SoundObj::info ( string *  sType,
AudioInfo AI 
)

Get Sound object information.

Parameters
sTypean string pointer filled in with sound type.
If nullptr is passed, the method ignores the retrieving of this value.
AIa pointer to an AudioInfo struct.
If nullptr is passed, the method ignores the retrieving of this struct.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::SoundObj::play ( Sint32  iChannel = -1,
Sint32  iLoop = 0 
)

Play a sound.

Parameters
iChannelMixing channel used for the sound play.
-1 will use the first free channel and it is set by default.
iLoopnumber of sound playing loops.
By default is set to 0.
0 plays the sound just once, 1 twice and -1 plays it forever.
Returns
greater than 0 on success(the channel used for playing it) or a negative error code on failure.
Sint32 CRM64Pro::SoundObj::fadeIn ( Sint32  iTime = 1000,
Sint32  iChannel = -1,
Sint32  iLoop = 0 
)

Play a sound with a fade in effect.

Parameters
iTimetime for fading in the sound, in milliseconds.
By default is set to 1000ms.
iChannelMixing channel used for the sound play.
-1 will use the first free channel and it is set by default.
iLoopnumber of sound playing loops.
By default is set to 0.
0 plays the sound just once, 1 twice and -1 plays it forever.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::SoundObj::saveToFile ( const string &  sFile)

Export the Sound to an external file.

Parameters
sFilestring containing the [directory]+filename.
The extension, if present, is removed and the right extension is automatically added.
If the file already exists, it will be overwritten.
Directory separators '\' and '/' are supported.
Returns
0 or greater on success or a negative error code on failure.
Sint32 CRM64Pro::SoundObj::save ( const string &  sFileCDC)

Save the Sound in to a CDC file.

If the Sound already exists on the CDC, it will be overwritten.

Parameters
sFileCDCstring containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.
Returns
greater than 0 on success or a negative error code on failure.
Note
If the CDC file is secured, this call will fail. For these cases, open first the CDC using ArchiveMgr::open() and use SoundObj::save() with the CDC id.
Sint32 CRM64Pro::SoundObj::save ( Sint32  idCDC)

Save the Sound in to a CDC file.

If the Sound already exists on the CDC, it will be overwritten.

Parameters
idCDCCDC id.
Returns
greater than 0 on success or a negative error code on failure.
Sint32 CRM64Pro::SoundMgr::info ( Sint32  iMode = 0)

Request Sound Manager information.

For displaying the information, it uses the default log.

Parameters
iMode-1 for displaying only Manager information.
0 for displaying Manager and all Objects information. This is the default value.
idSnd for displaying Manager and given Sound id information.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::SoundMgr::close ( Sint32  idSnd)

Close and destroy a sound.

Parameters
idSnd0 for closing all sound or the Sound id.
As the Sound Manager has the ability of sharing a Sound id, if the sound is shared, it will not be removed till the last owner call this method.
Returns
0 on success or a negative error code on failure.
Note
If you forget to close a sound, it will be automatically closed once the GDK is terminated.
Sint32 CRM64Pro::SoundMgr::getNum ( )

Get number of loaded objects.

Returns
the number of CDC files.
Sint32 CRM64Pro::SoundMgr::setName ( Sint32  idSnd,
const string &  sName 
)

Change the object name.

Parameters
idSndSound id.
sNameThe name to give to the sound e.g. 'mySound'.
The object name must be unique and with a maximum size of 64 characters or will be truncated.
Returns
0 on success or a negative error code on failure.
SoundObj * CRM64Pro::SoundMgr::get ( Sint32  idSnd = 0)

Get a pointer to the sound using its handler.

By default it returns the first sound loaded.

Parameters
idSndSound id.
Returns
nullptr the sound was not found.
A pointer to the sound object.
Sint32 CRM64Pro::SoundMgr::stop ( Sint32  iChannel)

Stop sound playing in a channel.

Parameters
iChannelMixing channel where the sound is being played.
-1 will affect all channels.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::SoundMgr::pause ( Sint32  iChannel)

Pause sound playing in a channel.

Parameters
iChannelMixing channel where the sound is being played.
-1 will affect all channels.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::SoundMgr::resume ( Sint32  iChannel)

Resume sound playing in a channel.

Parameters
iChannelMixing channel where the sound is being played.
-1 will affect all channels.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::SoundMgr::status ( Sint32  iChannel)

Get the sound status on a given channel.

Parameters
iChannelMixing channel where the sound is being played.
-1 will affect all channels.
Returns
C64_STATUS_DISABLEDchannel is not playing any sound.
C64_STATUS_ENABLEDchannel is playing a sound.
C64_STATUS_PAUSEDchannel playing is paused.
Sint32 CRM64Pro::SoundMgr::fadeOut ( Sint32  iChannel,
Sint32  iTime = 1000 
)

Sound fade out effect in a channel.

Parameters
iChannelMixing channel where the sound is being played.
-1 will affect all channels.
iTimetime for fading out the sound, in milliseconds.
By default is set to 1000ms.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::SoundMgr::panning ( Sint32  iChannel = -1,
Uint8  iLeft = 255,
Uint8  iRight = 255 
)

Set the panning of a channel.

Parameters
iChannelMixing channel where the sound is being played.
-1 will affect all channels, even the reserved for music playback.
By default, it is set to -1.
iLeftleft channel value ranging from 0 (quietest) to 255 (loudest).
By default, it is set to 255.
iRightright channel value ranging from 0 (quietest) to 255 (loudest).
By default, it is set to 255.
Returns
0 on success or a negative error code on failure.
Note
This effect does not work with 32bits floating point audio sampling and requires a mode different to Mono.
Sint32 CRM64Pro::SoundMgr::distance ( Sint32  iChannel = -1,
Uint8  iDistance = 0 
)

Set the distance of a channel.

Parameters
iChannelMixing channel where the sound is being played.
-1 will affect all channels, even the reserved for music playback.
By default, it is set to -1.
iDistancean integer from 0 to 255 that specifies the location of the sound in relation to the listener.
0 is overlapping the listener and 255 is as far away as possible. A good step value is 8.
By default, it is set to 0.
Returns
0 on success or a negative error code on failure.
Note
This effect does not work with 32bits floating point audio sampling.
Sint32 CRM64Pro::SoundMgr::position ( Sint32  iChannel = -1,
Sint16  iAngle = 0,
Uint8  iDistance = 0 
)

Set the position of a channel.

Parameters
iChannelMixing channel where the sound is being played.
-1 will affect all channels, even the reserved for music playback.
By default, it is set to -1.
iAnglean integer from 0 to 360 that specifies the location of the sound in relation to the listener.
0 is due north and rotates clockwise as the value increases.
By default, it is set to -1.
iDistancean integer from 0 to 255 that specifies the location of the sound in relation to the listener.
0 is overlapping the listener and 255 is as far away as possible. A good step value is 8.
By default, it is set to 0.
Returns
0 on success or a negative error code on failure.
Note
This effect does not work with 32bits floating point audio sampling.
Sint32 CRM64Pro::SoundMgr::loadFromFile ( const string &  sFile,
const string &  sName = "" 
)

Load a sound from an external file.

The Sound Manager has the ability of sharing ids based on the name as the key, so before trying to load a new one, it checks if it is already loaded for sharing it.

Parameters
sFilestring containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.
sNamethe image object name.
By default, it is set to empty to use the filename (without extension) for setting the object name.
The object name must be unique and with a maximum size of 64 characters or will be truncated.
Returns
greater than 0 on success(the Sound id) or a negative error code on failure.
Sint32 CRM64Pro::SoundMgr::load ( const string &  sFileCDC,
const string &  sName 
)

Load a sound stored in a CDC file.

The Sound Manager has the ability of sharing ids based on the name as the key, so before trying to load a new one, it checks if it is already loaded for sharing it.

Parameters
sFileCDCstring containing the [directory]+filename.
Directory separators '\' and '/' are supported.
sNamestring with the sound name (maximum size of 64 characters).
Returns
0 or greater on success(the Sound id) or a negative error code on failure.
Sint32 CRM64Pro::SoundMgr::load ( const Sint32  idCDC,
const string &  sName 
)

Load a sound stored in a CDC file.

The Sound Manager has the ability of sharing ids based on the name as the key, so before trying to load a new one, it checks if it is already loaded for sharing it.

Parameters
idCDCCDC id.
sNamestring with the sound name (maximum size of 64 characters).
Returns
0 or greater on success(the Sound id) or a negative error code on failure.
Sint32 CRM64Pro::SoundMgr::remove ( const Sint32  idCDC,
const string &  sName 
)

Remove a sound stored in a CDC file.

Parameters
idCDCCDC id.
sNamestring with the sound name (maximum size of 64 characters).
Returns
greater than 0 on success or a negative error code on failure.
Note
The sound must be closed before trying to remove it from the CDC.