1Name 2 3 ARB_uniform_buffer_object 4 5Name Strings 6 7 GL_ARB_uniform_buffer_object 8 9Contact 10 11 Benj Lipchak, APPLE (lipchak 'at' apple.com) 12 John Rosasco, APPLE (jdr 'at' apple.com) 13 Jeremy Sandmel, APPLE (jsandmel 'at' apple.com) 14 Pat Brown, NVIDIA (pbrown 'at' nvidia.com) 15 16Contributors 17 18 Rob Barris 19 Keith Bauer 20 Bob Beretta 21 Pat Brown 22 Nick Burns 23 Matt Collins 24 Michael Gold 25 John Kessenich 26 Jon Leech 27 Barthold Lichtenbelt 28 Benj Lipchak 29 Bruce Merry 30 John Rosasco 31 Jeremy Sandmel 32 Geoff Stahl 33 34Notice 35 36 Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at 37 http://www.khronos.org/registry/speccopyright.html 38 39Specification Update Policy 40 41 Khronos-approved extension specifications are updated in response to 42 issues and bugs prioritized by the Khronos OpenGL Working Group. For 43 extensions which have been promoted to a core Specification, fixes will 44 first appear in the latest version of that core Specification, and will 45 eventually be backported to the extension document. This policy is 46 described in more detail at 47 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 48 49Status 50 51 Complete. Approved by the ARB on February 17, 2009. 52 53Version 54 55 Last Modified Date: 2015/06/23 56 Author revision: 68 57 58Number 59 60 ARB Extension #57 61 62Dependencies 63 64 The OpenGL Shading Language (GLSL) is required. OpenGL 2.0 or the 65 ARB_shader_objects extension is required. 66 67 OpenGL 1.5 or ARB_vertex_buffer_object is required. 68 69 This extension is written against the OpenGL 2.1 specification and 70 version 1.20-8 of the OpenGL Shading Language specification. 71 72 This extension interacts with OpenGL 3.0, ARB_geometry_shader4, 73 ARB_texture_rectangle, EXT_gpu_shader4, EXT_texture_array, 74 EXT_texture_integer, and EXT_texture_buffer_object. 75 76Overview 77 78 This extension introduces the concept of a group of GLSL uniforms 79 known as a "uniform block", and the API mechanisms to store "uniform 80 blocks" in GL buffer objects. 81 82 The extension also defines both a standard cross-platform layout in 83 memory for uniform block data, as well as mechanisms to allow the GL 84 to optimize the data layout in an implementation-defined manner. 85 86 Prior to this extension, the existing interface for modification of 87 uniform values allowed modification of large numbers of values using 88 glUniform* calls, but only for a single uniform name (or a uniform 89 array) at a time. However, updating uniforms in this manner may not 90 map well to heterogenous uniform data structures defined for a GL 91 application and in these cases, the application is forced to either: 92 93 A) restructure their uniform data definitions into arrays 94 or 95 B) make an excessive number of calls through the GL interface 96 to one of the Uniform* variants. 97 98 These solutions have their disadvantages. Solution A imposes 99 considerable development overhead on the application developer. 100 Solution B may impose considerable run-time overhead on the 101 application if the number of uniforms modified in a given frame of 102 rendering is sufficiently large. 103 104 This extension provides a better alternative to either (A) or (B) by 105 allowing buffer object backing for the storage associated with all 106 uniforms of a given GLSL program. 107 108 Storing uniform blocks in buffer objects enables several key use 109 cases: 110 111 - sharing of uniform data storage between program objects and 112 between program stages 113 114 - rapid swapping of sets of previously defined uniforms by storing 115 sets of uniform data on the GL server 116 117 - rapid updates of uniform data from both the client and the server 118 119 The data storage for a uniform block can be declared to use one of 120 three layouts in memory: packed, shared, or std140. 121 122 - "packed" uniform blocks have an implementation-dependent data 123 layout for efficiency, and unused uniforms may be eliminated by 124 the compiler to save space. 125 126 - "shared" uniform blocks, the default layout, have an implementation- 127 dependent data layout for efficiency, but the layout will be uniquely 128 determined by the structure of the block, allowing data storage to be 129 shared across programs. 130 131 - "std140" uniform blocks have a standard cross-platform cross-vendor 132 layout (see below). Unused uniforms will not be eliminated. 133 134 Any uniforms not declared in a named uniform block are said to 135 be part of the "default uniform block". 136 137 While uniforms in the default uniform block are updated with 138 glUniform* entry points and can have static initializers, uniforms 139 in named uniform blocks are not. Instead, uniform block data is updated 140 using the routines that update buffer objects and can not use static 141 initializers. 142 143 Rules and Concepts Guiding this Specification: 144 145 For reference, a uniform has a "uniform index" (subsequently 146 referred to as "u_index) and also a "uniform location" to 147 efficiently identify it in the uniform data store of the 148 implementation. We subsequently refer to this uniform data store of 149 the implementation as the "uniform database". 150 151 A "uniform block" only has a "uniform block index" used for queries 152 and connecting the "uniform block" to a buffer object. A "uniform 153 block" has no "location" because "uniform blocks" are not updated 154 directly. The buffer object APIs are used instead. 155 156 Properties of Uniforms and uniform blocks: 157 158 a) A uniform is "active" if it exists in the database and has a valid 159 u_index. 160 b) A "uniform block" is "active" if it exists in the database and 161 has a valid ub_index. 162 c) Uniforms and "uniform blocks" can be inactive because they don't 163 exist in the source, or because they have been removed by dead 164 code elimination. 165 d) An inactive uniform has u_index == INVALID_INDEX. 166 e) An inactive uniform block has ub_index == INVALID_INDEX. 167 f) A u_index or ub_index of INVALID_INDEX generates the 168 INVALID_VALUE error if given as a function argument. 169 g) The default uniform block, which is not assigned any ub_index, uses a 170 private, internal data storage, and does not have any buffer object 171 associated with it. 172 h) An active uniform that is a member of the default uniform block has 173 location >= 0 and it has offset == stride == -1. 174 i) An active uniform that is a member of a named uniform block has 175 location == -1. 176 j) A uniform location of -1 is silently ignored if given as a function 177 argument. 178 k) Uniform block declarations may not be nested 179 180IP Status 181 182 No known IP claims. 183 184New Procedures and Functions 185 186 void GetUniformIndices(uint program, 187 sizei uniformCount, 188 const char* const * uniformNames, 189 uint* uniformIndices); 190 191 void GetActiveUniformsiv(uint program, 192 sizei uniformCount, 193 const uint* uniformIndices, 194 enum pname, 195 int* params); 196 197 void GetActiveUniformName(uint program, 198 uint uniformIndex, 199 sizei bufSize, 200 sizei* length, 201 char* uniformName); 202 203 uint GetUniformBlockIndex(uint program, 204 const char* uniformBlockName); 205 206 void GetActiveUniformBlockiv(uint program, 207 uint uniformBlockIndex, 208 enum pname, 209 int* params); 210 211 void GetActiveUniformBlockName(uint program, 212 uint uniformBlockIndex, 213 sizei bufSize, 214 sizei* length, 215 char* uniformBlockName); 216 217 void BindBufferRange(enum target, 218 uint index, 219 uint buffer, 220 intptr offset, 221 sizeiptr size); 222 223 void BindBufferBase(enum target, 224 uint index, 225 uint buffer); 226 227 void GetIntegeri_v(enum target, uint index, int* data); 228 229 void UniformBlockBinding(uint program, 230 uint uniformBlockIndex, 231 uint uniformBlockBinding); 232 233New Types 234 235 None. 236 237New Tokens 238 239 Accepted by the <target> parameters of BindBuffer, BufferData, 240 BufferSubData, MapBuffer, UnmapBuffer, GetBufferSubData, and 241 GetBufferPointerv: 242 243 UNIFORM_BUFFER 0x8A11 244 245 Accepted by the <pname> parameter of GetIntegeri_v, GetBooleanv, 246 GetIntegerv, GetFloatv, and GetDoublev: 247 248 UNIFORM_BUFFER_BINDING 0x8A28 249 250 Accepted by the <pname> parameter of GetIntegeri_v: 251 252 UNIFORM_BUFFER_START 0x8A29 253 UNIFORM_BUFFER_SIZE 0x8A2A 254 255 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 256 GetFloatv, and GetDoublev: 257 258 MAX_VERTEX_UNIFORM_BLOCKS 0x8A2B 259 MAX_GEOMETRY_UNIFORM_BLOCKS 0x8A2C 260 MAX_FRAGMENT_UNIFORM_BLOCKS 0x8A2D 261 MAX_COMBINED_UNIFORM_BLOCKS 0x8A2E 262 MAX_UNIFORM_BUFFER_BINDINGS 0x8A2F 263 MAX_UNIFORM_BLOCK_SIZE 0x8A30 264 MAX_COMBINED_VERTEX_UNIFORM_COMPONENTS 0x8A31 265 MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS 0x8A32 266 MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTS 0x8A33 267 UNIFORM_BUFFER_OFFSET_ALIGNMENT 0x8A34 268 269 Accepted by the <pname> parameter of GetProgramiv: 270 271 ACTIVE_UNIFORM_BLOCK_MAX_NAME_LENGTH 0x8A35 272 ACTIVE_UNIFORM_BLOCKS 0x8A36 273 274 Accepted by the <pname> parameter of GetActiveUniformsiv: 275 276 UNIFORM_TYPE 0x8A37 277 UNIFORM_SIZE 0x8A38 278 UNIFORM_NAME_LENGTH 0x8A39 279 UNIFORM_BLOCK_INDEX 0x8A3A 280 UNIFORM_OFFSET 0x8A3B 281 UNIFORM_ARRAY_STRIDE 0x8A3C 282 UNIFORM_MATRIX_STRIDE 0x8A3D 283 UNIFORM_IS_ROW_MAJOR 0x8A3E 284 285 Accepted by the <pname> parameter of GetActiveUniformBlockiv: 286 287 UNIFORM_BLOCK_BINDING 0x8A3F 288 UNIFORM_BLOCK_DATA_SIZE 0x8A40 289 UNIFORM_BLOCK_NAME_LENGTH 0x8A41 290 UNIFORM_BLOCK_ACTIVE_UNIFORMS 0x8A42 291 UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICES 0x8A43 292 UNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADER 0x8A44 293 UNIFORM_BLOCK_REFERENCED_BY_GEOMETRY_SHADER 0x8A45 294 UNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER 0x8A46 295 296 Returned by GetActiveUniformsiv and GetUniformBlockIndex 297 298 INVALID_INDEX 0xFFFFFFFFu 299 3002.1 Specification Updates 301 302Additions to Chapter 2 - OpenGL Operation 303 304 Section 2.9 - Buffer Objects 305 Add UNIFORM_BUFFER to list of buffer object targets on: 306 Pg 35, 2nd pgph 307 Pg 37, top of page 308 Pg 38, top of page 309 310 Section 2.15 - Vertex Shaders 311 Pg 79, bump Uniform Variables up to a numbered section since there 312 will now be hierarchy under it; replace all but first paragraph of 313 Uniform Variables section on this page, through to the start of the 314 first full paragraph on p. 80 (beginning "A valid <name>...") under 315 the description of GetUniformLocation: 316 317 Sets of uniforms can be grouped into "uniform blocks". The values of each 318 uniform in such a set are extracted from the data store of a buffer object 319 corresponding to the uniform block. 320 OpenGL Shading Language syntax serves to delimit named blocks of 321 uniforms that can be backed by a buffer object. These are referred to as 322 "named uniform blocks," and are assigned a uniform block index. Uniforms 323 that are declared outside of a named uniform block are said to be part of 324 the "default uniform block." Default uniform blocks have no name or uniform 325 block index. Like uniforms, uniform blocks can be active or inactive. Active 326 uniform blocks are those that contain active uniforms after a program has 327 been compiled and linked. 328 329 The amount of storage available for uniform variables in the default uniform 330 block accessed by a vertex shader is specified by the value of the 331 implementation-dependent constant MAX_VERTEX_UNIFORM_COMPONENTS. The total 332 amount of combined storage available for uniform variables in all uniform 333 blocks accessed by a vertex shader (including the default uniform block) 334 is specified by the value of the implementation-dependent 335 constant MAX_COMBINED_VERTEX_UNIFORM_COMPONENTS. These values 336 represent the numbers of individual floating-point, integer, or boolean 337 values that can be held in uniform variable storage for a vertex shader. 338 A link error is generated if an attempt is made to utilize more than 339 the space available for vertex shader uniform variables. 340 341 When a program is successfully linked, all active uniforms belonging to 342 the program object's default uniform block are initialized to zero (FALSE 343 for booleans). A successful link will also generate a location for each 344 active uniform in the default uniform block. The values of active uniforms 345 in the default uniform block can be changed using this location and the 346 appropriate Uniform* command (see below). These locations are invalidated 347 and new ones assigned after each successful re-link. 348 349 Similarly, when a program is successfully linked, all active uniforms 350 belonging to the program's named uniform blocks are assigned offsets 351 (and strides for array and matrix type uniforms) within the uniform block 352 according to layout rules described below. Uniform buffer objects provide 353 the storage for named uniform blocks, so the values of active uniforms in 354 named uniform blocks may be changed by modifying the contents of the buffer 355 object using commands such as BufferData, BufferSubData, MapBuffer, and 356 UnmapBuffer. Uniforms in a named uniform block are not assigned a location 357 and may not be modified using the Uniform* commands. The offsets and strides 358 of all active uniforms belonging to named uniform blocks of a program object 359 are invalidated and new ones assigned after each successful re-link. 360 361 To find the location within a program object of an active uniform 362 variable associated with the default uniform block, use the command 363 364 int GetUniformLocation(uint program, const char *name); 365 366 This command will return the location of uniform variable <name> if it 367 is associated with the default uniform block. <name> must be a 368 null-terminated string, without white space. The value -1 will be returned 369 if <name> does not correspond to an active uniform variable name in 370 <program>, if <name> is associated with a named uniform block, or if 371 <name> starts with the reserved prefix "gl_". 372 373 If <program> has not been successfully linked, the error INVALID_OPERATION 374 is generated. After a program is linked, the location of a uniform 375 variable will not change, unless the program is re-linked. 376 377 A valid <name>... 378 379 Pg 80, insert before the description of GetActiveUniform: 380 381 Named uniform blocks, like uniforms, are identified by name strings. 382 Uniform block indices corresponding to uniform block names can be queried 383 by calling 384 385 uint GetUniformBlockIndex(uint program, 386 const char* uniformBlockName); 387 388 <program> is the name of a program object for which the command 389 LinkProgram has been issued in the past. It is not 390 necessary for <program> to have been linked successfully. The link 391 could have failed because the number of active uniforms exceeded the 392 limit. 393 394 <uniformBlockName> must contain a null-terminated string specifying 395 the name of a uniform block. 396 397 GetUniformBlockIndex returns the uniform block index for the 398 uniform block named <uniformBlockName> of <program>. If 399 <uniformBlockName> does not identify an active uniform block of 400 <program>, or an error occurred, then INVALID_INDEX is returned. 401 The indices of the active uniform blocks of a program are assigned in 402 consecutive order, beginning with zero. 403 404 An active uniform block's name string can be queried from its 405 uniform block index by calling 406 407 void GetActiveUniformBlockName(uint program, 408 uint uniformBlockIndex, 409 sizei bufSize, 410 sizei* length, 411 char* uniformBlockName); 412 413 <program> is the name of a program object for which the command 414 LinkProgram has been issued in the past. It is not 415 necessary for <program> to have been linked successfully. The link 416 could have failed because the number of active uniforms exceeded the 417 limit. 418 419 <uniformBlockIndex> must be an active uniform block index of 420 <program>, in the range zero to the value of 421 ACTIVE_UNIFORM_BLOCKS - 1. The value of 422 ACTIVE_UNIFORM_BLOCKS can be queried with GetProgramiv (see 423 section 6.1.14). If <uniformBlockIndex> is greater than or equal to 424 the value of ACTIVE_UNIFORM_BLOCKS, the error INVALID_VALUE is 425 generated. 426 427 The string name of the uniform block identified by <uniformBlockIndex> 428 is returned into <uniformBlockName>. The name is 429 null-terminated. The actual number of characters written into 430 <uniformBlockName>, excluding the null terminator, is returned in <length>. 431 If <length> is NULL, no length is returned. 432 433 <bufSize> contains the maximum number of characters (including the 434 null terminator) that will be written back to <uniformBlockName>. 435 436 If an error occurs, nothing will be written to <uniformBlockName> or 437 <length>. 438 439 Information about an active uniform block can be queried by calling 440 441 void GetActiveUniformBlockiv(uint program, 442 uint uniformBlockIndex, 443 enum pname, 444 int* params); 445 446 <program> is the name of a program object for which the command 447 LinkProgram has been issued in the past. It is not 448 necessary for <program> to have been linked successfully. The link 449 could have failed because the number of active uniforms exceeded the 450 limit. 451 452 <uniformBlockIndex> is an active uniform block index of <program>. 453 If <uniformBlockIndex> is greater than or equal to the value of 454 ACTIVE_UNIFORM_BLOCKS, or is not the index of an active uniform 455 block in <program>, the error INVALID_VALUE is generated. 456 457 If no error occurs, the uniform block parameter(s) specified by 458 <pname> are returned in <params>. Otherwise, nothing will be written 459 to <params>. 460 461 If <pname> is UNIFORM_BLOCK_BINDING, then 462 the index of the uniform buffer binding 463 point last selected by the uniform block specified by <uniformBlockIndex> 464 for <program> is returned. If no uniform block has been previously 465 specified, zero is returned. 466 467 If <pname> is UNIFORM_BLOCK_DATA_SIZE, the value returned is the 468 implementation-dependent minimum total buffer object size, in 469 basic machine units, required to hold all active uniforms in the 470 uniform block identified by <uniformBlockIndex>. 471 It is neither guaranteed nor expected that a given implementation will 472 arrange uniform values as tightly packed in a buffer object. The exception 473 to this is the "std140" uniform block layout, which guarantees specific 474 packing behavior and does not require the application to query for offsets 475 and strides. In this case, the minimum size may still be queried, even 476 though it is determined in advance based only on the uniform block 477 declaration (see "Standard Uniform Block Layout" in section 2.15.3.1.2). 478 479 The total amount of buffer object storage available for any given uniform 480 block is subject to an implementation-dependent limit; the maximum amount 481 of available space, in basic machine units, can be queried by calling 482 GetIntegerv with the constant MAX_UNIFORM_BLOCK_SIZE. If the amount 483 of storage required for a uniform block exceeds this limit, a program may 484 fail to link. 485 486 If <pname> is UNIFORM_BLOCK_NAME_LENGTH, then the total length 487 (including the null terminator) of the name of the uniform block 488 identified by <uniformBlockIndex> is returned. 489 490 If <pname> is UNIFORM_BLOCK_ACTIVE_UNIFORMS, then the number of 491 active uniforms in the uniform block identified by 492 <uniformBlockIndex> is returned. 493 494 If <pname> is UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICES, then a list 495 of the active uniform indices for the uniform block identified by 496 <uniformBlockIndex> is returned. 497 The number of elements that will be written to <params> is the value 498 of UNIFORM_BLOCK_ACTIVE_UNIFORMS for <uniformBlockIndex>. 499 500 If <pname> is UNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADER, 501 UNIFORM_BLOCK_REFERENCED_BY_GEOMETRY_SHADER, or 502 UNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER, then 503 a boolean value indicating whether the uniform block identified by 504 <uniformBlockIndex> is referenced by the vertex, geometry, or fragment 505 programming stage of <program>, respectively, is returned. 506 507 Each active uniform, whether in a named uniform block or in the default 508 block, is assigned an index when a program is linked. These indices are 509 assigned in consecutive order, beginning with zero. The indices assigned 510 to a set of uniforms in a program may be queried by calling 511 512 void GetUniformIndices(uint program, 513 sizei uniformCount, 514 const char* const * uniformNames, 515 uint* uniformIndices); 516 517 <program> is the name of a program object for which the command 518 LinkProgram has been issued in the past. It is not 519 necessary for <program> to have been linked successfully. The link 520 could have failed because the number of active uniforms exceeded the 521 limit. 522 523 <uniformCount> indicates both the number of elements in the array of 524 names <uniformNames> and the number of indices that may be written to 525 <uniformIndices>. 526 527 <uniformNames> contains a list of <uniformCount> name strings 528 identifying the uniform names to be queried for indices. For each name 529 string in <uniformNames>, the index assigned to the active uniform of 530 that name will be written to the corresponding element of 531 <uniformIndices>. If a string in <uniformNames> is not the name of an 532 active uniform, the value INVALID_INDEX will be written to the 533 corresponding element of <uniformIndices>. 534 535 If an error occurs, nothing is written to <uniformIndices>. 536 537 The name of an active uniform may be queried from the corresponding uniform 538 index by calling 539 540 void GetActiveUniformName(uint program, 541 uint uniformIndex, 542 sizei bufSize, 543 sizei* length, 544 char* uniformName); 545 546 <program> is the name of a program object for which the command 547 LinkProgram has been issued in the past. It is not 548 necessary for <program> to have been linked successfully. The link 549 could have failed because the number of active uniforms exceeded the 550 limit. 551 552 <uniformIndex> must be an active uniform index of the program 553 <program>, in the range zero to the value of ACTIVE_UNIFORMS - 1. 554 The value of ACTIVE_UNIFORMS can be queried with GetProgramiv. If 555 <uniformIndex> is greater than or equal to the value of 556 ACTIVE_UNIFORMS, the error INVALID_VALUE is generated. 557 558 The name of the uniform identified by <uniformIndex> is 559 returned as a null-terminated string in <uniformName>. 560 The actual number of characters written into <uniformName>, excluding the 561 null terminator, is returned in <length>. If <length> is NULL, no length is 562 returned. The maximum number of characters that may be written into 563 <uniformName>, including the null terminator, is specified by <bufSize>. 564 The returned uniform name can be the name of built-in uniform state as 565 well. The complete list of built-in uniform state is described in section 566 7.5 of the OpenGL Shading Language specification. The length of the 567 longest uniform name in <program> is given by the value of 568 ACTIVE_UNIFORM_MAX_LENGTH, which can be queried with GetProgramiv. 569 570 If GetActiveUniformName is not successful, nothing is written to 571 <length> or <uniformName>. 572 573 Each uniform variable, declared in a shader, is broken down into one or 574 more strings using the "." (dot) and "[]" operators, if necessary, to the 575 point that it is legal to pass each string back into GetUniformLocation, 576 for default uniform block uniform names, or GetUniformIndices, for 577 named uniform block uniform names. 578 579 Pg 80, replace description of GetActiveUniform 580 581 Information about active uniforms can be obtained by calling either 582 583 void GetActiveUniform(uint program, 584 uint index, 585 sizei bufSize, 586 sizei* length, 587 int* size, 588 enum* type, 589 char* name); 590 591 or 592 593 void GetActiveUniformsiv(uint program, 594 sizei uniformCount, 595 const uint* uniformIndices, 596 enum pname, 597 int* params); 598 599 <program> is the name of a program object for which the command 600 LinkProgram has been issued in the past. It is not 601 necessary for <program> to have been linked successfully. The link 602 could have failed because the number of active uniforms exceeded the 603 limit. 604 605 These commands provide information about the uniform or uniforms selected 606 by <index> or <uniformIndices>, respectively. In GetActiveUniform, an 607 <index> of 0 selects the first active uniform, and an <index> of the value 608 of ACTIVE_UNIFORMS - 1 selects the last active uniform. In 609 GetActiveUniformsiv, <uniformIndices> is an array of such active uniform 610 indices. If any index is greater than or equal to the value of 611 ACTIVE_UNIFORMS, the error INVALID_VALUE is generated. 612 613 For the selected uniform, GetActiveUniform returns the uniform name as a 614 null-terminated string in <name>. The actual number of 615 characters written into <name>, excluding the null terminator, is returned 616 in <length>. If <length> is NULL, no length is returned. The maximum 617 number of characters that may be written into <name>, including the null 618 terminator, is specified by <bufSize>. The returned uniform name can be the 619 name of built-in uniform state as well. The complete list of built-in 620 uniform state is described in section 7.5 of the OpenGL Shading Language 621 specification. The length of the longest uniform name in <program> is given 622 by ACTIVE_UNIFORM_MAX_LENGTH. 623 624 Each uniform variable, declared in a shader, is broken down into one or 625 more strings using the "." (dot) and "[]" operators, if necessary, to the 626 point that it is legal to pass each string back into GetUniformLocation, 627 for default uniform block uniform names, or GetUniformIndices, for 628 named uniform block uniform names. 629 630 For the selected uniform, GetActiveUniform returns the type of the uniform 631 into <type> and the size of the uniform is into <size>. The value in 632 <size> is in units of the uniform type, which can be any of the 633 values in Table 2.utype. 634 635 If one or more elements of an array are active, GetActiveUniform will 636 return the name of the array in <name>, subject to the restrictions listed 637 above. The type of the array is returned in <type>. The <size> parameter 638 contains the highest array element index used, plus one. The compiler or 639 linker determines the highest index used. There will be only one active 640 uniform reported by the GL per uniform array. 641 642 GetActiveUniform will return as much information about active uniforms as 643 possible. If no information is available, <length> will be set to zero and 644 <name> will be an empty string. This situation could arise if 645 GetActiveUniform is issued after a failed link. 646 647 If an error occurs, nothing is written to <length>, <size>, <type>, 648 or <name>. 649 650 651 Type Name Token Keyword Type Name Token Keyword 652 --------------- ------- --------------- ------- 653 FLOAT float SAMPLER_1D sampler1D 654 FLOAT_VEC2 vec2 SAMPLER_2D sampler2D 655 FLOAT_VEC3 vec3 SAMPLER_3D sampler3D 656 FLOAT_VEC4 vec4 SAMPLER_CUBE samplerCube 657 INT int SAMPLER_1D_SHADOW sampler1DShadow 658 INT_VEC2 ivec2 SAMPLER_2D_SHADOW sampler2DShadow 659 INT_VEC3 ivec3 SAMPLER_1D_ARRAY_EXT sampler1DArray 660 INT_VEC4 ivec4 SAMPLER_2D_ARRAY_EXT sampler2DArray 661 UNSIGNED_INT unsigned int SAMPLER_1D_ARRAY_SHADOW_EXT sampler1DArrayShadow 662 UNSIGNED_INT_VEC2_EXT uvec2 SAMPLER_2D_ARRAY_SHADOW_EXT sampler2DArrayShadow 663 UNSIGNED_INT_VEC3_EXT uvec3 SAMPLER_CUBE_SHADOW_EXT samplerCubeShadow 664 UNSIGNED_INT_VEC4_EXT uvec4 SAMPLER_2D_RECT_ARB sampler2DRect 665 BOOL bool SAMPLER_2D_RECT_SHADOW_ARB sampler2DRectShadow 666 BOOL_VEC2 bvec2 INT_SAMPLER_1D_EXT isampler1D 667 BOOL_VEC3 bvec3 INT_SAMPLER_2D_EXT isampler2D 668 BOOL_VEC4 bvec4 INT_SAMPLER_3D_EXT isampler3D 669 FLOAT_MAT2 mat2 INT_SAMPLER_CUBE_EXT isamplerCube 670 FLOAT_MAT3 mat3 INT_SAMPLER_1D_ARRAY_EXT isampler1DArray 671 FLOAT_MAT4 mat4 INT_SAMPLER_2D_ARRAY_EXT isampler2DArray 672 FLOAT_MAT2x3 mat2x3 UNSIGNED_INT_SAMPLER_1D_EXT usampler1D 673 FLOAT_MAT2x4 mat2x4 UNSIGNED_INT_SAMPLER_2D_EXT usampler2D 674 FLOAT_MAT3x2 mat3x2 UNSIGNED_INT_SAMPLER_3D_EXT usampler3D 675 FLOAT_MAT3x4 mat3x4 UNSIGNED_INT_SAMPLER_CUBE_EXT usamplerCube 676 FLOAT_MAT4x2 mat4x2 UNSIGNED_INT_SAMPLER_1D_ARRAY_EXT usampler1DArray 677 FLOAT_MAT4x3 mat4x3 UNSIGNED_INT_SAMPLER_2D_ARRAY_EXT usampler2DArray 678 SAMPLER_BUFFER_EXT samplerBuffer 679 INT_SAMPLER_BUFFER_EXT isamplerBuffer 680 UNSIGNED_INT_SAMPLER_BUFFER_EXT usamplerBuffer 681 INT_SAMPLER_2D_RECT_EXT isampler2DRect 682 UNSIGNED_INT_SAMPLER_2D_RECT_EXT usampler2DRect 683 ----------------------------------------------------------------------- 684 Table 2.utype: OpenGL Shading Language type tokens returned by 685 GetActiveUniform and GetActiveUniformsiv, and corresponding shading 686 language keywords declaring each such type. 687 688 689 For GetActiveUniformsiv, <uniformCount> indicates both the number of 690 elements in the array of indices <uniformIndices> and the number of 691 parameters written to <params> upon successful return. <pname> identifies 692 a property of each uniform in <uniformIndices> that should be written into 693 the corresponding element of <params>. If an error occurs, nothing will 694 be written to <params>. 695 696 If <pname> is UNIFORM_TYPE, then an array identifying the types 697 of the uniforms specified by the corresponding array of 698 <uniformIndices> is returned. The returned types can be any of the 699 values in Table 2.utype. 700 701 If <pname> is UNIFORM_SIZE, then an array identifying the size 702 of the uniforms specified by the corresponding array of 703 <uniformIndices> is returned. The sizes returned are in units of the type 704 returned by a query of UNIFORM_TYPE. For active uniforms that are 705 arrays, the size is the number of active elements in the array; for 706 all other uniforms, the size is one. 707 708 If <pname> is UNIFORM_NAME_LENGTH, then an array identifying the 709 length, including the terminating null character, of the uniform 710 name strings specified by the corresponding array of 711 <uniformIndices> is returned. 712 713 If <pname> is UNIFORM_BLOCK_INDEX, then an array identifying the 714 uniform block index of each of the uniforms specified by the 715 corresponding array of <uniformIndices> is returned. The index of a 716 uniform associated with the default uniform block is -1. 717 718 If <pname> is UNIFORM_OFFSET, then an array of uniform buffer offsets 719 is returned. For uniforms in a named uniform block, the returned value 720 will be its offset, in basic machine units, relative to the beginning of 721 the uniform block in the buffer object data store. For uniforms in the 722 default uniform block, -1 will be returned. 723 724 If <pname> is UNIFORM_ARRAY_STRIDE, then an array identifying 725 the stride between elements, in basic machine units, of each of the 726 uniforms specified by the corresponding array of <uniformIndices> is 727 returned. The stride of a uniform associated with the default 728 uniform block is -1. Note that this information only makes sense for 729 uniforms that are arrays. For uniforms that are not arrays, but are 730 declared in a named uniform block, an array stride of zero is 731 returned. 732 733 If <pname> is UNIFORM_MATRIX_STRIDE, then an array identifying 734 the stride between columns of a column-major matrix or rows of a 735 row-major matrix, in basic machine units, of each of the uniforms 736 specified by the corresponding array of <uniformIndices> is 737 returned. The matrix stride of a uniform associated with the default 738 uniform block is -1. Note that this information only makes sense for 739 uniforms that are matrices. For uniforms that are not matrices, but 740 are declared in a named uniform block, a matrix stride of zero is 741 returned. 742 743 If <pname> is UNIFORM_IS_ROW_MAJOR, then 744 an array identifying whether each of the uniforms 745 specified by the corresponding array of <uniformIndices> is a row-major 746 matrix or not is returned. A value of one indicates a row-major 747 matrix, and a value of zero indicates a column-major matrix, a matrix 748 in the default uniform block, or a non-matrix. 749 750 Pg 81, replace Uniform* description with: 751 752 To load values into the uniform variables of the default uniform block of 753 the program object that is currently in use, use the commands 754 755 ... 756 757 The given values are loaded into the default uniform block uniform 758 variable location identified by <location>. 759 760 Sub-section 2.15.3.1 - Uniform Blocks 761 762 The values of uniforms arranged in named uniform blocks are extracted from 763 buffer object storage. The mechanisms for placing individual uniforms in 764 a buffer object and connecting a uniform block to an individual buffer 765 object are described below. 766 767 There is a set of implementation-dependent maximums for the number of 768 active uniform blocks used by each shader (vertex, fragment, geometry). 769 If the number of uniform blocks used by any shader in the program exceeds 770 its corresponding limit, the program will fail to link. The limits for 771 vertex, fragment, and geometry shaders can be obtained by calling 772 GetIntegerv with <pname> values of MAX_VERTEX_UNIFORM_BLOCKS, 773 MAX_FRAGMENT_UNIFORM_BLOCKS, and MAX_GEOMETRY_UNIFORM_BLOCKS, 774 respectively. 775 776 Additionally, there is an implementation-dependent limit on the sum of the 777 number of active uniform blocks used by each shader of a program. If a 778 uniform block is used by multiple shaders, each such use counts separately 779 against this combined limit. The combined uniform block use limit can be 780 obtained by calling GetIntegerv with a <pname> of 781 MAX_COMBINED_UNIFORM_BLOCKS. 782 783 When a named uniform block is declared by multiple shaders in a program, 784 it must be declared identically in each shader. The uniforms within the 785 block must be declared with the same names and types, and in the same 786 order. If a program contains multiple shaders with different declarations 787 for the same named uniform block differs between shader, the program will 788 fail to link. 789 790 Sub-section 2.15.3.1.1 - Uniform Buffer Object Storage 791 792 When stored in buffer objects associated with uniform blocks, uniforms are 793 represented in memory as follows: 794 795 - Members of type "bool" are extracted from a buffer object by reading a 796 single uint-typed value at the specified offset. All non-zero 797 values correspond to true, and zero corresponds to false. 798 799 - Members of type "int" are extracted from a buffer object by reading a 800 single int-typed value at the specified offset. 801 802 - Members of type "uint" are extracted from a buffer object by reading a 803 single uint-typed value at the specified offset. 804 805 - Members of type "float" are extracted from a buffer object by reading a 806 single float-typed value at the specified offset. 807 808 - Vectors with <N> elements with basic data types of "bool", "int", 809 "uint", or "float" are extracted as <N> values in consecutive memory 810 locations beginning at the specified offset, with components stored in 811 order with the first (X) component at the lowest offset. The GL data 812 type used for component extraction is derived according to the rules for 813 scalar members above. 814 815 - Column-major matrices with <C> columns and <R> rows (using the type 816 "mat<C>x<R>", or simply "mat<C>" if <C>==<R>) are treated as an array of 817 <C> floating-point column vectors, each consisting of <R> components. 818 The column vectors will be stored in order, with column zero at the 819 lowest offset. The difference in offsets between consecutive columns of 820 the matrix will be referred to as the column stride, and is constant 821 across the matrix. The column stride, UNIFORM_MATRIX_STRIDE, is an 822 implementation-dependent value and may be queried after a program is 823 linked. 824 825 - Row-major matrices with <C> columns and <R> rows (using the type 826 "mat<C>x<R>", or simply "mat<C>" if <C>==<R>) are treated as an array of 827 <R> floating-point row vectors, each consisting of <C> components. The 828 row vectors will be stored in order, with row zero at the lowest offset. 829 The difference in offsets between consecutive rows of the matrix will be 830 referred to as the row stride, and is constant across the matrix. The 831 row stride, UNIFORM_MATRIX_STRIDE, is an implementation-dependent 832 value and may be queried after a program is linked. 833 834 - Arrays of scalars, vectors, and matrices are stored in memory by element 835 order, with array member zero at the lowest offset. The difference in 836 offsets between each pair of elements in the array in basic machine 837 units is referred to as the array stride, and is constant across the 838 entire array. The array stride, UNIFORM_ARRAY_STRIDE, is an 839 implementation-dependent value and may be queried after a program is 840 linked. 841 842 Sub-section 2.15.3.1.2 - Standard Uniform Block Layout 843 844 By default, uniforms contained within a uniform block are extracted from 845 buffer storage in an implementation-dependent manner. Applications may 846 query the offsets assigned to uniforms inside uniform blocks with query 847 functions provided by the GL. 848 849 The "layout" qualifier provides shaders with control of the layout of 850 uniforms within a uniform block. When the "std140" layout is specified, 851 the offset of each uniform in a uniform block can be derived from the 852 definition of the uniform block by applying the set of rules described 853 below. 854 855 If a uniform block is declared in multiple shaders linked together into a 856 single program, the link will fail unless the uniform block declaration, 857 including layout qualifier, are identical in all such shaders. 858 859 When using the "std140" storage layout, structures will be laid out in 860 buffer storage with its members stored in monotonically increasing order 861 based on their location in the declaration. A structure and each 862 structure member have a base offset and a base alignment, from which an 863 aligned offset is computed by rounding the base offset up to a multiple of 864 the base alignment. The base offset of the first member of a structure is 865 taken from the aligned offset of the structure itself. The base offset of 866 all other structure members is derived by taking the offset of the last 867 basic machine unit consumed by the previous member and adding one. Each 868 structure member is stored in memory at its aligned offset. The members 869 of a top-level uniform block are laid out in buffer storage by treating 870 the uniform block as a structure with a base offset of zero. 871 872 (1) If the member is a scalar consuming <N> basic machine units, the 873 base alignment is <N>. 874 875 (2) If the member is a two- or four-component vector with components 876 consuming <N> basic machine units, the base alignment is 2<N> or 877 4<N>, respectively. 878 879 (3) If the member is a three-component vector with components consuming 880 <N> basic machine units, the base alignment is 4<N>. 881 882 (4) If the member is an array of scalars or vectors, the base alignment 883 and array stride are set to match the base alignment of a single 884 array element, according to rules (1), (2), and (3), and rounded up 885 to the base alignment of a vec4. The array may have padding at the 886 end; the base offset of the member following the array is rounded up 887 to the next multiple of the base alignment. 888 889 (5) If the member is a column-major matrix with <C> columns and <R> 890 rows, the matrix is stored identically to an array of <C> column 891 vectors with <R> components each, according to rule (4). 892 893 (6) If the member is an array of <S> column-major matrices with <C> 894 columns and <R> rows, the matrix is stored identically to a row of 895 <S>*<C> column vectors with <R> components each, according to rule 896 (4). 897 898 (7) If the member is a row-major matrix with <C> columns and <R> rows, 899 the matrix is stored identically to an array of <R> row vectors 900 with <C> components each, according to rule (4). 901 902 (8) If the member is an array of <S> row-major matrices with <C> columns 903 and <R> rows, the matrix is stored identically to a row of <S>*<R> 904 row vectors with <C> components each, according to rule (4). 905 906 (9) If the member is a structure, the base alignment of the structure is 907 <N>, where <N> is the largest base alignment value of any of its 908 members, and rounded up to the base alignment of a vec4. The 909 individual members of this sub-structure are then assigned offsets 910 by applying this set of rules recursively, where the base offset of 911 the first member of the sub-structure is equal to the aligned offset 912 of the structure. The structure may have padding at the end; the 913 base offset of the member following the sub-structure is rounded up 914 to the next multiple of the base alignment of the structure. 915 916 (10) If the member is an array of <S> structures, the <S> elements of 917 the array are laid out in order, according to rule (9). 918 919 For uniform blocks laid out according to these rules, the minimum buffer 920 object size returned by the UNIFORM_BLOCK_DATA_SIZE query is derived by 921 taking the offset of the last basic machine unit consumed by the last 922 uniform of the uniform block (including any end-of-array or 923 end-of-structure padding), adding one, and rounding up to the next 924 multiple of the base alignment required for a vec4. 925 926 Sub-section 2.15.3.2 - Uniform Buffer Object Bindings 927 928 The value an active uniform inside a named uniform block is extracted from 929 the data store of a buffer object bound to one of an array of uniform 930 buffer binding points. The number of binding points can be queried using 931 GetIntegerv with the constant MAX_UNIFORM_BUFFER_BINDINGS. 932 933 Buffer objects are bound to uniform block binding points by calling one of 934 the commands 935 936 void BindBufferRange(enum target, 937 uint index, 938 uint buffer, 939 intptr offset, 940 sizeiptr size); 941 942 void BindBufferBase(enum target, 943 uint index, 944 uint buffer); 945 946 with <target> set to UNIFORM_BUFFER. There is an array of buffer 947 object binding points with which uniform blocks can be associated via 948 UniformBlockBinding, plus a single general binding point that can be 949 used by other buffer object manipulation functions (e.g. BindBuffer, 950 MapBuffer). Both commands bind the buffer object named by <buffer> to the 951 general binding point, and additionally bind the buffer object to the 952 binding point in the array given by <index>. The error INVALID_VALUE is 953 generated if <index> is greater than or equal to the value of 954 MAX_UNIFORM_BUFFER_BINDINGS. 955 956 For BindBufferRange, <offset> specifies a starting offset into the 957 buffer object <buffer>, and <size> specifies the amount of data that can 958 be read from the buffer object while used as the storage for a uniform 959 block. Both <offset> and <size> are in basic machine units. An 960 INVALID_VALUE error is generated if <size> is less than or equal to zero 961 or if <offset> is not a multiple of the implementation-dependent 962 required alignment (the value of UNIFORM_BUFFER_OFFSET_ALIGNMENT). 963 964 BindBufferBase binds the entire buffer, even when the size of the buffer 965 is changed after the binding is established. It is equivalent to calling 966 BindBufferRange with <offset> zero, while <size> is determined by the 967 size of the bound buffer at the time the binding is used. 968 969 Regardless of the size specified with BindBufferRange, or indirectly 970 with BindBufferBase, the GL will never read or write beyond the end of a 971 bound buffer. This may result in visibly different behavior when a 972 buffer overflow would otherwise result. 973 974 Each of a program's active uniform blocks has a corresponding uniform buffer 975 object binding point. This binding point can be assigned by calling: 976 977 void UniformBlockBinding(uint program, 978 uint uniformBlockIndex, 979 uint uniformBlockBinding); 980 981 <program> is a name of a program object for which the command LinkProgram 982 has been issued in the past. 983 984 <uniformBlockIndex> must be an active uniform block index of the program 985 <program>. Otherwise, INVALID_VALUE is generated. 986 987 <uniformBlockBinding> must be less than MAX_UNIFORM_BUFFER_BINDINGS. 988 Otherwise, INVALID_VALUE is generated. 989 990 If successful, UniformBlockBinding specifies that 991 <program> will use the data store of the buffer object bound to the 992 binding point <uniformBlockBinding> to extract the values of the uniforms 993 in the uniform block identified by <uniformBlockIndex>. 994 995 The results of Begin or commands that perform an implicit Begin are 996 undefined when an active uniform block of the active program is assigned a 997 uniform buffer binding point where the <size> parameter to BindBufferRange 998 is less than the value of UNIFORM_BLOCK_DATA_SIZE for that uniform 999 block, or when no buffer object is bound to that binding point, and may 1000 result in GL interruption or termination. 1001 1002 When executing shaders that access uniform blocks, the binding point 1003 corresponding to each active uniform block must be populated with a buffer 1004 object with a size no smaller than the minimum required size of the 1005 uniform block (UNIFORM_BLOCK_DATA_SIZE). For binding points populated 1006 by BindBufferRange, the size in question is the value of the <size> 1007 parameter. If any active uniform block is not backed by a sufficiently 1008 large buffer object, the results of shader execution are undefined, and 1009 may result in GL interruption or termination. Shaders may be executed to 1010 process the primitives and vertices specified between Begin and End commands 1011 or by Draw* or MultiDraw* commands (see section 2.8). Shaders may also 1012 be executed as a result of DrawPixels, Bitmap, or RasterPos* commands. 1013 1014 When a program object is linked or re-linked, the uniform buffer object 1015 binding point assigned to each of its active uniform blocks is reset to 1016 zero. 1017 1018Additions to Chapter 3 - Rasterization 1019 1020 3.11.1 Shader Variables, p. 196 1021 Replace the second two sentences with: 1022 1023 The amount of storage available for fragment shader uniform variables in 1024 the default uniform block is specified by the value of the implementation- 1025 dependent constant MAX_FRAGMENT_UNIFORM_COMPONENTS. The total amount of 1026 combined storage available for fragment shader uniform variables in all 1027 uniform blocks (including the default uniform block) is specified by the 1028 value of the implementation-dependent constant 1029 MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTS. These values represent the 1030 numbers of individual floating-point, integer, or boolean values that can be 1031 held in uniform variable storage for a fragment shader. 1032 1033Additions to Chapter 4 - Per-Fragment Operations and the Framebuffer 1034 1035 None 1036 1037Additions to Chapter 5 - State and State Requests 1038 1039 5.4 Display Lists, p. 244 1040 Add the following language to the list of commands excluded from 1041 display list compilation: 1042 1043 "Buffer objects: BindBufferRange, BindBufferBase" 1044 1045 1046Additions to Chapter 6 - State and State Requests 1047 1048 6.1.1 Simple Queries, p. 247 1049 Add the following paragraph: 1050 1051 Indexed simple state variables are queried with the command 1052 1053 void GetIntegeri_v(enum target, uint index, int* data); 1054 1055 <target> is the name of the indexed state and <index> is the 1056 index of the particular element being queried. <data> is a 1057 pointer to a scalar or array of the indicated type in which 1058 to place the returned data. An INVALID_VALUE error is generated 1059 if <index> is outside the valid range for the indexed state 1060 <target>. 1061 1062 6.1.13 Buffer Object Queries, p. 260 1063 1064 Add after description of GetBufferPointerv: 1065 1066 To query which buffer objects are bound to the array of uniform 1067 buffer binding points and will be used as the storage for 1068 active uniform blocks, call GetIntegeri_v with <param> set to 1069 UNIFORM_BUFFER_BINDING. <index> must be in the range 1070 zero to the value of MAX_UNIFORM_BUFFER_BINDINGS - 1. 1071 The name of the buffer object bound to <index> is returned in 1072 <values>. If no buffer object is bound for <index>, zero is 1073 returned in <values>. 1074 1075 To query the starting offset or size of the range of each buffer object 1076 binding used for uniform buffers, call GetIntegeri_v with <param> set to 1077 UNIFORM_BUFFER_START or UNIFORM_BUFFER_SIZE respectively. <index> must 1078 be in the range zero to the value of MAX_UNIFORM_BUFFER_BINDINGS - 1. If 1079 the parameter (starting offset or size) was not specified when the 1080 buffer object was bound (e.g. if bound with BindBufferBase), or if no 1081 buffer object is bound to <index>, zero is returned. 1082 1083 6.1.14 Shader and Program Queries 1084 Pg 261, continuation of paragraph defining "GetProgramiv" 1085 1086 If <pname> is ACTIVE_UNIFORM_BLOCKS the number of uniform 1087 blocks for <program> containing active uniforms is returned. 1088 1089 If <pname> is ACTIVE_UNIFORM_BLOCK_MAX_NAME_LENGTH, the 1090 length of the longest active uniform block name, including 1091 the null terminator, is returned. 1092 1093 Pg 263, replace GetUniform{f|i}v description with: 1094 1095 ... return the value or values of the uniform at location <location> 1096 of the default uniform block for program object <program>... 1097 1098GLX Protocol 1099 1100 GLX protocol for BindBufferRange, BindBufferBase and GetIntegeri_v 1101 was added through NV_transform_feedback and EXT_draw_buffers2 1102 protocol specs. 1103 1104 The following rendering commands are sent to the server as part of 1105 a glXRender request: 1106 1107 UniformBlockBinding 1108 1109 2 16 rendering command length 1110 2 366 rendering command opcode 1111 4 CARD32 program 1112 4 CARD32 uniformBlockIndex 1113 4 CARD32 uniformBlockBinding 1114 1115 The following non-rendering commands are added: 1116 1117 GetUniformIndices 1118 1119 1 CARD8 opcode(X assigned) 1120 1 215 GLX opcode 1121 2 4+n+(s+p)/4 request length 1122 4 GLX_CONTEXT_TAG context tag 1123 4 CARD32 program 1124 4 CARD32 uniformCount 1125 n LISTofINT32 lengths[n], n = uniformCount, lengths[i] = strlen(uniformNames[i]) + 1, 0 <= i < n. 1126 s LISTofCHAR uniformNames, s = length[0]+...+length[n-1]. 1127 array 1128 p unused, p = pad(s) 1129 => 1130 1 1 reply 1131 1 unused 1132 2 CARD16 sequence number 1133 4 n reply length 1134 4 unused 1135 4 CARD32 n (number of uniform Indices) 1136 1137 if (n == 1) this follows: 1138 1139 4 CARD32 uniformIndices 1140 12 unused 1141 1142 otherwise this follows: 1143 1144 16 unused 1145 4*n LISTofCARD32 uniformIndices 1146 1147 GetActiveUniformsiv 1148 1149 1 CARD8 opcode(X assigned) 1150 1 216 GLX opcode 1151 2 5+n request length 1152 4 GLX_CONTEXT_TAG context tag 1153 4 CARD32 program 1154 4 INT32 uniformCount(n) 1155 4 ENUM pname 1156 n LISTofCARD32 uniformIndices 1157 1158 => 1159 1 1 reply 1160 1 unused 1161 2 CARD16 sequence number 1162 4 n reply length 1163 4 unused 1164 1165 if (n == 1) this follows: 1166 1167 4 INT32 params 1168 12 unused 1169 1170 otherwise this follows: 1171 1172 16 unused 1173 4*n LISTofINT32 params 1174 1175 GetActiveUniformName 1176 1177 1 CARD8 opcode(X assigned) 1178 1 217 GLX opcode 1179 2 5 request length 1180 4 GLX_CONTEXT_TAG context tag 1181 4 CARD32 program 1182 4 CARD32 uniformIndex 1183 4 INT32 bufsize 1184 => 1185 1 1 reply 1186 1 unused 1187 2 CARD16 sequence number 1188 4 m reply length, m = (n+p)/4 1189 4 unused 1190 4 INT32 n 1191 16 unused 1192 n LISTofCHAR uniformName, n = strlen(uniformName)+1 1193 p unused, p=pad(n) 1194 1195 GetUniformBlockIndex 1196 1197 1 CARD8 opcode(X assigned) 1198 1 218 GLX opcode 1199 2 3+(n+p)/4 request length 1200 4 GLX_CONTEXT_TAG context tag 1201 4 CARD32 program 1202 n LISTofCHAR uniformBlockName, n = strlen(uniformBlockName)+1 1203 p unused, p=pad(n) 1204 => 1205 1 1 reply 1206 1 unused 1207 2 CARD16 sequence number 1208 4 0 reply length 1209 4 CARD32 return value 1210 20 unused 1211 1212 GetActiveUniformBlockiv 1213 1214 1 CARD8 opcode(X assigned) 1215 1 219 GLX opcode 1216 2 5 request length 1217 4 GLX_CONTEXT_TAG context tag 1218 4 CARD32 program 1219 4 CARD32 uniformBlockIndex 1220 4 ENUM pname 1221 => 1222 1 1 reply 1223 1 unused 1224 2 CARD16 sequence number 1225 4 n reply length 1226 4 unused 1227 1228 if (n == 1) this follows: 1229 1230 4 INT32 params 1231 12 unused 1232 1233 otherwise this follows: 1234 1235 16 unused 1236 4*n LISTofINT32 params 1237 1238 GetActiveUniformBlockName 1239 1240 1 CARD8 opcode(X assigned) 1241 1 220 GLX opcode 1242 2 5 request length 1243 4 GLX_CONTEXT_TAG context tag 1244 4 CARD32 program 1245 4 CARD32 uniformBlockIndex 1246 4 INT32 bufsize 1247 => 1248 1 1 reply 1249 1 unused 1250 2 CARD16 sequence number 1251 4 m reply length, m = (n+p)/4 1252 4 unused 1253 4 INT32 n 1254 16 unused 1255 n LISTofCHAR uniformBlockName, n = strlen(uniformBlockName)+1 1256 p unused, p=pad(n) 1257 1258OpenGL Shading Language Spec v1.20.8 Updates 1259 1260 Including the following line in a shader can be used to control the 1261 language features described in this extension: 1262 1263 #extension GL_ARB_uniform_buffer_object : <behavior> 1264 1265 where <behavior> is as specified in section 3.3. 1266 1267 A new preprocessor #define is added to the OpenGL Shading 1268 Language: 1269 1270 #define GL_ARB_uniform_buffer_object 1 1271 1272 Add two new sections: 1273 1274 4.3.5.1 Uniform Blocks 1275 1276 Variable declarations at global scope can be grouped into a named block to 1277 provide coarser granularity for manipulation, sharing, or backing than is 1278 achievable with individual declarations. This is currently only allowed for 1279 uniform variables grouped into uniform blocks. All other uses are reserved. 1280 1281 The application backs a uniform block with a buffer. This allows application 1282 access to a set of uniform variables through a single buffer. The 1283 application will need to query the offsets of the variables within the 1284 block or follow standard rules for block layout in order to know how to 1285 layout the contents of a buffer used to back the block. 1286 1287 A uniform block (rather than a uniform variable) is created by the uniform 1288 keyword, followed by a block name, followed by an open curly brace ( { ) as 1289 follows: 1290 1291 uniform-block : 1292 layout-qualifieropt uniform block-name { member-list } ; 1293 1294 layout-qualifier : 1295 layout ( layout-qualifier-id-list ) 1296 1297 member-list : 1298 member-declaration 1299 member-declaration member-list 1300 1301 member-declaration : 1302 layout-qualifieropt uniformopt basic-type declarators ; 1303 1304 Where declarators are the same as for other uniform variable declarations, 1305 except initializers are not allowed. Layout qualifiers are defined in the 1306 next section. 1307 1308 For example, 1309 1310 uniform Transform { 1311 mat4 ModelViewMatrix; 1312 mat4 ModelViewProjectionMatrix; 1313 uniform mat3 NormalMatrix; // reuse of uniform is optional 1314 float Deformation; 1315 }; 1316 1317 The above establishes a uniform block named "Transform" with four uniforms 1318 grouped inside it. 1319 1320 The names declared inside the block are accessed as if they were declared 1321 outside the block. In no way does the shader ever access block members 1322 through any use of block-name. 1323 1324 Uniform block names and variable names declared within uniform blocks are 1325 scoped at the program level. Matching block names from multiple compilation 1326 units in the same program must match in terms of having the same number of 1327 declarations with the same sequence of types and the same sequence of member 1328 names, as well as having the same member-wise layout qualification (see next 1329 section). Any mismatch will generate a link error. 1330 1331 Sampler types are not allowed inside of uniform blocks. All other types, 1332 arrays, and structures allowed for uniforms are allowed within a uniform 1333 block. 1334 1335 There is an implementation-dependent limit on the number of uniform blocks 1336 that can be used per stage. If this limit is exceeded, it will cause a link 1337 error. 1338 1339 4.3.5.2 Uniform Block Layout Qualifiers 1340 1341 The layout-qualifier-id-list for uniform blocks is a comma separated list of 1342 the following qualifiers: 1343 1344 shared (default) 1345 packed 1346 std140 1347 row_major 1348 column_major (default) 1349 1350 These qualifiers are identifiers, not keywords. None of these have any 1351 semantic affect at all on the usage of the variables being declared; they 1352 only describe how data is laid out in memory. For example, matrix semantics 1353 are always column-based, as described in the rest of this specification, no 1354 matter what layout qualifiers are being used. 1355 1356 Uniform block layout qualifiers can be declared at global scope, on a single 1357 uniform block, or on a single block member. 1358 1359 At global scope, it is an error to use layout qualifiers to declare a 1360 variable. Instead, at global scope, layout qualifiers apply just to the 1361 keyword uniform and establish default qualification for subsequent blocks: 1362 1363 layout-defaults : 1364 layout-qualifier uniform ; 1365 1366 When this is done, the previous default qualification is first inherited and 1367 then overridden as per the override rules listed below for each qualifier 1368 listed in the declaration. The result becomes the new default qualification 1369 scoped to subsequent uniform block definitions. Layout defaults can only be 1370 specified at global scope. 1371 1372 The initial state of compilation is as if the following were declared: 1373 1374 layout(shared, column_major) uniform; 1375 1376 Explicitly declaring this in a shader will return defaults back to their 1377 initial state. 1378 1379 Uniform blocks can be declared with optional layout qualifiers, and so can 1380 their individual member declarations. Such block layout qualification is 1381 scoped only to the content of the block. As with global layout declarations, 1382 block layout qualification first inherits from the current default 1383 qualification and then overrides it. Similarly, individual member layout 1384 qualification is scoped just to the member declaration, and inherits from 1385 and overrides the block's qualification. 1386 1387 The shared qualifier overrides only the std140 and packed qualifiers; other 1388 qualifiers are inherited. The compiler/linker will ensure that multiple 1389 programs and programmable stages containing this definition will share the 1390 same memory layout for this block, as long as they also matched in their 1391 row_major and/or column_major qualifications. This allows use of the same 1392 buffer to back the same block definition across different programs. 1393 1394 The packed qualifier overrides only std140 and shared; other qualifiers are 1395 inherited. When packed is used, no shareable layout is guaranteed. The 1396 compiler and linker can optimize memory use based on what variables actively 1397 get used and on other criteria. Offsets must be queried, as there is no 1398 other way of guaranteeing where (and which) variables reside within the 1399 block. Attempts to share a packed uniform block across programs or stages 1400 will generally fail. However, implementations may aid application management 1401 of packed blocks by using canonical layouts for packed blocks. 1402 1403 The std140 qualifier overrides only the packed and shared qualifiers; other 1404 qualifiers are inherited. The layout is explicitly determined by this, as 1405 described in the API specification section 2.15.3.1.2. Hence, as in shared 1406 above, the resulting layout is shareable across programs. 1407 1408 Layout qualifiers on member declarations cannot use the shared, packed, or 1409 std140 qualifiers. These can only be used at global scope or on a block 1410 declaration. 1411 1412 The row_major qualifier overrides only the column_major qualifier; other 1413 qualifiers are inherited. It only affects the layout of matrices. Elements 1414 within a matrix row will be contiguous in memory. 1415 1416 The column_major qualifier overrides only the row_major qualifier; other 1417 qualifiers are inherited. It only affects the layout of matrices. Elements 1418 within a matrix column will be contiguous in memory. 1419 1420 When multiple arguments are listed in a layout declaration, the affect will 1421 be the same as if they were declared one at a time, in order from left to 1422 right, each in turn inheriting from and overriding the result from the 1423 previous qualification. 1424 1425 For example 1426 1427 layout(row_major, column_major) 1428 1429 results in the qualification being column_major. Other examples: 1430 1431 layout(shared, row_major) uniform; // default is now shared & row_major 1432 1433 layout(std140) uniform Transform { // layout of this block is std140 1434 mat4 M1; // row_major 1435 layout(column_major) mat4 M2; // column major 1436 mat3 N1; // row_major 1437 }; 1438 1439 uniform T2 { // layout of this block is shared 1440 ... 1441 }; 1442 1443 layout(column_major) uniform T3 { // shared and column_major 1444 mat4 M3; // column_major 1445 layout(row_major) mat4 m4; // row major 1446 mat3 N2; // column_major 1447 }; 1448 1449Interactions with OpenGL 3.0 1450 1451 If OpenGL 3.0 is supported, the introduction of BindBufferBase and 1452 BindBufferRange can be ignored, though the uniform buffer object 1453 language herein will need to be merged with the transform feedback 1454 language in GL 3.0. 1455 1456 If OpenGL 3.0 is supported, the introduction of GetIntegeri_v 1457 can be ignored. 1458 1459 If OpenGL 3.0 is supported, change: 1460 1461 "When a program is successfully linked, all active uniforms belonging to 1462 the program object's default uniform block are initialized to zero (FALSE 1463 for booleans). A successful link will also generate a location for each 1464 active uniform in the default uniform block. The values of active uniforms 1465 in the default uniform block can be changed using this location and the 1466 appropriate Uniform* command (see below)." 1467 1468 to 1469 1470 "When a program is successfully linked, all active uniforms belonging to 1471 the program object's default uniform block are initialized as defined by 1472 the version of the OpenGL Shading Language used to compile the program. A 1473 successful link will also generate a location for each active uniform in 1474 the default uniform block. The values of active uniforms in the default 1475 uniform block can be changed using this location and the appropriate 1476 Uniform* command (see below)." 1477 1478 If OpenGL 3.0 is supported, replace "Begin or commands that perform 1479 an implicit Begin" with "Draw* commands." 1480 1481 If OpenGL 3.0 is supported, UNIFORM_BUFFER is a valid target for 1482 new buffer-related API, e.g. MapBufferRange. 1483 1484Interactions with EXT_gpu_shader4 1485 1486 If EXT_gpu_shader4 is not supported, then all of the types in table 1487 2.utype with extension suffixes should be omitted. 1488 1489Interactions with ARB_texture_rectangle 1490 1491 If ARB_texture_rectangle is not available, then all of the types in 1492 table 2.utype with RECT in their names should be omitted. 1493 1494Interactions with EXT_texture_array 1495 1496 If EXT_texture_array is not available, then all of the types in 1497 table 2.utype with ARRAY in their names should be omitted. 1498 1499Interactions with EXT_texture_buffer_object 1500 1501 If EXT_texture_buffer_object is not available, then all of the types 1502 in table 2.utype with BUFFER in their names should be omitted. 1503 1504Interactions with EXT_texture_integer 1505 1506 If EXT_texture_integer is not available, then all of the types in 1507 table 2.utype with UNSIGNED_INT or INT_SAMPLER in their names should 1508 be omitted. 1509 1510Interactions with ARB_geometry_shader4 1511 1512 If ARB_geometry_shader4 is not supported, omit all mentions of the 1513 geometry shader stage, including MAX_GEOMETRY_UNIFORM_BUFFERS 1514 and UNIFORM_BLOCK_REFERENCED_BY_GEOMETRY_SHADER. The minimum 1515 value of MAX_COMBINED_UNIFORM_BLOCKS and 1516 MAX_UNIFORM_BUFFER_BINDINGS changes from 36 to 24. 1517 1518 Language describing MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS can be found 1519 in the ARB_geometry_shader4 specification. 1520 1521Errors 1522 1523 The error INVALID_OPERATION is generated by BindBufferRange and 1524 BindBufferBase if <buffer> is not the name of a valid buffer object. 1525 1526 The error INVALID_VALUE is generated by GetUniformIndices, 1527 GetActiveUniformsiv, GetActiveUniformName, GetUniformBlockIndex, 1528 GetActiveUniformBlockiv, GetActiveUniformBlockName, and 1529 UniformBlockBinding if <program> is not a value generated by GL. 1530 1531 The error INVALID_VALUE is generated by GetUniformIndices and 1532 GetActiveUniformsiv if <uniformCount> is less than zero. 1533 1534 The error INVALID_VALUE is generated by GetActiveUniformName and 1535 GetActiveUniformBlockName if <bufSize> is less than zero. 1536 1537 The error INVALID_VALUE is generated by BindBufferRange if <size> is less 1538 than zero. 1539 1540 The error INVALID_VALUE is generated by GetActiveUniformName if 1541 <uniformIndex> is greater than or equal to ACTIVE_UNIFORMS. 1542 1543 The error INVALID_VALUE is generated by GetActiveUniformsiv if any of 1544 the indices in <uniformIndices> is greater than or equal to ACTIVE_UNIFORMS. 1545 1546 The error INVALID_VALUE is generated by GetActiveUniformBlockiv, 1547 GetActiveUniformBlockName, and UniformBlockBinding if 1548 <uniformBlockIndex> is greater than or equal to ACTIVE_UNIFORM_BLOCKS. 1549 1550 The error INVALID_VALUE is generated by UniformBlockBinding if 1551 <uniformBlockBinding> is greater than or equal to 1552 MAX_UNIFORM_BUFFER_BINDINGS. 1553 1554 The error INVALID_VALUE is generated by BindBufferRange and BindBufferBase 1555 if <index> is greater than or equal to MAX_UNIFORM_BUFFER_BINDINGS. 1556 1557 The error INVALID_VALUE is generated by BindBufferRange if <offset> is not 1558 a multiple of UNIFORM_BUFFER_OFFSET_ALIGNMENT basic machine units. 1559 1560 The error INVALID_ENUM is generated by GetActiveUniformsiv and 1561 GetActiveUniformBlockiv if <pname> is not one of the accepted values. 1562 1563 The error INVALID_ENUM is generated by BindBufferRange and BindBufferBase 1564 if <target> is not an accepted indexable buffer object target. 1565 1566 1567New State 1568 Initial 1569 Get Value Type Get Command Value Description Sec Attribute 1570 -------------------------- ---- ----------- ----- ------------------------- ----- --------- 1571 UNIFORM_BUFFER_BINDING Z+ GetIntegerv 0 Uniform buffer object 2.15.3 - 1572 bound to the context for 1573 buffer object manipulation. 1574 1575 UNIFORM_BUFFER_BINDING nxZ+ GetIntegeri_v 0 Uniform buffer object 2.15.3 - 1576 bound to the specified 1577 context binding point 1578 1579 ACTIVE_UNIFORM_BLOCKS Z+ GetProgramiv 0 Number of active 2.15.3 - 1580 uniform blocks in a 1581 program 1582 1583 ACTIVE_UNIFORM_BLOCK_MAX_NAME_LENGTH 1584 Z+ GetProgramiv 0 Length of longest active 2.15.3 - 1585 uniform block name 1586 1587 UNIFORM_TYPE 0*xZ_27 GetActiveUniformsiv - Type of active uniform 2.15.3 - 1588 1589 UNIFORM_SIZE 0*xZ+ GetActiveUniformsiv - Size of active uniform 2.15.3 - 1590 1591 UNIFORM_NAME_LENGTH 0*xZ+ GetActiveUniformsiv - Uniform name length 2.15.3 - 1592 1593 UNIFORM_BLOCK_INDEX 0*xZ GetActiveUniformsiv - Uniform block index 2.15.3 - 1594 1595 UNIFORM_OFFSET 0*xZ GetActiveUniformsiv - Uniform buffer offset 2.15.3 - 1596 1597 UNIFORM_ARRAY_STRIDE 0*xZ GetActiveUniformsiv - Uniform buffer array 2.15.3 - 1598 stride 1599 1600 UNIFORM_MATRIX_STRIDE 0*xZ GetActiveUniformsiv - Uniform buffer intra- 2.15.3 - 1601 matrix stride 1602 1603 UNIFORM_IS_ROW_MAJOR 0*xZ+ GetActiveUniformsiv - Whether uniform is a 2.15.3 - 1604 row-major matrix 1605 1606 UNIFORM_BLOCK_BINDING 0*xZ+ GetActiveUniformBlockiv 0 Uniform buffer binding 2.15.3 - 1607 points associated with the 1608 specified uniform block 1609 1610 1611 UNIFORM_BLOCK_DATA_SIZE 0*xZ+ GetActiveUniformBlockiv - Size of the storage 2.15.3 - 1612 needed to hold this 1613 uniform block's data 1614 1615 1616 UNIFORM_BLOCK_ACTIVE_UNIFORMS 0*xZ+ GetActiveUniformBlockiv - Count of active 2.15.3 - 1617 uniforms in 1618 the specified 1619 uniform block 1620 1621 UNIFORM_BLOCK_ACTIVE_UNIFORM_INDICES 1622 0*xnxZ+ GetActiveUniformBlockiv - Array of active 2.15.3 - 1623 uniform indices of 1624 the specified 1625 uniform block 1626 1627 UNIFORM_BLOCK_REFERENCED_BY_VERTEX_SHADER 1628 0*xB GetActiveUniformBlockiv 0 TRUE if uniform block 2.15.3 - 1629 is actively 1630 referenced by the 1631 vertex shader 1632 1633 UNIFORM_BLOCK_REFERENCED_BY_GEOMETRY_SHADER 1634 0*xB GetActiveUniformBlockiv 0 TRUE if uniform block 2.15.3 - 1635 is actively 1636 referenced by the 1637 geometry shader 1638 1639 UNIFORM_BLOCK_REFERENCED_BY_FRAGMENT_SHADER 1640 0*xB GetActiveUniformBlockiv 0 TRUE if uniform block 2.15.3 - 1641 is actively 1642 referenced by the 1643 fragment shader 1644 1645New Implementation Dependent State 1646 1647 Minimum 1648 Get Value Type Get Command Value Description Sec Attribute 1649 -------------------------------- -- ----------- ----- ------------------------- ----- ---------- 1650 MAX_VERTEX_UNIFORM_BLOCKS Z+ GetIntegerv 12 Maximum number of vertex 2.15.3 - 1651 uniform buffers per 1652 program 1653 1654 MAX_FRAGMENT_UNIFORM_BLOCKS Z+ GetIntegerv 12 Maximum number of fragment 2.15.3 - 1655 uniform buffers per 1656 program 1657 1658 MAX_GEOMETRY_UNIFORM_BLOCKS Z+ GetIntegerv 12 Maximum number of geometry 2.15.3 - 1659 uniform buffers per 1660 program 1661 1662 MAX_COMBINED_UNIFORM_BLOCKS Z+ GetIntegerv 36 Maximum number of uniform 2.15.3 - 1663 buffers per program 1664 1665 MAX_UNIFORM_BUFFER_BINDINGS Z+ GetIntegerv 36 Maximum number of uniform 2.15.3 - 1666 buffer binding points 1667 on the context 1668 1669 MAX_UNIFORM_BLOCK_SIZE Z+ GetIntegerv 16384 Max size in basic machine 2.15.3 - 1670 units of a uniform block 1671 1672 MAX_VERTEX_UNIFORM_COMPONENTS Z+ GetIntegerv * Number of words for vertex 2.15.3 - 1673 shader uniform variables 1674 in default uniform block 1675 1676 MAX_FRAGMENT_UNIFORM_COMPONENTS Z+ GetIntegerv * Number of words for fragment 2.15.3 - 1677 shader uniform variables 1678 in default uniform block 1679 1680 MAX_GEOMETRY_UNIFORM_COMPONENTS Z+ GetIntegerv * Number of words for geometry 2.15.3 - 1681 shader uniform variables 1682 in default uniform block 1683 1684 MAX_COMBINED_VERTEX_UNIFORM_COMPONENTS Z+ GetIntegerv * Number of words for vertex 2.15.3 - 1685 shader uniform variables 1686 in all uniform blocks 1687 (including default) 1688 1689 MAX_COMBINED_FRAGMENT_UNIFORM_COMPONENTS Z+ GetIntegerv * Number of words for fragment 2.15.3 - 1690 shader uniform variables 1691 in all uniform blocks 1692 (including default) 1693 1694 MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS Z+ GetIntegerv * Number of words for geometry 2.15.3 - 1695 shader uniform variables 1696 in all uniform blocks 1697 (including default) 1698 1699 UNIFORM_BUFFER_OFFSET_ALIGNMENT Z+ GetIntegerv 1 Minimum required alignment 2.15.3 - 1700 for uniform buffer sizes 1701 and offsets 1702 1703 * Minimum value for OpenGL 3.1 is (MAX_<stage>_UNIFORM_BLOCKS * 1704 MAX_UNIFORM_BLOCK_SIZE) + MAX_<stage>_UNIFORM_COMPONENTS. Minimum 1705 value prior to OpenGL 3.1 is MAX_<stage>_UNIFORM_COMPONENTS. 1706 1707Sample Code 1708 1709 //////////////////////////////////////////////////////////////////////////// 1710 Example: Full code of a simple use case: updating a group of variables 1711 in a real shader. 1712 //////////////////////////////////////////////////////////////////////////// 1713 1714 //Platform-specific includes go here 1715 1716 #define glError() { \ 1717 GLenum err = glGetError(); \ 1718 while (err != GL_NO_ERROR) { \ 1719 printf("glError: %s caught at %s:%u", \ 1720 (char*)gluErrorString(err), __FILE__, __LINE__); \ 1721 err = glGetError(); \ 1722 exit(-1); \ 1723 } \ 1724 } 1725 1726 // globals 1727 int initialized = 0; 1728 1729 int width=640; 1730 int height=480; 1731 1732 GLfloat wf,hf; 1733 //uniform names 1734 GLchar* names[] = 1735 { 1736 "SurfaceColor", 1737 "WarmColor", 1738 "CoolColor", 1739 "DiffuseWarm", 1740 "DiffuseCool" 1741 }; 1742 GLuint buffer_id, uniformBlockIndex, index, vshad_id, fshad_id, prog_id; 1743 GLsizei uniformBlockSize; 1744 GLint singleSize, offset; 1745 1746 GLfloat colors[] = 1747 { 1748 0.45,0.45,1,1, 1749 0.45,0.45,1,1, 1750 0.75,0.75,0.75,1, 1751 0.0,0.0,1.0,1, 1752 0.0,1.0,0.0,1, 1753 }; 1754 1755 void reshape(int w, int h) { 1756 width = w; height = h; 1757 wf = (GLfloat) width; 1758 hf = (GLfloat) height; 1759 glMatrixMode(GL_PROJECTION); 1760 glLoadIdentity(); 1761 gluPerspective(60.0, wf/hf, 0.1, 100.0); 1762 } 1763 1764 void init_opengl() 1765 { 1766 reshape(width, height); 1767 //load_shader and link_program are utility functions omitted here 1768 vshad_id = load_shader(GL_VERTEX_SHADER, "gooch.vs"); 1769 fshad_id = load_shader(GL_FRAGMENT_SHADER, "gooch.fs"); 1770 prog_id = glCreateProgram(); 1771 glAttachShader(prog_id, vshad_id); 1772 glAttachShader(prog_id, fshad_id); 1773 link_program(prog_id); 1774 1775 //Update the uniforms using ARB_uniform_buffer_object 1776 glGenBuffers(1, &buffer_id); 1777 1778 //There's only one uniform block here, the 'colors0' uniform block. 1779 //It contains the color info for the gooch shader. 1780 uniformBlockIndex = glGetUniformBlockIndex(prog_id, "colors0"); 1781 1782 //We need to get the uniform block's size in order to back it with the 1783 //appropriate buffer 1784 glGetActiveUniformBlockiv(prog_id, uniformBlockIndex, 1785 GL_UNIFORM_BLOCK_DATA_SIZE, 1786 &uniformBlockSize); 1787 glError(); 1788 1789 //Create UBO. 1790 glBindBuffer(GL_UNIFORM_BUFFER, buffer_id); 1791 glBufferData(GL_UNIFORM_BUFFER, uniformBlockSize, 1792 NULL, GL_DYNAMIC_DRAW); 1793 1794 //Now we attach the buffer to UBO binding point 0... 1795 glBindBufferBase(GL_UNIFORM_BUFFER, 0, buffer_id); 1796 //And associate the uniform block to this binding point. 1797 glUniformBlockBinding(prog_id, uniformBlockIndex, 0); 1798 glError(); 1799 1800 //To update a single uniform in a uniform block, we need to get its 1801 //offset into the buffer. 1802 glGetUniformIndices(prog_id, 1, &names[2], &index); 1803 glGetActiveUniformsiv(prog_id, 1, &index, 1804 GL_UNIFORM_OFFSET, &offset); 1805 1806 glGetActiveUniformsiv(prog_id, 1, &index, 1807 GL_UNIFORM_SIZE, &singleSize); 1808 glError(); 1809 1810 glViewport(0, 0, width, height); 1811 } 1812 1813 void render() 1814 { 1815 glClearColor(0.0, 0.0, 0.0, 0.0); 1816 glClear(GL_DEPTH_BUFFER_BIT|GL_COLOR_BUFFER_BIT); 1817 1818 glUseProgram(prog_id); 1819 1820 glEnable(GL_DEPTH_TEST); 1821 glMatrixMode(GL_MODELVIEW); 1822 glLoadIdentity(); 1823 glTranslatef(0, 0, -4); 1824 glColor3f(1.0, 1.0, 1.0); 1825 glBindBuffer(GL_UNIFORM_BUFFER, buffer_id); 1826 //We can use BufferData to upload our data to the shader, 1827 //since we know it's in the std140 layout 1828 glBufferData(GL_UNIFORM_BUFFER, 80, colors, GL_DYNAMIC_DRAW); 1829 //With a non-standard layout, we'd use BufferSubData for each uniform. 1830 glBufferSubData(GL_UNIFORM_BUFFER, offset, singleSize, &colors[8]); 1831 //the teapot winds backwards 1832 glFrontFace(GL_CW); 1833 glutSolidTeapot(1.33); 1834 glFrontFace(GL_CCW); 1835 glutSwapBuffers(); 1836 } 1837 1838 void display() 1839 { 1840 if(!initialized) 1841 { 1842 init_opengl(); 1843 initialized = 1; 1844 } 1845 1846 render(); 1847 } 1848 1849 int main (int argc, const char** argv) { 1850 //GLUT initialization goes here 1851 } 1852 1853 // Vertex shader for Gooch shading 1854 // Author: Randi Rost 1855 // Copyright (c) 2002-2006 3Dlabs Inc. Ltd. 1856 // See 3Dlabs-License.txt for license information 1857 1858 vec3 LightPosition = vec3(0.0, 10.0, 4.0); 1859 1860 varying float NdotL; 1861 varying vec3 ReflectVec; 1862 varying vec3 ViewVec; 1863 1864 void main(void) 1865 { 1866 vec3 ecPos = vec3 (gl_ModelViewMatrix * gl_Vertex); 1867 vec3 tnorm = normalize(gl_NormalMatrix * gl_Normal); 1868 vec3 lightVec = normalize(LightPosition - ecPos); 1869 ReflectVec = normalize(reflect(-lightVec, tnorm)); 1870 ViewVec = normalize(-ecPos); 1871 NdotL = (dot(lightVec, tnorm) + 1.0) * 0.5; 1872 gl_Position = ftransform(); 1873 } 1874 1875 // Fragment shader for Gooch shading, adapted for ARB_uniform_buffer_object 1876 1877 #extension GL_ARB_uniform_buffer_object : enable 1878 1879 layout(std140) uniform colors0 1880 { 1881 float DiffuseCool; 1882 float DiffuseWarm; 1883 vec3 SurfaceColor; 1884 vec3 WarmColor; 1885 vec3 CoolColor; 1886 }; 1887 1888 varying float NdotL; 1889 varying vec3 ReflectVec; 1890 varying vec3 ViewVec; 1891 1892 void main (void) 1893 { 1894 vec3 kcool = min(CoolColor + DiffuseCool * SurfaceColor, 1.0); 1895 vec3 kwarm = min(WarmColor + DiffuseWarm * SurfaceColor, 1.0); 1896 vec3 kfinal = mix(kcool, kwarm, NdotL); 1897 1898 vec3 nreflect = normalize(ReflectVec); 1899 vec3 nview = normalize(ViewVec); 1900 1901 float spec = max(dot(nreflect, nview), 0.0); 1902 spec = pow(spec, 32.0); 1903 1904 gl_FragColor = vec4 (min(kfinal + spec, 1.0), 1.0); 1905 } 1906 1907Examples 1908 1909 The following example illustrates the rules specified by the "std140" 1910 layout. 1911 1912 layout(std140) uniform Example { 1913 1914 // Base types below consume 4 basic machine units 1915 // 1916 // base base align 1917 // rule align off. off. bytes used 1918 // ---- ------ ---- ---- ----------------------- 1919 float a; // 1 4 0 0 0..3 1920 vec2 b; // 2 8 4 8 8..15 1921 vec3 c; // 3 16 16 16 16..27 1922 struct { // 9 16 28 32 (align begin) 1923 int d; // 1 4 32 32 32..35 1924 bvec2 e; // 2 8 36 40 40..47 1925 } f; // 9 16 48 48 (pad end) 1926 float g; // 1 4 48 48 48..51 1927 float h[2]; // 4 16 52 64 64..67 (h[0]) 1928 // 80 80..83 (h[1]) 1929 // 4 16 84 96 (pad end of h) 1930 mat2x3 i; // 5/4 16 96 96 96..107 (i, column 0) 1931 // 112 112..123 (i, column 1) 1932 // 5/4 16 124 128 (pad end of i) 1933 struct { // 10 16 128 128 (align begin) 1934 uvec3 j; // 3 16 128 128 128..139 (o[0].j) 1935 vec2 k; // 2 8 140 144 144..151 (o[0].k) 1936 float l[2]; // 4 16 152 160 160..163 (o[0].l[0]) 1937 // 176 176..179 (o[0].l[1]) 1938 // 4 16 180 192 (pad end of o[0].l) 1939 vec2 m; // 2 8 192 192 192..199 (o[0].m) 1940 mat3 n[2]; // 6/4 16 200 208 208..219 (o[0].n[0], column 0) 1941 // 224 224..235 (o[0].n[0], column 1) 1942 // 240 240..251 (o[0].n[0], column 2) 1943 // 256 256..267 (o[0].n[1], column 0) 1944 // 272 272..283 (o[0].n[1], column 1) 1945 // 288 288..299 (o[0].n[1], column 2) 1946 // 6/4 16 300 304 (pad end of o[0].n) 1947 // 9 16 304 304 (pad end of o[0]) 1948 // 3 16 304 304 304..315 (o[1].j) 1949 // 2 8 316 320 320..327 (o[1].k) 1950 // 4 16 328 336 336..347 (o[1].l[0]) 1951 // 352 352..355 (o[1].l[1]) 1952 // 4 16 356 368 (pad end of o[1].l) 1953 // 2 8 368 368 368..375 (o[1].m) 1954 // 6/4 16 376 384 384..395 (o[1].n[0], column 0) 1955 // 400 400..411 (o[1].n[0], column 1) 1956 // 416 416..427 (o[1].n[0], column 2) 1957 // 432 432..443 (o[1].n[1], column 0) 1958 // 448 448..459 (o[1].n[1], column 1) 1959 // 464 464..475 (o[1].n[1], column 2) 1960 // 6/4 16 476 480 (pad end of o[1].n) 1961 // 9 16 480 480 (pad end of o[1]) 1962 } o[2]; 1963 }; 1964 1965 1966Issues 1967 1968 (1) How are offsets to elements in a uniform buffer correlated to 1969 uniform locations? 1970 1971 Resolved: Traditional uniform locations were used in the glUniform 1972 API to access the private uniform storage. This API does not allow 1973 the use of glUniform to update uniforms stored in uniform blocks. 1974 Instead it uses the various means to update buffer objects, and 1975 exposes the byte offsets of the uniforms in the buffer object. So, 1976 in short, uniform locations and uniform offsets are similar concepts 1977 but unrelated. 1978 1979 (2) Should uniforms declared bindable be excluded from a uniform 1980 buffer? 1981 1982 Resolved: No, however, if a bindable uniform is declared inside 1983 a named uniform uniform block, the bindable declaration and all 1984 associated behavior of the bindable uniform extension will be 1985 superceded by the mechanisms defined in this extension to obtain 1986 information about the location of uniforms and to update the values 1987 of those uniforms. 1988 1989 In other words, if the bindable modifier is used on a uniform declared 1990 within a named uniform block, it will be ignored. 1991 1992 (3) Are there restrictions on the data types or the order in which uniforms 1993 are declared that are to be included as part of the uniform buffer? 1994 1995 Resolved: The only restriction is that sampler uniforms can not be 1996 stored in a uniform buffer object. All other uniform types can be 1997 stored in a uniform block. 1998 1999 (4) Should a uniform buffer be split into multiple uniform buffers 2000 on a per data type basis to simplify the buffer offset interface ? 2001 2002 Resolved: No. This violates the intended "generic data store" 2003 convention of buffer objects. Users of this extension are free 2004 to group their uniform definitions on a per data-type basis in 2005 this manner and, indeed, it may, on some implementations, result 2006 in a more efficient uniform update model. 2007 2008 (5) Should uniform buffers be scoped per shader (program 2009 stage) rather than per program (as in GLSL) ? 2010 2011 Resolved: No, this extension does not change the per-program 2012 scope of uniforms. Uniforms in a uniform block, like traditional 2013 GLSL uniforms, are global to a program object. 2014 2015 It's tricky because allowing uniforms to have per-stage scope 2016 exposes both a feature and the possibility for an application 2017 programming error. 2018 2019 feature: an application that wants to use a uniform "foo" in two 2020 stages and wants uniform "foo" has different layouts 2021 and/or values in each stage (or possibly simply does not 2022 care if they do) 2023 vs. 2024 2025 error: an application that wants to use a uniform "foo" in two 2026 stages and does not want them to have different values, but 2027 *accidentally* defines "foo" in each stage differently or 2028 binds different uniform buffers to each stage. 2029 2030 Rather than enable this feature (and simultaneously add possibility 2031 for error) in this extension, we defer the choice to a future 2032 extension. 2033 2034 Note however, some of the motivation for a per-stage scope for 2035 uniform names comes from a broader desire to augment the GLSL API 2036 with a set of per-stage program objects that do not need to be 2037 linked at all. This is possibly a valuable addition to the GL API, 2038 but is left to be defined by an additional extension. Such a future 2039 extension could, if desired, add syntax to the GLSL to allow any 2040 uniform (uniform block or default) to be defined with "per-stage" scope 2041 in a more comprehensive way. 2042 2043 2044 (6) Should AttachUniformBuffer take a <program> argument? 2045 2046 This issue is moot. Earlier versions of this extension included 2047 the additional ability to attach a uniform buffer object directly 2048 to a progam's uniform blocks instead of going through the per-context 2049 uniform buffer binding points. 2050 2051 This feature has been deferred, possibly to be added in a future 2052 extension. 2053 2054 If this routine were to be added and does not take a program 2055 argument, then it should work on the currently bound program 2056 object, and its name should be changed to 2057 ProgramUniformBuffer, to conform to precedent set by 2058 FramebufferTexture, et. all. 2059 2060 Alternately, if AttachUniformBuffer requires a program 2061 argument, it would be for consistency with existing C API to 2062 GLSL (i.e., those that attach shaders to program objects and 2063 query program objects for information). 2064 2065 RESOLUTION: RESOLVED, moot. 2066 2067 2068 (7) Should uniforms in a uniform block be identified by location or 2069 string? 2070 2071 Resolved: By string and also by index (but not location). Name 2072 strings will be used to identify uniforms much as they are 2073 today. Uniform indices were available before for referring to 2074 uniforms because they provide a more efficient update mechanism 2075 to specify uniforms. Uniform block indices have been used in 2076 this extension for the same reason. 2077 2078 The location API not used by this extension and is only relevant for 2079 the glUniform* API. 2080 2081 RESOLUTION: RESOLVED, moot. 2082 2083 2084 (8) What is the order of operations under which a uniform buffer 2085 association is made with a program (or shader)? 2086 2087 It is known that at very least, that the uniform buffer 2088 offsets and strides will be known at link time. Does the 2089 uniform buffer need to be attached to the program prior to linking in 2090 order to keep these offsets constant or can a uniform buffer be 2091 bound to a program at any time post-link effectively acting as 2092 substitute storage for the uniform data? 2093 2094 RESOLVED: Uniform buffer objects are bound to the context's 2095 uniform buffer binding points, and this can happen at any time. 2096 However, the association of a program's uniform block to the context's 2097 uniform buffer binding points can only happen after linking because only 2098 then are uniform block indices known. 2099 2100 2101 (9) Can the existing Uniform API be used to update values in a 2102 uniform buffer? 2103 2104 Resolved: No. The Uniform* API won't update values in a uniform buffer, 2105 which is reinforced by the fact that uniform block uniforms do not have 2106 a location. 2107 2108 2109 (10) When is the size of a uniform block's storage known? 2110 2111 Resolved: Only after linking. 2112 2113 Once a program is linked, the storage needed for a given uniform 2114 block can be determined by querying for 2115 UNIFORM_BLOCK_DATA_SIZE. 2116 2117 If a uniform block needs more storage than the buffer object 2118 bound to the associated uniform buffer binding point can provide, 2119 results are undefined. This is no different than fetching off the end 2120 of an array. 2121 2122 2123 (11) Is it an error to call AttachUniformBuffer prior to 2124 linking the program designated by <program>? 2125 2126 Resolved. This issue is moot because the 2127 AttachUniformBuffer was removed/deferred to a future 2128 extension. 2129 2130 But if this API were added, then yes. INVALID_VALUE is generated 2131 if AttachUniformBuffer is used to attach a buffer to an 2132 invalid uniform block index. Prior to linking, there are no 2133 uniform block indices. 2134 2135 2136 (12) Some hardware does not support some of the GLSL data types 2137 natively (bools or ints perhaps). What limitations do we have in 2138 exposing the raw uniform data storage via the buffer object API ? 2139 2140 Resolved: None, but note that some implementations without 2141 native support for these data types may have to copy the data 2142 in these data types into some more native data types. 2143 2144 Also, queries are provided to expose the layout of the buffer 2145 objects to allow the buffers to be packed properly. 2146 2147 2148 (13) Are there expected limitations for dead uniform elimination 2149 using this extension? 2150 2151 Resolved: yes. 2152 2153 For starters, when using the "std140" layout, an implementation 2154 may not alter the storage layout in any way. This limitation 2155 includes dead uniform elimination. The standard layout must 2156 remain unchanged because an application will depend on it 2157 rather than querying for uniform offsets/strides. 2158 2159 When using the "shared" layout, dead uniform elimination is again 2160 excluded because different uniforms could be eliminated based on 2161 different shaders' uniform usage. In order to preserve shareability 2162 of the uniform blocks, the full contingent of uniforms must remain. 2163 2164 For the "packed" layout, an implementation may take the liberty of 2165 eliminating uniforms and uniform blocks that are not used by the paired 2166 shaders. Here, limitations exist only for arrays. Dead elements may be 2167 stripped from the end of an array that is never dynamically 2168 dereferenced. An application must query UNIFORM_SIZE before 2169 loading array data into the uniform buffer to ensure that trailing 2170 elements exist. 2171 2172 Issue (24) deals with stripping leading elements from an array, and 2173 issue (25) deals with stripping arbitrary elements from an array, 2174 both of which are currently disallowed. 2175 2176 Note that the default uniform block always exists even if it is empty. 2177 2178 2179 (14) Is it necessary to provide array uniform element offsets into 2180 a uniform buffer object? If so, this suggests string parsing 2181 of things such as "myuniform[12]". If not, this assumes array 2182 strides be guaranteed based on array data type for all hw platforms? 2183 2184 Resolved: No. The stride is provided explictly by querying 2185 UNIFORM_ARRAY_STRIDE with GetActiveUniformsiv. 2186 2187 2188 (15) How are the values from static initializer values propagated 2189 to a buffer object once it is attached? 2190 2191 Resolved: Static initialization values declared in a shader mapped 2192 to a uniform buffer are disallowed by the grammar and must be 2193 established through writes to the uniform buffer. 2194 2195 2196 (16) Is GetUniformBlockIndex needed? This information can be 2197 obtained (in reverse mapping) from GetActiveUniformBlock. 2198 2199 Resolved: Yes. GetUniformBlockIndex allows the uniform 2200 block database to be queried in the most natural manner: step 1) 2201 do the expensive conversion from a uniform block name to a 2202 uniform block index, step 2) use the uniform block index to 2203 obtain all other uniform block data, which is a simple array 2204 dereference, not a search. 2205 2206 2207 (17) is GetUniformIndex needed? This information can be obtained (in 2208 reverse mapping) from GetActiveUniform. 2209 2210 Resolved: Yes. See issue (16). 2211 2212 2213 (18) Should we add a separate function GetActiveUniformBlockBufferSize 2214 instead of using GetActiveUniformBlock to return everything. 2215 2216 Resolved: No. This issue became moot when the more general function 2217 GetActiveUniformBlockiv was added. 2218 2219 2220 (19) Should we provide a mechanism for iterating over the uniforms in a 2221 particular uniform block? 2222 2223 Resolved: Yes. This is provided by querying 2224 UNIFORM_BLOCK_ACTIVE_UNIFORMS with GetActiveUniformBlockiv. 2225 2226 2227 (20) Should we provide a means for the application to query the desired 2228 storage format for integers, booleans, and matrices, or should we specify 2229 a format and force non-conforming implementations to do a conversion? 2230 2231 RESOLUTION: No queries will be introduced. Implementations that cannot 2232 handle the prescribed storage formats must convert as necessary. 2233 2234 See also issue (48) 2235 2236 2237 (21) Should we delete the integer and boolean storage types in favor of 2238 implementation repacking of the data when the hardware doesn't support it? 2239 2240 RESOLUTION: RESOLVED, no. 2241 2242 Hardware that doesn't support the types must repack the uniform data 2243 if needed. This is true for all layout options. 2244 2245 2246 (22) How does the program notice new changes to the uniform buffer object? 2247 2248 Should we add a new "UpdateUniforms()" call or use 2249 AttachUniformBuffer(), or UseProgram() to realize changes. 2250 2251 RESOLUTION: Following the "standard" way in which object changes are 2252 noticed, the buffer object in question must be re-bound or 2253 re-attached if the changes to the buffer object come from another 2254 context. 2255 2256 If the changes come from this context, then the intent is to 2257 follow the general object model decision here that governs how 2258 child/container object state changes are made. 2259 2260 [Currently, this means that changes by this context will be 2261 noticed at next draw time, at the latest]. 2262 2263 2264 (23) The naming convention choosen for GetActiveUniformsiv and 2265 GetActivePartitionsiv is not a simple matter. 2266 2267 First, considering that the list of uniforms passed into these 2268 routines must be active uniform indices, and is an error if not, 2269 suggests that the name "Active" in these function calls is 2270 redundant. GLSL established a precedent of using "Active" in 2271 the names of functions that require their uniform parameters to 2272 consist solely of active uniforms. For these routines, it is an 2273 error to include an inactive uniform as one of their input 2274 parameters. Consistency with this GLSL precedent is the reason 2275 we've choosen to include "Active" in these routine names. 2276 2277 Second, note that GetActiveUniformsiv does not "get active 2278 uniforms" and GetActiveUniformBlocksiv does not "get active 2279 uniform blocks". There is a compelling argument therefore that 2280 these names are counterintuitive. In reality, these routines 2281 return parameters of active uniforms and active uniform blocks 2282 rather than the uniforms or uniform blocks themselves. Again, 2283 looking back at GLSL precedent note the conventions used for 2284 both GetProgramiv and GetShaderiv. Both of these routines have 2285 a <pname> argument and both of these routines are in fact 2286 returning parameters of programs and shaders respectively 2287 however "Parameters" was not included in the name. 2288 2289 Further challenging this second point are two other 2290 considerations. First, the GL spec prior to GLSL does in fact 2291 use "Parameters" in the name of functions that match this 2292 pattern. Second, this spec itself includes the name of the 2293 output parameter in the name (specifically calls to get Indices 2294 and Names). 2295 2296 In the end, because this specification has to work within the 2297 GLSL framework, it was decided that this precendent should 2298 prevail over all others. Therefore, these routines will not 2299 include "Parameters" in their names. 2300 2301 Resolved: See above. 2302 2303 2304 (24) Do we need to be able to query UNIFORM_START to get the index of 2305 the first active element of an array? 2306 2307 An application must query UNIFORM_SIZE to find the extent of an 2308 array at runtime because the GLSL compiler may have eliminated elements 2309 from the end of a static array during dead code elimination. If the 2310 application is not required to similarly query UNIFORM_START, the 2311 compiler must be prevented from eliminating elements from the start of 2312 an array. 2313 2314 For example, if an application declares "uniform float myFloat[10];" and 2315 accesses only the single element myFloat[7] in the shader text, the 2316 compiler may eliminate elements 8-9 only. Querying UNIFORM_SIZE 2317 will give 8, and UNIFORM_OFFSET will give the offset of element 0. 2318 2319 If we add UNIFORM_START, in this example, querying 2320 UNIFORM_SIZE will give 1, UNIFORM_START will give 7, and 2321 UNIFORM_OFFSET will give the offset of element 7 in the uniform 2322 buffer. 2323 2324 Purely for symmetry, it seems that the compiler should be as free to 2325 strip leading elements as it is to strip trailing elements. 2326 2327 After additional discussions, however, the working group decided 2328 not to introduce this complexity. This feature could be layered 2329 as an additional extension if desired. 2330 2331 RESOLUTION: RESOLVED 2332 2333 2334 (25) Following issue (24), should we provide a mechanism to allow the 2335 compiler to strip *any* dead elements from a uniform array without 2336 restriction, not just leading and trailing elements? 2337 2338 Resolved: No. Too cumbersome for the application to use. 2339 2340 2341 (26) Should we make any guarantees about the ordering of uniforms in the 2342 active uniform array, relative to their uniform block number? 2343 2344 It might be useful to guarantee that the ordering of the 2345 uniforms in the active uniform array is such that all uniforms 2346 in a single uniform block form a contiguous subrange of the 2347 active uniform array. 2348 2349 On the other hand, just knowing the order is probably not enough 2350 since you need to know offsets/strides, packing, etc. 2351 2352 This extension provides uniform block-based uniform updates. 2353 This level of organization is efficient and requires no further 2354 augmentation as this issue suggests. 2355 2356 RESOLUTION: RESOLVED, no 2357 2358 2359 (27) What is the difference between 2360 MAX_LOGICAL_UNIFORM_BUFFERS and 2361 MAX_COMBINED_UNIFORM_BUFFERS? 2362 2363 MAX_LOGICAL_UNIFORM_BUFFERS is the maximum number of 2364 uniform buffer binding points on the context. 2365 MAX_COMBINED_UNIFORM_BUFFERS is the maximum number of 2366 uniform buffers that any one program can use at one time. 2367 2368 Note, see issue (46) for a related issue with textures. 2369 2370 RESOLUTION: RESOLVED 2371 2372 2373 (28) Should we have versions of GetActiveUniforms and GetActiveUniformBlocks 2374 that return intptr types so a cast is not required. 2375 2376 No. Another extension can add them, and they have no real 2377 utility at this time except causing the app to allocate twice as much 2378 storage to store values that can't exceed 32 bits. 2379 2380 RESOLUTION: RESOLVED, No. 2381 2382 2383 (29) Transform feedback writes primitive information to a buffer object 2384 tightly arranged and in accordance with the size of the attributes 2385 designated for transform feedback (or varyings thereof). If uniform 2386 buffers are to leverage data supplied from the transform feedback 2387 operation, yet uniforms are not guaranteed to be tightly packed, how 2388 can one reasonably use transform feedback to populate uniform 2389 buffers? 2390 2391 DISCUSSION: As it stands, existing implementations pack uniform 2392 definitions on 16 byte boundaries, 4 byte boundaries or are tightly 2393 packed. If this is known for a given implementation, uniform 2394 declarations could of course be made such that they lined up on these 2395 boundaries. However, without a dedicated queryable interface in the GL 2396 C API, there is no way to guarantee the portability of this logic. 2397 2398 RESOLUTION: resolved, compatibility with XFB output is only guaranteed 2399 for vec4 types in a "std140" layout uniform block: 2400 2401 In order to facilitate the read-only nature of uniform and 2402 transform feedback data formatting, we've added to this 2403 specification a uniform buffer "std140" layout qualifier guarantee of 2404 vec4 types being tightly packed. This layout guarantee will provide 2405 portability of applications that wish to use transform feedback in 2406 conjunction with uniform buffers as they can simply rely on this 2407 data arrangement, declaring their uniforms accordingly, to allow 2408 ARB_uniform_buffer_object and EXT_transform_feedback to 2409 interoperate. 2410 2411 2412 (30) Should the "active" keyword in shader text be declared per uniform or 2413 per uniform block ? 2414 2415 Note, this issue is mostly moot, as we've decided to use a 2416 different syntax in the GLSL. Earlier versions of this spec 2417 leveraged the concept of 'active' uniforms from GLSL that were 2418 defined with the initial GLSL API. 2419 2420 The discussion that follows pertains to a feature where the user can 2421 declare uniforms and uniform blocks as active explicitly. 2422 2423 DISCUSSION: Declaring a uniform active has the advantages of simplicity 2424 and little additional spec language to describe behavior. When a 2425 uniform is declared active, all of its members are considered active 2426 (for structs and arrays) and therefore the arrangement of the data in 2427 that uniform can be guaranteed to be consistent. Consistency of this 2428 uniform data arrangement can be used to share the uniform across muliple 2429 programs without worrying about dead code elimination changing the 2430 offsets and strides of uniform data. 2431 2432 Declaring uniform blocks active has some of the advantages that were 2433 primary motivating factors for this specficiation being written. 2434 Namely, that uniforms did not have to be aggregated into structures in 2435 order to update them efficiently. In this case, uniforms don't have to 2436 be aggregated into structs in order to share them easily. Another 2437 advantage is the logical distinction of a group of shared uniforms that 2438 is analogous to how the uniform buffer object, also a shared entity, 2439 that backs them. 2440 2441 If a uniform uniform block is declared active, all uniforms therein are 2442 considered active. It is presumed under this model, that an advisable 2443 usage pattern would be to gather the declaration of shared uniforms of 2444 multiple shaders into an atomic shader source call. Then each 2445 individual shader would carry declarations of uniforms unique to 2446 themselves. 2447 2448 GLSL allows piecewise declaration of uniforms in multiple modules in a 2449 program. Piecewise declaration of shared uniform blocks carries with it 2450 some difficulties because missing pieces can change the layout of the 2451 uniform block. 2452 2453 A) Should we disallow piecewise construction of uniform blocks 2454 declared active by setting a compile time error if this is 2455 attempted ? 2456 2457 RESOLVED: Yes, piecewise construction of uniform blocks will be 2458 allowed. 2459 2460 Proposal for active uniform block demarcation: 2461 2462 Active uniform blocks are declared as followed: 2463 2464 active uniform block foo; 2465 2466 uniform <type> a; 2467 uniform <type> b; 2468 uniform <type> c; 2469 2470 uniform block; 2471 2472 The first uniform block delimiter names the uniform block. The second 2473 uniform block, with no name argument, terminates the "foo" uniform block 2474 and indicates that any subsequent uniform definition will be part of the 2475 default uniform block. 2476 2477 Subsequent declarations referring to uniform block "foo" augment the 2478 contents of the uniform block. These subsequent declarations, of 2479 course, can appear within the same shader or within other shader sources 2480 in the same program. 2481 2482 This aggregation mechanism, and the use of piece-wise definitions of 2483 uniform blocks, has sharing implications. 2484 2485 Considering the following example: 2486 2487 ***************************** 2488 PROGRAM A Text: 2489 2490 active uniform block foo; 2491 2492 uniform <type> a; 2493 uniform <type> b; 2494 2495 uniform block; 2496 2497 2498 ***************************** 2499 PROGRAM B Text: 2500 2501 active uniform block foo; 2502 2503 uniform <type> b; 2504 uniform <type> a; 2505 2506 uniform block; 2507 2508 ... some place later in the program text 2509 2510 active uniform block foo; 2511 2512 uniform <type> e; 2513 uniform <type> d; 2514 2515 uniform block; 2516 ***************************** 2517 2518 Both the order and the number of uniforms in the aggregate definition of 2519 'foo' in program B must be considered for sharing the uniform buffer 2520 backing A & B corresponding to uniform block 'foo'. 2521 2522 First, order. To avoid potential confusion with order of declarations 2523 of uniforms, all uniforms declared in a uniform block will be sorted in 2524 an implementation defined manner. By doing so, the implementation will 2525 allow sharing of uniform buffers with identical uniform declarations by 2526 name, type and number, but arranged in different orders. 2527 2528 Second, mismatches in declarations of uniforms within 'foo' between two 2529 different programs. Because uniforms are sorted, partial matches of 2530 uniform declarations within uniform blocks are not guaranteed to have 2531 the same offsets when the buffer is bound to different programs. In our 2532 example, there are no guarantees that the offset of uniform 'a' and the 2533 offset of uniform 'b' would be the same in uniform block foo of program 2534 'A' when compared to program 'B'. Applications must therefore use care 2535 when attempting to share uniform buffers between multiple programs 2536 because any mismatch in uniform name or type or the number of uniforms 2537 themselves between uniform block declarations will result in offsets 2538 without correlation and application errors should be expected if any 2539 assumptions about these offsets is made otherwise. 2540 2541 This sharing behavior if of particular significance when defining 2542 shaders as it suggests that the shaders themselves, if they choose to 2543 define uniform blocks piecewise across given program text. This sharing 2544 model suggests defining all uniform uniform blocks that are expected to 2545 be shared as standalone shader text definitions to logically segragate 2546 them from uniform block declarations that can be changed in a piecewise 2547 fashion. In this manner, the logically separated shared uniform uniform 2548 block can be handled as a distinct ShaderSource call and effectively act 2549 as a header file where the uniform block definition is guaranteed to be 2550 the same when used in multiple programs thus allowing sharing and 2551 consistent offsets. 2552 2553 RESOLUTION: RESOLVED 2554 2555 Partitions, uniforms, and varyings can all have the "active" keyword 2556 applied to them. See rules q - t in the rules and concepts list 2557 following the opening summary to this spec. 2558 2559 The resolution of issue (34) to use struct-like syntax for uniform block 2560 definition closes the issue on piecewise definition of uniform blocks 2561 discussed above. 2562 2563 2564 (31) ActiveVaryingNV() uses the GL C API to declare a varying active in 2565 contrast to declaring uniforms/uniform uniform blocks active as suggested in 2566 this specification. Is this inconsistency a concern ? 2567 2568 RESOLUTION: RESOLVED, moot. 2569 2570 Earlier versions of this spec declared uniforms and uniform blocks 2571 as active, and optionally extended this to varyings as well. 2572 2573 Later versions of this spec deferred this concept out of the extension. 2574 2575 The declaring a varying as active via function call requires 2576 that this call is made prior to link time and that it identifies 2577 the varying using a name string. It is more efficient to manage 2578 program resources using indices and is better in terms of 2579 locality of reference to make 'active' declarations in program 2580 text. We should consider whether we might want to add this back 2581 in in a future extension. 2582 2583 2584 (32) GetVaryingLocationNV() returns -1 if the designated name doesn't 2585 exist. Should we return -1 rather than a special purposed token if a 2586 uniform name doesn't exist to follow this precedent ? 2587 2588 RESOLUTION: RESOLVED 2589 2590 This specification uses indices which are unsigned integers and 2591 therefore our unsigned value of 0xFFFFFFFF is not called "-1" 2592 but acts effectively the same on platforms where GLint is 2593 32-bit twos-complement. 2594 2595 Also note, uniform (and varying locations) are signed which 2596 allows them to use -1 as a signifier, but uniform (and uniform 2597 block) indices are unsigned because they are used to iterate 2598 through uniforms (and uniform blocks). 2599 2600 2601 (33) Which uniform buffer object commands must be excluded from display 2602 lists? 2603 2604 RESOLUTION: Resolved 2605 2606 When used with 3.1 (where display lists have been removed 2607 altogether) obviously, this question is moot. 2608 2609 For GL 2.0/3.0, this should be resolved with the following 2610 precedents: 2611 2612 BindUniformBlock should follow the precedent of BindBufferRange, 2613 which does not get included in display lists. 2614 2615 UniformBlockBinding should follow the precedent of glUniform (for 2616 setting samplers) which *does* get included in display lists. 2617 2618 Note, the GL 2.1 spec says (p.244, section 5.4) that "GL 2619 commands that source data from buffer objects dereference the 2620 buffer object data in question at display list compile time, 2621 rather than encoding the buffer ID and buffer offset into the 2622 display list. Only GL commands that are executed immediately, 2623 rather than being compiled into a display list, are permitted to 2624 use a buffer object as a data sink." 2625 2626 The same rules would affect uniform blocks sourcing data from 2627 buffer objects. 2628 2629 So this basically means that only BindUniformBlock is excluded, 2630 (since all queries are already excluded), however see issue (55). 2631 2632 Since we use the BindBufferRange API introduced by OpenGL 3.0, and 2633 those routines are already excluded, there's no additions to the 2634 display list exclusion list needed. 2635 2636 2637 (34) What should the syntax of uniform block demarcation be ? 2638 2639 DISCUSSION: The two following syntaxes were considered: 2640 2641 uniform block foo; 2642 2643 uniform <type> a; 2644 uniform <type> b; 2645 2646 uniform block; 2647 2648 In this example, the "uniform block" keyword both opens and closes the 2649 uniform block. 2650 2651 Second, a struct-like syntax: 2652 2653 uniform myUniformBlock 2654 { 2655 int a; 2656 vec4 b; 2657 }; 2658 2659 and 2660 2661 packed uniform myUniformBlock 2662 { 2663 int a; 2664 vec4 b; 2665 }; 2666 2667 where "packed" means that the uniform block might be optimized by the 2668 compiler to eliminate/re-order uniforms. 2669 2670 This is functionally equivalent to the current uniform block 2671 syntax in this spec. 2672 2673 RESOLUTION: RESOLVED, using the "struct-like" syntax above. 2674 2675 2676 (35) Should UBOs be bound to context binding points rather than to 2677 programs themselves ? 2678 2679 DISCUSSION: 2680 2681 Attaching UBOs to programs versus the context has the following 2682 advantages: 2683 2684 UBOs and programs have natural encapsulation boundaries that 2685 fit with the conventions of object-oriented design 2686 programming. 2687 2688 Alternately, binding UBOs to the context has the following advantages: 2689 2690 Migration to the possible program environment object design 2691 expected in future versions of OpenGL will be handled more 2692 easily and won't require a semantics change because these 2693 context bindings will all be moved collectively to the PEO 2694 and UBO attachments will not have to be handled as a 2695 "special case" item. 2696 2697 If we support per-context per-stage bindings, then we'll need the 2698 following additions to this extension: 2699 2700 - a set number of binding points on the context for each stage 2701 (vertex/fragment/geometry) 2702 VERTEX_SHADER_BINDING_0..n 2703 GEOMETRY_SHADER_BINDING_0..n 2704 FRAGMENT_SHADER_BINDING_0..n 2705 2706 or alternately, a unified set of per context bindings 2707 SHADER_BINDING_0..n 2708 2709 - a new routine to bind a UBO to a per-stage context binding point 2710 BindUniformBuffer(enum target, uint uniformBlockIndex, 2711 uint buffer); 2712 2713 - a new routine that defines the mapping of a uniform block name 2714 string to a per-stage binding point index 2715 void UniformBlockBinding(uint program, uint unit, 2716 const char* name); 2717 2718 2719 RESOLUTION: RESOLVED, 2720 2721 Note per-context and per-program bindings serve two distinct use cases. 2722 2723 Per-context: assumes that there is generally many to one mapping 2724 between programs and given set of uniform buffers. 2725 2726 Per-program: assumes that there is a one to one mapping between 2727 programs and a given set of uniform buffers. 2728 2729 The original ARB "assembly-language" programming extensions serviced 2730 both use cases (with "program locals" and "program environment" 2731 parameters). 2732 2733 The GLSL programming API dropped the "program environment" / 2734 per-context storage of uniforms in favor of per-program only storage 2735 for uniforms. 2736 2737 This API currently supports only the context binding model, but 2738 a future extension could add the per-program-object bindings if 2739 desired. 2740 2741 2742 (36) How is the query for MAX_{FRAGMENT|VERTEX}_UNIFORM_COMPONENTS 2743 affected by UBOs? 2744 2745 DISCUSSION: MAX_{FRAGMENT|VERTEX}_UNIFORM_COMPONENTS traditionally 2746 referred to the limited amount of dedicated (often register based, 2747 sometimes per-stage) uniform storage. For implementations that 2748 support directly reading uniforms from arbitrary memory, the limit 2749 on uniform storage is generally not quantified by a single number of 2750 uniforms. Instead it is quantified by two numbers: the number of 2751 separate buffers that can be read at one time (per stage), and the 2752 sizes of one of those buffers. 2753 2754 On the other hand for implementations that wish to support this 2755 extension but that still have this limited amount of dedicated 2756 uniform storage this single MAX_{FRAGMENT|VERTEX}_UNIFORM_COMPONENTS 2757 value is still valid. 2758 2759 RESOLUTION: Resolved, as follows: 2760 2761 We added a new set of integer implementation-dependent queries, named 2762 MAX_COMBINED_{VERTEX|GEOMETRY|FRAGMENT}_UNIFORM_COMPONENTS. These 2763 would indicate the maximum total number of uniforms available between 2764 the default uniform block and all uniform blocks. For this ARB version 2765 of the extension, the minimum maximum would be 2766 MAX_{VERTEX|GEOMETRY|FRAGMENT}_UNIFORM_COMPONENTS. For the 3.1 core 2767 version, the minimum maximum would be larger: 2768 MAX_{VERTEX|GEOMETRY|FRAGMENT}_UNIFORM_BLOCKS * MAX_UNIFORM_BLOCK_SIZE + 2769 MAX_{VERTEX|GEOMETRY|FRAGMENT}_UNIFORM_COMPONENTS. 2770 2771 2772 (37) Do we need MAX_{VERTEX|GEOMETRY|FRAGMENT}_UNIFORM_BUFFERS 2773 or can we merge these into a single value MAX_UNIFORM_BUFFERS that 2774 is the same for the 3 stages? 2775 2776 DISCUSSION: 2777 2778 3 separate queries is needed only if we think implementations would have 2779 different values for each stage. 2780 2781 RESOLUTION: currently 3 queries, plus a "combined" query. 2782 2783 2784 (38) What's the deal with UniformBlockBinding()? How does it 2785 work? What is it for? 2786 2787 DISCUSSION: 2788 2789 UniformBlockBinding can be defined in two different ways, depending on 2790 the precedent we'd like to use. 2791 2792 It can either be similar to a uniform sampler (i.e., an indirection 2793 table that can choose a particular buffer to use after linking), or 2794 an attribute location (i.e., an indirection table that can choose a 2795 particular buffer to use PRIOR to linking). 2796 2797 The current API chooses the former precedent (i.e., uniform 2798 samplers), and as a result, UniformBlockBinding can be called (in 2799 fact, must be called) after linking the program. 2800 2801 If we desired to change this behavior, we'd need to modify 2802 UniformBlockBinding to take a uniform block *name* intead of *index*, 2803 because a uniform block index is only defined post-link. 2804 2805 This is workable, but slightly less flexible for the developer, at 2806 the cost of an indirection. 2807 2808 RESOLUTION: Use the "sampler" precedent, UniformBlockBinding is 2809 called post link. 2810 2811 2812 (39) Does the matrix packing need to be "per program" state or "per 2813 implementation" state? 2814 2815 DISCUSSION: 2816 2817 Is the choice of matrix packing really "per program"? If not, 2818 should we just use the per-context queries for this information? The 2819 former might be useful if we intend to expose some kind of 2820 per-program packing control in the shading language or API. If we 2821 don't, then the latter might be simpler. 2822 2823 Or do we think we might go further and make this per-uniform state 2824 in the future? if so, then the current per-program query is also 2825 insufficient. 2826 2827 After discussion with the working group, queries for 2828 matrix (and all other uniform layout) will be per-uniform, not 2829 per program, so these routines have been removed. 2830 2831 RESOLUTION: Resolved, this issue is moot. 2832 2833 2834 (40) Are uniform block indices assumed to be "tightly packed"? 2835 2836 Yes, an implementation will assign consecutive indices to 2837 active uniform blocks, starting with zero. 2838 2839 Note that there is no prescribed ordering in which indices must be 2840 assigned. In other words, which uniform block indices are assigned to 2841 which uniform blocks is an implementation choice. An application must 2842 call GetUniformBlockIndex to find the mapping. 2843 2844 RESOLUTION: Resolved, yes. 2845 2846 2847 (41) Is "uniform block" the right name? 2848 2849 The GLSL group considered many names here: "uniform blocks", 2850 "commons", "uniform groups", etc. Regardless of what the GLSL 2851 calls these groupings, we need *some name* that we can describe 2852 in the API spec and in the API names. Currently we use "uniform 2853 block" for this, and the API seems to make sense, but could 2854 change if someone has a better name. 2855 2856 RESOLUTION: RESOLVED, yes. 2857 2858 2859 (42) Should there be an "offset" for the base of the ubo so that an 2860 application can use collections uniforms within a buffer object? 2861 2862 DISCUSSION: 2863 2864 If we do this, we'd need an additional/augmented version of 2865 BindUniformBuffer that takes an offset, and a queriable required 2866 alignment for the offset. See also issue 55. 2867 2868 Currently, we do now support this offset (via BindBufferRange) and an 2869 alignment query (UNIFORM_BUFFER_OFFSET_ALIGNMENT). The offset 2870 is per-context binding point state. We probably want to pick up 2871 UNIFORM_BUFFER_START and UNIFORM_BUFFER_SIZE queries, too. See issue 2872 (65) to track whether we add these. 2873 2874 RESOLUTION: Resolved, there should be an offset for the base of a 2875 uniform block within a UBO. If an implementation can not support 2876 non-zero offsets, they can set UNIFORM_BUFFER_OFFSET_ALIGNMENT 2877 to a sufficiently large value. 2878 2879 2880 (43) Do we need the versions of the uniform queries that query the 2881 GL for the properties/names of multiple uniforms at one time? Or 2882 can we simplify those apis to only query for the property/name of 2883 one uniform at a time? 2884 2885 DISCUSSION: The multiquery apis are useful for getting lists of 2886 uniform data at once, but are more complicated (require arrays of 2887 pointers to output values). 2888 2889 Do we need these? 2890 2891 RESOLUTION: Resolved, we'll replace GetActiveUniformNames with 2892 GetActiveUniformName, but keep the rest which have solid use 2893 cases. 2894 2895 2896 (44) What is the default value for UNIFORM_BLOCK_BINDING? 2897 2898 Having the default values be set equal to the uniform block index at 2899 link time would be convenient. This would make it unnecessary 2900 for apps to call glUniformBlockBinding unless they wanted a 2901 non-default mapping. 2902 2903 After some discussion, using texture samplers as precedent, then 2904 the default value should be zero. 2905 2906 RESOLUTION. Resolved, default value is zero. 2907 2908 2909 (45) What is the default value of UNIFORM_BLOCK_BUFFER_BINDING? 2910 2911 This is moot without the AttachUniformBuffer API. This was the 2912 query for the uniform buffer object bound directly to a uniform 2913 block in the program object. 2914 2915 If we add this API in a future extension, it seems it should be 2916 zero. We would need for the spec to state the precedence of 2917 program attachments over context attachments. I.e., if the 2918 value of UNIFORM_BLOCK_BUFFER_BINDING is non-zero, then 2919 the backing for that uniform block comes from the specified 2920 uniform block uniform buffer binding, otherwise it comes from 2921 the unit binding, and hence from the context that is currently 2922 using the program. 2923 2924 RESOLUTION. RESOLVED, moot. 2925 2926 2927 (46) How do the logical/combined maximums for UBOs and textures 2928 relate to each other? 2929 2930 Textures have these queries: 2931 2932 MAX_TEXTURE_IMAGE_UNITS 2933 maximum textures that can be used by the fragment stage. 2934 2935 MAX_COMBINED_TEXTURE_IMAGE_UNITS 2936 maximum textures that can be used by all program stages 2937 at once. 2938 2939 Ideally, MAX_TEXTURE_IMAGE_UNITS would be called 2940 "MAX_FRAGMENT_TEXTURE_IMAGE_UNITS" 2941 2942 Also, most implementations use MAX_TEXTURE_IMAGE_UNITS to define 2943 the number of per-context binding points for textures, though 2944 technically, there's no requirement that the number of context 2945 binding points is equal to the number of fragment textures. 2946 2947 For instance, if an implementation had the ability to use more 2948 vertex or geometry textures than fragment textures, then this 2949 scheme would break down because there would not be enough 2950 context binding points for these other stages. 2951 2952 This spec tries to avoid this problem with the following queries: 2953 2954 MAX_VERTEX_UNIFORM_BLOCKS 2955 MAX_GEOMETRY_UNIFORM_BLOCKS 2956 MAX_FRAGMENT_UNIFORM_BLOCKS 2957 MAX_COMBINED_UNIFORM_BLOCKS (much like "combined" for textures) 2958 MAX_UNIFORM_BUFFER_BINDINGS (# UBO binding points on context) 2959 2960 For symmetry, we'd recommend that we make a similar update to textures 2961 in the 3.1 spec: 2962 2963 MAX_FRAGMENT_SAMPLERS (= old MAX_TEXTURE_IMAGE_UNITS) 2964 MAX_GEOMETRY_SAMPLERS (= old MAX_GEOMETRY_TEXTURE_IMAGE_UNITS) 2965 MAX_VERTEX_SAMPLERS (= old MAX_VERTEX_TEXTURE_IMAGE_UNITS) 2966 MAX_COMBINED_SAMPLERS (= old MAX_COMBINED_TEXTURE_IMAGE_UNITS) 2967 MAX_TEXTURE_IMAGE_BINDINGS (# texture binding points on context) 2968 2969 RESOLUTION: Resolved. The texture token name changes should be made 2970 in the 3.1 API spec, deprecating the old names. 2971 2972 2973 (47) Is using a keyword to specify packed/shared/std140 the best way 2974 to manage uniform block packing? What do they mean anyway? 2975 2976 DISCUSSION: 2977 2978 There are 3 use cases of interest: 2979 2980 "packed" 2981 2982 - implementation may optimize the layout to remove inactive 2983 uniforms and otherwise restructure the layout for 2984 efficiency. 2985 2986 - application must query the GL for the uniform block layout 2987 2988 "shared" 2989 2990 - implementation may optimize the layout but must use the same 2991 layout across shaders so that the resulting layout can be shared 2992 by multiple shaders 2993 2994 - application must query the GL for the uniform block layout 2995 2996 2997 "std140": 2998 - implementation must use a pre-determined layout, defined 2999 in this specification. 3000 - application need not query the implementation for layout 3001 information as it can be determined by reading the shader 3002 and the specification 3003 3004 3005 Other options considered included: 3006 - an API in the GL 3007 - a #pragma in the GLSL 3008 - gcc style __attribute__ tokens 3009 - others? 3010 3011 RESOLUTION: resolved, we use a layout qualifier construct which 3012 includes identifiers for "packed", "std140", and "shared" which is the 3013 intial default. These qualifiers can be used either within a uniform 3014 block declaration, or at global scope causing subsequent uniform blocks 3015 with unspecified layouts to adopt a new default layout. 3016 3017 3018 (48) What is the "std140" packing layout? 3019 3020 This extension is supposed to define a standard packing layout 3021 that applications can choose to use and know the uniform block 3022 data layout within the uniform buffer without querying the 3023 implementation. 3024 3025 The user would need to opt-in to this layout. 3026 3027 We need to define what this layout looks like. 3028 3029 See also issue (20). 3030 3031 RESOLUTION: resolved, standard layout is now in 2.15.3.1.2. 3032 3033 3034 (49) Will storage of int/ivec*/uint/uvec*/float/vec* be guaranteed 3035 to match the GLint, GLuint, and GLfloat types of the CPU's 3036 implementation? What if the CPU and GPU differ? What about indirect 3037 renderers? 3038 3039 See also issues (20) and (48) 3040 3041 RESOLVED: We've never figured out how to properly handle other buffer 3042 object extensions (e.g., VBO) in conjunction with indirect rendering 3043 with data type differences. This feature should continue that fine (?) 3044 tradition. 3045 3046 Ignoring indirect rendering, if the native data types of the GLSL 3047 executable's processor differs from the client's representation, data 3048 should still be extracted from buffer objects using the client's 3049 representation. Mechanisms that could be used to accomplish this 3050 include: 3051 3052 * having the driver making a copy of the buffer object for internal use, 3053 doing conversion during the copy; 3054 3055 * having the GLSL executable's processor automatically convert data 3056 types as they are fetched; or 3057 3058 * generating code to be executed by the GLSL executable's processor to 3059 manually perform data type conversions. 3060 3061 If dealing with data type mismatches turns out to be a problem on some 3062 implementations, it might be possible to provide an extension where 3063 applications to avoid conversion overhead by storing data using the 3064 native data type of the GPU, instead of the CPU. 3065 3066 3067 (50) This extension needs to be sanitized to be written against 3068 the 2.1 and 3.0 core specs. What are the differences? 3069 3070 Aside from the sanity checking for using the right 3071 section numbers and such, there are two other changes: 3072 3073 1) GetIntegeri_v doesn't exist in 2.0 so needs to be 3074 added by this extension for the 2.0 version 3075 3076 2) The "max components" query needs different behavior 3077 for a 2.1 vs. a 3.0/3.1 implementation. See issue (36) 3078 3079 3080 RESOLUTION: Resolved, interactions section added which 3081 details the differences when OpenGL 3.0 is supported. 3082 Spec is written against OpenGL 2.1, so that's where the 3083 section numbers come from. 3084 3085 3086 (51) Do we need to name the default uniform block with index 0 and 3087 name ""? 3088 3089 This is done for symmetry and to allow iterating through 3090 all uniform blocks, including the default, and treat them 3091 similarly. 3092 3093 On the other hand, it's a little weird since the default 3094 partition can not be used with a buffer object. On the third hand, 3095 maybe some day we will allow that. 3096 3097 As a side note, if we go with a name, should it be "", or 3098 perhaps "gl_DefaultUniformBlock" or something like that. 3099 3100 RESOLUTION: Resolved, do not reserve block number 0 for the default 3101 uniform block. The default uniform block no longer needs a name. 3102 If the uniform block index is queried for a uniform that is associated 3103 with the default uniform block, -1 is returned. 3104 3105 3106 (52) The current extension spec seems to specify "uint" indices, but 3107 the values in the queries such as GetActiveUniformBlockiv are 3108 returned as "int" values. Should we fix this? 3109 3110 Need to double check the APIs to see if we'd have to duplicate 3111 some or all of the queries to make them type safe for signed vs. 3112 unsigned ints. 3113 3114 RESOLUTION: resolved, No. There are a few other places in the GL 3115 query APIs that already suffer from this problem. 3116 3117 3118 (53) What are the UNIFORM_BLOCK_REFERENCED_BY_*_SHADER queries used 3119 for? 3120 3121 The total number of uniform blocks in each stage may be subject 3122 to a per-stage limit on some implementations. These queries 3123 allow the user to query the program's uniform blocks to see 3124 which are used for each stage. 3125 3126 RESOLUTION: resolved 3127 3128 (54) How do the APIs that use uniform locations relate to the 3129 uniforms in named uniform blocks? And how do the APIs 3130 introduced by this extension relate to uniforms in the default 3131 uniform block? 3132 3133 Basically, locations can't be used with uniforms in a uniform 3134 block, so that rules out any queries that require locations. 3135 3136 However, the query APIs introduced by this extension can be used 3137 with all uniforms, including those in a default uniform block. 3138 3139 RESOLUTION: resolved 3140 3141 (55) Should we use the BindBufferBase/BindBufferRange APIs that were 3142 introduced in GL 3.0 instead of BindUniformBuffer? 3143 3144 As defined, they'd work fine. 3145 3146 One side issue: should the "offset" be part of the context binding? 3147 or should the uniform blocks get to each select their own 3148 offset within a single context binding? 3149 3150 If implementations can support the latter, it may allow 3151 applications to get by with fewer context bindings. 3152 3153 If not, then we should replace BindUniformBuffer with 3154 these routines, but for the 2.0 extension version we'd still 3155 need to add those routines and duplicate their spec language 3156 in this spec. 3157 3158 See issue 42 for the resolution of this side issue. 3159 3160 RESOLUTION: resolved, yes we should use BindBufferBase/Range. 3161 3162 3163 (56) Can a mapping from uniform block to uniform buffer object be 3164 queried? 3165 3166 On one hand, it seems like GetActiveUniformBlock could handle 3167 it. 3168 3169 On the other hand, this linking is indirect: a uniform block 3170 selects a binding point, and a binding point binds a UBO. The GL 3171 *could* do the indirect lookup for you, but the data would only be 3172 valid until you changed the unit binding, so it's a little fragile 3173 for the implementation to provide this query. 3174 3175 RESOLUTION: Resolved, not needed, the user can do this. 3176 3177 3178 (57) Should we have MAX_UNIFORM_BUFFER_SIZE or a max size on 3179 uniform block data instead? 3180 3181 The uniform buffer could be larger than the amount of uniform 3182 block(s) data inside it. 3183 3184 Also see issue (36). 3185 3186 RESOLUTION: Resolved, name is MAX_UNIFORM_BLOCK_SIZE. 3187 3188 3189 (58) Is there any expectation that uniforms stay in the order 3190 declared for the packed/shared layouts? 3191 3192 This might make sharing easier, but is not clear if it's 3193 worth it / overly constraining. 3194 3195 RESOLUTION: resolved, yes, names/types must retain declaration order 3196 3197 3198 (59) Do we need the glsl syntax for declaring arrays of uniform 3199 blocks? 3200 3201 Deferred this feature to a future extension. 3202 3203 RESOLUTION, resolved 3204 3205 3206 (60) When using this extension with OpenGL 2.1/3.0, do we require 3207 that uniform buffer object names must be generated with glGenBuffers 3208 to be used with these new entry points? 3209 3210 For OpenGL 3.1 core, there is a blanket requirement to call glGen 3211 for object names. 3212 3213 For OpenGL 2.x, there is not a requirement to call glGen but in 3214 3.0, user-generated names have been deprecated. 3215 3216 For 3.0, we added two new object types (FBO/VAO) that 3217 required the user to call glGen, but existing object types 3218 (textures/renderbuffers/buffer objects) could be used 3219 without calling glGen. 3220 3221 We need to decide what to do with this when exporting 3222 this extension on 2.1 and 3.0. 3223 3224 RESOLUTION: Resolved, this extension does not govern the creation of 3225 buffer objects. That's done by BindBuffer, which is not altered 3226 by this spec, so on 2.1 and 3.0 you'd be able to use any name, 3227 whereas on 3.1 you'd be required to call GenBuffers. 3228 3229 3230 (61) Do we need "instance name" syntax? 3231 3232 RESOLUTION: resolved, deferred for now 3233 3234 3235 (62) Why don't the new tokens and entry points in this extension have 3236 "ARB" suffixes like other ARB extensions? 3237 3238 RESOLVED: Unlike a normal ARB extension, this is a strict subset 3239 of functionality already approved in OpenGL 3.1. This extension 3240 exists only to support that functionality on older hardware that 3241 cannot implement a full OpenGL 3.1 driver. Since there are no 3242 possible behavior changes between the ARB extension and core 3243 features, source code compatibility is improved by not using 3244 suffixes on the extension. 3245 3246 3247 (63) Should we introduce a query of a program's longest uniform name length, 3248 similar to the ACTIVE_UNIFORM_BLOCK_MAX_NAME_LENGTH query of a 3249 program's longest uniform block name? 3250 3251 RESOLUTION: Resolved, no. ACTIVE_UNIFORM_MAX_LENGTH serves this purpose 3252 well enough. No great need for a per uniform block query of the same. 3253 3254 3255 (64) What should the UNIFORM_OFFSET query return for uniforms that 3256 are associated with the default uniform block? Same for strides? 3257 3258 RESOLUTION: Resolved, spec'd to return -1 in these cases. 3259 3260 3261 (65) Should we add queries for the base offset and size of the uniform 3262 buffer bound to a binding point? What should the names be? 3263 3264 DISCUSSION: This would be analogous to the similar transform feedback 3265 queries. Names could be UNIFORM_BUFFER_START and UNIFORM_BUFFER_SIZE. 3266 3267 RESOLUTION: Resolved, yes. 3268 3269 3270 (66) Should we provide some mechanism allow applications to annotate their 3271 uniform declarations to specify an offset by hand? Direct3D 10 does. An 3272 example of the D3D syntax: 3273 3274 cbuffer D3DExample { 3275 float4 a : packoffset(c0); // bytes 0-15 3276 float3 b : packoffset(c16); // bytes 256-267 (c0-c15 are all vec4s) 3277 float1 c : packoffset(c1.y); // bytes 20-23 3278 } 3279 3280 If so, how would we handle a mixed declaration that includes some 3281 uniforms with annotations and others without? 3282 3283 RESOLVED: An annotation mechanism would be useful for fine-grained 3284 application control, but we will defer this. 3285 3286 3287 (67) Should we provide a mechanism to expose both row-major and column-major 3288 storage of matrices? 3289 3290 If no controls are provided in GLSL 1.40, the default resolution for the 3291 UBO layout documentation would be to treat all matrices as column-major. 3292 We will also need to pick a default orientation for matrices with that 3293 use no GLSL language mechanism to declare orientation. 3294 3295 Either way, the UBO GL API should provide a GetActiveUniform query to 3296 determine if an active matrix is stored in row- or column-major order. 3297 3298 RECOMMENDATION: Provide a should have a type modifier for matrix 3299 declarations, for example: 3300 3301 row_major mat4 matrix1; 3302 column_major mat4 matrix2; 3303 3304 It may be desirable to have a global control (e.g., a #pragma) to 3305 specify that all matrices are row- or column-major. 3306 3307 RESOLVED: Yes, we should provide this control. It is now available 3308 in the form of uniform block layout qualifiers. The identifiers 3309 "row_major" and "column_major" are allowed, with the latter serving as 3310 the initial default. These qualifiers can be specified on a per- 3311 matrix basis, a per-uniform block basis (affecting all matrices within 3312 the uniform block that have unspecified orders), or globally. In the 3313 latter case, all subsequent matrices with unspecified order will adopt 3314 a new default order. 3315 3316 3317 (68) Should the buffer layout be expressed in terms of standard GL types? 3318 For example, should the storage for a "vec3" be equivalent to "GLfloat [3]"? 3319 3320 RESOLVED: Yes. One other alternative would be to specify exact type 3321 (e.g., "32-bit floats using IEEE 754 encoding", "32-bit two's complement 3322 integers", etc...). These choices will be roughly equivalent in 3323 practice, and it's probably better to use standard GL types. 3324 3325 3326 (69) Do we need to pad the end of structures and/or arrays using the 3327 standard packing rules? Or should we be able to squeeze data types with 3328 small alignment requirements in the "holes" left at the end of structures or 3329 arrays with larger alignment requirements? 3330 3331 uniform ExamplePad { 3332 // with without 3333 // padding padding comments 3334 // ------- ------- ------------------------ 3335 struct { // 3336 vec3 a; // 0..11 0..11 3337 } b; // add 4B of padding? 3338 float c; // 16..19 12..15 3339 vec3 d[2]; // 32..43 16..27 align to 16B due to vec3 3340 // 48..59 32..43 add 4B of padding? 3341 float e; // 64..67 44..47 3342 struct { // align to 16B due to <f> 3343 vec4 f; // 80..95 48..63 3344 ivec2 g; // 96..103 64..71 3345 } h; // add 8B of padding? 3346 uint i; // 112..115 72..75 3347 } 3348 3349 The strongest argument against padding is compactness. 3350 3351 The strongest argument in favor of padding is to have a structure 3352 definition that can be matched with a similar structure definition in 3353 application code. For example, consider the following GLSL code: 3354 3355 uniform Example { 3356 vec3 a[10]; 3357 float b; 3358 }; 3359 3360 The standard layout rules suggest that the vec3 members of "a" are 3361 effectively padded out to vec4's in the array; so the natural C structure 3362 would look like: 3363 3364 typedef struct { float x, y, z, pad; } vec3InArray; 3365 struct Example { 3366 vec3InArray a[10]; 3367 float b; 3368 } 3369 3370 The problem is that without padding the end of arrays, the uniform "b" 3371 will be stored immediately after the last float in a[9], but with the C 3372 structure, that word will be consumed by a[9].pad, and "b" will be stored 3373 one word following. 3374 3375 A similar issue arises with structures; common C compilers seem to pad the 3376 end of structures to the largest alignment of the atomic types used in the 3377 structure. For example, if you have: 3378 3379 struct { 3380 double a; 3381 char b; 3382 } c; 3383 3384 common compilers will generate code where sizeof(c)==16. We are 3385 effectively treating vectors and matrices as atomic types, so it seems to 3386 make sense that for GLSL code like: 3387 3388 struct { 3389 vec4 a; 3390 float b; 3391 } c; 3392 3393 it would follow that sizeof(c)==32. 3394 3395 RESOLVED: Yes, we need to pad in support of the reasons above. 3396 3397 3398 (70) Should "bool" data types be represented as 8-bit quantities (a la 3399 GLboolean in most gl.h versions) or 32-bit? 3400 3401 RESOLVED: Use 32-bit integers. 3402 3403 Using GLboolean (8-bit) would be the closest match to the API types, but 3404 some implementations of this standard may prefer 32-bit integers at this 3405 point. We don't expect uniform blocks to contain enough bool-typed data 3406 where the wasted storage matters significantly. 3407 3408 One other option considered was to have an implementation-dependent 3409 representation, which could be queried, but requiring applications to 3410 query and handle multiple basic data types seemed cumbersome. Even if 3411 we did this, we would still want to have a single representation for a 3412 fully-defined "std140" packing, at least. 3413 3414 3415 (71) What happens we are using indirect rendering where the data types used 3416 by the client and server differ, due to endianness or some other issues 3417 related to basic data type? What happens if the processor running the GLSL 3418 executable uses different data type representations than the application? 3419 3420 DUPLICATE of issue (49) 3421 3422 3423 (72) What parameters should we provide for querying the layout of matrices 3424 (and arrays of matrices) in memory? 3425 3426 RESOLVED: We expect that matrices will be stored as an array of column 3427 vectors or row vectors. There are two possibly independent strides: 3428 3429 - bytes between columns/rows within a single matrix 3430 - bytes between matrices within an array of matrices 3431 3432 The GetActiveUniform*() API for UBO will provide queries for both 3433 strides. 3434 3435 For single matrices, the stride between columns/rows is the only 3436 parameter. Some implementations may provide tightly packed matrices, 3437 where a 3x3 column-major matrix might be represented with 9 consecutive 3438 floats with a 12-byte (3-float) stride between columns. Others, such as 3439 the "std140" packing above represents such a matrix as an array of 3 3440 column or row vectors, but pads each row/column for a 16-byte (4-float) 3441 stride. 3442 3443 For arrays of matrices, two queries would be needed for maximum 3444 flexibility. For example, a hypothetical implementation might pack 3x3 3445 arrays tightly as 9 floats, but require that each array in the matrix be 3446 aligned on a 16-byte boundary. This would have a column stride of 12B, 3447 but would require a matrix stride of 48B, not 3*12=36B. If we didn't 3448 care about such implementations, an alternate approach would be to 3449 treat an array of N column-major matrices with C columns as though it 3450 were an array of N*C column vectors, as in the std140 layout. The 3451 stride between matrices would be derived from the stride between 3452 columns. 3453 3454 Providing multiple queries seems like the safest choice, and doesn't 3455 have any significant down-side. The first stride query, between major 3456 vectors of a matrix, is UNIFORM_MATRIX_STRIDE. The latter query is 3457 actually the same UNIFORM_ARRAY_STRIDE query used for any type of 3458 array element. 3459 3460 3461 (73) Should GetActiveUniform allow you to query if a matrix is column- or 3462 row-major, so an app can determine the layout without knowing how the 3463 matrix is declared in the shader? 3464 3465 RESOLVED: Yes, UNIFORM_IS_ROW_MAJOR. 3466 3467 3468 (74) What's language mechanism should be used for opting into standard 3469 layout? 3470 3471 At the January 2009 F2F, it was recommended to specify a per-uniform 3472 block layout via a language mechanism such as: 3473 3474 layout(<identifier>) uniform { 3475 ... 3476 }; 3477 3478 where <identifier> must be "std140" in the current standard. Future 3479 extensions and core versions could define additional identifiers (such 3480 as "std140novec4"). The mechanism could be further extended to 3481 include an identifier list if there is ever a need for very fine-grained 3482 control. 3483 3484 There appears to be a strong desire for a global mechanism that doesn't 3485 require individually annotating each and every uniform block. Options 3486 considered include the #pragma described above and a GL API call that 3487 might set a "compiler flag" such as: 3488 3489 glProgramParameteri(program, GL_UNIFORM_BLOCK_LAYOUT, GL_LAYOUT_STD140); 3490 3491 It was noted that the GL API call, since implementations are permitted 3492 to do some or most code generation during glCompileShader(), where a 3493 program parameter would not be available. A similar shader parameter 3494 call could conceivably be provided. 3495 3496 RESOLVED: We've adopted a layout qualifier construct which can be used 3497 to specify the "std140" standard layout either within a uniform block 3498 declaration or at global scope, affecting all subsequently declared 3499 uniform blocks with unspecified layout. 3500 3501 (75) What is the story behind the "std140" packing, and the possible 3502 "std140vec4" alternative? 3503 3504 RESOLVED: The "std140" packing is intended to provide a common 3505 device-independent layout for uniform blocks that can be supported by 3506 all OpenGL 3.1-capable GPUs. Applications using this packing do not 3507 need to query the offsets and strides of all its uniforms and can rely 3508 on the same packing being used on all OpenGL 3.1 implementations. 3509 3510 While some implementations may be able to support a more space-efficient 3511 packing, "std140" does not attempt to provide any features not available 3512 on all platforms. Some of the limitations baked into this packing 3513 include: 3514 3515 * scalars need to be size-aligned; 3516 3517 * vectors are treated as atomic units, and need to be vector-size- 3518 aligned; 3519 3520 * array elements and structures are aligned/padded to 16-byte 3521 boundaries 3522 3523 The array/structure restriction is because some implementations treat 3524 uniform buffers as arrays of four-component vectors and may not be able 3525 to efficiently perform indexed array access with strides less than 16 3526 bytes. 3527 3528 The "std140novec4" alternate packing illustrates an alternate approach 3529 without required 16-byte alignment that might be exposed as a future 3530 vendor extension. 3531 3532 Future versions of OpenGL/GLSL may choose to provide additional sets of 3533 canonical packing rules that may end up being more compact. 3534 3535 (76) When using the standard layout, how is UNIFORM_BLOCK_DATA_SIZE 3536 determined? 3537 3538 RESOLVED: The data size returned by the query is derived by taking the 3539 next free byte after all uniform block members (including any specified 3540 end-of-array or end-of-structure padding) and rounding up to the next 3541 vec4 boundary. It would be equivalent to the offset of a hypothetical 3542 vec4 member added to the end of the uniform block. 3543 3544 There is no implementation-dependent padding of the uniform block data 3545 size when using the standard layout. 3546 3547 3548Revision History 3549 3550 (v68, 2015-06-23, srahman) 3551 - Add GLX protocol specification. 3552 3553 (v67, 2013-08-17, jon) 3554 - Add extra 'const' qualifier for GetUniformIndices <uniformNames> 3555 argument (Bug 10703). 3556 3557 (v66, 2012-09-17, jon) 3558 - Remove _EXT suffix from GL_UNIFORM_BUFFER_EXT in sample code (Bug 3559 7948). 3560 3561 (v65, 2012-06-28, jon) 3562 - Remove INVALID_VALUE error for BindBufferRange when specifying a 3563 range beyond the current end of buffer. Define BindBufferBase as 3564 specifying a range as large as the actual buffer size at time of 3565 use, and return zero when querying the buffer size as a sentinel 3566 value for the buffer size indicating this behavior. Specify that 3567 the GL will never read from or write to beyond the end of a bound 3568 buffer (Bugs 7318 and 7329, matching OpenGL 4.2 core spec 3569 behavior). Remove dangling references to nonexistent 3570 BindBufferOffset. 3571 3572 (v64, 2011-01-27, jon) 3573 - Change return value for start/size queries when no buffer 3574 bound from -1 to zero, to match state tables (Bug 7318). 3575 3576 (v63, 2011-01-21, pbrown) 3577 - Add interaction with ARB_geometry_shader4 to indicate that 3578 MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS is defined there. 3579 3580 (v62, 2009-03-26, jon) 3581 - Remove ARB suffixes for consistency with other extensions 3582 simultaneously introduced with new GL core features, intended 3583 to enable those features in older drivers. 3584 3585 (v61, 2009-02-16, benj) 3586 - pickup latest changes to GLSL language 3587 3588 (v60, 2009-02-12, benj) 3589 - revert the change to silently ignore INVALID_INDEX_ARB within 3590 <uniformIndices> passed to GetActiveUniformsivARB 3591 - picked up a few proposed language changes from Pat 3592 - updated table 2.utype to include types from extensions 3593 - added interactions for these extension types 3594 - fixed issue (40) resolution 3595 3596 (v59, 2009-02-12, benj) 3597 - remove INVALID_OPERATION error when <program> has not been linked, 3598 and instead just behave appropriately for the case where there are 3599 no active uniforms or uniform blocks 3600 - added GL 3.0 interaction regarding description of uniform 3601 initialization, which is limited to uniforms in the default block 3602 3603 (v58, 2009-02-11, jon) 3604 - Add some more comments. 3605 3606 (v57, 2009-02-11, benj) 3607 - restore 80-column width 3608 - change _STAGE to _SHADER in UNIFORM_BLOCK_REFERENCED_BY token names 3609 - silently ignore INVALID_INDEX_ARB in GetActiveUniformsivARB 3610 - clarify that matrices in the default uniform block return 0 for 3611 UNIFORM_IS_ROW_MAJOR 3612 - Replace Draw* with Begin or commands that perform an implicit Begin 3613 since the extension is written against GL 2.1 3614 3615 (v56, 2009-02-11, jon) 3616 - Accept some of Pat's edits and remove associated notes/comments. 3617 Add my comments on some others. 3618 3619 (v55, 2009-02-11, pbrown) 3620 - Many edits attempting to make the spec read more clearly. 3621 - Added a number of notes and issues in the spec for additional edits. 3622 3623 (v54, 2009-02-11, jon) 3624 - Note that uniform binding limits change when geometry 3625 shaders not supported, and update uniform state variable 3626 types. 3627 3628 (v53, 2009-02-09, jon) 3629 - Restore an error accidentally removed from GetUniformLocation 3630 (at least, I think it was accidentaly). 3631 3632 (v52, 2009-02-09, jon) 3633 - Resolve some issues as recommended by Bruce and leave his 3634 comments in for others Benj should look at. 3635 - Allow undefined behavior including termination if no buffer is 3636 bound backing a uniform block. 3637 3638 (v51, 2009-02-08, jon) 3639 - Cleanup before core spec integration: 3640 - Change definition of INVALID_INDEX_ARB to avoid signed/unsigned 3641 conversion questions by making it an unsigned literal (would 3642 like to change the name too, it looks too much like an error). 3643 - Rephrase some query language for greater consistency with core 3644 spec. Duplicated <program> error conditions in each affected 3645 call to avoid more state-dependent reading. 3646 3647 (v50, 2009-02-08, benj) 3648 - resolve last four issues (47), (67), (74), (76) 3649 - update the GLSL changes for uniform blocks 3650 - update API descriptions to refer to packed/shared/std140 layouts 3651 - update the buffer overrun language courtesy of Bruce 3652 - rename APPLE to ARB in the issues list 3653 - misc. other cleanups 3654 3655 (v49, 2009-02-05, benj) 3656 - change UBO overrun language to say "undefined behavior that may lead 3657 to GL interruption or termination" instead of just "undefined values" 3658 - flesh out Errors section 3659 3660 (v48, 2009-02-04, benj) 3661 - add query for whether a matrix uniform is row- or column-major 3662 - add query for the stride between a matrix uniform's major vectors 3663 - apply one description of <program> to all uniform query commands 3664 - update example code 3665 3666 (v47, 2009-02-03, benj) 3667 - update packing rules and examples 3668 - standardize on "named" uniform block instead of "user-defined" 3669 - refactor UBO spec language so it is blended with old uniform language 3670 3671 (v46, 2009-02-03, benj) 3672 - update token MAX token names re: issue (46) 3673 - rename "uniform block unit" to "uniform buffer binding point" 3674 - updated uniform block binding and uniform buffer binding overview 3675 - add queries for uniform buffer start and size re: issue (65) 3676 - resolved issues (46), (65), (69) 3677 - incorporated many more misc. suggestions from Bruce 3678 3679 (v45, 2009-02-02, benj) 3680 - rename from APPLE to ARB 3681 - assigned token values 3682 - misc. suggestions from Bruce, more to come 3683 - pull issues over from Pat's packing doc 3684 - resolved issues (57), (60), (62), (63), (64), (65) 3685 3686 (v44, 2009-01-30, benj) 3687 - resolved issues (20), (29), (42) 3688 - added MAX_COMBINED_{VERTEX|GEOMETRY|FRAGMENT}_UNIFORM_COMPONENTS 3689 queries with different minimum maxima for before and after GL 3.1, 3690 resolving issue (36) 3691 - replaced GetActiveUniformNamesAPPLE with GetActiveUniformNameAPPLE, 3692 resolving issue (43) 3693 - stop reserving uniform block index 0 for the default uniform block, 3694 resolving issue (51) 3695 - remove language saying uniform buffer range size must be aligned to 3696 UNIFORM_BUFFER_OFFSET_ALIGNMENT 3697 - make consistent use of "uniform block unit" instead of "uniform 3698 buffer unit" 3699 3700 (v43, 2009-01-29, benj) 3701 - UNIFORM_BLOCK_NAME_LENGTH changed from 0 to 1 for the default 3702 uniform block, since "" still has a null terminator 3703 - UNIFORM_BLOCK_DATA_SIZE description updated to reflect how 3704 offset/stride queries are unnecessary for "standard" layout 3705 - Add language to GetUniformLocation to say that uniforms in 3706 named uniform blocks return -1, and that Uniform* are for 3707 loading uniforms of the default uniform block 3708 - update discussion of issues (13), (15), (21), (34) to align with 3709 current spec 3710 - sanitize uniform query descriptions (both pre-existing and 3711 new in this extension) to clarify handling of uniforms from 3712 default uniform blocks vs. named uniform blocks, 3713 resolving issue (54) 3714 - rename MAX_UNIFORM_BUFFER_SIZE to MAX_UNIFORM_BLOCK_SIZE per 3715 issue (57) 3716 - introduce language guaranteeing order of member offsets will match 3717 order within declaration per issue (58) 3718 - update some section #s 3719 3720 (v42, 2009-01-28, benj) 3721 - introduce Pat's packing rules, including standard layout, 3722 resolving issues (48), (49) 3723 - add interactions with extensions and GL 3.0, resolving 3724 issue (50) 3725 - change names of MAX query names for uniform block 3726 per-stage, combined, and binding point limits 3727 - introduce BindBufferRange/BindBufferBase in place of 3728 BindUniformBufferAPPLE, resolving issue (55) 3729 - add missing query language in Chapter 6 3730 - add missing UNIFORM_BUFFER_OFFSET_ALIGNMENT_APPLE from 3731 state tables 3732 - separate new state from implementation state in state tables 3733 - remove instance-name language and arrays of uniform blocks per 3734 resolution to issues (59), (61) 3735 - fix minor typos and cosmetic issues 3736 - reformat some lines to fit in 80 columns 3737 - replace tabs with spaces 3738 3739 (v41, 2009-01-25, jsandmel) 3740 - incorporated resolutions/feedback from Portland F2F 3741 - resolved issues (33), (39), (44), (52), (55), (56), (58), (59) 3742 - added issue (61) 3743 3744 (v40, 2009-01-25, jsandmel) 3745 - fixed a few typos noticed by Barthold Lichtenbelt 3746 - fixed up some white space in issues list 3747 3748 (v39, 2009-01-21, jsandmel) 3749 - fixed a few typos noticed by Daniel Koch 3750 - added issue (60) 3751 3752 3753 (v38, 2009-01-21, jsandmel) 3754 - integrated feedback and questions from Bruce Merry 3755 - fixed typo in GetUniformIndices (missing const char**) 3756 - added length (output) parameter to GetActiveUniformBlockNameAPPLE 3757 for symmetry with GetActiveUniform 3758 - removed stale matrix packing queries (to be handled more generally 3759 with rest of packing language) 3760 - fixed wrong error language when validating <program> arguments 3761 to be consistent with generic error language already in 3762 GL spec 3763 - make GetActiveUniformNamesAPPLE not write NULL to names entries 3764 for invalid indices 3765 - made <bufSize> validation the same as GetActiveUniform 3766 - added issues (57), (58), (59) 3767 3768 3769 (v37, 2009-01-19, jsandmel) 3770 - incorporated feedback from Pat Brown 3771 - added issues (47) - (56) 3772 - added note to interactions section 3773 - clarified layouts in overview section 3774 - fixed wrong error code in GetActiveUniformBlockivAPPLE 3775 - added additional description to parameters in 3776 GetActiveUniformNamesAPPLE 3777 - added note to GetActiveUniformsivAPPLE to make it more 3778 similar to GetActiveUniform wrt to program linking and 3779 type/size queries. 3780 - added todo for UniformBlockBindingAPPLE to clarify over better 3781 based on feedback from pat 3782 - increased MAX_UNIFORM_BUFFER_SIZE_APPLE from 64 to 16k 3783 - unresolved issue (33) re: display lists 3784 3785 3786 (v36, 2009-01-14, jsandmel) 3787 - added issue (48) requesting the standard layout and referred 3788 to this in various places 3789 - added missing UNIFORM_BLOCK_NAME_LENGTH_APPLE state variable 3790 - corrected references of GetIndexedIntegerv with GetIntegeri_v 3791 - fixed typo in description of UNIFORM_BLOCK_INDEX_APPLE 3792 - clarified UNIFORM_OFFSET_APPLE description further 3793 - clarified that several constantscan be queried with GetIntegerv 3794 - fixed a set of stale references to "partitions" 3795 3796 (v35, 2009-01-14, jdr) 3797 - improved readability of a few areas 3798 - fixed a data type typo 3799 3800 (v34, 2009-01-12, jsandmel) 3801 - added issue (47) and preliminary keyword support for packed, 3802 sharable, standard layouts 3803 3804 (v33, 2009-01-11, jsandmel) 3805 - switched terminology from "partition" to "uniform block" 3806 - switched syntax from 'active' to 'packed', and changed default 3807 behavior 3808 - changed lots of function names to account for the above 3809 - cleaned up overview 3810 - dropped language talking about "binding" for the uniform block -> 3811 uniform block unit association, since it's not an object binding 3812 operation 3813 - added concept of "combined"/"logical" binding point max queries 3814 - incorporated most recent GLSL syntax from the GLSL working group for 3815 uniform blocks 3816 - removed the AttachUniformBufferAPPLE for per-program bindings of UBOs 3817 3818 (v32, 2008-12-08, jsandmel) 3819 - added UNIFORM_BUFFER_OFFSET_ALIGNMENT_APPLE 3820 3821 (v31, 2008-12-08, jsandmel) 3822 - minor updates to overview (this could still use more editing). 3823 3824 (v30, 2008-12-08, jsandmel) 3825 - cleaned up function argument names for clarity 3826 - reformatted new procedures/tokens section 3827 - added concept of uniformBlockBinding (for context bindings) to 3828 distinguish from uniformBlockIndex 3829 - renamed MAX_VERTEX_UNIFORM_BUFFERS_APPLE -> 3830 MAX_VERTEX_UNIFORM_BUFFERS_APPLE and friends. 3831 - removed/simplified the unneeded per-stage quries for active 3832 partitions (under assumption that partition names are global per 3833 program) 3834 - de-assigned apple enums for most tokens while we work out the enums 3835 - added UNIFORM_BLOCK_REFERENCED_BY_VERTEX_STAGE_APPLE and friends 3836 to queries of each partition 3837 - clarified/cleaned up overview of uniform partitions 3838 - added more detail to each of the function descriptions to clarify 3839 how each of the arguments was to be handled 3840 - temporarily deleted the Errors section since it was partially stale 3841 need to add this back later 3842 - removed stale query for UNIFORM_LOCATION_APPLE from state table 3843 - cleaned up (most of) issues list with API changes 3844 - removed some AMD/NV'isms from the issues language 3845 3846 (v29, 2008-11-24, jsandmel) 3847 - Added <stage> argument to query routines to indicate 3848 vtx/geom/fragment. 3849 - Still need to update sample code for this proposal. 3850 - Also need to still specify how uniform scoping works (cross 3851 stage or per stage). 3852 - Eliminated special "INVALID_INDEX_APPLE" value since the rest 3853 of the GLSL API uses "-1" to mean invalid index, so we use 3854 that here too. 3855 3856 (v28, 2008-10-08, jsandmel) 3857 - Added more discussion to issue (35) regarding context vs. 3858 program bindings of UBOs. 3859 - Added prototypes for BindUniformBuffer API. 3860 - Added issue (36) about maximum uniform component API. 3861 - Integrated the proposed API for per-context bindings into 3862 issue (35) from NVIDIA's NV_ubo proposal. 3863 - Added issue (37) about if we need 3 values for 3864 MAX_{VERTEX|GEOMETRY|FRAGMENT}_UNIFORM_BUFFERS_APPLE. 3865 3866 (2008-10-08, jdr) Grammar additions. Re-instated piece-wise partition 3867 definitions. Elaboration of issue 35. Addition of 36. Readability 3868 improvements. 3869 3870 (2008-10-07, jdr) 18 in previous check-in -> not true. 18 *is* in this 3871 one. Skeltal issue for NV suggested context binding points. 3872 3873 (2008-10-06, jdr) Incorporated Nick's and Matt's changes 2, 3, 4, 5, 3874 6, 8, 12, 14, 16, 17, and 18. 3875 3876 (2008-08-27, jdr) Additions to contributer list. 3877 3878 (2008-07-22, jdr) Changed buffer minimums and contributor list per 3879 discussion with NVidia. 3880 3881 (2008-06-19, jdr) Added issue 34 and language describing the decision 3882 to use struct-like syntax for partition definitions. Added explicit 3883 mention that AttachUniformBufferObjectAPPLE() was required after a 3884 uniform buffer object has been modified. Fixed examples. 3885 3886 (2008-03-18, jdr) Provide resolution and spec language for "active" and 3887 "partition" resolving related issues. Appended "_object" to spec name. 3888 Added required GLSL v1.20.8 spec language. 3889 3890 (2008-03-17, jdr) Removed issue 30 as it was a misread spec. Added 3891 resolutions for 29, 31, and 32 - made spec changes accordingly. Added 3892 proposal for active partition demarcation and sharing rules. 3893 3894 (2008-03-14, jdr) Added issues 29-34 for transform feedback, scoping the 3895 "active" keyword, and following precedents. 3896 3897 (2008-03-13, bb) Fixed incorrect error returns. 3898 3899 (2008-03-13, bb) Changed the return value of GetUniformBlockIndexAPPLE to 3900 uint. Added INVALID_INDEX. Fixed Example code 2. Cleaned up line breaks. 3901 Cleaned up issues. Added issues 24-26. 3902 3903 (2008-03-12, jdr) Added state tables and state retrieval segment. 3904 3905 (2008-03-12, jdr) Rewrote advanced source example. Made a few minor fixes 3906 and additions that writing the example illuminated. 3907 3908 (2008-03-11, jdr) After considerable dialog with BB around handling of bulk 3909 extraction of uniform meta-data, conclusions of dialog required sweeping 3910 changes to spec. Rewrote specification updates section. Added new 3911 tokens. Changed New Functions segment. Updated Errors segment. 3912 Added issue 23. 3913 3914 (2008-03-04, jdr) Rewrote specification updates section. Rewrote error 3915 section. 3916 3917 (2008-03-03, jdr) Rewrote overview to reflect partitioning. Re-arranged 3918 for spec worthiness. Cleaned up new procedures functions and defined 3919 aggregate layout function. Revised issues list to reflect partitioning, 3920 include more recent discussions, and used current accepted vernacular. 3921 3922 (2008-03-03, bb) Resolved issue 19. Changed the return value of 3923 GetActivePartitionUniformInfoAPPLE to a void because it does not return 3924 locations. 3925 3926 (2008-03-03, jdr) Changed to namespace to partitions. Added issues 21 & 3927 22. Added aggregate uniform info query per partition. 3928 3929 (2008-03-03, bb) Added separate partition support. Changed extension name 3930 to APPLE_uniform_buffer. 3931 3932 (2008-02-27, jdr) Dumped program arguments. Changed "types" output array 3933 to "sizes" output array. Added expected scatter/gather logic in the 3934 example to advocate efficient schlepping of uniform data into the buffer. 3935 3936 (2008-02-26, jdr) Changes to accomodate relative offsets. Revised 3937 example source. Error additions. Removed contact information for 3938 contributors list. 3939 3940 (2008-02-25, jdr) Added source example. 3941 3942 (2008-02-21, jdr) Added to issues list, resolutions of all issues 3943 excepting 16. Changes per meeting. Additions to procedures and 3944 explanations. 2.1 spec integration. Implementation Dependent State. 3945 3946 (2008-02-19, jdr) Added to issues list, additions to procedures and 3947 explanations, errors. 3948 3949 (2008-02-18, jdr) Added to issues list, modifications to procedures and 3950 explanations. 3951 3952 (2008-02-16, jdr) Added to issues list and procedures. 3953 3954 (2008-02-15, jdr) Initial revision, overview. 3955