Error Handling (OpenGL Programming)

The truth is, your program will make mistakes. Use of error-handling routines is essential during development and is highly recommended for commercially released applications (unless you can give a 100 percent guarantee your program will never generate an OpenGL error condition. Get real!). OpenGL has simple error-handling routines for the base GL and GLU libraries.

When OpenGL detects an error (in either the base GL or GLU), it records a current error code. The command that caused the error is ignored, so it has no effect on the OpenGL state or on the framebuffer contents. (If the error recorded was GL_OUT_OF_MEMORY, however, the results of the command are undefined.) Once recorded, the current error code isn’t cleared—that is, additional errors aren’t recorded—until you call the query command glGetError(), which returns the current error code. After you’ve queried and cleared the current error code, or if there’s no error to begin with, glGetError() returns GL_NO_ERROR.

Glenum glGetError(void);

Returns the value of the error flag. When an error occurs in either the GL or the GLU, the error flag is set to the appropriate error code value. If GL_NO_ERROR is returned, there has been no detectable error since the last call to glGetError() or since the GL was initialized. No other errors are recorded until glGetError() is called, the error code is returned, and the flag is reset to GL_NO_ERROR.


It is strongly recommended that you call glGetError() at least once in each display() routine. Table 14-1 lists the basic defined OpenGL error codes.

Error Code

Description

GL_INVALID_ENUM

GLenum argument out of range

GL_INVALID_VALUE

numeric argument out of range

GL_INVALID_OPERATION

operation illegal in current state

GL_STACK_OVERFLOW

command would cause a stack overflow

GL_STACK_UNDERFLOW

command would cause a stack underflow

GL_OUT_OF_MEMORY

not enough memory left to execute command

Table 14-1 OpenGL Error Codes

There are also 37 GLU NURBS errors (with nondescriptive constant names, GLU_NURBS_ERRORl, GLU_NURBS_ERROR2, and so on); 14 tessellator errors (GLU_TESS_MISSING_BEGIN_POLYGON, GLU_TESS_MISSING_ END_POLYGON, GLU_TESS_MISSING_BEGIN_CONTOUR, GLU_TESS_ MISSING_END_CONTOUR, GLU_TESS_COORD_TOO_LARGE, GLU_TESS_ NEED_COMBINE_CALLBACK, along with eight errors generically named GLU_TESS_ERROR*); and GLU_INCOMPATIBLE_GL_VERSION. Also, the GLU defines the error codes GLU_INVALID_ENUM, GLU_INVALID_VALUE, and GLU_OUT_OF_MEMORY, which have the same meanings as the related OpenGL codes.

To obtain a printable, descriptive string corresponding to either a GL or GLU error code, use the GLU routine gluErrorString().

const GLubyte* gluErrorString(GLenum enorCode);

Returns a pointer to a descriptive string that corresponds to the OpenGL or GLLT error number passed in enorCode.

In Example 14-1, a simple error-handling routine is shown.

Example 14-1 Querying and Printing an Error

Querying and Printing an Error

Note: The string returned by gluErrorString() must not be altered or freed by the application.

Next post:

Previous post: