|Maintainer||Sven Panne <firstname.lastname@example.org>|
This module corresponds to sections 4.1 (Basic Listener and Source Attributes) and 4.2 (Listener Object) of the OpenAL Specification and Reference (version 1.1).
The listener object defines various properties that affect processing of the sound for the actual output. The listener is unique for an OpenAL Context, and has no name. By controlling the listener, the application controls the way the user experiences the virtual world, as the listener defines the sampling/pickup point and orientation, and other parameters that affect the output stream.
It is entirely up to the driver and hardware configuration, i.e. the installation of OpenAL as part of the operating system and hardware setup, whether the output stream is generated for headphones or 2 speakers, 4.1 speakers, or other arrangements, whether (and which) HRTFs are applied, etc...
listenerVelocity contains current velocity (speed and direction) of the
listener in the world coordinate system. Any 3-tuple of valid float
values is allowed, and the initial velocity is (
Vector3 0 0 0).
listenerVelocity does not affect
listenerPosition. 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 independent parameters affecting
different aspects of the sounds.
listenerVelocity 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.
listenerGain contains a scalar amplitude multiplier, which is effectively
applied to all sources in the current context. The initial value 1 means
that the sound is unattenuated. A
listenerGain value of 0.5 is equivalent
to an attenuation of 6dB. 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.
listenerGain larger than 1 (amplification) is permitted. However, the
implementation is free to clamp the total gain (effective gain per source
times listener gain) to 1 to prevent overflow.
orientation contains an "at" vector and an "up" vector, where the
"at" vector represents the "forward" direction of the listener and the
orthogonal projection of the "up" vector into the subspace perpendicular to
the "at" vector represents the "up" direction for the listener. OpenAL
expects two vectors that are linearly independent. These vectors are not
expected to be normalized. If the two vectors are linearly dependent,
behavior is undefined. The initial orientation is (
Vector3 0 0 (-1),
Vector3 0 1 0), i.e. looking down the Z axis with the Y axis pointing