OpenAL Specification and Reference
<<< Previous		Next >>>

Listener and Sources

Basic Listener and Source Attributes

This section introduces basic attributes which can be set both for the Listener object and for Source objects.

The AL Listener and Sources have attributes to describe their position, velocity and orientation in three dimensional space. AL like OpenGL, uses a right-handed Cartesian coordinate system (RHS), where in a frontal default view X (thumb) points right, Y (index finger) points up , and Z (middle finger) points towards the viewer/camera. To switch from a left handed coordinate system (LHS) to a right handed coordinate systems, flip the sign on the Z coordinate.

Table 1. Listener/Source Position

Name	Signature	Values	Default
POSITION	3fv, 3f	any except NaN	{ 0.0f, 0.0f, 0.0f }

Description: POSITION specifies the current location of the Object in the world coordinate system. Any 3-tuple of valid float/double values is allowed. Implementation behavior on encountering NaN and Infinity is not defined. The Object position is always defined in the world coordinate system.

	Annotation (No Transformation)
	AL does not support transformation operations on Objects. Support for transformation matrices is not planned.

Table 2. Listener/Source Velocity

Name	Signature	Values	Default
VELOCITY	3fv, 3f	any except NaN	{ 0.0f, 0.0f, 0.0f }

Description: VELOCITY specifies the current velocity (speed and direction) of the Object, in the world coordinate system. Any 3-tuple of valid float/double values is allowed. The Object VELOCITY does not affect its position. AL does not calculate the velocity from subsequent position updates, nor does it adjust the position over time based on the specified velocity. Any such calculation is left to the application. For the purposes of sound processing, position and velocity are independent parameters affecting different aspects of the sounds.

VELOCITY is taken into account by the driver to synthesize the Doppler effect perceived by the Listener for each source, based on the velocity of both Source and Listener, and the Doppler related parameters.

Table 3. Listener/Source Gain (logarithmic)

Name	Signature	Values	Default
GAIN	f	0.0f, (0.0f, any	1.0f

Description: GAIN defines a scalar amplitude multiplier. As a Source attribute, it applies to that particular source only. As a Listener attribute, it effectively applies to all Sources in the current Context. The default 1.0 means that the sound is un-attenuated. A GAIN value of 0.5 is equivalent to an attenuation of 6 dB. The value zero equals silence (no output). Driver implementations are free to optimize this case and skip mixing and processing stages where applicable. The implementation is in charge of ensuring artifact-free (click-free) changes of gain values and is free to defer actual modification of the sound samples, within the limits of acceptable latencies.

GAIN larger than 1 (amplification) is permitted for Source and Listener. However, the implementation is free to clamp the total gain (effective gain per source times listener gain) to 1 to prevent overflow.

	Annotation/ Effective Minimal Distance
	Presuming that the sample uses the entire dynamic range of the encoding format, an effective gain of 1 represents the maximum volume at which a source can reasonably be played. During processing, the implementation combines the Source GAIN (or MIN_GAIN, if set and larger) with distance based attenuation. The distance at which the effective gain is 1 is equivalent to the DirectSound3D MIN_DISTANCE parameter. Once the effective gain has reached the maximum possible value, it will not increase with decreasing distance anymore.

Annotation/ Effective Minimal Distance

Presuming that the sample uses the entire dynamic range of the encoding format, an effective gain of 1 represents the maximum volume at which a source can reasonably be played. During processing, the implementation combines the Source GAIN (or MIN_GAIN, if set and larger) with distance based attenuation. The distance at which the effective gain is 1 is equivalent to the DirectSound3D MIN_DISTANCE parameter. Once the effective gain has reached the maximum possible value, it will not increase with decreasing distance anymore.

	Annotation (Muting a Context)
	To mute the current context, simply set Listener GAIN to zero. The implementation is expected to optimize for this case, calculating necessary (offset) updates but bypassing the mixing and releasing hardware resources. The specification does not guarantee that the implementation will release hardware resources used by a muted context.

	Annotation (Muting a Source)
	To mute a Source, set Source GAIN to zero. The AL implementation is encouraged to optimize for this case.

<<< Previous	Home	Next >>>
Velocity Dependent Doppler Effect		Listener Object