wiki:OpenAL_Parameters
Last modified 6 years ago Last modified on 2008-02-23 03:19:00

OpenAL Basics:

The OpenAL has three fundamental primitives or objects: Buffers, Sources, and a single Listener. Each object can be changed independently, the setting of one object does not affect the setting of others.

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. 
  • POSITION
  • VELOCITY
  • GAIN

Source Attributes:

  Sources specify attributes like position, velocity, and a buffer with sample data. By controlling a Source�s attributes the  
  application can modify and parameterize the static sample data provided by the Buffer referenced by the Source. Sources 
  define a localized sound, and encapsulate a set of attributes applied to a sound at its origin, 
  i.e. in the very first stage of the processing on the way to the listener. Source related effects have to be applied before
  Listener related effects unless the output is invariant to any collapse or reversal of order. 
  AL also provides additional functions to manipulate and query the execution state of Sources: the current playing status of 
  a source (started, stopped, paused), including access to the current sampling position within the associated Buffer."

http://www.wildfiregames.com/~soundfx/EXAMPLES/PRELIMOALDESCFLAT02.jpg

OpenAL Parameters

Documentation Excerpts:

Gain

  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.

Looping

  LOOPING: 	 		uint 	FALSE, TRUE 	FALSE 

Description: LOOPING is a flag that indicates that the Source will not be in STOPPED state once it reaches the end of last buffer in the buffer queue. Instead, the Source will immediately promote to INITIAL and PLAYING. The default value is FALSE. LOOPING can be changed on a Source in any execution state. In particular, it can be changed on a PLAYING Source.

Pitch

  PITCH: 	 		f 	(0.0f, 1.0f] 	1.0f 

Description: Desired pitch shift, where 1.0 equals identity. Each reduction by 50 percent equals a pitch shift of -12 semitones (one octave reduction). Zero is not a legal value.

Gain, Minimum

  MIN_GAIN: 	 		f 	0.0f, (0.0f, 1.0f]	0.0f 

Description: MIN_GAIN is a scalar amplitude threshold. It indicates the minimal GAIN which is always guaranteed for this Source. At the end of the processing of various attenuation factors such as distance based attenuation and Source GAIN, the effective gain calculated is compared to this value. If the effective gain is lower than MIN_GAIN, MIN_GAIN is applied. This happens before the Listener GAIN is applied. If a zero MIN_GAIN is set, then the effective gain will not be corrected.

Gain, Maximum

  MAX_GAIN: 	 		f 	0.0f, (0.0f, 1.0f]	1.0f 

Description: MAX_GAIN defines a scalar amplitude threshold. It indicates the maximal GAIN permitted for this Source. At the end of the processing of various attenuation factors such as distance based attenuation and Source GAIN, the effective gain calculated is compared to this value. If the effective gain is higher than MAX_GAIN, MAX_GAIN is applied. This happens before the Listener GAIN is applied. If the Listener gain times MAX_GAIN still exceeds the maximum gain the implementation can handle, the implementation is free to clamp. If a zero MAX_GAIN is set, then the Source is effectively muted. The implementation is free to optimize for this situation, but no optimization is required or recommended as setting GAIN to zero is the proper way to mute a Source.

Cone Outer Gain

  CONE_OUTER_GAIN: 	 	i,f	[0.0f, 1.0f] 	0.0f 

Description: the factor with which GAIN is multiplied to determine the effective gain outside the cone defined by the outer angle. The effective gain applied outside the outer cone is GAIN times CONE_OUTER_GAIN. Changing GAIN affects all directions, i.e. the source is attenuated in all directions, for any position of the listener. The application has to change CONE_OUTER_GAIN as well if a different behavior is desired.

Cone Inner Gain

  CONE_INNER_ANGLE: 	 	i,f 	any except NaN 	360.0f 

Description: Inside angle of the sound cone, in degrees. The default of 360 means that the inner angle covers the entire world, which is equivalent to an omnidirectional source.

Cone Outer Angle

  CONE_OUTER_ANGLE: 	 	i,f 	any except NaN 	360.0f 

Description: Outer angle of the sound cone, in degrees. The default of 360 means that the outer angle covers the entire world. If the inner angle is also 360, then the zone for angle-dependent attenuation is zero.

Priority

  PRIORITY: 			60

