ALC Queries

OpenAL Specification and Reference
<<< Previous	AL Contexts and the ALC API	Next >>>

Query for Current Context

The application can query for, and obtain an handle to, the current context for the application. If there is no current context, NULL is returned.

ALCcontext * alcGetCurrentContext(void);

Query for a Context's Device

The application can query for, and obtain an handle to, the device of a given context.

ALCdevice * alcGetContextsDevice( ALCcontext * context );

Query For Extensions

To verify that a given extension is available for the current context and the device it is associated with, use

boolean IsExtensionPresent( const ALCdevice * deviceHandle, const ubyte * extName );

A NULL name argument returns FALSE, as do invalid and unsupported string tokens. A NULL deviceHandle will result in an INVALID_DEVICE error.

Query for Function Entry Addresses

The application is expected to verify the applicability of an extension or core function entry point before requesting it by name, by use of alcIsExtensionPresent.

void * alcGetProcAddress( const ALCdevice * deviceHandle, const ubyte * funcName );

Entry points can be device specific, but are not context specific. Using a NULL device handle does not guarantee that the entry point is returned, even if available for one of the available devices. Specifying a NULL name parameter will cause an ALC_INVALID_VALUE error.

Retrieving Enumeration Values

Enumeration/token values are device independend, but tokens defined for extensions might not be present for a given device. Using a NULL handle is legal, but only the tokens defined by the AL core are guaranteed. Availability of extension tokens dependends on the ALC extension.

uint alcGetEnumValue ( const ALCdevice * deviceHandle, const ubyte enumName );

Specifying a NULL name parameter will cause an ALC_INVALID_VALUE error.

Query for Error Conditions

ALC uses the same conventions and mechanisms as AL for error handling. In particular, ALC does not use conventions derived from X11 (GLX) or Windows (WGL). The alcGetError function can be used to query ALC errors.

enum alcGetError( ALCdevice * deviceHandle);

Error conditions are specific to the device.

Table 2. Error Conditions

Name	Description
ALC_NO_ERROR	The device handle or specifier does name an accessible driver/server.
ALC_INVALID_DEVICE	The Context argument does not name a valid context.
ALC_INVALID_CONTEXT	The Context argument does not name a valid context.
ALC_INVALID_ENUM	A token used is not valid, or not applicable.
ALC_INVALID_VALUE	An value (e.g. attribute) is not valid, or not applicable.

String Query

The application can obtain certain strings from ALC.

const ubyte * alcGetString( ALCdevice * deviceHandle, enum token );

For some tokens, NULL is is a legal value for the deviceHandle. In other cases, specifying a NULL device will generate an ALC_INVALID_DEVICE error.

Table 3. String Query Tokens

Name	Description
ALC_DEFAULT_DEVICE_SPECIFIER	The specifier string for the default device (NULL handle is legal).
ALC_DEVICE_SPECIFIER	The specifier string for the device (NULL handle is not legal).
ALC_EXTENSIONS	The extensions string for diagnostics and printing.

In addition, printable error message strings are provided for all valid error tokens, including ALC_NO_ERROR, ALC_INVALID_DEVICE, ALC_INVALID_CONTEXT, ALC_INVALID_ENUM, ALC_INVALID_VALUE.

Integer Query

The application can query ALC for information using an integer query function.

void alcGetIntegerv( ALCdevice * deviceHandle, enum token , sizei size , int dest );

For some tokens, NULL is a legal deviceHandle. In other cases, specifying a NULL device will generate an ALC_INVALID_DEVICE error. The application has to specify the size of the destination buffer provided. A NULL destination or a zero size parameter will cause ALC to ignore the query.

Table 4. Integer Query Tokens

Name	Description
ALC_MAJOR_VERSION	Major version query.
ALC_MINOR_VERSION	Minor version query.
ALC_ATTRIBUTES_SIZE	The size required for the zero-terminated attributes list, for the current context. NULL is an invalid device. NULL (no current context for the specified device) is legal.
ALC_ALL_ATTRIBUTES	Expects a destination of ALC_CURRENT_ATTRIBUTES_SIZE, and provides the attribute list for the current context of the specified device. NULL is an invalid device. NULL (no current context for the specified device) will return the default attributes defined by the specified device.

<<< Previous	Home	Next >>>
Managing Rendering Contexts	Up	Shared Objects