• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    NV_sample_mask_override_coverage
4
5Name Strings
6
7    GL_NV_sample_mask_override_coverage
8
9Contact
10
11    Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com)
12
13Contributors
14
15    Jeff Bolz, NVIDIA
16    James Helferty, NVIDIA
17
18Status
19
20    Shipping
21
22Version
23
24    Last Modified Date:         March 27, 2015
25    Revision:                   2
26
27Number
28
29    OpenGL Extension #473
30    OpenGL ES Extension #236
31
32Dependencies
33
34    This extension is written against the OpenGL 4.3 specification
35    (Compatibility Profile).
36
37    This extension is written against version 4.30 of the OpenGL
38    Shading Language Specification.
39
40    This extension interacts with NV_framebuffer_mixed_samples.
41
42    This extension interacts with NV_fragment_program4.
43
44    This extension interacts with the OpenGL ES 3.0 and 3.1 specifications.
45
46    If implemented in OpenGL ES 3.0 or 3.1, OES_sample_variables is required.
47
48Overview
49
50    This extension allows the fragment shader to control whether the
51    gl_SampleMask output can enable samples that were not covered by the
52    original primitive, or that failed the early depth/stencil tests.
53    This can be enabled by redeclaring the gl_SampleMask output with the
54    "override_coverage" layout qualifier:
55
56        layout(override_coverage) out int gl_SampleMask[];
57
58New Procedures and Functions
59
60    None.
61
62New Tokens
63
64    None.
65
66Additions to Chapter 15 of the OpenGL 4.3 (Compatibility Profile) Specification
67(Rasterization)
68
69    Modify Section 15.2.3 Shader Outputs, p. 514
70
71    (replace the paragraph describing gl_SampleMask)
72
73    The built-in integer array gl_SampleMask can be used to change the sample
74    coverage for a fragment from within the shader. The number of elements in
75    the array is:
76
77        ceil(s/32)
78
79    where <s> is the maximum number of color samples supported by the
80    implementation. If bit <n> of element <w> in the array is set to zero,
81    sample <w>*32+<n> should be considered uncovered for the purposes of
82    multisample fragment operations (see section 17.3.3). Modifying the sample
83    mask in this way may exclude covered samples from being processed further
84    at a per-fragment granularity. If bit <n> of element <w> in the array is
85    set to one and gl_SampleMask is declared with the "override_coverage"
86    layout qualifier, then sample <w>*32+<n> should be considered covered for
87    the purposes of multisample fragment operations, even if it was not covered
88    by the original primitive or failed early fragment tests. If a bit is set
89    to one and gl_SampleMask was not declared with the "override_coverage"
90    layout qualifier, then that sample is considered covered only if it was
91    covered by the original primitive and was not discarded by early fragment
92    tests. If the fragment shader is being evaluated at any frequency other
93    than per-fragment, bits of the sample mask not corresponding to the current
94    fragment shader invocation are ignored.
95
96    Modify Section 17.3.3 Multisample Fragment Operations, p. 534
97
98    (move gl_SampleMask description before SAMPLE_ALPHA_TO_COVERAGE, and
99    replace with the following)
100
101    If a fragment shader is active and statically assigns to the built-in
102    output variable gl_SampleMask, the fragment coverage is modified in a way
103    that depends on the "override_coverage" layout qualifier. If gl_SampleMask
104    is qualified with "override_coverage", the fragment coverage is replaced
105    with the sample mask. If gl_SampleMask is not qualified with
106    "override_coverage", the fragment coverage is ANDed with the bits of the
107    sample mask. If such a fragment shader did not assign a value to
108    gl_SampleMask due to flow control, the value ANDed with the fragment
109    coverage or replacing the fragment coverage is undefined. If no fragment
110    shader is active, or if the active fragment shader does not statically
111    assign values to gl_SampleMask, the fragment coverage is not modified.
112
113New Implementation Dependent State
114
115    None.
116
117New State
118
119    None.
120
121Additions to the AGL/GLX/WGL Specifications
122
123    None.
124
125GLX Protocol
126
127    None.
128
129Modifications to the OpenGL Shading Language Specification, Version 4.30
130
131
132    Including the following line in a shader can be used to control the
133    language features described in this extension:
134
135      #extension GL_NV_sample_mask_override_coverage : <behavior>
136
137    where <behavior> is as specified in section 3.3.
138
139    New preprocessor #defines are added to the OpenGL Shading Language:
140
141      #define GL_NV_sample_mask_override_coverage               1
142
143
144    Modify Section 4.4.2.3 Fragment Shader Outputs (p. 64)
145
146    (add to the end of the section)
147
148    The built-in fragment shader variable gl_SampleMask may be redeclared using
149    the layout qualifier "override_coverage":
150
151    layout-qualifier-id
152        override_coverage
153
154    For example:
155
156        layout(override_coverage) out int gl_SampleMask[];
157
158    The effect of this qualifier is defined in Section 7.1 (Built-in Variables)
159    and Section 15.2.3 of the OpenGL Specification.
160
161
162    Modify Section 7.1 (Built-in Variables), p. 110
163
164    (replace the description of gl_SampleMask on p. 118)
165
166    The output array gl_SampleMask[] sets the sample mask for the fragment
167    being processed. If gl_SampleMask is not declared with the
168    "override_coverage" layout qualifier, coverage for the current fragment
169    will become the logical AND of the coverage mask and the output
170    gl_SampleMask. If gl_SampleMask is declared with the "override_coverage"
171    layout qualifier, coverage for the current fragment will be replaced by
172    the output gl_SampleMask. This array must be sized in the fragment shader
173    either implicitly or explicitly to be the same size described above. If the
174    fragment shader statically assigns a value to gl_SampleMask, the sample
175    mask will be undefined for any array elements of any fragment shader
176    invocations that fail to assign a value. If a shader does not statically
177    assign a value to gl_SampleMask, the sample mask has no effect on the
178    processing of a fragment.
179
180
181Dependencies on NV_framebuffer_mixed_samples
182
183    If NV_framebuffer_mixed_samples is supported, the definition of
184    gl_SampleMask should say "maximum number of color or raster samples
185    supported...".
186
187
188Dependencies on NV_fragment_program4
189
190    Modify Section 2.X.6.Y of the NV_fragment_program4 specification
191
192    (add new option section)
193
194    + Sample Mask Override Coverage (NV_sample_mask_override_coverage)
195
196    If a fragment program specifies the "NV_sample_mask_override_coverage"
197    option, the sample mask may enable coverage for samples not covered by the
198    original primitive, or those that failed early fragment tests, as described
199    in Section 15.2.3 Shader Outputs.
200
201
202Interactions with OpenGL ES 3.0 and 3.1
203
204    Modify paragraph 2 of Shader Outputs from "where <s> is the maximum number
205    of color samples supported by the implementation" to "where <s> is the
206    value of MAX_SAMPLES, the maximum number of..."
207
208    Remove any references to implicit sizing of the gl_SampleMask array, and
209    modify the example for "Fragment Shader Outputs" to have an explicit array
210    size:
211
212        layout(override_coverage) out int gl_SampleMask[(gl_MaxSamples+31)/32];
213
214    Modify OpenGL ES Shading Language 3.00 Specification, section 3.8
215    "Identifiers:"
216
217        Replace the second paragraph with the following:
218
219        Identifiers starting with "gl_" are reserved for use by OpenGL ES, and
220        may not be declared in a shader as either a variable or a function;
221        this results in a compile-time error. However, as noted in the
222        specification, there are some cases where previously declared variables
223        can be redeclared, and predeclared "gl_" names are allowed to be
224        redeclared in a shader only for these specific purposes. More
225        generally, it is a compile-time error to redeclare a variable,
226        including those starting "gl_".
227
228Errors
229
230    None.
231
232Issues
233
234    (1) How does this extension differ from NV_conservative_raster?
235
236    RESOLVED: NV_conservative_raster will generate a fragment for any pixel
237    that intersects the primitive, even if no samples are covered, and all
238    pixels will initially be treated as fully covered. When using this
239    extension without conservative raster, fragments will only be generated
240    if at least one sample is covered by the primitive, but the shader may
241    turn on other samples in the same pixel.
242
243    (2) How does this extension interact with per-sample shading (via
244    GL_SAMPLE_SHADING/glSampleShading() or attributes declared with the
245    "sample" interpolation qualifier)?
246
247    RESOLVED: Sample shading effectively runs multiple shading passes on each
248    fragment. Each of these passes may only override the coverage for samples
249    owned by that pass, other bits in the sample mask are ignored.
250
251    (3) For OpenGL ES, should we allow implicit sizing of the gl_SampleMask
252    array when it's redeclared?
253
254    RESOLVED: No. OpenGL ES convention is to explicitly size arrays. See issues
255    4 and 5 of OES_sample_variables.
256
257Revision History
258
259    Revision 2, 2015/03/27
260      - Add ES interactions
261
262    Revision 1
263      - Internal revisions.
264