ALC Queries

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.

NoteAnnotation (Exlicit Device Parameter)
 

Certain ALC Extensions might be relevant to context creation (like additional attributes, or support for unusual multi-context combinations), thus the application might have to query these before a context is created. On the other hand, ALC Extensions are specific to the device.

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

NameDescription
ALC_NO_ERRORThe device handle or specifier does name an accessible driver/server.
ALC_INVALID_DEVICEThe Context argument does not name a valid context.
ALC_INVALID_CONTEXTThe Context argument does not name a valid context.
ALC_INVALID_ENUMA token used is not valid, or not applicable.
ALC_INVALID_VALUEAn value (e.g. attribute) is not valid, or not applicable.

NoteAnnotation (No UNDERFLOW error)
 

Applications using synchronous (and, depending on CPU load, even an asynchronous implementation itself) might fail to prevent underflow of the rendering output buffer. No ALC error is generated in these cases, as it this error condition can not be applied to a specific command.

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

NameDescription
ALC_DEFAULT_DEVICE_SPECIFIERThe specifier string for the default device (NULL handle is legal).
ALC_DEVICE_SPECIFIERThe specifier string for the device (NULL handle is not legal).
ALC_EXTENSIONSThe 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

NameDescription
ALC_MAJOR_VERSIONMajor version query.
ALC_MINOR_VERSIONMinor version query.
ALC_ATTRIBUTES_SIZEThe 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_ATTRIBUTESExpects 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.

NoteAnnotation (Backward Compatibility)
 

Backward compatibility is guaranteed only for minor revisions. Breaking ABI backwards compatibility will require a issuing major revision.

NoteRFC / Version Matching
 

The ALC version can be different from the AL version. The ALC major version has to be identical between application and driver (client and server). The ALC minor version can differ between client and server, and the minimum of the two minor version numbers is returned.

NoteRFC / Device Enumeration
 

ALC_NUM_DEVICE_SPECIFIERS could be provided as an extension, but it requires the number of device configurations to be finite and small, as they are to be represented by strings.