AL Errors

The AL detects only a subset of those conditions 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

enum GetError (void);

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).

NoteRFC: GL distributed error
 

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 of all flags is cleared and the initial value of all codes is NO_ERROR.

NoteAnnotation (Looping GetError)
 

AL applications are advised to loop calls of GetError to make sure that all flags are reset. Only the first error occurence for each flag/code pair is recorded, subsequent errors are ignored. The result of a repeated GetError call is not a stack trace or LIFO sequence. All error handling is context specific.

NoteAnnotation (Only First Error)
 

Like OpenGL AL will ignore subsequent errors once an error conditation has been encountered.

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.

NoteAnnotation/ Verbose Error String
 

There is no need to maintain a separate GetErrorString function (inspired by the proposed gluGetErrorStrings) as the existing GetString entry point can be used.

Table 2. Error Conditions

NameDescription
NO_ERROR"No Error" token.
INVALID_NAMEInvalid Name parameter.
INVALID_ENUMInvalid parameter.
INVALID_VALUEInvalid enum parameter value.
INVALID_OPERATIONIllegal call.
OUT_OF_MEMORYUnable to allocate memory.
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 zero. 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, not to system errors such as memory access errors.

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 if the argument is a pointer to a symbolic constant 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 AL objects such as Buffers and Sources are checked for validity. If an invalid name parameter is specified in an AL 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. The specification does not guarantee that the implementation emits INVALID_VALUE if a NaN or Infinity value is passed in for a float or double argument (as the specification does not enforce possibly expensive testing of floating point values).

Commands can be invalid. For example, certain commands might not be applicable to a given object. There are also illegal combinations of tokens and values as arguments to a command. AL responds to any such illegal command 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 independent of recent commands if AL 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.

NoteRFC: INVALID_SIZE?
 

Specific error case in which the size argument is negative, or mismatches internal conditions for a getter?

NoteRFC: INVALID_POINTER?
 

GL seemingly does not specify a response to NULL pointer destinations, and does not assign an error case. INVALID_VALUE could be used, also we could introduce a separate INVALID_POINTER. Is there a good reason not to catch these cases?