This appendix provides some background information on OpenGL command names, defined types, and error handling. It's intended mainly as a quick reference. For more detailed information, refer to the OpenGL Programming Guide.
This section describes the naming convention for OpenGL calls. For a complete list of OpenGL equivalents to IRIS GL routines, see Appendix A, “OpenGL Commands and Their IRIS GL Equivalents.”
gl—OpenGL commands begin with the gl prefix (glEnable(), glTranslatef(), and so on).
glu—OpenGL Utility Library (GLU) commands begin with the glu prefix (gluDisk(), gluErrorString(), and so on).
glX—Commands that belong to the OpenGL extension to X (GLX) begin with the glX prefix (glXChooseVisual(), glXCopyContext(), and so on).
glut—Commands in the GLUT (OpenGL Utility Toolkit) library begin with a glut prefix (glutInit, glutMenuStatusFunc, and so on).
OpenGL commands are formed by a root name, optionally followed by up to four characters. The first character indicates the number of arguments. The second character, or pair of characters, specifies the type of the arguments. Table C-1 lists the character suffixes and the corresponding argument types (some of these values might be different on a 64-bit architecture).
Table C-1. Command Suffixes and Corresponding Argument Types
Letter | Type | C Type |
|---|---|---|
b | 8-bit integer | char |
s | 16-bit integer | short |
i | 32-bit integer | long |
f | 32-bit floating point | float |
d | 64-bit floating point | double |
ub | 8-bit unsigned integer | unsigned char |
us | 16-bit unsigned integer | unsigned short |
ui | 32-bit unsigned integer | unsigned long |
The final character, if present, is v. The v indicates that the command takes a pointer to an array of values—a vector—rather than a series of individual arguments.
IRIS GL used a similar mechanism for some commands. The predecessor to glVertex*(), for example, was v(), which also used a suffix to specify the number and type of its arguments.
Here are some examples of OpenGL command naming:
void glVertex2i( GLint x, GLint y); |
void glVertex3f( GLfloat x, GLfloat y, GLfloat z); void glVertex3dv( const GLdouble *v) ; |
The first version of the vertex call, glVertex2i(), takes two integer arguments. The second, glVertex3f(), is a three-dimensional version, which expects three floats. The third version, glVertex3dv(), expects an argument in the form of a vector, which is a pointer to an array. In this case, the array should have three elements.
Table C-2 lists C data types and their equivalent OpenGL defined types.
Table C-2. OpenGL Equivalents to C Data Types
C Type | Equivalent OpenGL Type |
|---|---|
bitmask value | GLbitfield |
boolean value | GLboolean |
double | GLdouble |
double value clamped to [ 0.0, 1.0 ] | GLclampd |
enumerated type | GLenum |
float | GLfloat |
float value clamped to [ 0.0, 1.0 ] | GLclampf |
long | GLint |
short | GLshort |
signed char | GLbyte |
unsigned char | GLubyte |
unsigned int | GLuint |
unsigned short | GLushort |
void | GLvoid |
When an error occurs, OpenGL sets an error flag to the appropriate error value. You can test error conditions using the glGetError() call, which returns the error number. Table C-3 lists possible error values. For details, see the reference page for glGetError().
Table C-3. glGetError() Return Values
Error | Description | Command Ignored? |
|---|---|---|
NO_ERROR | No error | No |
INVALID_ENUM | Enumerated argument out of range | Yes |
INVALID_VALUE | Numeric argument out of range | Yes |
INVALID_OPERATION | Operation illegal in current state | Yes |
STACK_OVERFLOW | Command would cause a stack overflow | Yes |
STACK_UNDERFLOW | Command would cause a stack underflow | Yes |
OUT_OF_MEMORY | Not enough memory left to execute command | Unknown |