1Name 2 3 NV_vertex_program4 4 5Name Strings 6 7 (none) 8 9Contact 10 11 Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com) 12 13Status 14 15 Shipping for GeForce 8 Series (November 2006) 16 17Version 18 19 Last Modified Date: 12/14/09 20 NVIDIA Revision: 7 21 22Number 23 24 325 25 26Dependencies 27 28 OpenGL 1.1 is required. 29 30 This extension is written against the OpenGL 2.0 specification. 31 32 ARB_vertex_program is required. 33 34 NV_gpu_program4 is required. This extension is supported if 35 "GL_NV_gpu_program4" is found in the extension string. 36 37 NVX_instanced_arrays affects the definition of this extension. 38 39Overview 40 41 This extension builds on the common assembly instruction set 42 infrastructure provided by NV_gpu_program4, adding vertex program-specific 43 features. 44 45 This extension provides the ability to specify integer vertex attributes 46 that are passed to vertex programs using integer data types, rather than 47 being converted to floating-point values as in existing vertex attribute 48 functions. The set of input and output bindings provided includes all 49 bindings supported by ARB_vertex_program. This extension provides 50 additional input bindings identifying the index of the vertex when vertex 51 arrays are used ("vertex.id") and the instance number when instanced 52 arrays are used ("vertex.instance", requires EXT_draw_instanced). It 53 also provides output bindings allowing vertex programs to directly specify 54 clip distances (for user clipping) plus a set of generic attributes that 55 allow programs to pass a greater number of attributes to subsequent 56 pipeline stages than is possible using only the pre-defined fixed-function 57 vertex outputs. 58 59 By and large, programs written to ARB_vertex_program can be ported 60 directly by simply changing the program header from "!!ARBvp1.0" to 61 "!!NVvp4.0", and then modifying instructions to take advantage of the 62 expanded feature set. There are a small number of areas where this 63 extension is not a functional superset of previous vertex program 64 extensions, which are documented in the NV_gpu_program4 specification. 65 66New Procedures and Functions 67 68 void VertexAttribI1iEXT(uint index, int x); 69 void VertexAttribI2iEXT(uint index, int x, int y); 70 void VertexAttribI3iEXT(uint index, int x, int y, int z); 71 void VertexAttribI4iEXT(uint index, int x, int y, int z, int w); 72 73 void VertexAttribI1uiEXT(uint index, uint x); 74 void VertexAttribI2uiEXT(uint index, uint x, uint y); 75 void VertexAttribI3uiEXT(uint index, uint x, uint y, uint z); 76 void VertexAttribI4uiEXT(uint index, uint x, uint y, uint z, uint w); 77 78 void VertexAttribI1ivEXT(uint index, const int *v); 79 void VertexAttribI2ivEXT(uint index, const int *v); 80 void VertexAttribI3ivEXT(uint index, const int *v); 81 void VertexAttribI4ivEXT(uint index, const int *v); 82 83 void VertexAttribI1uivEXT(uint index, const uint *v); 84 void VertexAttribI2uivEXT(uint index, const uint *v); 85 void VertexAttribI3uivEXT(uint index, const uint *v); 86 void VertexAttribI4uivEXT(uint index, const uint *v); 87 88 void VertexAttribI4bvEXT(uint index, const byte *v); 89 void VertexAttribI4svEXT(uint index, const short *v); 90 void VertexAttribI4ubvEXT(uint index, const ubyte *v); 91 void VertexAttribI4usvEXT(uint index, const ushort *v); 92 93 void VertexAttribIPointerEXT(uint index, int size, enum type, 94 sizei stride, const void *pointer); 95 96 void GetVertexAttribIivEXT(uint index, enum pname, int *params); 97 void GetVertexAttribIuivEXT(uint index, enum pname, uint *params); 98 99 (note: all these functions are shared with the EXT_gpu_shader4 100 extension.) 101 102New Tokens 103 104 Accepted by the <pname> parameters of GetVertexAttribdv, 105 GetVertexAttribfv, GetVertexAttribiv, GetVertexAttribIivEXT, and 106 GetVertexAttribIuivEXT: 107 108 VERTEX_ATTRIB_ARRAY_INTEGER_EXT 0x88FD 109 110 (note: this token is shared with the EXT_gpu_shader4 extension.) 111 112Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) 113 114 Modify Section 2.7 (Vertex Specification), p.20 115 116 (insert before last paragraph, p.22) The commands 117 118 void VertexAttribI[1234]{i,ui}EXT(uint index, T values); 119 void VertexAttribI[1234]{i,ui}vEXT(uint index, T values); 120 void VertexAttribI4{b,s,ub,us}vEXT(uint index, T values); 121 122 specify fixed-point coordinates that are not converted to floating-point 123 values, but instead are represented as signed or unsigned integer values. 124 Vertex programs that use integer instructions may read these attributes 125 using integer data types. A vertex program that attempts to read a vertex 126 attribute as a float will get undefined results if the attribute was 127 specified as an integer, and vice versa. 128 129 (modify second paragraph, p.23) Setting generic vertex attribute zero 130 specifies a vertex; the four vertex coordinates are taken from the values 131 of attribute zero. A Vertex2, Vertex3, or Vertex4 command is completely 132 equivalent to the corresponding VertexAttrib* or VertexAttribI* command 133 with an index of zero. ... 134 135 (insert at end of function list, p.24) 136 137 void VertexAttribIPointerEXT(uint index, int size, enum type, 138 sizei stride, const void *pointer); 139 140 (modify last paragraph, p.24) The <index> parameter in the 141 VertexAttribPointer and VertexAttribIPointerEXT commands identify the 142 generic vertex attribute array being described. The error INVALID_VALUE 143 is generated if <index> is greater than or equal to MAX_VERTEX_ATTRIBS. 144 Generic attribute arrays with integer <type> arguments can be handled in 145 one of three ways: converted to float by normalizing to [0,1] or [-1,1] 146 as specified in table 2.9, converted directly to float, or left as integer 147 values. Data for an array specified by VertexAttribPointer will be 148 converted to floating-point by normalizing if the <normalized> parameter 149 is TRUE, and converted directly to floating-point otherwise. Data for an 150 array specified by VertexAttribIPointerEXT will always be left as integer 151 values. 152 153 (modify Table 2.4, p. 25) 154 155 Integer 156 Command Sizes Handling Types 157 ---------------------- ------- --------- ----------------- 158 VertexPointer 2,3,4 cast ... 159 NormalPointer 3 normalize ... 160 ColorPointer 3,4 normalize ... 161 SecondaryColorPointer 3 normalize ... 162 IndexPointer 1 cast ... 163 FogCoordPointer 1 n/a ... 164 TexCoordPointer 1,2,3,4 cast ... 165 EdgeFlagPointer 1 integer ... 166 VertexAttribPointer 1,2,3,4 flag ... 167 VertexAttribIPointerEXT 1,2,3,4 integer byte, ubyte, short, 168 ushort, int, uint 169 170 Table 2.4: Vertex array sizes (values per vertex) and data types. The 171 "integer handling" column indicates how fixed-point data types are 172 handled: "cast" means that they converted to floating-point directly, 173 "normalize" means that they are converted to floating-point by 174 normalizing to [0,1] (for unsigned types) or [-1,1] (for signed types), 175 "integer" means that they remain as integer values, and "flag" means 176 that either "cast" or "normalized" applies, depending on the setting of 177 the <normalized> flag in VertexAttribPointer. 178 179 (modify end of pseudo-code, pp. 27-28) 180 181 for (j = 1; j < genericAttributes; j++) { 182 if (generic vertex attribute j array enabled) { 183 if (generic vertex attribute j array is a pure integer array) { 184 VertexAttribI[size][type]vEXT(j, generic vertex attribute j 185 array element i); 186 } else if (generic vertex attribute j array normalization flag 187 is set and <type> is not FLOAT or DOUBLE) { 188 VertexAttrib[size]N[type]v(j, generic vertex attribute j 189 array element i); 190 } else { 191 VertexAttrib[size][type]v(j, generic vertex attribute j 192 array element i); 193 } 194 } 195 } 196 197 if (generic vertex attribute 0 array enabled) { 198 if (generic vertex attribute 0 array is a pure integer array) { 199 VertexAttribI[size][type]vEXT(0, generic vertex attribute 0 200 array element i); 201 } else if (generic vertex attribute 0 array normalization flag 202 is set and <type> is not FLOAT or DOUBLE) { 203 VertexAttrib[size]N[type]v(0, generic vertex attribute 0 204 array element i); 205 } else { 206 VertexAttrib[size][type]v(0, generic vertex attribute 0 207 array element i); 208 } 209 } 210 211 Modify Section 2.X, GPU Programs 212 213 (insert after second paragraph) 214 215 Vertex Programs 216 217 Vertex programs are used to compute the transformed attributes of a 218 vertex, in lieu of the set of fixed-function operations described in 219 sections 2.10 through 2.13. Vertex programs are run on a single vertex at 220 a time, and the state of neighboring vertices is not available. The 221 inputs available to a vertex program are the vertex attributes described 222 in section 2.7. The results of the program are the attributes of a 223 transformed vertex, which include (among other things) a transformed 224 position, colors, and texture coordinates. The vertices transformed by a 225 vertex program are then processed normally by the remainder of the GL 226 pipeline. 227 228 Modify Section 2.X.2, Program Grammar 229 230 (replace third paragraph) 231 232 Vertex programs are required to begin with the header string "!!NVvp4.0". 233 This header string identifies the subsequent program body as being a 234 vertex program and indicates that it should be parsed according to the 235 base NV_gpu_program4 grammar plus the additions below. Program string 236 parsing begins with the character immediately following the header string. 237 238 (add the following grammar rules to the NV_gpu_program4 base grammar) 239 240 <resultUseW> ::= <resultVarName> <arrayMem> <optWriteMask> 241 | <resultColor> <optWriteMask> 242 | <resultColor> "." <colorType> <optWriteMask> 243 | <resultColor> "." <faceType> <optWriteMask> 244 | <resultColor> "." <faceType> "." <colorType> 245 "." <optWriteMask> 246 247 <resultUseD> ::= <resultColor> 248 | <resultColor> "." <colorType> 249 | <resultColor> "." <faceType> 250 | <resultColor> "." <faceType> "." <colorType> 251 | <resultMulti> 252 253 <attribBasic> ::= <vtxPrefix> "position" 254 | <vtxPrefix> "weight" <optArrayMemAbs> 255 | <vtxPrefix> "normal" 256 | <vtxPrefix> "fogcoord" 257 | <attribTexCoord> <optArrayMemAbs> 258 | <attribGeneric> <arrayMemAbs> 259 | <vtxPrefix> "id" 260 | <vtxPrefix> "instance" 261 262 <attribColor> ::= <vtxPrefix> "color" 263 264 <attribMulti> ::= <attribTexCoord> <arrayRange> 265 | <attribGeneric> <arrayRange> 266 267 <attribTexCoord> ::= <vtxPrefix> "texcoord" 268 269 <attribGeneric> ::= <vtxPrefix> "attrib" 270 271 <vtxPrefix> ::= "vertex" "." 272 273 <resultBasic> ::= <resPrefix> "position" 274 | <resPrefix> "fogcoord" 275 | <resPrefix> "pointsize" 276 | <resultTexCoord> <optArrayMemAbs> 277 | <resultClip> <arrayMemAbs> 278 | <resultGeneric> <arrayMemAbs> 279 | <resPrefix> "id" 280 281 <resultColor> ::= <resPrefix> "color" 282 283 <resultMulti> ::= <resultTexCoord> <arrayRange> 284 | <resultClip> <arrayRange> 285 | <resultGeneric> <arrayRange> 286 287 <resultTexCoord> ::= <resPrefix> "texcoord" 288 289 <resultClip> ::= <resPrefix> "clip" 290 291 <resultGeneric> ::= <resPrefix> "attrib" 292 293 <resPrefix> ::= "result" "." 294 295 (add the following subsection to Section 2.X.3.2, Program Attribute 296 Variables) 297 298 Vertex program attribute variables describe the attributes of the vertex 299 being transformed, as specified by the application. The set of available 300 bindings is enumerated in Table X.X. Except where otherwise noted, all 301 vertex program attribute bindings are four-component floating-point 302 vectors. 303 304 Vertex Attribute Binding Components Underlying State 305 ------------------------ ---------- ------------------------------ 306 vertex.position (x,y,z,w) object coordinates 307 vertex.normal (x,y,z,1) normal 308 vertex.color (r,g,b,a) primary color 309 vertex.color.primary (r,g,b,a) primary color 310 vertex.color.secondary (r,g,b,a) secondary color 311 vertex.fogcoord (f,0,0,1) fog coordinate 312 vertex.texcoord (s,t,r,q) texture coordinate, unit 0 313 vertex.texcoord[n] (s,t,r,q) texture coordinate, unit n 314 vertex.attrib[n] (x,y,z,w) generic vertex attribute n 315 vertex.id (id,-,-,-) vertex identifier (integer) 316 vertex.instance (i,-,-,-) primitive instance number (integer) 317 vertex.texcoord[n..o] (x,y,z,w) array of texture coordinates 318 vertex.attrib[n..o] (x,y,z,w) array of generic vertex attributes 319 320 Table X.X, Vertex Program Attribute Bindings. <n> and <o> refer to 321 integer constants. Only the "vertex.texcoord" and "vertex.attrib" 322 bindings are available in arrays. 323 324 NVIDIA Note: The "vertex.weight" and "vertex.matrixindex" bindings 325 described in ARB_vertex_program use state provided only by extensions 326 not supported by NVIDIA implementations and are not available. 327 328 If a vertex attribute binding matches "vertex.position", the "x", "y", "z" 329 and "w" components of the vertex attribute variable are filled with the 330 "x", "y", "z", and "w" components, respectively, of the vertex position. 331 332 If a vertex attribute binding matches "vertex.normal", the "x", "y", and 333 "z" components of the vertex attribute variable are filled with the "x", 334 "y", and "z" components, respectively, of the vertex normal. The "w" 335 component is filled with 1. 336 337 If a vertex attribute binding matches "vertex.color" or 338 "vertex.color.primary", the "x", "y", "z", and "w" components of the 339 vertex attribute variable are filled with the "r", "g", "b", and "a" 340 components, respectively, of the vertex color. 341 342 If a vertex attribute binding matches "vertex.color.secondary", the "x", 343 "y", "z", and "w" components of the vertex attribute variable are filled 344 with the "r", "g", "b", and "a" components, respectively, of the vertex 345 secondary color. 346 347 If a vertex attribute binding matches "vertex.fogcoord", the "x" component 348 of the vertex attribute variable is filled with the vertex fog coordinate. 349 The "y", "z", and "w" coordinates are filled with 0, 0, and 1, 350 respectively. 351 352 If a vertex attribute binding matches "vertex.texcoord" or 353 "vertex.texcoord[n]", the "x", "y", "z", and "w" components of the vertex 354 attribute variable are filled with the "s", "t", "r", and "q" components, 355 respectively, of the vertex texture coordinate set <n>. If "[n]" is 356 omitted, texture coordinate set zero is used. 357 358 If a vertex attribute binding matches "vertex.instance", the "x" component 359 of the vertex attribute variable is filled with the integer instance 360 number for the primitive to which the vertex belongs. The "y", "z", and 361 "w" components are undefined. 362 363 If a vertex attribute binding matches "vertex.attrib[n]", the "x", "y", 364 "z" and "w" components of the generic vertex attribute variable are filled 365 with the "x", "y", "z", and "w" components, respectively, of generic 366 vertex attribute <n>. Note that "vertex.attrib[0]" and "vertex.position" 367 are equivalent. Generic vertex attribute bindings are typeless, and can 368 be interpreted as having floating-point, signed integer, or unsigned 369 integer values, depending on how they are used in the program text. If a 370 vertex attribute is read using a data type different from the one used to 371 specify the generic attribute, the values corresponding to the binding are 372 undefined. 373 374 As described in section 2.7, setting a generic vertex attribute may leave 375 a corresponding conventional vertex attribute undefined, and vice versa. 376 To prevent inadvertent use of attribute pairs with undefined attributes, a 377 vertex program will fail to load if it binds both a conventional vertex 378 attribute and a generic vertex attribute listed in the same row of Table 379 X.X. 380 381 Conventional Attribute Binding Generic Attribute Binding 382 ------------------------------ ------------------------- 383 vertex.position vertex.attrib[0] 384 vertex.normal vertex.attrib[2] 385 vertex.color vertex.attrib[3] 386 vertex.color.primary vertex.attrib[3] 387 vertex.color.secondary vertex.attrib[4] 388 vertex.fogcoord vertex.attrib[5] 389 vertex.texcoord vertex.attrib[8] 390 vertex.texcoord[0] vertex.attrib[8] 391 vertex.texcoord[1] vertex.attrib[9] 392 vertex.texcoord[2] vertex.attrib[10] 393 vertex.texcoord[3] vertex.attrib[11] 394 vertex.texcoord[4] vertex.attrib[12] 395 vertex.texcoord[5] vertex.attrib[13] 396 vertex.texcoord[6] vertex.attrib[14] 397 vertex.texcoord[7] vertex.attrib[15] 398 vertex.texcoord[n] vertex.attrib[8+n] 399 400 Table X.X: Invalid Vertex Attribute Binding Pairs. Vertex programs 401 may not bind both attributes listed in any row. The <n> in the last row 402 matches the number of any valid texture unit. 403 404 If a vertex attribute binding matches "vertex.texcoord[n..o]" or 405 "vertex.attrib[n..o]", a sequence of 1+<o>-<n> texture coordinate bindings 406 are created. For texture coordinates, it is as though the sequence 407 "vertex.texcoord[n], vertex.texcoord[n+1], ... vertex.texcoord[o]" were 408 specfied. These bindings are available only in explicit declarations of 409 array variables. A program will fail to load if <n> is greater than <o>. 410 411 When doing vertex array rendering using buffer objects, a vertex ID is 412 also available. If a vertex attribute binding matches "vertex.id", the 413 "x" component of this vertex attribute is filled with the integer index 414 <i> implicitly passed to ArrayElement() to specify the vertex. The vertex 415 ID is defined if and only if: 416 417 * the vertex comes from a vertex array command that specifies a complete 418 primitive (e.g., DrawArrays, DrawElements), 419 420 * all enabled vertex arrays have non-zero buffer object bindings, and 421 422 * the vertex does not come from a display list (even if the display list 423 was compiled using DrawArrays/DrawElements using buffer objects). 424 425 The "y", "z", and "w" components of the vertex attribute are always 426 undefined. 427 428 (add the following subsection to section 2.X.3.5, Program Results.) 429 430 Vertex programs produce vertices, and the set of result variables 431 available to such programs correspond to the attributes of a transformed 432 vertex. The set of allowable result variable bindings for vertex and 433 fragment programs is given in Table X.4. 434 435 Binding Components Description 436 ----------------------------- ---------- ---------------------------- 437 result.position (x,y,z,w) position in clip coordinates 438 result.color (r,g,b,a) front-facing primary color 439 result.color.primary (r,g,b,a) front-facing primary color 440 result.color.secondary (r,g,b,a) front-facing secondary color 441 result.color.front (r,g,b,a) front-facing primary color 442 result.color.front.primary (r,g,b,a) front-facing primary color 443 result.color.front.secondary (r,g,b,a) front-facing secondary color 444 result.color.back (r,g,b,a) back-facing primary color 445 result.color.back.primary (r,g,b,a) back-facing primary color 446 result.color.back.secondary (r,g,b,a) back-facing secondary color 447 result.fogcoord (f,*,*,*) fog coordinate 448 result.pointsize (s,*,*,*) point size 449 result.texcoord (s,t,r,q) texture coordinate, unit 0 450 result.texcoord[n] (s,t,r,q) texture coordinate, unit n 451 result.attrib[n] (x,y,z,w) generic interpolant n 452 result.clip[n] (d,*,*,*) clip plane distance 453 result.texcoord[n..o] (s,t,r,q) texture coordinates n thru o 454 result.attrib[n..o] (x,y,z,w) generic interpolants n thru o 455 result.clip[n..o] (d,*,*,*) clip distances n thru o 456 result.id (id,*,*,*) vertex id 457 458 Table X.4: Vertex Program Result Variable Bindings. Components labeled 459 "*" are unused. 460 461 If a result variable binding matches "result.position", updates to the 462 "x", "y", "z", and "w" components of the result variable modify the "x", 463 "y", "z", and "w" components, respectively, of the transformed vertex's 464 clip coordinates. Final window coordinates will be generated for the 465 vertex as described in section 2.14.4.4. 466 467 If a result variable binding match begins with "result.color", updates to 468 the "x", "y", "z", and "w" components of the result variable modify the 469 "r", "g", "b", and "a" components, respectively, of the corresponding 470 vertex color attribute in Table X.4. Color bindings that do not specify 471 "front" or "back" are consided to refer to front-facing colors. Color 472 bindings that do not specify "primary" or "secondary" are considered to 473 refer to primary colors. 474 475 If a result variable binding matches "result.fogcoord", updates to the "x" 476 component of the result variable set the transformed vertex's fog 477 coordinate. Updates to the "y", "z", and "w" components of the result 478 variable have no effect. 479 480 If a result variable binding matches "result.pointsize", updates to the 481 "x" component of the result variable set the transformed vertex's point 482 size. Updates to the "y", "z", and "w" components of the result variable 483 have no effect. 484 485 If a result variable binding matches "result.texcoord" or 486 "result.texcoord[n]", updates to the "x", "y", "z", and "w" components of 487 the result variable set the "s", "t", "r" and "q" components, 488 respectively, of the transformed vertex's texture coordinates for texture 489 unit <n>. If "[n]" is omitted, texture unit zero is selected. 490 491 If a result variable binding matches "result.attrib[n]", updates to the 492 "x", "y", "z", and "w" components of the result variable set the "x", "y", 493 "z", and "w" components of the generic interpolant <n>. Generic 494 interpolants may be used by subsequent geometry or fragment program 495 invocations, but are not available to fixed-function fragment processing. 496 497 If a result variable binding matches "result.clip[n]", updates to the "x" 498 component of the result variable set the clip distance for clip plane <n>. 499 500 If a result variable binding matches "result.texcoord[n..o]", 501 "result.attrib[n..o]", or "result.clip[n..o]", a sequence of 1+<o>-<n> 502 bindings is created. For texture coordinates, it is as though the 503 sequence "result.texcoord[n], result.texcoord[n+1], 504 ... result.texcoord[o]" were specfied. This binding is available only in 505 explicit declarations of array variables. A program will fail to load if 506 <n> is greater than <o>. 507 508 If a result variable binding matches "result.id", updates to the "x" 509 component of the result variable provide a integer vertex identifier 510 available to geometry programs using the "vertex[m].id" attribute binding. 511 If a geometry program using vertex IDs is active and a vertex program is 512 active, the vertex program must write "result.id" or the vertex ID number 513 is undefined. 514 515 (add the following subsection to section 2.X.6, Program Options.) 516 517 Section 2.X.6.Y, Vertex Program Options 518 519 + Position-Invariant Vertex Programs (ARB_position_invariant) 520 521 If a vertex program specifies the "ARB_position_invariant" option, the 522 program is used to generate all transformed vertex attributes except for 523 position. Instead, clip coordinates are computed as specified in section 524 2.10. Additionally, user clipping is performed as described in section 525 2.11. Use of position-invariant vertex programs should generally 526 guarantee that the transformed position of a vertex should be the same 527 whether vertex program mode is enabled or disabled, allowing for correct 528 mixed multi-pass rendering semantics. 529 530 When the position-invariant option is specified in a vertex program, 531 vertex programs can no longer declare (explicitly or implicitly) a result 532 variable bound to "result.position". A semantic restriction is added to 533 indicate that a vertex program will fail to load if the number of 534 instructions it contains exceeds the implementation-dependent limit minus 535 four. 536 537 (add the following subsection to section 2.X.7, Program Declarations.) 538 539 Section 2.X.7.Y, Vertex Program Declarations 540 541 No declarations are supported at present for vertex programs. 542 543Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 544 545 None. 546 547Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 548Operations and the Frame Buffer) 549 550 None. 551 552Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) 553 554 None. 555 556Additions to Chapter 6 of the OpenGL 2.0 Specification (State and 557State Requests) 558 559 Modify Section 6.1.14, Shader and Program Queries (p. 256) 560 561 (modify 2nd paragraph, p.259) The commands 562 563 ... 564 void GetVertexAttribIivEXT(uint index, enum pname, int *params); 565 void GetVertexAttribIuivEXT(uint index, enum pname, uint *params); 566 567 obtain the... <pname> must be one of VERTEX_ATTRIB_ARRAY_ENABLED, 568 ... VERTEX_ATTRIB_ARRAY_NORMALIZED, VERTEX_ATTRIB_ARRAY_INTEGER_EXT, or 569 CURRENT_VERTEX_ATTRIB. ... 570 571 (split 3rd paragraph, p.259) ... The size, stride, type, normalized flag, 572 and unconverted integer flag are set by the commands VertexAttribPointer 573 and VertexAttribIPointerEXT. The normalized flag is always set to FALSE by 574 by VertexAttribIPointerEXT. The unconverted integer flag is always set to 575 FALSE by VertexAttribPointer and TRUE by VertexAttribIPointerEXT. 576 577 The query CURRENT_VERTEX_ATTRIB returns the current value for the generic 578 attribute <index>. GetVertexAttribdv and GetVertexAttribfv read and 579 return the current attribute values as floating-point values; 580 GetVertexAttribiv reads them as floating-point values and converts them to 581 integer values; GetVertexAttribIivEXT reads and returns them a signed 582 integers; GetVertexAttribIuivEXT reads and returns them as unsigned 583 integers. The results of the query are undefined if the current attribute 584 values are read using one data type but specified using a different one. 585 The error INVALID_OPERATION is generated if <index> is zero. 586 587Additions to the AGL/GLX/WGL Specifications 588 589 None 590 591GLX Protocol 592 593 The following rendering commands are sent to the server as part of a 594 glXRender request: 595 596 VertexAttribI1ivEXT 597 2 12 rendering command length 598 2 278 rendering command opcode 599 4 CARD32 index 600 4 INT32 v[0] 601 602 VertexAttribI2ivEXT 603 2 16 rendering command length 604 2 279 rendering command opcode 605 4 CARD32 index 606 4 INT32 v[0] 607 4 INT32 v[1] 608 609 VertexAttribI3ivEXT 610 2 20 rendering command length 611 2 280 rendering command opcode 612 4 CARD32 index 613 4 INT32 v[0] 614 4 INT32 v[1] 615 4 INT32 v[2] 616 617 VertexAttribI4ivEXT 618 2 24 rendering command length 619 2 281 rendering command opcode 620 4 CARD32 index 621 4 INT32 v[0] 622 4 INT32 v[1] 623 4 INT32 v[2] 624 4 INT32 v[3] 625 626 VertexAttribI1uivEXT 627 2 12 rendering command length 628 2 282 rendering command opcode 629 4 CARD32 index 630 4 CARD32 v[0] 631 632 VertexAttribI2uivEXT 633 2 16 rendering command length 634 2 283 rendering command opcode 635 4 CARD32 index 636 4 CARD32 v[0] 637 4 CARD32 v[1] 638 639 VertexAttribI3uivEXT 640 2 20 rendering command length 641 2 284 rendering command opcode 642 4 CARD32 index 643 4 CARD32 v[0] 644 4 CARD32 v[1] 645 4 CARD32 v[2] 646 647 VertexAttribI4uivEXT 648 2 24 rendering command length 649 2 285 rendering command opcode 650 4 CARD32 index 651 4 CARD32 v[0] 652 4 CARD32 v[1] 653 4 CARD32 v[2] 654 4 CARD32 v[3] 655 656 VertexAttribI4bvEXT 657 2 12 rendering command length 658 2 286 rendering command opcode 659 4 CARD32 index 660 1 INT8 v[0] 661 1 INT8 v[1] 662 1 INT8 v[2] 663 1 INT8 v[3] 664 665 VertexAttribI4svEXT 666 2 16 rendering command length 667 2 287 rendering command opcode 668 4 CARD32 index 669 2 INT16 v[0] 670 2 INT16 v[1] 671 2 INT16 v[2] 672 2 INT16 v[3] 673 674 VertexAttribI4ubvEXT 675 2 12 rendering command length 676 2 288 rendering command opcode 677 4 CARD32 index 678 1 CARD8 v[0] 679 1 CARD8 v[1] 680 1 CARD8 v[2] 681 1 CARD8 v[3] 682 683 VertexAttribI4usvEXT 684 2 16 rendering command length 685 2 289 rendering command opcode 686 4 CARD32 index 687 2 CARD16 v[0] 688 2 CARD16 v[1] 689 2 CARD16 v[2] 690 2 CARD16 v[3] 691 692 The following non-rendering commands are added. 693 694 GetVertexAttribIivEXT 695 1 CARD8 opcode (X assigned) 696 1 184 GLX opcode 697 2 4 request length 698 4 GLX_CONTEXT_TAG context tag 699 4 CARD32 index 700 4 ENUM pname 701 => 702 1 1 reply 703 1 unused 704 2 CARD16 sequence number 705 4 m reply length, m=(n==1?0:n) 706 4 unused 707 4 CARD32 n 708 709 if (n=1) this follows: 710 711 4 INT32 params 712 12 unused 713 714 otherwise this follows: 715 716 16 unused 717 n*4 LISTofINT32 params 718 719 GetVertexAttribIuivEXT 720 1 CARD8 opcode (X assigned) 721 1 185 GLX opcode 722 2 4 request length 723 4 GLX_CONTEXT_TAG context tag 724 4 CARD32 index 725 4 ENUM pname 726 => 727 1 1 reply 728 1 unused 729 2 CARD16 sequence number 730 4 m reply length, m=(n==1?0:n) 731 4 unused 732 4 CARD32 n 733 734 if (n=1) this follows: 735 736 4 CARD32 params 737 12 unused 738 739 otherwise this follows: 740 741 16 unused 742 n*4 LISTofCARD32 params 743 744Errors 745 746 None. 747 748Dependencies on EXT_draw_instanced 749 750 If EXT_draw_instanced or a similar extension is not supported, 751 references to the "vertex.instance" attribute binding and a 752 primitive's instance number should be eliminated. 753 754New State 755 756 (add to table 6.7, p. 268) 757 Initial 758 Get Value Type Get Command Value Description Sec. Attribute 759 --------- ---- --------------- ------- -------------------- ---- --------- 760 VERTEX_ATTRIB_ARRAY 16+xB GetVertexAttrib FALSE vertex attrib array 2.8 vertex-array 761 INTEGER_EXT has unconverted ints 762 763New Implementation Dependent State 764 765 None. 766 767Issues 768 769 (1) Should a new set of immediate-mode functions be provided for "real 770 integer" attributes? If so, which ones should be provided? 771 772 RESOLVED: Yes, although an incomplete subset is provided. This 773 extension provides vector and non-vector functions that accept 1-, 2-, 774 3-, and 4-component "int" and "uint" values. Additionally, we provide 775 only 4-component vector versions of functions that accept "byte", 776 "ubyte", "short", and "ushort" values. Note that the ARB_vertex_program 777 extension provided a similar incomplete subset. 778 779 Since existing VertexAttrib functions include versions that take integer 780 values and convert them to float, it was necessary to create a different 781 way to specify integer values that are not converted. We created a new 782 set of functions using capital letter "I" to denote "real integer" 783 values. 784 785 This "I" approach is consistent with a similar choice made by 786 ARB_vertex_program for the existing integer attribute functions. There 787 are two methods of converting to floating point -- straight casts and 788 normalization to [0,1] or [-1,+1]. The normalization version of the 789 attribute functions use the capital letter "N" to denote normalization. 790 791 (2) For vertex arrays with "real integer" attributes, should we provide a 792 new function to specify the array or re-use the existing one? 793 794 RESOLVED: Provide a new function, VertexAttribIPointerEXT. This 795 function and VertexAttribPointer both set the same attribute state -- 796 state set by VertexAttribPointer for a given <index> will be overwritten 797 by VertexAttribIPointerEXT() and vice versa. There is one new piece of 798 state per array (VERTEX_ATTRIB_ARRAY_INTEGER_EXT) which is set to TRUE 799 for VertexAttribIPointerEXT() and FALSE by VertexAttribPointer. The use 800 of a new function with capital "I" in the name is consistent with the 801 choice made for immediate-mode integer attributes. 802 803 We considered reusing the existing VertexAttribPointer function by 804 hijacking the <normalized> parameter, which specifies whether the 805 provided arrays are converted to float by normalizing or a straight 806 cast. It would have been possible to add a third setting to indicate 807 unconverted integer values, but that has two problems: (a) it doesn't 808 agree with the <normalized> flag being specified as a "boolean" (which 809 only has two values), and (b) the enum value that would be used would be 810 outside the range [0,255] and "boolean" may be represented using 811 single-byte data types. 812 813 One other possibility would have been to create a new set of <type> 814 values to indicate integer values that are never converted to floating 815 point -- for example, GL_INTEGER_INT. 816 817 (3) Should we provide a whole new set of generic integer vertex 818 attributes? 819 820 RESOLVED: No. This extension makes the existing generic vertex 821 attributes "typeless", where they can store either integer or 822 floating-point data. This avoids the need to introduce new hardware 823 resources for integer vertex attributes or software overhead in juggling 824 integer and floating-point generic attributes. 825 826 Vertex programs and any queries that access these attributes are 827 responsible for ensuring that they are read using the same data type 828 that they were specified using, and will get undefined results on type 829 mismatches. Checking for such mismatches would be an excellent feature 830 for an instrumented OpenGL driver, or other debugging tool. 831 832 (4) Should we provide integer forms of existing conventional attributes? 833 834 RESOLVED: No. We could have provided "integer" versions of Color, 835 TexCoord, MultiTexCoord, and other functions, but it didn't seem useful. 836 The use of generic attributes for such values is perfectly acceptable, 837 and fixed-function vertex processing paths won't know what to do with 838 integer values for position, color, normal, and so on. 839 840 (5) With integers throughout the pipeline, should we provide automatic 841 identifiers that can be read to get a "vertex number"? If so, how should 842 this functionality be provided? 843 844 RESOLVED: The "vertex.id" binding provides an integer "vertex number" 845 for each vertex called the "vertex ID". 846 847 When using vertex arrays in vertex buffer objects (VBOs), the vertex ID 848 is defined to be the index of the vertex in the array -- the value 849 implicitly passed to ArrayElement() when DrawArrays() or DrawElements() 850 is called. In practice, vertex arrays in buffer objects will be stored 851 in memory that is directly accessible by the GPU. When functions such 852 as DrawArrays() or DrawElements() are called, a set of vertex indices 853 are passed to the GPU to identify the vertices to pull out of the buffer 854 objects. These same indices can be easily passed to the vertex program. 855 856 Vertex IDs can be used by applications in a variety of ways, for example 857 to compute or look up some property of the vertex based on its position 858 in the data set. 859 860 Note: The EXT_texture_buffer_object extension can be used to bind a 861 buffer object as a texture resource, which can the be used for lookups 862 in a vertex program. If the amount of memory required for each vertex 863 is very large or is variable, the existing vertex array model might not 864 work very well. However, with TexBOs (texture buffer objects), the 865 vertex program can be used to compute an offset into the buffer object 866 holding the vertex data and fetch the data needed using texture lookups. 867 This approach blurs the line between texture and vertex pulling, and 868 treats the "texture" in question as a simple array. 869 870 (6) Should vertex IDs be provided for vertices in immediate mode? 871 Vertices in display lists? Vertex arrays compiled into a display list? 872 873 RESOLVED: No to all. 874 875 A different definition would be needed for immediate mode vertices, 876 since the vertex attributes are not specified with an index. It would 877 have been possible to implement some sort of counter where the vertex ID 878 indicates that the vertex is the <N>th one since the previous Begin 879 command. 880 881 Vertex arrays compiled into a display list are an even more complicated 882 problem, since either the "array element" definition or the alternate 883 "immediate mode" definition could be used. If the "array element" 884 definition were used, it would additionally be necessary to compile the 885 array element values into the display list. This would introduce 886 additional overhead into the display list, and the storage space for the 887 array element numbers would be wasted if no program using vertex ID were 888 ever used. 889 890 While such functionality may be useful, it is left to a subsequent 891 extension. 892 893 If such functionality is required, immediate mode VertexAttribI1i() 894 calls can be used to specify the desired "vertex ID" values as integer 895 generic attributes. In this case, the vertex program needs to refer to 896 the specified generic attribute, and not "vertex.id". 897 898 (7) Should vertex identifiers be provided for non-VBO vertex arrays? For 899 vertex arrays that are a mix of VBO and non-VBO arrays? 900 901 RESOLVED: Non-VBO arrays are generally not stored in memory directly 902 accessible by the GPU; the data are instead copied from the 903 application's memory as they are passed to the GPU. Additionally, the 904 index ordering may not be preserved by the copy. For example, if a 905 DrawElements() call passes vertices numbered 30, 20, 10, and 0 in order, 906 the GPU might see vertex 30's data first, immediately followed by vertex 907 20's data, and so on. 908 909 It would be possible for the driver to provide per-vertex ID values to 910 the GPU during the copy, but defining such functionality is left to a 911 subsequent extension. 912 913 For vertices with a mix of VBO arrays and non-VBO arrays, the non-VBO 914 arrays still have the same copy issues, so the automatic vertex ID is 915 not provided. 916 917 If such functionality is required, a generic vertex attribute array can 918 be set up using VertexAttribIPointerEXT(), holding integer values 0 919 through <maxSize>-1, where <maxSize> is the maximum vertex index used. 920 For each vertex, the appropriate "vertex ID" value will be taken from 921 this array. In this case, the vertex program needs to refer to the 922 specified generic attribute, and not "vertex.id". 923 924 (8) Should vertex IDs be available to geometry programs, and if so, how? 925 926 RESOLVED: Yes, vertex IDs can be passed to geometry programs using the 927 "result.id" binding in a vertex program. Note there is no requirement 928 that the "result.id" written for a vertex must match the "vertex.id" 929 originally provided. 930 931 Vertex IDs are not automatically provided to geometry programs; if a 932 vertex program doesn't write to "result.id" or if fixed-function vertex 933 processing is used, the vertex ID visible to the geometry program is 934 undefined. 935 936 (9) For instanced arrays (EXT_draw_instanced), should a vertex program 937 be able to read the instance number? If so, how? 938 939 RESOLVED: Yes, instance IDs are available to vertex programs using the 940 "vertex.instance" attribute. The instance ID is available in the "x" 941 component and should be read as an integer. 942 943 (10) Should instance IDs be available to geometry and fragment programs, 944 and if so, how? 945 946 UNRESOLVED: No. If a geometry or fragment program needs the instance 947 ID, the value read in the vertex program can be passed down using a 948 generic integer vertex attribute. 949 950 It would be possible to provide a named output binding (e.g., 951 "result.instance") that could be used to pass the instance ID to the 952 next pipeline stage. Using such a binding would have no functional 953 differences from using a generic attribute, except for a name. 954 955 In any event, instance IDs are not automatically available to geometry 956 or fragment programs; they must be passed from earlier pipeline stages. 957 958 (11) This is an NV extension (NV_vertex_program4). Why do all the new 959 functions and tokens have an "EXT" extension? 960 961 RESOLVED: These functions and tokens are shared between this extension 962 and the comparable high-level GLSL programmability extension 963 (EXT_gpu_shader4). Rather than provide a duplicate set of functions, we 964 simply use the EXT version here. 965 966Revision History 967 968 Rev. Date Author Changes 969 ---- -------- -------- -------------------------------------------- 970 7 09/15/08 jajones Added GLX protocol. 971 972 6 03/11/09 pbrown Fix section numbers for option/declaration 973 sections. 974 975 1-5 pbrown Internal spec development. 976