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.

	Annotation (No Frequency enumeration)
	As the implementation has to support conversion from one frequency to another to implement pitch, it is feasible to offer support for arbitrary sample frequencies, instead of restricting the application to an enumeration of supported sample frequencies. Another reason not to limit frequency to an enumerated set is that future hardware might support variable frequencies as well (it might be preferable to choose the sampling frequency according to the PSD of the signal then). However, it is desirable to avoid conversions due to differences between the sample frequency used in the original data, the frequency supported during the mixing, and the frequency expected by the output device.

Annotation (No Frequency enumeration)

As the implementation has to support conversion from one frequency to another to implement pitch, it is feasible to offer support for arbitrary sample frequencies, instead of restricting the application to an enumeration of supported sample frequencies. Another reason not to limit frequency to an enumerated set is that future hardware might support variable frequencies as well (it might be preferable to choose the sampling frequency according to the PSD of the signal then).

However, it is desirable to avoid conversions due to differences between the sample frequency used in the original data, the frequency supported during the mixing, and the frequency expected by the output device.

	Annotation (Implied Frequency)
	To account for the possibility of future AL implementations supporting encoding formats for the application might not want, or be able, to retrieve the actual frequency from the encoded sample, the specification will be amended to guarantee the following behavior: If a nonzero frequency is specified, it will force a conversion from the actual to the requested frequency. If the application specifies a 0 frequency, AL will use the actual frequency. If there is no frequency information implied by the format or contained in the encoded data, specifying a 0 frequency will yield INVALID_VALUE. It is recommended that applications use NONE instead of the literal value.

Annotation (Implied Frequency)

To account for the possibility of future AL implementations supporting encoding formats for the application might not want, or be able, to retrieve the actual frequency from the encoded sample, the specification will be amended to guarantee the following behavior: If a nonzero frequency is specified, it will force a conversion from the actual to the requested frequency. If the application specifies a 0 frequency, AL will use the actual frequency. If there is no frequency information implied by the format or contained in the encoded data, specifying a 0 frequency will yield INVALID_VALUE. It is recommended that applications use NONE instead of the literal value.

	Annotation (No Format query)
	As of this time there is no query for FORMAT, or format related state information. Query of the channels or bits of a given buffer make little sense if the query the internal (canonical, not buffer specific) format. Query of the original sample data format makes little sense unless the implementation is obliged to preserve the original data.

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