• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    ARB_transform_feedback_overflow_query
4
5Name Strings
6
7    GL_ARB_transform_feedback_overflow_query
8
9Contact
10
11    Brian Paul, VMware Inc. (brianp 'at' vmware.com)
12
13Contributors
14
15    Brian Paul, VMware
16    Daniel Rakos, AMD
17    Daniel Koch, NVIDIA
18
19Notice
20
21    Copyright (c) 2014 The Khronos Group Inc. Copyright terms at
22        http://www.khronos.org/registry/speccopyright.html
23
24Specification Update Policy
25
26    Khronos-approved extension specifications are updated in response to
27    issues and bugs prioritized by the Khronos OpenGL Working Group. For
28    extensions which have been promoted to a core Specification, fixes will
29    first appear in the latest version of that core Specification, and will
30    eventually be backported to the extension document. This policy is
31    described in more detail at
32        https://www.khronos.org/registry/OpenGL/docs/update_policy.php
33
34Status
35
36    Complete.
37    Approved by the ARB on June 26, 2014.
38    Ratified by the Khronos Board of Promoters on August 7, 2014.
39
40Version
41
42    Date: May 29, 2017
43    Revision: 5
44
45Number
46
47    ARB Extension #173
48
49Dependencies
50
51    OpenGL 3.0 is required.
52
53    The extension is written against the OpenGL 4.4 Specification, Core
54    Profile, March 19, 2014.
55
56    OpenGL 4.0 and ARB_transform_feedback3 affect the definition of this
57    extension.
58
59Overview
60
61    This extension adds new query types which can be used to detect overflow
62    of transform feedback buffers. The new query types are also accepted by
63    conditional rendering commands.
64
65IP Status
66
67    No known IP claims.
68
69New Procedures and Functions
70
71    None.
72
73New Tokens
74
75    Accepted by the <target> parameter of BeginQuery, EndQuery,
76    BeginQueryIndexed, EndQueryIndexed, GetQueryiv, and GetQueryIndexediv:
77
78        TRANSFORM_FEEDBACK_OVERFLOW_ARB                 0x82EC
79        TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB          0x82ED
80
81Additions to Chapter 4 of the OpenGL 4.4 (Core Profile) Specification (Event Model)
82
83    Modify Section 4.2, Query Objects and Asynchronous Queries
84
85    (add new bullet after second bullet on p. 39)
86
87      * Transform feedback overflow queries return information on whether or
88        not transform feedback overflow happened for one or more streams
89        (see section 13.x).
90
91    (modify errors section for BeginQueryIndexed on p. 40)
92
93    An INVALID_ENUM error is generated if <target> is not SAMPLES_PASSED,
94    ... for a primitives written query; or TRANSFORM_FEEDBACK_OVERFLOW_ARB
95    or TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB for a transform feedback
96    overflow query.
97
98    An INVALID_VALUE error is generated if <target> is SAMPLES_PASSED ...
99    TIME_ELAPSED, or TRANSFORM_FEEDBACK_OVERFLOW_ARB, and <index> is not
100    zero.
101
102    An INVALID_VALUE error is generated if <target> is PRIMITIVES_GENERATED,
103    TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN, or
104    TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB, and <index> is not in the range
105    zero to the value of MAX_VERTEX_STREAMS minus one.
106
107    (modify errors section for EndQueryIndexed on p. 41-42)
108
109    An INVALID_ENUM error is generated if <target> is not SAMPLES_PASSED,
110    ... TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN,
111    TRANSFORM_FEEDBACK_OVERFLOW_ARB, or
112    TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB.
113
114    An INVALID_VALUE error is generated if <target> is SAMPLES_PASSED, ...
115    TIME_ELAPSED, or TRANSFORM_FEEDBACK_OVERFLOW_ARB, and <index> is not
116    zero.
117
118    An INVALID_VALUE error is generated if <target> is PRIMITIVES_GENERATED,
119    TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN, or
120    TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB, and <index> is not in the range
121    zero to the value of MAX_VERTEX_STREAMS minus one.
122
123
124    Modify Section 4.2.1, Query Object Queries
125
126    (add new paragraph after fourth paragraph on p. 43)
127
128    For transform feedback overflow queries (TRANSFORM_FEEDBACK_OVERFLOW_ARB
129    and TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB) if the number of bits is
130    non-zero, the minimum number of bits is 1.
131
132    (modify errors section for GetQueryIndexediv on p 43)
133
134    An INVALID_ENUM error is generated if <target> is not ...,
135    TRANSFORM_FEEDBACK_OVERFLOW_ARB, or TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB.
136
137    An INVALID_VALUE error is generated if <target> is ..., or
138    TRANSFORM_FEEDBACK_OVERFLOW_ARB, and <index> is not zero.
139
140    An INVALID_VALUE error is generated if <target> is ..., or
141    TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB, and <index> is not in the range
142    zero to the value of MAX_VERTEX_STREAMS minus one.
143
144Additions to Chapter 10 of the OpenGL 4.4 (Core Profile) Specification (Vertex Specification and Drawing Commands)
145
146    Modify Section 10.10, Conditional Rendering
147
148    (modify first paragraph on p. 338)
149
150    Conditional rendering can be used to discard rendering commands based on
151    the result of a query. Conditional rendering is started and stopped using
152    the commands
153        ...
154    <id> specifies the name of a query whose results are used to determine if
155    the rendering commands are discarded. If the result (SAMPLES_PASSED) of
156    the query is zero, or if the result (ANY_SAMPLES_PASSED,
157    ANY_SAMPLES_PASSED_CONSERVATIVE, TRANSFORM_FEEDBACK_OVERFLOW_ARB, or
158    TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB) is false, ...
159
160    (modify second sentence of second paragraph on p. 338)
161
162    If the result (SAMPLES_PASSED) of the query is non-zero, or if the
163    result (ANY_SAMPLES_PASSED, ANY_SAMPLES_PASSED_CONSERVATIVE,
164    TRANSFORM_FEEDBACK_OVERFLOW_ARB, or
165    TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB) is true, such commands are not
166    discarded.
167
168    (modify errors section for BeginConditionalRender on p. 339)
169
170    An INVALID_OPERATION error is generated if <id> is the named of a query
171    object with a target other than ..., TRANSFORM_FEEDBACK_OVERFLOW_ARB, or
172    TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB, or if <id> is the name of a query
173    currently in progress.
174
175Additions to Chapter 13 of the OpenGL 4.4 (Core Profile) Specification
176(Fixed-Function Vertex Post-Processing)
177
178    Add new Section after 13.3, Primitive Queries
179
180    13.x Transform Feedback Overflow Queries
181
182    Transform feedback overflow queries use query objects to track whether
183    or not all stream vertices were written to buffer objects in transform
184    feedback mode.
185
186    When BeginQueryIndexed is called with a <target> of
187    TRANSFORM_FEEDBACK_OVERFLOW_ARB, the transform feedback overflow state
188    maintained by the GL is set to false. If transform feedback is active
189    and a primitive to be recorded on any stream does not fit in one of the
190    buffer objects used for capture, the overflow state is set to true.
191
192    When BeginQueryIndexed is called with a <target> of
193    TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB, the transform feedback stream
194    overflow state maintained by the GL for vertex stream <index> is set to
195    false. There is a separate overflow state for each vertex stream. If
196    transform feedback is active and a primitive to be recorded on stream
197    <index> does not fit in one of the buffer objects used for capture, the
198    overflow state for vertex stream <index> is set to true.
199
200Additions to the AGL/EGL/GLX/WGL Specifications
201
202     None.
203
204New State
205
206    Modify Table 23.74, Miscellaneous
207
208    (update the state table to cover the new query types on p. 599)
209
210    Get Value      Type  Get Command  Initial Value  Description                Sec.
211    -------------  ----  -----------  -------------  -------------------------  -----
212    CURRENT_QUERY  9xZ+  GetQueryiv         0        Active query object names  4.2.1
213
214New Implementation Dependent State
215
216    Modify Table 23.69, Implementation Dependent Values
217
218    (update the state table to cover the new query types on p. 594)
219
220    Get Value           Type  Get Command  Minimum Value   Description         Sec.
221    ------------------  ----  -----------  --------------  ------------------  -----
222    QUERY_COUNTER_BITS  9xZ+  GetQueryiv   see sec. 4.2.1  Asynchronous query  4.1.1
223                                                           counter bits
224
225Dependencies on OpenGL 4.0 and ARB_transform_feedback3
226
227    If OpenGL 4.0 and ARB_transform_feedback3 are not support then remove all
228    references to TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB.
229
230Issues
231
232    (1) Why is this extension necessary?
233
234      RESOLVED:  An application can query the number of vertices written
235      to a transform feedback buffer and compare that to the size of the
236      buffer (or number of vertices drawn) to try to detect overflow but
237      that is ineffective if subsequent rendering is to be predicated on
238      that condition.  Basically, the whole point is to have a queries
239      which can be used by BeginConditionalRender.
240
241      Note that this feature is present in another, competing graphics API.
242      This extension will allow one to better implement that API's features
243      on top of OpenGL.
244
245    (2) For conditional rendering do we want to discard or not discard
246        drawing if the query indicates transform feedback buffer overflow?
247
248      RESOLVED: Some apps probably want one way while others want the
249      other. This can be solved by the GL_ARB_conditional_render_inverted
250      extension which allows one to specify predication either on the normal
251      or inverted query result.
252
253    (3) Is the overflow condition determined per transform feedback buffer or
254        per vertex stream?
255
256      DISCUSSION: There may be multiple buffers used to capture primitives of
257      the same vertex stream and while the buffers themselves are the ones
258      that overflow, the overflow condition itself is determined per vertex
259      stream, as no data is written to any of the buffers used to capture
260      primitives of a particular vertex stream if not all of them are able to
261      capture the whole primitive.
262
263      RESOLVED: Overflow is determined per vertex stream.
264
265    (4) What do queries with target TRANSFORM_FEEDBACK_OVERFLOW_ARB track?
266
267      RESOLVED: Tracks overflow condition for all vertex streams. If OpenGL 4.0
268      and ARB_transform_feedback3 are not supported this trivially simplifies to
269      tracking overflow condition for the first and only vertex stream.
270
271Revision History
272
273    Revision 5, 2017/05/29 (Daniel Koch)
274      - fix typo
275
276    Revision 4, 2014/06/17 (Jon Leech)
277      - Add missing error condition for BeginQueryIndexed / EndQueryIndexed
278        and <target>TRANSFORM_FEEDBACK_STREAM_OVERFLOW_ARB (Bug 12376).
279
280    Revision 3, 2014/04/25 (Daniel Rakos)
281      - Renamed to ARB_transform_feedback_overflow_query.
282      - Replaced EXT suffixes with ARB ones.
283
284    Revision 2, 2014/04/16 (Daniel Rakos)
285      - Renamed extension to EXT_transform_feedback_overflow_query.
286      - Renamed new query targets to TRANSFORM_FEEDBACK_OVERFLOW_EXT and
287        TRANSFORM_FEEDBACK_STREAM_OVERFLOW_EXT.
288      - Added issues (3) and (4).
289      - Moved transform feedback overflow queries to have their own section
290        instead of introducing them as part of primitive queries.
291      - Added state table changes.
292      - Clarified language and error conditions.
293
294    Revision 1, 2014/01/27 (Brian Paul)
295      - Initial revision.
296