1Name 2 3 ARB_shader_objects 4 5Name Strings 6 7 GL_ARB_shader_objects 8 9Contributors 10 11 Kurt Akeley 12 Allen Akin 13 Dave Baldwin 14 Bob Beretta 15 Pat Brown 16 Matt Craighead 17 Cass Everitt 18 Mandar Godse 19 Evan Hart 20 Phil Huxley 21 Deron Dann Johnson 22 James Jones 23 Dale Kirkland 24 John Kessenich 25 Steve Koren 26 Jon Leech 27 Bill Licea-Kane 28 Barthold Lichtenbelt 29 Kent Lin 30 Benjamin Lipchak 31 Rob Mace 32 Michael McCool 33 Teri Morrison 34 Jeremy Morris 35 Glenn Ortner 36 Ian Romanick 37 Randi Rost 38 Jeremy Sandmel 39 Folker Schamel 40 Mik Wells 41 42Contact 43 44 Barthold Lichtenbelt, 3Dlabs, Inc. (barthold 'at' 3dlabs.com) 45 Randi Rost, 3Dlabs, Inc. (rost 'at' 3dlabs.com) 46 47Notice 48 49 Copyright (c) 2003-2013 The Khronos Group Inc. Copyright terms at 50 http://www.khronos.org/registry/speccopyright.html 51 52Specification Update Policy 53 54 Khronos-approved extension specifications are updated in response to 55 issues and bugs prioritized by the Khronos OpenGL Working Group. For 56 extensions which have been promoted to a core Specification, fixes will 57 first appear in the latest version of that core Specification, and will 58 eventually be backported to the extension document. This policy is 59 described in more detail at 60 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 61 62IP Status 63 64 As described in the Contributor License, which can be found at 65 http://www.3dlabs.com/support/developer/ogl2/specs/3dlabs_contributor.pdf. 66 67Status 68 69 Complete. Approved by the ARB on June 11, 2003. 70 Updated revision 0.89 approved by the ARB on June 17, 2004. 71 72Version 73 74 Last Modified Date: December 14, 2009 75 Author Revision: 0.90 76 77Number 78 79 ARB Extension #30 80 81Dependencies 82 83 OpenGL 1.0 is required. 84 85 This extension is written against version 1.10 of the OpenGL Shading 86 Language Specification. 87 88 The extension is written against the OpenGL 1.4 Specification. 89 90Overview 91 92 This extension adds API calls that are necessary to manage shader 93 objects and program objects as defined in the OpenGL 2.0 white papers by 94 3Dlabs. 95 96 The generation of an executable that runs on one of OpenGL's 97 programmable units is modeled to that of developing a typical C/C++ 98 application. There are one or more source files, each of which are 99 stored by OpenGL in a shader object. Each shader object (source file) 100 needs to be compiled and attached to a program object. Once all shader 101 objects are compiled successfully, the program object needs to be linked 102 to produce an executable. This executable is part of the program object, 103 and can now be loaded onto the programmable units to make it part of the 104 current OpenGL state. Both the compile and link stages generate a text 105 string that can be queried to get more information. This information 106 could be, but is not limited to, compile errors, link errors, 107 optimization hints, etc. Values for uniform variables, declared in a 108 shader, can be set by the application and used to control a shader's 109 behavior. 110 111 This extension defines functions for creating shader objects and program 112 objects, for compiling shader objects, for linking program objects, for 113 attaching shader objects to program objects, and for using a program 114 object as part of current state. Functions to load uniform values are 115 also defined. Some house keeping functions, like deleting an object and 116 querying object state, are also provided. 117 118 Although this extension defines the API for creating shader objects, it 119 does not define any specific types of shader objects. It is assumed that 120 this extension will be implemented along with at least one such 121 additional extension for creating a specific type of OpenGL 2.0 shader 122 (e.g., the ARB_fragment_shader extension or the ARB_vertex_shader 123 extension). 124 125Issues 126 127 1) What to do if part of a shader pair is not present? 128 129 DISCUSSION: There are several shader types that go together. For 130 example, a VERTEX_SHADER and a FRAGMENT_SHADER form a pair that is part 131 of the geometry pipeline. It is not required to supply both shader types 132 of a pair in a program object. 133 134 RESOLUTION: If one or the other of a pair is not present in the program 135 object, OpenGL will substitute the standard 1.4 OpenGL pipeline for the 136 one not present. The most likely place for this substitution to happen 137 is the link stage. Note that it is defined elsewhere exactly what part 138 of the OpenGL 1.4 pipeline a shader replaces. 139 140 2) Should source code string passed to ShaderSourceARB be null 141 terminated? 142 143 DISCUSSION: Source code strings should not be required to end with the 144 byte 0. This is a programming language dependent concept, and interferes 145 with loading source code out of files. (Memory mapping read-only files 146 leaves no ability to add a 0 at the end without an extra copy). 147 Development of shaders can be from files, not necessarily from embedded 148 source. If null termination was required a shader's source code would be 149 read from a file, based on an address and a length, then get copied to 150 add a 0 on, then are passed to the compiler which promptly goes and 151 finds the 0, in order to get back to an address and a length. That is 152 all useless work. 153 154 RESOLUTION: It is allowed, but not required, to have a null termination 155 at the end of the string. If the string is null terminated, OpenGL can 156 find out the length of the string, and the length parameter passed in 157 can be set to negative one. 158 159 3) Should the string passed in to GetUniformLocationARB be null 160 terminated? 161 162 DISCUSSION: It is not very likely that this will be a memory mapped 163 file, therefore null termination can be assumed. 164 165 RESOLUTION: Yes. 166 167 4) Should the string returned by GetInfoLog be null terminated? 168 169 DISCUSSION: In this case it is useful to have the info string be null 170 terminated, so it can be passed to printf() directly. All other strings 171 returned by the GL are also null terminated. 172 173 RESOLUTION: YES 174 175 5) Should GetInfoLog also return the length of the string? 176 177 DISCUSSION: This applies to an older version of GetInfoLog, but is no 178 longer applicable. 179 180 RESOLUTION: N/A 181 182 6) Do we need a new GLcharARB data type to handle input strings? 183 184 DISCUSSION: Currently there is no precedence of passing in strings into 185 OpenGL. This exposes a deficiency in OpenGL data types. In C++ a literal 186 string is of type char. OpenGL only has GLubyte and GLbyte data types, 187 defined as being unsigned char and signed char respectively. This means 188 that it is not possible to pass a literal string to OpenGL using either 189 GLubyte or GLbyte. For example, GetUniformLocationARB(programObj, 190 "Offset") needs to have the prototype GetUniformLocationARB(handleARB 191 obj, const char *string). 192 193 RESOLUTION: YES 194 195 7) Do we load uniforms using their string representation? 196 197 DISCUSSION: Loading uniforms is still performance sensitive, although 198 not as much as vertex attributes. Passing in a string into the load 199 uniform command seems too big of a performance hit. Every time the load 200 is called the string needs to be parsed and the location for the data 201 computed. It is better to move this performance cost outside the load 202 uniform command into GetUniformLocationARB. 203 204 RESOLUTION: NO. 205 206 8) Should Uniform*ARB take a program object as a parameter? 207 208 DISCUSSION: Again, this is a performance issue. If it does, the object 209 passed in needs to be validated for every uniform loaded. Instead, move 210 this validation cost outside the uniform command, and have the uniform 211 command modify uniforms for the currently in use program object (Set by 212 UseProgramObjectARB). The validation cost is now much lower. The program 213 object is validated once, when calling UseProgramObjectARB. 214 215 RESOLUTION: NO. 216 217 9) Should uniform values be state per program object? 218 219 DISCUSSION: Should values loaded for uniforms be kept in a program 220 object, so that they are retained across program object switches? This 221 is application friendly. However, loading uniforms becomes a bit more of 222 a heavy weight operation because the OpenGL implementation now has to 223 store its values with the program object, and reload when the program 224 object is made current, even if the previous program object already had 225 the same uniform values loaded. 226 227 RESOLUTION: YES. We don't want to force an application to re-load its 228 uniforms every time a program object is used. 229 230 10) Should the name space for uniforms be global per program object? 231 232 DISCUSSION: If one shader object references a uniform called "foo" and 233 another shader object, attached to the same program object, also 234 references "foo", are those shaders referencing the same uniform? If 235 they do not reference the same uniform values, uniforms now need to be 236 state per shader object and loaded per shader object. Also, if a vertex 237 shader references "foo" and the accompanying fragment shader also 238 references "foo", it would make sense to expect those to be the same 239 uniform reference. 240 241 RESOLUTION: YES. 242 243 11) What to do if no value is loaded for a uniform? 244 245 DISCUSSION: A program object can be used and rendering commenced without 246 loading values for all the uniforms referenced in its shader objects. 247 What to do in this case? Note that the values of the uniforms are state 248 belonging to the program object. Once loaded, these values are reused 249 whenever the program object is in use again. Should uniforms have an 250 initial value? 251 252 RESOLUTION: Uniforms are initialized to zero. 253 254 12) Should it be allowed to load uniforms in a display list? 255 256 DISCUSSION: Doing so will make the display list tied to a program 257 object. The location passed in to the load uniform commands is program 258 object specific. However, this can still be useful for some 259 applications. If a program object is in use at CallList time which does 260 not match that display list, then all bets are off. See also issue 30. 261 262 RESOLUTION: YES 263 264 13) Do we need uniforms that are local to a program object and uniforms 265 that are globally accessible by all program objects? 266 267 DISCUSSION: ARB_vertex_program has this functionality. It seems 268 convenient to be able to set a uniform once, and have its value be 269 accessible across many shaders (for example, a uniform used to set a 270 light position). This type of global uniform could be a performance win 271 as well, its value does not have to be cached by OpenGL per program 272 object, and re-loaded at every program object switch. 273 274 RESOLUTION: This is useful, but for this version of the spec this 275 functionality is deferred. 276 277 14) Do we need INT, FLOAT and BOOL versions of the load uniform 278 commands? 279 280 DISCUSSION: There are two types to keep separate. The type the uniform 281 is declared in the shader, and the type of the data the application uses 282 for uniform values. There are three basic uniform types that can be 283 declared in a shader: Float, Int and Bool. Thus one can envision an API 284 where the uniform type is encoded in the API name, besides the 285 application's data type. For example, UniformInt3iv(). Where the word 286 'Int' encodes the uniform type, and 'iv' the user input data type. On 287 the other hand, the uniform type information is known to the GL, and 288 therefore encoding it in the API name is redundant. 289 290 RESOLUTION: We won't encode the uniform type in the API name. 291 292 15) There is the potential for a huge explosion of load uniform 293 commands, what to do? 294 295 DISCUSSION: We need to be able to load a vec1, vec2, vec3, or vec4, or 296 arrays of vec1, arrays of vec2, arrays of vec3 or arrays of vec4. 297 Furtheremore, there is a need to also load 2x2, 3x3 and 4x4 matrices, 298 and arrays of 2x2, arrays of 3x3 and arrays of 4x4 matrices. The input 299 values to the load uniforms commands can (traditional OpenGL) come in 300 bytes, shorts, ints, floats, doubles and unsigned bytes, unsigned shorts 301 and unsigned ints. 302 303 RESOLUTION: A suggested subset is in the New Procedures and Functions 304 section below. 305 306 16) Should a special INVALID_HANDLE for the data type handleARB be 307 provided, or is 0 sufficient? 308 309 DISCUSSION: 0 is fine. There are less code defects if code compares to 310 zero than some invalid handle that is defined to zero anyway. 311 Applications should not compare to NULL, since NULL is not necessarily 312 defined to be zero in C, only in C++. Besides, a handleARB is an 313 integer. 314 315 RESOLUTION: YES. 316 317 17) What happens if the currently in use program object is re-linked by 318 calling LinkProgramARB? 319 320 DISCUSSION: Consider that the currently in use program object has a 321 uniform named "foo". The application changed some code around in that 322 program object, and still has a uniform named "foo", then calls 323 LinkProgramARB. After this link call the location of "foo" does not have 324 to be the same as before the link call. If LinkProgramARB does not imply 325 a call to UseProgramObjectARB, then a call to Uniform*ARB to load a 326 value for "foo" is ill defined. In this case, does the application use 327 the old location of "foo" or the new location? 328 329 It is consistent with other parts of OpenGL to have updates to an object 330 take effect after the update without issuing another command to make the 331 update active, for example the TexSubImage* commands. 332 333 RESOLUTION: The re-linked program will be used automatically, without 334 requiring a new call to UseProgarmObjectARB. 335 336 18) Should object handles be allocated by the application or by OpenGL? 337 338 DISCUSSION: For current OpenGL objects such as textures and display 339 lists, object Ids can be assigned by the application. The Id name space 340 is unique for texture objects and display lists. This resulted in a 341 different API for generating and managing texture Ids or Display List 342 Ids. 343 344 It is not desirable to keep the same mechanism for general object 345 management. It prevents the definition of generic operations on objects 346 such as deletion and querying. It prevents the OpenGL implementation 347 from managing the name space the way it sees fit. It is much more common 348 for the underlying library to allocate and manage handles and thereby 349 keep control of the name space. It can make using a third party supplied 350 library harder or even impossible. 351 352 RESOLUTION: Object handles should be allocated and its name space 353 managed by OpenGL, not by the application. 354 355 19) Should a handle be opaque to the application? 356 357 DISCUSSION: A handle is only read and written by OpenGL. Therefore the 358 interpretation of the value of the handle does not need to be exposed to 359 the application. However, we will expose how a handle is implemented. 360 Certain implementation choices for handles, like a pointer, are 361 discouraged. The practical solution seems to be to make a handle an 362 integer. 363 364 RESOLUTION: YES. 365 366 20) Do we need a way to get the source code back from a shader object? 367 368 DISCUSSION: To stay with the OpenGL philosophy that any state that can 369 be set also be queried, we need such a get. This function will return 370 the last set of strings stored in a shader object. Note that this set of 371 strings is not necessarily the same as the set of strings that compiled 372 and linked into program object currently in use. 373 374 RESOLUTION: YES, this is achieved through GetShaderSourceARB. 375 376 21) Are the limits on all resources an executable uses queriable and 377 known to the application? 378 379 DISCUSSION: Various proposals have been discussed. One very important 380 consideration is to end up with a specification that provides 381 application portability (e.g., ISVs do not need to support multiple 382 rendering back ends in order to run on all the different flavors of 383 hardware). ISVs definitely would prefer the specification to say that 384 the OpenGL Shading Language implementation is responsible for ensuring 385 that all valid shaders must run. 386 387 RESOLUTION: Resources that are easy to count (number of uniforms 388 available to a vertex shader, number of uniforms available to a fragment 389 shader, number of vertex attributes, number of varyings, number of 390 texture units) will have queriable limits. The application is 391 responsible for working within these externally visible limits. The 392 OpenGL Shading Language implementation is responsible for virtualizing 393 resources that are not easy to count (for example, the number of machine 394 instructions in the final executable, number of temporary registers used 395 in the final executable, etc.). The expectation is that for any 396 practical application an executable (generated by the link stage) will 397 run. 398 399 22) Should a higher level shading language be layered on top of OpenGL 400 instead of being designed to fit within OpenGL? 401 402 DISCUSSION: In the current design, the OpenGL Shading Language is 403 integrated into OpenGL and just provides alternative methods to the 404 state controlled pipeline of OpenGL 1.4. The Stanford approach is to 405 layer their shading language on top of OpenGL. This has some advantages 406 and disadvantages that will become apparent when the differences are 407 examined. 408 409 The Stanford approach uses a higher abstraction level. This helps with 410 writing some kinds of programs where the abstractions match the problem 411 domain. For example treating lights and surfaces as abstract entities 412 makes some 3D graphics operations easier, however OpenGL is now being 413 used for video and image processing where this abstraction is largely 414 irrelevant. Similarly many games have shunned lighting via traditional 415 means and use textures (light maps) instead. 416 417 There is nothing in the OpenGL Shading Language or bindings that prevent 418 higher levels of abstractions from being layered on top of a 419 programmable OpenGL. We also wish to keep the overall abstraction level 420 of OpenGL at its current level. 421 422 The Stanford approach also provides for different computational 423 frequencies. By having the higher levels of abstraction where one 424 program defines the current graphics operation in total allows the 425 compiler to separate out the parts that need to run at the primitive 426 group level, primitive level, vertex level and fragment level. The 427 compiler can therefore generate the code to run on the CPU, vertex 428 processor and fragment processor as appropriate. This is obviously more 429 complicated to implement than having the programmer specify the programs 430 to run on each part of the pipeline (although some hints are still 431 required by the Stanford language), although this does make the 432 virtualization of the hardware easier as the compiler has the overall 433 view. 434 435 The major disadvantage of this is that it forces more intrusive changes 436 to OpenGL to support the clear delineation of the primitives, vertices 437 and fragment operations. Many of the core OpenGL features have been 438 replaced. 439 440 An advantage of the current approach is that the look and feel of OpenGL 441 1.4 is maintained and it allows a graceful mix and match approach during 442 the transition period from fixed functionality to full programmability. 443 444 This is not a criticism of the Stanford work, as they had no choice but 445 to layer on top of OpenGL. 446 447 RESOLUTION: The OpenGL Shading Language should be built into OpenGL, and 448 not layered on top. It is also noted that if this is not the case, 449 OpenGL should still have a standard shading language. 450 451 23) Should an error be set if a glUseProgramObjectARB call is made on a 452 program object that has not been successfully linked? 453 454 DISCUSSION: This was an issue when UseProgramObject returned a Boolean 455 indicating success or failure. However, it no longer does, thus an error 456 has to be generated. 457 458 RESOLUTION: YES 459 460 24) Do we need a way to get object code back, just like the model of C 461 on host processors? 462 463 DISCUSSION: Lots in email on the arb-gl2 mailing list. This is about 464 lowest-level, machine specific code that may not even be portable within 465 a family of cards from the same vendor. One main goal is to save 466 compilation time. There seems to be general consensus that this has 467 merit. 468 469 RESOLUTION: This is an interesting capability to have, but will be 470 deferred to the next release or could be added as a separate extension. 471 472 25) How are samplers used to access textures? 473 474 DISCUSSION: Samplers are special uniforms used in the OpenGL Shading 475 Language to identify the texture object used for each texture lookup. 476 The value of a sampler indicates the texture image unit being accessed. 477 The type of the sampler identifies the target on that texture image 478 unit. The texture object bound to that texture image unit's target is 479 then used for the texture lookup. For example, a variable of type 480 sampler2D selects target TEXTURE_2D on its texture image unit. Binding 481 of texture objects to targets is done as usual with BindTexture. 482 Selecting the texture image unit to bind is done as usual with 483 ActiveTexture. 484 485 The location of a sampler needs to be queried with 486 GetUniformLocationARB, just like any uniform variable, and its value 487 needs to be set by calling Uniform1i{v}ARB. 488 489 In the future, sampler types might allow for binding a texture object 490 directly, instead of binding to a texture image unit first, to get to a 491 texture object. 492 493 RESOLUTION: Resolved 494 495 26) Do we need a validation command as a developers aid? 496 497 DISCUSSION: The LinkProgramARB command will check if the code in all 498 shaders in the program object will link. It will catch things like 499 having too many active samplers, a mismatch between varyings in a vertex 500 and fragment shader, etc. However, it will not check for any errors 501 related to the values of uniforms or inconsistent OpenGL state that 502 would result in undefined behavior or worse, prevent a program object 503 from executing. A validation command could check for things like a 504 mismatch between a shadow texture lookup and no TEXTURE_COMPARE_MODE 505 set. Or check for values of samplers being out of range. Or check for 506 samplers of different types being used to access the same texture image 507 unit, etc. This validate command will at least do all the validation 508 that needs to occur at render time, and it could do anything extra that 509 might help the developer understand their shader(s) better. Note that it 510 is not necessary to call validate, it only is a development tool. 511 512 RESOLUTION: YES, this is a desirable feature. 513 514 27) Should there be an info log per object? 515 516 DISCUSSION: To store the info log per object created is consistent with 517 the whole object model. However, it might not be useful to keep an info 518 log around till the object is deleted. It does take resources away from 519 the system. Hence we could keep one info log per object type (shader or 520 program objects) as not to take too many resources. 521 522 Alternatively, the specification could say that at least one info log is 523 kept per object type, but that the GL implementation is free to keep 524 more. This was considered in an earlier version of this specification, 525 but broke down when considering the life time of an info log in a 526 multi-context situation. 527 528 Note that in either case the API definition for GetInfoLogARB does not 529 change. The application passes in a handle for the object, and if the 530 info log does not exist it returns an empty string. 531 532 RESOLUTION: We will have an info log per object, and not worry about the 533 resource usage. 534 535 28) Is there a need to have a command to append source code to a shader 536 object? 537 538 DISCUSSION: AppendShaderARB facilitates applications that generate 539 shaders on the fly. Developers can pass parts of a shader source to 540 OpenGL this way. However, the application can do the same thing in its 541 own memory buffer, and then pass the whole shader to OpenGL using 542 ShaderSourceARB. The application usually doesn't have to copy or 543 concatenate strings together. It can build a list of strings and pass 544 those to OpenGL all at once using ShaderSourceARB. 545 546 RESOLUTION: No, this is deemed not necessary. 547 548 29) Should loading the source code into a shader object automatically 549 invoke a compilation? 550 551 DISCUSSION: Keeping the loading of source and compilation of the source 552 as two distinctive API commands makes it possible for the application to 553 control when an expensive operation like a compile is done. For example, 554 it could first load all source for all its shaders at startup, and 555 compile them as needed through the execution of the application. Keeping 556 it separate leaves the most control to the application. 557 558 RESOLUTION: No. 559 560 30) What happens if an application tries to load more values in a 561 uniform than its declared extent? 562 563 DISCUSSION: It is possible to run off the end of a uniform, which could 564 potentially corrupt other uniforms, or any data that is stored by OpenGL 565 at the position next to the uniform. 566 567 Since it is not known, nor desirable to dictate, where an implementation 568 stores its uniforms, it cannot be defined what happens when a load 569 uniform command runs off the end. While enforcing bounds checking is 570 potentially expensive and can cost a good deal of performance, the 571 safety provided by bounds checking is considered more important than the 572 highest possible uniform loading performance. 573 574 Note also that the OpenGL Shading Language states that it is undefined 575 when a shader references an array element outside the array bounds. 576 577 RESOLUTION: The GL implementation must do whatever bounds checking is 578 necessary while loading uniforms. Applications that would like the 579 highest API performance should strongly consider using vertex attributes 580 for a small number of frequently changing values. 581 582 31) Should UseProgramObjectARB be display-list-able? 583 584 DISCUSSION: Consider a geometric object consisting of multiple 585 primitives. The primitives within this geometric object are rendered 586 using different shaders. The only way to encapsulate this into one 587 display list is by allowing UseProgramObjectARB to be compiled into a 588 display list. If this is not allowed, then the geometric object has to 589 be broken up in potentially many display lists, creating a management 590 nightmare for ISVs. 591 592 ARB_vertex_program allows BindProgramARB to be compiled into a display 593 list. Thus when using ARB_vertex_program it is possible to achieve the 594 scenario described above. 595 596 UseProgramObjectARB will generate a GL error if its operation failed, so 597 that applications can still check if it succeeded. 598 599 RESOLUTION: Yes 600 601 32) Can you explain how uniform loading works? 602 603 DISCUSSION: Uniform variables, including samplers, are named and 604 declared in a shader. This name is a string and needs to be used in 605 GetUniformLocationARB to retrieve a location ID. Once this location ID 606 has been retrieved it won't change until the next call to 607 LinkProgramARB. After LinkProgramARB has been issued, the application 608 will have to query the location IDs of uniform variables again. 609 LinkProgramARB will initialize all uniforms to zero. Note that 610 GetUniformLocationARB will only return a location ID if the uniform is 611 part of the set of active uniforms, else it will return -1. The set of 612 active uniforms, for a given program object, can be queried with 613 GetActiveUniformARB. 614 615 Once the location ID is obtained, it can be used in the Uniform*ARB 616 commands to load value(s) for the uniform. Note that the Uniform*ARB 617 command used has to match the size and the type of the uniform variable. 618 619 GetUniformLocationARB can only retrieve location IDs for uniforms 620 declared as a basic type (float, int, bool and vectors thereof) and 621 arrays of basic types. It is not possible to query the location ID of a 622 structure, for example. The application will have to break down the 623 structure into its fields until it has reached a basic type or an array 624 of basic type. It does this by using the "." (dot) and "[]" operations 625 in the name string passed to GetUniformLocationARB. It is possible to 626 query the location ID of an element K in an array. It is possible to use 627 that location ID to load multiple values into an array starting at that 628 location K. However, it is not possible to take that location ID and add 629 an integer N to that location ID to advance to element K + N in that 630 array. The application will have to query the location ID of array 631 element K + N separately. 632 633 For example, consider the following structure: 634 635 struct { 636 struct { 637 float a; 638 float b[10]; 639 } c[2]; 640 vec2 d; 641 } e; 642 643 loc1 = GetUniformLocationARB(programObject, "e.d") is a valid command. 644 loc2 = GetUniformLocationARB(programObject, "e.c[0]") is not valid. 645 loc3 = GetUniformLocationARB(programObject, "e.c[0].b") is a valid command. 646 loc4 = GetUniformLocationARB(programObject, "e.c[0].b[2]") is a valid command. 647 648 The location loc2 cannot be retrieved because "e.c[0]" references a 649 structure. 650 651 Uniform2fARB(loc1, 1.0f, 2.0f) is a valid command. 652 Uniform2iARB(loc1, 1, 2) is not. loc1 references a vec2, not an ivec2. 653 Uniform1fARB(loc1, 1.0f) is not. loc1 references a vec2, not a float. 654 Uniform1fvARB(loc3, 10, floatPtr) is a valid command. 655 Uniform1fvARB(loc4, 10, floatPtr) is not. It runs off the end of the array. 656 Uniform1fvARB(loc4, 8, floatPtr) is a valid command. 657 658 RESOLUTION: Yes 659 660 33) Should automatic conversion of input data types be done when loading 661 uniforms? 662 663 DISCUSSION: In other words, if the application passes an integer to the 664 uniform loading commands, and the uniform is declared as a float, should 665 automatic type conversion of that integer to a float occur? The vertex 666 attribute loading commands do this, for example. 667 668 OpenGL specifies that this kind of type conversion is dependent on the 669 usage of the data. Color, normals and depth components are normalized 670 and converted to floats as specified in Table 2.6. Other components are 671 not normalized before conversion to float. However, generally it is not 672 known what a uniform is used for. 673 674 It is hard to imagine that it is useful for an application to pass in 675 data that is declared as a different type in the shader. In that case 676 the type of the uniform in the shader could be matched to the 677 application's data type instead. 678 679 RESOLUTION: NO. If the basic type of the uniform is float, then 680 Uniform*f{v}ARB will have to be used. If the basic type of the uniform 681 is integer, then Uniform*i{v}ARB will have to be used. If the basic type 682 of the uniform is a sampler, then Uniform1i{v}ARB will have to be used. 683 684 Since there is no Boolean type in C (and we are defining C bindings) but 685 there is a Boolean type in the OpenGL Shading Language, type conversion 686 needs to be done. It is allowed to either pass in floats or integers if 687 the uniform is declared as a boolean. If the basic type of the uniform 688 is a Boolean, then either Uniform*f{v}ARB or Uniform*i{v}ARB can be 689 used. 690 691 Note that the uniform loading API can later be extended to allow for 692 automatic type conversion, with and without normalization, if it turns 693 out that is desired. 694 695 34) Why introduce the new terms "Use" and "Create"? 696 697 DISCUSSION: This question refers to glUseProgramObjectARB, 698 glCreateShaderObjectARB and glCreateProgramOBjectARB. We could have 699 defined glNewShaderObjectARB, glNewProgramObjectARB and left off the 700 "Use" in glUseProgramOBjectARB, resulting in glProgramObjectARB. 701 702 RESOLUTION: "New" is used for an existing function name (glNewList) that 703 takes a name as input, instead of returning a handle. We deliberately 704 chose "Create" for functions that return handles. Similarly "Use" is 705 used in a function name that takes a handle as input. Different names 706 make it clear to the developer that there are different semantics. 707 708 35) How is a uniform array treated when only some of the array elements 709 are actually used? 710 711 DISCUSSION: We have two goals in mind: 712 713 1) To be able to always load a uniform array starting from offset 0 714 into the array. 715 2) To keep the list of active uniforms as small as possible. 716 717 RESOLUTION: For a uniform array declared in a shader, 718 GetActiveUniformARB() will return the name of the array, its basic type 719 and a count. This count is determined by the highest element used in the 720 shader (as determined by the linker / compiler). If the shader doesn't 721 use the array at all, then the GL should obviously not report it as an 722 active uniform. Loading more data for the array, using Uniform*ARB, than 723 the count returned by GetActiveUniformARB is allowed. The extra data is 724 silently ignored (sent to the bit-bucket). 725 726 For example, consider the array: 727 728 uniform vec3 a[10]; 729 730 Which is used in a shader that uses elements 3 and 7 in this array. 731 GetActiveUniformARB will return: 732 733 "a" - the name of the array 734 8 - The size of the array (based on the highest element used, 7) 735 FLOAT_VEC3_ARB - The type 736 737 Since array elements 0 through 7 are active, the application can query 738 the locations for elements 0, 1, 2, 3, 4, 5, 6, 7 using 739 GetUniformLocationARB(). 740 741 Loading data for this array using a count of 10 (not 8) is allowed. Thus 742 it is legal to issue: 743 744 location = GetUniformLocation(progObj, "a"); 745 LoadUniform3fv(location, 10, dataPtr); 746 747 This will load data into array elements 0 through 7, since only array 748 elements 0 through 7 are active, and will ignore the rest of the data. 749 750 Array data is queried one element at a time. In order to query any 751 uniform, a location needs to be provided by the application. Therefore, 752 in this example, the application can query data for array elements 0 753 through 7, but not for elements 8 and 9. 754 755 This makes array loading portable, independent of the smartness of the 756 compiler / linker. It also encourages shader writers to start using 757 array elements starting at zero, and work their way upwards, to get 758 maximum resource efficiency from the OpenGL implementation. It also 759 works nicely with auto-sized uniform arrays (an array declared with 760 empty brackets "[]" and indexed only with compile time constants). 761 762 36) Should a location of -1 passed in to Uniform*ARB generate a GL error? 763 764 DISCUSSION: The Uniform*API commands will set an INVALID_OPERATION error 765 when passing in a location that does not exist. GetUniformLocationARB 766 will return -1 if the string passed in is not an active uniform, or if 767 it starts with the prefix "gl_". (This means you cannot get a location 768 for active built-in uniforms, for example gl_ModelviewMatrix). 769 770 If you're looping over GetUniformLocationARB and passing the result to 771 one of the Uniform*ARB commands, and if any -1 location passed to 772 Uniform*ARB will generate a GL error, then this means that you should 773 really bracket your Uniform*ARB command with a 'if (location != -1) 774 statement. It seems desireable to not generate a GL error when -1 is 775 passed in as a location to Uniform*ARB. The data passed in should then 776 be silently ignored. 777 778 RESOLUTION. NO. Note that this has changed since the version 0.87 (which 779 was published in the extension registry). That version did set an error 780 when passing in a location of -1. 781 782 37) What should the behavior of glDeleteObject(0) be? 783 784 DISCUSSION: It would be desirable to allow 0 as a valid input value, and 785 not raise an error. 786 787 RESOLUTION: glDeleteObject() will silently ignore deleting the value 0. 788 This is consistent with glDeleteTextures() that also silently ignores 789 deleting the value 0. 790 791 38) It is unclear how GetUniform*ARB works for matrices. Is the data 792 returned in column or row major order? 793 794 DISCUSSION: glGet(MODEL_VIEW_MATRIX) returns data in column major order. 795 It was discussed, but rejected, to add two new commands to return 796 matrices in column or row major order: 797 798 void GetUniformMatrixfvARB(handleARB programObj, int location, 799 boolean transpose, float *params) 800 void GetUniformMatrixivARB(handleARB programObj, int location, 801 boolean transpose, float *params) 802 803 RESOLUTION: GetUniformARB will return data in column major order, 804 regardles of the transpose flag used to set the matrix in the 805 LoadUniform*ARB commands. 806 807 39) Do "const" qualified variables consume uniform word storage, or not? 808 809 RESOLUTION: They do not. 810 811 40) What happens when a program object currently in use is re-linked, 812 and this re-link fails? 813 814 DISCUSSION: This should not affect the executable(s), part of the 815 current rendering state. As opposed to revert to fix pipeline for 816 example. 817 818 RESOLUTION: The currently active executable code will be kept until 819 changed or the program has been linked successfully. 820 821 41) What happens when an empty program object (one with no shader 822 objects attached) is linked? 823 824 DISCUSSION: Linking a program object with just a vertex shader will get 825 you fixed- function fragment processing. Vice versa, linking a program 826 object with just a fragment shader gets you fixed-function vertex 827 processing. 828 829 RESOLUTION: This will succeed and in this case you get the fixed 830 pipeline for both vertex and fragment processing if UseProgramObject() 831 is issued for this program object. 832 833 42) How to indicate the first element of an array when requesting a 834 uniform location? 835 836 DISCUSSION: There is a desire to have the location of the first element 837 of an array be indicated either using the name of the uniform array, or 838 by using the name appended with "[0]". 839 840 That would mean the following: 841 842 uniform s a[1]; // Where 's' is some struct with a field 'f' that is a float. 843 844 The following string combinations could be formed to pass into 845 GetUniformLocation: 846 847 a[0].f 848 a.f 849 850 If 'f' is an array float f[1] then the following string combinations 851 could be formed to pass into GetUniformLocation: 852 853 a[0].f[0] 854 a[0].f 855 a.f[0] 856 a.f 857 858 RESOLUTION: The spec is changed so that in the middle of a string it is 859 mandatory to use [0]. Thus that means that only the following two 860 strings are valid to pass to GetUniformLocation: 861 862 a[0].f 863 a[0].f[0] 864 865 43) What does GetActiveUniformARB() report for the following two 866 uniforms? 867 868 DISCUSSION: Consider shader code with: 869 870 uniform float a[1]; 871 uniform float a; 872 873 The size reported by GetActiveUniformARB() will be '1', and the type 874 reported will be float. The string reported can be 'a' in both cases, or 875 can be 'a[0]' in the array case. In other words, from this data it is 876 not clear to the application if 'a' is an array of size one or a scalar. 877 Reporting 'a[0]' is the recommended way for the array case. Technically 878 it doesn't really matter, since it is legal to address the first element 879 of an array with 'a' or 'a[0]' and pass either string into 880 GetUniformLocation. 881 882 RESOLUTION: The GL implementation can report either string. However, it 883 is recommended to return 'a[0]'. 884 885 44) Do GL enables affect the built-in state available to a shader? 886 887 DISCUSSION: The lighting state, for example, is still tracked and kept 888 current even when lighting, or a specific light, is disabled. This goes 889 for all built-in state listed in Chapter 7.5 of the OpenGL Shading 890 Language Specification. Do realize that the enables 891 VERTEX_PROGRAM_POINT_SIZE and VERTEX_PROGRAM_TWO_SIDE do need to be 892 enabled by the application, to get their desired effect. 893 894 RESOLUTION: Enable state is a piece of orthogonal state that is not 895 available to a shader. The enable state does not affect the built-in 896 state that is available to a shader, which is listed in Chapter 7.5 of 897 the OpenGL Shading Language specification. 898 899 45) Please give an example of using the uniform API. 900 901 DISCUSSION: Below are two examples. The first one queries each active 902 uniform, then loads a value for it. The second example works of a list 903 of uniforms, and queries their locations. Some of the uniforms in that 904 list might not be active. 905 906 // 907 // Example code that queries active uniforms, then loads their values 908 // 909 void 910 example1(GLhandleARB programObject) 911 { 912 int i, count, size, type, linked, location; 913 char uniformName[1000]; 914 915 // Link the program object and make sure it succeeded. 916 glLinkProgramARB(programObject); 917 glGetObjectParameterivARB(programObject, GL_OBJECT_LINK_STATUS_ARB, &linked); 918 919 if (!linked) { 920 return; 921 } 922 923 // Install the executables in the program object as part of current state. 924 glUseProgramObjectARB(programObject); 925 926 // Check for GL Errors 927 928 // Setup uniform values in the array 'colorInterior'. 929 930 // Query the number of active uniforms 931 glGetObjectParameterivARB(programObject, GL_OBJECT_ACTIVE_UNIFORMS_ARB, 932 &count); 933 934 // Loop over each of the active uniforms, and set their value 935 for (i = 0; i < count; i++) 936 { 937 glGetActiveUniformARB(programObject, i, 1000, NULL, &size, &type, 938 uniformName); 939 printf("active uniform: %s\n",uniformName); 940 941 location = glGetUniformLocationARB(programObject, uniformName); 942 943 if (type == GL_FLOAT_VEC3_ARB) { 944 float *data; 945 946 // Allocate data based on 'size' 947 // do some kind of hash lookup on the uniform name to get the 948 // data to load for the uniform. 949 lookupUniformData(uniformName, data); 950 951 // This a vec3, therefore need to use the '3f' or '3fv' version 952 // of the uniform loading commands. 953 glUniform3fvARB(location, size, data); 954 } // else : Setup more types here 955 } 956 } 957 958 959 // 960 // Example code that has a list of uniforms, and loads values for each uniform 961 // in the list. Not all uniforms have to be active ones. 962 // 963 void 964 example2(GLhandleARB programObject) 965 { 966 int i, count, linked, location; 967 char **uniformName; 968 float *data; 969 970 // Link the program object and make sure it succeeded. 971 glLinkProgramARB(programObject); 972 glGetObjectParameterivARB(programObject, GL_OBJECT_LINK_STATUS_ARB, &linked); 973 974 if (!linked) { 975 return; 976 } 977 978 // Install the executables in the program object as part of current state. 979 glUseProgramObjectARB(programObject); 980 981 // Check for GL Errors 982 983 // Setup uniform values in the array 'data'. 984 // Setup 'count' and the array 'uniformName' 985 986 // Loop over the list of uniforms in uniformName, and set their value 987 for (i = 0; i < count; i++) 988 { 989 // Location will be -1 if the uniform is not active, but that is OK 990 // the uniform loading commands will silently ignore a location of -1. 991 location = glGetUniformLocationARB(programObject, uniformName[i]); 992 993 // This a a vec3, therefore need to use the '3f' or '3fv' version of 994 // the uniform loading command. 995 glUniform3fvARB(location, 1, &data[i * 3]); 996 } 997 } 998 999 46) Should we add capability to query if an object is dirty? 1000 1001 DISCUSSION: Specifically, do we add a way to query if a program object 1002 needs relinking? Do we add a way to query if a shader object needs 1003 re-compilation? 1004 1005 RESOLUTION: No, the application can keep track of this information as 1006 well. Mipmap state consistency is not queriable either, for example. 1007 1008New Procedures and Functions 1009 1010 void DeleteObjectARB(handleARB obj) 1011 1012 handleARB GetHandleARB(enum pname) 1013 1014 void DetachObjectARB(handleARB containerObj, handleARB attachedObj) 1015 1016 handleARB CreateShaderObjectARB(enum shaderType) 1017 1018 void ShaderSourceARB(handleARB shaderObj, sizei count, const charARB **string, 1019 const int *length) 1020 1021 void CompileShaderARB(handleARB shaderObj) 1022 1023 handleARB CreateProgramObjectARB(void) 1024 1025 void AttachObjectARB(handleARB containerObj, handleARB obj) 1026 1027 void LinkProgramARB(handleARB programObj) 1028 1029 void UseProgramObjectARB(handleARB programObj) 1030 1031 void ValidateProgramARB(handleARB programObj) 1032 1033 void Uniform1fARB(int location, float v0) 1034 void Uniform2fARB(int location, float v0, float v1) 1035 void Uniform3fARB(int location, float v0, float v1, float v2) 1036 void Uniform4fARB(int location, float v0, float v1, float v2, float v3) 1037 1038 void Uniform1iARB(int location, int v0) 1039 void Uniform2iARB(int location, int v0, int v1) 1040 void Uniform3iARB(int location, int v0, int v1, int v2) 1041 void Uniform4iARB(int location, int v0, int v1, int v2, int v3) 1042 1043 void Uniform1fvARB(int location, sizei count, const float *value) 1044 void Uniform2fvARB(int location, sizei count, const float *value) 1045 void Uniform3fvARB(int location, sizei count, const float *value) 1046 void Uniform4fvARB(int location, sizei count, const float *value) 1047 1048 void Uniform1ivARB(int location, sizei count, const int *value) 1049 void Uniform2ivARB(int location, sizei count, const int *value) 1050 void Uniform3ivARB(int location, sizei count, const int *value) 1051 void Uniform4ivARB(int location, sizei count, const int *value) 1052 1053 void UniformMatrix2fvARB(int location, sizei count, boolean transpose, const float *value) 1054 void UniformMatrix3fvARB(int location, sizei count, boolean transpose, const float *value) 1055 void UniformMatrix4fvARB(int location, sizei count, boolean transpose, const float *value) 1056 1057 void GetObjectParameterfvARB(handleARB obj, enum pname, float *params) 1058 void GetObjectParameterivARB(handleARB obj, enum pname, int *params) 1059 1060 void GetInfoLogARB(handleARB obj, sizei maxLength, sizei *length, charARB *infoLog) 1061 1062 void GetAttachedObjectsARB(handleARB containerObj, sizei maxCount, sizei *count, 1063 handleARB *obj) 1064 1065 int GetUniformLocationARB(handleARB programObj, const charARB *name) 1066 1067 void GetActiveUniformARB(handleARB programObj, uint index, sizei maxLength, 1068 sizei *length, int *size, enum *type, charARB *name) 1069 1070 void GetUniformfvARB(handleARB programObj, int location, float *params) 1071 void GetUniformivARB(handleARB programObj, int location, int *params) 1072 1073 void GetShaderSourceARB(handleARB obj, sizei maxLength, sizei *length, 1074 charARB *source) 1075 1076New Tokens 1077 1078 Accepted by the <pname> argument of GetHandleARB: 1079 1080 PROGRAM_OBJECT_ARB 0x8B40 1081 1082 Accepted by the <pname> parameter of GetObjectParameter{fi}vARB: 1083 1084 OBJECT_TYPE_ARB 0x8B4E 1085 OBJECT_SUBTYPE_ARB 0x8B4F 1086 OBJECT_DELETE_STATUS_ARB 0x8B80 1087 OBJECT_COMPILE_STATUS_ARB 0x8B81 1088 OBJECT_LINK_STATUS_ARB 0x8B82 1089 OBJECT_VALIDATE_STATUS_ARB 0x8B83 1090 OBJECT_INFO_LOG_LENGTH_ARB 0x8B84 1091 OBJECT_ATTACHED_OBJECTS_ARB 0x8B85 1092 OBJECT_ACTIVE_UNIFORMS_ARB 0x8B86 1093 OBJECT_ACTIVE_UNIFORM_MAX_LENGTH_ARB 0x8B87 1094 OBJECT_SHADER_SOURCE_LENGTH_ARB 0x8B88 1095 1096 Returned by the <params> parameter of GetObjectParameter{fi}vARB: 1097 1098 SHADER_OBJECT_ARB 0x8B48 1099 1100 Returned by the <type> parameter of GetActiveUniformARB: 1101 1102 FLOAT 0x1406 1103 FLOAT_VEC2_ARB 0x8B50 1104 FLOAT_VEC3_ARB 0x8B51 1105 FLOAT_VEC4_ARB 0x8B52 1106 INT 0x1404 1107 INT_VEC2_ARB 0x8B53 1108 INT_VEC3_ARB 0x8B54 1109 INT_VEC4_ARB 0x8B55 1110 BOOL_ARB 0x8B56 1111 BOOL_VEC2_ARB 0x8B57 1112 BOOL_VEC3_ARB 0x8B58 1113 BOOL_VEC4_ARB 0x8B59 1114 FLOAT_MAT2_ARB 0x8B5A 1115 FLOAT_MAT3_ARB 0x8B5B 1116 FLOAT_MAT4_ARB 0x8B5C 1117 SAMPLER_1D_ARB 0x8B5D 1118 SAMPLER_2D_ARB 0x8B5E 1119 SAMPLER_3D_ARB 0x8B5F 1120 SAMPLER_CUBE_ARB 0x8B60 1121 SAMPLER_1D_SHADOW_ARB 0x8B61 1122 SAMPLER_2D_SHADOW_ARB 0x8B62 1123 SAMPLER_2D_RECT_ARB 0x8B63 1124 SAMPLER_2D_RECT_SHADOW_ARB 0x8B64 1125 1126Additions to Chapter 2 of the OpenGL 1.4 Specification (OpenGL Operation) 1127 1128 Add two new rows to Table 2.2, page 9. 1129 1130 GL Type Minimum Description 1131 Bit Width 1132 ------- ------- ------------- 1133 charARB 8 characters that make up strings 1134 handleARB 32 identifier for generic objects 1135 1136 Modify Section 2.5, GL Errors, p. 11 1137 1138 (modify the last paragraph, p. 11) Four error generation conditions are 1139 implicit... 1140 1141 (modify the first paragraph, p. 12) ...the error INVALID_VALUE results. 1142 Third, the error INVALID_VALUE is generated by any command that takes 1143 one or more handles as input, and one or more of these handles are not a 1144 generic object handle generated by OpenGL. Finally, if memory is 1145 exhausted... 1146 1147 Modify Section 2.6.1 Begin and End Objects, p. 13 1148 1149 Remove the term "objects" from this section. 1150 1151 Add a new section 2.14 Generic Objects, p.60 1152 1153 The currently existing object types in OpenGL, texture objects (see 1154 Section 3.8.12) and display lists (see Section 5.4), each have their own 1155 management API and object ID name space. Rather than designing a new API 1156 for each new object type added to OpenGL, this section introduces a more 1157 generic object API, which is initially applied to shader objects 1158 (Section 2.14.1) and program objects (Section 2.14.2). 1159 1160 In OpenGL, a "generic object" is an OpenGL-managed opaque data 1161 structure. The data stored in such a generic object may be quite large, 1162 so applications are given control over how objects are managed. Generic 1163 objects are given handles (names) by OpenGL at object creation time. 1164 Applications can specify the data that is to be stored in objects and 1165 can modify that data through function calls. Generic objects can be 1166 created, deleted, modified, attached, detached and used as part of the 1167 current rendering state. 1168 1169 Some types of generic objects act as containers for other objects. 1170 Linking an object to another is called "attaching" and unlinking an 1171 object is called "detaching". 1172 1173 To attach an object to a container object, use the command: 1174 1175 void AttachObjectARB (handleARB containerObj, handleARB obj) 1176 1177 The error INVALID_OPERATION is generated if <obj> is not a type that can 1178 be attached to a container object or if <containerObj> is not a 1179 container object. The same error is generated if an attempt is made to 1180 attach the same object more than once to the same container object. 1181 1182 To detach an object from the container object it is attached to, use the 1183 command: 1184 1185 void DetachObjectARB(handleARB containerObj, handleARB attachedObj) 1186 1187 If the object <attachedObj> is not attached to any other container 1188 object in any rendering context, and the object is flagged for deletion, 1189 the information for <attachedObj> and the data for <attachedObj> is 1190 deleted. If <attachedObj> is not attached to <containerObj>, the error 1191 INVALID_OPERATION is generated. The error INVALID_OPERATION is also 1192 generated if <containerObj> is not a container object. 1193 1194 Generic objects can be deleted with the following command: 1195 1196 void DeleteObjectARB(handleARB obj) 1197 1198 This command will either delete the object, or flag it for deletion. An 1199 object that is attached to a container object is not deleted until it is 1200 no longer attached to any container object, for any context. If it is 1201 still attached to at least one container object, the object is flagged 1202 for deletion. If the object is part of the current rendering state, it 1203 is not deleted until it is no longer part of the current rendering state 1204 for any context. If the object is still part of the rendering state of 1205 at least one context, it is flagged for deletion. 1206 1207 if an object is flagged for deletion, its Boolean status bit 1208 OBJECT_DELETE_STATUS_ARB is set to true. The value of 1209 OBJECT_DELETE_STATUS_ARB can be queried with GetObjectParameter{fi}vARB 1210 (see Section 6.1.12). 1211 1212 DeleteObjectARB will silently ignore the value zero. 1213 1214 When a container object is deleted, it will detach each attached object 1215 as part of the deletion process. When an object is deleted, all 1216 information for the object referenced is lost. The data for the object 1217 is also deleted. One bit of state is needed to indicate if a delete 1218 request for an object was made. The default is no request. 1219 1220 Add Subsection 2.14.1 Shader Objects 1221 1222 Subsequent sections of this specification will define stages of the GL 1223 pipeline that are programmable. The source code that makes up a program 1224 that gets executed by one of the programmable stages is encapsulated in 1225 one or more "shader objects". To create a shader object use the 1226 following command: 1227 1228 handleARB CreateShaderObjectARB(enum shaderType) 1229 1230 The shader object is empty when it is created. The <shaderType> argument 1231 specifies the type of shader object to be created, and should be one of 1232 < >. (This list to be augmented by other extensions.) If the shader 1233 object is created successfully, a handle that can be used to reference 1234 it is returned, and its object specific parameter OBJECT_TYPE_ARB is set 1235 to SHADER_OBJECT_ARB. The object specific parameter OBJECT_SUBTYPE_ARB 1236 is set to the actual type of the shader object created. The value of 1237 OBJECT_TYPE_ARB and OBJECT_SUBTYPE_ARB can be queried with 1238 GetObjectParameter{fi}vARB (see Section 6.1.12). If the creation failed 1239 the handle returned will be 0. 1240 1241 Source code for the shader is specified with the command: 1242 1243 void ShaderSourceARB(handleARB shaderObj, sizei count, 1244 const charARB **string, const int *length) 1245 1246 The <string> argument is an array of pointers to one or more, optionally 1247 null terminated, character strings that make up the source code. The 1248 <length> argument is an array with the number of charARBs in each string 1249 (the string length). Each element in this array can be set to negative 1250 one (or smaller), indicating that its accompanying string is null 1251 terminated. If <length> is set to NULL, all strings in the <string> 1252 argument are considered null terminated. The ShaderSourceARB command 1253 sets the source code for the specified shader object <shaderObj> to the 1254 text strings in the <string> array. If the object previously had source 1255 code loaded into it, it is completely replaced. The number of strings in 1256 the array is given in <count>. Any length passed in excludes the null 1257 termination in its count. If <shaderObj> does not reference a shader 1258 object, the error INVALID_OPERATION is generated. 1259 1260 The strings that are loaded into a shader object are expected to form 1261 the source code for a valid shader as defined in the OpenGL Shading 1262 Language Specification. Once the source code for a shader has been 1263 loaded, the shader object can be compiled with the following command: 1264 1265 void CompileShaderARB(handleARB shaderObj) 1266 1267 This function will compile <shaderObj>. Each shader object has a Boolean 1268 status, OBJECT_COMPILE_STATUS_ARB, that is modified as a result of 1269 compilation. This status can be queried with GetObjectParameter{fi}vARB 1270 (see Section 6.1.12). This status will be set to TRUE if the shader 1271 <shaderObj> was compiled without errors and is ready for use, and FALSE 1272 otherwise. Compilation can fail for a variety of reasons as listed in 1273 the OpenGL Shading Language Specification. If CompileShaderARB failed, 1274 any information about a previous compile is lost and is not restored. 1275 Thus a failed compile does not restore the old state of <shaderObj>. If 1276 <shaderObj> does not reference a shader object, the error 1277 INVALID_OPERATION is generated. 1278 1279 Note that changing the source code of a shader object, through 1280 ShaderSourceARB, does not change its compile status 1281 OBJECT_COMPILE_STATUS_ARB. 1282 1283 Each shader object has an information log that is modified as a result 1284 of compilation. This information log can be queried with GetInfoLogARB 1285 to obtain more information about the compilation attempt (see Section 1286 6.1.12). 1287 1288 Add Subsection 2.14.2 Program Objects 1289 1290 The shader objects that are to be used by the programmable stages of 1291 OpenGL are collected together to form a "program object". The programs 1292 that are executed by these programmable stages are called "executables". 1293 All information necessary for defining an executable is encapsulated in 1294 a program object. A program object is created with the following 1295 command: 1296 1297 handleARB CreateProgramObjectARB(void) 1298 1299 Program objects are empty when they are created. If the program object 1300 is created successfully, a handle that can be used to reference it is 1301 returned and its attribute OBJECT_TYPE_ARB is set to PROGRAM_OBJECT_ARB. 1302 If the creation failed the handle returned will be 0. 1303 1304 A program object is a container object. Shader objects are attached to a 1305 program object with the command AttachObjectARB. It is permissible to 1306 attach shader objects to program objects before source code has been 1307 loaded into the shader object, or before the shader object has been 1308 compiled. It is permissible to attach multiple shader objects of the 1309 same type to a single program object, and it is permissible to attach a 1310 shader object to more than one program object. 1311 1312 In order to use the shader objects contained in a program object, the 1313 program object must be linked. This is accomplished with the following 1314 command: 1315 1316 void LinkProgramARB (handleARB programObj) 1317 1318 This function will link <programObj>. Each program object has a Boolean 1319 status, OBJECT_LINK_STATUS_ARB, that is modified as a result of linking. 1320 This status can be queried with GetObjectParameter{fi}vARB (see Section 1321 6.1.12). This status will be set to TRUE if a valid executable is 1322 created, and FALSE otherwise. Linking can fail for a variety of reasons 1323 as specified in the OpenGL Shading Language Specification. Linking will 1324 also fail if one or more of the shader objects, attached to 1325 <programObj>, are not compiled successfully, or if more active uniform 1326 or active sampler variables are used in <programObj> than allowed (see 1327 Sections 2.14.3 and 2.14.4). If LinkProgramARB failed, any information 1328 about a previous link is lost and is not restored. Thus a failed link 1329 does not restore the old state of <programObj>. If <programObj> is not 1330 of type PROGRAM_OBJECT_ARB, the error INVALID_OPERATION is generated. 1331 1332 Each program object has an information log that is modified as a result 1333 of a link operation. This information log can be queried with 1334 GetInfoLogARB to obtain more information about the link operation (see 1335 Section 6.1.12). 1336 1337 If a valid executable is created, it can be made part of the current 1338 rendering state with the following command: 1339 1340 void UseProgramObjectARB(handleARB programObj) 1341 1342 This command will install the executable code as part of current 1343 rendering state if the program object <programObj> contains valid 1344 executable code, i.e. has been linked successfully. If 1345 UseProgramObjectARB is called with the handle set to 0, it is as if the 1346 GL had no programmable stages and the fixed functionality paths will be 1347 used instead. If <programObj> cannot be made part of the current 1348 rendering state, an INVALID_OPERATION error will be generated and the 1349 current rendering state left unmodified. This error will be set, for 1350 example, if <programObj> has not been linked successfully. If 1351 <programObj> is not of type PROGRAM_OBJECT_ARB, the error 1352 INVALID_OPERATION is generated. 1353 1354 While a program object is in use, applications are free to modify 1355 attached shader objects, compile attached shader objects, attach 1356 additional shader objects, and detach shader objects. This does not 1357 affect the link status OBJECT_LINK_STATUS_ARB of the program object. 1358 This does not affect the executable code that is part of the current 1359 state either. That executable code is only affected when the program 1360 object has been re-linked successfully. After such a successful re-link, 1361 the LinkProgramARB command will install the generated executable code as 1362 part of the current rendering state if the specified program object was 1363 already in use as a result of a previous call to UseProgramObjectARB. If 1364 this re-link failed, then the executable code part of the current state 1365 does not change. 1366 1367 Add Subsection 2.14.3 Uniform Variables 1368 1369 Shaders can declare and name "uniform variables" as discussed in the 1370 OpenGL Shading Language Specification. Values for these uniforms are to 1371 remain constant over a primitive, and typically they are constant across 1372 many primitives. Uniforms are program object specific state. They retain 1373 their values once loaded, and their values are restored whenever a 1374 program object is used, as long as the program object has not been 1375 re-linked. A uniform is considered "active" if it is determined by the 1376 compiler and linker that the uniform will actually be accessed when the 1377 executable code is executed. In cases where the compiler and linker 1378 cannot make a conclusive determination, the uniform will be considered 1379 active. 1380 1381 As a result of a successful link all active uniforms belonging to the 1382 program object are initialized to zero. A successful link will also 1383 generate a location for each active uniform. The values of active 1384 uniforms can be changed using this location and the appropriate 1385 Uniform*ARB command (see below). These locations are invalidated and new 1386 ones assigned after each successful re-link. 1387 1388 The following function can be used to find the location of an active 1389 uniform variable within a program object: 1390 1391 int GetUniformLocationARB(handleARB programObj, const charARB *name) 1392 1393 This command will return the location of uniform variable <name>. <name> 1394 has to be a null terminated string, without white space. The value of -1 1395 will be returned if <name> does not correspond to an active uniform 1396 variable name in <programObj> or if <name> starts with the reserved 1397 prefix "gl_". If <programObj> has not been successfully linked, or if 1398 <programObj> is not of type PROGRAM_OBJECT_ARB, the error 1399 INVALID_OPERATION is generated. The location of a uniform variable does 1400 not change until the next link command is issued. 1401 1402 A valid <name> cannot be a structure, an array of structures, or a 1403 subcomponent of a vector or a matrix. In order to identify a valid 1404 <name>, the "." (dot) and "[]" operators can be used in <name> to 1405 operate on a structure or to operate on an array. 1406 1407 The first element of a uniform array is identified using the name of the 1408 uniform array appended with "[0]". Except if the last part of the string 1409 <name> indicates a uniform array, then the location of the first element 1410 of that array can be retrieved by either using the name of the uniform 1411 array, or the name of the uniform array appended with "[0]". 1412 1413 To determine which of the declared uniform variables are active and to 1414 determine their sizes and types, use the command: 1415 1416 void GetActiveUniformARB(handleARB programObj, uint index, 1417 sizei maxLength, sizei *length, int *size, 1418 enum *type, charARB *name) 1419 1420 This command provides information about the uniform selected by <index>. 1421 The <index> of 0 selects the first active uniform, and <index> of 1422 OBJECT_ACTIVE_UNIFORMS_ARB-1 selects the last active uniform. The value 1423 of OBJECT_ACTIVE_UNIFORMS_ARB can be queried with 1424 GetObjectParameter{if}vARB (see Section 6.1.12). If <index> is greater 1425 than or equal to OBJECT_ACTIVE_UNIFORMS_ARB, the error INVALID_VALUE is 1426 generated. 1427 1428 The parameter <programObj> is a handle to a program object for which the 1429 command LinkProgramARB has been issued in the past. It is not necessary 1430 for <programObj> to have been linked successfully. The link could have 1431 failed because the number of active uniforms exceeded the limit. If 1432 <programObj> is not of type PROGRAM_OBJECT_ARB, the error 1433 INVALID_OPERATION is generated. 1434 1435 If an error occurred, the return parameters <length>, <size>, <type> and 1436 <name> will be unmodified. 1437 1438 For the selected uniform, the uniform name is returned into <name>. The 1439 string <name> will be null terminated. The actual number of characters 1440 written by the GL into <name> is returned in <length>. This count 1441 excludes the null termination. If <length> is NULL then the GL ignores 1442 this parameter. The maximum number of characters the GL is allowed to 1443 write into <name> is passed in by <maxLength>. The returned uniform name 1444 can be the name of built-in uniform state as well. The complete list of 1445 built-in uniform state is described in section 7.5 of the OpenGL Shading 1446 Language specification. The length of the longest uniform name in 1447 <programObj> is given by OBJECT_ACTIVE_UNIFORM_MAX_LENGTH_ARB, which can 1448 be queried with GetObjectParameter{if}vARB (see Section 6.1.12). 1449 1450 Each uniform variable, declared in a shader, is broken down into one or 1451 more strings using the "." (dot) and "[]" operators, if necessary, to 1452 the point that it is legal to pass each string back into 1453 GetUniformLocationARB. Each of these strings constitutes one active 1454 uniform, and each string is assigned an index. 1455 1456 For the selected uniform, the type of the uniform is returned into 1457 <type>. The size of the uniform is returned into <size>. The value in 1458 <size> is in units of the type returned in <type>. The type returned can 1459 be any of FLOAT, FLOAT_VEC2_ARB, FLOAT_VEC3_ARB, FLOAT_VEC4_ARB, INT, 1460 INT_VEC2_ARB, INT_VEC3_ARB, INT_VEC4_ARB, BOOL_ARB, BOOL_VEC2_ARB, 1461 BOOL_VEC3_ARB, BOOL_VEC4_ARB, FLOAT_MAT2_ARB, FLOAT_MAT3_ARB, 1462 FLOAT_MAT4_ARB, SAMPLER_1D_ARB, SAMPLER_2D_ARB, SAMPLER_3D_ARB, 1463 SAMPLER_CUBE_ARB, SAMPLER_1D_SHADOW_ARB, SAMPLER_2D_SHADOW_ARB, 1464 SAMPLER_2D_RECT_ARB or SAMPLER_2D_RECT_SHADOW_ARB. 1465 1466 If one or more elements of an array are active, GetActiveUniformARB will 1467 return the name of the array in <name>, subject to the restrictions 1468 listed above. The type of the array is returned in <type>. The <size> 1469 parameter contains the highest array element index used, plus one. The 1470 compiler or linker determines the highest index used. There will be only 1471 one active uniform reported by the GL per uniform array. 1472 1473 This command will return as much information about active uniforms as 1474 possible. If no information is available, <length> will be set to zero 1475 and <name> will be an empty string. This situation could arise if 1476 GetActiveUniformARB is issued after a failed link. 1477 1478 The following commands are used to load values into the uniform 1479 variables of the program object that is currently in use. 1480 1481 void Uniform{1234}fARB(int location, T value) 1482 void Uniform{1234}iARB(int location, T value) 1483 1484 void Uniform{1234}fvARB(int location, sizei count, T value) 1485 void Uniform{1234}ivARB(int location, sizei count, T value) 1486 1487 void UniformMatrix(234}fvARB(int location, sizei count, 1488 boolean transpose, T value) 1489 1490 These commands will load the given values into the uniform variable 1491 location identified by <location>. 1492 1493 The Uniform{1234}f{v}ARB commands will load one or more floating-point 1494 values <count> times into a uniform location defined as a float or 1495 floating-point vector or an array of floats or an array of 1496 floating-point vectors. 1497 1498 The Uniform{1234}i{v}ARB commands will load one or more integer values 1499 <count> times into a uniform location defined as a sampler, integer or 1500 integer vector or an array of integers or an array of integer vectors. 1501 Only the Uniform1i{v}ARB commands can be used to load sampler values. 1502 See section 2.14.4. 1503 1504 The UniformMatrix{234}fvARB commands will load a 2x2, 3x3 or 4x4 matrix 1505 (corresponding to 2, 3, or 4 in the command name) of floating-point 1506 values <count> times into a uniform location defined as a matrix or an 1507 array of matrices. If <transpose> is FALSE, the matrix is specified in 1508 column major order, otherwise in row major order. 1509 1510 When loading values for a uniform declared as a Boolean, a Boolean 1511 vector or an array of Booleans or an array of Boolean vectors, both the 1512 Uniform*i{v} and Uniform*f{v} set of commands can be used to load 1513 Boolean values. Type conversion is done by the GL. The uniform is set to 1514 FALSE if the input value is 0 or 0.0f, and set to TRUE otherwise. The 1515 Uniform*ARB command used must match the size of the uniform, as declared 1516 in the shader. For example, to load a uniform declared as a bvec2, 1517 either Uniform2i{v}ARB or Uniform2f{v}ARB can be used. An 1518 INVALID_OPERATION error will be generated if an attempt is made to use a 1519 non-matching Uniform*ARB command. In this example using Uniform1ivARB 1520 would generate an error. 1521 1522 For all other uniform types the Uniform*ARB command used must match the 1523 size and type of the uniform, as declared in the shader. No type 1524 conversions are done. For example, to load a uniform declared as a vec4, 1525 Uniform4f{v}ARB must be used. To load a 3x3 matrix, 1526 UniformFloatMatrix3fvARB must be used. An INVALID_OPERATION error will 1527 be generated if an attempt is made to use a non-matching Uniform*ARB 1528 command. In this example, using Uniform4i{v}ARB would generate an error. 1529 1530 When loading N elements starting at an arbitrary position k in a uniform 1531 declared as an array, elements k through k + N - 1 in the array will be 1532 replaced with the new values. Values for any array element that exceeds 1533 the highest array element index used, as reported by 1534 GetActiveUniformARB, will be ignored by the GL. 1535 1536 If the value of <location> is -1, the Uniform*ARB commands will silently 1537 ignore the data passed in. The current uniform values will therefore not 1538 be changed. 1539 1540 The following applies to errors that can be generated when loading 1541 uniforms: 1542 1543 - If the size indicated in the name of the Uniform*ARB command used 1544 does not match the size of the uniform declared in the shader, an 1545 INVALID_OPERATION error is generated and the uniform's value is not 1546 changed. 1547 - If a uniform not of type Boolean is loaded, then if the type 1548 indicated in the name of the Uniform*ARB command used does not match 1549 the type of the uniform declared in the shader, an INVALID_OPERATION 1550 error is generated and the uniform's value is not changed. 1551 - If <location> is not -1 and <location> does not exist for the program 1552 object currently in use, the error INVALID_OPERATION is generated. 1553 - The error INVALID_OPERATION is generated by any of the Uniform*ARB 1554 commands if there is no program object in use. 1555 1556 Add Subsection 2.14.4 Samplers 1557 1558 Samplers are special uniforms used in the OpenGL Shading Language to 1559 identify the texture object used for each texture lookup. The value of a 1560 sampler indicates the texture image unit being accessed. Setting a 1561 sampler's value to i selects texture image unit number i. The values of 1562 i range from zero to the maximum supported number of texture image 1563 units. This maximum is implementation dependent, and defined in other 1564 specifications. 1565 1566 The type of the sampler identifies the target on the texture image unit. 1567 The texture object bound to that texture image unit's target is then 1568 used for the texture lookup. For example, a variable of type sampler2D 1569 selects target TEXTURE_2D on its texture image unit. Binding of texture 1570 objects to targets is done as usual with BindTexture. Selecting the 1571 texture image unit to bind to is done as usual with ActiveTexture. 1572 1573 The location of a sampler needs to be queried with 1574 GetUniformLocationARB, just like any uniform variable. Sampler values 1575 need to be set by calling Uniform1i{v}ARB. Loading samplers with any of 1576 the other Uniform*ARB entry points is not allowed and will result in an 1577 INVALID_OPERATION error. 1578 1579 It is not allowed to have variables of different sampler types pointing 1580 to the same texture image unit within a program object. This situation 1581 can only be detected at the next rendering command issued, and an 1582 INVALID_OPERATION error will then be generated. 1583 1584 Active samplers are samplers actually being used in a program object. 1585 The LinkProgramARB command determines if a sampler is active or not. The 1586 LinkProgramARB command will attempt to determine if the active samplers 1587 in the shader(s) contained in the program object exceed the maximum 1588 allowable limits. If it determines that the count of active samplers 1589 exceeds the allowable limits, then the link fails. (These limits are 1590 determined by other extensions, and can be different for different types 1591 of shaders.) If this cannot be determined at link time, for example if 1592 the program object only contains a vertex shader, then this will be 1593 determined at the next rendering command issued, and an 1594 INVALID_OPERATION error will then be generated. 1595 1596 Add Subsection 2.14.5 Resource Limits 1597 1598 A shader should not fail to compile and a program object to link due to 1599 lack of instruction space or lack of temporary variables. 1600 Implementations should ensure that all valid shaders and program objects 1601 could be successfully compiled, linked and executed. 1602 1603 Add Subsection 2.15 Validation 1604 1605 It is not always possible to determine at link time if a program object 1606 actually will execute. Therefore validation is done when the first 1607 rendering command is issued, to determine if the currently active 1608 program object can be executed. If it cannot be executed then no 1609 fragments will be rendered, and Begin, RasterPos, or any command that 1610 performs an explicit Begin will generate the error INVALID_OPERATION. 1611 1612 This error is generated by Begin, RasterPos, or any command that 1613 performs an explicit Begin if: 1614 1615 * One or more samplers of different types in the current program 1616 object access the same texture image unit. 1617 * If more than the maximum allowable texture image units are accessed 1618 based on the count of active samplers and the rest of the GL state. 1619 Note that LinkProgramARB can normally resolve this, except for the 1620 case where an ARB_vertex_shader shader is mixed with an 1621 ARB_fragment_program shader or mixed with fixed-function fragment 1622 processing. 1623 1624 The INVALID_OPERATION error reported by these rendering commands does 1625 not provide enough information to find out why the currently active 1626 program object would not execute. No information at all is available 1627 about a program object that would still execute, but is inefficient or 1628 sub optimal given the current GL state. As a development aid, use the 1629 command 1630 1631 void ValidateProgramARB(handleARB programObj) 1632 1633 to validate the program object <programObj> against the GL state at that 1634 moment. Each program object has a Boolean status, 1635 OBJECT_VALIDATE_STATUS_ARB, that is modified as a result of validation. 1636 This status can be queried with GetObjectParameter{if}vARB (see Section 1637 6.1.12). If validation succeeded this status will be set to TRUE, 1638 otherwise it will be set to FALSE. If validation succeeded the program 1639 object is guaranteed to execute, given the current GL state. If 1640 validation failed, the program object is guaranteed to not execute, 1641 given the current GL state. If <programObj> is not of type 1642 PROGRAM_OBJECT_ARB, the error INVALID_OPERATION is generated. 1643 1644 ValidateProgramARB will validate at least as much as is done when a 1645 rendering command is issued, and it could validate more. For example, it 1646 could give a hint on how to optimize some piece of shader code. 1647 1648 ValidateProgramARB will store its information in the info log. This 1649 information will either be an empty string or it will contain validation 1650 information. 1651 1652 ValidateProgramARB is typically only useful during application 1653 development. An application should not expect different OpenGL 1654 implementations to produce identical information. 1655 1656 2.16 Undefined Behavior 1657 1658 By addressing arrays or matrices in a shader it is possible to index 1659 outside the declared extent of a uniform. Thus it could be possible to 1660 overwrite critical GL data that is stored next to the uniform in memory. 1661 What this data could be is GL implementation specific. The OpenGL 1662 Shading Language states that it is undefined what happens in this case. 1663 1664 The system environment the OpenGL implementation runs in can set certain 1665 rules, or good practices, that restrict certain behavior. For example, 1666 on a modern OS it is not allowed to overwrite data in someone else's 1667 address space. Similarly it would therefore not be allowed to overwrite 1668 GL data that belongs to another process. This could be further 1669 restricted by disallowing the ability to overwrite data belonging to 1670 another context within the same process. The GL implementation, in 1671 combination with the system environment, decides what is acceptable 1672 behavior; hence the specification leaves results undefined. 1673 1674 2.17 Required State 1675 1676 The state required to support shader objects consists of: 1677 1678 * The state that must be maintained to indicate which handles are 1679 currently in use as shader object names. 1680 1681 The state required per shader object consists of: 1682 1683 * A handleARB indicating the shader object name. 1684 * An array of arrays of type charARB containing the shader strings, 1685 initially empty. 1686 * An integer holding the length of the concatenation of the shader 1687 strings, including one null termination. 1688 * An array of unsigned integers holding the length of the shader 1689 strings, initially zero. 1690 * An integer holding the value of OBJECT_TYPE_ARB 1691 * An integer holding the value of OBJECT_SUBTYPE_ARB 1692 * A Boolean holding the status of the last compile. 1693 * A Boolean holding the delete status. 1694 * An array of type charARB containing the info log, initially empty. 1695 * An integer holding the length of the info log, including a null 1696 termination. 1697 1698 Initially, no shader objects exist. 1699 1700 The state required to support program objects consists of: 1701 1702 * The state that must be maintained to indicate which handles are 1703 currently in use as program object names. 1704 * One handleARB to store the handle of the program object currently in 1705 use. 1706 1707 The state required per program object consists of: 1708 1709 * A handleARB indicating the program object object name. 1710 * A list of handleARB to keep track of shader objects attached. 1711 * An integer holding the number of attached shader objects. 1712 * A Boolean indicating if the program object has been successfully 1713 linked. 1714 * A Boolean holding the status of the last validation attempt. 1715 * A Boolean holding the delete status. 1716 * An integer holding the value of OBJECT_TYPE_ARB. 1717 * An array of type charARB containing the info log, initially empty. 1718 * An integer holding the length of the info log, including a null 1719 termination. 1720 * An array of type charARB for each active uniform containing its 1721 name, initially empty. 1722 * An integer holding the length of the longest active uniform name, 1723 including a null termination. 1724 * An integer holding the number of active uniforms. 1725 * An integer for each active uniform, containing its size. 1726 * An integer for each active uniform, containing its type. 1727 * An integer for each active uniform, holdings its location. 1728 1729 Initially, no program objects exist. 1730 1731Additions to Chapter 3 of the OpenGL 1.4 Specification (Rasterization) 1732 1733 None 1734 1735Additions to Chapter 4 of the OpenGL 1.4 Specification (Per-Fragment 1736Operations and the Frame Buffer) 1737 1738 None 1739 1740Additions to Chapter 5 of the OpenGL 1.4 Specification (Special Functions) 1741 1742 Add to section 5.4, Display Lists. 1743 1744 Commands that are used to create and manage objects are not included in 1745 display lists, but are executed immediately. These include 1746 DeleteObjectARB, DetachObjectARB, CreateShaderObjectARB, 1747 ShaderSourceARB, CompileShaderARB, CreateProgramObjectARB, 1748 AttachObjectARB, and LinkProgramARB. 1749 1750 Commands that are used to query various pieces of object state are not 1751 included in display lists, but are executed immediately. These include 1752 GetHandleARB, GetObjectParameterfvARB, GetObjectParameterivARB, 1753 GetInfoLogARB, GetUniformfvARB, GetUniformivARB, GetUniformLocationARB, 1754 GetShaderSourceARB, GetActiveUniformARB, GetAttachedObjectsARB and 1755 ValidateProgramARB. 1756 1757Additions to Chapter 6 of the OpenGL 1.4 Specification (State and State Requests) 1758 1759 Add a new section just after section 6.1.11 (p. 214) called 6.1.12 1760 "Generic Object Queries" and renumber section 6.1.12 as 6.1.13. 1761 1762 The command 1763 1764 handleARB GetHandleARB(enum pname) 1765 1766 returns the handle to an object that is in use as part of current state. 1767 <pname> specifies the state item for which the current object is to be 1768 returned and can be one of PROGRAM_OBJECT_ARB. (This list is augmented 1769 by other extensions.) If <pname> is not a valid state item, 0 is 1770 returned. 1771 1772 The commands 1773 1774 void GetObjectParameterfvARB(handleARB obj, enum pname, float *params) 1775 void GetObjectParameterivARB(handleARB obj, enum pname, int *params) 1776 1777 return object specific parameter values for object <obj> in <params>. 1778 The parameter value to return is specified by <pname>. 1779 1780 If <pname> is OBJECT_TYPE_ARB, GetObjectParameter{if}vARB returns 1781 PROGRAM_OBJECT_ARB if <obj> references a program object. It returns 1782 SHADER_OBJECT_ARB if <obj> references any shader object. If <obj> is not 1783 of type PROGRAM_OBJECT_ARB or SHADER_OBJECT_ARB, the error 1784 INVALID_OPERATION is generated. 1785 1786 If <pname> is OBJECT_SUBTYPE_ARB, GetObjectParameter{if}vARB returns the 1787 subtype of a shader object. If <obj> is not of type SHADER_OBJECT_ARB, 1788 the error INVALID_OPERATION is generated. 1789 1790 If <pname> is OBJECT_DELETE_STATUS_ARB, GetObjectParameter{if}vARB 1791 returns 1 or 1.0f if status is TRUE and 0 or 0.0f if status is FALSE. If 1792 <obj> is not of type PROGRAM_OBJECT_ARB or SHADER_OBJECT_ARB, the error 1793 INVALID_OPERATION is generated. 1794 1795 If <pname> is OBJECT_LINK_STATUS_ARB, GetObjectParameter{if}vARB returns 1796 1 or 1.0f if status is TRUE and 0 or 0.0f if status is FALSE. If <obj> 1797 is not of type PROGRAM_OBJECT_ARB, the error INVALID_OPERATION is 1798 generated. 1799 1800 If <pname> is OBJECT_VALIDATE_STATUS_ARB, GetObjectParameter{if}vARB 1801 returns 1 or 1.0f if status is TRUE and 0 or 0.0f if status is FALSE. If 1802 <obj> is not of type PROGRAM_OBJECT_ARB, the error INVALID_OPERATION is 1803 generated. 1804 1805 If <pname> is OBJECT_COMPILE_STATUS_ARB, GetObjectParameter{if}vARB 1806 returns 1 or 1.0f if status is TRUE and 0 or 0.0f if status is FALSE. If 1807 <obj> is not of type SHADER_OBJECT_ARB, the error INVALID_OPERATION is 1808 generated. 1809 1810 If <pname> is OBJECT_INFO_LOG_LENGTH_ARB, GetObjectParameter{if}vARB 1811 returns the length of the info log, including a null termination. If 1812 there is no info log, 0 or 0.0f is returned. If <obj> is not of type 1813 PROGRAM_OBJECT_ARB or SHADER_OBJECT_ARB, the error INVALID_OPERATION is 1814 generated. 1815 1816 If <pname> is OBJECT_ATTACHED_OBJECTS_ARB, GetObjectParameter{if}vARB 1817 returns the number of objects attached. If no objects are attached, 0 or 1818 0.0f is returned. If <obj> is not of type PROGRAM_OBJECT_ARB the error 1819 INVALID_OPERATION is generated. 1820 1821 If <pname> is OBJECT_ACTIVE_UNIFORMS_ARB, GetObjectParameter{if}vARB 1822 returns the number of active uniforms. If no active uniforms exist, 0 or 1823 0.0f is returned. If <obj> is not of type PROGRAM_OBJECT_ARB the error 1824 INVALID_OPERATION is generated. 1825 1826 If <pname> is OBJECT_ACTIVE_UNIFORM_MAX_LENGTH_ARB, 1827 GetObjectParameter{if}vARB returns the length of the longest active 1828 uniform name, including a null termination. If no active uniforms exist, 1829 0 or 0.0f is returned. If <obj> is not of type PROGRAM_OBJECT_ARB the 1830 error INVALID_OPERATION is generated. 1831 1832 If <pname> is OBJECT_SHADER_SOURCE_LENGTH_ARB, 1833 GetObjectParameter{if}vARB returns the length of the concatenation of 1834 the source strings making up the shader source, including a null 1835 termination. If no source exists, 0 or 0.0f is returned. If <obj> is not 1836 of type SHADER_OBJECT_ARB the error INVALID_OPERATION is generated. 1837 1838 If an error occurred, the return parameter <params> will be unmodified. 1839 1840 The command 1841 1842 void GetAttachedObjectsARB(handleARB containerObj, sizei maxCount, 1843 sizei *count, handleARB *obj) 1844 1845 returns the handles of objects attached to <containerObj> in <obj>. The 1846 actual number of object handles written by the GL into <obj> is returned 1847 in <count>. If no objects are attached, <count> is set to zero. If 1848 <count> is NULL then the GL ignores this parameter. The maximum number 1849 of handles the GL is allowed to write into <obj> is passed in by 1850 <maxCount>. The number of objects attached to <containerObj> is given by 1851 OBJECT_ATTACHED_OBJECTS_ARB, which can be queried with 1852 GetObjectParameter{if}vARB. If <containerObj> is not of type 1853 PROGRAM_OBJECT_ARB, the error INVALID_OPERATION is generated. If an 1854 error occurred, the return parameters <count> and <obj> will be 1855 unmodified. 1856 1857 A string that contains information about the last link or validation 1858 attempt and last compilation attempt are kept per program or shader 1859 object. This string is called the info log and can be obtained with the 1860 command: 1861 1862 void GetInfoLogARB(handleARB obj, sizei maxLength, sizei *length, 1863 charARB *infoLog) 1864 1865 This command returns the info log string in <infoLog>. This string will 1866 be null terminated. The actual number of characters written by the GL 1867 into <infoLog> is returned in <length>, excluding the null termination. 1868 If <length> is NULL then the GL ignores this parameter. The maximum 1869 number of characters the GL is allowed to write into <infoLog> is passed 1870 in by <maxLength>. The number of characters in the info log is given by 1871 OBJECT_INFO_LOG_LENGTH_ARB, which can be queried with 1872 GetObjectParameter{fi}vARB. If <obj> is a shader object, the returned 1873 info log will either be an empty string or it will contain information 1874 about the last compilation attempt for that object. If <obj> is a 1875 program object, the returned info log will either be an empty string or 1876 it will contain information about the last link attempt or last 1877 validation attempt for that object. If <obj> is not of type 1878 PROGRAM_OBJECT_ARB or SHADER_OBJECT_ARB, the error INVALID_OPERATION is 1879 generated. If an error occurred, the return parameters <length> and 1880 <infoLog> will be unmodified. 1881 1882 The info log is typically only useful during application development and 1883 an application should not expect different OpenGL implementations to 1884 produce identical info logs. 1885 1886 The command 1887 1888 void GetShaderSourceARB(handleARB obj, sizei maxLength, 1889 sizei *length, charARB *source) 1890 1891 will return in <source> the string making up the source code for the 1892 shader object <obj>. The string <source> will be null terminated. The 1893 actual number of characters written by the GL into <source> is returned 1894 in <length>, excluding the null termination. If <length> is NULL then 1895 the GL ignores this parameter. The maximum number of characters the GL 1896 is allowed to write into <source> is passed in by <maxLength>. The 1897 string <source> is a concatenation of the strings passed to OpenGL using 1898 ShaderSourceARB. The length of this concatenation is given by 1899 OBJECT_SHADER_SOURCE_LENGTH_ARB, which can be queried with 1900 GetObjectParameter{if}vARB. If <obj> is not of type SHADER_OBJECT_ARB, 1901 the error INVALID_OPERATION is generated. If an error occurred, the 1902 return parameters <length> and <source> will be unmodified. 1903 1904 The commands 1905 1906 void GetUniformfvARB(handleARB programObj, int location, float *params) 1907 void GetUniformivARB(handleARB programObj, int location, int *params) 1908 1909 return the value or values of the uniform at location <location> for 1910 program object <programObj> in the array <params>. The type of the 1911 uniform at <location> determines the number of values returned. The 1912 error INVALID_OPERATION is generated if <programObj> is not of type 1913 PROGRAM_OBJECT_ARB or if <programObj> has not been linked successfully 1914 or if <location> is not a valid location for <programObj>. In order to 1915 query the values of an array of uniforms a GetUniform*ARB command needs 1916 to be issued for each array element. If the uniform queried is a matrix, 1917 the values of the matrix are returned in column major order. If an error 1918 occurred, the return parameter <params> will be unmodified. 1919 1920 Add to Table 6.3: State Variable Types (p. 217) 1921 1922 H Object handle 1923 1924Additions to Appendix A of the OpenGL 1.4 Specification (Invariance) 1925 1926 None 1927 1928Additions to the AGL/GLX/WGL Specifications 1929 1930 Analogous to sharing display lists and texture objects, it is possible 1931 to share the name space for handles for all objects across a set of 1932 contexts, as long as the server sides of the contexts share the same 1933 address space. No change is made to the AGL/GLX/WGL API. If handles are 1934 shared across contexts the data belonging to those objects are shared as 1935 well. Changes to objects shared between multiple rendering contexts will 1936 be serialized (i.e., the changes will occur in a specific order). 1937 1938 Changes to a program object made by one rendering context are not 1939 guaranteed to take effect in another rendering context until the other 1940 calls UseProgramObjectARB for that object. 1941 1942 When a program object is deleted by one rendering context, the object 1943 itself is not destroyed until it is no longer the current program object 1944 in any context. 1945 1946 When a shader object is deleted by one rendering context, the object 1947 itself is not destroyed until it is no longer attached to any program 1948 object in any context. 1949 1950GLX Protocol 1951 1952 The following rendering commands are sent to the server as part of a 1953 glXRender request: 1954 1955 DeleteObjectARB 1956 1957 2 8 rendering command length 1958 2 238 rendering command opcode 1959 4 CARD32 obj 1960 1961 DetachObjectARB 1962 1963 2 12 rendering command length 1964 2 239 rendering command opcode 1965 4 CARD32 containerObj 1966 4 CARD32 attachedObj 1967 1968 CompileShaderARB 1969 1970 2 8 rendering command length 1971 2 240 rendering command opcode 1972 4 CARD32 shaderObj 1973 1974 AttachObjectARB 1975 1976 2 12 rendering command length 1977 2 241 rendering command opcode 1978 4 CARD32 containerObj 1979 4 CARD32 obj 1980 1981 LinkProgramARB 1982 1983 2 8 rendering command length 1984 2 242 rendering command opcode 1985 4 CARD32 programObj 1986 1987 UseProgramObjectARB 1988 1989 2 8 rendering command length 1990 2 243 rendering command opcode 1991 4 CARD32 programObj 1992 1993 ValidateProgramARB 1994 1995 2 8 rendering command length 1996 2 244 rendering command opcode 1997 4 CARD32 programObj 1998 1999 Uniform1fARB 2000 2001 2 12 rendering command length 2002 2 245 rendering command opcode 2003 4 INT32 location 2004 4 FLOAT32 v0 2005 2006 Uniform2fARB 2007 2008 2 16 rendering command length 2009 2 246 rendering command opcode 2010 4 INT32 location 2011 4 FLOAT32 v0 2012 4 FLOAT32 v1 2013 2014 Uniform3fARB 2015 2016 2 20 rendering command length 2017 2 247 rendering command opcode 2018 4 INT32 location 2019 4 FLOAT32 v0 2020 4 FLOAT32 v1 2021 4 FLOAT32 v2 2022 2023 Uniform4fARB 2024 2 24 rendering command length 2025 2 248 rendering command opcode 2026 4 INT32 location 2027 4 FLOAT32 v0 2028 4 FLOAT32 v1 2029 4 FLOAT32 v2 2030 4 FLOAT32 v3 2031 2032 Uniform1iARB 2033 2034 2 12 rendering command length 2035 2 249 rendering command opcode 2036 4 INT32 location 2037 4 INT32 v0 2038 2039 Uniform2iARB 2040 2041 2 16 rendering command length 2042 2 250 rendering command opcode 2043 4 INT32 location 2044 4 INT32 v0 2045 4 INT32 v1 2046 2047 Uniform3iARB 2048 2049 2 20 rendering command length 2050 2 251 rendering command opcode 2051 4 INT32 location 2052 4 INT32 v0 2053 4 INT32 v1 2054 4 INT32 v2 2055 2056 Uniform4iARB 2057 2058 2 24 rendering command length 2059 2 252 rendering command opcode 2060 4 INT32 location 2061 4 INT32 v0 2062 4 INT32 v1 2063 4 INT32 v2 2064 4 INT32 v3 2065 2066 The following rendering commands are sent to the server as part of a 2067 glXRender request or as a glXRenderLarge request: 2068 2069 ShaderSourceARB 2070 2071 2 12+(count*4)+n+p rendering command length 2072 2 253 rendering command opcode 2073 4 CARD32 shaderObj 2074 4 CARD32 count 2075 4*count LISTofINT32 length 2076 n LISTofBYTE string. n is described below 2077 p unused, p=pad(n) 2078 2079 If the command is encoded in a glXRenderLarge request, the 2080 command opcode and command length fields above are expanded to 2081 4 bytes each: 2082 2083 4 16+(count*4)+n+p rendering command length 2084 4 253 rendering command opcode 2085 2086 n is the sum of the length of all the strings in the array passed 2087 in as <string>. The length of each string i, where i = [0, <count>), 2088 is strlen(<string[i]>) if <length> is NULL or if <length[i]> is 2089 negative. Otherwise, the length of string i is <length[i]>. If 2090 <count> is 0, n is 0. 2091 2092 Uniform1fvARB 2093 2094 2 12+count*4 rendering command length 2095 2 254 rendering command opcode 2096 4 INT32 location 2097 4 CARD32 count 2098 4*count LISTofFLOAT32 value 2099 2100 If the command is encoded in a glXRenderLarge request, the 2101 command opcode and command length fields above are expanded to 2102 4 bytes each: 2103 2104 4 16+count*4 rendering command length 2105 4 254 rendering command opcode 2106 2107 Uniform2fvARB 2108 2109 2 12+count*4*2 rendering command length 2110 2 255 rendering command opcode 2111 4 INT32 location 2112 4 CARD32 count 2113 4*count*2 LISTofFLOAT32 value 2114 2115 If the command is encoded in a glXRenderLarge request, the 2116 command opcode and command length fields above are expanded to 2117 4 bytes each: 2118 2119 4 16+count*4*2 rendering command length 2120 4 255 rendering command opcode 2121 2122 Uniform3fvARB 2123 2124 2 12+count*4*3 rendering command length 2125 2 256 rendering command opcode 2126 4 INT32 location 2127 4 CARD32 count 2128 4*count*3 LISTofFLOAT32 value 2129 2130 If the command is encoded in a glXRenderLarge request, the 2131 command opcode and command length fields above are expanded to 2132 4 bytes each: 2133 2134 4 16+count*4*3 rendering command length 2135 4 256 rendering command opcode 2136 2137 Uniform4fvARB 2138 2139 2 12+count*4*4 rendering command length 2140 2 257 rendering command opcode 2141 4 INT32 location 2142 4 CARD32 count 2143 4*count*4 LISTofFLOAT32 value 2144 2145 If the command is encoded in a glXRenderLarge request, the 2146 command opcode and command length fields above are expanded to 2147 4 bytes each: 2148 2149 4 16+count*4*4 rendering command length 2150 4 257 rendering command opcode 2151 2152 Uniform1ivARB 2153 2154 2 12+count*4 rendering command length 2155 2 258 rendering command opcode 2156 4 INT32 location 2157 4 CARD32 count 2158 4*count LISTofINT32 value 2159 2160 If the command is encoded in a glXRenderLarge request, the 2161 command opcode and command length fields above are expanded to 2162 4 bytes each: 2163 2164 4 16+count*4 rendering command length 2165 4 258 rendering command opcode 2166 2167 Uniform2ivARB 2168 2169 2 12+count*4*2 rendering command length 2170 2 259 rendering command opcode 2171 4 INT32 location 2172 4 CARD32 count 2173 4*count*2 LISTofINT32 value 2174 2175 If the command is encoded in a glXRenderLarge request, the 2176 command opcode and command length fields above are expanded to 2177 4 bytes each: 2178 2179 4 16+count*4*2 rendering command length 2180 4 259 rendering command opcode 2181 2182 Uniform3ivARB 2183 2184 2 12+count*4*3 rendering command length 2185 2 260 rendering command opcode 2186 4 INT32 location 2187 4 CARD32 count 2188 4*count*3 LISTofINT32 value 2189 2190 If the command is encoded in a glXRenderLarge request, the 2191 command opcode and command length fields above are expanded to 2192 4 bytes each: 2193 2194 4 16+count*4*3 rendering command length 2195 4 260 rendering command opcode 2196 2197 Uniform4ivARB 2198 2199 2 12+count*4*4 rendering command length 2200 2 261 rendering command opcode 2201 4 INT32 location 2202 4 CARD32 count 2203 4*count*4 LISTofINT32 value 2204 2205 If the command is encoded in a glXRenderLarge request, the 2206 command opcode and command length fields above are expanded to 2207 4 bytes each: 2208 2209 4 16+count*4*4 rendering command length 2210 4 261 rendering command opcode 2211 2212 UniformMatrix2fvARB 2213 2214 2 16+4*count*2*2 rendering command length 2215 2 262 rendering command opcode 2216 4 INT32 location 2217 4 CARD32 count 2218 1 CARD8 transpose 2219 3 CARD8 unused 2220 4*count*2*2 LISTofFLOAT32 value 2221 2222 If the command is encoded in a glXRenderLarge request, the 2223 command opcode and command length fields above are expanded to 2224 4 bytes each: 2225 2226 4 20+4*count*2*2 rendering command length 2227 4 262 rendering command opcode 2228 2229 UniformMatrix3fvARB 2230 2231 2 16+4*count*3*3 rendering command length 2232 2 263 rendering command opcode 2233 4 INT32 location 2234 4 CARD32 count 2235 1 CARD8 transpose 2236 3 CARD8 unused 2237 4*count*3*3 LISTofFLOAT32 value 2238 2239 If the command is encoded in a glXRenderLarge request, the 2240 command opcode and command length fields above are expanded to 2241 4 bytes each: 2242 2243 4 20+4*count*3*3 rendering command length 2244 4 263 rendering command opcode 2245 2246 UniformMatrix4fvARB 2247 2248 2 16+4*count*4*4 rendering command length 2249 2 264 rendering command opcode 2250 4 INT32 location 2251 4 CARD32 count 2252 1 CARD8 transpose 2253 3 CARD8 unused 2254 4*count*4*4 LISTofFLOAT32 value 2255 2256 If the command is encoded in a glXRenderLarge request, the 2257 command opcode and command length fields above are expanded to 2258 4 bytes each: 2259 2260 4 20+4*count*4*4 rendering command length 2261 4 264 rendering command opcode 2262 2263 2264 The following non-rendering commands are added. 2265 2266 GetHandleARB 2267 2268 1 CARD8 opcode (X assigned) 2269 1 167 GLX opcode 2270 2 3 request length 2271 4 GLX_CONTEXT_TAG context tag 2272 4 ENUM pname 2273 => 2274 1 1 reply 2275 1 unused 2276 2 CARD16 sequence number 2277 4 0 reply length 2278 4 CARD32 return value 2279 20 unused 2280 2281 CreateShaderObjectARB 2282 2283 1 CARD8 opcode (X assigned) 2284 1 168 GLX opcode 2285 2 3 request length 2286 4 GLX_CONTEXT_TAG context tag 2287 4 ENUM shaderType 2288 => 2289 1 1 reply 2290 1 unused 2291 2 CARD16 sequence number 2292 4 0 reply length 2293 4 CARD32 return value 2294 20 unused 2295 2296 CreateProgramObjectARB 2297 2298 1 CARD8 opcode (X assigned) 2299 1 169 GLX opcode 2300 2 2 request length 2301 4 GLX_CONTEXT_TAG context tag 2302 => 2303 1 1 reply 2304 1 unused 2305 2 CARD16 sequence number 2306 4 0 reply length 2307 4 CARD32 return value 2308 20 unused 2309 2310 GetObjectParameterfvARB 2311 2312 1 CARD8 opcode (X assigned) 2313 1 170 GLX opcode 2314 2 4 request length 2315 4 GLX_CONTEXT_TAG context tag 2316 4 CARD32 obj 2317 4 ENUM pname 2318 => 2319 1 1 reply 2320 1 unused 2321 1 CARD16 sequence number 2322 4 m reply length, m = ((n == 1) ? 0 : n) 2323 4 unused 2324 4 CARD32 n 2325 2326 if (n = 1) this follows: 2327 2328 4 FLOAT32 params 2329 12 unused 2330 2331 otherwise this follows: 2332 2333 16 unused 2334 n*4 LISTofFLOAT32 params 2335 2336 Note that n may be zero, indicating that a GL error occured. 2337 2338 GetObjectParameterivARB 2339 2340 1 CARD8 opcode (X assigened) 2341 1 171 GLX opcode 2342 2 4 request length 2343 4 GLX_CONTEXT_TAG context tag 2344 4 CARD32 obj 2345 4 ENUM pname 2346 => 2347 1 1 reply 2348 1 unused 2349 2 CARD16 sequence number 2350 4 m reply length, m = ((n == 1) ? 0 : n) 2351 4 unused 2352 4 CARD32 n 2353 2354 if (n = 1) this follows: 2355 2356 4 INT32 params 2357 12 unused 2358 2359 otherwise this follows: 2360 2361 16 unused 2362 n*4 LISTofINT32 params 2363 2364 Note that n may be zero, indicating that a GL error occured. 2365 2366 GetInfoLogARB 2367 2368 1 CARD8 opcode (X assigned) 2369 1 172 GLX opcode 2370 2 4 request length 2371 4 GLX_CONTEXT_TAG context tag 2372 4 CARD32 obj 2373 4 CARD32 maxLength 2374 => 2375 1 1 reply 2376 1 unused 2377 2 CARD16 sequence number 2378 4 m reply length, m = (n+p)/4 2379 4 unused 2380 4 CARD32 n, as defined below. 2381 16 unused 2382 n LISTofBYTE infoLog 2383 p unused, p = pad(n) 2384 2385 n is calculated on the server as strlen(<infoLog>) + 1 on success, or 2386 0 if there was an error retrieving the info log. If <length> is not 2387 NULL, it is set to max(1, n) - 1. 2388 2389 GetAttachedObjectsARB 2390 2391 1 CARD8 opcode (X assigned) 2392 1 173 GLX opcode 2393 2 4 request length 2394 4 GLX_CONTEXT_TAG context tag 2395 4 CARD32 containerObj 2396 4 CARD32 maxCount 2397 => 2398 1 1 reply 2399 1 unused 2400 2 CARD16 sequence number 2401 4 m reply length, m = (n == 1 ? 0 : n) 2402 4 unused 2403 4 CARD32 count, n = count 2404 2405 if (n = 1) this follows: 2406 2407 4 CARD32 obj 2408 12 unused 2409 2410 otherwise this follows: 2411 2412 16 unused 2413 4*n LISTofCARD32 obj 2414 2415 Note that n may be zero, indicating that a GL error occured. 2416 2417 GetUniformLocationARB 2418 1 CARD8 opcode (X assigned) 2419 1 174 GLX opcode 2420 2 (12+n+p)/4 request length 2421 4 GLX_CONTEXT_TAG context tag 2422 4 CARD32 programObj 2423 n LISTofBYTE name, n = strlen(name)+1 2424 p unused, p = pad(n) 2425 => 2426 1 1 reply 2427 1 unused 2428 2 CARD16 sequence number 2429 4 0 reply length 2430 4 CARD32 return value 2431 20 unused 2432 2433 GetActiveUniformARB 2434 2435 1 CARD8 opcode (X assigned) 2436 1 175 GLX opcode 2437 2 5 request length 2438 4 GLX_CONTEXT_TAG context tag 2439 4 CARD32 programObj 2440 4 CARD32 index 2441 4 CARD32 maxLength 2442 => 2443 1 1 reply 2444 1 unused 2445 2 CARD16 sequence number 2446 4 m reply length, m = (n+p)/4 2447 4 unused 2448 4 CARD32 n, n = length+1 2449 4 CARD32 size 2450 4 ENUM type 2451 8 unused 2452 n LISTofBYTE name 2453 p unused , p = pad(n) 2454 2455 n is calculated on the server as strlen(<name>) + 1 on success, or 0 2456 if there was an error retrieving the active uniform's name. If 2457 <length> is not NULL, it is set to max(1, n) - 1. 2458 2459 GetUniformfvARB 2460 2461 1 CARD8 opcode (X assigned) 2462 1 176 GLX opcode 2463 2 4 request length 2464 4 GLX_CONTEXT_TAG context rag 2465 4 CARD32 programObj 2466 4 INT32 location 2467 => 2468 1 1 reply 2469 1 unused 2470 2 CARD16 sequence number 2471 4 m reply length, m = ((n == 1) ? 0 : n) 2472 4 unused 2473 4 CARD32 n 2474 2475 if (n = 1) this follows: 2476 2477 4 FLOAT32 params 2478 12 unused 2479 2480 otherwise this follows: 2481 2482 16 unused 2483 4*n LISTofFLOAT32 params 2484 2485 Note that n may be zero, indicating that a GL error occured. 2486 2487 GetUniformivARB 2488 2489 1 CARD8 opcode (X assigned) 2490 1 177 GLX opcode 2491 2 4 request length 2492 4 GLX_CONTEXT_TAG context rag 2493 4 CARD32 programObj 2494 4 INT32 location 2495 => 2496 1 1 reply 2497 1 unused 2498 2 CARD16 sequence number 2499 4 m reply length, m = ((n == 1) ? 0 : n) 2500 4 unused 2501 4 INT32 n 2502 2503 if (n = 1) this follows: 2504 2505 4 INT32 params 2506 12 unused 2507 2508 otherwise this follows: 2509 2510 16 unused 2511 4*n LISTofINT32 params 2512 2513 Note that n may be zero, indicating that a GL error occured. 2514 2515 GetShaderSourceARB 2516 2517 1 CARD8 opcode (X assigned) 2518 1 178 GLX opcode 2519 2 4 request length 2520 4 GLX_CONTEXT_TAG context tag 2521 4 CARD32 obj 2522 4 CARD32 maxLength 2523 => 2524 1 1 reply 2525 1 unused 2526 2 CARD16 sequence number 2527 4 m reply length, m = (n+p)/4 2528 4 unused 2529 4 CARD32 length 2530 16 unused 2531 n LISTofBYTE source, n = length+1 2532 p unused, p = pad(n) 2533 2534 Note that n may be zero, indicating that a GL error occured. 2535 2536Errors 2537 2538 The error INVALID_VALUE is generated by any command that takes one or 2539 more handles as input, and one or more of these handles are not an 2540 object handle generated by OpenGL. Note that this error is also set when 2541 passing in the value 0 as a handle, except for UseProgramObjectARB and 2542 DeleteObject. Passing in 0 to UseProgramObjectARB is valid, and ignored 2543 by DeleteObject. 2544 2545 The error INVALID_OPERATION is generated by AttachObjectARB if <obj> is 2546 not of type SHADER_OBJECT_ARB or if <containerObj> is not of type 2547 PROGRAM_OBJECT_ARB. 2548 2549 The error INVALID_OPERATION is generated by AttachObjectARB if <obj> is 2550 already attached to <containerObj>. 2551 2552 The error INVALID_OPERATION is generated by DetachObjectARB if 2553 <attachedObj> is not attached to <containerObj>. 2554 2555 The error INVALID_OPERATION is generated by DetachObjectARB if 2556 <containerObj> is not of type PROGRAM_OBJECT_ARB. 2557 2558 The error INVALID_OPERATION is generated by ShaderSourceARB and 2559 CompileShaderARB if <shaderObj> is not of type SHADER_OBJECT_ARB. 2560 2561 The error INVALID_OPERATION is generated by LinkProgramARB if 2562 <programObj> is not of type PROGRAM_OBJECT_ARB. 2563 2564 The error INVALID_OPERATION is generated by UseProgramObjectARB if 2565 <programObj> is not of type PROGRAM_OBJECT_ARB. 2566 2567 The error INVALID_OPERATION is generated by UseProgramObjectARB if 2568 <programObj> could not be made part of the current state. 2569 2570 The error INVALID_OPERATION is generated by GetUniformLocationARB if 2571 <programObj> is not of type PROGRAM_OBJECT_ARB or if <programObj> has 2572 not been linked successfully. 2573 2574 The error INVALID_OPERATION is generated by GetActiveUniformARB if 2575 <programObj> is not of type PROGRAM_OBJECT_ARB. 2576 2577 The error INVALID_VALUE is generated by GetActiveUniformARB if <index> 2578 is greater than or equal to OBJECT_ACTIVE_UNIFORMS_ARB. 2579 2580 The error INVALID_OPERATION is generated by the Uniform*ARB commands if 2581 the size does not match the size of the uniform declared in the shader. 2582 2583 The error INVALID_OPERATION is generated by the Uniform*ARB commands if 2584 the type does not match the type of the uniform declared in the shader, 2585 if the uniform is not of type Boolean. 2586 2587 The error INVALID_OPERATION is generated by the Uniform*ARB commands if 2588 <location> is not -1 and <location> does not exist for the program object 2589 currently in use. 2590 2591 The error INVALID_OPERATION is generated by the Uniform*ARB commands if 2592 there is no program object in use. 2593 2594 The error INVALID_OPERATION is generated if a uniform command other than 2595 Uniform1i{v}ARB is used to load a sampler value. 2596 2597 The error INVALID_OPERATION is generated by ValidateProgramARB if 2598 <programObj> is not of type PROGRAM_OBJECT_ARB. 2599 2600 The error INVALID_OPERATION is generated by GetObjectParameter{if}vARB 2601 if <pname> is OBJECT_TYPE_ARB or OBJECT_DELETE_STATUS_ARB or 2602 OBJECT_INFO_LOG_LENGTH_ARB and <obj> is not of type PROGRAM_OBJECT_ARB 2603 or SHADER_OBJECT_ARB. 2604 2605 The error INVALID_OPERATION is generated by GetObjectParameter{if}vARB 2606 if <pname> is OBJECT_LINK_STATUS_ARB or OBJECT_VALIDATE_STATUS_ARB or 2607 OBJECT_ATTACHED_OBJECTS_ARB or OBJECT_ACTIVE_UNIFORMS_ARB or 2608 OBJECT_ACTIVE_UNIFORM_MAX_LENGTH_ARB and <obj> is not of type 2609 PROGRAM_OBJECT_ARB. 2610 2611 The error INVALID_OPERATION is generated by GetObjectParameter{if}vARB 2612 if <pname> is OBJECT_SUBTYPE_ARB or OBJECT_COMPILE_STATUS_ARB or 2613 OBJECT_SHADER_SOURCE_LENGTH_ARB and <obj> is not of type 2614 SHADER_OBJECT_ARB. 2615 2616 The error INVALID_OPERATION is generated by GetAttachedObjectsARB if 2617 <containerObj> is not of type PROGRAM_OBJECT_ARB. 2618 2619 The error INVALID_OPERATION is generated by GetInfoLogARB if <obj> is 2620 not of type SHADER_OBJECT_ARB or PROGRAM_OBJECT_ARB. 2621 2622 The error INVALID_OPERATION is generated by GetShaderSourceARB if <obj> 2623 is not of type SHADER_OBJECT_ARB. 2624 2625 The error INVALID_OPERATION is generated by GetUniform{if}vARB if 2626 <programObj> is not of type PROGRAM_OBJECT_ARB or if <programObj> has 2627 not been linked successfully or if <location> is not a valid location 2628 for <programObj>. 2629 2630 The error INVALID_OPERATION is generated if Begin, RasterPos, or any 2631 command that performs an explicit Begin is called if: 2632 2633 - One or more samplers of different types in the current program 2634 object access the same texture image unit. 2635 - More than the maximum allowable texture image units are accessed 2636 based on the count of active samplers and the rest of the GL state 2637 (note that LinkProgramARB can normally resolve this, except for the 2638 case where an ARB_vertex_shader shader is mixed with an 2639 ARB_fragment_program shader or mixed with fixed-function fragment 2640 processing). 2641 2642New State 2643 2644 Initial 2645 Get Value Type Get Command Value Description Sec. Attribute 2646 --------- ---- ------------------------- ------- ----------- ---- --------- 2647 PROGRAM_OBJECT_ARB H GetHandle 0 Handle of current 2.14.2 - 2648 program object 2649 2650 Table X. New state introduced. 2651 2652 Initial 2653 Get Value Type Get Command Value Description Sec. Attribute 2654 --------- ----- ----------------------- ------------- ----------- ---- --------- 2655 - H object specific object handle 2.14.1 - 2656 - 0+xchar GetInfoLogARB "" Info log for shader 6.1.12 - 2657 objects 2658 - 0+xchar GetShaderSourceARB "" source for a shader 2.14.1 - 2659 OBJECT_TYPE_ARB Z+ GetObjectParameterivARB SHADER_OBJECT Type of object 2.14.1 - 2660 OBJECT_SUBTYPE_ARB Z+ GetObjectParameterivARB - Sub type of object 2.14.1 - 2661 OBJECT_DELETE_STATUS_ARB B GetObjectParameterivARB FALSE Shader deleted 2.14 - 2662 OBJECT_COMPILE_STATUS_ARB B GetObjectParameterivARB FALSE Compile succeeded 2.14.1 - 2663 OBJECT_INFO_LOG_LENGTH_ARB Z+ GetObjectParameterivARB 0 Length of info log 6.1.12 - 2664 OBJECT_SHADER_SOURCE_LENGTH_ARB Z+ GetObjectParameterivARB 0 Length of source code 6.1.12 - 2665 2666 Table X Shader object state. 2667 2668 Initial 2669 Get Value Type Get Command Value Description Sec. Attribute 2670 --------- ----- ----------------------- ------------- ----------- ---- --------- 2671 - 0+xZ+ GetActiveUniformARB - Size of active uniform 2.14.3 - 2672 - 0+xZ+ GetActiveUniformARB - Type of active uniform 2.14.3 - 2673 - 0+xcharARB GetActiveUniformARB "" Name of active uniform 2.14.3 - 2674 - 0+xZ GetUniformLocationARB - Location of active uniform 2.14.3 - 2675 - 0+xchar GetInfoLogARB "" Info log for program objects 6.1.12 - 2676 OBJECT_ATTACHED_OBJECTS_ARB Z+ GetObjectParameterivARB 0 Number of attached objects 6.1.12 - 2677 OBJECT_ACTIVE_UNIFORMS_ARB Z+ GetObjectParameterivARB 0 Number of active uniforms 2.14.3 - 2678 OBJECT_DELETE_STATUS_ARB B GetObjectParameterivARB FALSE Program object deleted 2.14 - 2679 OBJECT_LINK_STATUS_ARB B GetObjectParameterivARB FALSE Link succeeded 2.14.2 - 2680 OBJECT_VALIDATE_STATUS_ARB B GetObjectParameterivARB FALSE Validate succeeded 2.15 - 2681 OBJECT_INFO_LOG_LENGTH_ARB Z+ GetObjectParameterivARB 0 Length of info log 6.1.12 - 2682 OBJECT_TYPE_ARB Z+ GetObjectParameterivARB PROGRAM_OBJECT Type of object 2.14.2 - 2683 OBJECT_ACTIVE_UNIFORM_ 2684 MAX_LENGTH_ARB Z+ GetObjectParameterivARB 0 Max uniform name length 6.1.12 - 2685 - 0+xhandle GetAttachedObjectsARB empty list Shader objects attached 6.1.12 2686 - H object specific object handle 2.14.2 - 2687 2688 Table X Program object state. 2689 2690New Implementation Dependent State 2691 2692 None 2693 2694Sample Usage 2695 2696 For examples on how to use GetUniformLocationARB and the Uniform*ARB 2697 API, see issue 32. 2698 2699 // 2700 // Example usage of GetActiveUniformARB. 2701 // 2702 GLint maxLength; 2703 GLint i, uniformCount; 2704 GLcharARB **name; 2705 GLsizei *length; 2706 GLint *size; 2707 GLenum *type; 2708 2709 // 2710 // Get the number of uniforms, and the length of the longest name. 2711 // 2712 glGetObjectParameterivARB(programObject, 2713 GL_OBJECTS_ACTIVE_UNIFORM_MAX_LENGTH_ARB, 2714 &maxLength); 2715 glGetObjectParameterivARB(programObject, GL_OBJECTS_ACTIVE_UNIFORMS_ARB, 2716 &uniformCount); 2717 2718 // 2719 // Allocate arrays to store the answers in. For simplicity, the return 2720 // from malloc is not checked for NULL. 2721 // 2722 size = (GLint *) malloc(uniformCount * sizeof(GLint)); 2723 type = (GLint *) malloc(uniformCount * sizeof(GLenum)); 2724 length = (GLsizei *) malloc(uniformCount * sizeof(GLsizei)); 2725 name = (GLcharARB **) malloc(uniformCount * sizeof(GLcharARB **)); 2726 2727 // 2728 // Loop over glGetActiveUniformARB and store the results away. 2729 // 2730 for (i = 0; i < uniformCount; i++) { 2731 name[i] = (GLcharARB *) malloc(maxLength * sizeof(GLcharARB)); 2732 glGetActiveUniformARB(programObject, i, maxLength, &length[i], 2733 &size[i], &type[i], name[i]); 2734 } 2735 2736 See the ARB_vertex_shader and ARB_fragment_shader extension documents 2737 for more examples. 2738 2739Revision History 2740 2741 Revision: 0.5 6/5/2002 2742 - First draft for circulation 2743 Revision: 0.51 2744 - Started issues section. Added string discussions and uniform 2745 discussions. 2746 - Added content to the Contributors, and Errors section 2747 - Named and explained all parameters to all API calls 2748 - Added a new GLchar type 2749 - Load/AppendShaderGL2 take a length argument 2750 - GetUniformLocationGL2 takes a length argument for the string passed 2751 in 2752 - GetInfoLogGL2 now also optionally returns the length of the string 2753 - Clarified DetachObjectGL2 and DeleteObject(s)GL2 and their 2754 interaction 2755 Revision 0.52 2756 - Removed NULL_HANDLE_GL2 2757 - Added explanation of what happens when program and shader objects 2758 are shared among contexts. 2759 Revision: 0.60 2760 - Merged GL2_core_objects extension into this one. Core_objects is now 2761 obsolete. 2762 Revision: 0.61 2763 - Took out any reference to 'project'. This term was unnecessary, 2764 since it meant the same as program object. 2765 Revision: 0.62 2766 - Now references V1.0 of OpenGL Shading Language Specification 2767 - Fixed minor typos 2768 - Accepted by the GL2 working group 2769 Revision: 0.63 10/17/2002 2770 - Removed IsObjectGL2(). It overlaps with GetObjectParameter{if}vGL2. 2771 - Expanded GetObjectParameter{if}GL2. Added OBJECT_TYPE_GL2. 2772 Revision: 0.64 10/18/2002 2773 - Added list of entrypoints that are not compiled into a display list 2774 to section 5. 2775 - Updated Errors section. 2776 Revision: 0.65 10/23/2002 2777 - Added GetShaderSourceGL2. 2778 - Added GetUniform{if}vGL2 2779 - Updated errors section. 2780 - Moved shader resources section in here from GL2_vertex_shader. 2781 Revision: 0.7 10/29/2002 2782 - Added issue number 16. 2783 - Second distribution to the GL2 working group. 2784 - Now written against the OpenGL 1.4 specification. 2785 Revision: 0.71 11/26/2002 2786 - Added six more issues discussion uniform loading (issues 7-15). 2787 - Added loadUniform commands to load values for INT and BOOL declared 2788 uniforms. 2789 - Changed the behavior for loadUniforms to allow to load the first N 2790 values if loading into a uniform declared with an extent bigger than 2791 N. 2792 - Made a GLhandle an unsigned integer, read and written only by the GL 2793 - Added high level shading language layering issue 22. This issue came 2794 from the OpenGL Shading Language document. 2795 - Updated resource limits issue number 21. 2796 Revision: 0.72 01/27/2003 2797 - Added issue 24. 2798 - Added to the list of contributors. 2799 - Changed the GLchar type to GLcharGL2 2800 - Changed GLhandle type to GLhandleGL2 2801 Revision: 0.73 02/20/2003 2802 - Updated section 2.14.4. Loading uniforms of the wrong type will 2803 result in undefined shader results. 2804 - Loading more or less data than the declared extent of the uniform is 2805 now handled consistently. 2806 - Added section 2.14.4.1 'Samplers' 2807 - Added an extra error condition for LinkProgramGL2 when using too 2808 many active samplers. 2809 - Added issue 25, explaining how to use samplers for texture access. 2810 - Added issue 26, need for a validate command. 2811 - Added section 2.15, Validation 2812 Revision: 0.74 02/23/2003 2813 - Added use of [] and . (dot) operators in GetUniformLocationGL2 2814 - Refined wording in section 2.14.4.1. 2815 Revision: 0.75 03/27/2003 2816 - Begin can generate an error in certain cases. 2817 - Closed issue 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 and made spec 2818 changes, if necessary, to reflect the resolutions of these issues. 2819 - Added issues 27, 28, 29, 30, 31. 2820 - Changed the loadUniform API. Less entry points, aimed at performance 2821 of loading uniforms. Also added a transpose flag to the matrix ones. 2822 - Updated IP Status section to point to the contributors agreement. 2823 - Removed ObjectParameter*GL2. These are not used anywhere. 2824 - AttachObjectGL2 no longer returns a Boolean. There is no reason that 2825 an attach should ever fail, if a valid program object and shader 2826 object are passed in. 2827 - Defined the lifetime of the pointers returned by GetInfoLogGL2 and 2828 GetShaderSourceGL2. 2829 - Added GetAttachedObjectsGL2. 2830 Revision: 0.76 03/28/2003 2831 - UseProgramObjectGL2 no longer returns anything. It can now be 2832 compiled into a display list. 2833 - Closed issues 14, 15, 30. 2834 - Allowed loading more than one element in a uniform array, by just 2835 querying the location of the first element to be loaded. 2836 - Added the UNIFORM_ERROR_CHECK_GL2 enable. 2837 - Changed GetInfoLogGL2 so that GL only has to maintain at least one 2838 info log for shader objects and at least one for program objects. 2839 - Added section 2.16, undefined behavior 2840 Revision: 0.77 04/03/2003 2841 - AppendShader now takes an array of strings, just like ShaderSource. 2842 - GetShaderSources returns an array of strings. 2843 - Closed issues 16, 17, 18, 19, 20. 2844 Revision: 0.78 04/07/2003 2845 - Closed issues 21, 22, 23, 24, 25, 26. 2846 - Added lifetime to the pointer returned by ValidateProgram. Also 2847 changed ValidateProgram to take a handle to a program object. 2848 - LinkProgramGL2 will now set all uniforms to zero. 2849 - Added GetShaderSourceGL2 example code. 2850 Revision: 0.79 04/09/2003 2851 - Added section 2.17, required state. 2852 - Clarified GetInfoLog, especially when sharing objects across 2853 contexts. 2854 - Changed ValidateProgramGL2 to store its information in the info log. 2855 It'll return a Boolean to indicate a successful validation. 2856 - Clarified the use of the '.' And '[]' operators in 2857 GetUniformLocation. 2858 Revision: 0.80 04/17/2003 2859 - Removed AppendShaderGL2. 2860 - Closed issues 28, 29, 30 and 31. 2861 - Clarified GetUniformLocationGL2 based on Folker's feedback. 2862 - Added GetActiveUniformsGL2. 2863 Revision: 0.81 04/18/2003 2864 - GetUniformLocationGL2 only works for active uniforms now. 2865 - Re-worded GetActiveUniformsGL2 to be more like GetActiveAttribsGL2. 2866 - Added wording explicitly saying that a failed compile or link is not 2867 state neutral (does not revert back to the old state). 2868 - Added a sentence saying that the memory pointer returned by 2869 GetActiveUniforms, GetInfoLog, GetAttachedObjects and 2870 GetShaderSource is owned by OpenGL and should not be overwritten by 2871 the caller. 2872 Revision: 0.82 04/27/2003 2873 - Forgot to close issue 27. 2874 - Changed a few occurances of "char" to charGL2. 2875 - Updated language describing GetUniformLocationGL2. 2876 - Changed the location of the Contributors License to a publicly 2877 accessible place on www.3dlabs.com. 2878 - GetActiveUniformsGL2 is not display-listable. 2879 - Removed one error condition for ValidateProgramGL2. 2880 - Added errors for GetAttachedObjectsGL2. 2881 - Renamed the following functions: 2882 - glLoadShader --> glShaderSource 2883 - glGetShaderString --> glGetShaderSource 2884 - glAttachShaderObject --> glAttachObject 2885 - glGetAttachedShaderObjects --> glGetAttachedObjects 2886 - Clarified that GetActiveUniformsGL2 will return as much information 2887 as possible. If it has none, it'll return a count of zero. 2888 - Numerous clarifications and some reordering of paragraphs based on 2889 Pat's feedback. 2890 - Spelled out three reasons why LinkProgram can fail. 2891 - Spelled out that the Uniform*GL2 command used needs to match both 2892 the type and the size of a uniform declared in a shader. 2893 - Updated the error checking rules for the Uniform*GL2 commands. 2894 - Passing in '0', or a handle that is not an object handle generated 2895 by the GL, results in the error INVALID_VALUE. All other calls that 2896 get passed a valid handle, but that handle is of the wrong type for 2897 that operation, set an INVALID_OPERATION error. 2898 - Added issue 32, explaining GetUniformLocationGL2 and uniform 2899 loading. 2900 Revision: 0.83 04/28/2003 2901 - Added more state tables. 2902 - Added Kent Lin to the list of contributors. 2903 Revision: 0.84 04/29/2003 2904 - Added a few more examples to issue 32. 2905 - Clarified the Errors section with respect to passing in 0 as a 2906 handle. 2907 - Version voted on, and approved, by the ARB-GL2 working group. 2908 Revision: 0.85 05/09/2003 2909 - Fixed a mistake in the program object state table for GetInfoLogGL2. 2910 - Fixed a mistake in the resolution of issue 27. 2911 - Clarified the resolution of issue 17. 2912 - Clarified that in case of doubt by the compiler/linker, a uniform 2913 will be marked as active. Section 2.14.3 (intro). 2914 - Clarified that you need to pass in three NULL pointers to 2915 GetActiveUniformsGL2, to only get the count of active uniforms. 2916 - Clarified the lifetime of the pointers returned by 2917 GetActiveUniformsGL2, GetShaderSourceGL2 and GetAttachedObjectsGL2. 2918 - Fixed a typo in the first entry in the Errors section. 2919 - Changed the count parameter in the Uniform*vGL2 commands to be of 2920 type sizei. Also did this for ShaderSourceGL2. 2921 - Expanded the two paragraphs explaining how Uniform*GL2 works into 2922 several smaller ones. 2923 - Clarified that GetInfoLogGL2 returns NULL if the handle passed in is 2924 invalid, or not a program or shader object. 2925 - Added fourth implicit error rule to section 2.5, GL Errors. Note 2926 that this rule was already in the Errors section. 2927 - Added Jon Leech, Evan Hart, Benjamin Lipchak and Jeremy Sandmel to 2928 the list of contributors. 2929 - Assigned enum values. 2930 Revision: 0.86 05/15/2003 2931 - Assigned missing enum value to SHADER_OBJECT_GL2. 2932 - Replaced all GL2 occurrences with ARB. Fixed some typos. 2933 - Added several more to the contributors list. If anyone is still left 2934 out, let Bill Licea Kane, Jon Leech or myself know. 2935 Revision: 0.87 06/13/2003 2936 - Changed resolution of issue 27 and the description of GetInfoLog to 2937 have an info log per object. Removed the info log language from the 2938 AGL/GLX/WGL section. 2939 - Changed the resolution of issue 14, 15, 25 (uniform API name). 2940 - Changed the discussion and resolution of issue 30. (uniform 2941 loading). 2942 - Added issue 33. 2943 - Changed the uniform API commands. The type of the uniform is no 2944 longer encoded in the name of the API. 2945 - Updated section 2.14.4, samplers. 2946 - Updated the Errors section w.r.t. uniform loading 2947 - Updated section 2.16, undefined behavior. 2948 - Deleted DeleteObjectsARB. 2949 - Removed the Boolean return from CompileShaderARB, LinkProgramARB and 2950 ValidateProgramARB. 2951 - Added several new error conditions for GetObjectParameter{if}vARB to 2952 the Errors section an section 6.1.12. 2953 - Updated the New State and Required State sections. 2954 - Changed GetInfoLog to no longer return a pointer to GL memory. 2955 - Changed GetAttachedObjects to no longer return a pointer to GL 2956 memory. 2957 - Changed GetActiveUniform to no longer return a pointer to GL memory. 2958 This call now returns data for one active uniform, instead of all 2959 active uniforms. Also added its returns (type, size and name) to the 2960 state tables and Required State section. 2961 - Changed GetShaderSource to no longer return a pointer to GL memory. 2962 - Added OBJECT_SUBTYPE_ARB, OBJECT_DELETE_STATUS_ARB, 2963 OBJECT_COMPILE_STATUS_ARB, OBJECT_LINK_STATUS_ARB, 2964 OBJECT_VALIDATE_STATUS_ARB, OBJECT_INFO_LOG_LENGTH_ARB, 2965 OBJECT_ATTACHED_OBJECTS_ARB, OBJECT_ACTIVE_UNIFORMS_ARB, 2966 OBJECT_ACTIVE_UNIFORM_MAX_LENGTH_ARB, 2967 OBJECT_SHADER_SOURCE_LENGTH_ARB as a queriable parameter to 2968 GetObjectParameter{if}vARB. 2969 - Modified the introduction to section 2.14 to mention texture and 2970 display list objects. 2971 - Added issue 34. 2972 - Updated the example section with a new example. 2973 - Re-ordered the Errors section. They are now in the order of API 2974 calls described in Sections 2-6. 2975 - Language clean-up throughout the document. 2976 - Consistently used "OpenGL Shading Language" where appropriate (This 2977 is the official name). 2978 - Changed issue 5. This issue is now obsolete, with the new GetInfoLog 2979 API. 2980 - Clarified section 2.14.4, Samplers. The values to load range from 0 2981 to to max available texture image units. 2982 - ARB approved version. 2983 Revision: 0.88 03/29/2004 2984 - Added ARB extension number (31) and edited the status paragraph. 2985 - GetActiveUniform now returns types for samplers. 2986 - If at least one element in a uniform array is active, then this 2987 array will be reported by GetActiveUniform as being active starting 2988 at element 0 through the highest element used. Added issue 35 2989 explaining this in detail. 2990 - Passing in a location of -1 to Uniform*ARB will be silently ignored 2991 (no GL error will be generated). Also added issue 36 explaining 2992 this. 2993 - DeleteObject will silently ignore the value 0. Added issue 37. 2994 - The current program object handle is no longer part of the 'current' 2995 state. 2996 - Specified that GetUniform returns values in column major order for 2997 matrices. Also clarified that GetUniform returns only one element of 2998 an array of uniforms. Added issue 38. 2999 - Specified what happens when ValidateProgramARB fails. This means 3000 that the program object will not execute, and no fragments will be 3001 rendered. 3002 - Added 'const' to the data passed in the Uniform*vARB commands. 3003 - Clarified that return parameters of the various Get commands are 3004 unmodified if an error occurred. 3005 - Added issue 39. 3006 - Added issue 40, and clarified failed re-link behavior in the spec. 3007 - Added issue 41. 3008 - Clarified that the compile status of a shader object does not change 3009 when source is loaded in it. 3010 - Clarified that the link status of a program object is not affected 3011 by attaching or detaching or re-compiling attached shader objects. 3012 - Few fixes to the Errors section. 3013 - Clarified GetUniformLocation and GetActiveUniform when addressing 3014 the first element of an array. Added issue 42 explaining this. 3015 - Added issue 43, 44 and 45. 3016 Revision: 0.89 04/06/2004 3017 - Updated the Shading Language Version referenced to the now official 3018 version 1.10. 3019 - Added language describing the Uniform* loading commands that 3020 Uniform1i{v} is used to load samplers. 3021 - Clarified issues 36, 42 and 43 based on Pat's feedback. 3022 - Changed the examples in issue 45 a bit. Hopefully for the better. 3023 - Added issue 46. 3024 - Removed an error condition I had added earlier for glBegin(). 3025 - Expanded section 2.15 to include the exact conditions when 3026 validation is allowed to fail. Previously these conditions were only 3027 in the Errors section, listed for glBegin(). 3028 - ARB-GL2 workgroup approved version. 3029 Revision: 0.90 12/14/2009 3030 - Added GLX protocol 3031 3032