Nomenclature: Difference between revisions

From OpenGL Wiki
Jump to navigation Jump to search
(A few clarifications.)
(→‎Direct state access: Referencing the DSA nomenclature snippet.)
Line 102: Line 102:

=== Direct state access ===
=== Direct state access ===
{{infobox feature
| name = Direct State Access
| core = 4.5
| core_extension = {{extref|direct_state_access}}
| ext_extension = {{extref|direct_state_access|EXT}}
{{snippet|:Nomenclature/Direct State Access}}

[[Category:General OpenGL]]
[[Category:General OpenGL]]

Revision as of 04:56, 15 April 2015

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.6
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's functions is a bit more consistent than the non-DSA naming. As with non-DSA functions, they follow the standard Verb-Object-Command syntax. However, there were several non-DSA functions that affected some object's state without naming the Object type in its function. In the case of DSA, all DSA functions consistently specify the Object, even if it makes the function name unwieldy.

The difference is that DSA functions use a different Object​ name from the non-DSA functions. Because OpenGL is defined to be implemented in C, function overloading cannot be used. So DSA functions are differentiated from their non-DSA versions by using a different Object​ name.

There is an inconsistency in how this new Object​ name was chosen. For some object types, the new Object​ name is the old Object​ name prefixed with "Named". Others objects use a longer version of the original, non-DSA Object​ name. Fortunately, all functions that act on a particular object will consistently use the same Object​ name:

OpenGL Object Type Context Object Name DSA Object Name
Texture Object "Tex" "Texture"
Framebuffer Object "Framebuffer" "NamedFramebuffer"
Buffer Object "Buffer" "NamedBuffer"
Transform Feedback Object "TransformFeedback"1 "TransformFeedback"
Vertex Array Object N/A2 "VertexArray"
Sampler Object N/A3 "Sampler"
Query Object N/A3 "Query"
Program Object N/A3 "Program"
1: Transform feedback objects have a lot of functions that use TF objects in rendering operations. But the actual state in them consists only of the buffers attached to GL_TRANSFORM_FEEDBACK_BUFFER via glBindBufferRange, as well as a captured primitive count. As such, while they had a formal Object​ name, it was only used for functions that used the object for feedback operations rather than state-accessing functions. So the existing name could be appropriated for DSA functions (to attach buffers to the feedback object).
2: The functions that manipulate this object were so inconsistently named that there was never really a consistent object name for them.
3: These object types already used DSA-style functions. For program objects, DSA-style uniform setting (e.g. glProgramUniform) was added with separable programs in GL 4.2.

There are some functions which were introduced before OpenGL 4.5. These functions work in a DSA style, but use the old Object​ name. For example, glClearTexImage takes the texture object to be cleared as a parameter, rather than acting on context state. The DSA feature did not add variations on these that use the DSA-Object​ name.