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