1Name 2 3 ARB_vertex_shader 4 5Name Strings 6 7 GL_ARB_vertex_shader 8 9Contributors 10 11 Kurt Akeley 12 Allen Akin 13 Dave Baldwin 14 Pat Brown 15 Matt Craighead 16 Cass Everitt 17 Evan Hart 18 Phil Huxley 19 Dale Kirkland 20 John Kessenich 21 Steve Koren 22 Jon Leech 23 Bill Licea-Kane 24 Benjamin Lipchak 25 Barthold Lichtenbelt 26 Kent Lin 27 Jeremy Morris 28 Teri Morrison 29 Glenn Ortner 30 Randi Rost 31 Jeremy Sandmel 32 Folker Schamel 33 Eskil Steenberg 34 35 The ARB_vertex_program working group members. Several concepts and 36 chunks of text are copied from the ARB_vertex_program specification. 37 38Contact 39 40 Barthold Lichtenbelt, 3Dlabs, Inc. (barthold 'at' 3dlabs.com) 41 Randi Rost, 3Dlabs, Inc. (rost 'at' 3dlabs.com) 42 43Notice 44 45 Copyright (c) 2003-2013 The Khronos Group Inc. Copyright terms at 46 http://www.khronos.org/registry/speccopyright.html 47 48IP Status 49 50 As described in the Contributor License, which can be found at 51 http://developer.3dlabs.com/openGL2/specs/3dlabs_contributor.pdf . 52 53Status 54 55 Complete. Approved by the ARB on June 11, 2003. 56 Updated revision 0.81 approved by the ARB on June 17, 2004. 57 58Version 59 60 Last Modified Date: December 14, 2009 61 Author Revision: 0.83 62 63Number 64 65 ARB Extension #31 66 67Dependencies 68 69 OpenGL 1.0 is required. 70 71 This extension is written against version 1.10 of the OpenGL Shading 72 Language Specification. 73 74 The extension is written against the OpenGL 1.4 Specification. 75 76 The ARB_shader_objects extension is required. 77 78Overview 79 80 This extension adds programmable vertex level processing to OpenGL. The 81 application can write vertex shaders in a high level language as defined 82 in the OpenGL Shading Language specification. The language itself is not 83 discussed here. A vertex shader replaces the transformation, texture 84 coordinate generation and lighting parts of OpenGL, and it also adds 85 texture access at the vertex level. Furthermore, management of vertex 86 shader objects and loading generic attributes are discussed. A vertex 87 shader object, attached to a program object, can be compiled and linked 88 to produce an executable that runs on the vertex processor in OpenGL. 89 This extension also defines how such an executable interacts with the 90 fixed functionality vertex processing of OpenGL 1.4. 91 92Issues 93 94 1) What does need to be said about invariance (Appendix A of the OpenGL 95 1.4 spec)? 96 97 DISCUSSION: Numerous rules and proposals have been discussed. In the 98 end, simplicity is an important goal. It is always possible to later add 99 more invariance rules, if it turns out to be desirable. 100 101 RESOLUTION: The same shader will produce the same result when run 102 multiple times with the same input. The wording 'the same shader' means 103 a program object that is populated with the same source strings, which 104 are compiled and then linked, possibly multiple times. This program 105 object is executed using the same GL state vector. 106 107 Position invariance between a vertex shader and the fixed functionality 108 pipeline is important for certain applications. Therefore there must be 109 a way to guarantee that a vertex shader produces the exact same position 110 for a vertex as the fixed function pipeline does. This is achieved by 111 using the built-in function ftransform in a vertex shader, and assign it 112 to the output variable gl_Position. The shader does this instead of 113 computing the product of the ModelViewProjection matrix with the vertex 114 position. See section 2.15.6 for more. 115 116 2) Should we take the API commands to load generic vertex attributes 117 from ARB_vertex_program? 118 119 DISCUSSION: At first glance these commands, for example 120 VertexAttrib3fvARB, look like exactly what this extension needs. 121 However, if we re-use these commands here, how does the GL 122 implementation decide where attributes go when using shaders written 123 using ARB_vertex_program or this extension? What happens to the 124 attribute value when switching between an ARB_vertex_program and an 125 ARB_vertex_shader shader? How does this resolve with respect to 126 undefined aliasing defined in ARB_vertex_program and the no aliasing 127 defined in this extension? 128 129 RESOLUTION: Resolved, we will re-use these entry points. It is very 130 convenient for an ISV to be able to re-use the entry points to load 131 data, and only have to switch shaders when it wants to go from an 132 ARB_vertex_program shader to an ARB_vertex_shader shader. This extension 133 allows for no aliasing among generic attributes and standard vertex 134 attributes, whereas ARB_vertex_program has the concept of undefined 135 aliasing. In order to resolve this the interactions section extends 136 ARB_vertex_program to expose this no aliasing approach. Note that we do 137 not lift the restriction in the grammar on invalid attribute binding 138 pairs, see Table X.2.1 in the ARB_vertex_program specification. 139 140 3) Should we take the API commands to load generic vertex arrays from 141 ARB_vertex_program? 142 143 DISCUSSION: See issue 2. 144 145 RESOLUTION: Resolved, yes we will re-use these entry points. See also 146 the previous issue resolution. 147 148 4) Should we take the API commands to query the values of generic 149 attributes from ARB_vertex_program? 150 151 DISCUSSION: This goes hand in hand with issue 2. 152 153 RESOLUTION: Yes we will. 154 155 5) Do we need to specify how Evaluators and AUTO_NORMAL generation 156 interacts? 157 158 DISCUSSION: ARB_vertex_program specifies that for evaluated normals the 159 normal is no longer automatically normalized when a vertex shader is 160 active. This is discussed in detail in issue 92 in the 161 ARB_vertex_program specification. 162 163 RESOLUTION: We will follow ARB_vertex_program. 164 165 6) What should the initial value of the generic vertex attributes be? 166 167 DISCUSSION: ARB_vertex_program leaves their initial values undefined. It 168 seems to make sense to do so, because of the undefined aliasing. In this 169 extension there is no aliasing among conventional and generic 170 attributes. Hence it could be desirable to define the initial values to 171 be (0, 0, 0, 1). 172 173 RESOLUTION: The initial values are (0, 0, 0, 1). 174 175 7) Do generic attributes push and pop? 176 177 DISCUSSION: There has been some concern that adding more state than 178 strictly necessary is a performance issue for applications that push and 179 pop a lot. Conventional attributes are pushed and popped, as well as 180 generic attributes, by ARB_vertex_program. 181 182 RESOLUTION: YES, they are part of GL state, and such should push and pop 183 under the 'current' bit. Note that an OpenGL implementation could track 184 if a generic attribute has been set, and as long as it has not, never 185 push/pop that attribute. 186 187 8) How does user clipping work? 188 189 DISCUSSION: The OpenGL Shading Language provides a gl_ClipVertex 190 built-in variable in the vertex shading language. This variable provides 191 a place for vertex shaders to specify a coordinate to be used by the 192 user clipping plane stage. The user must ensure that the clip vertex and 193 user clipping planes are defined in the same coordinate space. Note that 194 this is different than ARB_vertex_program, where user clipping is 195 ignored unless the position invariant option is enabled (where all 196 vertex transformation options are performed by the fixed functionality 197 pipeline). Here are some tips on how to use user clipping in a vertex 198 shader: 199 200 1) When using a traditional transform in a vertex shader, compute the 201 eye coordinates and store the result in gl_ClipVertex. 202 203 2) If clip planes are enabled with a vertex shader, gl_ClipVertex must 204 be written to, otherwise results will be undefined. 205 206 3) When doing object-space clipping, keep in mind that the clip planes 207 are automatically transformed to eye coordinates (see section 2.11 208 of the GL 1.4 spec). Use an identity modelView matrix to avoid this 209 transformation. 210 211 RESOLUTION: Resolved. See also section 2.11. 212 213 9) Do we need a vertex shader point size enable? 214 215 DISCUSSION: ARB_vertex_program provides an enable, 216 VERTEX_PROGRAM_POINT_SIZE_ARB. This extension uses the same enable. If 217 VERTEX_PROGRAM_POINT_SIZE mode is enabled, and a vertex shader is 218 active, then the point size is taken from the vertex shader's point size 219 result, otherwise it is taken from the PointSize command. The OpenGL 220 Shading Language provides a built-in gl_PointSize that a vertex shader 221 can write to, to specify the point size in pixels. If gl_PointSize is 222 not written while the point size mode is enabled then the point size 223 used in the rasterization stage is undefined. 224 225 This point size enable is convenient for the majority of applications 226 who do not change the point size. Not setting the enable means the point 227 size is picked up automatically, instead of having to write a shader 228 which always outputs the same point size. 229 230 RESOLUTION: Yes. 231 232 10) How to handle the color sum stage? 233 234 DISCUSSION: It is the vertex shader's responsibility to write a primary 235 and secondary color into the appropriate built in varying variables, if 236 subsequent stages in the pipeline use these. Otherwise results are 237 undefined. Section 3.9 of the OpenGL 1.4 spec states that the color sum 238 stage is always applied when lighting is enabled, ignoring the value of 239 the COLOR_SUM enable bit. Should we take out this automatic enable when 240 lighting is enabled? 241 242 RESOLUTION: This automatic enable will only have effect when no vertex 243 shader is active. This behavior is the same in ARB_vertex_program. 244 245 11) Does generic attribute zero also provoke (signal the end of a 246 vertex), or just the glVertex command? 247 248 DISCUSSION: To be more compatible with ARB_vertex_program this would be 249 desirable. It may be that no attribute directly expresses a vertex 250 position. The shader may derive the position based on multiple 251 attributes, where there is no clear attribute that can be marked as "the 252 vertex". On the other hand, it is mandatory in a vertex shader to write 253 to gl_Vertex. Thus it makes some sense that the glVertex API has to be 254 used to signal the end of a vertex. 255 256 RESOLUTION: Resolved. For compatibility reasons, attribute zero will 257 also provoke. 258 259 12) How to handle texture access from a vertex shader? 260 261 DISCUSSION: The OpenGL Shading Language allows for texture access from a 262 vertex shader. What is the OpenGL support necessary to make that 263 actually happen? Two approaches seem feasible. 1) Virtualize the number 264 of texture image units available in OpenGL. Deprecate the concept of 265 binding a texture object to a texture image unit. Instead, bind a 266 texture object directly to a sampler. 2) A not so drastic approach that 267 makes a maximum number of texture image units available to a vertex 268 shader as well as to the fragment processing part of the OpenGL 269 pipeline. The sum of the available texture image units cannot exceed the 270 constant MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB. 271 272 RESOLUTION: Option 2) is what is used in this specification. Option 1) 273 is a more invasive approach, and left for a future extension. 274 275 This approach allows for two types of hardware. One where the hardware 276 resources to perform the functions associated with a texture image unit 277 are not shared between a vertex and fragment shader, and one type of 278 hardware where they are shared. The maximum number of texture image 279 units available to a vertex shader is 280 MAX_VERTEX_TEXTURE_IMAGE_UNITS_ARB. The maximum number of texture image 281 units available to the fragment stage of OpenGL is 282 MAX_TEXTURE_IMAGE_UNITS_ARB. Now consider, for example, an 283 implementation that supports up to 16 texture stages and shares its 284 texture mapping resources between the vertex shader and fragment shader. 285 For this implementation MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB, 286 MAX_VERTEX_TEXTURE_IMAGE_UNITS_ARB and MAX_TEXTURE_IMAGE_UNITS_ARB would 287 all be set to 16. A hardware implementation which does not share its 288 texture mapping resources, and who can support 2 texture stages for a 289 vertex shader and 16 texture stages for the fragment processing, would 290 set MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB to 18, 291 MAX_VERTEX_TEXTURE_IMAGE_UNITS_ARB to 2 and MAX_TEXTURE_IMAGE_UNITS_ARB 292 to 16. A vertex shader cannot use more than 293 MAX_VERTEX_TEXTURE_IMAGE_UNITS_ARB texture image units. The fragment 294 processing part of OpenGL cannot use more than 295 MAX_TEXTURE_IMAGE_UNITS_ARB texture image units. 296 297 Both the vertex shader and fragment processing combined cannot use more 298 than MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB texture image units. If a 299 vertex shader and fragment processing part of OpenGL both use the same 300 texture image unit, then that counts as separate units against the above 301 mentioned limits. 302 303 Automatic LOD calculation does not happen during vertex processing in a 304 vertex shader, hence there is no automatic selection of an image array 305 level. Minification or magnification of a texture map is controlled by a 306 LOD value passed as an argument in some of the built-in texture lookup 307 functions. These built-in texture lookup functions, defined in the 308 OpenGL Shading Language, come in two flavors. One set of lookup 309 functions that take a LOD value as an input, and one set that does not 310 take a LOD value. 311 312 If the former set of functions is used, then the LOD value passed in is 313 used directly as the LOD value lambda' in section 3.8.8 equation 3.16 on 314 page 140 of the OpenGL 1.4 spec. This in turn defines lambda, which then 315 is used as usual to determine magnification or minification and, when 316 mipmapping, which mipmap array(s) to select. 317 318 If the latter set of functions is used, then lambda, the result of 319 equation 3.16, is set to zero. This effectively means a texture object 320 is considered magnified, and only paragraph 3.8.9 applies. 321 322 13) Do we split a texture unit into a texture image unit and a texture 323 coordinate set? 324 325 DISCUSSION: This is what ARB_fragment_program does, and 326 ARB_fragment_shader as well. The OpenGL Shading Language allows for 327 texture lookups in a vertex shader. This means that a vertex shader 328 should have access to a texture image unit (texture maps and associated 329 parameters). A vertex shader also has access to state stored with a 330 texture coordinate set, which encompasses vertex texture coordinate 331 attributes, as well as the texture matrix stack and texture generation 332 state. The number of supported texture image units and texture 333 coordinate sets is not necessarily the same on a particular 334 implementation. 335 336 RESOLUTION: Yes 337 338 14) Do we need to specify different texture coordinate sets for a vertex 339 shader and fragment processing? 340 341 DISCUSSION: So far there are MAX_TEXTURE_COORDS_ARB texture coordinate 342 sets. This constant is defined in ARB_fragment_program, and re-used in 343 ARB_fragment_shader as well as the OpenGL Shading Language (see built-in 344 constants, section 7.4). Only a vertex shader has access to vertex 345 texture coordinate attributes. But both an ARB vertex and fragment 346 shader has access to the other state associated with a texture 347 coordinate set. That state is texture generation and the texture matrix 348 stack. 349 350 RESOLUTION: NO. 351 352 15) What is the minimum value for MAX_VERTEX_TEXTURE_IMAGE_UNITS_ARB? 353 354 DISCUSSION: Should this be zero, or more? 355 356 RESOLUTION: Resolved, zero. 357 358 16) Do we also need a built in function to guarantee position invariance 359 with respect to user clip planes? 360 361 DISCUSSION: Issue 1 discusses invariance with respect to the vertex 362 position. A vertex shader however can also output coordinates used for 363 subsequent user clipping, by writing to gl_ClipVertex. In other words, 364 do we need something like gl_ClipVertex = ftransformClip()? 365 366 RESOLUTION: NO, position invariance with respect to user clipping seems 367 like a rarely needed feature. The OpenGL Shading Language does not have 368 a ftransformClip() built-in function. If this functionality is ever 369 needed, it is easy to add later. 370 371 17) What happens to the point size when a vertex shader is active? 372 373 DISCUSSION: The point size is taken from the built-in gl_PointSize when 374 VERTEX_PROGRAM_POINT_SIZE_ARB is enabled, but what to do with distance 375 attenuation and point fade (see Section 3.3)? 376 377 RESOLUTION: Resolved. The vertex shader should compute distance 378 attenuation. Fixed function computes it as a function of, among others, 379 eyeZ. It is not required for a vertex shader to compute eyeZ, and the 380 fixed function eyeZ might have nothing to do with the vertex position 381 computed in the vertex shader. Point fade, however, should still be 382 fixed function. The vertex shader could compute a point fade, but it'll 383 produce incorrect results if the application issues the following 384 commands: 385 386 glPolygonMode(GL_FRONT, GL_FILL); 387 glPolygonMode(GL_BACK, GL_POINT); 388 389 In this case you would want to fade if a vertex belonged to a 390 back-facing triangle, but not if it could belong to a front-facing one. 391 392 18) What is the deal with range and precision of colors once output from 393 the vertex shader? 394 395 DISCUSSION: Section 2.13.6 of the GL 1.4 spec specifies that all 396 components of both the primary and secondary colors be clamped to the 397 range [0,1]. Section 2.13.9 furthermore specifies that each color 398 component be converted to a fixed-point value with enough bits to 399 satisfy the frame buffer depth. Section 2.1.1 says that the maximum 400 representable magnitude of a floating-point number for colors must be at 401 least 2^10. 402 403 It is desirable to bypass clamping of colors when an ARB_fragment_shader 404 shader is also active. It has utility to be able to exceed the range 405 [0,1] and deal with extended range colors in a fragment shader. 406 407 Varying variables, including the built-in color variables, are declared 408 as floating point vectors in the OpenGL Shading Language, and 409 interpolated as floating-point values. It does not seem to make much 410 sense to specify a conversion to fixed-point after the ARB vertex shader 411 writes colors, then interpolate those fixed-point colors, then convert 412 the interpolated values back to floating point for input in the ARB 413 fragment shader. 414 415 ARB_fragment_program leaves the primary and secondary colors as the only 416 varying variables that have less range (2^10) than any other varying. It 417 promoted texture coordinates to full citizens with a maximum 418 representable magnitude of at least 2^32. 419 420 There are three cases to consider: 421 422 1) An ARB_vertex_shader shader writing colors that are consumed by an 423 ARB_fragment_shader shader. 424 2) An ARB_vertex_shader shader writing colors that are consumed by an 425 ARB_fragment_program shader. 426 3) An ARB_vertex_shader shader writing colors that are consumed by 427 fixed-function fragment processing. 428 429 An argument can be made that a shader writer can bypass the clamping and 430 conversion to fixed-point by defining its own varying variables, and use 431 that to interpolate colors. It can then use the built-in gl_FrontFacing 432 in a fragment shader for front or back face color selection. This is 433 certainly true, but it bypasses the (fixed-function) front and back face 434 color selection, which happens in a stage after the vertex shader. This 435 front/back face selection stage can only be used when writing to the 436 vertex shader built-in gl_FrontColor, gl_BackColor, 437 gl_FrontSecondaryColor and gl_BackSecondaryColor. 438 439 RESOLUTION: We anticipate future extensions will generalize the final 440 color-processing clamp with an enable/disable clamp. Therefore, this 441 specification will leave the final color clamp and conversion to 442 fixed-point in place for gl_FrontColor, gl_FrontSecondaryColor, 443 gl_BackColor, and gl_BackSecondaryColor. 444 445 19) How do I get a list of all attributes and their types used by a 446 shader and when do I bind generic vertex attributes? 447 448 DISCUSSION: GetActiveAttribARB will return the name of an attribute and 449 its type declared and actually used in the shader, as determined by the 450 compiler and linker. Looping over all attributes and calling 451 GetActiveAttribARB will generate the list of attribute names and types 452 used in a shader. This list is called the active attributes list. 453 GetActiveAttribARB can be called after a link attempt. It is not 454 necessary for the link to have succeeded. After all, one of the reasons 455 the link failed could be that there are too many active attributes. It 456 is not required to call BindAttribLocationARB before issuing 457 GetActiveAttribARB. BindAttributeLocationARB can be called any time. In 458 order to have a BindAttribLocationARB command take effect, the program 459 object will have to be (re)linked. Thus the order of commands to get the 460 list of active attributes could be: Link the program object, call 461 GetActiveAttribARB as many times as needed, call BindAttribLocationARB 462 one or more times, then call link again. 463 464 It is allowed to issue BindAttribLocationARB before any vertex shader 465 objects are attached to a program object. Hence it is allowed to bind 466 any name to a location, including a name that is never used as an 467 attribute in any vertex shader object. 468 469 RESOLUTION: Resolved, call GetActiveAttribARB. 470 471 20) Who assigns vertex attribute variable names to indices used in the 472 VertexAttrib*ARB commands? 473 474 DISCUSSION: Both the GL and the application can do this. The linker will 475 assign indices to vertex attributes declared in a vertex shader. These 476 values can be queried by the application and used to load values for the 477 generic vertex attributes. Alternatively the application can override 478 this assignment, and bind attribute variable names to any generic vertex 479 attribute index of their choice, within the range 0 to 480 MAX_VERTEX_ATTRIBS_ARB. An application would have to do this when 481 building a display list, for example. In this case it is possible to 482 generate the display list before the program object has even been 483 created. 484 485 Only indices for generic attributes can be queried, or set. Conventional 486 attributes are handled by the GL, and guaranteed to not alias with 487 generic attributes. 488 489 RESOLUTION: Both the GL and the application. 490 491 21) How should this extension handle changes to material state within 492 Begin/End? 493 494 DISCUSSION: Supporting per-vertex material properties places additional 495 pressure on the number of per-vertex bindings an OpenGL implementation 496 can support, which already is a scarce resource. 497 498 RESOLUTION: Materials are declared as uniforms in the OpenGL Shading 499 Language. Any changes to the material properties inside a Begin/End 500 through Material commands, or indirectly through ColorMaterial and Color 501 commands, are not guaranteed to actually update material state until the 502 next End command. At that point, all material property state is 503 guaranteed to be updated. 504 505 In practice, material properties are usually not changed within 506 Begin/End. Applications needing to change material properties inside a 507 Begin/End in a vertex shader can work around this limitation by storing 508 the color in a conventional or generic vertex attribute and modifying 509 the vertex shader accordingly. 510 511 22) What space are gl_Position and gl_ClipVertex in? 512 513 DISCUSSION: The GL treats the values in the built-in output variable 514 gl_Position as being in clip space, for the purpose of clipping against 515 the clip volume. See Section 2.11 of the OpenGL 1.4 specification. The 516 GL treats the values in the (optional) built-in output variable 517 gl_ClipVertex as being in eye-space for clipping against a 518 client-defined clip plane. 519 520 RESOLUTION: clip-space and eye-space respectively. 521 522 23) What texture operations are not affected by a vertex shader 523 performing a texture lookup? 524 525 RESOLUTION: Whether or not a vertex shader is active, the following 526 operations still behave as specified: 527 528 * texture image specification (pp. 119-128) 529 * alternate texture image specification (pp. 128-132) 530 * compressed texture image specification (pp. 132-135) 531 * texture parameters behave as specified even when a texture is 532 accessed from within a vertex shader (pp. 135-147) 533 * texture state and proxy state (pp. 148-149) 534 * texture object specification (pp. 149-152) 535 * texture comparison modes (p. 157) 536 537New Procedures and Functions 538 539 void VertexAttrib1fARB(uint index, float v0) 540 void VertexAttrib1sARB(uint index, short v0) 541 void VertexAttrib1dARB(uint index, double v0) 542 void VertexAttrib2fARB(uint index, float v0, float v1) 543 void VertexAttrib2sARB(uint index, short v0, short v1) 544 void VertexAttrib2dARB(uint index, double v0, double v1) 545 void VertexAttrib3fARB(uint index, float v0, float v1, float v2) 546 void VertexAttrib3sARB(uint index, short v0, short v1, short v2) 547 void VertexAttrib3dARB(uint index, double v0, double v1, double v2) 548 void VertexAttrib4fARB(uint index, float v0, float v1, float v2, float v3) 549 void VertexAttrib4sARB(uint index, short v0, short v1, short v2, short v3) 550 void VertexAttrib4dARB(uint index, double v0, double v1, double v2, double v3) 551 void VertexAttrib4NubARB(uint index, ubyte x, ubyte y, ubyte z, ubyte w) 552 553 void VertexAttrib1fvARB(uint index, const float *v) 554 void VertexAttrib1svARB(uint index, const short *v) 555 void VertexAttrib1dvARB(uint index, const double *v) 556 void VertexAttrib2fvARB(uint index, const float *v) 557 void VertexAttrib2svARB(uint index, const short *v) 558 void VertexAttrib2dvARB(uint index, const double *v) 559 void VertexAttrib3fvARB(uint index, const float *v) 560 void VertexAttrib3svARB(uint index, const short *v) 561 void VertexAttrib3dvARB(uint index, const double *v) 562 void VertexAttrib4fvARB(uint index, const float *v) 563 void VertexAttrib4svARB(uint index, const short *v) 564 void VertexAttrib4dvARB(uint index, const double *v) 565 void VertexAttrib4ivARB(uint index, const int *v) 566 void VertexAttrib4bvARB(uint index, const byte *v) 567 568 void VertexAttrib4ubvARB(uint index, const ubyte *v) 569 void VertexAttrib4usvARB(uint index, const ushort *v) 570 void VertexAttrib4uivARB(uint index, const uint *v) 571 572 void VertexAttrib4NbvARB(uint index, const byte *v) 573 void VertexAttrib4NsvARB(uint index, const short *v) 574 void VertexAttrib4NivARB(uint index, const int *v) 575 void VertexAttrib4NubvARB(uint index, const ubyte *v) 576 void VertexAttrib4NusvARB(uint index, const ushort *v) 577 void VertexAttrib4NuivARB(uint index, const uint *v) 578 579 void VertexAttribPointerARB(uint index, int size, enum type, boolean normalized, 580 sizei stride, const void *pointer) 581 582 void EnableVertexAttribArrayARB(uint index) 583 void DisableVertexAttribArrayARB(uint index) 584 585 void BindAttribLocationARB(handleARB programObj, uint index, const charARB *name) 586 587 void GetActiveAttribARB(handleARB programObj, uint index, sizei maxLength, 588 sizei *length, int *size, enum *type, charARB *name) 589 590 GLint GetAttribLocationARB(handleARB programObj, const charARB *name) 591 592 void GetVertexAttribdvARB(uint index, enum pname, double *params) 593 void GetVertexAttribfvARB(uint index, enum pname, float *params) 594 void GetVertexAttribivARB(uint index, enum pname, int *params) 595 void GetVertexAttribPointervARB(uint index, enum pname, void **pointer) 596 597New Tokens 598 599 Accepted by the <shaderType> argument of CreateShaderObjectARB and 600 returned by the <params> parameter of GetObjectParameter{if}vARB: 601 602 VERTEX_SHADER_ARB 0x8B31 603 604 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 605 GetFloatv, and GetDoublev: 606 607 MAX_VERTEX_UNIFORM_COMPONENTS_ARB 0x8B4A 608 MAX_VARYING_FLOATS_ARB 0x8B4B 609 MAX_VERTEX_ATTRIBS_ARB 0x8869 610 MAX_TEXTURE_IMAGE_UNITS_ARB 0x8872 611 MAX_VERTEX_TEXTURE_IMAGE_UNITS_ARB 0x8B4C 612 MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB 0x8B4D 613 MAX_TEXTURE_COORDS_ARB 0x8871 614 615 Accepted by the <cap> parameter of Disable, Enable, and IsEnabled, and 616 by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and 617 GetDoublev: 618 619 VERTEX_PROGRAM_POINT_SIZE_ARB 0x8642 620 VERTEX_PROGRAM_TWO_SIDE_ARB 0x8643 621 622 Accepted by the <pname> parameter GetObjectParameter{if}vARB: 623 624 OBJECT_ACTIVE_ATTRIBUTES_ARB 0x8B89 625 OBJECT_ACTIVE_ATTRIBUTE_MAX_LENGTH_ARB 0x8B8A 626 627 Accepted by the <pname> parameter of GetVertexAttrib{dfi}vARB: 628 629 VERTEX_ATTRIB_ARRAY_ENABLED_ARB 0x8622 630 VERTEX_ATTRIB_ARRAY_SIZE_ARB 0x8623 631 VERTEX_ATTRIB_ARRAY_STRIDE_ARB 0x8624 632 VERTEX_ATTRIB_ARRAY_TYPE_ARB 0x8625 633 VERTEX_ATTRIB_ARRAY_NORMALIZED_ARB 0x886A 634 CURRENT_VERTEX_ATTRIB_ARB 0x8626 635 636 Accepted by the <pname> parameter of GetVertexAttribPointervARB: 637 638 VERTEX_ATTRIB_ARRAY_POINTER_ARB 0x8645 639 640 Returned by the <type> parameter of GetActiveAttribARB: 641 642 FLOAT 0x1406 643 FLOAT_VEC2_ARB 0x8B50 644 FLOAT_VEC3_ARB 0x8B51 645 FLOAT_VEC4_ARB 0x8B52 646 FLOAT_MAT2_ARB 0x8B5A 647 FLOAT_MAT3_ARB 0x8B5B 648 FLOAT_MAT4_ARB 0x8B5C 649 650Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation) 651 652 Modify Section 2.1.1, Floating-Point Computation (p. 6) 653 654 (modify first paragraph, p. 6) ... are accurate to about 1 part in 10^5. 655 The maximum representable magnitude of a floating-point number used to 656 represent positional, normal or texture coordinates must be at least 657 2^32. The maximum representable magnitude for colors must be at least 658 2^10. The maximum representable magnitude for all other floating-point 659 values must be at least 2^32. 660 661 Modify Section 2.6, Begin/End Paradigm (p. 12) 662 663 (modify last paragraph, p. 12) Each vertex is specified with two, three, 664 or four coordinates. In addition, a current normal, multiple current 665 texture coordinate sets, multiple current generic vertex attributes, 666 current color ... Generic vertex attributes can be accessed from within 667 vertex shaders (section 2.15) and used to compute values for consumption 668 by later processing stages. 669 670 Modify Section 2.6.3, GL Commands within Begin/End (p. 19) 671 672 (modify first paragraph of section, p. 19) The only GL commands that are 673 allowed within any Begin/End pairs are the commands for specifying 674 vertex coordinates, vertex colors, normal coordinates, texture 675 coordinates, generic vertex attributes and fog coordinates (Vertex, 676 Color, SecondaryColor, Index, Normal, TexCoord and MultiTexCoord, 677 VertexAttrib*ARB, FogCoord), ... 678 679 Modify Section 2.7, Vertex Specification (p. 19) 680 681 (modify second paragraph, p. 20) Implementations support more than one 682 set of texture coordinates. The commands 683 684 void MultiTexCoord{1234}{sifd}(enum texture, T coords) 685 void MultiTexCoord{1234}{sifd}v(enum texture, T coords) 686 687 take the coordinate set to be modified as the <texture> parameter. 688 <texture> is a symbolic constant of the form TEXTUREi, indicating that 689 texture coordinate set i is to be modified. The constants obey TEXTUREi 690 = TEXTURE0 + i (i is in the range 0 to k-1, where k is the 691 implementation-dependent number of texture coordinate sets defined by 692 MAX_TEXTURE_COORDS_ARB). 693 694 (remove the "Finally" from the second paragraph on p. 21) 695 696 (add the following prior to the last paragraph in the section, p. 21) 697 698 Vertex shaders (see Section 2.15) can be written to access an array of 699 4-component generic vertex attributes in addition to the conventional 700 attributes specified previously. The first slot of this array is 701 numbered 0, and the length of the array is specified by the 702 implementation-dependent constant MAX_VERTEX_ATTRIBS_ARB. 703 704 The commands 705 706 void VertexAttrib{1234}{sfd}ARB(uint index, T values) 707 void VertexAttrib{123}{sfd}vARB(uint index, T values) 708 void VertexAttrib4{bsifd ubusui}vARB(uint index, T values) 709 710 can be used to load the given value(s) into the generic attribute at 711 slot <index>, whose components are named <x>, <y>, <z>, and <w>. The 712 VertexAttrib1*ARB family of commands sets the <x> coordinate to the 713 provided single argument while setting <y> and <z> to 0 and <w> to 1. 714 Similarly, VertexAttrib2*ARB commands set <x> and <y> to the specified 715 values, <z> to 0 and <w> to 1; VertexAttrib3*ARB commands set <x>, <y>, 716 and <z>, with <w> set to 1, and VertexAttrib4*ARB commands set all four 717 coordinates. The error INVALID_VALUE is generated if <index> is greater 718 than or equal to MAX_VERTEX_ATTRIBS_ARB. 719 720 The commands 721 722 void VertexAttrib4NubARB(uint index, T values) 723 void VertexAttrib4N{bsi ubusui}vARB(uint index, T values) 724 725 also specify vertex attributes with fixed-point coordinates that are 726 scaled to a normalized range, according to Table 2.6. 727 728 The VertexAttrib*ARB entry points defined earlier can also be used to 729 load attributes declared as a 2x2, 3x3 or 4x4 matrix in a vertex shader. 730 Each column of a matrix takes up one generic 4-component attribute slot 731 out of the MAX_VERTEX_ATTRIBS_ARB available slots. Matrices are loaded 732 into these slots in column major order. Matrix columns need to be loaded 733 in increasing slot numbers. 734 735 Setting generic vertex attribute zero specifies a vertex; the four 736 vertex coordinates are taken from the values of attribute zero. A 737 Vertex2, Vertex3, or Vertex4 command is completely equivalent to the 738 corresponding VertexAttrib*ARB command with an index of zero. Setting 739 any other generic vertex attribute updates the current values of the 740 attribute. There are no current values for vertex attribute zero. 741 742 There is no aliasing among generic attributes and conventional 743 attributes. In other words, an application can set all 744 MAX_VERTEX_ATTRIBS_ARB generic attributes and all conventional 745 attributes without fear of one particular attribute overwriting the 746 value of another attribute. 747 748 (Change the first half of the last paragraph in the section, p. 21, to) 749 750 The state required to support vertex specification consists of four 751 floating-point numbers per texture coordinate set to store the current 752 texture coordinates s, t, r, and q, three floating-point numbers to 753 store the three coordinates of the current normal, one floating-point 754 number to store the current fog coordinate, four floating- point values 755 to store the current RGBA color, four floating-point values to store the 756 current RGBA secondary color, one floating-point value to store the 757 current color index, and MAX_VERTEX_ATTRIBS_ARB-1 four-component 758 floating-point vectors for generic vertex attributes. There is no notion 759 of a current vertex, so no state is devoted to vertex coordinates or 760 generic vertex attribute zero. The initial texture coordinates are 761 (S,T,R,Q) = (0,0,0,1) for each texture coordinate set. The initial 762 current normal has coordinates (0,0,1). The initial fog coordinate is 763 zero. The initial RGBA color is (R,G,B,A) = (1,1,1,1) and the initial 764 RGBA secondary color is (0, 0, 0, 1). The initial color index is 1. The 765 initial values for all generic vertex attributes are (0, 0, 0, 1). 766 767 Modify Section 2.8, Vertex Arrays (p. 23) 768 769 (modify first paragraph of section, p.23) The vertex specification 770 commands described in section 2.7 accept data in almost any format, but 771 their use requires many command executions to specify even simple 772 geometry. Vertex data may also be placed into arrays that are stored in 773 the client's address space. Blocks of data in these arrays may then be 774 used to specify multiple geometric primitives through the execution of a 775 single GL command. The client may specify up to 7 plus the values of 776 MAX_TEXTURE_COORDS_ARB and MAX_VERTEX_ATTRIBS_ARB arrays: One each to 777 store vertex coordinates, edge flags, colors, secondary colors, color 778 indices, normals, fog coordinates, one or more texture coordinate sets, 779 and one or more generic vertex attributes. 780 781 The commands 782 783 ... 784 785 void VertexAttribPointerARB(uint index, int size, enum type, 786 boolean normalized, sizei stride, 787 const void *pointer) 788 789 describe the locations and organizations... 790 791 (add after the first paragraph, p.24) The <index> parameter in the 792 VertexAttribPointerARB command identifies the generic vertex attribute 793 array being described. The error INVALID_VALUE is generated if <index> 794 is greater than or equal to MAX_VERTEX_ATTRIBS_ARB. The <normalized> 795 parameter in the VertexAttribPointerARB command identifies whether 796 fixed-point types should be normalized when converted to floating-point. 797 If <normalized> is TRUE, fixed-point data are converted as specified in 798 Table 2.6; otherwise, the fixed-point values are converted directly. 799 800 (add to the beginning of the page, p. 25) An individual generic vertex 801 attribute array is enabled or disabled by calling one of 802 803 void EnableVertexAttribArrayARB(uint index) 804 void DisableVertexAttribArrayARB(uint index) 805 806 where <index> identifies the generic vertex attribute array to enable or 807 disable. The error INVALID_VALUE is generated if <index> is greater than 808 or equal to MAX_VERTEX_ATTRIBS_ARB. 809 810 (modify Table 2.4, p.24) 811 812 Normal 813 Command Sizes ized? Types 814 ---------------------- ------- ------ --------------------------- 815 VertexPointer 2,3,4 no short, int, float, double 816 NormalPointer 3 yes byte, short, int, float, 817 double 818 ColorPointer 3,4 yes byte, ubyte, short, ushort, 819 int, uint, float, double 820 SecondaryColorPointer 3 yes byte, ubyte, short, ushort, 821 int, uint, float, double 822 IndexPointer 1 no ubyte, short, int, float, 823 double 824 FogCoordPointer 1 n/a float, double 825 TexCoordPointer 1,2,3,4 no short, int, float, double 826 EdgeFlagPointer 1 no boolean 827 VertexAttribPointerARB 1,2,3,4 flag byte, ubyte, short, ushort, 828 int, uint, float, double 829 830 Table 2.4: Vertex array sizes (values per vertex) and data types. The 831 "normalized" column indicates whether fixed-point types are accepted 832 directly or normalized to [0,1] (for unsigned types) or [-1,1] (for 833 signed types). For generic vertex attributes, fixed-point data are 834 normalized if and only if the <normalized> flag is set. 835 836 (modify first paragraph, p. 25) The command 837 838 void ClientActiveTexture(enum texture) 839 840 is used to select the vertex array client state parameters to be 841 modified by the TexCoordPointer command and the array affected by 842 EnableClientState and DisableClientState with parameter 843 TEXTURE_COORD_ARRAY. This command sets the client state variable 844 CLIENT_ACTIVE_TEXTURE. Each texture coordinate set has a client state 845 vector which is selected when this command is invoked. This state vector 846 includes the vertex array state. This call also selects the texture 847 coordinate set state used for queries of client state. 848 849 (modify third paragraph, p. 25) The command 850 851 void ArrayElement(int i); 852 853 transfers the ith element of every enabled array to the GL. The effect 854 of ArrayElement(i) is the same as the effect of the command sequence 855 856 if (normal array enabled) { 857 Normal3[type]v(normal array element i); 858 } 859 if (color array enabled) { 860 Color[size][type]v(color array element i); 861 } 862 if (secondary color array enabled) { 863 SecondaryColor3[type]v(secondary color array element i); 864 } 865 if (fog coordinate array enabled) { 866 FogCoord[type]v(fog coordinate array element i); 867 } 868 for (j = 0; j < textureUnits; j++) { 869 if (texture coordinate set j array enabled) { 870 MultiTexCoord[size][type]v(TEXTURE0 + j, 871 texture coordinate set j 872 array element i); 873 } 874 if (color index array enabled) { 875 Index[type]v(color index array element i); 876 } 877 if (edge flag array enabled) { 878 EdgeFlagv(edge flag array element i); 879 } 880 for (j = 1; j < genericAttributes; j++) { 881 if (generic vertex attribute j array enabled) { 882 if (generic vertex attribute j array normalization flag 883 is set, and type is not FLOAT or DOUBLE) { 884 VertexAttrib[size]N[type]vARB(j, generic vertex attribute j 885 array element i); 886 } else { 887 VertexAttrib[size][type]vARB(j, generic vertex attribute j 888 array element i); 889 } 890 } 891 } 892 if (generic attribute array 0 enabled) { 893 if (generic vertex attribute 0 array normalization flag 894 is set, and type is not FLOAT or DOUBLE) { 895 VertexAttrib[size]N[type]vARB(0, generic vertex attribute 0 896 array element i); 897 } else { 898 VertexAttrib[size][type]vARB(0, generic vertex attribute 0 899 array element i); 900 } 901 } else if (vertex array enabled) { 902 Vertex[size][type]vARB(vertex array element i); 903 } 904 905 where <textureUnits> and <genericAttributes> give the number of texture 906 coordinate sets and generic vertex attributes supported by the 907 implementation, respectively. "[size]" and "[type]" correspond to the 908 size and type of the corresponding array. For generic vertex attributes, 909 it is assumed that a complete set of vertex attribute commands exists, 910 even though not all such functions are provided by the GL. 911 912 (modify the first paragraph on p. 26) ...with one exception: The current 913 edge flag, texture coordinates, color, secondary color, color index, fog 914 coordinate, normal coordinates and generic attributes are each 915 indeterminate after execution of DrawArrays, if the corresponding array 916 is enabled. 917 918 (modify the first paragraph on p. 27) ...with one exception: The current 919 edge flag, texture coordinates, color, secondary color, color index, fog 920 coordinate, normal coordinates and generic attributes are each 921 indeterminate after execution of DrawElements, if the corresponding 922 array is enabled. 923 924 (modify last paragraph of section, p. 30) If the number of supported 925 texture coordinate sets (the value of MAX_TEXTURE_COORDS_ARB) is m and 926 the number of supported generic vertex attributes (the value of 927 MAX_VERTEX_ATTRIBS_ARB) is n, then the client state required to 928 implement vertex arrays consists of 7+m+n Boolean values, 7+m+n memory 929 pointers, 7+m+n integer stride values, 7+m+n symbolic constants 930 representing array types, 3+m+n integers representing values per element 931 and n boolean values indicating normalization. In the initial state, the 932 boolean values are each disabled, the memory pointers are each null, the 933 strides are each zero, the array types are each FLOAT, and the integers 934 representing values per element are each four. 935 936 Modify Section 2.10, Coordinate Transformations (p. 31) 937 938 (add at the beginning of the section) This section and the discussion 939 through section 2.13 describe the state values and operations necessary 940 for transforming vertex attributes according to a fixed-functionality 941 method. An alternate method for transforming vertex attributes is 942 described in section 2.15. 943 944 Modify Section 2.10.2, Matrices (p. 33) 945 946 (modify first paragraph, p. 37) For each texture coordinate set, a 4x4 947 matrix is applied to the corresponding texture coordinates. This matrix 948 is applied as... 949 950 (modify third and fourth paragraphs, p. 37) The command 951 952 void ActiveTexture(enum texture) 953 954 specifies the active texture unit selector, ACTIVE_TEXTURE. Each texture 955 unit contains up to two distinct sub-units: a texture coordinate 956 processing unit (consisting of a texture matrix stack and texture 957 coordinate generation state) and a texture image unit (consisting of all 958 the texture state defined in Section 3.8). In implementations with a 959 different number of supported texture coordinate sets and texture image 960 units, some texture units may consist of only one of the two sub-units. 961 962 The active texture unit selector specifies the texture coordinate set 963 accessed by commands involving texture coordinate processing. Such 964 commands include those accessing the current matrix stack (if 965 MATRIX_MODE is TEXTURE), TexGen (section 2.10.4), Enable/Disable (if any 966 texture coordinate generation enum is selected), as well as queries of 967 the current texture coordinates and current raster texture coordinates. 968 If the texture coordinate set number corresponding to the current value 969 of ACTIVE_TEXTURE is greater than or equal to the 970 implementation-dependent constant MAX_TEXTURE_COORDS_ARB, the error 971 INVALID_OPERATION is generated by any such command. The active texture 972 unit selector also selects the texture image unit accessed by commands 973 involving texture image processing (section 3.8). Such commands include 974 all variants of TexEnv, TexParameter, and TexImage commands, 975 BindTexture, Enable/Disable for any texture target (e.g., TEXTURE_2D), 976 and queries of all such state. If the texture image unit number 977 corresponding to the current value of ACTIVE_TEXTURE is greater than or 978 equal to the implementation-dependent constant 979 MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB, the error INVALID_OPERATION is 980 generated by any such command. 981 982 ActiveTexture generates the error INVALID_ENUM if an invalid <texture> 983 is specified. <texture> is a symbolic constant of the form TEXTUREi, 984 indicating that texture unit i is to be modified. The constants obey 985 TEXTUREi = TEXTURE0 + i (i is in the range 0 to k-1, where k is the 986 larger of the MAX_TEXTURE_COORDS_ARB and 987 MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB). For compatibility with old OpenGL 988 specifications, the implementation-dependent constant MAX_TEXTURE_UNITS 989 specifies the number of conventional texture units supported by the 990 implementation. Its value must be no larger than the minimum of 991 MAX_TEXTURE_COORDS_ARB and MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB. 992 993 (modify third paragraph, p. 38) The state required to implement 994 transformations consists of a 4-valued integer indicating the current 995 matrix mode, one stack of at least two 4x4 matrices for each of COLOR, 996 PROJECTION, each texture coordinate set, and TEXTURE and a stack of at 997 least 32 4x4 matrices for MODELVIEW. Each matrix stack has an associated 998 stack pointer. Initially, there is only one matrix on each stack, and 999 all matrices are set to the identity. The initial matrix mode is 1000 MODELVIEW. The initial value of ACTIVE_TEXTURE is TEXTURE0. 1001 1002 Modify Section 2.11, Clipping (p. 42) 1003 1004 (Add a new paragraph between the first and second paragraph on page 43) 1005 When a vertex shader is active, the vector (Xe Ye Ze We)T is no longer 1006 computed by the GL. Instead, the OpenGL Shading Language provides a 1007 gl_ClipVertex built-in variable, which is used in the dot product with 1008 the client-defined clip planes. The user must ensure that the clip 1009 vertex and client-defined clip planes are defined in the same coordinate 1010 space. Note that the value in gl_ClipVertex is undefined if it is not 1011 written by the vertex shader. 1012 1013 Modify Section 2.12, Current Raster Position 1014 1015 (modify fourth paragraph, p.44) The coordinates are treated as if they 1016 were specified in a Vertex command. If a vertex shader is active, this 1017 vertex shader is executed using the x, y, z, and w coordinates as the 1018 object coordinates of the vertex. Otherwise, the x, y, z, and w 1019 coordinates are transformed by the current model-view and projection 1020 matrices. These coordinates, along with current values, are used to 1021 generate primary and secondary colors and texture coordinates just as is 1022 done for a vertex. The colors and texture coordinates produced using 1023 either method replace the colors and texture coordinates stored in the 1024 current raster position's associated data. If a vertex shader is active 1025 then the current raster distance is set to the value of the shader built 1026 in varying gl_FogFragCoord. Otherwise, if the value of the fog source 1027 (see section 3.10) is FOG_COORDINATE_SOURCE, then the current raster 1028 distance is set to the value of the current fog coordinate. Otherwise, 1029 the current raster distance is set to the distance from the origin of 1030 the eye coordinate system to the vertex as transformed by only the 1031 current model-view matrix. This distance may be approximated as 1032 discussed in section 3.10. 1033 1034 Since vertex shaders may be executed when the raster position is set, 1035 any attributes not written by the shader will result in undefined state 1036 in the current raster position. Vertex shaders should output all varying 1037 variables that would be used when rasterizing pixel primitives using the 1038 current raster position. 1039 1040 Modify section 2.13.1, Lighting 1041 1042 (add just before the first paragraph on page 53) Additionally, vertex 1043 shaders can operate in two-sided color mode. When a vertex shader is 1044 active, front and back colors can be computed by the vertex shader and 1045 written to the gl_FrontColor, gl_BackColor, gl_FrontSecondaryColor and 1046 gl_BackSecondaryColor outputs. If VERTEX_PROGRAM_TWO_SIDE_ARB is 1047 enabled, the GL chooses between front and back colors, as described 1048 later. Otherwise, the front color output is always selected. Two-sided 1049 color mode is enabled and disabled by calling Enable or Disable with the 1050 symbolic value VERTEX_PROGRAM_TWO_SIDE_ARB. 1051 1052 The selection between back color and front color depends ... 1053 1054 Modify section 2.13.2, Lighting Parameter Specification (p. 53) 1055 1056 (add a new paragraph between paragraph 2 and 3 on page 54) Material 1057 properties can be changed inside a Begin/End pair by calling Material. 1058 However, when a vertex shader is active such property changes are not 1059 guaranteed to update material parameters, defined in Table 2.8, until 1060 the following End command. 1061 1062 Modify section 2.13.3, ColorMaterial 1063 1064 (add a paragraph after the last paragraph, page 57) Material properties 1065 can be changed inside a Begin/End pair indirectly by enabling 1066 ColorMaterial mode and making Color calls. However, when a vertex shader 1067 is active such property changes are not guaranteed to update material 1068 parameters, defined in Table 2.8, until the following End command. 1069 1070 Rename and Modify Section 2.13.8, Color and Texture Coordinate Clipping 1071 (p.59) 1072 1073 (modify second paragraph, p. 60) Texture coordinates, varying variables, 1074 fog coordinates and point sizes computed on a per vertex basis must also 1075 be clipped when a primitive is clipped. The method is exactly analogous 1076 to that used for color clipping. 1077 1078 Add Section 2.15 Vertex Shaders 1079 1080 The sequence of operations described in Sections 2.10 through 2.13 is a 1081 fixed- functionality method for processing vertex data. Applications can 1082 more generally describe the operations that occur on vertex values and 1083 their associated data by using a "vertex shader". 1084 1085 A vertex shader is an array of strings containing source code for the 1086 operations that are meant to occur on each vertex that is processed. The 1087 language used for vertex shaders is described in the OpenGL Shading 1088 Language Specification. 1089 1090 Section 2.15.1 Creating and Using a Vertex Shader 1091 1092 In order to create a vertex shader, use CreateShaderObjectARB with a 1093 <shaderType> of VERTEX_SHADER_ARB. The source code for the vertex shader 1094 can be specified in one call using the ShaderSourceARB command. A vertex 1095 shader is compiled by issuing CompileShaderARB and attached to a program 1096 object by calling AttachObjectARB. When LinkProgramARB is issued, all of 1097 the attached shader objects of type VERTEX_SHADER_ARB are linked 1098 together to create an executable program that can be used to process 1099 vertex values and their associated data. This executable program will 1100 become part of current state and used to process subsequent vertex data 1101 when UseProgramObjectARB is called. 1102 1103 CreateShaderObjectARB will set the object specific parameter 1104 OBJECT_SUBTYPE_ARB to VERTEX_SHADER_ARB. 1105 1106 Section 2.15.2 Vertex Attributes 1107 1108 Conventional vertex attributes are communicated to the vertex shader via 1109 the Vertex, Normal, Color, etc. API commands (or their vertex array 1110 equivalents). Generic attributes are communicated via the 1111 VertexAttrib*ARB and VertexAttribPointerARB commands. The binding of the 1112 name of an attribute variable to a generic attribute index is assigned 1113 by the GL and can be queried. This generic attribute index can be used 1114 in the VertexAttrib*ARB and VertexAttribPointerARB commands. 1115 Alternatively, this binding can be overridden and specified explicitly, 1116 if so desired. These mechanisms make it possible for a vertex shader to 1117 use descriptive names for attribute variables rather than having generic 1118 variables numbered from 0 to MAX_VERTEX_ATTRIBS_ARB - 1. For example, an 1119 application can specify that the attribute variable "tangentVec" in a 1120 vertex shader will be mapped to generic vertex attribute number 6. 1121 1122 When an attribute variable declared as a float, vec2, vec3 or vec4 is 1123 bound to a generic attribute index <i>, its value(s) are stored in the 1124 <x>, <x,y>, <x,y,z> or <x,y,z,w> components of the generic attribute at 1125 slot <i>. Recall that the VertexAttrib*ARB commands will set unused 1126 components to default values (either 0 or 1, see section 2.7). 1127 1128 An attribute (either conventional or generic) is considered "active" if 1129 it is determined by the compiler and linker that the attribute may be 1130 accessed when the executable code is executed. The program object will 1131 fail to link if the sum of the active generic and active conventional 1132 attributes exceeds MAX_VERTEX_ATTRIBS_ARB. Attribute variables that are 1133 declared in a vertex shader but never used will not count against the 1134 limit. In cases where the compiler and linker cannot make a conclusive 1135 determination, the attribute will be considered active. 1136 1137 To determine which of the declared vertex attribute variables an 1138 executable program uses and to determine their types, use the command: 1139 1140 void GetActiveAttribARB(handleARB programObj, uint index, 1141 sizei maxLength, sizei *length, int *size, 1142 enum *type, charARB *name) 1143 1144 This command provides information about the attribute selected by 1145 <index>. The <index> of 0 selects the first active attribute, and 1146 <index> of OBJECT_ACTIVE_ATTRIBUTES_ARB-1 selects the last active 1147 attribute. The value of OBJECT_ACTIVE_ATTRIBUTES_ARB can be queried with 1148 GetObjectParameter{if}vARB (see Section 6.1.12). If <index> is greater 1149 than or equal to OBJECT_ACTIVE_ATTRIBUTES_ARB, the error INVALID_VALUE 1150 is generated. 1151 1152 The parameter <programObj> is a handle to a program object for which the 1153 command LinkProgramARB has been issued in the past. It is not necessary 1154 for <programObj> to have been linked successfully. The link could have 1155 failed because the number of active attributes exceeded the limit. If 1156 <programObj> is not of type PROGRAM_OBJECT_ARB, the error 1157 INVALID_OPERATION is generated. 1158 1159 For the selected attribute, the attribute name is returned into <name>. 1160 The string <name> will be null terminated. The actual number of 1161 characters written by the GL into <name> is returned in <length>. This 1162 count excludes the null termination. If <length> is NULL then the GL 1163 ignores this parameter. The maximum number of characters the GL is 1164 allowed to write into <name> is passed in by <maxLength>. The returned 1165 attribute name can be the name of a generic attribute or a conventional 1166 attribute (which begin with the prefix "gl_", see the OpenGL Shading 1167 Language specification for a complete list). The length of the longest 1168 attribute name in <programObj> is given by 1169 OBJECT_ACTIVE_ATTRIBUTE_MAX_LENGTH_ARB, which can be queried with 1170 GetObjectParameter{if}vARB (see Section 6.1.12). 1171 1172 For the selected attribute, the type of the attribute is returned into 1173 <type>. The size of the attribute is returned into <size>. The value in 1174 <size> is in units of the type returned in <type>. The type returned can 1175 be any of FLOAT, FLOAT_VEC2_ARB, FLOAT_VEC3_ARB, FLOAT_VEC4_ARB, 1176 FLOAT_MAT2_ARB, FLOAT_MAT3_ARB, or FLOAT_MAT4_ARB. 1177 1178 If an error occurred, the return parameters <length>, <size>, <type> and 1179 <name> will be unmodified. 1180 1181 This command will return as much information about active attributes as 1182 possible. If no information is available, <length> will be set to zero 1183 and <name> will be an empty string. This situation could arise if 1184 GetActiveAttribARB is issued after a failed link. 1185 1186 After a program object has been linked successfully, the bindings of 1187 attribute variable names to indices can be queried. 1188 1189 The command 1190 1191 GLint GetAttribLocationARB(handle programObj, const charARB *name) 1192 1193 will return the generic attribute index that the attribute variable 1194 named <name> is bound to. <name> has to be a null terminated string. 1195 <programObj> is a handle to a program object that has been successfully 1196 linked. If <name> is not an active attribute, or if <name> is a 1197 conventional attribute, -1 will be returned. If <name> is an attribute 1198 matrix, and it is active, then GetAttribLocationARB returns the index of 1199 the first column of that matrix. If <programObj> has not been 1200 successfully linked, or if <programObj> is not of type 1201 PROGRAM_OBJECT_ARB, the error INVALID_OPERATION is generated. 1202 1203 The binding of an attribute variable to a generic attribute index can 1204 also be specified explicitly. 1205 1206 The command 1207 1208 void BindAttribLocationARB(handleARB programObj, uint index, 1209 const charARB *name) 1210 1211 binds the attribute variable named <name> to generic vertex attribute 1212 <index> for the program object <programObj>. If <name> was bound 1213 previously, that binding information is lost. <name> has to be a null 1214 terminated string. If <name> is declared as an attribute matrix, <index> 1215 indicates the first column of that matrix. The other matrix columns are 1216 then automatically bound to locations <index> + 1 for a mat2, <index> + 1217 1 and <index> + 2 for a mat3 and <index> + 1, <index> + 2 and <index> + 1218 3 for a mat4. The error INVALID_VALUE is generated if <index> is equal 1219 or greater than MAX_VERTEX_ATTRIBS_ARB. The error INVALID_OPERATION is 1220 generated if <name> starts with the reserved "gl_" prefix. If 1221 <programObj> is not of type PROGRAM_OBJECT_ARB, the error 1222 INVALID_OPERATION is generated. 1223 1224 Applications cannot bind any conventional attributes (the attributes 1225 starting with "gl_" defined in the OpenGL Shading Language 1226 specification). Conventional attributes used in a vertex shader will be 1227 bound automatically. 1228 1229 In order to have attribute bindings take effect the program object needs 1230 to be linked after issuing the BindAttribLocationARB command. The linker 1231 will bind any active attributes not already explicitly specified through 1232 BindAttribLocationARB. After a successful link the complete list of 1233 bindings can be queried using the command GetAttribLocationARB. 1234 1235 It is generally not known to the GL until link time if <name> is 1236 declared as an attribute matrix. Therefore LinkProgramARB can fail 1237 because binding of a matrix to a generic attribute index caused one or 1238 more columns of the matrix to be bound to indices outside the 1239 MAX_VERTEX_ATTRIBS_ARB range. LinkProgramARB can also fail because 1240 BindAttribLocationsARB commands have been issued leaving not enough 1241 contiguous indices for a matrix to be fitted in by the linker. 1242 1243 It is allowed to issue BindAttribLocationARB before any vertex shader 1244 objects are attached to a program object. Hence it is allowed to bind 1245 any name (except a name starting with "gl_") to an index, including a 1246 name that is never used as an attribute in any vertex shader object. 1247 1248 The values of generic attributes sent to generic attribute index <i> are 1249 part of current GL state, just like the conventional attributes. If a 1250 new program object has been made active, then these values will be 1251 tracked by the GL in such a way that the same values will be observed by 1252 attributes in the new program object that are also bound to index <i>. 1253 1254 It is a link error to have a vertex shader statically consume the 1255 conventional attribute gl_Vertex and have the same vertex shader 1256 statically consume a generic vertex attribute that is bound to index 1257 zero. This would result in aliasing between a generic vertex attribute 1258 and the conventional attribute gl_Vertex, which is disallowed (see the 1259 description of VertexAttrib*ARB in Section 2.7). 1260 1261 It is possible for an application to bind more than one attribute name 1262 to the same location. This is referred to as "aliasing". This will only 1263 work if only one of the aliased attributes is active in the executable 1264 program, or if no path through the shader consumes more than one 1265 attribute of a set of attributes aliased to the same location. OpenGL 1266 implementations are not required to detect violations of this rule. The 1267 compiler and linker are allowed to assume that no aliasing is done, and 1268 are free to employ optimizations that work only in the absence of 1269 aliasing. It is not possible to alias generic attributes with 1270 conventional ones. 1271 1272 When a vertex shader is active, more (or less) vertex attributes might 1273 be sent to OpenGL than the vertex shader uses. When fewer attributes 1274 than the current vertex shader uses are sent, the vertex shader uses the 1275 values in the current state for the attributes not provided. In the case 1276 of a generic vertex attribute that current value comes from the slot 1277 index number the generic attribute is bound to. When more attributes are 1278 provided than the vertex shader uses the vertex shader ignores the extra 1279 attributes but these extra attributes continue to modify the current 1280 vertex attribute state. 1281 1282 Section 2.15.3 Uniform Variables 1283 1284 A vertex shader may define one or more "uniform" variables. These values 1285 are to remain constant over a primitive or a sequence of primitives. The 1286 OpenGL Shading Language specification defines a set of built-in uniform 1287 variables for vertex shaders that correspond to the state that GL 1288 manages for the purpose of processing vertices. The amount of storage 1289 that is available for vertex shader uniform variables is specified by 1290 the implementation dependent constant MAX_VERTEX_UNIFORM_COMPONENTS_ARB. 1291 This value represents the number of individual floating point values, or 1292 individual integer values or individual Boolean values that can be held 1293 in uniform variable storage for a vertex shader. A link error will be 1294 generated if an attempt is made to utilize more than the space available 1295 for vertex shader uniform variables. 1296 1297 Section 2.15.4 Varying Variables 1298 1299 A vertex shader may define one or more "varying" variables (see the 1300 OpenGL Shading Language specification). These values are expected to be 1301 interpolated across the primitive being rendered. The OpenGL Shading 1302 Language specification defines a set of built-in varying variables for 1303 vertex shaders that correspond to the values required for the fixed 1304 functionality processing that occurs after vertex processing. The number 1305 of interpolators that is available for processing varying variables is 1306 specified by the implementation dependent constant 1307 MAX_VARYING_FLOATS_ARB. This value represents the number of individual 1308 floating point values that can be interpolated, therefore interpolating 1309 a vertex will consume 4 (x, y, z, w) and interpolating a color will also 1310 consume 4 (R, G, B, A). A link error will be generated if an attempt is 1311 made to utilize more than MAX_VARYING_FLOATS_ARB interpolators. 1312 1313 Section 2.15.5 Texture access 1314 1315 Vertex shaders have the ability to do a lookup into a texture map. Zero 1316 or more texture image units are available to a vertex shader to access 1317 textures. The maximum number of texture image units available to a 1318 vertex shader is MAX_VERTEX_TEXTURE_IMAGE_UNITS_ARB. The maximum number 1319 of texture image units available to the fragment stage of OpenGL is 1320 MAX_TEXTURE_IMAGE_UNITS_ARB. Both the vertex shader and fragment 1321 processing combined cannot use more than 1322 MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB texture image units. If both the 1323 vertex shader and the fragment processing stage access the same texture 1324 image unit, then that counts as using two texture image units against 1325 the MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB limit. 1326 1327 When a texture lookup is performed in a vertex shader, the GL computes 1328 the filtered texture value tau in the manner described in sections 3.8.8 1329 and 3.8.9, and converts it to a texture source color C_s according to 1330 table 3.21 (section 3.8.13). The GL returns a four-component vector 1331 (R_s, G_s, B_s, A_s) to the vertex shader. 1332 1333 In a vertex shader, it is not possible to perform automatic LOD 1334 calculations using partial derivatives of the texture coordinates with 1335 respect to window coordinates as described in section 3.8.8. Hence, 1336 there is no automatic selection of an image array level. Minification or 1337 magnification of a texture map is controlled by a LOD value optionally 1338 passed as an argument in the texture lookup functions. If the texture 1339 lookup function supplies an explicit LOD value <l>, then the pre-bias 1340 LOD value lambda_base(x,y) = l (equation 3.16a). If the texture lookup 1341 function does not supply an explicit LOD value, then lambda_base(x,y) = 1342 0. The scale factor rho(x,y) and its approximation function f(x,y), 1343 pages 141-142, are ignored. 1344 1345 Texture comparison requires the vertex shader to use the shadow versions 1346 of the texture lookup functions. This in turn means that samplers of 1347 type sampler1DShadow or sampler2DShadow or sampler2DRectShadow need to 1348 be used to indicate the texture image unit that has a depth texture 1349 bound to it. 1350 1351 The results of a texture lookup function are undefined if: 1352 1353 * The sampler used in a texture lookup function is of type sampler1D 1354 or sampler2D or sampler2DRect, and the texture object's internal 1355 format is DEPTH_COMPONENT, and the TEXTURE_COMPARE_MODE is not NONE. 1356 * The sampler used in a texture lookup function is of type 1357 sampler1DShadow or sampler2DShadow or sampler2DRectShadow, and the 1358 texture object's internal format is DEPTH_COMPONENT, and the 1359 TEXTURE_COMPARE_MODE is NONE. 1360 * The sampler used in a texture lookup function is of type 1361 sampler1DShadow or sampler2DShadow or sampler2DRectShadow, and the 1362 texture object's internal format is not DEPTH_COMPONENT. 1363 1364 If a vertex shader uses a sampler which associated texture object is not 1365 complete, as defined in section 3.8.10, the texture image unit will 1366 return (R, G, B, A) = (0, 0, 0, 1). 1367 1368 Section 2.15.6 Position Invariance 1369 1370 If a vertex shader uses the built-in function ftransform() to generate a 1371 vertex position, then this generally guarantees that the transformed 1372 position will be the same whether using this vertex shader or the fixed 1373 functionality OpenGL pipeline. This allows for correct mixed multi-pass 1374 rendering algorithms. 1375 1376 Section 2.15.7 Vertex Shader Execution 1377 1378 If a successfully linked program object that contains a vertex shader is 1379 made current by calling UseProgramObjectARB, the executable version of 1380 the vertex shader is used to process incoming vertex values rather than 1381 the fixed functionality vertex processing described in Sections 1382 2.10-2.13. In particular, 1383 1384 * The model-view matrix is not applied to vertex coordinates (pp. 1385 31-32) 1386 * The projection matrix is not applied to vertex coordinates (pp. 1387 31-32) 1388 * The texture matrices are not applied to texture coordinates (p. 37) 1389 * Normals are not transformed to eye coordinates (pp. 38-39) 1390 * Normals are not rescaled or normalized (pp. 39-40) 1391 * Normalization of AUTO_NORMAL evaluated normals is not performed. (p. 1392 191) 1393 * Texture coordinates are not generated automatically (pp. 40-42) 1394 * Per vertex lighting is not performed (pp. 48-53) 1395 * Color material computations are not performed (pp. 54-57) 1396 * Color index lighting is not performed (pp. 57-58) 1397 * All of the above applies when setting the current raster position 1398 (pp. 44-45) 1399 1400 The following operations are applied to vertex values that are the 1401 result of executing the vertex shader: 1402 1403 * Color clamping or masking (p. 56) 1404 * Perspective division on clip coordinates (pp. 31-32) 1405 * Viewport mapping (pp. 32-33) 1406 * Depth range (p. 33) 1407 * Clipping, including user clipping (pp. 42-44) 1408 * Front face determination (p. 53) 1409 * Flat-shading (pp. 58-59) 1410 * Color, texture coordinate, fog, point-size and generic attribute 1411 clipping (pp. 59-60) 1412 * Final color processing (p. 60) 1413 1414 Section 2.15.8 Required State 1415 1416 Besides the required state outlined in the ARB_shader_objects extension 1417 document, the following state is also required: 1418 1419 The state required to support vertex shaders consists of: 1420 1421 * A bit indicating whether or not vertex program two-sided color mode 1422 is enabled, initially disabled. 1423 * A bit indicating whether or not vertex program point size mode is 1424 enabled, initially disabled. 1425 1426 The state required per program object consists of: 1427 1428 * An array of strings holding the names of active attributes. 1429 * An array of integers holding the sizes of active attributes. 1430 * An array of integers holding the types of active attributes. 1431 * An integer holding the number of active attributes 1432 * An integer holding the length of the longest attribute name. 1433 * An array of integers holding the locations of active generic 1434 attributes. 1435 * An array of MAX_VERTEX_UNIFORM_COMPONENTS_ARB words that holds 1436 uniform values. 1437 1438Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization) 1439 1440 Modify Section 3.3, Points (p. 66) 1441 1442 (replace the first and second paragraph) If a vertex shader is not 1443 active, then the rasterization of points is controlled with 1444 1445 void PointSize(float size) 1446 1447 <size> specifies the requested size of a point. The default value is 1448 1.0. A value less than or equal to zero results in the error 1449 INVALID_VALUE. The requested point size is multiplied with a distance 1450 attenuation factor, clamped to a specified point size range, and further 1451 clamped to the implementation-dependent point size range to produce the 1452 derived point size: 1453 1454 derived_size = ... 1455 1456 (add a paragraph between the third and fourth paragraph) 1457 1458 If a vertex shader is active and vertex program point size mode is 1459 enabled, then the derived point size is taken from the, potentially 1460 clipped, shader built in gl_PointSize and clamped to the 1461 implementation-dependent point size range. If the value written to 1462 gl_PointSize is less than or equal to zero, results are undefined. If a 1463 vertex shader is active and vertex program point size mode is disabled, 1464 then the derived point size is taken from the point size state as 1465 specified by the PointSize command. In this case no distance attenuation 1466 is performed. Vertex program point size mode is enabled and disabled by 1467 calling Enable or Disable with the symbolic value 1468 VERTEX_PROGRAM_POINT_SIZE_ARB. 1469 1470 If multisampling is enabled, an implementation ... 1471 1472 Modify Section 3.8.8 Texture Minification (p. 140) 1473 1474 (modify subsection Scale Factor and Level of Detail. Replace its first 1475 paragraph) 1476 1477 The choice is governed by a scale factor rho(x,y) and the level of 1478 detail parameter lambda(x,y), defined as 1479 1480 lambda_base(x,y) = log2[rho(x,y)] 3.16a 1481 1482 lambda'(x,y) = lambda_base(x,y) + 3.16b 1483 clamp(texobj_bias + texunit_bias) 1484 1485 |------- LODmax lambda' > LODmax 1486 lambda(x,y) = | lambda' LODmin <= lambda' <= LODmax 3.16c 1487 | LODmin lambda' < LODmin 1488 |------- undefined LODmin > LODmax 1489 1490 texobj_bias is the value of TEXTURE_LOD_BIAS for the bound texture 1491 object (as described in section 3.8.4), and texunit_bias is the value of 1492 TEXTURE_LOD_BIAS for the current texture unit (as described in section 1493 3.8.13). The sum of these values is clamped to the range [-max_bias, 1494 max_bias] where max_bias is the value of the implementation defined 1495 constant MAX_TEXTURE_LOD_BIAS. 1496 1497 Modify Section 3.9 Color Sum (p. 160) 1498 1499 (modify third paragraph) Color sum is enabled or disabled using the 1500 generic Enable and Disable commands, respectively, with the symbolic 1501 constant COLOR_SUM. If lighting is enabled and if a vertex shader is not 1502 active, the color sum stage is always applied, ignoring the value of 1503 COLOR_SUM. 1504 1505 Modify Section 3.10, Fog (p. 160) 1506 1507 (modify second paragraph) If a vertex shader is active, or if the fog 1508 source, as defined below, is FOG_COORDINATE, then c is the interpolated 1509 value of the fog coordinate for this fragment. Otherwise, if the fog 1510 source is FRAGMENT_DEPTH, then c is the eye-coordinate distance from the 1511 eye, (0, 0, 0, 1) in eye coordinates, to the fragment center. The 1512 equation and the fog source, along with either d or e and s, is 1513 specified with 1514 1515Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment 1516Operations and the Frame Buffer) 1517 1518 None 1519 1520Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions) 1521 1522 Modify Section 5.1, Evaluators (p. 188) 1523 1524 (modify next-to-last paragraph, p. 191) For MAP_VERTEX_3, let q = p. For 1525 MAP_VERTEX_4, let q=(x/w,y/w,z/w), where (x,y,z,w) = p. Then let 1526 1527 dq dq 1528 m = -- x --. 1529 du dv 1530 1531 Then the generated analytic normal, n, is given by n=m if a vertex 1532 shader is active, or else by n=m/|m|. 1533 1534 Modify Section 5.4, Display Lists (p. 198) 1535 1536 (change second paragraph, p. 202) 1537 1538 Certain commands, when called when compiling a display list, are not 1539 compiled into the display list but are executed immediately. These are: 1540 IsList,...Flush, Finish, GetAttribLocationARB, GetActiveAttribARB, 1541 BindAttribLocationARB, VertexAttribPointerARB, 1542 EnableVertexAttribArrayARB, DisableVertexAttribArrayARB as well as 1543 IsEnabled and all of the Get commands defined in Section 6.1.12. 1544 1545 (add just before the final paragraph of the section on p. 202) 1546 1547 When a program object is in use, a display list may be executed whose 1548 vertex attribute calls do not match up exactly with what is expected by 1549 the vertex shader contained in that program object. How this mismatch is 1550 handled is described in section 2.15.2. 1551 1552Additions to Chapter 6 of the OpenGL 1.4 Specification (State and State 1553Requests) 1554 1555 Modify Section 6.1.2, Data Conversions (p. 205) 1556 1557 (add to end of last paragraph, p. 206) Queries of texture state 1558 variables corresponding to texture coordinate processing unit (namely, 1559 TexGen state and enables, and matrices) will produce an 1560 INVALID_OPERATION error if the value of ACTIVE_TEXTURE is greater than 1561 or equal to MAX_TEXTURE_COORDS_ARB. All other texture state queries will 1562 result in an INVALID_OPERATION error if the value of ACTIVE_TEXTURE is 1563 greater than or equal to MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB. 1564 1565 Modify section 6.1.12 Generic Object Queries. 1566 1567 The commands 1568 1569 void GetObjectParameterfvARB(handleARB obj, enum pname, 1570 float *params) 1571 void GetObjectParameterivARB(handleARB obj, enum pname, int *params) 1572 1573 return object specific parameter values for object <obj> in <params>. 1574 The parameter value to return is specified by <pname>. 1575 1576 If <pname> is OBJECT_SUBTYPE_ARB, GetObjectParameter{if}vARB returns 1577 VERTEX_SHADER_ARB if <obj> references a shader object. If <obj> is not 1578 of type SHADER_OBJECT_ARB, the error INVALID_OPERATION is generated. 1579 1580 If <pname> is OBJECT_ACTIVE_ATTRIBUTES_ARB, GetObjectParameter{if}vARB 1581 returns the number of active attributes. If no active attributes exist, 1582 0 or 0.0f is returned. If <obj> is not of type PROGRAM_OBJECT_ARB the 1583 error INVALID_OPERATION is generated. 1584 1585 If <pname> is OBJECT_ACTIVE_ATTRIBUTE_MAX_LENGTH_ARB, 1586 GetObjectParameter{if}vARB returns the length of the longest active 1587 attribute name, including a null termination. If no active attributes 1588 exist, 0 or 0.0f is returned. If <obj> is not of type PROGRAM_OBJECT_ARB 1589 the error INVALID_OPERATION is generated. 1590 1591 The commands 1592 1593 void GetVertexAttribdvARB(uint index, enum pname, double *params) 1594 void GetVertexAttribfvARB(uint index, enum pname, float *params) 1595 void GetVertexAttribivARB(uint index, enum pname, int *params) 1596 1597 obtain the vertex attribute state named by <pname> for the generic 1598 vertex attribute numbered <index> and places the information in the 1599 array <params>. <pname> must be one of VERTEX_ATTRIB_ARRAY_ENABLED_ARB, 1600 VERTEX_ATTRIB_ARRAY_SIZE_ARB, VERTEX_ATTRIB_ARRAY_STRIDE_ARB, 1601 VERTEX_ATTRIB_ARRAY_TYPE_ARB, VERTEX_ATTRIB_ARRAY_NORMALIZED_ARB, or 1602 CURRENT_VERTEX_ATTRIB_ARB. Note that all the queries except 1603 CURRENT_VERTEX_ATTRIB_ARB return client state. The error INVALID_VALUE 1604 is generated if <index> is greater than or equal to 1605 MAX_VERTEX_ATTRIBS_ARB. 1606 1607 All but the last query return information about generic vertex attribute 1608 arrays. The enable state of a generic vertex attribute array is set by 1609 the command EnableVertexAttribArrayARB and cleared by 1610 DisableVertexAttribArrayARB. The size, stride, type and normalized flag 1611 are set by the command VertexAttribPointerARB. The query 1612 CURRENT_VERTEX_ATTRIB_ARB returns the current value for the generic 1613 attribute <index>. In this case the error INVALID_OPERATION is generated 1614 if <index> is zero, as there is no current value for generic attribute 1615 zero. 1616 1617 Note that all the queries except CURRENT_VERTEX_ATTRIB_ARB return client 1618 state. The error INVALID_VALUE is generated if <index> is greater than 1619 or equal to MAX_VERTEX_ATTRIBS_ARB. 1620 1621 The command 1622 1623 void GetVertexAttribPointervARB(uint index, enum pname, 1624 void **pointer) 1625 1626 obtains the pointer named <pname> for vertex attribute numbered <index> 1627 and places the information in the array <pointer>. <pname> must be 1628 VERTEX_ATTRIB_ARRAY_POINTER_ARB. The INVALID_VALUE error is generated if 1629 <index> is greater than or equal to MAX_VERTEX_ATTRIBS_ARB. 1630 1631Additions to Appendix A of the OpenGL 1.4 Specification (Invariance) 1632 1633 Add to end of Section A.3 (p. 250): 1634 1635 The same vertex shader will produce the same result when run multiple 1636 times with the same input. The wording 'the same shader' means a program 1637 object that is populated with the same source strings, which are 1638 compiled and then linked, possibly multiple times. This program object 1639 is then executed using the same GL state vector. 1640 1641Additions to the AGL/GLX/WGL Specifications 1642 1643 None 1644 1645Interactions with ARB_vertex_program and ARB_fragment_program 1646 1647 Mixing a high level ARB_vertex_shader shader with a low level 1648 ARB_fragment_program shader is allowed. However, a high level 1649 ARB_vertex_shader shader and a low level ARB_vertex_program shader 1650 cannot be active at the same time. 1651 1652Interactions with ARB_vertex_program 1653 1654 Enabling an ARB_vertex_shader shader by issuing the command 1655 UseProgramObjectARB(), with a handle which is not zero, results in any 1656 low level vertex shader to be ignored and overrides the enable 1657 VERTEX_PROGRAM_ARB. Note that the value for VERTEX_PROGRAM_ARB does not 1658 change by installing an ARB_vertex_shader shader. 1659 1660 The following enums and entry points are re-used from 1661 ARB_vertex_program: 1662 1663 MAX_VERTEX_ATTRIBS_ARB 0x8869 1664 VERTEX_ATTRIB_ARRAY_ENABLED_ARB 0x8622 1665 VERTEX_ATTRIB_ARRAY_SIZE_ARB 0x8623 1666 VERTEX_ATTRIB_ARRAY_STRIDE_ARB 0x8624 1667 VERTEX_ATTRIB_ARRAY_TYPE_ARB 0x8625 1668 VERTEX_ATTRIB_ARRAY_NORMALIZED_ARB 0x886A 1669 CURRENT_VERTEX_ATTRIB_ARB 0x8626 1670 VERTEX_ATTRIB_ARRAY_POINTER_ARB 0x8645 1671 VERTEX_PROGRAM_TWO_SIDE_ARB 0x8643 1672 VERTEX_PROGRAM_POINT_SIZE_ARB 0x8642 1673 1674 VertexAttrib*ARB 1675 VertexAttribPointerARB 1676 EnableVertexAttribArrayARB 1677 DisableVertexAttribArrayARB 1678 GetVertexAttrib*ARB 1679 GetVertexAttribPointervARB 1680 1681 The ARB_vertex_program extension is modified to turn undefined vertex 1682 attribute aliasing into non-aliasing. That means that generic vertex 1683 attributes and conventional attributes do not alias on top of each 1684 other. 1685 1686 The following edits are against version 36 of the ARB_vertex_program 1687 specification. 1688 1689 * Section 2.7. Delete the paragraph above Table X.1, Generic and 1690 Conventional Attribute Mappings. Add the following sentence in its 1691 place: "There is no aliasing among generic attributes and 1692 conventional attributes." 1693 * Section 2.7. Delete the paragraph below Table X.1 1694 * Section 2.7. Delete Table X.1. 1695 * Change the last sentence in Section 2.7 to: "The initial values for 1696 all generic vertex attributes are (0, 0, 0, 1)." 1697 * Section 2.8. Edit the paragraph below the pseudo code. Change "As 1698 described in section 2.7, setting a generic vertex attributes ..." 1699 into "As described in section 2.7, there is no aliasing among 1700 generic vertex attributes and conventional attributes". 1701 * Section 2.14.3.1. Delete the first part of the paragraph above Table 1702 X.2.1. The new paragraph becomes "A vertex program will fail to load 1703 if it binds both a conventional vertex attribute and a generic 1704 vertex attribute listed in the same row of Table X.2.1." 1705 1706Interactions with ARB_fragment_program 1707 1708 The following enums are re-used from ARB_fragment_program: 1709 1710 MAX_TEXTURE_IMAGE_UNITS_ARB 0x8872 1711 MAX_TEXTURE_COORDS_ARB 0x8871 1712 1713Interactions with ARB_vertex_blend 1714 1715 If ARB_vertex_blend is supported, and if a vertex shader is active, the 1716 executable version of the vertex shader is used to process incoming 1717 vertex values rather than the fixed functionality vertex blend 1718 processing described in ARB_vertex_blend. In particular, 1719 1720 * Vertex coordinates are not transformed to eye space as described by 1721 the equation in Section 2.10 provided by ARB_vertex_blend. 1722 * Normals are not transformed to eye space as described by the 1723 equations in Section 2.10.2 provided by ARB_vertex_blend. 1724 1725Interactions with ARB_matrix_palette 1726 1727 If ARB_matrix_palette is supported, and if a vertex shader is active, 1728 the executable version of the vertex shader is used to process incoming 1729 vertex values rather than the fixed functionality matrix processing 1730 described in ARB_matrix_palette. In particular, 1731 1732 * Vertex coordinates are not transformed to eye space as described by 1733 the equation in Section 2.10 of the ARB_matrix_palette 1734 specification. 1735 * Normals are not transformed to eye space as described by the 1736 equations in Section 2.10.3 of the ARB_matrix_palette specification. 1737 1738GLX Protocol 1739 1740 The ARB_vertex_program extension defines GLX protocol for the following 1741 rendering commands. 1742 1743 VertexAttrib1fvARB, VertexAttrib1svARB, VertexAttrib1dvARB, 1744 VertexAttrib2fvARB, VertexAttrib2svARB, VertexAttrib2dvARB, 1745 VertexAttrib3fvARB, VertexAttrib3svARB, VertexAttrib3dvARB, 1746 VertexAttrib4fvARB, VertexAttrib4svARB, VertexAttrib4dvARB, 1747 VertexAttrib4ivARB, VertexAttrib4bvARB, VertexAttrib4ubvARB, 1748 VertexAttrib4usvARB, VertexAttrib4uivARB, VertexAttrib4NbvARB, 1749 VertexAttrib4NsvARB, VertexAttrib4NivARB, VertexAttrib4NubvARB, 1750 VertexAttrib4NusvARB, VertexAttrib4NuivARB 1751 1752 The following rendering commands are sent to the server as part of a 1753 glXRender request: 1754 1755 BindAttribLocationARB 1756 1757 2 12+n+p rendering command length 1758 2 265 rendering command opcode 1759 4 CARD32 programObj 1760 4 CARD32 index 1761 n LISTofBYTE name, n = strlen(name) + 1 1762 p unused, p = pad(n) 1763 1764 The following non-rendering commands are added. 1765 1766 GetActiveAttribARB 1767 1768 1 CARD8 opcode (X assigned) 1769 1 179 GLX opcode 1770 2 5 request length 1771 4 GLX_CONTEXT_TAG context tag 1772 4 CARD32 programObj 1773 4 CARD32 index 1774 4 CARD32 maxLength 1775 => 1776 1 1 reply 1777 1 unused 1778 2 CARD16 sequence number 1779 4 m reply length, m = (n+p)/4 1780 4 unused 1781 4 CARD32 n 1782 4 INT32 size 1783 4 ENUM type 1784 8 unused 1785 n LISTofBYTE name, n = length+1 1786 p unused , p = pad(n) 1787 1788 Note that n may be zero, indicating that a GL error occured. 1789 1790 GetAttribLocationARB 1791 1792 1 CARD8 opcode (X assigned) 1793 1 180 GLX opcode 1794 2 (12+n+p)/4 request length, n = strlen(name) + 1 1795 4 GLX_CONTEXT_TAG context tag 1796 4 CARD32 programObj 1797 n LISTofBYTE name 1798 p unused, p = pad(n) 1799 => 1800 1 1 reply 1801 1 unused 1802 2 CARD16 sequence number 1803 4 0 reply length 1804 4 INT32 return value 1805 20 unused 1806 1807 GetVertexAttribdvARB 1808 1809 1 CARD32 opcode (X assigned) 1810 1 181 GLX opcode 1811 2 4 request length 1812 4 GLX_CONTEXT_TAG context tag 1813 4 CARD32 index 1814 4 ENUM pname 1815 => 1816 1 1 reply 1817 1 unused 1818 2 CARD16 sequence number 1819 4 m reply length, m = ((n == 1) ? 0 : 2*n) 1820 4 unused 1821 4 CARD32 n 1822 1823 if (n = 1) this follows: 1824 1825 8 FL0AT64 params 1826 8 unused 1827 1828 otherwise this follows: 1829 1830 16 unused 1831 8*n LISTofFLOAT64 params 1832 1833 The ARB_vertex_program extension defines GLX protocol for the following 1834 non-rendering commands. 1835 1836 GetVertexAttribfvARB and GetVertexAttribivARB. 1837 1838 The following are entirely client-side commands and do not 1839 require GLX protocol. 1840 1841 GetVertexAttribPointervARB, VertexAttribPointerARB 1842 EnableVertexAttribArrayARB, DisableVertexAttribArrayARB 1843 1844Errors 1845 1846 The error INVALID_VALUE is generated by any command that takes one or 1847 more handles as input, and one or more handles are not an object handle 1848 generated by OpenGL. 1849 1850 The error INVALID_VALUE is generated by any of the VertexAttrib*ARB 1851 commands if <index> is equal or greater than MAX_VERTEX_ATTRIBS_ARB. 1852 1853 The error INVALID_VALUE is generated by VertexAttribPointerARB if 1854 <index> is equal or greater than MAX_VERTEX_ATTRIBS_ARB. 1855 1856 The error INVALID_VALUE is generated by VertexAttribPointerARB if <size> 1857 is not one of 1, 2, 3, or 4. 1858 1859 The error INVALID_VALUE is generated by VertexAttribPointerARB if 1860 <stride> is negative. 1861 1862 The error INVALID_VALUE is generated by EnableVertexAttribArrayARB or 1863 DisableVertexAttribArrayARB if <index> is greater than or equal to 1864 MAX_VERTEX_ATTRIBS_ARB. 1865 1866 The error INVALID_OPERATION is generated by any command accessing 1867 texture coordinate processing state if the texture unit number 1868 corresponding to the current value of ACTIVE_TEXTURE is greater than or 1869 equal to the implementation-dependent constant MAX_TEXTURE_COORDS_ARB. 1870 1871 The error INVALID_OPERATION is generated by any command accessing 1872 texture image processing state if the texture unit number corresponding 1873 to the current value of ACTIVE_TEXTURE is greater than or equal to the 1874 implementation-dependent constant MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB. 1875 1876 The error INVALID_OPERATION is generated by GetActiveAttribARB if 1877 <programObj> is not of type PROGRAM_OBJECT_ARB. 1878 1879 The error INVALID_VALUE is generated by GetActiveAttribARB if <index> is 1880 greater than or equal to OBJECT_ACTIVE_ATTRIBUTES_ARB. 1881 1882 The error INVALID_OPERATION is generated by GetAttribLocationARB if 1883 <programObj> is not of type PROGRAM_OBJECT_ARB or if <programObj> has 1884 not been linked successfully. 1885 1886 The error INVALID_OPERATION is generated by BindAttribLocationARB if 1887 <name> starts with the reserved "gl_" prefix. 1888 1889 The error INVALID_VALUE is generated by BindAttribLocationARB if <index> 1890 is equal or greater than MAX_VERTEX_ATTRIBS_ARB. 1891 1892 The error INVALID_OPERATION is generated by BindAttribLocationARB if 1893 <programObj> is not of type PROGRAM_OBJECT_ARB. 1894 1895 The error INVALID_OPERATION is generated by GetObjectParameter{if}vARB 1896 if <pname> is OBJECT_ACTIVE_ATTRIBUTES_ARB or 1897 OBJECT_ACTIVE_ATTRIBUTE_MAX_LENGTH_ARB and <obj> is not of type 1898 PROGRAM_OBJECT_ARB. 1899 1900 The error INVALID_OPERATION is generated by GetObjectParameter{if}vARB 1901 if <pname> is OBJECT_SUBTYPE_ARB and <obj> is not of type 1902 SHADER_OBJECT_ARB. 1903 1904 The error INVALID_OPERATION is generated by GetVertexAttrib*ARB if 1905 <index> is zero and <pname> is CURRENT_VERTEX_ATTRIB_ARB. 1906 1907 The error INVALID_VALUE is generated by GetVertexAttrib*ARB if <index> 1908 is greater than or equal to MAX_VERTEX_ATTRIBS_ARB. 1909 1910 The error INVALID_VALUE is generated by GetVertexAttribPointervARB if 1911 <index> is equal or greater than MAX_VERTEX_ATTRIBS_ARB. 1912 1913New State 1914 Initial 1915 Get Value Type Get Command Value Description Sec. Attribute 1916 --------- ---- ------------------------- ------- ----------- ---- --------- 1917 VERTEX_PROGRAM_TWO_SIDE_ARB B IsEnabled False two-sided color mode 2.13.1 enable 1918 CURRENT_VERTEX_ATTRIB_ARB 16+xR4 GetVertexAttributeARB (0,0,0,1) generic vertex attribute 2.7 current 1919 VERTEX_PROGRAM_POINT_SIZE_ARB B IsEnabled False point size mode 3.3 enable 1920 1921 Table X. New Accessible State Introduced by ARB_vertex_shader 1922 1923 1924 Get Value Type Get Command Initial Value Description Section Attribute 1925 ------------------------------- ------ ------------- ------------- ------------------ ------- ------------ 1926 VERTEX_ATTRIB_ARRAY_ENABLED_ARB 16+xB GetVertex- False vertex attrib 2.8 vertex-array 1927 AttribARB array enable 1928 VERTEX_ATTRIB_ARRAY_SIZE_ARB 16+xZ GetVertex- 4 vertex attrib 2.8 vertex-array 1929 AttribARB array size 1930 VERTEX_ATTRIB_ARRAY_STRIDE_ARB 16+xZ+ GetVertex- 0 vertex attrib 2.8 vertex-array 1931 AttributeARB array stride 1932 VERTEX_ATTRIB_ARRAY_TYPE_ARB 16+xZ4 GetVertex- FLOAT vertex attrib 2.8 vertex-array 1933 AttributeARB array type 1934 VERTEX_ATTRIB_ARRAY_ 16+xB GetVertex- False vertex attrib 2.8 vertex-array 1935 NORMALIZED_ARB AttributeARB array normalized 1936 VERTEX_ATTRIB_ARRAY_POINTER_ARB 16+xP GetVertex- NULL vertex attrib 2.8 vertex-array 1937 AttribPointerARB array pointer 1938 1939 Table X New Accessible Client State Introduced by ARB_vertex_shader 1940 1941 Initial 1942 Get Value Type Get Command Value Description Sec. Attribute 1943 --------- ----- ----------------------- ------------- ----------- ---- --------- 1944 OBJECT_TYPE_ARB Z2 GetObjectParameterivARB SHADER_OBJECT_ARB Type of object 2.15.1 - 1945 OBJECT_SUBTYPE_ARB Z2 GetObjectParameterivARB VERTEX_SHADER_ARB Sub type of object 2.15.1 - 1946 1947 Table X Shader object state. 1948 1949 Initial 1950 Get Value Type Get Command Value Description Sec. Attribute 1951 --------- ----- ----------------------- -------- ----------- ---- --------- 1952 - 0+xZ+ GetActiveAttribARB - Size of active attribute 2.15.2 - 1953 - 0+xZ+ GetActiveAttribARB - Type of active attribute 2.15.2 - 1954 - 0+xcharARB GetActiveAttribARB "" Name of active attribute 2.15.2 - 1955 - 0+xZ GetAttribLocationARB - Location of active generic 2.15.2 - 1956 attribute 1957 512+xR GetUniformARB 0 Uniform value 2.15.3 - 1958 OBJECT_ACTIVE_ATTRIBUTES_ARB Z+ GetObjectParameterivARB 0 Number of active attributes 2.15.2 - 1959 OBJECT_ACTIVE_ATTRIBUTES_ 1960 MAX_LENGTH_ARB Z+ GetObjectParameterivARB 0 Max attribute name length 6.1.12 - 1961 1962 Table X Program object state. 1963 1964 1965New Implementation Dependent State 1966 1967 Minimum 1968 Get Value Type Get Command Value Description Sec. Attr. 1969 --------- ---- ----------- ------- ----------- ---- ----- 1970 MAX_VERTEX_ATTRIBS_ARB Z+ GetIntegerv 16 Number of active 2.15.2 - 1971 vertex attributes 1972 MAX_VERTEX_UNIFORM_COMPONENTS_ARB Z+ GetIntegerv 512 Number of words 2.15.3 - 1973 for vertex shader 1974 uniform variables 1975 MAX_VARYING_FLOATS_ARB Z+ GetIntegerv 32 Number of floats 2.15.4 - 1976 for interpolated 1977 (varying) variables 1978 MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB Z+ GetIntegerv 2 Number of texture image 2.15.5 - 1979 units that can be accessed 1980 by a vertex shader and the 1981 fragment processing part of 1982 OpenGL combined. 1983 MAX_VERTEX_TEXTURE_IMAGE_UNITS_ARB Z+ GetIntegerv 0 Number of separate 2.15.5 - 1984 texture units that can 1985 be accessed by a vertex 1986 shader. 1987 MAX_TEXTURE_IMAGE_UNITS_ARB Z+ GetIntegerv 2 Number of separate 2.15.5 - 1988 texture units that can 1989 be accessed by the fragment 1990 processing part of OpenGL. 1991 MAX_TEXTURE_COORDS_ARB Z+ GetIntegerv 2 Number of texture 2.7 - 1992 coordinate sets 1993 1994 Table X New Implementation Dependent State Introduced by ARB_vertex_shader 1995 1996Sample Usage 1997 1998 GLboolean init(GLcharARB *vertexShader) 1999 { 2000 GLcharARB *pInfoLog; 2001 GLboolean compiled = GL_FALSE; 2002 GLboolean linked = GL_FALSE; 2003 GLint length, maxLength; 2004 2005 // 2006 // Create shader and program objects. 2007 // 2008 ProgramObject = glCreateProgramObjectARB(); 2009 VertexShaderObject = glCreateShaderObjectARB(GL_VERTEX_SHADER_ARB); 2010 2011 length = strlen(vertexShader); 2012 glShaderSourceARB(VertexShaderObject, 1, &vertexShader, &length); 2013 2014 // 2015 // OpenGL made a copy of the shader, we can free our copy 2016 // 2017 free(vertexShader); 2018 2019 // 2020 // Compile the vertex shader, and print out the compiler log file. 2021 // 2022 glCompileShaderARB(VertexShaderObject); 2023 glGetObjectParameterivARB(VertexShaderObject, 2024 GL_OBJECT_COMPILE_STATUS_ARB, &compiled); 2025 2026 glGetObjectParameterivARB(VertexShaderObject, 2027 GL_OBJECT_INFO_LOG_LENGTH_ARB, &maxLength); 2028 pInfoLog = (GLcharARB *) malloc(maxLength * sizeof(GLcharARB)); 2029 glGetInfoLogARB(VertexShaderObject, maxLength, &length, pInfoLog); 2030 2031 printf("%s\n", pInfoLog); 2032 free(pInfoLog); 2033 2034 if (!compiled) { 2035 printf("Compile failed\n"); 2036 return GL_FALSE; 2037 } 2038 2039 // 2040 // Populate the program object with the compiled shader 2041 // 2042 glAttachObjectARB(ProgramObject, VertexShaderObject); 2043 2044 // 2045 // We want the shader object to go away as soon as it is detached 2046 // from the program object it is attached to. We can call delete now 2047 // to achieve that. Note that calling delete on a program object 2048 // will result in all shaders attached to that program object to be 2049 // detached. If delete has been called for the shader object, 2050 // calling delete on the program object will result in the shader 2051 // object being deleted as well. 2052 // 2053 glDeleteObjectARB(VertexShaderObject); 2054 2055 // 2056 // Bind user attributes before linking the program object. 2057 // 2058 glBindAttribLocationARB(ProgramObject, 1, "myFirstAttribute"); 2059 glBindAttribLocationARB(ProgramObject, 2, "mySecondAttribute"); 2060 2061 // 2062 // Link the program and print out the linker log file 2063 // 2064 glLinkProgramARB(ProgramObject); 2065 glGetObjectParameterivARB(ProgramObject, GL_OBJECT_LINK_STATUS_ARB, 2066 &linked); 2067 2068 glGetObjectParameterivARB(ProgramObject, 2069 GL_OBJECT_INFO_LOG_LENGTH_ARB, &maxLength); 2070 pInfoLog = (GLcharARB *) malloc(maxLength * sizeof(GLcharARB)); 2071 glGetInfoLogARB(ProgramObject, maxLength, &length, pInfoLog); 2072 2073 printf("%s\n", pInfoLog); 2074 free(pInfoLog); 2075 2076 // 2077 // If all went well, make the ProgramObject part of the current state 2078 // 2079 if (linked) { 2080 glUseProgramObjectARB(ProgramObject); 2081 return GL_TRUE; 2082 } else { 2083 printf("Link failed\n"); 2084 return GL_FALSE; 2085 } 2086 } 2087 2088 GLhandleARB ProgramObject; 2089 GLhandleARB VertexShaderObject; 2090 2091 void main() 2092 { 2093 GLcharARB *vertexShader; // Holds source for the shader 2094 int location; // Uniform location 2095 float uniformData[3] = {0.0, 1.0. 2.0}; 2096 float vertexData1[3] = {0.0, 1.0. 2.0}; 2097 float vertexData2[3] = {0.0, 1.0. 2.0}; 2098 2099 // 2100 // Fill in the source in vertexShader 2101 // 2102 . 2103 . 2104 2105 // 2106 // Create shader and program objects, setup generic attributes, 2107 // compile the shader object and link the program object and make it 2108 // part of the current state. 2109 // 2110 init(vertexShader); 2111 2112 // 2113 // Get the location of someUniformName in the vertex shader, then 2114 // load its data. 2115 // 2116 location = glGetUniformLocationARB(ProgramObject, "someUniformName") 2117 glUniform3fvARB(location, 1, &uniformData[0]); 2118 2119 // 2120 // Render 2121 // 2122 glBegin(...); 2123 . 2124 . 2125 glVertexAttrib3fvARB(1, vertexData1); 2126 glVertexAttrib3fvARB(2, vertexData2); 2127 . 2128 . 2129 glEnd(); 2130 } 2131 2132Revision History 2133 2134 Revision: 0.5 6/5/2002 2135 - First draft for circulation 2136 Revision: 0.51 2137 - Updated API entry points in the New Procedures and Functions section 2138 - Named and explained all parameters to all API calls 2139 - BindAttributeLocationGL2 and GetActiveAttributesGL2 now have a 2140 length argument for their strings 2141 - Updated the section that describes state required to support vertex 2142 specification 2143 - Changed how standard attribute values are preserved across program 2144 changes (always preserved) 2145 - Changed language describing what happens when too few or too many 2146 attributes are provided 2147 - Updated the list of OpenGL stages that are and are not replaced by a 2148 vertex shader 2149 - Added suggestion for what new vertex array functionality to include 2150 - Added content to the errors section 2151 - Expanded the issues section up to and including number 4. 2152 Revision: 0.52 2153 - Generic vertex attributes, except for vertex arrays, are loaded 2154 using the exact same API commands as ARB_vertex_program uses. Added 2155 discussion of this to the issues section. 2156 - Changed the vertex array section to be TBD. 2157 Revision: 0.53 2158 - Now references V1.0 of the OpenGL Shading Language Specification 2159 - Fixed minor typos 2160 - Accepted by the GL2 working group 2161 Revision: 0.54 10/17/2002 2162 - Removed IsObjectGL2(). 2163 - Expanded GetObjectParameter{if}GL2. Added OBJECT_SUBTYPE_GL2. 2164 Revision: 0.55 10/18/2002 2165 - The index parameter to BindAttributeLocation is now a uint instead 2166 of a ubyte. 2167 - Updated Errors section. 2168 - Added language disallowing mixing GL2 high level vertex shader with 2169 low level ARB vertex program or fragment program. 2170 - Documented interaction with ARB_vertex_blend 2171 Revision: 0.56 10/18/2002 2172 - Added vertex array interface, and added an issue discussing it. 2173 - Changed re-using ARB_vertex_program VertexAttrib*ARB commands issue. 2174 Revision: 0.57 10/21/2002 2175 - Changed VA interface to be exactly the same as ARB_vertex_program 2176 - Replaced MAX_ACTIVE_ATTRIBUTES_GL2 with MAX_VERTEX_ATTRIBS_ARB. 2177 - Went back to a different set of VertexAttribute*GL2 calls (instead 2178 of re-using the ARB_vertex_program ones). 2179 - Updated issues 2 and 3. 2180 - Added code to the sample usage section. 2181 Revision: 0.58 10/23/2002 2182 - Spelled out GetObjectParameter, instead of using 'T value' in its 2183 parameter list. 2184 - Fixed usage of const keyword in GetAttributeLocations. 2185 - Added GetVertexAttribute{ifd}vGL2 2186 - Added GetVertexAttribPointervARB 2187 - Updated interactions with ARB_vertex_program section 2188 - Updated errors section. 2189 - Moved shader resources section to GL2_shader_objects. 2190 - Updated chapter 5, Display Lists. 2191 Revision: 0.6 10/29/2002 2192 - Fixed typos. 2193 - Changed Issue three to unresolved. 2194 - Added issue number four. 2195 - Second distribution to the GL2 working group. 2196 - Now written against the OpenGL 1.4 specification. 2197 Revision: 0.61 11/26/2002 2198 - Minimum for MAX_VARYING_FLOATS reduced from 40 to 32. 2199 - Allowed mixing of a high level GL2 vertex shader with a low level 2200 ARB_fragment_program shader. 2201 Revision: 0.62 12/04/2002 2202 - Resolved Issue 5 the same way as ARB_vertex_program. As a result, 2203 added language to section 5.1. 2204 Revision: 0.63 1/29/2003 2205 - Marked issues 2 and 4 as unresolved. 2206 - Updated list of contributors. 2207 - Added issue 6, 7, 8, 9. 2208 - Updated the 'state required' section of section 2.7 and 2.8. 2209 - Renamed 'user-defined attribute' to 'generic attribute' to match 2210 ARB_vertex_program terminology. 2211 - Added language to section 2.13.2 and 2.13.3 about material and 2212 ColorMaterial handling when a GL2 shader is active. 2213 - Added wording to section 3.10 for PointSize and Fog. 2214 - Added a two sided lighting enable to section 2.13.1. 2215 - Added wording to explain how raster pos works, section 2.12 2216 - Added and resolved issue 10. Added wording to section 3.9. 2217 - Added issue 11. 2218 - Third working group distribution. 2219 Revision: 0.64 2/03/2003 2220 - Added VERTEX_PROGRAM_TWO_SIDE_ARB to the new tokens section. 2221 - Resolved issue 6, 7, 8, 10, 11 and updated the spec to reflect this. 2222 - Added wording to section 2.11, clipping 2223 - Updated the New State section 2224 - Updated the New Tokens section 2225 - Changed the VertexAttribute*GL2 entry points to VertexAttrib*ARB, 2226 which are the same entry points as defined in ARB_vertex_program. 2227 - Made generic attribute zero provoke a vertex 2228 - Resolved issue 2,3 and 4. Edited the interactions with 2229 ARB_vertex_program section to reflect this. 2230 - Consistently used 'conventional attributes' instead of 'standard 2231 attributes'. 2232 - Tried to clarify the wording in section 2.15.2 regarding attribute 2233 tracking. 2234 - Updated the Errors section 2235 - Added issue 12, texture access 2236 - Fourth working group distribution. 2237 Revision: 0.65 2/10/2003 2238 - Updated section 5.4, commands excluded from a display list. 2239 - Added section 2.15.6, position invariance. Renamed the old section 2240 2.15.6 to 2.15.7. 2241 - Added a discussion section to issue 1, invariance 2242 - Updated Appendix A, invariance 2243 - Added a proposed resolution to issue 12. Related to that are the new 2244 issues 13, 14 and 15. 2245 - Added language to sections 2.7, 2.8, 2.10.2 and 6.1.2 to support 2246 texture access. 2247 - Added a new section 2.15.5 to support texture access. 2248 - Added MAX_FRAGMENT_TEXTURE_UNITS_GL2, MAX_VERTEX_TEXTURE_UNITS_GL2 2249 and MAX_TEXTURE_IMAGE_UNITS_GL2. 2250 - Fifth working group distribution 2251 Revision: 0.66 2/11/2003 2252 - Added issue 16. Position invariance with respect to user clipping 2253 and closed it. 2254 - Closed issue 1. 2255 - Updated 'implementation dependent state' section. 2256 - Renamed MAX_VERTEX_UNIFORM_FLOATS_GL2 to 2257 MAX_VERTEX_UNIFORM_WORDS_GL2. 2258 - Consistently used 'texture coordinate set' instead of 'texture 2259 coordinate unit'. 2260 - Distributed to HP 2261 Revision: 0.67 2/13/2003 2262 - Added wording about interaction with ARB_matrix_palette. Same 2263 applies as the interaction with ARB_vertex_blend. 2264 - Sixth working group distribution 2265 Revision: 0.68 2/20/2003 2266 - Renamed MAX_FRAGMENT_TEXTURE_UNITS_GL2 to 2267 MAX_TEXTURE_IMAGE_UNITS_ARB 2268 - Renamed MAX_VERTEX_TEXTURE_UNITS_GL2 to 2269 MAX_VERTEX_TEXTURE_IMAGE_UNITS_GL2 2270 - Renamed MAX_TEXTURE_IMAGE_UNITS_GL2 to 2271 MAX_COMBINED_TEXTURE_IMAGE_UNITS_GL2 2272 - Added wording to issue 12) explaining how LOD calculation works. 2273 - Updated section 2.15.5 with respect to LOD calculations. 2274 - Updated section 2.15.5. Accessing the same texture image unit from a 2275 vertex shader and fragment processing counts as using two image 2276 units against the limit MAX_COMBINED_TEXTURE_IMAGE_UNITS_GL2. 2277 - Updated the interactions with ARB_vertex and fragment_program 2278 section. 2279 - Added the 'interactions with ARB_fragment_program' section. 2280 Revision: 0.69 2/27/2003 2281 - Updated the interactions with ARB_vertex and fragment_program 2282 section, again. 2283 - Updated the texture access section 2.15.5. It is more carefully 2284 worded and references the relevant texturing sections in chapter 3. 2285 - Closed issues 2, 3 and 4. Attribute handling. 2286 - Closed issue 9 and modified section 3.3 to reflect the resolution. 2287 - Updated texture coordinates to full citizens with respect to their 2288 dynamic range. Section 2.1.1. ARB_fragment_program already does 2289 this. 2290 Revision: 0.70 3/3/2003 2291 - Treatment of PointSize wasn't complete with respect to point 2292 attenuation and point fade. Section 3.3. 2293 - Added issue 17 explaining what happens to point distance attenuation 2294 and point fade. 2295 - Texture access now takes the texture object and texture unit bias 2296 into account as well. See sections 2.15.5 and Section 3.8.8. 2297 - Fixed numerous small typos and tried to clarify wording here and 2298 there. 2299 - It is no longer a requirement to load and/or compile a vertex shader 2300 before specifying its attribute bindings. 2301 - Added section 2.15.8 Required State. 2302 - Rewrote the overview section. 2303 Revision: 0.71 3/3/2003 2304 - Upgraded colors to be full floating point citizens, section 2.1.1. 2305 - Added language about undefined results if a vertex shader does not 2306 clamp when fixed-function fragment processing is used or an 2307 ARB_fragment_program target is active. Section 2.15.7. 2308 - Added issue number 18, explaining color clamping and conversion to 2309 fixed-point. 2310 Revision: 0.72 3/31/2003 2311 - Updated PointSize. Its value is undefined unless written by the 2312 shader. 2313 - Changed issue 9. We will have a point size enable after all. 2314 - Updated IP Status section to point to the contributors agreement. 2315 - Renamed BindAttributeLocation to BindAttribLocation to be in line 2316 with the rest of the vertex attribute naming (VertexAttrib etc). 2317 - Renamed GetActiveAttributes to GetActiveAttribs for the same reason. 2318 Revision: 0.73 4/9/2003 2319 - Added to the example usage section. Shows how to use 2320 GetActiveAttribs. 2321 - GetActiveAttribs no longer returns the length of the strings. They 2322 are always null terminated, a length parameter is no longer needed. 2323 - GetActiveAttribs no longer returns a Boolean. It was never set. 2324 - Added life time to the pointer returned by GetActiveAttribs. 2325 - GetActiveAttribs now also returns the type of each attribute. 2326 - It is no longer a link error if generic attributes are not bound yet 2327 using BindAttribute. 2328 - Renamed "handle" to "handleGL2". 2329 - Updated section 2.15.8 2330 Revision: 0.74 4/17/2003 2331 - Added issues 19, 20 and 21. 2332 - Re-ordered section 2.15.2. Vertex Attributes 2333 - The GL will assign an index for an attribute variable in a vertex 2334 shader. This index is queriable using the new GetAttribLocationGL2 2335 command. 2336 - Clarified BindAttribLocationGL2. It can override any binding 2337 assigned by the GL. It can be called at any time. Binding takes 2338 effect once a program object is (re)linked. 2339 - Added text that clarifies how to load and bind attributes declared 2340 as a matrix to section 2.7 and 2.15.2. 2341 - Clarified issues 1, 7, 8, 9, 11, 18 based on Pat's feedback. I 2342 didn't change their resolution, just tried to make them clearer. 2343 - Numerous other small clarifications based on Pat's feedback. 2344 Revision: 0.75 4/18/2003 2345 - Made BindAttribLocationGL2 display-listable. 2346 - Query of active attributes is still allowed after a failed link. 2347 After all the link could fail because there were too many active 2348 attributes. 2349 - Added a size parameter to GetActiveAttribsGL2. 2350 - Clarified when the linker can generate errors based on incorrect 2351 user bindings of attributes. 2352 - More clarification's based on Pat's feedback, most of them in 2353 section 2.15.2 Vertex Attributes. 2354 - Re-did section 2.13.1, two sided lighting with a vertex shader 2355 enabled. 2356 - Refined the section about aliasing attributes in section 2.15.2. 2357 - Changed MAX_VERTEX_UNIFORM_WORDS_GL2 to 2358 MAX_VERTEX_UNIFORM_COMPONENTS_GL2 2359 Revision: 0.76 4/21/2003 2360 - Changed a few occurances of "char" to charGL2. 2361 - GetAttribLocation and BindAttribLocation no longer take a length, 2362 just like GetUniformLocation. 2363 - Updated the example section to reflect the latest API changes. 2364 - Changed the location of the Contributors License to a publicly 2365 accessible place on www.3dlabs.com. 2366 - Version approved by the ARB-GL2 working group. 2367 Revision: 0.77 5/09/2003 2368 - Fixed issues 17 and 19 where some language was out of sync with the 2369 actual resolution in the spec. 2370 - Change 'zero' to NULL in the text describing GetActiveAttribsGL2. 2371 - Fixed typo in one of the comments in the example section and in the 2372 revision history. 2373 - Removed the VertexAttribMatrix*GL2 entry points from the 'new 2374 procedures and functions' section. These were never intended to be 2375 part of the spec. 2376 - Added Kent Lin to the list of contributors. 2377 - Added state tables. Not all state defined in the spec was present in 2378 the tables. 2379 - Section 2.15.8, required state for program objects was incorrect. 2380 - Clarified the lifetime of the pointers returned by 2381 GetActiveAttribsGL2. 2382 - Clarified that you need to pass in three NULL pointers to 2383 GetActiveAttribsGL2, to only get the count of active attributes. 2384 - Listed (already defined in the Errors section) error conditions to 2385 GetActiveUniformsGL2, GetAttribLocationGL2 and 2386 BindAttribLocationGL2. 2387 - Updated example section to reflect the latest API names. 2388 - The first error rule should have been INVALID_VALUE (consistent with 2389 GL2_shader_objects). 2390 - Added Jon Leech, Evan Hart, Benjamin Lipchak and Jeremy Sandmel to 2391 the list of contributors. 2392 - Removed the two rules from Appendix A (invariance) and updated Issue 2393 1 to reflect this. Added the same repeatability rule as the fragment 2394 shader. 2395 - Assigned enum values. 2396 Revision: 0.78 5/15/2003 2397 - Deleted reference to AppendShader (this call no longer exist). 2398 - Renamed all GL2 occurrences to ARB. 2399 - Added SHADER_OBJECT_ARB to the list of new tokens. 2400 - Fixed typos. 2401 - Added to the contributors list. If anyone is still left out, let 2402 Bill Licea Kane, Jon Leech or myself know. 2403 Revision: 0.79 6/24/2003 2404 - Changed MAX_VERTEX_TEXTURE_IMAGE_UNITS minimum value to 0 (from 1). 2405 Updated issue 15 to reflect this. 2406 - Updates issue 18 (color clamping). As a result, updated Section 2407 2.1.1 and 2.15.7. 2408 - Changed GetActiveAttrib to no longer return a pointer to GL memory. 2409 This call now returns data for one active attribute, instead of all 2410 active attributes. As a results, added error conditions to the 2411 Errors section. 2412 - BindAttribLocationARB is not display-listable. 2413 - Added OBJECT_ACTIVE_ATTRIBUTE_MAX_LENGTH_ARB and 2414 OBJECT_ACTIVE_ATTRIBUTES_ARB as a queriable parameter to 2415 GetObjectParameter{if}vARB. As a result, changed the New State 2416 section, and the Required State section. 2417 - Ordered the Errors section in the order of API commands described in 2418 the spec. Also split errors in one error per API command. 2419 - Updated the examples section. 2420 - General language cleanup. 2421 - ARB approved version. 2422 Revision: 0.80 3/16/2004 2423 - Section 2.15.5 changed that zero or more, and not one or more, 2424 texture image units are available to a vertex shader. 2425 - Section 2.15.5 Added language (copied from the fragment shader spec) 2426 about samplers and depth textures and undefined behavior. Also 2427 copied the language that specifies what happens when a texture 2428 object is incomplete. Also copied the language that specifies what 2429 stays the same with texture operations. 2430 - Added ARB extension number (31) and edited the status paragraph. 2431 - Removed SHADER_OBJECT_ARB, OBJECT_TYPE_ARB and OBJECT_SUBTYPE_ARB 2432 tokens from the New Tokens section. They are already defined in 2433 ARB_shader_objects. Also removed references to these in Chapter 6, 2434 GetObjectParameter{fi}v and the Errors section. 2435 - Changed MAX_COMBINED_TEXTURE_IMAGE_UNITS_ARB to 2 (from 3). 2436 - Changed a typo: OBJECT_ACTIVE_ATTRIBUTES_MAX_LENGTH_ARB should be 2437 OBJECT_ACTIVE_ATTRIBUTE_MAX_LENGTH_ARB (without the 'S') 2438 - Specified that the return parameters for GetACtiveAttribARB are 2439 unmodified when a GL error occurs. 2440 - Section 2.13.8. Varying variables, not generic vertex attributes, are 2441 clipped. 2442 - GetAttribLocationARB() in the 'New Procedures and Functions' section 2443 takes a handleARB not a handle. 2444 - Explained the meaning of the parameters to GetVertexAttrib*ARB. 2445 - Added that the current values of secondary color, fog coord and generic 2446 attributes are undefined after a call to DrawArrays or DrawElements, if 2447 the respective arrays are enabled. 2448 - Added resolution 22. 2449 - Added a paragraph to section 2.15.2 that makes it a link error to have 2450 both gl_Vertex an a generic attribute bound to index zero be used in a 2451 vertex shader. 2452 Revision: 0.81 3/30/2004 2453 - Removed ARB from DEPTH_COMPONENT_ARB 2454 - GetObjectParameter{if}vARB instead of GetObjectParameter{fi}vARB. 2455 - Updated the version of the Shading Language document referenced to 2456 100.53 2457 - Updated description of MAX_VERTEX_UNIFORM_COMPONENTS_ARB in the 2458 state tables. 2459 - Moved spec language related to texture operations not affected by a 2460 vertex shader to issue 23. 2461 - ARB-GL2 workgroup approved version. 2462 Revision 0.82, 12/12/2006 2463 - Fixed spelling of glGetObjectParameterivARB in sample code. 2464 Revision 0.83 12/14/2009 2465 - Added GLX protocol. 2466 2467