DemoGL::Reference::Functions::DEMOGL_SoundSystemFreeElement

DEMOGL_SoundSystemFreeElement

DEMOGL_SoundSystemFreeElement removes a loaded sound element from the sound system. After calling DEMOGL_SoundSystemFreeElement the given sound element is no longer available and refering to this sound element in script commands or in DemoGL API calls will result in an error. You load sound elements with DEMOGL_SoundSystemLoadElement. 

int
DEMOGL_SoundSystemFreeElement(
	const int iElementCodeID,
	const int iElementType
);
Parameters.
iElementCodeID
Specifies the ElementCodeID of the channel which should be removed from the sound system.
iElementType
Specifies of which type the to be freed sound element is. iElementType can be one of the following sound element types:

Sound element type Description
DGL_SS_MP3ELEMENT Sound element stored in the MP3 standard, i.e. MPEG v1.0 and v2.0 layer3.
DGL_SS_MODELEMENT Sound element stored in one of the following formats: MOD, XM, IT, S3M or MTM.
DGL_SS_SAMPLEELEMENT Sound element stored in the standard windows PCM format, or compressed with a custom CODEC. When you use a custom CODEC, this CODEC is required to be installed on the user's computer for the WAV to be decoded. So, you should either distribute the CODEC with your software, or use a CODEC that comes with Windows (eg. Microsoft ADPCM).

Return values.
If the function succeeds, it returns SYS_OK.
If the function fails, it returns one of the following error codes:

Error code Description
DGL_SS_ERR_ILLEGALELEMENTID The iElementCodeID value is not found as a loaded sound element.
DGL_SS_ERR_ILLEGALELEMENTTYPE The iElementType specified is not known.

Remarks.
DemoGL keeps track of multiple loads of the same sound element data. If a sound element is loaded more than once, calling DEMOGL_SoundSystemFreeElement won't remove it from the sound system because more references to this same sound element exist. When the last reference frees the sound element it will be removed from the sound system. This totally transparent to the caller of DEMOGL_SoundSystemFreeElement who will receive a success even if the sound element is not removed because other references exist.

Example.

Requirements.
DemoGL v1.3 (build 0112 or higher)

See also.
DEMOGL_SoundSystemLoadElement, _SOUNDSYSTEM commands

Last changed on 18-jan-2001

©1999-2001 Solutions Design