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

Source Objects

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.

Managing Source Names

AL provides calls to request and release Source Names handles. Calls to control Source Execution State are also provided.

Requesting a Source Name

The application requests a number of Sources using GenSources.

sizei GenSources ( sizei n , uint * sources );

Releasing Source Names

The application requests deletion of a number of Sources by DeleteSources.

void DeleteSources ( sizei n , uint * sources );

Validating a Source Name

The application can verify whether a source name is valid using the IsSource query.

boolean IsSource ( uint sourceName );

Source Attributes

This section lists the attributes that are set per Source, affecting the processing of the current buffer. Some of these attributes can also be set for buffer queue entries.

Source Positioning

Table 5. SOURCE_RELATIVE Attribute

Name	Signature	Values	Default
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.

Buffer Looping

Table 6. Source LOOPING Attribute

Name	Signature	Values	Default
LOOPING	uint	TURE, FALSE	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.

Current Buffer

Table 7. Source BUFFER Attribute

Name	Signature	Values	Default
BUFFER	ui	any valid bufferName	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.

Queue State Queries

Table 8. BUFFERS_QUEUED Attribute

Name	Signature	Values	Default
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.

Table 9. BUFFERS_PROCESSED Attribute

Name	Signature	Values	Default
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.

Bounds on Gain

Table 10. Source Minimal Gain

Name	Signature	Values	Default
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.

Table 11. Source Maximal Gain (logarithmic)

Name	Signature	Values	Default
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.

Distance Model Attributes

Table 12. REFERENCE_DISTANCE Attribute

Name	Signature	Values	Default
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.

Table 13. ROLLOFF_FACTOR Attribute

Name	Signature	Values	Default
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.

Table 14. MAX_DISTANCE Attribute

Name	Signature	Values	Default
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.

Frequency Shift by Pitch

Table 15. Source PITCH Attribute

Name	Signature	Values	Default
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.

Direction and Cone

Each Source can be directional, depending on the settings for CONE_INNER_ANGLE and CONE_OUTER_ANGLE. There are three zones defined: the inner cone, the outside zone, and the transitional zone in between. The angle-dependent gain for a directional source is constant inside the inner cone, and changes over the transitional zone to the value specified outside the outer cone. Source GAIN is applied for the inner cone, with an application selectable CONE_OUTER_GAIN factor to define the gain in the outer zone. In the transitional zone implementation-dependent interpolation between GAIN and GAIN times CONE_OUTER_GAIN is applied.

Table 16. Source DIRECTION Attribute

Name	Signature	Values	Default
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.

Table 17. Source CONE_INNER_ANGLE Attribute

Name	Signature	Values	Default
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.

Table 18. Source CONE_OUTER_ANGLE Attribute

Name	Signature	Values	Default
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.

Table 19. Source CONE_OUTER_GAIN Attribute

Name	Signature	Values	Default
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.

Changing Source Attributes

The Source specifies the position and other properties as taken into account during sound processing.

void Source{n}{sifd} ( uint sourceName , enum paramName , T value );

void Source{n}{sifd}v ( uint sourceName , enum paramName , T * values );

Querying Source Attributes

Source state is maintained inside the AL implementation, and the current attributes can be queried. The performance of such queries is implementation dependent, no performance guarantees are made. The valid values for the paramName parameter are identical to the ones for Source*.

void GetSource{n}{sifd}{v} ( uint sourceName , enum paramName , T * values );

Queueing Buffers with a Source

AL does not specify a built-in streaming mechanism. There is no mechanism to stream data e.g. into a Buffer object. Instead, the API introduces a more flexible and versatile mechanism to queue Buffers for Sources.

There are many ways to use this feature, with streaming being only one of them.

Streaming is replaced by queuing static buffers. This effectively moves any multi-buffer caching into the application and allows the application to select how many buffers it wants to use, whether these are re-used in cycle, pooled, or thrown away.
Looping (over a finite number of repititions) can be implemented by explicitely repeating buffers in the queue. Infinite loops can (theoretically) be accomplished by sufficiently large repetition counters. If only a single buffer is supposed to be repeated infinitely, using the respective Source attribute is recommended.
Loop Points for restricted looping inside a buffer can in many cases be replaced by splitting the sample into several buffers, queueing the sample fragments (including repetitions) accordingly.

Buffers can be queued, unqueued after they have been used, and either be deleted, or refilled and queued again. Splitting large samples over several buffers maintained in a queue has a distinct advantages over approaches that require explicit management of samples and sample indices.

