DemoGL SDK:Reference:Functions:DEMOGL

DemoGL::Reference::Functions::DEMOGL_SoundSystemLoadElement

DEMOGL_SoundSystemLoadElement

DEMOGL_SoundSystemLoadElement loads a sound element into the sound system so it can be used for playing sound.

int
DEMOGL_SoundSystemLoadElement(
	const char *pszFilename,
	const int iElementType,
	const char *pszElementScriptID,
	const bool bUses3D
);

Parameters.

pszFilename

Pointer to a zero-terminated string which contains the filename, inclusive path, of the file which contains the sound element data. When constructing the path, keep in mind the datafile/datadir specific settings of DemoGL, see: DEMOGL_SetVariable(3).

iElementType

Specifies of which type the to be loaded sound element is so the sound system can use the correct logic to play the sound. 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).

pszElementScriptID

Pointer to a zero-terminated string which contains the ElementScriptID that should be associated with the sound element that should be loaded. When DEMOGL_SoundSystemLoadElement succeeds, script commands can interact with the loaded sound element, refering to it by using pszElementScriptID. The ElementScriptID is very important as it is used as a global reference to the sound element both in the script and from code. By specifying the same ElementScriptID for a sound element as a previous loaded, but not freed, sound element, the reference counter of that already loaded element will be increased and no loading takes place, but the caller will receive the ElementCodeID of that previous loaded sound element. When you specify a different ElementScriptID as a sound element previously loaded, but pszFilename is identical to that of the previously loaded soundelement, the filedata will still be loaded and threated as a new sound element. This way, you can load the same data more than once with for example with and without 3D support, specifying different bUses3D values and different pszElementScriptID values.

bUses3D

Specifies if this sound element will be usable with 3D sound functionality (true) or not (false). When bUses3D is true, panning and volume are related to the 3D position of the sound element and the listener and simple panning and volume functions will not have any effect on the sound element. The element is then 'loaded with 3D enabled'. When bUses3D is false you can set panning and volume with the simple channel API functions for setting panning and volume, but 3D functionality will not have any effect on the sound element's play, it will generate an error. Once set, this can't be changed.

Return values.

If the function succeeds, it returns the ElementCodeID.
If the function fails, it returns one of the following error codes:

Error code Description

DGL_SS_ERR_COULDNTLOAD Sound element couldn't be loaded, probably filename related.

DGL_SS_ERR_ELEMENTSTOREFULL The internal store for sound elements is full. See Definitions and defaults for the maximum amount of loadable sound elements at one time.

DGL_SS_ERR_INITOFELEMENTFAILED The initialisation of the sound element failed. Errorcode of the underlying sound library is logged on the system console for in depth details. These errorcodes are defined in DemoGL_Bass.h.

Remarks.

Pay attention which sound element type you specify when you try to load a sound element. ElementCodeID's are unique and can be used to refer to a sound element in the DemoGL API calls related to sound elements. When you don't need a sound element anymore, remove it from the system by DEMOGL_SoundSystemFreeElement. Do not load sound elements with DEMOGL_FileLoad. When you have specified bUses3D as true with a sound element and you want to use that sound data also as a non-3D sound, load the file again as a different sound element, and specify a different pszElementScriptID with the new sound element. References to the same sound element, caused by loading the same data specifying the same pszElementScriptID will be decreased when DEMOGL_SoundSystemFreeElement is called or the FREE[elementtype] command is used with the _SOUNDSYSTEM object in the script.

Example.

Requirements.

DemoGL v1.3 (build 0112 or higher)

Last changed on 18-jan-2001

Š1999-2001 Solutions Design

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).

Error code	Description
DGL_SS_ERR_COULDNTLOAD	Sound element couldn't be loaded, probably filename related.
DGL_SS_ERR_ELEMENTSTOREFULL	The internal store for sound elements is full. See Definitions and defaults for the maximum amount of loadable sound elements at one time.
DGL_SS_ERR_INITOFELEMENTFAILED	The initialisation of the sound element failed. Errorcode of the underlying sound library is logged on the system console for in depth details. These errorcodes are defined in DemoGL_Bass.h.