Object Paradigm

AL is an object-oriented API, but it does not expose classes, structs, or other explicit data structures to the application.

Object Categories

AL has three primary categories of Objects:

In the following, "{Object}" will stand for either Source, Listener, or Buffer.

Static vs. Dynamic Objects

The vast majority of AL objects are dynamic, and will be created on application demand. There are also AL objects that do not have to be created, and can not be created, on application demand. Currently, the Listener is the only such static object in AL.

Object Names

Dynamic Objects are manipulated using an integer, which in analogy to OpenGL is referred to as the object's "name". These are of type unsigned integer (uint). Names can be valid beyond the lifetime of the context they were requested if the objects in question can be shared among contexts. No guarantees or assumptions are made in the specification about the precise values or their distribution over the lifetime of the application. As objects might be shared, Names are guaranteed to be unique within a class of AL objects, but no guarantees are made across different classes of objects. Objects that are unique (singletons), like the Listener, do not require and do not have an integer "name".

Requesting Object Names

AL provides calls to obtain Object Names. The application requests a number of Objects of a given category using Gen{Object}s. If the number n of Objects requested is negative, an INVALID_VALUE error will caused. The actual values of the Names returned are implementation dependent. No guarantees on range or value are made. Unlike OpenGL OpenAL does not offer alternative means to define (bind) a Name.

Allocation of Object Names does not imply immediate allocation of resources or creation of Objects: the implementation is free to defer this until a given Object is actually used in mutator calls. The Names are written at the memory location specified by the caller.

void Gen{Object}s ( sizei n , uint * objectNames );

Requesting zero names is a legal NOP. Requesting a negative number of names causes an INVALID_VALUE error. AL will respond with an OUT_OF_MEMORY if the application requests too many objects. The specification does not guarantee that the AL implementation will allocate all resources needed for the actual objects at the time the names are reserved. In many cases (Buffers) this could only be implemented by worst case estimation. Allocation of names does not guarantee that all the named objects can actually be used.

NoteAnnotation (No application selected Names)
 

Unlike GL, applications are not free to choose Names; all Names have to be requested. Aside from possible benefits for the implementation, and avoidance of errors in projects that have many modules using the AL implementation (a problem encountered in GL, when the two generation mechanisms are mixed), this also leaves open the door to feed different kinds of objects by Name through the same API entry points.

NoteAnnotate (Negative/zero sizei)
 

The specification does not guarantee that sizei is an unsigned integer, but legal values have to be non-negative. However, requesting zero names is a legal NOP.

NoteRFC: Resource Release Hint
 

Do we need a hint that resource release has to be done on DeleteXXX, instead of leaving this housekeeping to AL?

NoteRFC: Zero Name
 

Do we reserve the name "0"? OpenGL provides an alternative mechanism which lets the application pick texture names, which we discarded because it is prone to create error conditions when mixing both approaches. As all our names are generated using GenXXXX, there is no real need to treat "0" special.

Releasing Object Names

AL provides calls to the application to release Object Names using Delete{Object}s, implicitly requesting deletion of the Objects associated with the Names released. If the number n of Objects named is negative, an INVALID_VALUE error will be caused. If one or more of the specified Names is not valid, an INVALID_NAME error will be caused. Implementation behavior following any error is undefined.

Once deleted (even if an error occured on deletion), the Names are no longer valid for use with any AL function calls including calls to Delete{Objects}s. Any such use will cause an INVALID_NAME error.

The AL implementation is free to defer actual release of resources. Ideally, resources should be released as soon as possible, but no guarantees are made.

void Delete{Object}s(sizei n, uint *objectNames);

NoteAnnotation
 

GenXXX and DeleteXXX can not reasonably be expected to be used for controlling driver-side resource management from the application. A driver might never release a Source once allocated during the lifetime of the application.

NoteRFC: Deletion Errors
 

chasan@acm.org: What happens if an active source (or its associated buffer) is deleted? The source should be stopped? Or the delete operation is invalid?

Validating an Object Name

AL provides calls to validate the Name of an Object. The application can verify whether an Object Name is valid using the Is{Object} query. There is no vector (array) version of this function as it defeats the purpose of unambiguous (in)valdiation. Returns TRUE if id is a valid Object Name, and FALSE otherwise. Object Names are valid between request (Gen{Object}s) and release (Delete{Object}s). Is{Object} does not distinguish between invalid and deleted Names.

boolean Is{Object}(uint objectName);

NoteRFC/bk000504:
 

If zero is a valid name, this function will have to accept it without an actyual object (or only an internal dummy) being associated with it. I recommend that implementations never return "0" as an object name.

Setting Object Attributes

For AL Objects, calls to control their attributes are provided. These depend on the actual properties of a given Object Category. The precise API is discussed for each category, below. Each AL command affecting the state of a named Object is usually of the form

void {Object}{n}{sifd}{v} ( uint objectName , enum paramName , T values );

In the case of unnamed (unique) Objects, the (integer) objectName is omitted, as it is implied by the {Object} part of function name:

void {Object}{n}{sifd}{v} ( enum paramName , T values );

For example, the Listener3d command would not require an (integer) objectName argument.

The objectName specifies the AL object affected by this call. Use of an invalid Name will cause an INVALID_NAME error.

The Object's Attribute to be affected has to be named as paramName. AL parameters applicable to one category of Objects are not necessarily legal for another catetgory of AL Objects. Specification of a parameter illegal for a given object will cause an INVALID_OPERATION error.

Not all possible values for a type will be legal for a given objectName and parameterName. Use of an illegal value or a NULL value pointer will cause an INVALID_VALUE error.

Any command that causes an error is a NOP.

Querying Object Attributes

For named and for unique AL Objects, calls to query their current attributes are provided. These depend on the actual properties of a given Object Category. The performance of such queries is implementation dependent, no performance guarantees are made. The valid values for the parameter paramName are identical to the ones legal for the complementing attribute setting function.

void Get{Object}{n}{sifd}{v} ( uint objectName , enum paramName , T * destination );

For unnamed unique Objects, the objectName is omitted as it is implied by the function name:

void Get{Object}{n}{sifd}{v} ( enum paramName , T * destination );

The precise API is discussed for each category separately, below. Unlike their matching mutators, Query functions for non-scalar properties (vectors etc.) are only available in array form.

Use of an invalid Name will cause an INVALID_NAME error. Specification of an illegal parameter type (token) will cause an INVALID_ENUM error. A call with a destination NULL pointer will be quietly ignored. The AL state will not be affected by errors. In case of errors, destination memory will not be changed.

Object Attributes

Attributes affecting the processing of sounds can be set for various AL Object categories, or might change as an effect of AL calls. The vast majority of these Object properties are specific to the AL Object category, in question, but some are applicable to two or more categories, and are listed separately.

The general form in which this document describes parameters is

Table 3. {Object} Parameters

NameSignatureValuesDefault
paramNameT range or set scalar or n-tuple
Description: The description specifies additional restrictions and details. paramName is given as the AL enum defined as its name. T can be a list of legal signatures, usually the array form as well as the flat (unfolded) form.

NoteRFC: Initial (Default) State
 

The default state of objects will have to be specified here. There will be no commands that allow the application to set other defaults.