7.6. Query Functions

The OpenGL Shading Language API contains several functions for querying object state. To obtain information about a shader object, use the following command:

void glGetShaderiv(GLuint shader,                                     GLenum pname,                                     GLint *params)

Returns in params the value of a parameter for a specific shader object. This function returns information about a shader object. Permitted parameters and their meanings are described in Table 7.1. In this table, the value for pname is shown on the left, and the operation performed is shown on the right. Table 7.1. Queriable shader object parameters Parameter Operation GL_SHADER_TYPE params returns a value of either GL_VERTEX_SHADER or GL_FRAGMENT_SHADER, depending on whether shader is the name of a vertex shader object or a fragment shader object. GL_DELETE_STATUS params returns GL_TRUE if shader is currently flagged for deletion, and GL_FALSE otherwise. GL_COMPILE_STATUS params returns GL_TRUE if the last compile operation on shader was successful, and GL_FALSE otherwise. GL_INFO_LOG_LENGTH params returns the number of characters in the information log for shader, including the null termination character. If the object has no information log, a value of 0 is returned. GL_SHADER_SOURCE_LENGTH params returns the length of the concatenation of the source strings that make up the shader source for shader, including the null termination character. If no source code exists, 0 is returned.

A similar function is provided for querying the state of a program object: the status of an operation on a program object, the number of attached shader objects, the number of active attributes (see Section 7.7), the number of active uniform variables (see Section 7.8), or the length of any of the strings maintained by a program object. The command to obtain information about a program object is

void glGetProgramiv(GLuint program,                                       GLenum pname,                                       GLint *params)

Returns in params the value of a parameter for a particular program object. This function returns information about a program object. Permitted parameters and their meanings are described in Table 7.2. In this table, the value for pname is shown on the left, and the operation performed is shown on the right. Table 7.2. Queriable program object parameters Parameter Operation GL_DELETE_STATUS params returns GL_TRUE if program is currently flagged for deletion, and GL_FALSE otherwise. GL_LINK_STATUS params returns GL_TRUE if the last link operation on program was successful, and GL_FALSE otherwise. GL_VALIDATE_STATUS params returns GL_TRUE if the last validation operation on program was successful, and GL_FALSE otherwise. GL_INFO_LOG_LENGTH params returns the number of characters in the information log for program, including the null termination character. If the object has no information log, a value of 0 is returned. GL_ATTACHED_SHADERS params returns the number of shader objects attached to program. GL_ACTIVE_ATTRIBUTES params returns the number of active attribute variables for program. GL_ACTIVE_ATTRIBUTE_MAX_LENGTH params returns the length of the longest active attribute variable name for program, including the null termination character. If no active attribute variables exist, 0 is returned. GL_ACTIVE_UNIFORMS params returns the number of active uniform variables for program. GL_ACTIVE_UNIFORM_MAX_LENGTH params returns the length of the longest active uniform variable name for program, including the null termination character. If no active uniform variables exist, 0 is returned.

The command to obtain the current shader string from a shader object is

void glGetShaderSource(GLuint shader                                               GLsizei bufSize,                                               GLsizei *length,                                               GLchar *source)

Returns a concatenation of the source code strings from the shader object specified by shader. The source code strings for a shader object are the result of a previous call to glShaderSource. The string returned by the function is null terminated. glGetShaderSource returns in source as much of the source code string as it can, up to a maximum of bufSize characters. The number of characters actually returned, excluding the null termination character, is specified by length. If the length of the returned string is not required, a value of NULL can be passed in the length argument. The size of the buffer required to store the returned source code string can be obtained by calling glGetShader with the value GL_SHADER_SOURCE_LENGTH.

Information about the compilation operation is stored in the information log for a shader object. Similarly, information about the link and validation operations is stored in the information log for a program object. The information log is a string that contains diagnostic messages and warnings. The information log may contain information useful during application development even if the compilation or link operation was successful. The information log is typically only useful during application development, and an application should not expect different OpenGL implementations to produce identical descriptions of error. To obtain the information log for a shader object, call