Queueing command

The application can queue up one or multiple buffer names using SourceQueueBuffers. The buffers will be queued in the sequence in which they appear in the array.

void alSourceQueueBuffers ( uint sourceName , sizei numBuffers , uint * bufferNames );

This command is legal on a Source in any state (to allow for streaming, queueing has to be possible on a PLAYING Source). Queues are read-only with exception of the unqueue operation. The Buffer Name NONE (i.e. 0) can be queued.

Unqueueing command

Once a queue entry for a buffer has been appended to a queue and is pending processing, it should not be changed. Removal of a given queue entry is not possible unless either the Source is STOPPED (in which case then entire queue is considered processed), or if the queue entry has already been processed (PLAYING or PAUSED Source).

The Unqueue command removes a number of buffers entries that have finished processing, in the order of appearance, from the queue. The operation will fail if more buffers are requested than available, leaving the destination arguments unchanged. An INVALID_VALUE error will be thrown. If no error, the destination argument will have been updated accordingly.

void SourceUnqueueBuffers ( uint sourceName , sizei numEntries , uint * bufferNames );

Managing Source Execution

The execution state of a source can be queried. AL provides a set of functions that initiate state transitions causing Sources to start and stop execution.

TBA: State Transition Diagram.

Source State Query

The application can query the current state of any Source using GetSource with the parameter Name SOURCE_STATE. Each Source can be in one of four possible execution states: INITIAL, PLAYING, PAUSED, STOPPED. Sources that are either PLAYING or PAUSED are considered active. Sources that are STOPPED or INITIAL are considered inactive. Only PLAYING Sources are included in the processing. The implementation is free to skip those processing stages for Sources that have no effect on the output (e.g. mixing for a Source muted by zero GAIN, but not sample offset increments). Depending on the current state of a Source certain (e.g. repeated) state transition commands are legal NOPs: they will be ignored, no error is generated.

State Transition Commands

The default state of any Source is INITIAL. From this state it can be propagated to any other state by appropriate use of the commands below. There are no irreversible state transitions.

void SourcePlay ( uint sName );

void SourcePause ( uint sName );

void SourceStop ( uint sName );

void SourceRewind ( uint sName );

The functions are also available as a vector variant, which guarantees synchronized operation on a set of Sources.

void SourcePlayv ( sizei n , uint * sNames );

void SourcePausev ( sizei n , uint * sNames );

void SourceStopv ( sizei n , uint * sNames );

void SourceRewindv ( sizei n , uint * sNames );

The following state/command/state transitions are defined:

Play() applied to an INITIAL Source will promote the Source to PLAYING, thus the data found in the Buffer will be fed into the processing, starting at the beginning. Play() applied to a PLAYING Source will restart the Source from the beginning. It will not affect the configuration, and will leave the Source in PLAYING state, but reset the sampling offset to the beginning. Play() applied to a PAUSED Source will resume processing using the Source state as preserved at the Pause() operation. Play() applied to a STOPPED Source will propagate it to INITIAL then to PLAYING immediately.
Pause() applied to an INITIAL Source is a legal NOP. Pause() applied to a PLAYING Source will change its state to PAUSED. The Source is exempt from processing, its current state is preserved. Pause() applied to a PAUSED Source is a legal NOP. Pause() applied to a STOPPED Source is a legal NOP.
Stop() applied to an INITIAL Source is a legal NOP. Stop() applied to a PLAYING Source will change its state to STOPPED. The Source is exempt from processing, its current state is preserved. Stop() applied to a PAUSED Source will change its state to STOPPED, with the same consequences as on a PLAYING Source. Stop() applied to a STOPPED Source is a legal NOP.
Rewind() applied to an INITIAL Source is a legal NOP. Rewind() applied to a PLAYING Source will change its state to STOPPED then INITIAL. The Source is exempt from processing, its current state is preserved, with the exception of the sampling offset which is reset to the beginning. Rewind() applied to a PAUSED Source will change its state to INITIAL, with the same consequences as on a PLAYING Source. Rewind() applied to a STOPPED Source promotes the Source to INITIAL, resetting the sampling offset to the beginning.

Resetting Configuration

The INITIAL state is not necessarily identical to the default state in which Source is created. INITIAL merely indicates that the Source can be executed using the SourcePlay command. A STOPPED or INITIAL Source can be reset into the default configuration by using a sequence Source commands as necessary. As the application has to specify all relevant state anyway to create a useful Source configuration, no reset command is provided.