Manipulating Buffer Attributes

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

Buffer Attributes

This section lists the attributes that can be set, or queried, per Buffer. Note that some of these attributes can not be set using the Buffer commands, but are set using commands like BufferData.

Querying the attributes of a Buffer with a buffer name that is not valid throws an INVALID_OPERATION. Passing in an attribute name that is invalid throws an INVALID_VALUE error.

Table 1. Buffer FREQUENCY Attribute

Name	Signature	Values	Default
FREQUENCY	float	none	(0, any]

Description: Frequency, specified in samples per second, i.e. units of Hertz [Hz]. Query by GetBuffer. The frequency state of a buffer is set by BufferData calls.

Table 2. Buffer SIZE Attribute

Name	Signature	Values	Default
SIZE	sizei	[0, MAX_UINT]	0

Description: Size in bytes of the buffer data. Query through GetBuffer, can be set only using BufferData calls. Setting a SIZE of 0 is a legal NOP. The number of bytes does not necessarily equal the number of samples (e.g. for compressed data).

Querying Buffer Attributes

Buffer state is maintained inside the AL implementation and can be queried in full. The valid values for paramName are identical to the ones for Buffer*.

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

Specifying Buffer Content

A special case of Buffer state is the actual sound sample data stored in asociation with the Buffer. Applications can specify sample data using BufferData.

void BufferData{n}{sifd}{v} ( uint bufferName, enum format, void *; data , sizei size , uint frequency);

The data specified is copied to an internal software, or if possible, hardware buffer. The implementation is free to apply decompression, conversion, resampling, and filtering as needed. The internal format of the Buffer is not exposed to the application, and not accessible. Valid formats are FORMAT_MONO8, FORMAT_MONO16, FORMAT_STEREO8, and FORMAT_STEREO16. An implementation may expose other formats, see the chapter on Extensions for information on determining if additional formats are supported.

Applications should always check for an error condition after attempting to specify buffer data in case an implementation has to generate an OUT_OF_MEMORY or conversion related INVALID_VALUE error. The application is free to reuse the memory specified by the data pointer once the call to BufferData returns. The implementation has to dereference, e.g. copy, the data during BufferData execution.

<<< Previous	Home	Next >>>
Managing Buffer Names	Up	AL Contexts and the ALC API