void glGetShaderInfoLog(GLuint shader,                                                GLsizei maxLength,                                                GLsizei *length,                                                GLchar *infoLog)

Returns the information log for the specified shader object. The information log for a shader object is modified when the shader is compiled. The string that is returned is null terminated. glGetShaderInfoLog returns in infoLog as much of the information log as it can, up to a maximum of maxLength characters. The number of characters actually returned, excluding the null termination character, is specified by length. If the length of the returned string is not required, a value of NULL can be passed in the length argument. The size of the buffer required to store the returned information log can be obtained by calling glGetShader with the value GL_INFO_LOG_LENGTH. The information log for a shader object is a string that may contain diagnostic messages, warning messages, and other information about the last compile operation. When a shader object is created, its information log is a string of length 0.

To obtain the information log for a program object, call

void glGetProgramInfoLog(GLuint program,                                                   GLsizei maxLength,                                                   GLsizei *length,                                                   GLchar *infoLog)

Returns the information log for the specified program object. The information log for a program object is modified when the program object is linked or validated. The string that is returned is null terminated. glGetProgramInfoLog returns in infoLog as much of the information log as it can, up to a maximum of maxLength characters. The number of characters actually returned, excluding the null termination character, is specified by length. If the length of the returned string is not required, a value of NULL can be passed in the length argument. The size of the buffer required to store the returned information log can be obtained by calling glGetProgram with the value GL_INFO_LOG_LENGTH. The information log for a program object is an empty string, a string containing information about the last link operation, or a string containing information about the last validation operation. It may contain diagnostic messages, warning messages, and other information. When a program object is created, its information log is a string of length 0.

The way the API is set up, you first need to perform a query to find out the length of the the information log (number of characters in the string). After allocating a buffer of the appropriate size, you can call glGetShaderInfoLog or glGetProgramInfoLog to put the information log string into the allocated buffer. You can then print it if you want to do so. Listing 7.2 shows a C function that does all this for a shader object. The code for obtaining the information log for a program object is almost identical.

Listing 7.2. C function to print the information log for an object

void printShaderInfoLog(GLuint shader) { int infologLen = 0; int charsWritten = 0; GLchar *infoLog; glGetShaderiv(shader, GL_INFO_LOG_LENGTH, &infologLen); printOpenGLError(); // Check for OpenGL errors if (infologLen > 0) { infoLog = (GLchar*) malloc(infologLen); if (infoLog == NULL) { printf("ERROR: Could not allocate InfoLog buffer\n"); exit(1); } glGetShaderInfoLog(shader, infologLen, &charsWritten, infoLog); printf("InfoLog:\n%s\n\n", infoLog); free(infoLog); } printOpenGLError(); // Check for OpenGL errors }

You can obtain the program object that is currently in use by calling glGet with the symbolic constant GL_CURRENT_PROGRAM.

The command to query a list of shader objects attached to a particular program object is

void glGetAttachedShaders(GLuint program,                                                     GLsizei maxCount,                                                     GLsizei *count,                                                     GLuint *shaders)

Returns the handles of the shader objects attached to program. It returns in shaders as many of the handles of these shader objects as it can, up to a maximum of maxCount. The number of handles actually returned is specified by count. If the number of handles actually returned is not required (for instance, if it has just been obtained with glGetProgram), a value of NULL may be passed for count. If no shader objects are attached to program, a value of 0 is returned in count. The actual number of attached shaders can be obtained by calling glGetProgram with the value GL_ATTACHED_SHADERS.

Two new functions have been added to determine whether an object is a shader object or a program object. These functions may be useful if you have to process an object (for instance, to print its information log) without knowing whether it is a valid shader or program object. These two functions are defined as

GLboolean glIsShader(GLuint shader)
Returns GL_TRUE if shader is the name of a shader object. If shader is zero or a non-zero value that is not the name of a shader object, glIsShader returns GL_FALSE.

GLboolean glIsProgram(GLuint program)
Returns GL_TRUE if program is the name of a program object. If program is zero or a non-zero value that is not the name of a program object, glIsProgram returns GL_FALSE.