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