OpenGL Object/Object Name

From OpenGL Wiki
Jump to navigation Jump to search

OpenGL Objects, as well as the non-standard objects like Program Objects and Sync Objects, are very useful. However, their names are non-intuitive; they are just numbers (or pointers in the case of sync objects). Furthermore, those numbers are defined by the system, rather than by the user. This makes debugging with objects difficult.

However, OpenGL has a mechanism to associate an arbitrary string name with any object. This also permits system-generated messages to be able to talk about an object by its string name. The functions to set the name for an object are:

void glObjectLabel(GLenum identifier​, GLuint name​, GLsizei length​, const char * label​);

void glObjectPtrLabel(void * ptr​, GLsizei length​, const char * label​);

The first function is used to set all objects that use GLuints for their object types. This means all OpenGL Objects, as well as all Shader/Program Object types. The second function sets the name for Sync Objects.

Identifier Object Type
GL_BUFFER Buffer Object
GL_SHADER Shader object
GL_PROGRAM Program Object
GL_VERTEX_ARRAY Vertex Array Object
GL_QUERY Query Object
GL_PROGRAM_PIPELINE Program Pipeline Object
GL_TRANSFORM_FEEDBACK Transform Feedback Object
GL_SAMPLER Sampler Object
GL_TEXTURE Texture Object
GL_RENDERBUFFER Renderbuffer Object
GL_FRAMEBUFFER Framebuffer Object

For GLuint-based objects, the object name alone is not enough to identify the object, since two objects of different object types may have the same GLuint name. Therefore, the type is specified by the identifier​ parameter, which must be one of the enumerators on the left.

The length​ specifies the length of the string label​, which must be less than GL_MAX_LABEL_LENGTH (which will be no less than 256).

The name of an object may be used by debug output messages that reference this object. This is not a requirement, but it can be useful for debugging purposes.


To retrieve the name of an object, you use these functions:

void glGetObjectLabel(GLenum identifier​, GLuint name​, GLsizei bufSize​, GLsizei * length​, char * label​);

void glGetObjectPtrLabel(void * ptr​, GLsizei bufSize​, GLsizei * length​, char * label​);

The bufSize​ is the total number of bytes in label​; the function will not copy more than this many bytes (including a null-terminator) into label​. If length​ is not NULL, then the function will store the number of characters written into the buffer (including the NULL pointer). If label​ is NULL, then the total length of the string will be copied into length​. If both are NULL, an error results.