1Name 2 3 ARB_geometry_shader4 4 5Name String 6 7 GL_ARB_geometry_shader4 8 9Contact 10 11 Pat Brown, NVIDIA (pbrown 'at' nvidia.com) 12 Barthold Lichtenbelt, NVIDIA (blichtenbelt 'at' nvidia.com) 13 14Notice 15 16 Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at 17 http://www.khronos.org/registry/speccopyright.html 18 19Specification Update Policy 20 21 Khronos-approved extension specifications are updated in response to 22 issues and bugs prioritized by the Khronos OpenGL Working Group. For 23 extensions which have been promoted to a core Specification, fixes will 24 first appear in the latest version of that core Specification, and will 25 eventually be backported to the extension document. This policy is 26 described in more detail at 27 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 28 29Status 30 31 Approved by the ARB on July 11, 2008 32 33Version 34 35 Last Modified Date: 01/21/2011 36 NVIDIA Revision: 26 37 38Number 39 40 ARB Extension #47 41 42Dependencies 43 44 OpenGL 1.1 is required. 45 46 This extension is written against the OpenGL 2.0 specification. 47 48 EXT_framebuffer_object interacts with this extension. 49 50 EXT_framebuffer_blit interacts with this extension. 51 52 EXT_texture_array interacts with this extension. 53 54 ARB_texture_rectangle trivially affects the definition of this 55 extension. 56 57 ARB_texture_buffer_object trivially affects the definition of this 58 extension. 59 60 NV_primitive_restart trivially affects the definition of this 61 extension. 62 63 This extension interacts with ARB_tranform_feedback. 64 65 This extension interacts with geometry shader support in OpenGL 3.2. 66 67 This extension interacts with ARB_uniform_buffer_object. 68 69Overview 70 71 ARB_geometry_shader4 defines a new shader type available to be run on the 72 GPU, called a geometry shader. Geometry shaders are run after vertices are 73 transformed, but prior to color clamping, flat shading and clipping. 74 75 A geometry shader begins with a single primitive (point, line, 76 triangle). It can read the attributes of any of the vertices in the 77 primitive and use them to generate new primitives. A geometry shader has a 78 fixed output primitive type (point, line strip, or triangle strip) and 79 emits vertices to define a new primitive. A geometry shader can emit 80 multiple disconnected primitives. The primitives emitted by the geometry 81 shader are clipped and then processed like an equivalent OpenGL primitive 82 specified by the application. 83 84 Furthermore, ARB_geometry_shader4 provides four additional primitive 85 types: lines with adjacency, line strips with adjacency, separate 86 triangles with adjacency, and triangle strips with adjacency. Some of the 87 vertices specified in these new primitive types are not part of the 88 ordinary primitives, instead they represent neighboring vertices that are 89 adjacent to the two line segment end points (lines/strips) or the three 90 triangle edges (triangles/tstrips). These vertices can be accessed by 91 geometry shaders and used to match up the vertices emitted by the geometry 92 shader with those of neighboring primitives. 93 94 Since geometry shaders expect a specific input primitive type, an error 95 will occur if the application presents primitives of a different type. 96 For example, if a geometry shader expects points, an error will occur at 97 Begin() time, if a primitive mode of TRIANGLES is specified. 98 99New Procedures and Functions 100 101 void ProgramParameteriARB(uint program, enum pname, int value); 102 void FramebufferTextureARB(enum target, enum attachment, 103 uint texture, int level); 104 void FramebufferTextureLayerARB(enum target, enum attachment, 105 uint texture, int level, int layer); 106 void FramebufferTextureFaceARB(enum target, enum attachment, 107 uint texture, int level, enum face); 108 109New Tokens 110 111 Accepted by the <type> parameter of CreateShader and returned by the 112 <params> parameter of GetShaderiv: 113 114 GEOMETRY_SHADER_ARB 0x8DD9 115 116 Accepted by the <pname> parameter of ProgramParameteriARB and 117 GetProgramiv: 118 119 GEOMETRY_VERTICES_OUT_ARB 0x8DDA 120 GEOMETRY_INPUT_TYPE_ARB 0x8DDB 121 GEOMETRY_OUTPUT_TYPE_ARB 0x8DDC 122 123 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 124 GetFloatv, and GetDoublev: 125 126 MAX_GEOMETRY_TEXTURE_IMAGE_UNITS_ARB 0x8C29 127 MAX_GEOMETRY_VARYING_COMPONENTS_ARB 0x8DDD 128 MAX_VERTEX_VARYING_COMPONENTS_ARB 0x8DDE 129 MAX_VARYING_COMPONENTS 130 MAX_GEOMETRY_UNIFORM_COMPONENTS_ARB 0x8DDF 131 MAX_GEOMETRY_OUTPUT_VERTICES_ARB 0x8DE0 132 MAX_GEOMETRY_TOTAL_OUTPUT_COMPONENTS_ARB 0x8DE1 133 134 Accepted by the <mode> parameter of Begin, DrawArrays, 135 MultiDrawArrays, DrawElements, MultiDrawElements, and 136 DrawRangeElements: 137 138 LINES_ADJACENCY_ARB 0xA 139 LINE_STRIP_ADJACENCY_ARB 0xB 140 TRIANGLES_ADJACENCY_ARB 0xC 141 TRIANGLE_STRIP_ADJACENCY_ARB 0xD 142 143 Returned by CheckFramebufferStatusARB: 144 145 FRAMEBUFFER_INCOMPLETE_LAYER_TARGETS_ARB 0x8DA8 146 FRAMEBUFFER_INCOMPLETE_LAYER_COUNT_ARB 0x8DA9 147 148 Accepted by the <pname> parameter of GetFramebufferAttachment- 149 ParameterivARB: 150 151 FRAMEBUFFER_ATTACHMENT_LAYERED_ARB 0x8DA7 152 FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER 0x8CD4 153 154 Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, 155 and by the <pname> parameter of GetIntegerv, GetFloatv, GetDoublev, 156 and GetBooleanv: 157 158 PROGRAM_POINT_SIZE_ARB 0x8642 159 160 (Note: FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER is simply an alias for the 161 FRAMEBUFFER_ATTACHMENT_TEXTURE_3D_ZOFFSET_ARB token provided in 162 EXT_framebuffer_object. This extension generalizes the notion of 163 "<zoffset>" to include layers of an array texture.) 164 165 (Note: PROGRAM_POINT_SIZE_ARB is simply an alias for the 166 VERTEX_PROGRAM_POINT_SIZE token provided in OpenGL 2.0, which is itself an 167 alias for VERTEX_PROGRAM_POINT_SIZE_ARB provided by 168 ARB_vertex_program. Program-computed point sizes can be enabled if 169 geometry shaders are enabled.) 170 171Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL 172Operation) 173 174 Modify Section 2.6.1 (Begin and End Objects), p. 13 175 176 (Add to end of section, p. 18) 177 178 (add figure on discussions of lines and line strips with adjacency) 179 180 1 - - - 2----->3 - - - 4 1 - - - 2--->3--->4--->5 - - - 6 181 182 5 - - - 6----->7 - - - 8 183 184 (a) (b) 185 186 Figure 2.X1 (a) Lines with adjacency, (b) Line strip with adjacency. 187 The vertices connected with solid lines belong to the main primitives; 188 the vertices connected by dashed lines are the adjacent vertices that 189 may be used in a geometry shader. 190 191 Lines with Adjacency 192 193 Lines with adjacency are independent line segments where each endpoint has 194 a corresponding "adjacent" vertex that can be accessed by a geometry 195 shader (Section 2.16). If a geometry shader is not active, the "adjacent" 196 vertices are ignored. 197 198 A line segment is drawn from the 4i + 2nd vertex to the 4i + 3rd vertex 199 for each i = 0, 1, ... , n-1, where there are 4n+k vertices between the 200 Begin and End. k is either 0, 1, 2, or 3; if k is not zero, the final k 201 vertices are ignored. For line segment i, the 4i + 1st and 4i + 4th 202 vertices are considered adjacent to the 4i + 2nd and 4i + 3rd vertices, 203 respectively. See Figure 2.X1. 204 205 Lines with adjacency are generated by calling Begin with the argument 206 value LINES_ADJACENCY_ARB. 207 208 Line Strips with Adjacency 209 210 Line strips with adjacency are similar to line strips, except that each 211 line segment has a pair of adjacent vertices that can be accessed by a 212 geometry shader (Section 2.15). If a geometry shader is not active, the 213 "adjacent" vertices are ignored. 214 215 A line segment is drawn from the i + 2nd vertex to the i + 3rd vertex for 216 each i = 0, 1, ..., n-1, where there are n+3 vertices between the Begin 217 and End. If there are fewer than four vertices between a Begin and End, 218 all vertices are ignored. For line segment i, the i + 1st and i + 4th 219 vertex are considered adjacent to the i + 2nd and i + 3rd vertices, 220 respectively. See Figure 2.X1. 221 222 Line strips with adjacency are generated by calling Begin with the 223 argument value LINE_STRIP_ADJACENCY_ARB. 224 225 -------------------------------------------------------------------- 226 227 (add figure and discussion of triangles with adjacency) 228 229 2 - - - 3 - - - 4 8 - - - 9 - - - 10 230 ^\ ^\ 231 \ | \ | \ | \ | 232 | \ | \ 233 \ | \ | \ | \ | 234 | \ | \ 235 \ | \ | \ | \ | 236 | v | v 237 1<------5 7<------11 238 239 \ | \ | 240 241 \ | \ | 242 243 \ | \ | 244 245 6 12 246 247 Figure 2.X2 Triangles with adjacency. The vertices connected with solid 248 lines belong to the main primitive; the vertices connected by dashed 249 lines are the adjacent vertices that may be used in a geometry shader. 250 251 Triangles with Adjacency 252 253 Triangles with adjacency are similar to separate triangles, except that 254 each triangle edge has an adjacent vertex that can be accessed by a 255 geometry shader (Section 2.15). If a geometry shader is not active, the 256 "adjacent" vertices are ignored. 257 258 The 6i + 1st, 6i + 3rd, and 6i + 5th vertices (in that order) determine a 259 triangle for each i = 0, 1, ..., n-1, where there are 6n+k vertices 260 between the Begin and End. k is either 0, 1, 2, 3, 4, or 5; if k is 261 non-zero, the final k vertices are ignored. For triangle i, the i + 2nd, 262 i + 4th, and i + 6th vertices are considered adjacent to edges from the i 263 + 1st to the i + 3rd, from the i + 3rd to the i + 5th, and from the i + 264 5th to the i + 1st vertices, respectively. See Figure 2.X2. 265 266 Triangles with adjacency are generated by calling Begin with the argument 267 value TRIANGLES_ADJACENCY_ARB. 268 269 -------------------------------------------------------------------- 270 271 (add figure and discussion of triangle strips with adjacency) 272 273 6 6 274 275 | \ | \ 276 277 | \ | \ 278 279 | \ | \ 280 281 2 - - - 3- - - >6 2 - - - 3------>7 2 - - - 3------>7- - - 10 282 ^\ ^^ | ^^ ^^ | 283 \ | \ | \ | \ | \ \ | \ | \ 284 | \ | \ | | \ | \ | 285 \ | \ | \ | \ | \ \ | \ | \ 286 | \ | \ | | \ | \ | 287 \ | \ | \ | \ | \ \ | \ | \ 288 | v | vv | vv v| 289 1<------5 1<------5 - - - 8 1<------5<------9 290 291 \ | \ | \ | \ | 292 293 \ | \ | \ | \ | 294 295 \ | \ | \ | \ | 296 297 4 4 4 8 298 299 300 6 10 301 302 | \ | \ 303 304 | \ | \ 305 306 | \ | \ 307 2 - - - 3------>7------>11 308 ^^ ^^ | 309 \ | \ | \ | \ 310 | \ | \ | 311 \ | \ | \ | \ 312 | \ | \ | 313 \ | \ | \ | \ 314 | vv vv 315 1<------5<------9 - - - 12 316 317 \ | \ | 318 319 \ | \ | 320 321 \ | \ | 322 323 4 8 324 325 Figure 2.X3 Triangle strips with adjacency. The vertices connected with 326 solid lines belong to the main primitives; the vertices connected by 327 dashed lines are the adjacent vertices that may be used in a geometry 328 shader. 329 330 Triangle Strips with Adjacency 331 332 Triangle strips with adjacency are similar to triangle strips, except that 333 each triangle edge has an adjacent vertex that can be accessed by a 334 geometry shader (Section 2.15). If a geometry shader is not active, the 335 "adjacent" vertices are ignored. 336 337 In triangle strips with adjacency, n triangles are drawn using 2 * (n+2) + 338 k vertices between the Begin and End. k is either 0 or 1; if k is 1, the 339 final vertex is ignored. If fewer than 6 vertices are specified between 340 the Begin and End, the entire primitive is ignored. Table 2.X1 describes 341 the vertices and order used to draw each triangle, and which vertices are 342 considered adjacent to each edge of the triangle. See Figure 2.X3. 343 344 (add table) 345 primitive adjacent 346 vertices vertices 347 primitive 1st 2nd 3rd 1/2 2/3 3/1 348 --------------- ---- ---- ---- ---- ---- ---- 349 only (i==0, n==1) 1 3 5 2 6 4 350 first (i==0) 1 3 5 2 7 4 351 middle (i odd) 2i+3 2i+1 2i+5 2i-1 2i+4 2i+7 352 middle (i even) 2i+1 2i+3 2i+5 2i-1 2i+7 2i+4 353 last (i==n-1, i odd) 2i+3 2i+1 2i+5 2i-1 2i+4 2i+6 354 last (i==n-1, i even) 2i+1 2i+3 2i+5 2i-1 2i+6 2i+4 355 356 Table 2.X1: Triangles generated by triangle strips with adjacency. 357 Each triangle is drawn using the vertices in the "1st", "2nd", and "3rd" 358 columns under "primitive vertices", in that order. The vertices in the 359 "1/2", "2/3", and "3/1" columns under "adjacent vertices" are considered 360 adjacent to the edges from the first to the second, from the second to 361 the third, and from the third to the first vertex of the triangle, 362 respectively. The six rows correspond to the six cases: the first and 363 only triangle (i=0, n=1), the first triangle of several (i=0, n>0), 364 "odd" middle triangles (i=1,3,5...), "even" middle triangles 365 (i=2,4,6,...), and special cases for the last triangle inside the 366 Begin/End, when i is either even or odd. For the purposes of this 367 table, the first vertex specified after Begin is numbered "1" and the 368 first triangle is numbered "0". 369 370 Triangle strips with adjacency are generated by calling Begin with the 371 argument value TRIANGLE_STRIP_ADJACENCY_ARB. 372 373 Modify Section 2.14.1, Lighting (p. 59) 374 375 (modify fourth paragraph, p. 63) Additionally, vertex and geometry shaders 376 can operate in two-sided color mode, which is enabled and disabled by 377 calling Enable or Disable with the symbolic value VERTEX_PROGRAM_TWO_SIDE. 378 When a vertex or geometry shader is active, the shaders can write front 379 and back color values to the gl_FrontColor, gl_BackColor, 380 gl_FrontSecondaryColor and gl_BackSecondaryColor outputs. When a vertex or 381 geometry shader is active and two-sided color mode is enabled, the GL 382 chooses between front and back colors, as described below. If two-sided 383 color mode is disabled, the front color output is always selected. 384 385 Modify Section 2.15.2 Program Objects, p. 73 386 387 Change the first paragraph on p. 74 as follows: 388 389 Program objects are empty when they are created. Default values for 390 program object parameters are discussed in section 2.15.5, Required 391 State. A non-zero name that can be used to reference the program object is 392 returned. 393 394 Change the language below the LinkProgram command on p. 74 as follows: 395 396 ... Linking can fail for a variety of reasons as specified in the OpenGL 397 Shading Language Specification. Linking will also fail if one or more of 398 the shader objects, attached to <program> are not compiled successfully, 399 or if more active uniform or active sampler variables are used in 400 <program> than allowed (see sections 2.15.3 and 2.16.3). Linking will also 401 fail if the program object contains objects to form a geometry shader (see 402 section 2.16), but no objects to form a vertex shader or if the program 403 object contains objects to form a geometry shader, and the value of 404 GEOMETRY_VERTICES_OUT_ARB is zero. If LinkProgram failed, .. 405 406 Add the following paragraphs above the description of 407 DeleteProgram, p. 75: 408 409 To set a program object parameter, call 410 411 void ProgramParameteriARB(uint program, enum pname, int value) 412 413 <param> identifies which parameter to set for <program>. <value> holds the 414 value being set. Legal values for <param> and <value> are discussed in 415 section 2.16. 416 417 Modify Section 2.15.3, Shader Variables, p. 75 418 419 Modify the first paragraph of section 'Varying Variables' p. 83 as 420 follows: 421 422 A vertex shader may define one or more varying variables (see the OpenGL 423 Shading Language specification). Varying variables are outputs of a vertex 424 shader. They are either used as the mechanism to communicate values to a 425 geometry shader, if one is active, or to communicate values to the 426 fragment shader. The OpenGL Shading Language specification also defines a 427 set of built-in varying variables that vertex shaders can write to (see 428 section 7.6 of the OpenGL Shading Language Specification). These variables 429 can also be used to communicate values to a geometry shader, if one is 430 active, or to communicate values to the fragment shader and to the fixed- 431 function processing that occurs after vertex shading. 432 433 If a geometry shader is not active, the values of all varying variables, 434 including built-in variables, are expected to be interpolated across the 435 primitive being rendered, unless flat shaded. The number of interpolators 436 available for processing varying variables is given by the 437 implementation-dependent constant MAX_VARYING_COMPONENTS. This value 438 represents the number of individual components that can be interpolated; 439 varying variables declared as vectors, matrices, and arrays will all 440 consume multiple interpolators. When a program is linked, all components 441 of any varying variable written by a vertex shader, or read by a fragment 442 shader, will count against this limit. The transformed vertex position 443 (gl_Position) does not count against this limit. A program whose vertex 444 and/or fragment shaders access more than MAX_VARYING_COMPONENTS 445 components worth of varying variables may fail to link, unless 446 device-dependent optimizations are able to make the program fit within 447 available hardware resources. 448 449 Note that the two values MAX_VARYING_FLOATS and MAX_VARYING_COMPONENTS 450 are aliases of each other. The use of MAX_VARYING_FLOATS however is 451 discouraged; varying variables can be declared as integers as well. 452 453 If a geometry shader is active, the values of varying variables are 454 collected by the primitive assembly stage and passed on to the geometry 455 shader once enough data for one primitive has been collected (see also 456 section 2.16). The OpenGL Shading Language specification also defines a 457 set of built-in varying and built-in special variables that vertex shaders 458 can write to (see sections 7.1 and 7.6 of the OpenGL Shading Language 459 Specification). These variables are also collected and passed on to the 460 geometry shader once enough data has been collected. The number of 461 components of varying and special variables that can be collected per 462 vertex by the primitive assembly stage is given by the implementation 463 dependent constant MAX_VERTEX_VARYING_COMPONENTS_ARB. This value 464 represents the number of individual components that can be collected; 465 varying variables declared as vectors, matrices, and arrays will all 466 consume multiple components. When a program is linked, all components of 467 any varying variable written by a vertex shader, or read by a geometry 468 shader, will count against this limit. A program whose vertex and/or 469 geometry shaders access more than MAX_VERTEX_VARYING_COMPONENTS_ARB 470 components worth of varying variables may fail to link, unless 471 device-dependent optimizations are able to make the program fit within 472 available hardware resources. 473 474 Modify Section 2.15.4 Shader Execution, p. 84 475 476 Change the following sentence: 477 478 "The following operations are applied to vertex values that are the result 479 of executing the vertex shader:" 480 481 As follows: 482 483 If no geometry shader (see section 2.16) is present in the program object, 484 the following operations are applied to vertex values that are the result 485 of executing the vertex shader: 486 487 [bulleted list of operations] 488 489 On page 85, below the list of bullets, add the following: 490 491 If a geometry shader is present in the program object, geometry shading 492 (section 2.16) is applied to vertex values that are the result of 493 executing the vertex shader. 494 495 Modify the first paragraph of the section 'Texture Access', p. 85, 496 as follows: 497 498 Vertex shaders have the ability to do a lookup into a texture map, if 499 supported by the GL implementation. The maximum number of texture image 500 units available to a vertex shader is MAX_VERTEX_TEXTURE_IMAGE_UNITS; a 501 maximum number of zero indicates that the GL implementation does not 502 support texture accesses in vertex shaders. The vertex shader, geometry 503 shader, if exists, and fragment processing combined cannot use more than 504 MAX_COMBINED_TEXTURE_IMAGE_UNITS texture image units. If the vertex 505 shader, geometry shader and the fragment processing stage access the same 506 texture image unit, then that counts as using three texture image units 507 against the MAX_COMBINED_TEXTURE_IMAGE_UNITS limit. 508 509 Modify Section 2.15.5, Required State, p. 88 510 511 Add the following bullets to the state required per program object: 512 513 * One integer to store the value of GEOMETRY_VERTICES_OUT_ARB, initially 514 zero. 515 516 * One integer to store the value of GEOMETRY_INPUT_TYPE_ARB, initially 517 set to TRIANGLES. 518 519 * One integer to store the value of GEOMETRY_OUTPUT_TYPE_ARB, initially 520 set to TRIANGLE_STRIP. 521 522 Insert New Section 2.16, Geometry Shaders after p. 89 523 524 After vertices are processed, they are arranged into primitives, as 525 described in section 2.6.1 (Begin/End Objects). This section described a 526 new pipeline stage that processes those primitives. A geometry shader 527 defines the operations that are performed in this new pipeline stage. A 528 geometry shader is an array of strings containing source code. The source 529 code language used is described in the OpenGL Shading Language 530 specification. A geometry shader operates on a single primitive at a time 531 and emits one or more output primitives, all of the same type, which are 532 then processed like an equivalent OpenGL primitive specified by the 533 application. The original primitive is discarded after the geometry 534 shader completes. The inputs available to a geometry shader are the 535 transformed attributes of all the vertices that belong to the primitive. 536 Additional "adjacency" primitives are available which also make the 537 transformed attributes of neighboring vertices available to the shader. 538 The results of the shader are a new set of transformed vertices, arranged 539 into primitives by the shader. 540 541 This new geometry shader pipeline stage is inserted after primitive 542 assembly, right before color clamping (section 2.14.6), flat shading 543 (section 2.14.7) and clipping (sections 2.12 and 2.14.8). 544 545 A geometry shader only applies when the GL is in RGB mode. Its operation 546 in color index mode is undefined. 547 548 Geometry shaders are created as described in section 2.15.1 using a type 549 parameter of GEOMETRY_SHADER_ARB. They are attached to and used in program 550 objects as described in section 2.15.2. When the program object currently 551 in use includes a geometry shader, its geometry shader is considered 552 active, and is used to process primitives. If the program object has no 553 geometry shader, or no program object is in use, this new primitive 554 processing pipeline stage is bypassed. 555 556 A program object that includes a geometry shader must also include a 557 vertex shader; otherwise a link error will occur. 558 559 Section 2.16.1, Geometry shader Input Primitives 560 561 A geometry shader can operate on one of five input primitive types. 562 Depending on the input primitive type, one to six input vertices are 563 available when the shader is executed. Each input primitive type supports 564 a subset of the primitives provided by the GL. If a geometry shader is 565 active, Begin, or any function that implicitly calls Begin, will produce 566 an INVALID_OPERATION error if the <mode> parameter is incompatible with 567 the input primitive type of the currently active program object, as 568 discussed below. 569 570 The input primitive type is a parameter of the program object, and must be 571 set before linking by calling ProgramParameteriARB with <pname> set to 572 GEOMETRY_INPUT_TYPE_ARB and <value> set to one of POINTS, LINES, 573 LINES_ADJACENCY_ARB, TRIANGLES or TRIANGLES_ADJACENCY_ARB. This setting 574 will not be in effect until the next time LinkProgram has been called 575 successfully. Note that queries of GEOMETRY_INPUT_TYPE_ARB will return the 576 last value set. This is not necessarily the value used to generate the 577 executable code in the program object. After a program object has been 578 created it will have a default value for GEOMETRY_INPUT_TYPE_ARB, as 579 discussed in section 2.15.5, Required State. 580 581 Note that a geometry shader that accesses more input vertices than are 582 available for a given input primitive type can be successfully compiled, 583 because the input primitive type is not part of the shader 584 object. However, a program object, containing a shader object that access 585 more input vertices than are available for the input primitive type of the 586 program object, will not link. 587 588 The supported input primitive types are: 589 590 Points (POINTS) 591 592 Geometry shaders that operate on points are valid only for the POINTS 593 primitive type. There is only a single vertex available for each geometry 594 shader invocation. 595 596 Lines (LINES) 597 598 Geometry shaders that operate on line segments are valid only for the 599 LINES, LINE_STRIP, and LINE_LOOP primitive types. There are two vertices 600 available for each geometry shader invocation. The first vertex refers to 601 the vertex at the beginning of the line segment and the second vertex 602 refers to the vertex at the end of the line segment. See also section 603 2.16.4. 604 605 Lines with Adjacency (LINES_ADJACENCY_ARB) 606 607 Geometry shaders that operate on line segments with adjacent vertices are 608 valid only for the LINES_ADJACENCY_ARB and LINE_STRIP_ADJACENCY_ARB 609 primitive types. There are four vertices available for each program 610 invocation. The second vertex refers to attributes of the vertex at the 611 beginning of the line segment and the third vertex refers to the vertex at 612 the end of the line segment. The first and fourth vertices refer to the 613 vertices adjacent to the beginning and end of the line segment, 614 respectively. 615 616 Triangles (TRIANGLES) 617 618 Geometry shaders that operate on triangles are valid for the TRIANGLES, 619 TRIANGLE_STRIP and TRIANGLE_FAN primitive types. 620 621 There are three vertices available for each program invocation. The first, 622 second and third vertices refer to attributes of the first, second and 623 third vertex of the triangle, respectively. 624 625 Triangles with Adjacency (TRIANGLES_ADJACENCY_ARB) 626 627 Geometry shaders that operate on triangles with adjacent vertices are 628 valid for the TRIANGLES_ADJACENCY_ARB and TRIANGLE_STRIP_ADJACENCY_ARB 629 primitive types. There are six vertices available for each program 630 invocation. The first, third and fifth vertices refer to attributes of the 631 first, second and third vertex of the triangle, respectively. The second, 632 fourth and sixth vertices refer to attributes of the vertices adjacent to 633 the edges from the first to the second vertex, from the second to the 634 third vertex, and from the third to the first vertex, respectively. 635 636 Section 2.16.2, Geometry Shader Output Primitives 637 638 A geometry shader can generate primitives of one of three types. The 639 supported output primitive types are points (POINTS), line strips 640 (LINE_STRIP), and triangle strips (TRIANGLE_STRIP). The vertices output 641 by the geometry shader are decomposed into points, lines, or triangles 642 based on the output primitive type in the manner described in section 643 2.6.1. The resulting primitives are then further processed as shown in 644 figure 2.16.xxx. If the number of vertices emitted by the geometry shader 645 is not sufficient to produce a single primitive, nothing is drawn. 646 647 The output primitive type is a parameter of the program object, and can be 648 set by calling ProgramParameteriARB with <pname> set to 649 GEOMETRY_OUTPUT_TYPE_ARB and <value> set to one of POINTS, LINE_STRIP or 650 TRIANGLE_STRIP. This setting will not be in effect until the next time 651 LinkProgram has been called successfully. Note that queries of 652 GEOMETRY_OUTPUT_TYPE_ARB will return the last value set; which is not 653 necessarily the value used to generate the executable code in the program 654 object. After a program object has been created it will have a default 655 value for GEOMETRY_OUTPUT_TYPE_ARB, as discussed in section 2.15.5, 656 Required State. . 657 658 Section 2.16.3 Geometry Shader Variables 659 660 Geometry shaders can access uniforms belonging to the current program 661 object. The amount of storage available for uniform variables in the 662 default uniform block accessed by a geometry shader is specified by the 663 value of the implementation-dependent constant 664 MAX_GEOMETRY_UNIFORM_COMPONENTS_ARB. The total amount of combined storage 665 available for uniform variables in all uniform blocks accessed by a 666 geometry shader (including the default uniform block) is specified by the 667 value of the implementation-dependent constant 668 MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS. These values represent the 669 numbers of individual floating-point, integer, or boolean values that can 670 be held in uniform variable storage for a geometry shader. A link error is 671 generated if an attempt is made to utilize more than the space available 672 for geometry shader uniform variables. Uniforms are manipulated as 673 described in section 2.15.3. Geometry shaders also have access to 674 samplers, to perform texturing operations, as described in sections 2.15.3 675 and 3.8. 676 677 Geometry shaders can access the transformed attributes of all vertices for 678 its input primitive type through input varying variables. A vertex shader, 679 writing to output varying variables, generates the values of these input 680 varying variables. This includes values for built-in as well as 681 user-defined varying variables. Values for any varying variables that are 682 not written by a vertex shader are undefined. Additionally, a geometry 683 shader has access to a built-in variable that holds the ID of the current 684 primitive. This ID is generated by the primitive assembly stage that sits 685 in between the vertex and geometry shader. 686 687 Additionally, geometry shaders can write to one, or more, varying 688 variables for each primitive it outputs. These values are optionally flat 689 shaded (using the OpenGL Shading Language varying qualifier "flat") and 690 clipped, then the clipped values interpolated across the primitive (if not 691 flat shaded). The results of these interpolations are available to a 692 fragment shader, if one is active. Furthermore, geometry shaders can write 693 to a set of built- in varying variables, defined in the OpenGL Shading 694 Language, that correspond to the values required for the fixed-function 695 processing that occurs after geometry processing. 696 697 Section 2.16.4, Geometry Shader Execution Environment 698 699 If a successfully linked program object that contains a geometry shader is 700 made current by calling UseProgram, the executable version of the geometry 701 shader is used to process primitives resulting from the primitive assembly 702 stage. 703 704 The following operations are applied to the primitives that are the result 705 of executing a geometry shader: 706 707 * color clamping or masking (section 2.14.6), 708 709 * flat shading (section 2.14.7), 710 711 * clipping, including client-defined clip planes (section 2.12), 712 713 * front face determination (section 2.14.1), 714 715 * color and associated data clipping (section 2.14.8), 716 717 * perspective division on clip coordinates (section 2.11), 718 719 * final color processing (section 2.14.9), and 720 721 * viewport transformation, including depth-range scaling (section 722 2.11.1). 723 724 There are several special considerations for geometry shader execution 725 described in the following sections. 726 727 Texture Access 728 729 Geometry shaders have the ability to do a lookup into a texture map, if 730 supported by the GL implementation. The maximum number of texture image 731 units available to a geometry shader is 732 MAX_GEOMETRY_TEXTURE_IMAGE_UNITS_ARB; a maximum number of zero indicates 733 that the GL implementation does not support texture accesses in geometry 734 shaders. 735 736 The vertex shader, geometry shader and fragment processing combined cannot 737 use more than MAX_COMBINED_TEXTURE_IMAGE_UNITS texture image units. If the 738 vertex shader, geometry shader and the fragment processing stage access 739 the same texture image unit, then that counts as using three texture image 740 units against the MAX_COMBINED_TEXTURE_IMAGE_UNITS limit. 741 742 When a texture lookup is performed in a geometry shader, the filtered 743 texture value tau is computed in the manner described in sections 3.8.8 744 and 3.8.9, and converted to a texture source color Cs according to table 745 3.21 (section 3.8.13). A four component vector (Rs,Gs,Bs,As) is returned 746 to the geometry shader. In a geometry shader it is not possible to perform 747 automatic level-of- detail calculations using partial derivatives of the 748 texture coordinates with respect to window coordinates as described in 749 section 3.8.8. Hence, there is no automatic selection of an image array 750 level. Minification or magnification of a texture map is controlled by a 751 level-of-detail value optionally passed as an argument in the texture 752 lookup functions. If the texture lookup function supplies an explicit 753 level-of-detail value lambda, then the pre-bias level-of-detail value 754 LAMBDAbase(x, y) = lambda (replacing equation 3.18). If the texture lookup 755 function does not supply an explicit level-of-detail value, then 756 LAMBDAbase(x, y) = 0. The scale factor Rho(x, y) and its approximation 757 function f(x, y) (see equation 3.21) are ignored. 758 759 Texture lookups involving textures with depth component data can either 760 return the depth data directly or return the results of a comparison with 761 the R value (see section 3.8.14) used to perform the lookup. The 762 comparison operation is requested in the shader by using any of the shadow 763 sampler and in the texture using the TEXTURE COMPARE MODE parameter. These 764 requests must be consistent; the results of a texture lookup are undefined 765 if: 766 767 * the sampler used in a texture lookup function is not one of the shadow 768 sampler types, and the texture object's internal format is DEPTH 769 COMPONENT, and the TEXTURE COMPARE MODE is not NONE; 770 771 * the sampler used in a texture lookup function is one of the shadow 772 sampler types, and the texture object's internal format is DEPTH 773 COMPONENT, and the TEXTURE COMPARE MODE is NONE; or 774 775 * the sampler used in a texture lookup function is one of the shadow 776 sampler types, and the texture object's internal format is not DEPTH 777 COMPONENT. 778 779 If a geometry shader uses a sampler where the associated texture object is 780 not complete as defined in section 3.8.10, the texture image unit will 781 return (R,G,B,A) = (0, 0, 0, 1). 782 783 Geometry Shader Inputs 784 785 The OpenGL Shading Language specification describes the set of built-in 786 variables that are available as inputs to the geometry shader. This set 787 receives the values from the equivalent built-in output variables written 788 by the vertex shader. These built-in variables are arrays; each element in 789 the array holds the value for a specific vertex of the input 790 primitive. The length of each array depends on the value of the input 791 primitive type, as determined by the program object value 792 GEOMETRY_INPUT_TYPE_ARB, and is set by the GL during link. Each built-in 793 variable is a one-dimensional array, except for the built-in texture 794 coordinate variable, which is a two- dimensional array. The vertex shader 795 built-in output gl_TexCoord[] is a one-dimensional array. Therefore, the 796 geometry shader equivalent input variable gl_TexCoordIn[][] becomes a two- 797 dimensional array. See the OpenGL Shading Language Specification, sections 798 4.3.6 and 7.6 for more information. 799 800 The built-in varying variables gl_FrontColorIn[], gl_BackColorIn[], 801 gl_FrontSecondaryColorIn[] and gl_BackSecondaryColorIn[] hold the 802 per-vertex front and back colors of the primary and secondary colors, as 803 written by the vertex shader to its equivalent built-in output variables. 804 805 The built-in varying variable gl_TexCoordIn[][] holds the per- vertex 806 values of the array of texture coordinates, as written by the vertex 807 shader to its built-in output array gl_TexCoord[]. 808 809 The built-in varying variable gl_FogFragCoordIn[] holds the per- vertex 810 fog coordinate, as written by the vertex shader to its built- in output 811 variable gl_FogFragCoord. 812 813 The built-in varying variable gl_PositionIn[] holds the per-vertex 814 position, as written by the vertex shader to its output variable 815 gl_Position. Note that writing to gl_Position from either the vertex or 816 fragment shader is optional. See also section 7.1 "Vertex and Geometry 817 Shader Special Variables" of the OpenGL Shading Language specification. 818 819 The built-in varying variable gl_ClipVertexIn[] holds the per-vertex 820 position in clip coordinates, as written by the vertex shader to its 821 output variable gl_ClipVertex. 822 823 The built-in varying variable gl_PointSizeIn[] holds the per-vertex point 824 size written by the vertex shader to its built-in output varying variable 825 gl_PointSize. If the vertex shader does not write gl_PointSize, the value 826 of gl_PointSizeIn[] is undefined, regardless of the value of the enable 827 VERTEX_PROGRAM_POINT_SIZE. 828 829 The built-in special variable gl_PrimitiveIDIn is not an array and has no 830 vertex shader equivalent. It is filled with the number of primitives 831 processed since the last time Begin was called (directly or indirectly via 832 vertex array functions). The first primitive generated after a Begin is 833 numbered zero, and the primitive ID counter is incremented after every 834 individual point, line, or triangle primitive is processed. For triangles 835 drawn in point or line mode, the primitive ID counter is incremented only 836 once, even though multiple points or lines may be drawn. Restarting a 837 primitive topology using the primitive restart index has no effect on the 838 primitive ID counter. 839 840 Similarly to the built-in varying variables, user-defined input varying 841 variables need to be declared as arrays. Declaring a size is optional. If 842 no size is specified, it will be inferred by the linker from the input 843 primitive type. If a size is specified, it has to be of the size matching 844 the number of vertices of the input primitive type, otherwise a link error 845 will occur. The built-in variable gl_VerticesIn, if so desired, can be 846 used to size the array correctly for each input primitive 847 type. User-defined varying variables can be declared as arrays in the 848 vertex shader. This means that those, on input to the geometry shader, 849 must be declared as two-dimensional arrays. See sections 4.3.6 and 7.6 of 850 the OpenGL Shading Language Specification for more information. 851 852 Using any of the built-in or user-defined input varying variables can 853 count against the limit MAX_VERTEX_VARYING_COMPONENTS_ARB as discussed in 854 section 2.15.3. 855 856 Geometry Shader outputs 857 858 A geometry shader is limited in the number of vertices it may emit per 859 invocation. The maximum number of vertices a geometry shader can possibly 860 emit needs to be set as a parameter of the program object that contains 861 the geometry shader. To do so, call ProgramParameteriARB with <pname> set 862 to GEOMETRY_VERTICES_OUT_ARB and <value> set to the maximum number of 863 vertices the geometry shader will emit in one invocation. This setting 864 will not be guaranteed to be in effect until the next time LinkProgram has 865 been called successfully. If a geometry shader, in one invocation, emits 866 more vertices than the value GEOMETRY_VERTICES_OUT_ARB, these emits may 867 have no effect. 868 869 There are two implementation-dependent limits on the value of 870 GEOMETRY_VERTICES_OUT_ARB. First, the error INVALID_VALUE will be 871 generated by ProgramParameteriARB if the number of vertices specified 872 exceeds the value of MAX_GEOMETRY_OUTPUT_VERTICES_ARB. Second, the 873 product of the total number of vertices and the sum of all components of 874 all active varying variables may not exceed the value of 875 MAX_GEOMETRY_TOTAL_OUTPUT_COMPONENTS_ARB. LinkProgram will fail if it 876 determines that the total component limit would be violated. 877 878 A geometry shader can write to built-in as well as user-defined varying 879 variables. These values are expected to be interpolated across the 880 primitive it outputs, unless they are specified to be flat shaded. In 881 order to seamlessly be able to insert or remove a geometry shader from a 882 program object, the rules, names and types of the output built-in varying 883 variables and user-defined varying variables are the same as for the 884 vertex shader. Refer to section 2.15.3 and the OpenGL Shading Language 885 specification sections 4.3.6, 7.1 and 7.6 for more detail. 886 887 The built-in output variables gl_FrontColor, gl_BackColor, 888 gl_FrontSecondaryColor, and gl_BackSecondaryColor hold the front and back 889 colors for the primary and secondary colors for the current vertex. 890 891 The built-in output variable gl_TexCoord[] is an array and holds the set 892 of texture coordinates for the current vertex. 893 894 The built-in output variable gl_FogFragCoord is used as the "c" value, as 895 described in section 3.10 "Fog" of the OpenGL 2.0 specification. 896 897 The built-in special variable gl_Position is intended to hold the 898 homogeneous vertex position. Writing gl_Position is optional. 899 900 The built-in special variable gl_ClipVertex holds the vertex coordinate 901 used in the clipping stage, as described in section 2.12 "Clipping" of the 902 OpenGL 2.0 specification. 903 904 The built-in special variable gl_PointSize, if written, holds the size of 905 the point to be rasterized, measured in pixels. 906 907 Additionally, a geometry shader can write to the built-in special 908 variables gl_PrimitiveID and gl_Layer, whereas a vertex shader cannot. The 909 built-in gl_PrimitiveID provides a single integer that serves as a 910 primitive identifier. This written primitive ID is available to fragment 911 shaders. If a fragment shader using primitive IDs is active and a 912 geometry shader is also active, the geometry shader must write to 913 gl_PrimitiveID or the primitive ID number is undefined. The built-in 914 variable gl_Layer is used in layered rendering, and discussed in the next 915 section. 916 917 The number of components available for varying variables is given by the 918 implementation-dependent constant 919 MAX_GEOMETRY_VARYING_COMPONENTS_ARB. This value represents the number of 920 individual components of a varying variable; varying variables declared as 921 vectors, matrices, and arrays will all consume multiple components. When a 922 program is linked, all components of any varying variable written by a 923 geometry shader, or read by a fragment shader, will count against this 924 limit. The transformed vertex position (gl_Position) does not count 925 against this limit. A program whose geometry and/or fragment shaders 926 access more than MAX_GEOMETRY_VARYING_COMPONENTS_ARB worth of varying 927 variable components may fail to link, unless device-dependent 928 optimizations are able to make the program fit within available hardware 929 resources. 930 931 Layered rendering 932 933 Geometry shaders can be used to render to one of several different layers 934 of cube map textures, three-dimensional textures, plus one- dimensional 935 and two-dimensional texture arrays. This functionality allows an 936 application to bind an entire "complex" texture to a framebuffer object, 937 and render primitives to arbitrary layers computed at run time. For 938 example, this mechanism can be used to project and render a scene onto all 939 six faces of a cubemap texture in one pass. The layer to render to is 940 specified by writing to the built-in output variable gl_layer. Layered 941 rendering requires the use of framebuffer objects. Refer to the section 942 'Dependencies on EXT_framebuffer_object' for details. 943 944Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 945 946 Modify Section 3.3, Points (p. 95) 947 948 (replace all Section 3.3 text on p. 95) 949 950 A point is drawn by generating a set of fragments in the shape of a square 951 or circle centered around the vertex of the point. Each vertex has an 952 associated point size that controls the size of that square or circle. 953 954 If no vertex or geometry shader is active, the size of the point is 955 controlled by 956 957 void PointSize(float size); 958 959 <size> specifies the requested size of a point. The default value is 960 1.0. A value less than or equal to zero results in the error 961 INVALID_VALUE. 962 963 The requested point size is multiplied with a distance attenuation factor, 964 clamped to a specified point size range, and further clamped to the 965 implementation-dependent point size range to produce the derived point 966 size: 967 968 derived size = clamp(size * sqrt(1/(a+b*d+c*d^2))) 969 970 where d is the eye-coordinate distance from the eye, (0,0,0,1) in eye 971 coordinates, to the vertex, and a, b, and c are distance attenuation 972 function coefficients. 973 974 If a vertex or geometry shader is active, the derived size depends on the 975 per-vertex point size mode enable. Per-vertex point size mode is enabled 976 or disabled by calling Enable or Disable with the symbolic value 977 PROGRAM_POINT_SIZE_ARB. If per-vertex point size is enabled and a 978 geometry shader is active, the derived point size is taken from the 979 (potentially clipped) point size variable gl_PointSize written by the 980 geometry shader. If per-vertex point size is enabled and no geometry 981 shader is active, the derived point size is taken from the (potentially 982 clipped) point size variable gl_PointSize written by the vertex shader. If 983 per-vertex point size is disabled and a geometry and/or vertex shader is 984 active, the derived point size is taken from the <size> value provided to 985 PointSize, with no distance attenuation applied. In all cases, the 986 derived point size is clamped to the implementation-dependent point size 987 range. 988 989 If multisampling is not enabled, the derived size is passed on to 990 rasterization as the point width. ... 991 992 Modify section 3.10 "Fog", p. 191 993 994 Modify the third paragraph of this section as follows. 995 996 If a vertex or geometry shader is active, or if the fog source, as defined 997 below, is FOG_COORD, then c is the interpolated value of the fog 998 coordinate for this fragment. Otherwise, ... 999 1000Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 1001Operations and the Frame Buffer) 1002 1003 None. 1004 1005Additions to Chapter 5 of the OpenGL 2.0 Specification (Special 1006Functions) 1007 1008 Change section 5.4 Display Lists, p. 237 1009 1010 Add the command ProgramParameteriARB to the list of commands that are not 1011 compiled into a display list, but executed immediately, under "Program and 1012 Shader Objects", p. 241 1013 1014Additions to Chapter 6 of the OpenGL 2.0 Specification (State and State 1015Requests) 1016 1017 Modify section 6.1.14, Shader and Program Objects, p. 256 1018 1019 Add to the second paragraph on p. 257: 1020 1021 ... if <shader> is a fragment shader object, and GEOMETRY_SHADER_ARB is 1022 returned if <shader> is a geometry shader object. 1023 1024 Add to the end of the description of GetProgramiv, p. 257: 1025 1026 If <pname> is GEOMETRY_VERTICES_OUT_ARB, the current value of the maximum 1027 number of vertices the geometry shader will output is returned. If <pname> 1028 is GEOMETRY_INPUT_TYPE_ARB, the current geometry shader input type is 1029 returned and can be one of POINTS, LINES, LINES_ADJACENCY_ARB, TRIANGLES 1030 or TRIANGLES_ADJACENCY_ARB. If <pname> is GEOMETRY_OUTPUT_TYPE_ARB, the 1031 current geometry shader output type is returned and can be one of POINTS, 1032 LINE_STRIP or TRIANGLE_STRIP. 1033 1034Additions to Appendix A of the OpenGL 2.0 Specification (Invariance) 1035 1036 None. 1037 1038Additions to the AGL/GLX/WGL Specifications 1039 1040 None. 1041 1042Dependencies on NV_primitive_restart 1043 1044 The spec describes the behavior that primitive restart does not affect the 1045 primitive ID counter gl_PrimitiveIDIn. If NV_primitive_restart is not 1046 supported, references to that extension in the discussion of the primitive 1047 ID should be removed. 1048 1049Dependencies on EXT_framebuffer_object 1050 1051 If EXT_framebuffer_object (or similar functionality) is not supported, the 1052 gl_Layer output has no effect. "FramebufferTextureARB" and 1053 "FramebufferTextureLayerARB" should be removed from "New Procedures and 1054 Functions", and FRAMEBUFFER_ATTACHMENT_LAYERED_ARB, 1055 FRAMEBUFFER_INCOMPLETE_LAYER_TARGETS_ARB, and 1056 FRAMEBUFFER_INCOMPLETE_LAYER_COUNT_ARB should be removed from "New 1057 Tokens". 1058 1059 Otherwise, this extension modifies EXT_framebuffer_object to add the 1060 notion of layered framebuffer attachments and framebuffers that can be 1061 used in conjunction with geometry shaders to allow programs to direct 1062 primitives to a face of a cube map or layer of a three-dimensional texture 1063 or one- or two-dimensional array texture. The layer used for rendering 1064 can be selected by the geometry shader at run time. 1065 1066 (insert before the end of Section 4.4.2, Attaching Images to Framebuffer 1067 Objects) 1068 1069 There are several types of framebuffer-attachable images: 1070 1071 * the image of a renderbuffer object, which is always two-dimensional, 1072 1073 * a single level of a one-dimensional texture, which is treated as a 1074 two-dimensional image with a height of one, 1075 1076 * a single level of a two-dimensional or rectangle texture, 1077 1078 * a single face of a cube map texture level, which is treated as a 1079 two-dimensional image, or 1080 1081 * a single layer of a one- or two-dimensional array texture or 1082 three-dimensional texture, which is treated as a two-dimensional 1083 image. 1084 1085 Additionally, an entire level of a three-dimensional texture, cube map 1086 texture, or one- or two-dimensional array texture can be attached to an 1087 attachment point. Such attachments are treated as an array of 1088 two-dimensional images, arranged in layers, and the corresponding 1089 attachment point is considered to be layered. 1090 1091 (replace section 4.4.2.3, "Attaching Texture Images to a Framebuffer") 1092 1093 GL supports copying the rendered contents of the framebuffer into the 1094 images of a texture object through the use of the routines 1095 CopyTexImage{1D|2D}, and CopyTexSubImage{1D|2D|3D}. Additionally, GL 1096 supports rendering directly into the images of a texture object. 1097 1098 To render directly into a texture image, a specified level of a texture 1099 object can be attached as one of the logical buffers of the currently 1100 bound framebuffer object by calling: 1101 1102 void FramebufferTextureARB(enum target, enum attachment, 1103 uint texture, int level); 1104 1105 <target> must be FRAMEBUFFER_EXT. <attachment> must be one of the 1106 attachment points of the framebuffer listed in table 1.nnn. 1107 1108 If <texture> is zero, any image or array of images attached to the 1109 attachment point named by <attachment> is detached, and the state of the 1110 attachment point is reset to its initial values. <level> is ignored if 1111 <texture> is zero. 1112 1113 If <texture> is non-zero, FramebufferTextureARB attaches level <level> of 1114 the texture object named <texture> to the framebuffer attachment point 1115 named by <attachment>. The error INVALID_VALUE is generated if <texture> 1116 is not the name of a texture object, or if <level> is not a supported 1117 texture level number for textures of the type corresponding to <target>. 1118 The error INVALID_OPERATION is generated if <texture> is the name of a 1119 buffer texture. 1120 1121 If <texture> is the name of a three-dimensional texture, cube map texture, 1122 or one- or two-dimensional array texture, the texture level attached to 1123 the framebuffer attachment point is an array of images, and the 1124 framebuffer attachment is considered layered. 1125 1126 The command 1127 1128 void FramebufferTextureLayerARB(enum target, enum attachment, 1129 uint texture, int level, int layer); 1130 1131 operates like FramebufferTextureARB, except that only a single layer of 1132 the texture level, numbered <layer>, is attached to the attachment point. 1133 If <texture> is non-zero, the error INVALID_VALUE is generated if <layer> 1134 is negative, or if <texture> is not the name of a texture object. The 1135 error INVALID_OPERATION is generated unless <texture> is zero or the name 1136 of a three-dimensional or one- or two-dimensional array texture. 1137 1138 The command 1139 1140 void FramebufferTextureFaceARB(enum target, enum attachment, 1141 uint texture, int level, enum face); 1142 1143 operates like FramebufferTextureARB, except that only a single face of a 1144 cube map texture, given by <face>, is attached to the attachment point. 1145 <face> is one of TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_NEGATIVE_X, 1146 TEXTURE_CUBE_MAP_POSITIVE_Y, TEXTURE_CUBE_MAP_NEGATIVE_Y, 1147 TEXTURE_CUBE_MAP_POSITIVE_Z, TEXTURE_CUBE_MAP_NEGATIVE_Z. If <texture> is 1148 non-zero, the error INVALID_VALUE is generated if <texture> is not the 1149 name of a texture object. The error INVALID_OPERATION is generated unless 1150 <texture> is zero or the name of a cube map texture. 1151 1152 The command 1153 1154 void FramebufferTexture1DARB(enum target, enum attachment, 1155 enum textarget, uint texture, int level); 1156 1157 operates identically to FramebufferTextureARB, except for two additional 1158 restrictions. If <texture> is non-zero, the error INVALID_ENUM is 1159 generated if <textarget> is not TEXTURE_1D and the error INVALID_OPERATION 1160 is generated unless <texture> is the name of a one-dimensional texture. 1161 1162 The command 1163 1164 void FramebufferTexture2DARB(enum target, enum attachment, 1165 enum textarget, uint texture, int level); 1166 1167 operates similarly to FramebufferTextureARB. If <textarget> is TEXTURE_2D 1168 or TEXTURE_RECTANGLE_ARB, <texture> must be zero or the name of a 1169 two-dimensional or rectangle texture. If <textarget> is 1170 TEXTURE_CUBE_MAP_POSITIVE_X, TEXTURE_CUBE_MAP_NEGATIVE_X, 1171 TEXTURE_CUBE_MAP_POSITIVE_Y, TEXTURE_CUBE_MAP_NEGATIVE_Y, 1172 TEXTURE_CUBE_MAP_POSITIVE_Z, or TEXTURE_CUBE_MAP_NEGATIVE_Z, <texture> 1173 must be zero or the name of a cube map texture. For cube map textures, 1174 only the single face of the cube map texture level given by <textarget> is 1175 attached. The error INVALID_ENUM is generated if <texture> is not zero 1176 and <textarget> is not one of the values enumerated above. The error 1177 INVALID_OPERATION is generated if <texture> is the name of a texture whose 1178 type does not match the texture type required by <textarget>. 1179 1180 The command 1181 1182 void FramebufferTexture3DEXT(enum target, enum attachment, 1183 enum textarget, uint texture, 1184 int level, int zoffset); 1185 1186 behaves identically to FramebufferTextureLayerARB, with the <layer> 1187 parameter set to the value of <zoffset>. The error INVALID_ENUM is 1188 generated if <textarget> is not TEXTURE_3D. The error INVALID_OPERATION 1189 is generated unless <texture> is zero or the name of a three-dimensional 1190 texture. 1191 1192 For all FramebufferTexture commands, if <texture> is non-zero and the 1193 command does not result in an error, the framebuffer attachment state 1194 corresponding to <attachment> is updated based on the new attachment. 1195 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is set to TEXTURE, 1196 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT is set to <texture>, and 1197 FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL is set to <level>. 1198 FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_FACE is set to <textarget> if 1199 FramebufferTexture2DEXT is called and <texture> is the name of a cubemap 1200 texture; otherwise, it is set to TEXTURE_CUBE_MAP_POSITIVE_X. 1201 FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER is set to <layer> or <zoffset> if 1202 FramebufferTextureLayerEXT or FramebufferTexture3DEXT is called; 1203 otherwise, it is set to zero. FRAMEBUFFER_ATTACHMENT_LAYERED_ARB is set 1204 to TRUE if FramebufferTextureARB is called and <texture> is the name of a 1205 three-dimensional texture, cube map texture, or one- or two-dimensional 1206 array texture; otherwise it is set to FALSE. 1207 1208 (modify Section 4.4.4.1, Framebuffer Attachment Completeness -- add to the 1209 conditions necessary for attachment completeness) 1210 1211 The framebuffer attachment point <attachment> is said to be "framebuffer 1212 attachment complete" if ...: 1213 1214 * If FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE and 1215 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT names a three-dimensional 1216 texture, FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER must be smaller than 1217 the depth of the texture. 1218 1219 * If FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE and 1220 FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT names a one- or two-dimensional 1221 array texture, FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER must be 1222 smaller than the number of layers in the texture. 1223 1224 (modify section 4.4.4.2, Framebuffer Completeness -- add to the list of 1225 conditions necessary for completeness) 1226 1227 * If any framebuffer attachment is layered, all populated attachments 1228 must be layered. Additionally, all populated color attachments must 1229 be from textures of the same target (i.e., three-dimensional, cube 1230 map, or one- or two-dimensional array textures). 1231 { FRAMEBUFFER_INCOMPLETE_LAYER_TARGETS_ARB } 1232 1233 * If any framebuffer attachment is layered, all attachments must have 1234 the same layer count. For three-dimensional textures, the layer count 1235 is the depth of the attached volume. For cube map textures, the layer 1236 count is always six. For one- and two-dimensional array textures, the 1237 layer count is simply the number of layers in the array texture. 1238 { FRAMEBUFFER_INCOMPLETE_LAYER_COUNT_ARB } 1239 1240 The enum in { brackets } after each clause of the framebuffer completeness 1241 rules specifies the return value of CheckFramebufferStatusARB (see below) 1242 that is generated when that clause is violated. ... 1243 1244 (add section 4.4.7, Layered Framebuffers) 1245 1246 A framebuffer is considered to be layered if it is complete and all of its 1247 populated attachments are layered. When rendering to a layered 1248 framebuffer, each fragment generated by the GL is assigned a layer number. 1249 The layer number for a fragment is zero if 1250 1251 * the fragment is generated by DrawPixels, CopyPixels, or Bitmap, 1252 1253 * geometry shaders are disabled, or 1254 1255 * the current geometry shader does not contain an instruction that 1256 statically assigns a value to the built-in output variable gl_Layer. 1257 1258 Otherwise, the layer for each point, line, or triangle emitted by the 1259 geometry shader is taken from the layer output of one of the vertices of 1260 the primitive. The vertex used is implementation-dependent. To get 1261 defined results, all vertices of each primitive emitted should set the 1262 same value for gl_Layer. Since the EndPrimitive() built-in function 1263 starts a new output primitive, defined results can be achieved if 1264 EndPrimitive() is called between two vertices emitted with different layer 1265 numbers. A layer number written by a geometry shader has no effect if the 1266 framebuffer is not layered. 1267 1268 When fragments are written to a layered framebuffer, the fragment's layer 1269 number selects a single image from the array of images at each attachment 1270 point to use for the stencil test (section 4.1.5), depth buffer test 1271 (section 4.1.6), and for blending and color buffer writes (section 4.1.8). 1272 If the fragment's layer number is negative or greater than the number of 1273 layers attached, the effects of the fragment on the framebuffer contents 1274 are undefined. 1275 1276 When the Clear command is used to clear a layered framebuffer attachment, 1277 all layers of the attachment are cleared. 1278 1279 When commands such as ReadPixels or CopyPixels read from a layered 1280 framebuffer, the image at layer zero of the selected attachment is always 1281 used to obtain pixel values. 1282 1283 When cube map texture levels are attached to a layered framebuffer, there 1284 are six layers attached, numbered zero through five. Each layer number is 1285 mapped to a cube map face, as indicated in Table X.4. 1286 1287 layer number cube map face 1288 ------------ --------------------------- 1289 0 TEXTURE_CUBE_MAP_POSITIVE_X 1290 1 TEXTURE_CUBE_MAP_NEGATIVE_X 1291 2 TEXTURE_CUBE_MAP_POSITIVE_Y 1292 3 TEXTURE_CUBE_MAP_NEGATIVE_Y 1293 4 TEXTURE_CUBE_MAP_POSITIVE_Z 1294 5 TEXTURE_CUBE_MAP_NEGATIVE_Z 1295 1296 Table X.4, Layer numbers for cube map texture faces. The layers are 1297 numbered in the same sequence as the cube map face token values. 1298 1299 (modify Section 6.1.3, Enumerated Queries -- Modify/add to list of <pname> 1300 values for GetFramebufferAttachmentParameterivARB if 1301 FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE_EXT is TEXTURE) 1302 1303 If <pname> is FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER and the attached 1304 image is a layer of a three-dimensional texture or one- or 1305 two-dimensional array texture, then <params> will contain the specified 1306 layer number. Otherwise, <params> will contain the value zero. 1307 1308 If <pname> is FRAMEBUFFER_ATTACHMENT_LAYERED_ARB, then <params> will 1309 contain TRUE if an entire level of a three-dimesional texture, cube map 1310 texture, or one- or two-dimensional array texture is attached to the 1311 <attachment>. Otherwise, <params> will contain FALSE. 1312 1313 (Modify the Additions to Chapter 5, section 5.4) 1314 1315 Add the commands FramebufferTextureARB, FramebufferTextureLayerARB, and 1316 FramebufferTextureFaceARB to the list of commands that are not compiled 1317 into a display list, but executed immediately. 1318 1319Dependencies on EXT_framebuffer_blit 1320 1321 If EXT_framebuffer_blit is supported, the EXT_framebuffer_object language 1322 should be further amended so that <target> values passed to 1323 FramebufferTextureARB and FramebufferTextureLayerARB can be 1324 DRAW_FRAMEBUFFER_EXT or READ_FRAMEBUFFER_EXT, and that those functions 1325 set/query state for the draw framebuffer if <target> is FRAMEBUFFER_EXT. 1326 1327 If BlitFramebufferEXT() is called with a layered read framebuffer, pixel 1328 values are obtained from layer zero from the read framebuffer. If the 1329 draw framebuffer is layered, pixel values are written to layer zero of the 1330 draw framebuffer. If both framebuffers are layered, the two-dimensional 1331 blit operation is still performed only on layer zero. 1332 1333Dependencies on EXT_texture_array 1334 1335 If EXT_texture_array is not supported, the discussion array textures the 1336 layered rendering edits to EXT_framebuffer_object should be 1337 removed. Layered rendering to cube map and 3D textures would still be 1338 supported. 1339 1340 If EXT_texture_array is supported, the edits to EXT_framebuffer_object 1341 supersede those made in EXT_texture_array, except for language pertaining 1342 to mipmap generation of array textures. 1343 1344 There are no functional incompatibilities between the FBO support in these 1345 two specifications. The only differences are that this extension supports 1346 layered rendering and also rewrites certain sections of the core FBO 1347 specification more aggressively. 1348 1349Dependencies on ARB_texture_rectangle 1350 1351 If ARB_texture_rectangle is not supported, all references to rectangle 1352 textures in the EXT_framebuffer_object spec language should be removed. 1353 1354Dependencies on ARB_texture_buffer_object 1355 1356 If ARB_buffer_object is not supported, the reference to an 1357 INVALID_OPERATION error if a buffer texture is passed to 1358 FramebufferTextureARB should be removed. 1359 1360Dependencies on OpenGL 3.2 1361 1362 If this extension and OpenGL 3.2 (and GLSL 1.50) are supported, two 1363 slightly different versions of geometry shader support are available. 1364 1365 In this extension, the input and output primitive types and maximum output 1366 vertex count are specified prior to linking, using the 1367 ProgramParameteriARB command. However, OpenGL 3.2 requires that these 1368 properties be specified using the "layout" modifier in geometry shader 1369 source and provides no program paramter state. For implementations 1370 supporting both features, there are potentially two different ways to set 1371 these properties prior to linking a program. If no geometry shader 1372 enables this extension via "#extension", all three properties must be 1373 specified in shader source as required by OpenGL 3.2. Otherwise, these 1374 properties need not be specified in source code, but still may be if 1375 #version 150 or better is enabled. If a given property is specified in 1376 geometry shader source, the value from the source code is used; otherwise, 1377 the value of the program parameter state is used. 1378 1379 Additionally, OpenGL 3.2 and ARB_geometry_shader have similarly-named 1380 queries for the input and output primitive type and maximum vertex count. 1381 In particular, the commands 1382 1383 glGetProgramiv(program, GL_GEOMETRY_VERTICES_OUT_ARB, &verticesOut); 1384 glGetProgramiv(program, GL_GEOMETRY_INPUT_TYPE_ARB, &inputType); 1385 glGetProgramiv(program, GL_GEOMETRY_OUTPUT_TYPE_ARB, &outputType); 1386 1387 query the program parameter state provided by this extension. If the 1388 program parameter state is changed without relinking, the new values will 1389 be returned, even though old values will be in effect when the program is 1390 used. These queries are not supported by unextended OpenGL 3.2. Instead, 1391 OpenGL 3.2 supports the following queries: 1392 1393 glGetProgramiv(program, GL_GEOMETRY_VERTICES_OUT, &verticesOut); 1394 glGetProgramiv(program, GL_GEOMETRY_INPUT_TYPE, &inputType); 1395 glGetProgramiv(program, GL_GEOMETRY_OUTPUT_TYPE, &outputType); 1396 1397 The OpenGL 3.2 queries return the properties established when the program 1398 is linked, and ignore the program parameter state. Despite the very 1399 similar names, there is no conflict -- neither the enumerant names nor the 1400 values are exactly the same. 1401 1402 If OpenGL 3.2 is supported and layered framebuffer attachments are used, 1403 the requirement that all layer counts match is removed and the 1404 FRAMEBUFFER_INCOMPLETE_LAYER_COUNT_ARB error condition will never be 1405 generated. Instead, rendering will use the minimum layer count for all 1406 attachments as specified by OpenGL 3.2. This change was made for 1407 consistency with OpenGL 3.0's framebuffer object support, which similarly 1408 lifted the requirement that framebuffer attachments have matching widths 1409 and heights. 1410 1411Dependencies on ARB_uniform_buffer_object 1412 1413 If ARB_uniform_buffer_object (or OpenGL 3.1) is not supported, language 1414 referring to MAX_COMBINED_GEOMETRY_UNIFORM_COMPONENTS (defined in the 1415 ARB_uniform_buffer_object spec) and the "default uniform block" should be 1416 removed. 1417 1418 1419GLX Protocol 1420 1421 The following rendering command is sent to the server as part of a 1422 glXRender request: 1423 1424 ProgramParameteriARB 1425 2 16 rendering command length 1426 2 266 rendering command opcode 1427 4 CARD32 program 1428 4 ENUM pname 1429 4 INT32 value 1430 1431 FramebufferTextureARB 1432 1433 2 20 rendering command length 1434 2 267 rendering command opcode 1435 4 ENUM target 1436 4 ENUM attachment 1437 4 CARD32 texture 1438 4 INT32 level 1439 1440 FramebufferTextureLayerARB 1441 1442 2 24 rendering command length 1443 2 237 rendering command opcode 1444 4 ENUM target 1445 4 ENUM attachment 1446 4 CARD32 texture 1447 4 INT32 level 1448 4 INT32 layer 1449 1450 FramebufferTextureFaceARB 1451 1452 2 24 rendering command length 1453 2 268 rendering command opcode 1454 4 ENUM target 1455 4 ENUM attachment 1456 4 CARD32 texture 1457 4 INT32 level 1458 4 ENUM face 1459 1460Errors 1461 1462 The error INVALID_VALUE is generated by ProgramParameteriARB if <pname> is 1463 GEOMETRY_INPUT_TYPE_ARB and <value> is not one of POINTS, LINES, 1464 LINES_ADJACENCY_ARB, TRIANGLES or TRIANGLES_ADJACENCY_ARB. 1465 1466 The error INVALID_VALUE is generated by ProgramParameteriARB if <pname> is 1467 GEOMETRY_OUTPUT_TYPE_ARB and <value> is not one of POINTS, LINE_STRIP or 1468 TRIANGLE_STRIP. 1469 1470 The error INVALID_VALUE is generated by ProgramParameteriARB if <pname> is 1471 GEOMETRY_VERTICES_OUT_ARB and <value> is negative. 1472 1473 The error INVALID_VALUE is generated by ProgramParameteriARB if <pname> is 1474 GEOMETRY_VERTICES_OUT_ARB and <value> exceeds 1475 MAX_GEOMETRY_OUTPUT_VERTICES_ARB. 1476 1477 The error INVALID_VALUE is generated by ProgramParameteriARB if <pname> is 1478 set to GEOMETRY_VERTICES_OUT_ARB and the product of <value> and the sum of 1479 all components of all active varying variables exceeds 1480 MAX_GEOMETRY_TOTAL_OUTPUT_COMPONENTS_ARB. 1481 1482 The error INVALID_OPERATION is generated if Begin, or any command that 1483 implicitly calls Begin, is called when a geometry shader is active and: 1484 1485 * the input primitive type of the current geometry shader is 1486 POINTS and <mode> is not POINTS, 1487 1488 * the input primitive type of the current geometry shader is 1489 LINES and <mode> is not LINES, LINE_STRIP, or LINE_LOOP, 1490 1491 * the input primitive type of the current geometry shader is 1492 TRIANGLES and <mode> is not TRIANGLES, TRIANGLE_STRIP or 1493 TRIANGLE_FAN, 1494 1495 * the input primitive type of the current geometry shader is 1496 LINES_ADJACENCY_ARB and <mode> is not LINES_ADJACENCY_ARB or 1497 LINE_STRIP_ADJACENCY_ARB, or 1498 1499 * the input primitive type of the current geometry shader is 1500 TRIANGLES_ADJACENCY_ARB and <mode> is not 1501 TRIANGLES_ADJACENCY_ARB or TRIANGLE_STRIP_ADJACENCY_ARB. 1502 1503New State 1504 1505 Initial 1506 Get Value Type Get Command Value Description Sec. Attribute 1507 ------------------------- ---- ----------- ------- ---------------------- ------ ---------- 1508 FRAMEBUFFER_ATTACHMENT_ nxB GetFramebuffer- FALSE Framebuffer attachment 4.4.2.3 - 1509 LAYERED_ARB Attachment- is layered 1510 ParameterivARB 1511 1512 Modify the following state value in Table 6.28, Shader Object State, 1513 p. 289. 1514 1515 Get Value Type Get Command Value Description Sec. Attribute 1516 ------------------ ---- ----------- ------- ---------------------- ------ --------- 1517 SHADER_TYPE Z2 GetShaderiv - Type of shader (vertex, 2.15.1 - 1518 Fragment, geometry) 1519 1520 Add the following state to Table 6.29, Program Object State, p. 290 1521 1522 Initial 1523 Get Value Type Get Command Value Description Sec. Attribute 1524 ------------------------- ---- ------------ ------- ----------------- ------ ------- 1525 GEOMETRY_VERTICES_OUT_ARB Z+ GetProgramiv 0 max # of output vertices 2.16.4 - 1526 GEOMETRY_INPUT_TYPE_ARB Z5 GetProgramiv TRIANGLES Primitive input type 2.16.1 - 1527 GEOMETRY_OUTPUT_TYPE_ARB Z3 GetProgramiv TRIANGLE_ Primitive output type 2.16.2 - 1528 STRIP 1529 1530New Implementation Dependent State 1531 1532 Min. 1533 Get Value Type Get Command Value Description Sec. Attrib 1534 ---------------------- ---- ----------- ----- -------------------- -------- ------ 1535 MAX_GEOMETRY_TEXTURE_ Z+ GetIntegerv 0 maximum number of 2.16.4 - 1536 IMAGE_UNITS_ARB texture image units 1537 accessible in a 1538 geometry shader 1539 MAX_GEOMETRY_OUTPUT_ Z+ GetIntegerv 256 maximum number of 2.16.4 - 1540 VERTICES_ARB vertices that any 1541 geometry shader can 1542 can emit 1543 MAX_GEOMETRY_TOTAL_ Z+ GetIntegerv 1024 maximum number of 2.16.4 - 1544 OUTPUT_COMPONENTS_ARB total components (all 1545 vertices) of active 1546 varyings that a 1547 geometry shader can 1548 emit 1549 MAX_GEOMETRY_UNIFORM_ Z+ GetIntegerv 512 Number of words for 2.16.3 - 1550 COMPONENTS_ARB geometry shader 1551 uniform variables 1552 MAX_GEOMETRY_VARYING_ Z+ GetIntegerv 32 Number of components 2.16.4 - 1553 COMPONENTS_ARB for varying variables 1554 between geometry and 1555 fragment shaders 1556 MAX_VERTEX_VARYING_ Z+ GetIntegerv 32 Number of components 2.15.3 - 1557 COMPONENTS_ARB for varying variables 1558 between Vertex and 1559 geometry shaders 1560 MAX_VARYING_ Z+ GetIntegerv 32 Alias for 2.15.3 - 1561 COMPONENTS_ARB MAX_VARYING_FLOATS 1562 1563Modifications to the OpenGL Shading Language Specification version 15641.10.59 1565 1566 Including the following line in a shader can be used to control the 1567 language features described in this extension: 1568 1569 #extension GL_ARB_geometry_shader4 : <behavior> 1570 1571 where <behavior> is as specified in section 3.3. 1572 1573 A new preprocessor #define is added to the OpenGL Shading Language: 1574 1575 #define GL_ARB_geometry_shader4 1 1576 1577 Change the introduction to Chapter 2 "Overview of OpenGL Shading" as 1578 follows: 1579 1580 The OpenGL Shading Language is actually three closely related 1581 languages. These languages are used to create shaders for the programmable 1582 processors contained in the OpenGL processing pipeline. The precise 1583 definition of these programmable units is left to separate 1584 specifications. In this document, we define them only well enough to 1585 provide a context for defining these languages. Unless otherwise noted in 1586 this paper, a language feature applies to all languages, and common usage 1587 will refer to these languages as a single language. The specific languages 1588 will be referred to by the name of the processor they target: vertex, 1589 geometry or fragment. 1590 1591 Change the last sentence of the first paragraph of section 3.2 1592 "Source Strings" to: 1593 1594 Multiple shaders of the same language (vertex, geometry or fragment) can 1595 be linked together to form a single program. 1596 1597 Change the first paragraph of section 4.1.3, "Integers" as follows: 1598 1599 ... integers are limited to 16 bits of precision, plus a sign 1600 representation in the vertex, geometry and fragment languages.. 1601 1602 Change the first paragraph of section 4.1.9, "Arrays", as follows: 1603 1604 Variables of the same type can be aggregated into one- and two- 1605 dimensional arrays by declaring a name followed by brackets ( [ ] for 1606 one-dimensional arrays and [][] for two-dimensional arrays) enclosing an 1607 optional size. When an array size is specified in a declaration, it must 1608 be an integral constant expression (see Section 4.3.3 "Integral Constant 1609 Expressions") greater than zero. If an array is indexed with an 1610 expression that is not an integral constant expression or passed as an 1611 argument to a function, then its size must be declared before any such 1612 use. It is legal to declare an array without a size and then later 1613 re-declare the same name as an array of the same type and specify a 1614 size. It is illegal to declare an array with a size, and then later (in 1615 the same shader) index the same array with an integral constant expression 1616 greater than or equal to the declared size. It is also illegal to index an 1617 array with a negative constant expression. Arrays declared as formal 1618 parameters in a function declaration must specify a size. Undefined 1619 behavior results from indexing an array with a non-constant expression 1620 that's greater than or equal to the array's size or less than 0. All basic 1621 types and structures can be formed into arrays. 1622 1623 Two-dimensional arrays can only be declared as "varying in" variables in a 1624 geometry shader. See section 4.3.6 for details. All other declarations of 1625 two-dimensional arrays are illegal. 1626 1627 Change the fourth paragraph of section 4.2 "Scoping", as follows: 1628 1629 Shared globals are global variables declared with the same name in 1630 independently compiled units (shaders) of the same language (vertex, 1631 geometry or fragment) that are linked together . 1632 1633 Change section 4.3 "Type Qualifiers" 1634 1635 Change the "varying", "in" and "out" qualifiers as follows: 1636 1637 varying - linkage between a vertex shader and geometry shader, or between 1638 a geometry shader and a fragment shader, or between a vertex shader and a 1639 fragment shader. 1640 1641 in - for function parameters passed into a function or for input varying 1642 variables (geometry only) 1643 1644 out - for function parameters passed back out of a function, but not 1645 initialized for use when passed in. Also for output varying variables 1646 (geometry only). 1647 1648 Change section 4.3.6 "Varying" as follows: 1649 1650 Varying variables provide the interface between the vertex shader and 1651 geometry shader and also between the geometry shader and fragment shader 1652 and the fixed functionality between them. If no geometry shader is 1653 present, varying variables also provide the interface between the vertex 1654 shader and fragment shader. 1655 1656 The vertex, or geometry shader will compute values per vertex (such 1657 as color, texture coordinates, etc) and write them to output variables 1658 declared with the "varying" qualifier (vertex or geometry) or "varying 1659 out" qualifiers (geometry only). A vertex or geometry shader may also 1660 read these output varying variables, getting back the same values it has 1661 written. Reading an output varying variable in a vertex or geometry shader 1662 returns undefined results if it is read before being written. 1663 1664 A geometry shader may also read from an input varying variable declared 1665 with the "varying in" qualifiers. The value read will be the same value as 1666 written by the vertex shader for that varying variable. Since a geometry 1667 shader operates on primitives, each input varying variable needs to be 1668 declared as an array. Each element of such an array corresponds to a 1669 vertex of the primitive being processed. If the varying variable is 1670 declared as a scalar or matrix in the vertex shader, it will be a 1671 one-dimensional array in the geometry shader. Each array can optionally 1672 have a size declared. If a size is not specified, it inferred by the 1673 linker and depends on the value of the input primitive type. See table 1674 4.3.xxx to determine the exact size. The read-only built-in constant 1675 gl_VerticesIn will be set to this value by the linker. If a size is 1676 specified, it has to be the size as given by table 4.3.xxx, otherwise a 1677 link error will occur. The built-in constant gl_VerticesIn, if so desired, 1678 can be used to size the array correctly for each input primitive 1679 type. Varying variables can also be declared as arrays in the vertex 1680 shader. This means that those, on input to the geometry shader, must be 1681 declared as two- dimensional arrays. The first index to the 1682 two-dimensional array holds the vertex number. Declaring a size for the 1683 first range of the array is optional, just as it is for one-dimensional 1684 arrays. The second index holds the per-vertex array data. Declaring a 1685 size for the second range of the array is not optional, and has to match 1686 the declaration in the vertex shader. 1687 1688 Value of built-in 1689 Input primitive type gl_VerticesIn 1690 ----------------------- ----------------- 1691 POINTS 1 1692 LINES 2 1693 LINES_ADJACENCY_ARB 4 1694 TRIANGLES 3 1695 TRIANGLES_ADJACENCY_ARB 6 1696 1697 Table 4.3.xxxx The value of the built-in variable gl_VerticesIn is 1698 determined at link time, based on the input primitive type. 1699 1700 It is illegal to index these varying arrays, or in the case of two- 1701 dimensional arrays, the first range of the array, with a negative integral 1702 constant expression or an integral constant expression greater than or 1703 equal to gl_VerticesIn. A link error will occur in these cases. 1704 1705 Varying variables that are part of the interface to the fragment shader 1706 are set per vertex and interpolated in a perspective correct manner, 1707 unless flat shaded, over the primitive being rendered. If single-sampling, 1708 the interpolated value is for the fragment center. If multi-sampling, the 1709 interpolated value can be anywhere within the pixel, including the 1710 fragment center or one of the fragment samples. 1711 1712 A fragment shader may read from varying variables and the value read will 1713 be the interpolated value, as a function of the fragment's position within 1714 the primitive, unless the varying variable is flat shaded. A fragment 1715 shader cannot write to a varying variable. 1716 1717 If a geometry shader is present, the type of the varying variables with 1718 the same name declared in the vertex shader and the input varying 1719 variables in the geometry shader must match, otherwise the link command 1720 will fail. Likewise, the type of the output varying variables with the 1721 same name declared in the geometry shader and the varying variables in the 1722 fragment shader must match. 1723 1724 If a geometry shader is not present, the type of the varying variables 1725 with the same name declared in both the vertex and fragment shaders must 1726 match, otherwise the link command will fail. 1727 1728 Only those varying variables used (i.e. read) in the geometry or fragment 1729 shader must be written to by the vertex or geometry shader; declaring 1730 superfluous varying variables in the vertex shader or declaring 1731 superfluous output varying variables in the geometry shader is 1732 permissible. 1733 1734 Varying variables are declared as in the following example: 1735 1736 varying in float foo[]; // geometry shader input. Size of the 1737 // array set as a result of link, based 1738 // on the input primitive type. 1739 1740 varying in float foo[gl_VerticesIn]; // geometry shader input 1741 1742 varying in float foo[3]; // geometry shader input. Only legal for 1743 // the TRIANGLES input primitive type 1744 1745 varying in float foo[][5]; // Size of the first range set as a 1746 // result of link. Each vertex holds an 1747 // array of 5 floats. 1748 1749 varying out vec4 bar; // geometry output 1750 varying vec3 normal; // vertex shader output or fragment 1751 // shader input 1752 1753 The varying qualifier can be used only with the data types float, vec2, 1754 vec3, vec4, mat2, mat3 and mat4 or arrays of these. Structures cannot be 1755 varying. Additionally, the "varying in" and "varying out" qualifiers can 1756 only be used in a geometry shader. 1757 1758 If no vertex shader is active, the fixed functionality pipeline of OpenGL 1759 will compute values for the built-in varying variables that will be 1760 consumed by the fragment shader. Similarly, if no fragment shader is 1761 active, the vertex shader or geometry shader is responsible for computing 1762 and writing to the built-in varying variables that are needed for OpenGL's 1763 fixed functionality fragment pipeline. 1764 1765 Varying variables are required to have global scope, and must be declared 1766 outside of function bodies, before their first use. 1767 1768 Change section 7.1 "Vertex Shader Special Variables" 1769 1770 Rename this section to "Vertex and Geometry Shader Special Variables" 1771 1772 Anywhere in this section where it reads "vertex language" replace it with 1773 "vertex and geometry language". 1774 1775 Anywhere in this section where it reads "vertex shader" replace it with 1776 "vertex shader or geometry shader". 1777 1778 Change the second paragraph to: 1779 1780 The variable gl_Position is available only in the vertex and geometry 1781 language and is intended for writing the homogeneous vertex position. It 1782 can be written at any time during shader execution. It may also be read 1783 back by the shader after being written. This value will be used by 1784 primitive assembly, clipping, culling, and other fixed functionality 1785 operations that operate on primitives after vertex or geometry processing 1786 has occurred. Compilers may generate a diagnostic message if they detect 1787 gl_Position is read before being written, but not all such cases are 1788 detectable. Writing to gl_Position is optional. If gl_Position is not 1789 written but subsequent stages of the OpenGL pipeline consume gl_Position, 1790 then results are undefined. 1791 1792 Change the last sentence of this section into the following: 1793 1794 The read-only built-in gl_PrimitiveIDIn is available only in the geometry 1795 language and is filled with the number of primitives processed by the 1796 geometry shader since the last time Begin was called (directly or 1797 indirectly via vertex array functions). See section 2.16.4 for more 1798 information. 1799 1800 This variable is intrinsically declared as: 1801 1802 int gl_PrimitiveIDIn; // read only 1803 1804 The built-in output variable gl_PrimitiveID is available only in the 1805 geometry language and provides a single integer that serves as a primitive 1806 identifier. This written primitive ID is available to fragment shaders. 1807 If a fragment shader using primitive IDs is active and a geometry shader 1808 is also active, the geometry shader must write to gl_PrimitiveID or the 1809 primitive ID in the fragment shader number is undefined. 1810 1811 The built-in output variable gl_Layer is available only in the geometry 1812 language, and provides the number of the layer of textures attached to a 1813 FBO to direct rendering to. If a shader statically assigns a value to 1814 gl_Layer, layered rendering mode is enabled. See section 2.16.4 for a 1815 detailed explanation. If a shader statically assigns a value to gl_Layer, 1816 and there is an execution path through the shader that does not set 1817 gl_Layer, then the value of gl_Layer may be undefined for executions of 1818 the shader that take that path. 1819 1820 These variables area intrinsically declared as: 1821 1822 int gl_PrimitiveID; 1823 int gl_Layer; 1824 1825 These variables can be read back by the shader after writing to them, to 1826 retrieve what was written. Reading the variable before writing it results 1827 in undefined behavior. If it is written more than once, the last value 1828 written is consumed by the subsequent operations. 1829 1830 All built-in variables discussed in this section have global scope. 1831 1832 Change section 7.2 "Fragment Shader Special Variables" 1833 1834 Change the first paragraph on p. 44 as follows: 1835 1836 The fragment shader has access to the read-only built-in variable 1837 gl_FrontFacing whose value is true if the fragment belongs to a 1838 front-facing primitive. One use of this is to emulate two-sided lighting 1839 by selecting one of two colors calculated by the vertex shader or geometry 1840 shader. 1841 1842 Change the first sentence of section 7.4 "Built-in Constants" 1843 1844 The following built-in constant is provided to geometry shaders. 1845 1846 const int gl_VerticesIn; // Value set at link time 1847 1848 The following built-in constants are provided to the vertex, geometry and 1849 fragment shaders: 1850 1851 Change section 7.6 "Varing Variables" 1852 1853 Unlike user-defined varying variables, the built-in varying variables 1854 don't have a strict one-to-one correspondence between the vertex language, 1855 geometry language and the fragment language. Four sets are provided, one 1856 set for the vertex language output, one set for the geometry language 1857 output, one set for the fragment language input and another set for the 1858 geometry language input. Their relationship is described below. 1859 1860 The following built-in varying variables are available to write to in a 1861 vertex shader or geometry shader. A particular one should be written to if 1862 any functionality in a corresponding geometry shader or fragment shader or 1863 fixed pipeline uses it or state derived from it. Otherwise, behavior is 1864 undefined. 1865 1866 Vertex language built-in outputs: 1867 1868 varying vec4 gl_FrontColor; 1869 varying vec4 gl_BackColor; 1870 varying vec4 gl_FrontSecondaryColor; 1871 varying vec4 gl_BackSecondaryColor; 1872 varying vec4 gl_TexCoord[]; // at most will be gl_MaxTextureCoords 1873 varying float gl_FogFragCoord; 1874 1875 Geometry language built-in outputs: 1876 1877 varying out vec4 gl_FrontColor; 1878 varying out vec4 gl_BackColor; 1879 varying out vec4 gl_FrontSecondaryColor; 1880 varying out vec4 gl_BackSecondaryColor; 1881 varying out vec4 gl_TexCoord[]; // at most gl_MaxTextureCoords 1882 varying out float gl_FogFragCoord; 1883 1884 For gl_FogFragCoord, the value written will be used as the "c" value on 1885 page 160 of the OpenGL 1.4 Specification by the fixed functionality 1886 pipeline. For example, if the z-coordinate of the fragment in eye space is 1887 desired as "c", then that's what the vertex or geometry shader should 1888 write into gl_FogFragCoord. 1889 1890 Indices used to subscript gl_TexCoord must either be an integral constant 1891 expressions, or this array must be re-declared by the shader with a 1892 size. The size can be at most gl_MaxTextureCoords. Using indexes close to 1893 0 may aid the implementation in preserving varying resources. 1894 1895 The following input varying variables are available to read from in a 1896 geometry shader. 1897 1898 varying in vec4 gl_FrontColorIn[gl_VerticesIn]; 1899 varying in vec4 gl_BackColorIn[gl_VerticesIn]; 1900 varying in vec4 gl_FrontSecondaryColorIn[gl_VerticesIn]; 1901 varying in vec4 gl_BackSecondaryColorIn[gl_VerticesIn]; 1902 varying in vec4 gl_TexCoordIn[gl_VerticesIn][]; // at most will be 1903 // gl_MaxTextureCoords 1904 varying in float gl_FogFragCoordIn[gl_VerticesIn]; 1905 varying in vec4 gl_PositionIn[gl_VerticesIn]; 1906 varying in float gl_PointSizeIn[gl_VerticesIn]; 1907 varying in vec4 gl_ClipVertexIn[gl_VerticesIn]; 1908 1909 All built-in variables are one-dimensional arrays, except for 1910 gl_TexCoordIn, which is a two-dimensional array. Each element of a 1911 one-dimensional array, or the first index of a two-dimensional array, 1912 corresponds to a vertex of the primitive being processed and receives 1913 their value from the equivalent vertex output varying variables. See also 1914 section 4.3.6. 1915 1916 The following varying variables are available to read from in a fragment 1917 shader. The gl_Color and gl_SecondaryColor names are the same names as 1918 attributes passed to the vertex shader. However, there is no name 1919 conflict, because attributes are visible only in vertex shaders and the 1920 following are only visible in a fragment shader. 1921 1922 varying vec4 gl_Color; 1923 varying vec4 gl_SecondaryColor; 1924 varying vec4 gl_TexCoord[]; // at most will be gl_MaxTextureCoords 1925 varying float gl_FogFragCoord; 1926 1927 The values in gl_Color and gl_SecondaryColor will be derived automatically 1928 by the system from gl_FrontColor, gl_BackColor, gl_FrontSecondaryColor, 1929 and gl_BackSecondaryColor. This selection process is described in section 1930 2.14.1 of the OpenGL 2.0 Specification. If fixed functionality is used for 1931 vertex processing, then gl_FogFragCoord will either be the z-coordinate of 1932 the fragment in eye space, or the interpolation of the fog coordinate, as 1933 described in section 3.10 of the OpenGL 1.4 Specification. The 1934 gl_TexCoord[] values are the interpolated gl_TexCoord[] values from a 1935 vertex or geometry shader or the texture coordinates of any fixed pipeline 1936 based vertex functionality. 1937 1938 Indices to the fragment shader gl_TexCoord array are as described above in 1939 the vertex and geometry shader text. 1940 1941 Change section 8.7 "Texture Lookup Functions" 1942 1943 Change the first paragraph to: 1944 1945 Texture lookup functions are available to vertex, geometry and fragment 1946 shaders. However, level of detail is not computed by fixed functionality 1947 for vertex or geometry shaders, so there are some differences in operation 1948 between texture lookups. The functions. 1949 1950 Change the third and fourth paragraphs to: 1951 1952 In all functions below, the bias parameter is optional for fragment 1953 shaders. The bias parameter is not accepted in a vertex or geometry 1954 shader. For a fragment shader, if bias is present, it is added to the 1955 calculated level of detail prior to performing the texture access 1956 operation. If the bias parameter is not provided, then the implementation 1957 automatically selects level of detail: For a texture that is not 1958 mip-mapped, the texture is used directly. If it is mip- mapped and running 1959 in a fragment shader, the LOD computed by the implementation is used to do 1960 the texture lookup. If it is mip- mapped and running on the vertex or 1961 geometry shader, then the base LOD of the texture is used. 1962 1963 The built-ins suffixed with "Lod" are allowed only in a vertex or geometry 1964 shader. For the "Lod" functions, lod is directly used as the level of 1965 detail. 1966 1967 Change section 8.9 Noise Functions 1968 1969 Change the first paragraph to: 1970 1971 Noise functions are available to the vertex, geometry and fragment 1972 shaders. They are... 1973 1974 Add a section 8.10 Geometry Shader Functions 1975 1976 This section contains functions that are geometry language specific. 1977 1978 Syntax: 1979 1980 void EmitVertex(); // Geometry only 1981 void EndPrimitive(); // Geometry only 1982 1983 Description: 1984 1985 The function EmitVertex() specifies that a vertex is completed. A vertex 1986 is added to the current output primitive using the current values of the 1987 varying output variables and the current values of the special built-in 1988 output variables gl_PointSize, gl_ClipVertex, gl_Layer, gl_Position and 1989 gl_PrimitiveID. The values of any unwritten output variables are 1990 undefined. The values of all varying output variables and the special 1991 built-in output variables are undefined after a call to EmitVertex(). If a 1992 geometry shader, in one invocation, emits more vertices than the value 1993 GEOMETRY_VERTICES_OUT_ARB, these emits may have no effect. 1994 1995 The function EndPrimitive() specifies that the current output primitive is 1996 completed and a new output primitive (of the same type) should be 1997 started. This function does not emit a vertex. The effect of 1998 EndPrimitive() is roughly equivalent to calling End followed by a new 1999 Begin, where the primitive mode is taken from the program object parameter 2000 GEOMETRY_OUTPUT_TYPE_ARB. If the output primitive type is POINTS, calling 2001 EndPrimitive() is optional. 2002 2003 A geometry shader starts with an output primitive containing no 2004 vertices. When a geometry shader terminates, the current output primitive 2005 is automatically completed. It is not necessary to call EndPrimitive() if 2006 the geometry shader writes only a single primitive. 2007 2008 Add/Change section 9 (Shading language grammar): 2009 2010 init_declarator_list: 2011 single_declaration 2012 init_declarator_list COMMA IDENTIFIER 2013 init_declarator_list COMMA IDENTIFIER array_declarator_suffix 2014 init_declarator_list COMMA IDENTIFIER EQUAL initializer 2015 2016 single_declaration: 2017 fully_specified_type 2018 fully_specified_type IDENTIFIER 2019 fully_specified_type IDENTIFIER array_declarator_suffix 2020 fully_specified_type IDENTIFIER EQUAL initializer 2021 2022 array_declarator_suffix: 2023 LEFT_BRACKET RIGHT_BRACKET 2024 LEFT_BRACKET constant_expression RIGHT_BRACKET 2025 LEFT_BRACKET RIGHT_BRACKET array_declarator_suffix 2026 LEFT_BRACKET constant_expression RIGHT_BRACKET 2027 array_declarator_suffix 2028 2029 type_qualifier: 2030 CONST 2031 ATTRIBUTE // Vertex only 2032 VARYING 2033 VARYING IN // Geometry only 2034 VARYING OUT // Geometry only 2035 UNIFORM 2036 2037NVIDIA Implementation Details 2038 2039 Because of a hardware limitation, some GeForce 8 series chips use the 2040 odd vertex of an incomplete TRIANGLE_STRIP_ADJACENCY_ARB primitive 2041 as a replacement adjacency vertex rather than ignoring it. 2042 2043Issues 2044 2045 1. How do geometry shaders fit into the existing GL pipeline? 2046 2047 RESOLVED: The following diagram illustrates how geometry shaders fit 2048 into the "vertex processing" portion of the GL (Chapter 2 of the OpenGL 2049 2.0 Specification). 2050 2051 First, vertex attributes are specified via immediate-mode commands or 2052 through vertex arrays. They can be conventional attributes (e.g., 2053 glVertex, glColor, glTexCoord) or generic (numbered) attributes. 2054 2055 Vertices are then transformed, either using a vertex shader or 2056 fixed-function vertex processing. Fixed-function vertex processing 2057 includes position transformation (modelview and projection matrices), 2058 lighting, texture coordinate generation, and other calculations. The 2059 results of either method are a "transformed vertex", which has a 2060 position (in clip coordinates), front and back colors, texture 2061 coordinates, generic attributes (vertex shader only), and so on. Note 2062 that on many current GL implementations, vertex processing is performed 2063 by executing a "fixed function vertex shader" generated by the driver. 2064 2065 After vertex transformation, vertices are assembled into primitives, 2066 according to the topology (e.g., TRIANGLES, QUAD_STRIP) provided by the 2067 call to glBegin(). Primitives are points, lines, triangles, quads, or 2068 polygons. Many GL implementations do not directly support quads or 2069 polygons, but instead decompose them into triangles as permitted by the 2070 spec. 2071 2072 After initial primitive assembly, a geometry shader is executed on each 2073 individual point, line, or triangle primitive, if one is active. It can 2074 read the attributes of each transformed vertex, perform arbitrary 2075 computations, and emit new transformed vertices. These emitted vertices 2076 are themselves assembled into primitives according to the output 2077 primitive type of the geometry shader. 2078 2079 Then, the colors of the vertices of each primitive are clamped to [0,1] 2080 (if color clamping is enabled), and flat shading may be performed by 2081 taking the color from the provoking vertex of the primitive. 2082 2083 Each primitive is clipped to the view volume, and to any enabled 2084 user-defined clip planes. Color, texture coordinate, and other 2085 attribute values are computed for each new vertex introduced by 2086 clipping. 2087 2088 After clipping, the position of each vertex (in clip coordinates) is 2089 converted to normalized device coordinates in the perspective division 2090 (divide by w) step, and to window coordinates in the viewport 2091 transformation step. 2092 2093 At the same time, color values may be converted to normalized 2094 fixed-point values according to the "Final Color Processing" portion of 2095 the specification. 2096 2097 After the vertices of the primitive are transformed to window 2098 coordinate, the GL determines if the primitive is front- or back-facing. 2099 That information is used for two-sided color selection, where a single 2100 set of colors is selected from either the front or back colors 2101 associated with each transformed vertex. 2102 2103 When all this is done, the final transformed position, colors (primary 2104 and secondary), and other attributes are used for rasterization (Chapter 2105 3 in the OpenGL 2.0 Specification). 2106 2107 When the raster position is specified (via glRasterPos), it goes through 2108 the entire vertex processing pipeline as though it were a point. 2109 However, geometry shaders are never run on the raster position. 2110 2111 2112 |generic |conventional 2113 |vertex |vertex 2114 |attributes |attributes 2115 | | 2116 | +-------------------+ 2117 | | | 2118 V V V 2119 vertex fixed-function 2120 shader vertex 2121 | processing 2122 | | 2123 | | 2124 +<-------------------+ 2125 | Output 2126 |position, color, Primitive 2127 |other vertex data Type 2128 | | 2129 V | 2130 Begin/ primitive geometry primitive | 2131 End ------> assembly -----> shader ----> assembly <-+ 2132 State | | 2133 V | 2134 +<------------------------------+ 2135 | 2136 | 2137 | color flat 2138 +----------> clamping ----> shading 2139 | | 2140 V | 2141 +<------------------------------+ 2142 | 2143 | 2144 clipping 2145 | 2146 | perspective viewport 2147 +------> divide ----> transform 2148 | | 2149 | +---+-----+ 2150 | V | 2151 | final facing | 2152 +------> color determination | 2153 | processing | | 2154 | | | | 2155 | | | | 2156 | +-----+ +----+ | 2157 | | | | 2158 | V V | 2159 | two-sided | 2160 | coloring | 2161 | | | 2162 | | | 2163 +------------------+ | +-------------+ 2164 | | | 2165 V V V 2166 rasterization 2167 | 2168 | 2169 V 2170 2171 2. Why is this called GL_ARB_geometry_shader4? There aren't any previous 2172 versions of this extension, let alone three? 2173 2174 RESOLVED: To match its sibling, ARB_gpu_shader4 and the assembly 2175 version NV_gpu_program4. This is the fourth generation of shading 2176 functionality, hence the "4" in the name. 2177 2178 3. Should the GL produce errors at Begin time if an application specifies a 2179 primitive mode that is "incompatible" with the geometry shader? For 2180 example, if the geometry shader operates on triangles and the 2181 application sends a POINTS primitive? 2182 2183 RESOLVED: Yes. Mismatches of app-specified primitive types and 2184 geometry shader input primitive types appear to be errors and would 2185 produce weird and wonderful effects. 2186 2187 4. Can the input primitive type of a geometry shader be determined at run 2188 time? 2189 2190 RESOLVED: No. Each geometry shader has a single input primitive type, 2191 and vertices are presented to the shader in a specific order based on 2192 that type. 2193 2194 5. Can the input primitive type of a geometry shader be changed? 2195 2196 DISCUSSION: The input primitive type is a property of the program 2197 object. A change of the input primitive type means the program object 2198 will need to be re-linked. It would be nice if the input primitive type 2199 was known at compile time, so that the compiler can do error checking of 2200 the type and the number of vertices being accessed by the shader. Since 2201 we allow multiple compilation units to form one geometry shader, it is 2202 not clear how to achieve that. Therefore, the input primitive type is a 2203 property of the program object, and not of a shader object. 2204 2205 RESOLVED: Yes, but each change means the program object will have to be 2206 re-linked. 2207 2208 6. Can the output primitive type of a geometry shader be determined 2209 at run time? 2210 2211 RESOLVED: Not in this extension. 2212 2213 7. Can the output primitive type of a program object be changed? 2214 2215 RESOLVED: Yes, but the program object will have to be re-linked in order 2216 for the change to have effect on program execution. 2217 2218 8. Must the output primitive type of a geometry shader match the 2219 input primitive type in any way? 2220 2221 RESOLVED: No, you can have a geometry shader generate points out of 2222 triangles or triangles out of points. Some combinations are analogous 2223 to existing OpenGL operations: reading triangles and writing points or 2224 line strips can be used to emulate a subset of PolygonMode 2225 functionality. Reading points and writing triangle strips can be used 2226 to emulate point sprites. 2227 2228 9. Are primitives emitted by a geometry shader processed like any other 2229 OpenGL primitive? 2230 2231 RESOLVED: Yes. Antialiasing, stippling, polygon offset, polygon mode, 2232 culling, two-sided lighting and color selection, point sprite 2233 operations, and fragment processing all work as expected. 2234 2235 One limitation is that the only output primitive types supported are 2236 points, line strips, and triangle strips, none of which meaningfully 2237 support edge flags that are sometimes used in conjunction with the POINT 2238 and LINE polygon modes. Edge flags are always ignored for line-mode 2239 triangle strips. 2240 2241 10. Should geometry shaders support additional input primitive types? 2242 2243 RESOLVED: Possibly in a future extension. It should be straightforward 2244 to build a future extension to support geometry shaders that operate on 2245 quads. Other primitive types might be more demanding on hardware. Quads 2246 with adjacency would require 12 vertices per shader execution. General 2247 polygons may require even more, since there is no fixed bound on the 2248 number of vertices in a polygon. 2249 2250 11. Should geometry shaders support additional output primitive types? 2251 2252 RESOLVED: Possibly in a future extension. Additional output types 2253 (e.g., independent lines, line loops, triangle fans, polygons) may be 2254 useful in the future; triangle fans/polygons seem particularly useful. 2255 2256 12. How are adjacency primitives processed by the GL? 2257 2258 RESOLVED: The primitive type of an adjacent primitive is set as a Begin 2259 mode parameter. Any vertex of an adjacency primitive will be treated as 2260 a regular vertex, and processed by a vertex shader as well as the 2261 geometry shader. The geometry shader cannot output adjacency primitives, 2262 thus processing stops with the geometry shader. If a geometry shader is 2263 not active, the GL ignores the "adjacent" vertices in the adjacency 2264 primitive. 2265 2266 13. Should we provide additional adjacency primitive types that can be 2267 used inside a Begin/End? 2268 2269 RESOLVED: Not in this extension. It may be desirable to add new 2270 primitive types (e.g., TRIANGLE_FAN_ADJACENCY) in a future extension. 2271 2272 14. How do geometry shaders interact with RasterPos? 2273 2274 RESOLVED: Geometry shaders are ignored when specifying the raster 2275 position. 2276 2277 15. How do geometry shaders interact with pixel primitives 2278 (DrawPixels, Bitmap)? 2279 2280 RESOLVED: They do not. 2281 2282 16. Is there a limit on the number of vertices that can be emitted by 2283 a geometry shader? 2284 2285 RESOLVED: Unfortunately, yes. Besides practical hardware limits, there 2286 may also be practical performance advantages when applications guarantee 2287 a tight upper bound on the number of vertices a geometry shader will 2288 emit. GPUs frequently excecute programs in parallel, and there are 2289 substantial implementation challenges to parallel execution of geometry 2290 threads that can write an unbounded number of results, particular given 2291 that all the primitives generated by the first geometry shader 2292 invocation must be consumed before any of the primitives generated by 2293 the second program invocation. Limiting the amount of data a geometry 2294 shader can write substantially eases the implementation burden. 2295 2296 A program object, holding a geometry shader, must declare a maximum 2297 number of vertices that can be emitted. There is an 2298 implementation-dependent limit on the total number of vertices a program 2299 object can emit (256 minimum) and the product of the number of vertices 2300 emitted and the number of components of all active varying variables 2301 (1024 minimum). 2302 2303 It would be ideal if the limit could be inferred from the instructions 2304 in the shader itself, and that would be possible for many shaders, 2305 particularly ones with straight-line flow control. For shaders with 2306 more complicated flow control (subroutines, data- dependent looping, and 2307 so on), it would be impossible to make such an inference and a "safe" 2308 limit would have to be used with adverse and possibly unexpected 2309 performance consequences. 2310 2311 The limit on the number of EmitVertex() calls that can be issued can not 2312 always be enforced at compile time, or even at Begin time. We specify 2313 that if a shader tries to emit more vertices than allowed, emits that 2314 exceed the limit may or may not have any effect. 2315 2316 17. Should it be possible to change the limit GEOMETRY_VERTICES_OUT_ARB, the 2317 number of vertices emitted by a geometry shader, after the program 2318 object, containing the shader, is linked? 2319 2320 RESOLVED: NO. See also issue 31. Changing this limit might require a 2321 re-compile and/or re-link of the shaders and program object on certain 2322 implementations. Pretending that this limit can be changed without 2323 re-linking does not reflect reality. 2324 2325 18. How do user clipping and geometry shaders interact? 2326 2327 RESOLVED: Just like vertex shaders and user clipping interact. The 2328 geometry shader needs to provide the (eye) position gl_ClipVertex. 2329 Primitives are clipped after geometry shader execution, not before. 2330 2331 19. How do edge flags interact with adjacency primitives? 2332 2333 RESOLVED: If geometry programs are disabled, adjacency primitives are 2334 still supported. For TRIANGLES_ADJACENCY_ARB, edge flags will apply as 2335 they do for TRIANGLES. Such primitives are rendered as independent 2336 triangles as though the adjacency vertices were not provided. Edge 2337 flags for the "real" vertices are supported. For all other adjacency 2338 primitive types, edge flags are irrelevant. 2339 2340 20. Now that a third shader object type is added, what combinations of 2341 GLSL, assembly (ARB or NV) low level and fixed-function do we want 2342 to support? 2343 2344 DISCUSSION: With the addition of the geometry shader, the number of 2345 combinations the GL pipeline could support doubled (there is no 2346 fixed-function geometry shading). Possible combinations now are: 2347 2348 vertex geometry fragment 2349 2350 ff/ASM/GLSL none/ASM/GLSL ff/ASM/GLSL 2351 2352 for a total of 3 x 3 x 3 is 27 combinations. Before the geometry shader 2353 was added, the number of combinations was 9, and those we need to 2354 support. We have a choice on the other 18. 2355 2356 RESOLUTION: It makes sense to draw a line at raster in the GL 2357 pipeline. The 'north' side of this line covers vertex and geometry 2358 shaders, the 'south' side fragment shaders. We now add a simple rule 2359 that states that if a program object contains anything north of this 2360 line, the north side will be 100% GLSL. This means that: 2361 2362 a) GLSL program objects with a vertex shader can only use a geometry 2363 shader and not an assembly geometry program. If an assembly geometry 2364 program is enabled, it is bypassed. This also avoids a tricky case -- a 2365 GLSL program object with a vertex and a fragment program linked 2366 together. Injecting an assembly geometry shader in the middle at run 2367 time won't work well. 2368 2369 b) GLSL program objects with a geometry shader must have a vertex shader 2370 (cannot be ARB/NV or fixed-function vertex shading). 2371 2372 The 'south' side in this program object still can be any of 2373 ff/ARB/NV/GLSL. 2374 2375 21. How do geometry shaders interact with color clamping? 2376 2377 RESOLVED: Geometry shader execution occurs prior to color clamping in 2378 the pipeline. This means the colors written by vertex shaders are not 2379 clamped to [0,1] before they are read by geometry shaders. If color 2380 clamping is enabled, any vertex colors written by the geometry shader 2381 will have their components clamped to [0,1]. 2382 2383 22. What is a primitive ID and a vertex ID? I am confused. 2384 2385 DISCUSSION: A vertex shader can read a built-in attribute that holds the 2386 ID of the current vertex it is processing. See the ARB_gpu_shader4 spec 2387 for more information on vertex ID. If the geometry shader needs access 2388 to a vertex ID as well, it can be passed as a user-defined varying 2389 variable. A geometry shader can read a built-in varying variable that 2390 holds the ID of the current primitive it is processing. It also has the 2391 ability to write to a built-in output primitive ID variable, to 2392 communicate the primitive ID to a fragment shader. A fragment shader 2393 can read a built-in attribute that holds the ID of the current primitive 2394 it is processing. A primitive ID will be generated even if no geometry 2395 shader is active. 2396 2397 23. After a call to EmitVertex(), should the values of the output varying 2398 variables be retained or be undefined? 2399 2400 DISCUSSION: There is not a clear answer to this question .The underlying 2401 HW mechanism is as follows. An array of output registers is set aside to 2402 store vertices that make up primitives. After each EmitVertex() a 2403 pointer into that array is incremented. The shader no longer has access 2404 to the previous set of values. This argues that the values of output 2405 varying variables should be undefined after an EmitVertex() call. The 2406 shader is responsible for writing values to all varying variables it 2407 wants to emit, for each emit. The counter argument to this is that this 2408 is not a nice model for GLSL to program in. The compiler can store 2409 varying outputs in a temp register and preserve their values across 2410 EmitVertex() calls, at the cost of increased register pressure. 2411 2412 RESOLUTION: For now, without being a clear winner, we've decided to go 2413 with the undefined option. The shader is responsible for writng values 2414 to all varying variabvles it wants to emit, for each emit. 2415 2416 24. How to distinguish between input and output "varying" variables? 2417 2418 DISCUSSION: Geometry shader outputs are varying variables consistent 2419 with the existing definition of varying (used to communicate to the 2420 fragment processing stage). Geometry inputs are received from a vertex 2421 shader writing to its varying variable outputs. The inputs could be 2422 called "varying", to match with the vertex shader, or could be called 2423 "attributes" to match the vertex shader inputs (which are called 2424 attributes). 2425 2426 RESOLUTION: We'll call input variables "varying", and not 2427 "attributes". To distinguish between input and output, they will be 2428 further qualified with the words "in" and "out" resulting in, for 2429 example: 2430 2431 varying in float foo; 2432 varying out vec4 bar[]; 2433 2434 25. What is the syntax for declaring varying input variables? 2435 2436 DISCUSSION: We need a way to distinguish between the vertices of the 2437 input primitive. Suggestions: 2438 2439 1. Declare each input varying variable as an unsized array. Its size 2440 is inferred by the linker based on the output primitive type. 2441 2442 2. Declare each input varying variable as a sized array. If the size 2443 does not match the output primitive type, a link error occurs. 2444 2445 3. Have an array of structures, where the structure contains the 2446 attributes for each vertex. 2447 2448 RESOLUTION: Option 1 seems simple and solves the problem, but it is not 2449 a clear winner over the other two. To aid the shader writer in figuring 2450 out the size of each array, a new built-in constant, gl_VerticesIn, is 2451 defined that holds the number of vertices for the current input 2452 primitive type. 2453 2454 26. Does gl_PointSize, gl_Layer, gl_ClipVertex count agains the 2455 MAX_GEOMETRY_VARYING_COMPONENTS limit? 2456 2457 RESOLUTION: Core OpenGL 2.0 makes a distinction between varying 2458 variables, output from a vertex shader and interpolated over a 2459 primitive, and 'special built-in variables' that are outputs, but not 2460 interpolated across a primitive. Only varying variables do count against 2461 the MAX_VERTEX_VARYING_COMPONENTS limit. gl_PointSize, gl_Layer, 2462 gl_ClipVertex and gl_Position are 'special built-in' variables, and 2463 therefore should not count against the limit. If HW does need to take 2464 components away to support those, that is ok. The actual spec language 2465 does mention possible implementation dependencies. 2466 2467 27. Should writing to gl_Position be optional? 2468 2469 DISCUSSION: Before this extensions, the OpenGL Shading Language required 2470 that gl_Position be written to in a vertex shader. With the addition of 2471 geometry shaders, it is not necessary anymore for a vertex shader to 2472 output gl_Position. The geometry shader can do so. With the addition of 2473 transform-feedback (see the transform feedback specification) it is not 2474 necessary useful for the geometry shader to write out gl_Position 2475 either. 2476 2477 RESOLUTION: Yes, this should be optional. 2478 2479 28. Should geometry shaders be able to select a layer of a 3D texture, cube 2480 map texture, or array texture at run time? If so, how? 2481 2482 RESOLVED: See also issue 32. This extension provides a per-vertex output 2483 called "gl_Layer", which is an integer specifying the layer to render 2484 to. In order to get defined results, the value of gl_Layer needs to be 2485 constant for each primitive (point, line or triangle) being emitted by a 2486 geometry shader. This layer value is used for all fragments generated by 2487 that primitive. 2488 2489 The EXT_framebuffer_object (FBO) extension is used for rendering to 2490 textures, but for cube maps and 3D textures, it only provides the 2491 ability to attach a single face or layer of such textures. 2492 2493 This extension generalizes FBO by creates new entry points to bind an 2494 entire texture level (FramebufferTextureARB) or a single layer of a 2495 texture level (FramebufferTextureLayerARB) or a single face of a level 2496 of a cube map texture (FramebufferTextureFaceARB) to an attachment 2497 point. The existing FBO binding functions, FramebufferTexture[123]DARB 2498 are retained, and are defined in terms of the more general new 2499 functions. 2500 2501 The new functions do not have a dimension in the function name or a 2502 <textarget> parameter, which can be inferred from the provided 2503 texture. 2504 2505 When an entire texel level of a cube map, 3D, or array texture is 2506 attached, that attachment is considered layered. The framebuffer is 2507 considered layered if any attachment is layered. When the framebuffer 2508 is layered, there are three additional completeness requirements: 2509 2510 * all attachments must be layered 2511 * all color attachments must be from textures of identical type 2512 * all attachments must have the same number of layers 2513 2514 We expect subsequent versions of the FBO spec to relax the requirement 2515 that all attachments must have the same width and height, and plan to 2516 relax the similar requirement for layer count at that time. 2517 2518 When rendering to a layered framebuffer, layer zero is used unless a 2519 geometry shader that writes (statically assings, to be precise) to 2520 gl_Layer. When rendering to a non-layered framebuffer, the value of 2521 gl_Layer is ignored and the set of single-image attachments are used. 2522 When reading from a layered framebuffer (e.g., ReadPixels), layer zero 2523 is always used. When clearing a layered framebuffer, all layers are 2524 cleared to the corresponding clear values. 2525 2526 Several other approaches were considered, including leveraging existing 2527 FBO attachment functions and requiring the use of FramebufferTexture3D 2528 with a <zoffset> of zero to make a framebuffer attachment "layerable" 2529 (attaching layer zero means that the attachment could be used for either 2530 layered- or non- layered rendering). Whether rendering was layered or 2531 not could either be inferred from the active geometry shader, or set as 2532 a new property of the framebuffer object. There is presently no 2533 FramebufferParameter API to set a property of a framebuffer, so it would 2534 have been necessary to create new set/query APIs if this approach were 2535 chosen. 2536 2537 29. How should per-vertex point size work with geometry shaders? 2538 2539 RESOLVED: The value of the existing VERTEX_PROGRAM_POINT_SIZE enable, to 2540 control the point size behavior of a vertex shader, does not affect 2541 geometry shaders. Specifically, If a geometry shader is active, the 2542 point size is taken from the point size output gl_PointSize of the 2543 vertex shader, regardless of the value of VERTEX_PROGRAM_POINT_SIZE. 2544 2545 30. Geometry shaders don't provide a QUADS or generic POLYGON input 2546 primitive type. In this extension, what happens if an application 2547 provides QUADS, QUAD_STRIP, or POLYGON primitives? 2548 2549 RESOLVED: Not all vendors supporting this extension were able to accept 2550 quads and polygon primitives as input, so such functionality was not 2551 provided in this extension. This extension requires that primitives 2552 provided to the GL must match the input primitive type of the active 2553 geometry shader (if any). QUADS, QUAD_STRIP, and POLYGON primitives are 2554 considered not to match any input primitive type, so an 2555 INVALID_OPERATION error will result. 2556 2557 The NV_geometry_shader4 extension (built on top of this one) allows 2558 applications to provide quads or general polygon primitives to a 2559 geometry shader with an input primitive type of TRIANGLES. Such 2560 primitives are decomposed into triangles, and a geometry shader is run 2561 on each triangle independently. 2562 2563 31. Geometry shaders provide a limit on the number of vertices that can be 2564 emitted. Can this limit be changed at dynamically? 2565 2566 RESOLVED: See also issue 17. Not in this extension. This functionality 2567 was not provided because it would be an expensive operation on some 2568 implementations of this extension. The NV_geometry_shader4 extension 2569 (layered on top of this one) does allow applications to change this 2570 limit dynamically. 2571 2572 An application can change the vertex output limit at any time. To allow 2573 for the possibility of dynamic changes (as in NV_geometry_shader4) but 2574 not require it, a limit change is not guaranteed to take effect unless 2575 the program object is re-linked. However, there is no guarantee that 2576 such limit changes will not take effect immediately. 2577 2578 32. See also issue 28. Each vertex emitted by a geometry shader can specify 2579 a layer to render to using the output variable "gl_Layer". For 2580 LINE_STRIP and TRIANGLE_STRIP output primitive types, which vertex's 2581 layer is used? 2582 2583 RESOLVED: The vertex from which the layer is extracted is unfortunately 2584 undefined. In practice, some implementations of this extension will 2585 extract the layer number from the first vertex of the output primitive; 2586 others will extract it from the last (provoking) vertex. A future 2587 geometry shader extension may choose to define this behavior one way or 2588 the other. 2589 2590 To get portable results, the layer number should be the same for all 2591 vertices in any single primitive emitted by the geometry shader. The 2592 EndPrimitive() built-in function available in a geometry shader starts a 2593 new primitive, and the layer number emitted can be safely changed after 2594 EndPrimitive() is called. 2595 2596 33. The grammar allows "varying", "varying out", and "varying in" as 2597 type-qualifiers for geometry shaders. What does "varying" without "in" 2598 or "out" mean for a geometry shader? 2599 2600 RESOLVED: The "varying" type qualifier in a geometry shader not 2601 followed by "in" or "out" means the same as "varying out". 2602 2603 This is consistent with the specification saying: "In order to seamlessly 2604 be able to insert or remove a geometry shader from a program object, 2605 the rules, names and types of the output built-in varying variables and 2606 user-defined varying variables are the same as for the vertex shader." 2607 2608 34. What happens if you try to do a framebuffer blit (EXT_framebuffer_blit) 2609 to/from a layered framebuffer? 2610 2611 RESOLVED: BlitFramebufferEXT() is a two-dimensional operation (only has 2612 a width and height), so only reads/writes layer zero. The framebuffer 2613 blit operation is defined partially in terms of CopyPixels, which itself 2614 is defined in terms of ReadPixels and DrawPixels. This spec defines 2615 both operations to use layer zero when a layered framebuffer is 2616 involved. 2617 2618 It may be desirable to provide a three-dimensional framebuffer blit 2619 operation or an explicit copy single-step operation between two 2620 three-dimensional, cube map, or array textures. That functionality is 2621 left for a future extension or OpenGL version. 2622 2623 35. Why are the MAX_VARYING_COMPONENTS and FRAMEBUFFER_ATTACHMENT_TEXTURE_LAYER 2624 tokens un-suffixed? 2625 2626 PROPOSED: Both of these tokens are provided in un-suffixed form in 2627 OpenGL 3.0, which was released simultaneously with 2628 ARB_geometry_shader4, and are not going to change their meaning 2629 when this extension is promoted to a future core release since 2630 their meaning is already defined by both 3.0 and this extension 2631 to be the same 2632 2633Revision History 2634 2635 Rev. Date Author Changes 2636 ---- -------- -------- ----------------------------------------- 2637 26 01/21/11 pbrown Add language describing MAX_COMBINED_ 2638 GEOMETRY_UNIFORM_COMPONENTS from an interaction 2639 with ARB_uniform_buffer_object (bug 7027). 2640 2641 25 12/21/09 jjones Add GLX protocol. 2642 2643 24 07/21/09 pbrown Clarify that when doing layered rendering, 2644 a layer specified in the shader is used to 2645 select the depth and stencil layers accessed. 2646 2647 23 06/30/09 pbrown Add interaction with OpenGL 3.2. 2648 2649 22 08/07/08 jleech Strip ARB suffix from a few tokens already 2650 in OpenGL 3.0 (see issue 35). 2651 2652 21 07/09/08 jsandmel last edit accidentally added dependencies 2653 on ARB_framebuffer_object. as per working 2654 group meeting 7/11, this was unintentional, so 2655 it's now been reverted back to a dependency on 2656 EXT_framebuffer_object 2657 2658 20 07/09/08 jsandmel converted to ARB. no functional changes. 2659 2660 2661 19 04/04/08 pbrown Changed MAX_GEOMETRY_TEXTURE_IMAGE_UNITS_ARB 2662 minimum value to zero, to match discussion (from 2663 aeddy). Added separators to group pictures and 2664 discussions of each of the new primitive types 2665 together. 2666 2667 18 03/15/08 pbrown Additional dependency on EXT_framebuffer_blit; 2668 blits to/from layered targets affect only 2669 layer zero. 2670 2671 17 05/22/07 mjk Clarify that "varying" means the same as 2672 "varying out" in a geometry shader. 2673 2674 16 01/10/07 pbrown Specify that the total component limit is 2675 enforced at LinkProgram time. 2676 2677 15 12/15/06 pbrown Documented that the '#extension' token 2678 for this extension should begin with "GL_", 2679 as apparently called for per convention. 2680 2681 14 -- Pre-release revisions. 2682