DemoGL::Reference::Functions::DEMOGL_SoundSystemSetChannel3DPosition

DEMOGL_SoundSystemSetChannel3DPosition

DEMOGL_SoundSystemChannelSet3DAttributes sets the position of the given channel in 3D space, inclusive its orientation. This position is then used to calculate how the sound produced by the given channel is received by the global listener, which position can be set by DEMOGL_SoundSystemSetListener3DPosition 

int
DEMOGL_SoundSystemSetChannel3DPosition(
	const int iChannelCodeID,
	SSoundChannel3DPosition * const p3DPosition
);
Parameters.
iChannelCodeID
Specifies the ChannelCodeID of the channel which 3D attributes should be set.
p3DPosition
Pointer to filled SSoundChannel3DPosition structure with the 3D position, orientation and soundspeed to apply to the channel with ChannelCodeID iChannelCodeID

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_CHANNELACTIONFAILED The underlying sound library reported an error while applying the 3D position to the channel or the element which owns the sound data the given channel is playing is loaded without 3D enabled, see DEMOGL_SoundSystemLoadElement
DGL_SS_ERR_CHANNELNOTINUSE The iChannelCodeID value is not found as an active channel.
DGL_SS_ERR_ILLEGALELEMENTTYPE The channel specified is playing data belonging to an element of an unknown type. This is caused by an implementation error. Should not happen.

Remarks.
Only the channel with the codeID iChannelCodeID is affected with the 3D position, not the element, because sound elements don't have a position because they're not playing, the sound channel plays the sound the sound element contains. You can position this channel, which is in fact the sound producer, in 3D space using DEMOGL_SoundSystemSetChannel3DPosition. Keep in mind that allthough SSoundChannel3DPosition contains a velocity parameter, this is only for the doppler calculations. When you want to create a moving sound source, you have to update the 3D position of the sound channel acting as the sound source, every frame.

NOTE: There is just one  listener position in the sound system, because that's the way the underlying sound library works. This way, you have to keep in mind that two or more effects visible at the same time with total different scenes have to use the same global listener position for their 3D enabled sound channels. It will be odd at first, but it's the same way OpenGL works: there is no camera, the frustum is always at (0,0,0) looking at the negative Z, the world is moved/rotated so it looks as if the 'camera' is rotated/moved. Updating the global listener position in more than one effect in one frame is useless: only the last one will have any effect.

Example.

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

See also.
DEMOGL_SoundSystemLoadElement, DEMOGL_SoundSystemSetListener3DPosition, SSoundChannel3DPosition

Last changed on 18-jan-2001

©1999-2001 Solutions Design