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