Difference between revisions of "Nomenclature/Direct State Access"

From OpenGL Wiki
Jump to navigation Jump to search
(Adding page about DSA nomenclature. It's a subpage so that it can be included in the nomenclature article as well as the DSA page.)
 
m
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The {{pagelink|Nomenclature}} for {{pagelink|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 {{pagelink|Nomenclature}} for {{pagelink|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 unusual bit with DSA functions is that some of the prefixes will use {{code|Named}} as part of the prefix, while others do not. Fortunately, all functions within a particular object group will consistently use the same convention.
+
The difference is that DSA functions use a different {{param|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 {{param|Object}} name.
 +
 
 +
There is an inconsistency in how this new {{param|Object}} name was chosen. For some object types, the new {{param|Object}} name is the old {{param|Object}} name prefixed with "{{code|Named}}". Others objects use a longer version of the original, non-DSA {{param|Object}} name. Fortunately, all functions that act on a particular object will consistently use the same {{param|Object}} name:
  
 
{|class="wikitable"
 
{|class="wikitable"
 
!OpenGL Object Type
 
!OpenGL Object Type
!Context Prefix
+
!Context Object Name
!DSA Prefix
+
!DSA Object Name
 
|-
 
|-
 
|[[Texture|Texture Object]]
 
|[[Texture|Texture Object]]
Line 21: Line 23:
 
|-
 
|-
 
|[[Transform Feedback Object]]
 
|[[Transform Feedback Object]]
|N/A<sup>1</sup>
+
|"TransformFeedback"<sup>1</sup>
 
|"TransformFeedback"
 
|"TransformFeedback"
 
|-
 
|-
 
|[[Vertex Array Object]]
 
|[[Vertex Array Object]]
|"VertexAttrib"
+
|N/A<sup>2</sup>
 
|"VertexArray"
 
|"VertexArray"
 
|-
 
|-
 
|[[Sampler Object]]
 
|[[Sampler Object]]
|N/A<sup>2</sup>
+
|N/A<sup>3</sup>
 
|"Sampler"
 
|"Sampler"
 
|-
 
|-
 
|[[Query Object]]
 
|[[Query Object]]
|N/A<sup>2</sup>
+
|N/A<sup>3</sup>
 
|"Query"
 
|"Query"
 +
|-
 +
|[[Program Object]]
 +
|N/A<sup>3</sup>
 +
|"Program"
 
|}
 
|}
  
:<sup>1</sup>: Transform feedback state consists only of the buffers bound to {{enum|GL_TRANSFORM_FEEDBACK_BUFFER}} with {{apifunc|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.</br>
+
:<sup>1</sup>: 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 {{enum|GL_TRANSFORM_FEEDBACK_BUFFER}} via {{apifunc|glBindBufferRange}}, as well as a captured primitive count. As such, while they had a formal {{param|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).</br>
:<sup>2</sup>: These object types already used DSA-style functions.
+
:<sup>2</sup>: The functions that manipulate this object were so inconsistently named that there was never really a consistent object name for them.
 +
:<sup>3</sup>: These object types already used DSA-style functions. For program objects, DSA-style uniform setting (e.g. {{apifunc|glProgramUniform}}) was added with separable programs in GL 4.2.
  
While these conventions are followed, there are functions where the object prefix does not come first in a function's name. All {{code|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".
+
There are some functions which were introduced before OpenGL 4.5. These functions work in a DSA style, but use the old {{param|Object}} name. For example, {{apifunc|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-{{param|Object}} name.

Latest revision as of 08:34, 2 July 2018

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.