1Name 2 3 NV_transform_feedback 4 5Name Strings 6 7 GL_NV_transform_feedback 8 9Contributors 10 11 Cliff Woolley 12 Nick Carter 13 14Contact 15 16 Barthold Lichtenbelt (blichtenbelt 'at' nvidia.com) 17 Pat Brown (pbrown 'at' nvidia.com) 18 Eric Werness (ewerness 'at' nvidia.com) 19 20Status 21 22 Shipping for GeForce 8 Series (November 2006) 23 24Version 25 26 Last Modified Date: 03/09/2011 27 NVIDIA Revision: 18 28 29Number 30 31 341 32 33Dependencies 34 35 OpenGL 1.5 is required. 36 37 This extension interacts with EXT_timer_query. 38 39 NV_vertex_program4, NV_geometry_program4 and NV_gpu_program4 affect this 40 extension. 41 42 EXT_geometry_shader4 trivially interacts with this extension. 43 44 This extension has an OpenGL Shading Language component. As such it 45 interacts with ARB_shader_objects and OpenGL 2.0. 46 47 This extension is written against the OpenGL 2.0 specification. 48 49Overview 50 51 This extension provides a new mode to the GL, called transform feedback, 52 which records vertex attributes of the primitives processed by the GL. 53 The selected attributes are written into buffer objects, and can be 54 written with each attribute in a separate buffer object or with all 55 attributes interleaved into a single buffer object. If a geometry program 56 or shader is active, the primitives recorded are those emitted by the 57 geometry program. Otherwise, transform feedback captures primitives whose 58 vertex are transformed by a vertex program or shader, or by fixed-function 59 vertex processing. In either case, the primitives captured are those 60 generated prior to clipping. Transform feedback mode is capable of 61 capturing transformed vertex data generated by fixed-function vertex 62 processing, outputs from assembly vertex or geometry programs, or varying 63 variables emitted from GLSL vertex or geometry shaders. 64 65 The vertex data recorded in transform feedback mode is stored into buffer 66 objects as an array of vertex attributes. The regular representation and 67 the use of buffer objects allows the recorded data to be processed 68 directly by the GL without requiring CPU intervention to copy data. In 69 particular, transform feedback data can be used for vertex arrays (via 70 vertex buffer objects), as the source for pixel data (via pixel buffer 71 objects), as program constant data (via the NV_parameter_buffer_object or 72 EXT_bindable_uniform extension), or via any other extension that makes use 73 of buffer objects. 74 75 This extension introduces new query object support to allow transform 76 feedback mode to operate asynchronously. Query objects allow applications 77 to determine when transform feedback results are complete, as well as the 78 number of primitives processed and written back to buffer objects while in 79 transform feedback mode. This extension also provides a new rasterizer 80 discard enable, which allows applications to use transform feedback to 81 capture vertex attributes without rendering anything. 82 83New Procedures and Functions 84 85 void BindBufferRangeNV(enum target, uint index, uint buffer, 86 intptr offset, sizeiptr size) 87 void BindBufferOffsetNV(enum target, uint index, uint buffer, 88 intptr offset) 89 void BindBufferBaseNV(enum target, uint index, uint buffer) 90 void TransformFeedbackAttribsNV(sizei count, const int *attribs, 91 enum bufferMode) 92 void TransformFeedbackVaryingsNV(uint program, sizei count, 93 const int *locations, 94 enum bufferMode) 95 void BeginTransformFeedbackNV(enum primitiveMode) 96 void EndTransformFeedbackNV() 97 98 int GetVaryingLocationNV(uint program, const char *name) 99 void GetActiveVaryingNV(uint program, uint index, 100 sizei bufSize, sizei *length, sizei *size, 101 enum *type, char *name) 102 void ActiveVaryingNV(uint program, const char *name) 103 void GetTransformFeedbackVaryingNV(uint program, uint index, 104 int *location) 105 106 void GetIntegerIndexedvEXT(enum param, uint index, int *values); 107 void GetBooleanIndexedvEXT(enum param, uint index, boolean *values); 108 109 (Note: These indexed query functions are provided in the EXT_draw_buffers2 110 extension. The boolean query is not useful for any queryable value in 111 this extension, but is supported for completeness and consistency with 112 base GL typed "Get" functions.) 113 114 115New Tokens 116 117 Accepted by the <target> parameters of BindBuffer, BufferData, 118 BufferSubData, MapBuffer, UnmapBuffer, GetBufferSubData, 119 GetBufferPointerv, BindBufferRangeNV, BindBufferOffsetNV and 120 BindBufferBaseNV: 121 122 TRANSFORM_FEEDBACK_BUFFER_NV 0x8C8E 123 124 Accepted by the <param> parameter of GetIntegerIndexedvEXT and 125 GetBooleanIndexedvEXT: 126 127 TRANSFORM_FEEDBACK_BUFFER_START_NV 0x8C84 128 TRANSFORM_FEEDBACK_BUFFER_SIZE_NV 0x8C85 129 TRANSFORM_FEEDBACK_RECORD_NV 0x8C86 130 131 Accepted by the <param> parameter of GetIntegerIndexedvEXT and 132 GetBooleanIndexedvEXT, and by the <pname> parameter of GetBooleanv, 133 GetDoublev, GetIntegerv, and GetFloatv: 134 135 TRANSFORM_FEEDBACK_BUFFER_BINDING_NV 0x8C8F 136 137 Accepted by the <bufferMode> parameter of TransformFeedbackAttribsNV and 138 TransformFeedbackVaryingsNV: 139 140 INTERLEAVED_ATTRIBS_NV 0x8C8C 141 SEPARATE_ATTRIBS_NV 0x8C8D 142 143 Accepted by the <target> parameter of BeginQuery, EndQuery, and 144 GetQueryiv: 145 146 PRIMITIVES_GENERATED_NV 0x8C87 147 TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV 0x8C88 148 149 Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, and by 150 the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and 151 GetDoublev: 152 153 RASTERIZER_DISCARD_NV 0x8C89 154 155 Accepted by the <pname> parameter of GetBooleanv, GetDoublev, GetIntegerv, 156 and GetFloatv: 157 158 MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS_NV 0x8C8A 159 MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV 0x8C8B 160 MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTS_NV 0x8C80 161 TRANSFORM_FEEDBACK_ATTRIBS_NV 0x8C7E 162 163 Accepted by the <pname> parameter of GetProgramiv: 164 165 ACTIVE_VARYINGS_NV 0x8C81 166 ACTIVE_VARYING_MAX_LENGTH_NV 0x8C82 167 TRANSFORM_FEEDBACK_VARYINGS_NV 0x8C83 168 169 Accepted by the <pname> parameter of GetBooleanv, GetDoublev, GetIntegerv, 170 GetFloatv, and GetProgramiv: 171 172 TRANSFORM_FEEDBACK_BUFFER_MODE_NV 0x8C7F 173 174 Accepted by the <attribs> parameter of TransformFeedbackAttribsNV: 175 176 BACK_PRIMARY_COLOR_NV 0x8C77 177 BACK_SECONDARY_COLOR_NV 0x8C78 178 TEXTURE_COORD_NV 0x8C79 179 CLIP_DISTANCE_NV 0x8C7A 180 VERTEX_ID_NV 0x8C7B 181 PRIMITIVE_ID_NV 0x8C7C 182 GENERIC_ATTRIB_NV 0x8C7D 183 POINT_SIZE 0x0B11 184 FOG_COORDINATE 0x8451 185 SECONDARY_COLOR_NV 0x852D 186 PRIMARY_COLOR 0x8577 187 POSITION 0x1203 188 LAYER_NV 0x8DAA 189 190 (note: POINT_SIZE, FOG_COORDINATE, PRIMARY_COLOR, and POSITION are 191 defined in the core OpenGL specification; SECONDARY_COLOR_NV is defined 192 in NV_register_combiners.) 193 194 Returned by the <type> parameter of GetActiveVaryingNV: 195 196 UNSIGNED_INT_VEC2_EXT 0x8DC6 197 UNSIGNED_INT_VEC3_EXT 0x8DC7 198 UNSIGNED_INT_VEC4_EXT 0x8DC8 199 200 (note: All three of these are defined in the EXT_gpu_shader4 201 extension.) 202 203Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL 204Operation) 205 206 Insert three new sections between Sections 2.11, Coordinate Transforms and 207 2.12, Clipping: 208 209 (Move the "Asynchronous Queries" language out of Section 4.1.7) 210 211 Section 2.X, Asynchronous Queries 212 213 Asynchronous queries provide a mechanism to return information about the 214 processing of a sequence of GL commands. There are two query types 215 supported by the GL. Transform feedback queries (section 2.Y) returns 216 information on the number of vertices and primitives processed by the GL 217 and written to one or more buffer objects. Occlusion queries (section 218 4.1.7.1) count the number of fragments or samples that pass the depth 219 test. 220 221 The results of asynchronous queries are not returned by the GL immediately 222 after the completion of the last command in the set; subsequent commands 223 can be processed while the query results are not complete. When 224 available, the query results are stored in an associated query object. 225 The commands described in section 6.1.12 provide mechanisms to determine 226 when query results are available and return the actual results of the 227 query. The name space for query objects is the unsigned integers, with 228 zero reserved by the GL. 229 230 Each type of query supported by the GL has an active query object name. If 231 the active query object name for a query type is non-zero, the GL is 232 currently tracking the information corresponding to that query type and 233 the query results will be written into the corresponding query object. If 234 the active query object for a query type name is zero, no such information 235 is being tracked. 236 237 A query object is created by calling 238 239 void BeginQuery(enum target, uint id); 240 241 with an unused name <id>. <target> indicates the type of query to be 242 performed; valid values of <target> are defined in subsequent 243 sections. When a query object is created, the name <id> is marked as used 244 and associated with a new query object. 245 246 BeginQuery sets the active query object name for the query type given by 247 <target> to <id>. If BeginQuery is called with an <id> of zero, if the 248 active query object name for <target> is non-zero, or if <id> is the 249 active query object name for any query type, the error INVALID OPERATION 250 is generated. 251 252 The command 253 254 void EndQuery(enum target); 255 256 marks the end of the sequence of commands to be tracked for the query type 257 given by <target>. The active query object for <target> is updated to 258 indicate that query results are not available, and the active query object 259 name for <target> is reset to zero. When the commands issued prior to 260 EndQuery have completed and a final query result is available, the query 261 object, active when EndQuery is, called is updated by the GL. The query 262 object is updated to indicate that the query results are available and to 263 contain the query result. If the active query object name for <target> is 264 zero when EndQuery is called, the error INVALID_OPERATION is generated. 265 266 The command 267 268 void GenQueries(sizei n, uint *ids); 269 270 returns <n> previously unused query object names in <ids>. These names are 271 marked as used, but no object is associated with them until the first time 272 they are used by BeginQuery. 273 274 Query objects are deleted by calling 275 276 void DeleteQueries(sizei n, const uint *ids); 277 278 <ids> contains <n> names of query objects to be deleted. After a query 279 object is deleted, its name is again unused. Unused names in <ids> are 280 silently ignored. 281 282 Calling either GenQueries or DeleteQueries while any query of any target 283 is active causes an INVALID_OPERATION error to be generated. 284 285 Query objects contain two pieces of state: a single bit indicating 286 whether a query result is available, and an integer containing the query 287 result value. The number of bits used to represent the query result is 288 implementation-dependent. In the initial state of a query object, the 289 result is available and its value is zero. 290 291 The necessary state for each query type is an unsigned integer holding the 292 active query object name (zero if no query object is active), and any 293 state necessary to keep the current results of an asynchronous query in 294 progress. 295 296 Section 2.Y, Transform Feedback 297 298 In 'transform feedback' mode the vertices of transformed primitives are 299 written out to one or more buffer objects. The vertices are fed back after 300 the geometry shader stage, if it exists, or otherwise after vertex 301 processing right before clipping (section 2.12) but after color 302 clamping. Optionally the transformed vertices can be discarded after being 303 stored into one or more buffer objects, or they can be passed on down to 304 the clipping stage for further processing. 305 306 Transform feedback is started and finished by calling 307 308 void BeginTransformFeedbackNV(enum primitiveMode) 309 310 and 311 312 void EndTransformFeedbackNV(), 313 314 respectively. Transform feedback is said to be active after a call to 315 BeginTransformFeedbackNV and inactive after a call to 316 EndTransformFeedbackNV. Transform feedback is initially inactive. 317 Transform feedback is performed after color clamping, but immediately 318 before clipping in the OpenGL pipeline. <primitiveMode> is one of 319 TRIANGLES, LINES, or POINTS, and specifies the output type of primitives 320 that will be recorded into the buffer objects bound for transform feedback 321 (see below). <primitiveMode> places a restriction on the primitive types 322 that may be rendered during an instance of transform feedback. See table 323 X.1. 324 325 Transform Feedback 326 primitiveMode allowed render primitive modes 327 ---------------------- --------------------------------- 328 POINTS POINTS 329 LINES LINES, LINE_LOOP, and LINE_STRIP 330 TRIANGLES TRIANGLES, TRIANGLE_STRIP, 331 TRIANGLE_FAN, QUADS, QUAD_STRIP, 332 and POLYGON 333 334 Table X.1 Legal combinations between the transform feedback primitive 335 mode, as passed to BeginTransformFeedbackNV and the current primitive 336 mode. 337 338 If a geometry program or geometry shader is active, the output primitive 339 type of the currently active program is used as the render primitive in 340 table X.1, otherwise the Begin mode is used. 341 342 Quads and polygons will be tessellated and recorded as triangles (the 343 order of tessellation within a primitive is undefined); primitives 344 specified in strips or fans will be assembled and recorded as individual 345 primitives. Incomplete primitives are not recorded. Begin or any operation 346 that implicitly calls Begin (such as DrawElements) will generate 347 INVALID_OPERATION if the begin mode is not an allowed begin mode for the 348 current transform feedback buffer state. If a geometry program or geometry 349 shader is active, its output primitive mode is used for the error check 350 instead of the begin mode. 351 352 It is an invalid operation error to call BeginTransformFeedbackNV, 353 TransformFeedbackVaryingsNV, TransformFeedbackAttribsNV, or UseProgram or 354 LinkProgram on the currently active program object while transform 355 feedback is active. It is an invalid operation error to call 356 EndTransformFeedbackNV while transform feedback is inactive. 357 358 Transform feedback can operate in either INTERLEAVED_ATTRIBS_NV or 359 SEPARATE_ATTRIBS_NV mode. In the INTERLEAVED_ATTRIBS_NV mode, several 360 vertex attributes can be written, interleaved, into a single buffer 361 object. In the SEPARATE_ATTRIBS_NV mode, vertex attributes are recorded, 362 non-interleaved, into several buffer objects simultaneously. 363 364 It is an INVALID_OPERATION error to call BeginTransformFeedbackNV if there 365 is no buffer object bound to index 0 (see the description of the 366 BindBuffer* commands below) in INTERLEAVED_ATTRIBS_NV mode. It is also an 367 INVALID_OPERATION error to call BeginTransformFeedbackNV if the number of 368 buffer objects bound in SEPARATE_ATTRIBS_NV mode is less than the number 369 of buffer objects required, as given by the current transform feedback 370 state. It is also an INVALID_OPERATION error to call 371 BeginTransformFeedbackNV if no attributes are specified to be captured in 372 either separate or interleaved mode. 373 374 Buffer objects are made to be targets of transform feedback by calling one 375 of 376 377 void BindBufferRangeNV(enum target, uint index, uint buffer, 378 intptr offset, sizeiptr size) 379 void BindBufferOffsetNV(enum target, uint index, uint buffer, 380 intptr offset) 381 void BindBufferBaseNV(enum target, uint index, uint buffer) 382 383 where <target> is set to TRANSFORM_FEEDBACK_BUFFER_NV. Any of the three 384 BindBuffer* commands perform the equivalent of BindBuffer(target, 385 buffer). <buffer> specifies which buffer object to bind to the target at 386 index number <index>. <index> exists for use with the SEPARATE_ATTRIBS_NV 387 mode and must be less than the value of 388 MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV. <offset> specifies a starting 389 offset into the buffer object <buffer>. <size> specifies the number of 390 elements that can be written during transform feedback mode. This is 391 useful to prevent the GL from writing past a certain position in the 392 buffer object. Both <offset> and <size> are in basic machine units. The 393 error INVALID_VALUE is generated if the value of <size> is less than or 394 equal to zero. The error INVALID_VALUE is generated if <offset> or <size> 395 are not word-aligned. The error INVALID_OPERATION is generated when any of 396 the BindBuffer* commands is called while transform feedback is active. 397 398 BindBufferBaseNV is equivalent to calling BindBufferOffsetNV with an 399 <offset> of 0. BindBufferOffsetNV is the equivalent of calling 400 BindBufferRangeNV with <size> = sizeof(buffer) - <offset> and rounding 401 <size> down so that it is word-aligned. 402 403 If recording the vertices of a primitive to the buffer objects being used 404 for transform feedback purposes would result in either exceeding the 405 limits of any buffer object's size, or in exceeding the end position 406 <offset> + <size> - 1, as set by BindBufferRangeNV, then no vertices of 407 the primitive are recorded, and the counter corresponding to the 408 asynchronous query target TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV (see 409 Section 2.Z) is not incremented. 410 411 Two methods exist to specify which transformed vertex attributes are 412 streamed to one, or more, buffer objects in transform feedback mode. If 413 an OpenGL Shading Language vertex and/or geometry shader is active, then 414 the state set with the TransformFeedbackVaryingsNV() command determines 415 which attributes to record. If neither a vertex nor geometry shader is 416 active, the state set with the TransformFeedbackAttribsNV() command 417 determines which attributes to record. 418 419 When a program object containing a vertex shader and/or geometry shader is 420 active, the set of vertex attributes recorded in transform feedback mode 421 is specified by 422 423 void TransformFeedbackVaryingsNV(uint program, sizei count, 424 const int *locations, 425 enum bufferMode) 426 427 This command sets the transform feedback state for <program> and specifies 428 which varying variables to record when transform feedback is active. The 429 array <locations> contains <count> locations of active varying variables, 430 as queried with GetActiveVaryingNV(), to stream to a buffer object. See 431 section 2.15.3. <bufferMode> is one of INTERLEAVED_ATTRIBS_NV or 432 SEPARATE_ATTRIBS_NV. The error INVALID_OPERATION is generated if any 433 value in <locations> does not reference an active varying variable, or if 434 any value in <locations> appears more than once in the array. The same 435 error is generated if <program> has not been linked successfully. The 436 program object's state value TRANSFORM_FEEDBACK_BUFFER_MODE_NV will be set 437 to <bufferMode> and the program object's state value 438 TRANSFORM_FEEDBACK_VARYINGS_NV set to <count>. These values can be queried 439 with GetProgramiv (see section 6.1.14). 440 441 In the INTERLEAVED_ATTRIBS_NV mode, varying variables are written, 442 interleaved, into one buffer object. This is the buffer object bound to 443 index 0. Varying variables are written out to that buffer object in the 444 order that they appear in the array <locations>. The error 445 INVALID_OPERATION is generated if the total number of components of all 446 varying variables specified in the array <locations> is greater than 447 MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS_NV. 448 449 In the SEPARATE_ATTRIBS_NV mode, varying variables are recorded, 450 non-interleaved, into several buffer objects simultaneously. The first 451 varying variable in the array <locations> is written to the buffer bound 452 to index 0. The last varying variable is written to the buffer object 453 bound to index <count> - 1. No more than 454 MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV buffer objects can be written 455 to simultaneously. The error INVALID_VALUE is generated if <count> is 456 greater than that limit. Furthermore, the number of components for each 457 varying variable in the array <locations> cannot exceed 458 MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTS_NV. The error INVALID_VALUE is 459 generated if any varying variable in <locations> exceeds this limit. 460 461 It is not necessary to (re-)link <program> after calling 462 TransformFeedbackVaryingsNV(). Changes to the transform feedback state 463 will be picked up right away after calling TransformFeedbackVaryingsNV(). 464 465 The value for any attribute specified to be streamed to a buffer object 466 but not actually written by a vertex or geometry shader is undefined. 467 468 When neither a vertex nor geometry shader is active, the vertex attributes 469 produced by fixed-function vertex processing or an assembly vertex or 470 geometry program can be recorded in transform feedback mode. The set of 471 attributes to record is specified by 472 473 void TransformFeedbackAttribsNV(sizei count, const int *attribs, 474 enum bufferMode) 475 476 This command specifies which attributes to record into one, or more, 477 buffer objects. The value TRANSFORM_FEEDBACK_BUFFER_MODE_NV will be set 478 to <bufferMode> and the value TRANSFORM_FEEDBACK_ATTRIBS_NV set to 479 <count>. The array <attribs> contains an interleaved representation of 480 the attributes desired to be fed back containing 3*count values. For 481 attrib i, the value at 3*i+0 is the enum corresponding to the attrib, as 482 given in table X.2. The value at 3*i+1 is the number of components of the 483 provided attrib to be fed back and is between 1 and 4. The value at 3*i+2 484 is the index for attribute enumerants corresponding to more than one real 485 attribute. For an attribute enumerant corresponding to only one attribute, 486 the index is ignored. For an attribute enumerant corresponding to more 487 than one attribute, the error INVALID_VALUE is generated if the index 488 value is outside the allowable range for that attribute. 489 490 permitted GPU_program_4 491 attrib sizes index? result name 492 --------------------- -------- -------- -------------- 493 POSITION 1,2,3,4 no position 494 PRIMARY_COLOR 1,2,3,4 no color.front.primary 495 SECONDARY_COLOR_NV 1,2,3,4 no color.front.secondary 496 BACK_PRIMARY_COLOR_NV 1,2,3,4 no color.back.primary 497 BACK_SECONDARY_COLOR_NV 1,2,3,4 no color.back.secondary 498 FOG_COORDINATE 1 no fogcoord 499 POINT_SIZE 1 no pointsize 500 TEXTURE_COORD_NV 1,2,3,4 yes texcoord[index] 501 CLIP_DISTANCE_NV 1 yes clip[index] 502 VERTEX_ID_NV 1 no vertexid 503 PRIMITIVE_ID_NV 1 no primid 504 GENERIC_ATTRIB_NV 1,2,3,4 yes attrib[index] 505 LAYER_NV 1 no layer 506 507 Table X.2: Transform Feedback Attribute Specifiers.The 'attrib' column 508 specifies which attribute to record. The 'permitted sizes' column 509 indicates how many components of the attribute can be recorded. The 510 'index' column indicates if the attribute is indexed. The 'gpu program 4' 511 column shows which result variable of a vertex or geometry program 512 corresponds to the attribute to record. 513 514 The TransformFeedbackAttribsNV() command sets transform feedback state 515 which is used both when the GL is in fixed-function vertex processing 516 mode, as well as when an assembly vertex and/or geometry program is 517 active. 518 519 The parameter <bufferMode> has the same meaning as described for 520 TransformFeedbackVaryingsNV(). Attributes are either written interleaved, 521 or into separate buffer objects, in the same manner as described earlier 522 for TransformFeedbackVaryingsNV(). 523 524 In the INTERLEAVED_ATTRIBS_NV mode, the error INVALID_VALUE is generated 525 if the sum of the values of elements 3*i+1 in the array <attribs> is 526 greater than MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS_NV. 527 528 In the SEPARATE_ATTRIBS_NV mode, no more than 529 MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV buffer objects can be written 530 to simultaneously. The error INVALID_VALUE is generated if <count> is 531 greater than that limit. 532 533 The error INVALID_OPERATION is generated if any attribute appears more 534 than once in the array <attribs>. 535 536 The value for any attribute specified to be streamed to a buffer object 537 but not actually written by a vertex or geometry program is undefined. 538 The values of PRIMITIVE_ID_NV or LAYER_NV for a vertex is defined if and 539 only if a geometry program is active and that program writes to the result 540 variables "result.primid" or "result.layer", respectively. The value of 541 VERTEX_ID_NV is only defined if and only if a vertex program is active, no 542 geometry program is active, and the vertex program writes to the output 543 attribute "result.id". 544 545 Section 2.Z, Primitive Queries 546 547 Primitive queries use query objects to track the number of primitives 548 generated by the GL and to track the number of primitives written to 549 transform feedback buffers. 550 551 When BeginQuery is called with a <target> of PRIMITIVES_GENERATED_NV, the 552 primitives-generated count maintained by the GL is set to zero. When the 553 generated primitive query is active, the primitives-generated count is 554 incremented every time a primitive reaches the Discarding Rasterization 555 stage (see Section 3.x) right before rasterization. This counter counts 556 the number of primitives emitted by a geometry shader, if active, possibly 557 further tessellated into separate primitives during the transform-feedback 558 stage, if active. 559 560 When BeginQuery is called with a <target> of 561 TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV, the transform-feedback- 562 primitives-written count maintained by the GL is set to zero. When the 563 transform feedback primitive written query is active, the 564 transform-feedback-primitives-written count is incremented every time a 565 primitive is recorded into a buffer object. If transform feedback is not 566 active, this counter is not incremented. If the primitive does not fit in 567 the buffer object, the counter is not incremented. 568 569 These two queries can be used together to determine if all primitives have 570 been written to the bound feedback buffers; if both queries are run 571 simultaneously and the query results are equal, all primitives have been 572 written to the buffer(s). If the number of primitives written is less than 573 the number of primitives generated, the buffer is full. 574 575 Modify section 2.15.3 "Shader Variables", page 75. 576 577 Change the second sentence in the first paragraph on p. 84 as follows: 578 579 . . . or read by a fragment shader, will count against this limit. The 580 transformed vertex position (gl_Position) does not count against this 581 limit. 582 583 Add the following paragraphs on p.84: 584 585 A varying variable is considered active if it is determined by the linker 586 that the varying will actually be used when the executable code in a 587 program object is executed. The linker will make this determination 588 regardless of the transform-feedback state set with the 589 TransformFeedbackVaryingsNV() command. In cases where the linker cannot 590 make a conclusive determination, the varying will be considered active. It 591 is possible to override this determination and force the linker to 592 consider a varying variable as active by calling ActiveVaryingNV(). This 593 can be useful in transform feedback mode if there are varying variables to 594 be recorded but not otherwise needed. 595 596 To find the location of an active varying variable, call 597 598 int GetVaryingLocationNV(uint program, const char *name) 599 600 This command will return the location of varying variable <name>. <name> 601 is a null-terminated string without whitespace. If <name> is not the name 602 of an active varying variable in <program>, -1 is returned. Locations for 603 both user-defined as well as built-in varying variables can be queried. If 604 <program> has not been successfully linked, the error INVALID_OPERATION is 605 generated. After a program is linked, the location will not change, unless 606 the program is re- linked. A valid name cannot be any portion of a single 607 vector or matrix, but can be a single element of an array or the whole 608 array. Note that varying variables cannot be structures. 609 610 To determine the set of active varying variables used by a program object, 611 and their data types, use the command: 612 613 void GetActiveVaryingNV(uint program, uint index, 614 sizei bufSize, sizei *length, sizei *size, 615 enum *type, char *name); 616 617 This command provides information about the varying selected by 618 <index>. An <index> of 0 selects the first active varying variable, and an 619 <index> of ACTIVE_VARYINGS_NV-1 selects the last active varying 620 variable. The value of ACTIVE_VARYINGS_NV can be queried with 621 GetProgramiv (see section 6.1.14). If <index> is greater than or equal to 622 ACTIVE_VARYINGS_NV, the error INVALID_VALUE is generated. The parameter 623 <program> is the name of a program object for which the command 624 LinkProgram has been issued in the past. It is not necessary for <program> 625 to have been linked successfully. The link could have failed because the 626 number of active varying variables exceeded the limit. 627 628 The name of the selected varying is returned as a null-terminated string 629 in <name>. The actual number of characters written into <name>, excluding 630 the null terminator, is returned in <length>. If <length> is NULL, no 631 length is returned. The maximum number of characters that may be written 632 into <name>, including the null terminator, is specified by <bufSize>. The 633 returned varying name can be the name of a user defined varying variable 634 or the name of a built- in varying (which begin with the prefix "gl_", see 635 the OpenGL Shading Language specification for a complete list). The length 636 of the longest varying name in program is given by 637 ACTIVE_VARYING_MAX_LENGTH_NV, which can be queried with GetProgramiv (see 638 section 6.1.14). 639 640 For the selected varying variable, its type is returned into <type>. The 641 size of the varying is returned into <size>. The value in <size> is in 642 units of the type returned in <type>. The type returned can be any of 643 FLOAT, FLOAT_VEC2, FLOAT_VEC3, FLOAT_VEC4, INT, INT_VEC2, INT_VEC3, 644 INT_VEC4, UNSIGNED_INT, UNSIGNED_INT_VEC2_EXT, UNSIGNED_INT_VEC3_EXT, 645 UNSIGNED_INT_VEC4_EXT, FLOAT_MAT2, FLOAT_MAT3, or FLOAT_MAT4. If an error 646 occurred, the return parameters <length>, <size>, <type> and <name> will 647 be unmodified. This command will return as much information about active 648 varying variables as possible. If no information is available, <length> 649 will be set to zero and <name> will be an empty string. This situation 650 could arise if GetActiveVaryingNV is issued after a failed link. 651 652 To force the linker to mark a varying variable as active, call 653 654 void ActiveVaryingNV(uint program, const char *name) 655 656 to specify that the varying variable <name> in <program> should be marked 657 as active when the program is next linked. In particular, it does not 658 modify the list of active varying variables in a program object that has 659 already been linked. For any varying variable in <program> not passed to 660 ActiveVaryingNV, the linker will determine their active status. <name> 661 must be a null-terminated string without whitespace. A valid name cannot 662 be an element of an array, or any portion of a single vector or 663 matrix. ActiveVaryingNV may be issued before any shader objects are 664 attached to <program>. Hence, <name> can contain any string, including a 665 name that is never used as a varying variable in any shader object. Such 666 names are ignored by the GL. 667 668 The application is advised to force any varying variable live that it 669 needs for transform feedback purposes. The set of active varying variables 670 are linker dependent. 671 672Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 673 674 (Add new section 3.X, Discarding Rasterization) 675 676 Primitives can be optionally discarded before rasterization by calling 677 Enable and Disable with RASTERIZER_DISCARD_NV. When enabled, primitives 678 are discarded right before the rasterization stage, but after the optional 679 transform feedback stage. When disabled, primitives are passed through to 680 the rasterization stage to be processed normally. RASTERIZER_DISCARD_NV 681 applies to the DrawPixels, CopyPixels, Bitmap, Clear and Accum commands as 682 well. 683 684Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 685Operations and the Frame Buffer) 686 687 (Replace section 4.1.7, "Occlusion Queries", p. 204, with the following) 688 689 Occlusion queries use query objects to track the number of fragments or 690 samples that pass the depth test. An occlusion query can be started and 691 finished by calling BeginQuery and EndQuery, respectively, with a <target> 692 of SAMPLES_PASSED. 693 694 When an occlusion query starts, the samples-passed count maintained by the 695 GL is set to zero. When an occlusion query is active, the samples-passed 696 count is incremented for each fragment that passes the depth test. If the 697 value of SAMPLE BUFFERS is 0, then the samples- passed count is 698 incremented by 1 for each fragment. If the value of SAMPLE BUFFERS is 1, 699 then the samples-passed count is incremented by the number of samples 700 whose coverage bit is set. However, implementations, at their discretion, 701 may instead increase the samples-passed count by the value of SAMPLES if 702 any sample in the fragment is covered. When an occlusion query finishes 703 and all fragments generated by the commands issued prior to EndQuery have 704 been generated, the samples-passed count is written to the corresponding 705 query object as the query result value, and the query result for that 706 object is marked as available. 707 708 If the samples-passed count overflows, (i.e., exceeds the value 2^n - 1, 709 where n is the number of bits in the samples-passed count), its value 710 becomes undefined. It is recommended, but not required, that 711 implementations handle this overflow case by saturating at 2^n - 1 and 712 incrementing no further. 713 714Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) 715 716 (Add to section 5.4, Display Lists p. 237) 717 718 On p. 241, add the following to the list of vertex buffer object commands 719 not compiled into a display list: BindBufferRangeNV, BindBufferOffsetNV, 720 BindBufferBaseNV, TransformFeedbackAttribsNV, 721 TransformFeedbackVaryingsNV, and ActiveVaryingNV. 722 723Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State 724Requests) 725 726 Modify the second paragraph of section 6.1.1 (Simple Queries) p244 to read 727 as follows: 728 729 ...<data> is a pointer to a scalar or array of the indicated type in which 730 to place the returned data. The commands 731 732 void GetIntegerIndexedvEXT(enum param, uint index, int *values); 733 void GetBooleanIndexedvEXT(enum param, uint index, boolean *values); 734 735 are used to query indexed state. <target> is the name of the indexed 736 state and <index> is the index of the particular element being queried. 737 <data> is a pointer to a scalar or array of the indicated type in which to 738 place the returned data. In addition ... 739 740 (Replace Section 6.1.12, Occlusion Queries, p. 254) 741 742 Section 6.1.12, Asynchronous Queries 743 744 The command 745 746 boolean IsQuery(uint id); 747 748 returns TRUE if <id> is the name of a query object. If <id> is zero, or if 749 <id> is a non-zero value that is not the name of a query object, IsQuery 750 returns FALSE. 751 752 Information about a query target can be queried with the command 753 754 void GetQueryiv(enum target, enum pname, int *params); 755 756 <target> identifies the query target and can be SAMPLES_PASSED for 757 occlusion queries or PRIMITIVES_GENERATED_NV and 758 TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV for primitive queries. 759 760 If <pname> is CURRENT_QUERY, the name of the currently active query for 761 <target>, or zero if no query is active, will be placed in <params>. 762 763 If <pname> is QUERY_COUNTER_BITS, the implementation-dependent number of 764 bits used to hold the query result for <target> will be placed in 765 params. The number of query counter bits may be zero, in which case the 766 counter contains no useful information. 767 768 For primitive queries (PRIMITIVES_GENERATED_NV and 769 TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV) if the number of bits is 770 non-zero, the minimum number of bits allowed is 32. 771 772 For occlusion queries (SAMPLES_PASSED), if the number of bits is non- 773 zero, the minimum number of bits allowed is a function of the 774 implementation's maximum viewport dimensions (MAX_VIEWPORT_DIMS). The 775 counter must be able to represent at least two overdraws for every pixel 776 in the viewport. The formula to compute the allowable minimum value (where 777 n is the minimum number of bits) is: 778 779 n = min(32, ceil(log_2(maxViewportWidth * 780 maxViewportHeight * 2))). 781 782 The state of a query object can be queried with the commands 783 784 void GetQueryObjectiv(uint id, enum pname, int *params); 785 void GetQueryObjectuiv(uint id, enum pname, uint *params); 786 787 If <id> is not the name of a query object, or if the query object named by 788 <id> is currently active, then an INVALID_OPERATION error is generated. 789 790 If <pname> is QUERY_RESULT, then the query object's result value is 791 returned as a single integer in <params>. If the value is so large in 792 magnitude that it cannot be represented with the requested type, then the 793 nearest value representable using the requested type is returned. If the 794 number of query counter bits for any <target> is zero, then the result is 795 returned as a single integer with a value of 0. 796 797 There may be an indeterminate delay before the above query returns. If 798 <pname> is QUERY_RESULT_AVAILABLE, FALSE is returned if such a delay would 799 be required, TRUE is returned otherwise. It must always be true that if 800 any query object returns a result available of TRUE, all queries of the 801 same type issued prior to that query must also return TRUE. 802 803 Querying the state for any given query object forces the corresponding 804 query to complete within a finite amount of time. 805 806 If multiple queries are issued using the same object name prior to calling 807 GetQueryObject[u]iv, the result and availability information returned will 808 always be from the last query issued. The results from any queries before 809 the last one will be lost if they are not retrieved before starting a new 810 query on the same <target> and <id>. 811 812 (Add to Section 6.1.13, Buffer Objects, p. 255) 813 814 Add the following paragraph to the bottom of this section, p. 256. 815 816 To query which buffer objects are the target(s) when transform feedback is 817 active, call GetIntegerIndexedvEXT() with <param> set to 818 TRANSFORM_FEEDBACK_BUFFER_BINDING_NV. <index> has to be in the range 0 to 819 MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV - 1, otherwise the error 820 INVALID_VALUE is generated. The name of the buffer object bound to <index> 821 is returned in <values>. If no buffer object is bound for <index>, zero is 822 returned in <values>. 823 824 To query the starting offset or size of the range of each buffer object 825 binding used for transform feedback, call GetIntegerIndexedvEXT() with 826 <param> set to TRANSFORM_FEEDBACK_BUFFER_START_NV or 827 TRANSFORM_FEEDBACK_BUFFER_SIZE_NV respectively. The error INVALID_VALUE 828 is generated if <index> not in the range 0 to 829 MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV - 1. If the parameter 830 (starting offset or size) was not specified when the buffer object was 831 bound, or if no buffer object is bound to <index>, zero is returned. 832 833 (Add a new Section 6.1.14 "Transform Feedback " and rename 6.1.14 to 834 6.1.15) 835 836 To query the attributes to stream to a buffer object when neither an 837 OpenGL Shading Language vertex nor geometry shader is active, call 838 GetIntegerIndexedvEXT() with <param> set to 839 TRANSFORM_FEEDBACK_RECORD_NV. This will return three values in <values> 840 for each <index>. The first value returned is the attribute. The second 841 value the number of components of the attribute, and the third value the 842 index of the attribute, if applicable. If the attribute is not indexed, 843 the third component will return 0. The parameter <index> has to be in the 844 range 0 to TRANSFORM_FEEDBACK_ATTRIBS_NV - 1, otherwise the error 845 INVALID_VALUE is generated. If no data exists for <index> 0 is returned 846 three times in <values>. 847 848 To query the attributes to stream to a buffer object when a vertex and/or 849 geometry shader is active, use the command 850 GetTransformFeedbackVaryingNV(), as explained in section 6.1.14. 851 852 (add to Section 6.1.14, Shader and Program Queries, p. 256) 853 854 Add the following paragraph to the bottom of page 257: 855 856 If <pname> is TRANSFORM_FEEDBACK_BUFFER_MODE_NV, the buffer mode, 857 used when transform feedback is active, is returned. It can be one of 858 SEPARATE_ATTRIBS_NV or INTERLEAVED_ATTRIBS_NV. If <pname> is 859 TRANSFORM_FEEDBACK_VARINGS_NV, the number of varying variables to stream 860 to one, or more, buffer objects are returned. If <pname> is 861 ACTIVE_VARYINGS_NV, the number of active varying variables is 862 returned. If no active varyings exist, 0 is returned. If <pname> is 863 ACTIVE_VARYINGS_MAX_LENGTH_NV, the length of the longest active varying 864 name, including a null terminator, is returned. If no active varying 865 variable exists, 0 is returned. 866 867 The command 868 869 void GetTransformFeedbackVaryingNV(uint program, uint index, 870 int *location) 871 872 returns, for each <index>, the location of a varying variable to stream to 873 a buffer object in <location>. The <index> element of the array 874 <locations>, as passed to TransformFeedbackVaryingsNV, is 875 returned. <index> has to be in the program object specific range 0 to 876 TRANSFORM_FEEDBACK_VARYINGS_NV - 1, otherwise the error INVALID_VALUE is 877 generated. If no location exists for <index>, -1 is returned. If <program> 878 is not the name of a program object, or if program object has not been 879 linked successfully, the error INVALID_OPERATION is generated. 880 881Additions to Appendix A of the OpenGL 2.0 Specification (Invariance) 882 883 None. 884 885Additions to the AGL/GLX/WGL Specifications 886 887 None. 888 889GLX Protocol 890 891 UNDER DEVELOPMENT 892 893Interactions with EXT_timer_query 894 895 EXT_timer_query is the first extension to generalize the BeginQuery and 896 EndQuery mechanism introduced by ARB_occlusion_query and OpenGL 1.5 to 897 cover an additional query type. This extension is the second. This 898 extension is written against the OpenGL 2.0 specification and uses most of 899 the modifications in the EXT_timer_query specification. If 900 EXT_timer_query is supported, timer queries need to be added as a third 901 query type. 902 903Dependencies on NV_geometry_program4 and EXT_geometry_shader4 904 905 If NV_geometry_program4 is not supported, delete the reference to the 906 output primitive type in Section 2.Y. Delete the reference to 907 PRIMITIVE_ID_NV and LAYER_NV. 908 909 If EXT_geometry_shader4 is not supported, delete any reference to a 910 geometry shader. 911 912Dependencies on NV_vertex_program4 and NV_gpu_program4 913 914 If NV_vertex_program4 is not supported, delete any reference to 915 VERTEX_ID_NV. If NV_gpu_program4 is not supported, table X.2 needs to 916 refer to the "result" variables defined in the ARB_vertex_program 917 specification instead. 918 919Interactions with ARB_shader_objects and OpenGL 2.0 920 921 If neither ARB_shader_objects nor OpenGL 2.0 is supported, all references 922 to shader and program objects, as well as varying variables, should be 923 removed. This also means that functions including 924 TransformFeedbackVaryingsNV, GetVaryingLocationNV, GetActiveVaryingNV, 925 ActiveVaryingNV, and GetTransformFeedbackVaryingNV will not be 926 supported, and enums that are relevant only in the context of shader and 927 program objects will not be accepted. 928 929Errors 930 931 The error INVALID_OPERATION is generated by BeginQuery if called with an 932 <id> of zero, if the active query object name for <target> is non- zero, 933 or if <id> is the active query object name for any query type. 934 935 The error INVALID_OPERATION is generated by EndQuery if the active query 936 object name for <target> is zero. 937 938 The error INVALID_OPERATION is generated if Begin, or any command that 939 performs an explicit Begin, is called when: 940 941 * A geometry program or shader is not active AND the begin mode does not 942 match the allowed begin modes for the current transform feedback state 943 as given by table X.1. 944 945 * A geometry program or shader is active AND the output primitive type 946 (of the geometry program / shader) does not match the allowed begin 947 modes for the current transform feedback state as given by table X.1. 948 949 The error INVALID_OPERATION is generated by BeginTransformFeedbackNV if 950 there is no buffer object bound to index 0 in INTERLEAVED_ATTRIBS_NV 951 mode. 952 953 The error INVALID_OPERATION is generated by BeginTransformFeedbackNV if 954 the number of buffer objects bound in SEPARATE_ATTRIBS_NV mode is less 955 than the number of buffer objects required, as given by the current 956 transform feedback state. 957 958 The error INVALID_OPERATION is generated by BeginTransformFeedbackNV if 959 no attributes are specified to be captured. 960 961 The error INVALID_OPERATION is generated by BeginTransformFeedbackNV, 962 TransformFeedbackVaryingsNV, TransformFeedbackAttribsNV, or UseProgram or 963 LinkProgram, called on the currently in use program object, while 964 transform feedback is active. 965 966 The error INVALID_OPERATION is generated by EndTransformFeedbackNV while 967 transform feedback is inactive. 968 969 The error INVALID_OPERATION is generated by BindBufferRangeNV, 970 BindBufferOffsetNV or BindBufferBaseNV if <target> is 971 TRANSFORM_FEEDBACK_BUFFER_NV and <index> is greater or equal 972 than MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV. 973 974 The error INVALID_VALUE is generated by BindBufferRangeNV if the value of 975 <size> <= 0. 976 977 The error INVALID_VALUE is generated by BindBufferRangeNV or 978 BindBufferOffsetNV if <start> or <end> are not word-aligned. 979 980 The error INVALID_OPERATION is generated when any of the BindBuffer* 981 commands is called while transform feedback is active. 982 983 The error INVALID_OPERATION is generated by TransformFeedbackVaryingsNV 984 commands if any location appears more than once in the array <locations. 985 986 The error INVALID_OPERATION is generated by TransformFeedbackVaryingsNV 987 if any location in <locations> references a non-existing varying variable. 988 989 The error INVALID_OPERATION is generated by TransformFeedbackVaryingsNV 990 if <program> has not been linked successfully. 991 992 The error INVALID_OPERATION is generated by TransformFeedbackVaryingsNV 993 in INTERLEAVED_ATTRIBS_NV mode if the total number of components of all 994 varying variables specified in the array <locations> is greater than 995 MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS_NV. 996 997 The error INVALID_VALUE is generated by TransformFeedbackVaryingsNV or 998 TransformFeedbackAttribsNV in SEPARATE_ATTRIBS_NV mode if <count> is 999 greater than MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV. 1000 1001 The error INVALID_VALUE is generated by TransformFeedbackVaryingsNV in 1002 SEPARATE_ATTRIBS_NV mode if the number of components for each varying 1003 variable in the array <locations> is greater than 1004 MAX_TRANSFORM_FEEDBACK_SEPARATE_COMPONENTS_NV. 1005 1006 The error INVALID_VALUE is generated by TransformFeedbackAttribsNV in 1007 INTERLEAVED_ATTRIBS_NV mode if the sum of the values of the components of 1008 the attributes in the array <attribs> is greater than 1009 MAX_TRANSFORM_FEEDBACK_INTERLEAVED_COMPONENTS_NV. 1010 1011 The error INVALID_OPERATION is generated by TransformFeedbackAttribsNV if 1012 an enum value is specified more than once in the array <attribs>. 1013 1014 The error INVALID_OPERATION is generated by TransformFeedbackAttribsNV if 1015 the number of components for each attribute in the array <attribs> is 1016 outside the range [0,4]. 1017 1018 The error INVALID_VALUE is generated by TransformFeedbackAttribsNV if the 1019 index value is in the array <attribs> is outside the allowable range for 1020 an attribute enumerant corresponding to more than one real attribute. 1021 1022 The error INVALID_OPERATION is generated by GetVaryingLocationNV if 1023 <program> is not the name of a program object or if <program> has not been 1024 linked successfully. 1025 1026 The error INVALID_OPERATION is generated by GetActiveVaryingNV or 1027 ActiveVaryingNV if <program> is not the name of a program object. 1028 1029 The error INVALID_VALUE is generated by GetActiveVaryingNV if <index> is 1030 greater than or equal to ACTIVE_VARYINGS_NV. 1031 1032 The error INVALID_VALUE is generated by GetIntegerIndexedvEXT() or 1033 GetBooleanIndexedv() with <param> set to TRANSFORM_FEEDBACK_RECORD_NV if 1034 <index> is greater than or equal to TRANSFORM_FEEDBACK_ATTRIBS_NV. 1035 1036 The error INVALID_VALUE is generated by GetIntegerIndexedvEXT() or 1037 GetBooleanIndexedvEXT() with <param> set to 1038 TRANSFORM_FEEDBACK_BUFFER_BINDING_NV if <index> is greater than or equal 1039 to MAX_TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS_NV. 1040 1041 The error INVALID_VALUE is generated by GetTransformFeedbackVaryingsNV if 1042 <index> is greater than the program object specific value 1043 TRANSFORM_FEEDBACK_VARYINGS_NV - 1. 1044 1045 The error INVALID_OPERATION is generated by 1046 GetTransformFeedbackVaryingsNV if <program> is not the name of a program 1047 object, or if program object has not been linked successfully. 1048 1049New State 1050 1051 (Add a new table: Table 6.X, Transform Feedback State) 1052 1053 Get Value Type Get Command Init. Value Description Sec Attrib 1054 ------------------ ------ -------------- ------------ ------------------------- ----- ------ 1055 TRANSFORM_FEEDBACK_ Z2 GetIntegerv INTERLEAVED_ Transform feedback mode 2.Y - 1056 BUFFER_MODE_NV ATTRIBS_NV 1057 TRANSFORM_FEEDBACK_ Z2 GetIntegerv 0 Number of attributes to 2.Y - 1058 ATTRIBS_NV capture in transform 1059 feedback mode 1060 TRANSFORM_FEEDBACK_ Z+ GetIntegerv 0 Buffer object bound to 6.1.13 - 1061 BUFFER_BINDING_NV generic bind point for 1062 transform feedback. 1063 TRANSFORM_FEEDBACK_ nx3*Z+ GetInteger- 0 Name, component count, 6.1.14 - 1064 RECORD_NV IndexedvEXT and index of each 1065 attribute captured 1066 TRANSFORM_FEEDBACK_ nxZ+ GetInteger- 0 Buffer object bound to 6.1.13 - 1067 BUFFER_BINDING_NV IndexedvEXT each transform feedback 1068 attribute stream. 1069 TRANSFORM_FEEDBACK_ nxZ+ GetInteger- 0 Start offset of binding 6.1.13 - 1070 BUFFER_START_NV IndexedvEXT range for each transform 1071 feedback attrib. stream 1072 TRANSFORM_FEEDBACK_ nxZ+ GetInteger- 0 Size of binding range 6.1.13 - 1073 BUFFER_SIZE_NV IndexedvEXT for each transform 1074 feedback attrib. stream 1075 1076 (Modify Table 6.37, p 298, updating the query object state to cover 1077 transform feedback.) 1078 1079 Get Value Type Get Command Init. Value Description Sec Attribute 1080 ---------------- ---- ---------------- ----------- ------------------------- ----- --------- 1081 CURRENT_QUERY 3xZ+ GetQueryiv 0 Active query object name 2.X - 1082 (occlusion, timer, xform 1083 feedback) 1084 QUERY_RESULT 3xZ+ GetQueryObjectiv 0 Query object result 2.X - 1085 (samples passed, Time 1086 elapsed, feedback data amount) 1087 QUERY_RESULT_AVAILABLE 3xZ+ GetQueryObjectiv TRUE Query object result 2.X - 1088 available? 1089 1090 (Modify Table 6.29, p. 290, Program Object State. Add the following state.) 1091 1092 Get Value Type Get Command Init. Value Description Sec Attribute 1093 ---------------- ---- ------------ ----------- ------------------------- ----- --------- 1094 ACTIVE_VARYINGS_NV Z+ GetProgramiv 0 Number of active varyings 2.15.3 - 1095 ACTIVE_VARYING_MAX_ Z+ GetProgramiv 0 Maximum active varying 2.15.3 - 1096 LENGTH_NV name length 1097 TRANSFORM_FEEDBACK_ Z2 GetProgramiv INTERLEAVED_ Transform feedback mode 6.1.14 - 1098 BUFFER_MODE_NV ATTRIBS_NV for the program 1099 TRANSFORM_FEEDBACK_ Z+ GetProgramiv 0 Number of varyings to 6.1.14 - 1100 VARYINGS_NV stream to buffer object(s) 1101 - nxZ+ GetVarying- - Location of each active 2.15.3 - 1102 LocationNV varying variable 1103 - Z+ GetActive- - Size of each active 2.15.3 - 1104 VaryingNV varying variable 1105 - Z+ GetActive- - Type of each active 2.15.3 - 1106 VaryingNV varying variable 1107 - 0+x- GetActive- - Name of each active 2.15.3 - 1108 char VaryingNV varying variable 1109 - Z+ GetTransform- - Varying location for one 6.1.14 - 1110 Feedback- of the multiple varyings 1111 VaryingNV to capture 1112 1113New Implementation Dependent State 1114 1115 (Modify Table 6.34, p. 295. Update the query object state to cover 1116 transform feedback.) 1117 1118 Get Value Type Get Command Minimum Value Description Sec Attribute 1119 -------------------- ---- ----------- ------------- -------------------------- ------ --------- 1120 QUERY_COUNTER_BITS 2xZ+ GetQueryiv see 6.1.12 Asynchronous query counter 6.1.12 - 1121 bits (occlusion, timer, 1122 transform feedback queries) 1123 1124 (Add a new table, Table 6.X. Transform Feedback State.) 1125 1126 NOTE: In the "GetValue" columns below, MXFB stands for 1127 "MAX_TRANSFORM_FEEDBACK". 1128 1129 Get Value Type Get Command Minimum Value Description Sec Attribute 1130 -------------------- ---- ----------- ------------- -------------------------- ------ --------- 1131 MXFB_INTERLEAVED_ Z+ GetIntegerv 64 Max number of components to 2.Y - 1132 COMPONENTS_NV write to a single buffer in 1133 interleaved mode 1134 MXFB_SEPARATE_ Z+ GetIntegerv 4 Max number of separate 2.Y - 1135 ATTRIBS_NV attributes or varyings that 1136 can be captured in transform 1137 feedback 1138 MXFB_SEPARATE Z+ GetIntegerv 4 Max number of components 2.Y - 1139 COMPONENTS_NV per attribute or varying 1140 in separate mode 1141 1142Issues 1143 1144 1. How does transform feedback differ from core GL feedback? 1145 1146 * Transform feedback writes vertex data to buffer objects, which allows 1147 the data returned to be used directly by vertex pulling. GL feedback 1148 mode writes vertex data to a buffer in system memory. 1149 1150 * Transform feedback is done after transformation, but prior to 1151 clipping. The primitives returned contain the original transformed 1152 vertices produced by vertex or geometry program execution, and does 1153 not contain any primitives inserted by clipping. 1154 1155 * Transform feedback supports only a single basic output primitive type 1156 (points, lines, or triangles), while core GL feedback mode supports 1157 all primitive types. Since only one primitive type is supported, the 1158 data returned does not contain tokens describing each primitive being 1159 fed back. Primitive tokens make the data returned by GL feedback mode 1160 irregular and unsuitable for vertex pulling. 1161 1162 2. What should this extension be called? 1163 1164 RESOLVED: The current name is "NV_transform_feedback", playing off the 1165 fact that it is transformed primitives that are handled and the 1166 similarities to GL feedback mode. 1167 1168 3. What happens if you bind a buffer for transform feedback that is 1169 currently bound for other purposes? Should we somehow detect this case 1170 and produce an error? 1171 1172 !!! NBC I feel strongly that we should follow the precedent for 1173 Map/Unmap. The reason that MapBuffer and UnmapBuffer are a precedent 1174 here is because while a buffer object is in the mapped state, no GL 1175 commands are allowed to operate on the buffer object's data. So by 1176 analogy, while a buffer is being used for transform feedback, no other 1177 GL commands should be allowed to operate on the buffer object's data. 1178 This includes initiating any rendering which would cause the GL to 1179 source data from an active transform feedback buffer object. 1180 1181 UNRESOLVED 1182 1183 4. Should this extension include any new buffer object binding targets, or 1184 should it overload ARRAY_BUFFER, or should we skip the binding target 1185 altogether in favor of a buffer object name accepted directly by the 1186 new GL commands? 1187 1188 RESOLVED: There are new binding points for XFB along with a new API 1189 (BindBufferBase etc) to set the internal binding points. A new binding 1190 point, TRANSFORM_FEEDBACK_BUFFER_NV is also introduced. 1191 1192 5. Previous buffer object extensions provided a way to have existing GL 1193 commands reference a buffer object instead of a user-supplied buffer. 1194 Should the new commands introduced here allow referencing a 1195 user-supplied buffer in addition to a buffer object? 1196 1197 RESOLVED: No. A program can get the contents of the feedback buffer back 1198 to the CPU using MapBuffer and GetBufferSubData 1199 1200 6. Is BeginTransformFeedback really necessary? Could the query just 1201 initiate the transform feedback mode? 1202 1203 RESOLUTION: Using BeginTransformFeedback and EndTransformFeedback gives 1204 a clean place to spec all of the transform-feedback-specific issues 1205 without cluttering up the query language. Also, the queries don't have 1206 to be done at the same time as beginning and ending the feedback 1207 process. 1208 1209 7. What usage enums should be provided to glBufferData for use in 1210 conjunction with transform feedback? 1211 1212 RESOLVED: STREAM_COPY or STREAM_READ are expected to be the most common 1213 usages. If a buffer object is being written by the GL through transform 1214 feedback, and the contents of the buffer object are subsequently being 1215 consumed by the GL (e.g. by being used as a vertex buffer object), then 1216 this is a *_COPY usage. If the buffer object is being written by the GL 1217 through transform feedback, but is being consumed by the application 1218 (e.g. being mapped for read), this is a *_READ usage. The temporal 1219 (STREAM, STATIC, or DYNAMIC) component of the usage enum is determined 1220 by the ratio between how often the contents of the buffer object are 1221 modified and how often operations that source data from the buffer 1222 object occur. 1223 1224 8. What should the behavior be when a buffer object is the active target 1225 of transform feedback, and it is deleted via DeleteBuffers? 1226 1227 RESOLVED: Deletion is deferred until the EndTransformFeedback if 1228 transform feedback is active. 1229 1230 9. Should we allow more buffers to be bound than are used? 1231 1232 RESOLVED: Yes. The extra buffers are not in the way and can stay bound. 1233 1234 10. Should we allow feedback to buffer lists with holes (i.e. 0 and 2 1235 bound)? 1236 1237 RESOLVED: No. This makes for an ugly API with the potential for bugs, 1238 without any real benefit. The application can as well bind all buffers 1239 needed to incremented indices. It is an invalid operation to not have a 1240 buffer bound where one is required. 1241 1242 11. Why only one feedback primitive mode per feedback invocation? 1243 1244 RESOLVED: Having primitive tokens breaks up the stream and makes it less 1245 amenable to being read back in as a vertex buffer. Also, mixing multiple 1246 primitive types makes the counting of primitives less clear for the 1247 application. 1248 1249 12. Is RasterPos fed back? 1250 1251 RESOLVED: No. 1252 1253 13. Is DrawPixels/CopyPixels/Bitmap fed back? 1254 1255 RESOLVED: No. Rasterization occurs as normal, but there is no 1256 output to the feedback buffer. This is consistent with taking a 1257 tap out of the pipe before clipping. 1258 1259 14. Why do we need new BindBuffer* functions? 1260 1261 RESOLVED: All previous buffer object extensions have been retrofits of 1262 existing pointer-based APIs. New extensions built assuming buffer 1263 objects don't have that history, so need a new API. The functionality of 1264 these new functions combines the functionality of BindBuffer, to set the 1265 external bind point used by calls like MapBuffer and BufferSubData, with 1266 the functionality to set an internal bind point like VertexAttribPointer 1267 does. 1268 1269 15. How do the transform feedback indices, passed to the BindBuffer* 1270 commands, work with multiple bindings? 1271 1272 RESOLVED: The same way that they work with vertex arrays. There is one 1273 external bind point, TRANSFORM_FEEDBACK_BUFFER_NV. There are n internal 1274 bind points, selected with the <index> parameter to the BindBuffer* 1275 commands, where n is some implementation dependent limit. The 1276 BindBuffer* commands take the buffer passed and bind it to the external 1277 bind point, as well as to the selected internal bind point. 1278 1279 For example: 1280 1281 BindBufferOffsetNV(TRANSFORM_FEEDBACK_BUFFER_NV, 0, 1, 12); 1282 // XFB index 0 points at buffer 1 with offset 12 1283 1284 BindBuffer(TRANSFORM_FEEDBACK_BUFFER_NV, 2); 1285 // Buffer 2 is now bound to the external bind point. XFB index 0 still 1286 // points at buffer 1 1287 1288 MapBuffer(TRANSFORM_FEEDBACK_BUFFER_NV, ...); 1289 // Maps buffer 2 1290 1291 16. How are quads/quadstrips/polygons tessellated into triangles? 1292 1293 RESOLVED: In an implementation-dependent manner. OpenGL doesn't define 1294 quads or polygons in terms of triangles, so there is no one correct way 1295 to do it, and different GPUs may implement the behavior differently. A 1296 quad may be split into two triangles in several different ways, and an 1297 application may not rely on this behavior. 1298 1299 17. How does this extension interact with display lists? 1300 1301 RESOLVED: Just like the VBO extension, none of the BindBuffer* commands 1302 are compiled into a display list. 1303 1304 18. Does polygon mode state affect the logic that determines if the 1305 transform feed back primitive mode and the render mode states are 1306 valid at the start of transform feedback mode? 1307 1308 RESOLVED: PolygonMode has no influence on the BeginTransFormFeedback 1309 primitiveMode check since it is performed later, in raster. 1310 1311 19. What to do with incomplete primitives? 1312 1313 RESOLVED: If there is no room to store one or more vertices of a 1314 primitive in a buffer object, none of the vertices in that primitive are 1315 written to the buffer. If a partial primitive enters transform feedback 1316 (i.e. only two vertices sent in triangles mode), none of the vertices in 1317 that primitive are written to the buffer object. 1318 1319 20. Why does TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN_NV have a 1320 TRANSFORM_FEEDBACK prefix but PRIMITIVES_GENERATED_NV doesn't? 1321 1322 RESOLVED: The number of primitives generated is independent of any 1323 feedback that is active. The number of primitives that are written is 1324 only valid for transform feedback - another extension could conceivably 1325 have a different way of writing out primitives that would require a 1326 similar but distinct token. 1327 1328 21. When a GLSL vertex shader is active, what happens in transform 1329 feedback mode if non-active varying variables are specified? 1330 1331 DISCUSSION: Active varying variables are varying variables, declared in 1332 the shader, that the linker determined are actually needed. As an 1333 optimization, the linker can discard the ones declared, but not 1334 needed. If non-active varying variables need to be fed into a buffer 1335 object, the linker should not perform this optimization. 1336 1337 There are three suggested resolutions to this problem: 1338 1339 1. The set of varying variables that need to be streamed to a buffer 1340 object in transform feedback mode are set as a property of the 1341 program object, and are taken into account during the link step. 1342 This means that changing the set means the application will have to 1343 re-link the program object in order to have the change take effect. 1344 1345 2. The set of varying variables that need to be streamed to a buffer 1346 object in transform feedback mode are specified after the program 1347 object has been linked. This is the most flexible option from the 1348 applications perspective, but this might mean that a) specifying 1349 this set could force the GL to re-link 'under the covers', and b) 1350 could mean that the GL runs out of varying variable slots because 1351 the combined total of the set of active varyings and the varyings 1352 to stream in transform feedback mode is too large. 1353 1354 3. This solution is a hybrid of the above two approaches. The set of 1355 potential varying variables that need to be streamed to a buffer 1356 object are set as a property of the program object. These varying 1357 variables are marked as active by the application and therefore 1358 cannot be eliminated during the link step. However, a sub-set of 1359 varying variables to actually stream to a buffer object can be 1360 changed without the application having to re-link the program 1361 object. This approach gives the application flexibility to change 1362 the set of varying variables to stream, while it eliminates the 1363 need for the GL to compile 'under the covers'. 1364 1365 RESOLUTION: Option 3 offers a good compromise, and therefore we'll go 1366 with that. 1367 1368 22. Given option 3 in the previous resolution, how to specify that a 1369 varying variable has to be considered active by the linker? 1370 1371 DISCUSSION: There are two approaches to the application specifying which 1372 varying variables are active. We can either provide a simple flag that 1373 specifies that all varying variables are considered active, or we can 1374 provide a more complex mechanism where the application can specify an 1375 individual varying variable as being active. 1376 1377 RESOLUTION: RESOLVED. The 'all or nothing' flag is a simple idea, but 1378 has a drawback when used with a 'uber-shader' that implements many paths 1379 to achieve an effect, but only one path is used during any run of the 1380 shader. In this case, a lot more varying variables might be flagged as 1381 active then really is necessary, running the risk of running out of 1382 resources. Therefore, we'll provide a mechanism for the application to 1383 specify on a per varying variable basis if it is active. 1384 1385 23. Given the discussion in the previous issues, should a 1386 GetActiveVarying() command be added, modeled after the existing 1387 getActiveUniform() command? 1388 1389 DISCUSSION: Such a command will return the list of active uniforms, 1390 after the program object has been linked. As per issue 22's resolution, 1391 the complete set of varying variables that could be streamed to a buffer 1392 object needs to be specified before the program object is linked. 1393 1394 It can be useful to an application to stream out a subset of the active 1395 varying variables or to find out the whole set of active varyings, 1396 especially since the set can be implementation dependent. 1397 1398 RESOLUTION: YES. 1399 1400 24. What is proper use of the command ActiveVaryingNV()? 1401 1402 RESOLVED: The application is well advised to force any varying variable 1403 live that it needs for transform feedback purposes. The set of active 1404 varying variables are linker dependent. For example, if a program object 1405 has no fragment shader, then the LinkProgram command cannot typically 1406 determine which built-in varying variables, output by a geometry or 1407 vertex shader, are active. This is because the fragment processing state 1408 can change, and therefore such a determination cannot be made until a 1409 render command is issued. Furthermore, any user-defined varyings are 1410 likely to be marked as non-active if there is no fragment shader because 1411 they are guaranteed to have no effect on fixed-function fragment 1412 processing. If there is both a vertex (or geometry) and fragment shader 1413 in a program object, the application can probably deduce what will be an 1414 active varying variable, or not. But beware of any (static) flow-control 1415 that the linker can use to do cross vertex- fragment optimization to 1416 cull any varying variables. 1417 1418 25. Are primitives sent down the pipeline after transform feedback, or 1419 discarded? 1420 1421 RESOLVED: Primitives can be optionally discarded before rasterization by 1422 calling Enable and Disable with RASTERIZER_DISCARD_NV. When enabled, 1423 primitives are discarded after vertex attributes are recorded into the 1424 buffer objects bound to transform feedback. When disabled, primitives 1425 are passed through to the rasterization stage to be clipped and 1426 rasterized normally. All rasterization operations are discarded, not 1427 just those that are fed back into the buffer. 1428 1429 This applies to DrawPixels, CopyPixels, Bitmap, Clear, Accum as well. 1430 1431 26. If a varying is declared as an array, is the whole array streamed out? 1432 1433 RESOLVED: No, the application has to specify which elements of an array 1434 it wants to stream out. Implementations might not be able to stream out 1435 a large number of components to a single buffer object. If that is the 1436 case, the application can stream each element of an array to a different 1437 buffer object in TRANSFORM_FEEDBACK_SEPARATE_ATTRIBS mode. 1438 1439 27. Is it possible to capture attributes when using the fixed-function 1440 pipeline? 1441 1442 RESOLVED: Yes, there is nothing that precludes this. The application is 1443 responsible for sending down the needed vertex attributes and setting 1444 the GL state, as desired, for the attributes it wants to stream to a 1445 buffer object. Note that VERTEX_ID_NV is not defined in fixed-function. 1446 1447 28. Is it possible to record hardware-generated primitive ID values that 1448 would be available to a pixel shader? 1449 1450 RESOLVED: Transform feedback can only record the primitive ID values 1451 emitted per-vertex by a geometry shader or program. While each 1452 primitive recorded for transform-feedback has a well-defined primitive 1453 ID, transform feedback is only capable of recording the attributes of 1454 individual vertices. 1455 1456 29. Does transform feedback support the ability to capture per-vertex 1457 layer outputs, as provided by EXT_geometry_shader4 and 1458 NV_geometry_program4? 1459 1460 RESOLVED: Yes. For GLSL shaders, it is sufficient to reference the 1461 built-in varying "gl_Layer". For assembly geometry programs, the 1462 original version of the spec did not provide an enum allowing you to 1463 name "result.layer" in TransformFeedbackAttribsNV. This was an 1464 oversight in the original spec, which was fixed by version 14. An 1465 updated driver will be required to take advantage of this capability; 1466 NVIDIA drivers supporting this extension published prior to February 1467 2008 will not be able to capture "result.layer". The value captured for 1468 LAYER_NV will be undefined unless a geometry program that writes 1469 "result.layer" is active. 1470 1471Revision History 1472 1473 Rev. Date Author Changes 1474 ---- -------- -------- ----------------------------------------- 1475 18 03/09/11 mjk Minor typo fixes. 1476 1477 17 01/28/11 pbrown Change return value for start/size queries 1478 when no buffer bound from -1 to zero, to 1479 match state tables (Bug 7318), as done by 1480 Jon Leech in related EXT/ARB extensions and 1481 the core API specification. 1482 1483 16 08/17/08 pbrown Remove a non-existent function from the 1484 set of functions that can generate invalid 1485 operation errors while XFB is active. 1486 1487 15 02/20/08 pbrown Fix incorrect minimum for MAX_TRANSFORM_ 1488 FEEDBACK_SEPARATE_COMPONENTS_NV. Should be 1489 4, not 16. 1490 1491 14 02/04/08 pbrown Fixed a problem with the spec where we were 1492 unable to record "result.layer" using the 1493 assembly interface. Added a new enum to 1494 address. 1495 1496 13 11/28/07 pbrown Specified the captured primitive ID to be 1497 undefined unless a geometry shader emits it 1498 as a vertex output. XFB can only record 1499 per-vertex data. 1500 1501 12 09/27/07 pbrown Removed incorrect error description from 1502 the errors section -- buffer objects don't 1503 need to be bound before calling Transform- 1504 Feedback{Attribs,Varyings}NV, just before 1505 BeginTransformFeedbackNV. 1506 1507 11 08/28/07 pbrown Added an error calling BeginTransformFeedback 1508 if no attributes would be captured (i.e., 1509 attribute count is 0 for ASM or no attributes 1510 specified in the active GLSL program). 1511 1512 10 02/09/07 pbrown Updated status section (now released). 1513 1514 9 10/23/06 pbrown Fixed prototype for GetIntegerIndexedEXT and 1515 GetBooleanIndexedEXT: <index> is unsigned. 1516 1517 8 10/19/06 pbrown Removed stray addition of GetFloatIndexedvEXT 1518 and GetDoubleIndexedvEXT. Minor wording 1519 fixes. 1520 1521 7 10/17/06 pbrown Rename from EXT to NV while working on 1522 standardizing a functional subset extension 1523 that will be named EXT_transform_feedback. We 1524 expect that the EXT should be equivalent to 1525 the NV, except that it (a) removes support for 1526 non-GLSL usage, (b) removes the ability to 1527 change the set of varyings captured without 1528 relinking. NVIDIA expects to support both the 1529 NV and EXT forms of this extension going 1530 forward. Fix state table formatting. Removed 1531 GetFloatIndexedvEXT and GetDoubleIndexedvEXT, 1532 which are not needed by this and related 1533 extensions. 1534 1535 6 09/11/06 pbrown Fix bad prototype for GetActiveVaryingEXT 1536 and bad references to "GetActiveVaryingsEXT". 1537 Fix enum names for INTERLEAVED_ATTRIBS_EXT and 1538 SEPARATE_ATTRIBS_EXT (no TRANSFORM_ FEEDBACK 1539 prefix). Remove erroneous state table entries 1540 that were obsoleted by the introduction of the 1541 TRANSFORM_FEEDBACK_RECORD_EXT query. 1542 1543 5 08/31/06 pbrown Fix miscellaneous spec errata. Record enum 1544 values that weren't documented in previous 1545 spec versions. Use correct function names for 1546 indexed "Get" functions. Clarify that GLSL 1547 interactions mean that some functions and 1548 enums defined here aren't supported if GLSL 1549 isn't supported. Fixed the double-assignment 1550 of several TransformFeedbackAttribsEXT enums 1551 and re-packed that portion of the enum range. 1552 Clarify that several new functions are 1553 non-listable. Fix the query tokens for buffer 1554 object range bindings to match the API 1555 (start/size, not start/end). 1556 1557 4 08/30/06 pbrown Reformatting as a plaintext document 1558 instead of an exported MS Word document. 1559 1560 3 07/26/06 barthold Forgot a few changes w.r.t. version 2. 1561 1562 2 07/14/06 barthold Change BindBufferRangeEXT to take an 1563 offset and size parameter. Change 1564 BindBufferOffsetEXT to take an offset 1565 parameter. 1566 1567 1 barthold Internal spec development. 1568