Managing Buffer Names

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

Buffer Attributes

Table 1. Buffer FREQUENCY Attribute

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

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

	Annotation/ variable Frequency attribute
	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/ variable Frequency attribute

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 IMPLIED 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 IMPLIED 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	ui	[0, MAX_UINT]	0

Description: Size in bytes of the buffer data. Specifying a SIZE of 0 is a legal NOP. The number of bytes does not equal the number of samples (e.g. for compressed data).

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

Querying Buffer Attributes

Buffer state is maintained inside the OpenAL implementation and can be queried in full. The valid values for the param parameter 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 data for non-streaming Buffers 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.

<<< Previous	Home	Next >>>
Managing Buffer Names	Up	Processing Queue