1Name
2
3    ARB_fragment_layer_viewport
4
5Name Strings
6
7    GL_ARB_fragment_layer_viewport
8
9Contact
10
11    Piers Daniell, NVIDIA Corporation (pdaniell 'at' nvidia.com)
12
13Contributors
14
15    Christophe Riccio, AMD
16    Daniel Koch, Transgaming
17    John Kessenich
18    Pat Brown, NVIDIA
19
20Notice
21
22    Copyright (c) 2012-2014 The Khronos Group Inc. Copyright terms at
23        http://www.khronos.org/registry/speccopyright.html
24
25Specification Update Policy
26
27    Khronos-approved extension specifications are updated in response to
28    issues and bugs prioritized by the Khronos OpenGL Working Group. For
29    extensions which have been promoted to a core Specification, fixes will
30    first appear in the latest version of that core Specification, and will
31    eventually be backported to the extension document. This policy is
32    described in more detail at
33        https://www.khronos.org/registry/OpenGL/docs/update_policy.php
34
35Status
36
37    Complete. 
38    Approved by the ARB on 2012/06/18.
39    Ratified by the Khronos Board of Promoters on 2012/07/27.
40
41Version
42
43    Last Modified Date:         January 28, 2014
44    Revision:                   5
45
46Number
47
48    ARB Extension #129
49
50Dependencies
51
52    OpenGL 3.0 and ARB_geometry_shader4, or OpenGL 3.2 is required.
53
54    ARB_viewport_array is required.
55    
56    This extension is written against The OpenGL Shading Language 4.20.11
57    Specification.
58
59    This extension interacts with NV_gpu_program4.
60
61Overview
62
63    The geometry shader has the special built-in variables gl_Layer and
64    gl_ViewportIndex that specify which layer and viewport primitives
65    are rendered to. Currently the fragment shader does not know which
66    layer or viewport the fragments are being written to without the
67    application implementing their own interface variables between
68    the geometry and fragment shaders.
69    
70    This extension specifies that the gl_Layer and gl_ViewportIndex
71    built-in variables are also available to the fragment shader so the
72    application doesn't need to implement these manually.
73
74New Procedures and Functions
75
76    None
77
78New Tokens
79
80    None
81
82Additions to Chapter 7 of the OpenGL Shading Language 4.20.11 Specification
83(Built-In Variables)
84
85    "Including the following line in a shader will enable the language
86    features described in this extension:
87
88        #extension GL_ARB_fragment_layer_viewport : <behavior>
89
90    where <behavior> is as specified in section 3.3 for the #extension
91    directive."
92
93    A new preprocessor macro is added to the OpenGL Shading Language:
94
95      #define GL_ARB_fragment_layer_viewport    1
96
97    Add to the section labelled "In the fragment language, built-in variables
98    are intrinsically declared as:" on page 99:
99    
100   "in int gl_Layer;
101    in int gl_ViewportIndex;"
102    
103    Modify the first paragraph describing gl_Layer start on the bottom of page
104    100 as follows:
105    
106   "The variable gl_Layer is available as an output variable in the geometry
107    shader and an input variable in the fragment shader. In the geometry
108    shader it is used to select a specific layer (or face and layer of a cube
109    map) of a multi-layer framebuffer attachment. The actual layer used will
110    come from ..."
111    
112    Add the following paragraph to the end of the section describing gl_Layer
113    on page 101 as follows:
114    
115   "The input variable gl_Layer in the fragment language will have the same 
116    value that was written to the output variable gl_Layer in the geometry 
117    language. If the geometry stage does not dynamically assign a value to 
118    gl_Layer, the value of gl_Layer in the fragment stage will be undefined.  
119    If the geometry stage makes no static assignment to gl_Layer, the input 
120    gl_Layer in the fragment stage will be zero.  Otherwise, the fragment 
121    stage will read the same value written by the geometry stage, even if 
122    that value is out of range.  If a fragment shader contains a static 
123    access to gl_Layer, it will count against the implementation defined 
124    limit for the maximum number of inputs to the fragment stage."
125    
126    Modify the fourth paragraph on page 101 which begins the description of
127    gl_ViewportIndex:
128    
129   "The variable gl_ViewportIndex is available as an output variable in the
130    geometry shader and an input variable in the fragment shader. In the
131    geometry shader it provides the index of the viewport to which the next
132    primitive emitted from the geometry shader should be drawn. ..."
133   
134    After this paragraph add the following new paragraph:
135    
136   "The input variable gl_ViewportIndex in the fragment stage will have the 
137    same value that was written to the output variable gl_ViewportIndex in 
138    the geometry stage.  If the geometry stage does not dynamically assign 
139    to gl_ViewportIndex, the value of gl_ViewportIndex in the fragment shader 
140    will be undefined. If the geometry stage makes no static assignment to 
141    gl_ViewportIndex, the fragment stage will read zero. Otherwise, the 
142    fragment stage will read the same value written by the geometry stage, 
143    even if that value is out of range. If a fragment shader contains a static 
144    access to gl_ViewportIndex, it will count against the implementation 
145    defined limit for the maximum number of inputs to the fragment stage."
146
147Additions to the AGL/GLX/WGL Specifications
148
149    None
150
151Dependencies on NV_gpu_program4
152
153    If NV_gpu_program4 is supported, the following edits are made to extend
154    the assembly programming model documented in the NV_gpu_program4
155    extension.  Note that the "result.viewport" geometry shader output
156    requires the use of the "ARB_viewport_array" program option, as documented
157    in the ARB_viewport_array specification.
158
159    (Modify the additions to "Section 2.X.3.2, Program Attribute Variables"
160    from the NV_fragment_program4 extension)
161
162      Fragment Attribute Binding  Components  Underlying State
163      --------------------------  ----------  ----------------------------
164      fragment.layer              (l,-,-,-)   primitive layer
165      fragment.viewport           (v,-,-,-)   primitive viewport index
166
167    If a fragment attribute binding matches "fragment.layer", the "x"
168    component of the fragment attribute variable is filled with a single
169    integer.  If a geometry program is active and includes an instruction
170    writing to the "result.layer" output, this value is obtained by taking the
171    layer value emitted by the geometry program for the provoking vertex.
172    Otherwise, the value zero will be used.  The "y", "z", and "w" components
173    of the variable are always undefined.
174
175    If a fragment attribute binding matches "fragment.viewport", the "x"
176    component of the fragment attribute variable is filled with a single
177    integer.  If a geometry program is active and includes an instruction
178    writing to the "result.viewport" output, this value is obtained by taking
179    the viewport index value emitted by the geometry program for the provoking
180    vertex.  Otherwise, the value zero will be used.  The "y", "z", and "w"
181    components of the variable are always undefined.
182
183    (Add to "Section 2.X.6, Program Options" of the NV_gpu_program4 extension)
184
185    + Fragment Layer and Viewport Index Inputs (ARB_fragment_layer_viewport)
186
187    If a fragment program specifies the "ARB_fragment_layer_viewport" option,
188    it may use the "fragment.layer" and "fragment.viewport" bindings.  If this
189    option is not specified, a program will fail to load if it uses those
190    bindings.
191
192
193Errors
194
195    None
196
197New State
198
199    None
200
201New Implementation Dependent State
202
203    None
204
205Issues
206
207    None
208
209Revision History
210
211    Rev.    Date    Author    Changes
212    ----  --------  --------  -----------------------------------------------
213    5     01/28/14  Ian R     Fix dependencies.  s/gl_Value/gl_Layer/.  Add
214                              GLSL define for GL_ARB_fragment_layer_viewport.
215    4     06/05/12  johnk     Improve distinctions between stage and shader and
216                              make it be any static access that triggers the 
217                              count against number of inputs to the fragment stage.
218    3     05/31/12  pdaniell  Update language for unassigned and out-of-range
219                              behavior for gl_Layer and gl_ViewportIndex.
220    2     05/25/12  pbrown    Add interaction with NV_gpu_program4, providing
221                              assembly program support for these inputs.
222    1     05/14/12  pdaniell  Initial version.
223