AL Errors

The AL detects only a subset of those conditionsd that could be considered errors. This is because in many cases error checking would adversely impact the performance of an error-free program. The command

is used to obtain error information. Each detectable error is assigned a numeric code. When an error is detected by AL, a flag is set and the error code is recorded. Further errors, if they occur, do not affect this recorded code. When GetError is called, the code is returned and the flag is cleared, so that a further error will again record its code. If a call to GetError returns NO_ERROR then there has been no detectable error since the last call to GetError (or since the AL was initialized).

To allow for distributed implementations there may be several flag/code pairs. In this case, after a call to GetError returns a value other than NO_ERROR each subsequent call returns the non-NO_ERROR code of another distinct flag-code pair (in unspecified order), until all NO_ERROR codes have been returned. When there are no more non-NO_ERROR codes, all flags be reset. The initial state pf all flags is cleared and the initial value of all codes is NO_ERROR.

Error codes can be mapped to strings. The GetString function returns a pointer to a constant (literal) string that is identical to the identifier used for the enumeration value, as defined in the specification.

The table summarizes the AL errors. Currently, when an error flag is set, results of AL operations are undefined only if OUT_OF_MEMORY has occured. In other cases, the command generating the error is ignored so that it has no effect on AL state or output buffer contents. If the error generating command returns a value, it returns zro. If the generating command modifies values through a pointer argument, no change is made to these values. These error semantics apply only to AL errors, noot to system errors such as memory access errors. This behavior is the current behavior, the action of the AL in the presence of errors is subject to change.

Several error generation conditions are implicit in the description of the various AL commands. First, if a command that requires an enumerated value is passed a value that is not one of those specified as allowable for that command, the error INVALID_ENUM results. This is the case even iof the argument is a pointer to a value if that value is not allowable for the given command. This will occur whether the value is allowable for other functions, or an invalid integer value.

Integer parameters that are used as names for OpenAL objects such as Buffers, Sources, are checked for validity. If an invalid name parameter is specified in an OpenAL command, an INVALID_NAME error will be generated, and the command is ignored.

If a negative integer is provided where an argument of type sizei is specified, the error INVALID_VALUE results. The same error will result from attempts to set integral and floating point values for attributes exceeding the legal range for these. There is no obligation on the implementation to emit INVALID_VALUE if a NaN or Infinity value is passed in for a float or double argument.

Illegal commands are using a valid target (e.g. name), a valid parameter enum, and/or valid parameter values, in an illegal combination. OpenAL has several such mutually exclusive commands operating on similar objects. One example is treating a streaming buffer as a non-streaming buffer, another is appending data to a non-streaming buffer. OpenAL responds to any such illegal combination with an INVALID_OPERATION error.

If memory is exhausted as a side effect of the execution of an AL command, either on system level or by exhausting the allocated resources at AL's internal disposal, the error OUT_OF_MEMORY may be generated. This can also happen independend of recent commands if OpenAL has to request memory for an internal task and fails to allocate the required memory from the operating system.

Otherwise errors are generated only for conditions that are explicitely described in this specification.