| Name |
| |
| OES_sample_variables |
| |
| Name Strings |
| |
| GL_OES_sample_variables |
| |
| Contact |
| |
| Daniel Koch, NVIDIA Corporation (dkoch 'at' nvidia.com) |
| |
| Contributors |
| |
| Pat Brown, NVIDIA |
| Eric Werness, NVIDIA |
| Graeme Leese, Broadcom |
| Contributors to ARB_gpu_shader5 |
| Contributors to ARB_sample_shading |
| Members of the OpenGL ES Working Group |
| |
| Notice |
| |
| Copyright (c) 2011-2019 The Khronos Group Inc. Copyright terms at |
| http://www.khronos.org/registry/speccopyright.html |
| |
| Specification Update Policy |
| |
| Khronos-approved extension specifications are updated in response to |
| issues and bugs prioritized by the Khronos OpenGL ES Working Group. For |
| extensions which have been promoted to a core Specification, fixes will |
| first appear in the latest version of that core Specification, and will |
| eventually be backported to the extension document. This policy is |
| described in more detail at |
| https://www.khronos.org/registry/OpenGL/docs/update_policy.php |
| |
| Status |
| |
| Complete. |
| Ratified by the Khronos Board of Promoters on 2014/03/14. |
| |
| Version |
| |
| Last Modified Date: January 10, 2019 |
| Revision: 10 |
| |
| Number |
| |
| OpenGL ES Extension #170 |
| |
| Dependencies |
| |
| OpenGL ES 3.0 and GLSL ES 3.00 required. |
| |
| This extension is written against the OpenGL ES 3.0.2 (April 8, 2013) |
| and the OpenGL ES Shading Language Specification Revision 4 |
| (March 6, 2013) specifications. |
| |
| This extension interacts with OES_sample_shading. |
| |
| This extension interacts with OES_shader_multisample_interpolation. |
| |
| This extension interacts with OpenGL ES 3.1. |
| |
| Overview |
| |
| This extension allows fragment shaders more control over multisample |
| rendering. The mask of samples covered by a fragment can be read by |
| the shader and individual samples can be masked out. Additionally |
| fragment shaders can be run on individual samples and the sample's |
| ID and position read to allow better interaction with multisample |
| resources such as textures. |
| |
| In multisample rendering, an implementation is allowed to assign the |
| same sets of fragment shader input values to each sample, which then |
| allows the optimization where the shader is only evaluated once and |
| then distributed to the samples that have been determined to be |
| covered by the primitive currently being rasterized. This extension |
| does not change how values are interpolated, but it makes some details |
| of the current sample available. This means that where these features |
| are used (gl_SampleID and gl_SamplePosition), implementations must |
| run the fragment shader for each sample. |
| |
| In order to obtain per-sample interpolation on fragment inputs, either |
| OES_sample_shading or OES_shader_multisample_interpolation must |
| be used in conjunction with the features from this extension. |
| |
| New Procedures and Functions |
| |
| None. |
| |
| New Tokens |
| |
| None. |
| |
| Additions to Chapter 2 of the OpenGL ES 3.0 Specification (OpenGL ES Operation) |
| |
| None. |
| |
| Additions to Chapter 3 of the OpenGL ES 3.0 Specification (Rasterization) |
| |
| Modify section 3.9.2, Shader Execution, p. 162 |
| |
| (Add the following paragraphs to the section Shader Inputs, p. 164, after |
| the paragraph about gl_FrontFacing) |
| |
| The built-in read-only variable gl_SampleID is filled with the |
| sample number of the sample currently being processed. This variable |
| is in the range zero to gl_NumSamples minus one, where |
| gl_NumSamples is the |
| total number of samples in the framebuffer, or one if rendering to a |
| non-multisample framebuffer. Using gl_SampleID in a fragment shader |
| causes the entire shader to be executed per-sample. When rendering to a |
| non-multisample buffer, |
| gl_SampleID will always be zero. gl_NumSamples is the sample count |
| of the framebuffer regardless of whether the framebuffer is multisampled |
| or not. |
| |
| The built-in read-only variable gl_SamplePosition contains the |
| position of the current sample within the multi-sample draw buffer. |
| The x and y components of gl_SamplePosition contain the sub-pixel |
| coordinate of the current sample and will have values in the range |
| [0, 1]. The sub-pixel coordinate of the center of the pixel is |
| always (0.5, 0.5). Using this variable in a fragment shader |
| causes the entire shader to be executed per-sample. When rendering to a |
| non-multisample buffer, |
| gl_SamplePosition will always be (0.5, 0.5). |
| |
| The built-in variable gl_SampleMaskIn is an integer array holding |
| bitfields indicating the set of fragment samples covered by the primitive |
| corresponding to the fragment shader invocation. The number of elements |
| in the array is ceil(gl_MaxSamples/32), where gl_MaxSamples is the |
| the value of MAX_SAMPLES, the maximum number of color samples supported |
| by the implementation. Bit <n> of element <w> in the |
| array is set if and only if the sample numbered <w>*32+<n> is considered |
| covered for this fragment shader invocation. When rendering to a |
| non-multisample buffer, all |
| bits are zero except for bit zero of the first array element. That bit |
| will be one if the pixel is covered and zero otherwise. Bits in the |
| sample mask corresponding to covered samples that will be killed due to |
| SAMPLE_COVERAGE or SAMPLE_MASK will not be set (section 4.1.3). |
| When per-sample shading is active due to the use of a fragment input |
| qualified by "sample" or due to the use of the gl_SampleID or |
| gl_SamplePosition variables, only the bit for the current sample is |
| set in gl_SampleMaskIn. |
| When OpenGL ES API state specifies multiple fragment shader invocations |
| for a given fragment, the bit corresponding to each covered sample will |
| be set in exactly one fragment shader invocation. |
| |
| Modify section Shader Outputs, p. 165 |
| |
| (Replace the second sentence of the first paragraph with the following) |
| |
| These outputs are split into two categories, user-defined outputs and the |
| built-in outputs gl_FragColor, gl_FragData[n] (both available only in |
| OpenGL ES Shading Language version 1.00), gl_FragDepth and gl_SampleMask. |
| |
| (Insert the following paragraph after the first paragraph of the section) |
| |
| The built-in integer array gl_SampleMask can be used to change the |
| sample coverage for a fragment from within the shader. The number |
| of elements in the array is ceil(gl_MaxSamples/32), where |
| gl_MaxSamples is the value of MAX_SAMPLES, the maximum number of |
| color samples supported by the implementation. |
| If bit <n> of element <w> in the array is set to zero, sample |
| <w>*32+<n> should be considered uncovered for the purposes of |
| multisample fragment operations (Section 4.1.3). Modifying the |
| sample mask in this way may exclude covered samples from being |
| processed further at a per-fragment granularity. However, setting |
| sample mask bits to one will never enable samples not covered by the |
| original primitive. If the fragment shader is being executed at |
| any frequency other than per-fragment, bits of the sample mask not |
| corresponding to the current fragment shader invocation are ignored. |
| |
| |
| Additions to Chapter 4 of the OpenGL ES 3.0.2 Specification (Per-Fragment |
| Operations and the Framebuffer) |
| |
| Modify Section 4.1.3, Multisample Fragment Operations, p. 170 |
| |
| (modify first paragraph of section) This step modifies fragment alpha and |
| coverage values based on the values of SAMPLE_ALPHA_TO_COVERAGE, |
| SAMPLE_COVERAGE, SAMPLE_COVERAGE_VALUE, |
| SAMPLE_COVERAGE_INVERT, and an output sample mask optionally written by |
| the fragment shader. No changes to the fragment alpha or coverage values |
| are made at this step if the value of |
| SAMPLE_BUFFERS is not one. |
| |
| (insert new paragraph before the paragraph on SAMPLE_COVERAGE, p. 171) |
| |
| Next, if a fragment shader is active and statically assigns to the |
| built-in output variable gl_SampleMask, the fragment coverage is ANDed |
| with the bits of the sample mask. The initial values for elements of |
| gl_SampleMask are undefined. Bits in each array element that are not |
| written due to flow control or partial writes (i.e., bit-wise operations) |
| will continue to have undefined values. The value of those bits ANDed with |
| the fragment coverage is undefined. If no fragment shader is active, or |
| if the active fragment shader does not statically assign values to |
| gl_SampleMask, the fragment coverage is not modified. |
| |
| |
| Additions to Chapter 5 of the OpenGL ES 3.0.2 Specification (Special Functions) |
| |
| None. |
| |
| Additions to Chapter 6 of the OpenGL ES 3.0.2 Specification (State and |
| State Requests) |
| |
| None. |
| |
| Modifications to The OpenGL ES Shading Language Specification, Version 3.00.04 |
| |
| Including the following line in a shader can be used to control the |
| language features described in this extension: |
| |
| #extension GL_OES_sample_variables |
| |
| A new preprocessor #define is added to the OpenGL ES Shading Language: |
| |
| #define GL_OES_sample_variables 1 |
| |
| Add to section 7.2 "Fragment Shader Special Variables" |
| |
| (add the following to the list of built-in variables that are accessible |
| from a fragment shader) |
| |
| in lowp int gl_SampleID; |
| in mediump vec2 gl_SamplePosition; |
| in highp int gl_SampleMaskIn[(gl_MaxSamples+31)/32]; |
| out highp int gl_SampleMask[(gl_MaxSamples+31)/32]; |
| |
| (add the following descriptions of the new variables) |
| |
| The input variable gl_SampleID is filled with the |
| sample number of the sample currently being processed. This |
| variable is in the range 0 to gl_NumSamples-1, where gl_NumSamples is |
| the total number of samples in the framebuffer, or one if rendering to |
| a non-multisample framebuffer. Any static use of gl_SampleID in a |
| fragment shader causes the entire shader to be executed per-sample. |
| |
| The input variable gl_SamplePosition contains the |
| position of the current sample within the multi-sample draw |
| buffer. The x and y components of gl_SamplePosition contain the |
| sub-pixel coordinate of the current sample and will have values in |
| the range 0.0 to 1.0. Any static use of this variable in a fragment |
| shader causes the entire shader to be executed per-sample. |
| |
| For the both the input array gl_SampleMaskIn[] and the output |
| array gl_SampleMask[], bit B of mask M (gl_SampleMaskIn[M] |
| or gl_SampleMask[M]) corresponds to sample 32*M+B. These arrays |
| have ceil(gl_MaxSamples/32) elements, where gl_MaxSamples is |
| the maximum number of color samples supported by the implementation. |
| |
| The input variable gl_SampleMaskIn indicates the set of samples covered |
| by the primitive generating the fragment during multisample rasterization. |
| It has a sample bit set if and only if the sample is considered covered for |
| this fragment shader invocation. |
| |
| The output array gl_SampleMask[] sets the sample mask for |
| the fragment being processed. Coverage for the current fragment will |
| be the logical AND of the coverage mask and the output |
| gl_SampleMask. If the fragment shader |
| statically assigns a value to gl_SampleMask, the sample mask will |
| be undefined for any array elements of any fragment shader |
| invocations that fails to assign a value. If a shader does not |
| statically assign a value to gl_SampleMask, the sample mask has no |
| effect on the processing of a fragment. |
| |
| Add to section 7.3 Built-in Constants |
| |
| const mediump int gl_MaxSamples = 4; |
| |
| Add to Section 7.4 Built-in Uniform State |
| |
| (Add the following prototype to the list of built-in uniforms |
| accessible from a fragment shader:) |
| |
| uniform lowp int gl_NumSamples; |
| |
| Additions to the AGL/GLX/WGL/EGL Specifications |
| |
| None |
| |
| Dependencies on OES_sample_shading |
| |
| If OES_sample_shading is not supported ignore any mention of API state |
| that forces multiple shader invocations per fragment. |
| |
| Dependencies on OES_shader_multisample_interpolation |
| |
| If OES_shader_multisample_interpolation is not supported ignore any mention of the |
| "sample" qualifier keyword for fragment inputs. |
| |
| Dependencies on OpenGL ES 3.1 |
| |
| If OpenGL ES 3.1 is not supported, ignore references to SAMPLE_MASK. |
| |
| Errors |
| |
| None. |
| |
| New State |
| |
| None. |
| |
| New Implementation Dependent State |
| |
| None. |
| |
| Issues |
| |
| (0) This extension is based on ARB_sample_shading. What are the major |
| differences? |
| |
| 1- rebased against ES 3.0 |
| 2- various editing for consistency to GL 4.4/GLSL 440 specs |
| 3- added precision qualifiers for GLSL builtins |
| 4- removed mention of SAMPLE_ALPHA_TO_ONE |
| 5- replaced mention of "color and texture coordinates" with more |
| generic language about fragment shader inputs. |
| 6- removed mention of multisample enable. |
| 7- added gl_SampleMaskIn from ARB_gpu_shader5 |
| 8- replace the term 'evaluated' with 'executed' (Issue 3) |
| 9- removed mention of sizing gl_SampleMask[] (Issue 4) |
| 10- added gl_MaxSamples shading language constant. |
| |
| For historical issues, please see ARB_sample_shading and |
| ARB_gpu_shader5. |
| |
| (1) OpenGL has a MULTISAMPLE enable that was not included in OpenGL ES. |
| Should we add it into this extension or base it purely on if the target |
| surface is multisample? |
| |
| DISCUSSION: |
| GL (4.4) says: |
| "Multisample rasterization is enabled or disabled by calling Enable or |
| Disable with the symbolic constant MULTISAMPLE." |
| |
| GL ES (3.0.2) says: |
| "Multisample rasterization cannot be enabled or disabled after a GL |
| context is created." |
| |
| RESOLVED. Multisample rasterization should be based on the target |
| surface properties. Will not pick up the explicit multisample |
| enable, but the language for ES3.0.2 doesn't sound right either. |
| Bug 10690 tracks this and it should be fixed in later versions |
| of the ES3.0 specification. |
| |
| (2) ES requires vec2s in a fragment shader to be declared with a precision |
| qualifiers, what precision should be used for gl_SamplePosition? |
| |
| RESOLVED: mediump should be used since lowp might be implemented with |
| fixed point and be unable to exactly represent [0.5, 0.5]. |
| |
| (3) Is it reasonable to run shaders per-sample when interpolation is still |
| per-fragment? |
| |
| RESOLVED: Yes. This allows a useful way of interacting with |
| multi-sample resources so it is included. To avoid confusion between |
| between per-sample interpolation and per-sample execution, we'll |
| use the term "executed" instead of "evaluated". |
| |
| (4) ARB_sample_shaders says that "gl_SampleMask[] must be sized either |
| implicitly or explicitly in the fragment shader to be the same size |
| described above." ES doesn't have implicitly sized arrays. |
| Does this need to be explicitly declared in a shader or should it be |
| predeclared by the implementation? If predeclared, should it be an |
| error to redeclare it in the shader? |
| |
| RESOLVED: In practice, one couldn't detect a difference between an |
| implicitly sized array and one that is automatically sized correctly |
| by a builtin declaration. In ES it is considered to be declared |
| (correctly sized) by the implementation when necessary and thus no |
| specific statement is required. As with all built-ins it is an |
| error for a shader to redeclare it. |
| |
| (5) How does one know the size of the gl_SampleMaskIn/gl_SampleMask |
| arrays? |
| |
| RESOLVED: The GL spec states that the size of the arrays is |
| ceil(<s>/32) where <s> is the maximum number of color samples |
| in the implementation. <s> is thus the equivalent of MAX_SAMPLES |
| which is the upper bound on the number of supported sample |
| of any format. As a convenience we add the built-in shading |
| language constant gl_MaxSamples to mirror this API |
| constant in the shading language and the size of the arrays is |
| defined in terms of this constant. |
| |
| (6) Should the shading language built-ins have OES suffixes? |
| |
| RESOLVED: No. Per Bug 11637, the WG made a policy decision |
| that GLSL ES identifiers imported without semantic change |
| or subsetting as OES extensions from core GLSL do not carry |
| suffixes. The #extension mechanism must still be used to |
| enable the appropriate extension before the functionality can |
| be used. |
| |
| |
| Revision History |
| |
| Rev. Date Author Changes |
| ---- ---------- -------- ----------------------------------------- |
| 10 2019-01-10 Jon Leech Clarify the requirements on gl_SampleMaskIn |
| (internal API issue #45). |
| 9 2014-02-12 dkoch remove GLSL suffixes per Issue 6. |
| 8 2014-01-30 dkoch rename to OES, clean editing notes |
| 7 2013-12-11 dkoch correct names of interacting extensions |
| 6 2013-10-24 dkoch add gl_MaxSampleOES builtin constant and Issue 5 |
| 5 2013-10-22 dkoch Clarifications from Ian Romanick |
| 4 2013-10-03 dkoch Added dependency on texture_storage_multisample |
| 3 2013-10-03 dkoch Resolved all issues. |
| Changed gl_SamplePosition to mediump. |
| Changed the term "evaluated" to "executed". |
| Removed language about sizing gl_SampleMask. |
| 2 2013-09-08 dkoch Added interactions for SampleMaskIn, deps. |
| Misc small editorial updates. |
| Added issue 4, unresolved issue 3. |
| 1 2013-09-03 gleese Extracted from OES_sample_shading and |
| OES_shader_multisample_interpolation |
| |
