Nomenclature

From OpenGL.org
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 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 is an optional suffix. It instead means a "vector". That is, the function takes an array of values, defined by a pointer. If it 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 will be restricted to an expected size 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 will yield different results.

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 is provided 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 is very strange. 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.