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 of element in the array is set if and only if the sample numbered *32+ 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 of element in the array is set to zero, sample *32+ 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(/32) where is the maximum number of color samples in the implementation. 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