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 OpenAL Listener and Sources have attributes to describe their position, velocity and orientation in three dimensional space. OpenAL like OpenGL, uses a right-handed Cartesian coordinate system (RHS), where in a frontal default view X (thumb) points right, Y points up (index finger), and Z points towards the viewer/camera (middle finger). 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. OpenAL does not support transformation operations on Objects.

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. OpenAL 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 independend 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 relative to the medium.

Table 3. Listener/Source Gain

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

Description: GAIN is 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/ No Per-Source Distance Model
	The purpose of the the per-Source Distance Model in DS3D and A3D is to allow different ranges for Sources. In OpenAL the application accomplishes a similar behavior by increasing GAIN into values larger than 1, amplifying the Source. By setting the MIN_GAIN and MAX_GAIN thresholds the application can select the desired dynamic range for a Source directly, while the effective range is determined by GAIN.

Annotation/ No Per-Source Distance Model

The purpose of the the per-Source Distance Model in DS3D and A3D is to allow different ranges for Sources. In OpenAL the application accomplishes a similar behavior by increasing GAIN into values larger than 1, amplifying the Source. By setting the MIN_GAIN and MAX_GAIN thresholds the application can select the desired dynamic range for a Source directly, while the effective range is determined by GAIN.

	Annotation/ Muting a Context
	To mute the current context, simply set Listener GAIN to zero. The implementation can optimize for this case by doing necessary (offset) updates but skipping the mixing and releasing hardware resources.

	Annotation/ Mutng a Source
	To mute a Source, set Source GAIN to zero. The OpenAL implementation is encouraged to omptimize for this case.

<<< Previous	Home	Next >>>
Pitch Scaling for Doppler Effect		Listener Object