Description:

  • 100= emergency use only (undefined overhead)
  • 90= required (voiceover, you are under attack warning)
  • 80= rather important (battle sounds, death, destruction)
  • 70= rather important (building)
  • 60= not so important (resources)
  • 50= fluff (ambient - birds, etc.)

Buffer

  BUFFER: 	 		ui 	any valid buffer name 	NONE 

Description: Specify the current Buffer object, which means the head entry in its queue. Using BUFFER with the Source command on a STOPPED or INITIAL Source empties the entire queue, then appends the one Buffer specified. For a PLAYING or PAUSED Source, using the Source command with BUFFER is an INVALID_OPERATION. It can be applied to INITIAL and STOPPED Sources only. Specifying an invalid bufferName will result in an INVALID_VALUE error while specifying an invalid sourceName results in an INVALID_NAME error. NONE, i.e. 0, is a valid buffer Name. Source( sName, BUFFER, 0 ) is a legal way to release the current buffer queue on an INITIAL or STOPPED Source, whether it has just one entry (current buffer) or more. The Source( sName, BUFFER, NONE) call still causes an INVALID_OPERATION for any source PLAYING or PAUSED, consequently it can not be abused to mute or stop a source.

Velocity

  VELOCITY: 	 		3fv, 3f 	any except NaN 	{ 0.0f, 0.0f, 0.0f }  (For Doppler Effects*) 	

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.

Source Relative

  SOURCE_RELATIVE: 	 	boolean 	FALSE, TRUE 	FALSE 	

SOURCE_RELATIVE set to TRUE indicates that the values specified by POSITION are to be interpreted relative to the listener position.

Position

  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.

Distance, Maximum

  MAX_DISTANCE: 	 		float 	[0, any] 	MAX_FLOAT 	

This is used for distance attenuation calculations based on inverse distance with rolloff, if the Inverse Clamped Distance Model is used. In this case, distances greater than MAX_DISTANCE will be clamped MAX_DISTANCE. MAX_DISTANCE based clamping is applied before MIN_GAIN clamping, so if the effective gain at MAX_DISTANCE is larger than MIN_GAIN, MIN_GAIN will have no effect. No culling is supported.

Rolloff Factor

  ROLLOFF_FACTOR: 	 	float 	[0, any] 	1.0f 	

This is used for distance attenuation calculations based on inverse distance with rolloff. For distances smaller than MAX_DISTANCE (and, depending on the distance model, larger than REFERENCE_DISTANCE), this will scale the distance attenuation over the applicable range. See section on distance models for details how the attenuation is computed as a function of the distance. In particular, ROLLOFF_FACTOR can be set to zero for those Sources which are supposed to be exempt from distance attenuation. The implementation is encouraged to optimize this case, bypassing distance attenuation calculation entirely on a per-Source basis. "

Distance, Referance

  REFERENCE_DISTANCE: 	 	float 	[0, any] 	1.0f 	

This is used for distance attenuation calculations based on inverse distance with rolloff. Depending on the distance model it will also act as a distance threshold below which gain is clamped. See the section on distance models for details.

Velocity

  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.

Direction

  DIRECTION: 	 		3fv, 3f 	any except NaN 	{ 0.0f, 0.0f, 0.0f } 	

Description: If DIRECTION does not equal the zero vector, the Source is directional. The sound emission is presumed to be symmetric around the direction vector (cylinder symmetry). Sources are not oriented in full 3 degrees of freedom, only two angles are effectively needed. The zero vector is default, indicating that a Source is not directional. Specifying a non-zero vector will make the Source directional. Specifying a zero vector for a directional Source will effectively mark it as nondirectional.

===Buffers Queued===

  BUFFERS_QUEUED: 	 	uint 	[0, any] 	NONE	Query only. Query the number of buffers in the queue of a given Source. This includes those not yet played, the one currently playing, and the ones that have been played already. This will return 0 if the current and only bufferName is 0. 

Buffers Processed

  BUFFERS_PROCESSED: 	 	uint 	[0, any] 	NONE	

Query only. Query the number of buffers that have been played by a given Source. Indirectly, this gives the index of the buffer currently playing. Used to determine how much slots are needed for unqueueing them. On an STOPPED Source, all buffers are processed. On an INITIAL Source, no buffers are processed, all buffers are pending. This will return 0 if the current and only bufferName is 0.