Jump to: navigation, search

OpenGL has a particular Nomenclature, a system for naming functions that is followed consistently (mostly).

Function suffixes

Because OpenGL is cross-platform, it does not require a language that has function overloading. However, it does have many functions that conceptually do the same thing (so they have the same name), yet they have variations that take different parameter types. These functions are given unique names by adding type-based suffixes. OpenGL has a specific scheme for defining these suffixes.

Function type suffixes are typically defined in the following pattern:

FunctionName{1234}{b s i i64 f d ub us ui ui64}{v}

The first set of braces is an optional number from 1 to 4. This defines the number of parameters of those types that the function takes. The number is specified only if different variations of the function take different numbers of arguments.

The second set of braces defines the types themselves, as defined by this table:

Suffix OpenGL Type
b GLbyte​
s GLshort​
i GLint​
i64 GLint64​
ub GLubyte​
us GLushort​
ui GLuint​
ui64 GLuint64​
f GLfloat​
d GLdouble​

Therefore, the function glVertexAttrib3ub​ is the version of glVertexAttrib that takes 3 values, all of type GLubyte​.

The v​ suffix means that the function takes a "vector". That is, the function takes an array of values, defined by a pointer. If this suffix is used in conjunction with a number, then the array is expected to be exactly that many values. For example, glVertexAttrib3fv takes a GLfloat*​ that is expected to be an array of 3 floats.

When it is not used in conjunction with a number, the array's size will be based on some other parameter. In the case of glCreateShaderProgramv, the size is an explicit parameter. In the case of glSamplerParameterfv, the size is implicit based on the nature of the pname​ parameter. Different pname​ enumerators take different numbers of arguments.

v​ can also be used for output values. For example, glGetProgramResourceiv will write its results to the given array of integers. The size of the array that the user allocates is given to the function as a parameter, to help prevent buffer overruns.

Unusual suffixes

There are a few oddball type suffixes, particularly around querying common state data from the context. The glGet family of functions rather than using the standard type suffixes, they use a spelled typename. So there is glGetBooleanv, glGetIntegerv and so forth.

More unusual still is the use of the i_v​ suffix. This is used for querying indexed state, typically set by glEnablei/glDisablei. These function take an array of values (hence the v​ part), but they also take an integer index in addition to the enumerator (hence the i​ part. The underscore is there because it doesn't take an array of integer indices; it takes an array of the particular type. So glGetFloati_v takes an array of floats, using an integer index.

Not suffixes

There are some things which will look like type suffixes but are not. For example, there is the function glVertexAttribI4i. The I​ part is not a type suffix; the proper name for this function is glVertexAttribI​, because it has different behavior from the glVertexAttrib​ family than simply what type of data it takes. It doesn't merely take a different type; it treats the value in a very different way.

Function names and objects

The OpenGL object model is build around objects as containers of state. To access such objects, you first bind some state to a location in the context, then call functions that modify or read the bound state. As such, there are OpenGL functions that are closely associated with various objects.

OpenGL uses a semi-consistent naming convention for functions in this regard. Functions which modify the state of a bound object are of the form glOBJECT_NAME​*​, where OBJECT_NAME​ represents that object. Functions which read data from those objects are of the form glGetOBJECT_NAME​*​. Here are the object names and their common object types:

OpenGL Object Type Function Name
Texture Object "Tex"
Framebuffer Object "Framebuffer"
Buffer Object "Buffer"
Sampler Object "Sampler"
Query Object "Query"
Transform Feedback Objects "TransformFeedback"

However, OpenGL is only semi-consistent about this. OpenGL is consistent in that all functions of the form glOBJECT_NAME​*​ do indeed modify that object type's state. But most objects will have other functions not of that form which modify the object's state too. For example, glDrawBuffers and glReadBuffer both set framebuffer state, despite not being named glFramebufferDrawBuffers​ or glFramebufferReadBuffers​.

Similarly, not all state for an object is accessible through glGetOBJECT_NAME​*​ functions. OpenGL is more consistent about these, but there are still exceptions. For example, the current read and draw buffers cannot be queried with a glGetFramebuffer*​ call; you must use the generic glGetIntegerv for them.

Most of these cases are due to legacy issues. The read and draw buffers predates framebuffer objects entirely; originally, they were ordinary context state, not bound to an object. So to maintain backwards compatibility with existing code, they simply stated that the old functions modify objects rather than global state.

Direct state access

Direct State Access
Core in version 4.5
Core since version 4.5
Core ARB extension ARB_direct_state_access
EXT extension EXT_direct_state_access
V · E

The Nomenclature for Direct State Access is a bit more consistent than the non-DSA naming. Just as with functions that modify objects through the context, DSA functions apply an object-specific prefix to the function name. Unlike the context functions, all DSA functions consistently use the object prefix (even if it makes the function name unwieldy).

The unusual bit with DSA functions is that some of the prefixes will use Named​ as part of the prefix, while others do not. Fortunately, all functions within a particular object group will consistently use the same convention.

OpenGL Object Type Context Prefix DSA Prefix
Texture Object "Tex" "Texture"
Framebuffer Object "Framebuffer" "NamedFramebuffer"
Buffer Object "Buffer" "NamedBuffer"
Transform Feedback Object N/A1 "TransformFeedback"
Vertex Array Object "VertexAttrib" "VertexArray"
Sampler Object N/A2 "Sampler"
Query Object N/A2 "Query"
1: Transform feedback state consists only of the buffers bound to GL_TRANSFORM_FEEDBACK_BUFFER​ with glBindBufferRange, as well as a captured primitive count. As such, they never needed an object-based prefix. Direct state access gives transform feedback buffer attachment their own calls, so they need a prefix.
2: These object types already used DSA-style functions.

While these conventions are followed, there are functions where the object prefix does not come first in a function's name. All glGet​ functions put the object prefix after the "Get". This is also true for "Invalidate", "Map", "Unmap", "FlushMapped", "Enable", "Disable", "Clear", "Blit", "Copy", "Check", and "Compressed".