1Name 2 3 ARB_shader_viewport_layer_array 4 5Name Strings 6 7 GL_ARB_shader_viewport_layer_array 8 9Contact 10 11 Graham Sellers, AMD (graham.sellers 'at' amd.com) 12 13Contributors 14 15 Graham Sellers 16 17Notice 18 19 Copyright (c) 2015 The Khronos Group Inc. Copyright terms at 20 http://www.khronos.org/registry/speccopyright.html 21 22Specification Update Policy 23 24 Khronos-approved extension specifications are updated in response to 25 issues and bugs prioritized by the Khronos OpenGL Working Group. For 26 extensions which have been promoted to a core Specification, fixes will 27 first appear in the latest version of that core Specification, and will 28 eventually be backported to the extension document. This policy is 29 described in more detail at 30 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 31 32Status 33 34 Complete. Approved by the ARB on June 26, 2015. 35 Ratified by the Khronos Board of Promoters on August 7, 2015. 36 37Version 38 39 Last Modified Date: February 12, 2019 40 Revision: 2 41 42Number 43 44 ARB Extension #185 45 46Dependencies 47 48 OpenGL 4.1 is required. 49 50 The extension is written against the OpenGL 4.5 Specification, Core Profile, 51 February 2, 2015 and the OpenGL Shading Language Specification, 52 version 4.50.5. 53 54Overview 55 56 The gl_ViewportIndex and gl_Layer built-in variables were introduced by 57 the in OpenGL 4.1. These variables are available in un-extended OpenGL 58 only to the geometry shader. When written in the geometry shader, they 59 cause geometry to be directed to one of an array of several independent 60 viewport rectangles or framebuffer attachment layers, respectively. 61 62 In order to use any viewport or attachment layer other than zero, a 63 geometry shader must be present. Geometry shaders introduce processing 64 overhead and potential performance issues. The AMD_vertex_shader_layer 65 and AMD_vertex_shader_viewport_index extensions allowed the gl_Layer 66 and gl_ViewportIndex outputs to be written directly from the vertex shader 67 with no geometry shader present. 68 69 This extension effectively merges the AMD_vertex_shader_layer and 70 AMD_vertex_shader_viewport_index extensions together and extends them further 71 to allow both outputs to be written from tessellation evaluation shaders. 72 73New Procedures and Functions 74 75 None. 76 77New Tokens 78 79 None. 80 81Additions to Chapter 9 of the OpenGL 4.5 (Core) Specification (Framebuffers 82and Framebuffer Objects) 83 84 Modify section 9.8, "Layered Framebuffers" as follows: 85 86 Remove the bullet list explaining when layer number zero is used 87 and replace the language with: 88 89 The layer number of a fragment is zero if no vertex processing shader 90 (vertex, tessellation evaluation or geometry) statically assigns a value 91 to the built-in output gl_Layer. 92 93 Replace the following paragraph with: 94 95 Otherwise, the layer for each point, line, or triangle is taken from 96 the gl_Layer output of the last active vertex processing stage to one of 97 the vertices of the primitive. The vertex used is implementation-dependent. 98 To get defined results, all vertices of each primitive should set the same 99 value for gl_Layer. The layer number written by a vertex procesing shader 100 has no effect if the framebuffer is not layered. 101 102Additions to Chapter 11 of the OpenGL 4.5 (Core) Specification (Programmable 103Vertex Processing) 104 105 Add the following to Subsection 11.1.3.10, "Shader Outputs" 106 107 The built-in output gl_Layer is used in layered rendering, and is 108 discussed further in the next section. 109 The built-in output gl_ViewportIndex is used to direct rendering 110 to one of several viewports and is discussed further in the next section. 111 112 Move Subsection 11.3.4.6, "Layer and Viewport Selection" into a new section 113 11.4, "Layer and Viewport Selection", renumber surrounding sections 114 appropriately. 115 116 Replace all instances of "Geometry shaders" in Section 11.4 with 117 "Vertex, tessellation and geometry shaders". 118 119Additions to Chapter 13 of the OpenGL 4.5 (Core) Specification (Fixed-Function 120Vertex Post-Processing) 121 122 Modify section 13.6.1 "Controlling the Viewport" as follows: 123 124 Replace the paragraph beginning "Multiple viewports are available ..." 125 with: 126 127 Multiple viewports are available and are numbered zero through the value 128 of MAX_VIEWPORTS minus one. If an active vertex processing shader is active and 129 writes to gl_ViewportIndex, the viewport transformation uses the viewport 130 corresponding to the value assigned to gl_ViewportIndex taken from an 131 implementation-dependent primitive vertex. If the value of the viewport 132 index is outside the range zero to the value of MAX_VIEWPORTS minus one, 133 the results of the viewport transformation are undefined. If the active 134 vertex, tessellation or geometry shaders (if present) do not write to 135 gl_ViewportIndex, the viewport numbered zero is used by the viewport 136 transformation. 137 138 139Modifications to the OpenGL Shading Language Specification, Version 4.50 140 141 Including the following line in a shader can be used to control the 142 language features described in this extension: 143 144 #extension GL_ARB_shader_viewport_layer_array : <behavior> 145 146 where <behavior> is as specified in section 3.3. 147 148 New preprocessor #defines are added to the OpenGL Shading Language: 149 150 #define GL_ARB_shader_viewport_layer_array 1 151 152 Modify Section 7.1 (Built-In Language Variables), p. 122 153 154 Add to the list of vertex shader built-ins: 155 156 out gl_PerVertex { 157 ... 158 int gl_ViewportIndex; 159 int gl_Layer; 160 }; 161 162 Add to the list of tessellation evaluation shader built-ins: 163 164 out gl_PerVertex { 165 ... 166 int gl_ViewportIndex; 167 int gl_Layer; 168 }; 169 170 Modify the language introducing "gl_Layer" on p.127 as follows: 171 172 The variable gl_Layer is available as an output variable in the vertex, 173 tessellation evaluation, and geometry (VTG) languages and an input 174 variable in the fragment language. In the VTG languages, it is used to 175 select a specific layer (or face and layer of a cube map) of a 176 multi-layer framebuffer attachment. The actual layer used will come 177 from one of the vertices in the primitive being shaded. Which vertex 178 the layer comes from is discussed in section 11.4 "Layer and 179 Viewport Selection" of the OpenGL Specification. It might be undefined, 180 so it is best to write the same layer value for all vertices of a 181 primitive. If a shader statically assigns a value to gl_Layer, layered 182 rendering mode is enabled. See section 11.3.4.5 "Geometry Shader 183 Outputs" and section 9.4.9 "Layered Framebuffers" of the OpenGL 184 Graphics System Specification for more information. If a shader 185 statically assigns a value to gl_Layer, and there is an execution path 186 through the shader that does not set gl_Layer, then the value of 187 gl_Layer is undefined for executions of the shader that take that path. 188 189 ... 190 191 The input variable gl_Layer in the fragment language will have the same 192 value that was written to the output variable gl_Layer in the VTG 193 languages. If the final VTG stage does not dynamically assign a value to 194 gl_Layer, the value of gl_Layer in the fragment stage will be undefined. 195 If the final VTG stage makes no static assignment to gl_Layer, the input 196 gl_Value in the fragment stage will be zero. Otherwise, the fragment stage 197 will read the same value written by the final VTG stage, even if that value 198 is out of range. If a fragment shader contains a static access to gl_Layer, 199 it will count against the implementation defined limit for the maximum 200 number of inputs to the fragment stage. 201 202 Modify the language introducing "gl_ViewportIndex" on p.128 as follows: 203 204 The variable gl_ViewportIndex is available as an output variable in the 205 VTG languages and an input variable in the fragment language. In the 206 geometry language, it provides the index of the viewport to which the next 207 primitive emitted from the geometry shader should be drawn. In the vertex 208 and tessellation evaluation languages, it provides the index of the viewport 209 associated with the vertex being shaded. Primitives will undergo viewport 210 transformation and scissor testing using the viewport transformation and 211 scissor rectangle selected by the value of gl_ViewportIndex. The viewport 212 index used will come from one of the vertices in the primitive being 213 shaded. However, which vertex the viewport index comes from is 214 implementation-dependent, so it is best to use the same viewport index for 215 all vertices of the primitive. If the final VTG stage does not assign a 216 value to gl_ViewportIndex, viewport transform and 217 scissor rectangle zero will be used. If a shader statically assigns a value 218 to gl_ViewportIndex and there is a path through the shader that does not 219 assign a value to gl_ViewportIndex, the value of gl_ViewportIndex is 220 undefined for executions of the shader that take that path. See section 221 11.4 "Layer and Viewport Selection" of the OpenGL Graphics System 222 Specification for more information. 223 224 The input variable gl_ViewportIndex in the fragment stage will have the 225 same value that was written to the output variable gl_ViewportIndex in the 226 final VTG stage. If the final VTG stage does not dynamically assign to 227 gl_ViewportIndex, the value of gl_ViewportIndex in the fragment shader will 228 be undefined. If the final VTG stage makes no static assignment to 229 gl_ViewportIndex, the fragment stage will read zero. Otherwise, the 230 fragment stage will read the same value written by the final VTG stage, 231 even if that value is out of range. If a fragment shader contains a static 232 access to gl_ViewportIndex, it will count against the implementation 233 defined limit for the maximum number of inputs to the fragment stage. 234 235Additions to the AGL/GLX/WGL Specifications 236 237 None. 238 239GLX Protocol 240 241 None. 242 243Errors 244 245 None. 246 247New State 248 249 None. 250 251New Implementation Dependent State 252 253 None. 254 255Issues 256 257 1) Do we want to allow writes to these built-in variables from tessellation 258 shaders? 259 260 RESOLVED: Yes, this is allowed in tessellation evaluation shaders. Note that 261 it is not possible to write either variable in the tessellation control shader. 262 263 2) What happens if gl_ViewportIndex or gl_Layer is written in the vertex 264 shader and a geometry shader is present? 265 266 RESOLVED: The value written by the last vertex processing stage is used. 267 If the last vertex processing stage (vertex, tessellation evaluation or 268 geometry) does not statically assign to gl_ViewportIndex or gl_Layer, 269 index or layer zero is assumed. 270 271 3) Are provoking vertex semantics honored for the purposes of writes to 272 gl_ViewportIndex in the VS? 273 274 RESOLVED: Yes, they are. Query VIEWPORT_INDEX_PROVOKING_VERTEX to determine 275 the 'provokingness' of gl_ViewportIndex. In general, though, it's best 276 practice to ensure that all vertices of a single primitive (including 277 strips, fans and loops) have the same value for gl_ViewportIndex. 278 279 4) Do we want gl_ViewportIndexIn or gl_LayerIn inputs to shaders to allow 280 automatic passing of these variables along the pipe? 281 282 DISCUSSION: Rather not. This is just emualating things that the application 283 could and should do itself. Pushing built-ins down the pipe that aren't consuming 284 dedicated hardware resources just complicates things like counting rules and 285 ultimately ends up pretty inefficient. 286 287 5) Are the gl_ViewportIndex and gl_Layer builtins part of the "out gl_PerVertex" 288 block or not? 289 290 RESOLVED: The initial version of this extension didn't specify and many 291 implementations treated them as loose variables (or didn't care). However, 292 the spec language makes it quite clear that there is an instance of these 293 variables and a shader is expected to write the same value for each 294 vertex. 295 In practise, unless an application is trying to redeclare these variables 296 it isn't really possible to tell where they are declared. 297 298Revision History 299 300 Rev. Date Author Changes 301 ---- -------- -------- ----------------------------------------- 302 303 1 03/19/2015 gsellers Initial version merging AMD_vertex_shader_viewport_index 304 and AMD_vertex_shader_layer 305 2 02/12/2019 dkoch opengl/api/44: clarify that builtins should be 306 part of the "out gl_PerVertex" block. 307