EXT_raster_multisample

GL_EXT_raster_multisample

Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com)

Pat Brown, NVIDIA
Mathias Heyer, NVIDIA

Shipping

Last Modified Date:         March 27, 2015
Revision:                   2

OpenGL Extension #462
OpenGL ES Extension #226

This extension is written against the OpenGL 4.3 (Compatibility Profile)
specification.

This extension requires OpenGL ES 3.0.3 (December 18, 2013) in an
OpenGL ES implementation.

This extension interacts with NV_fragment_coverage_to_color.

This extension interacts with EXT_depth_bounds_test.

This extension interacts with OES_sample_shading.

This extension interacts with OES_sample_variables.

This extension allows rendering to a non-multisample color buffer while
rasterizing with more than one sample. The result of rasterization
(coverage) is available in the gl_SampleMaskIn[] fragment shader input,
multisample rasterization is enabled for all primitives, and several per-
fragment operations operate at the raster sample rate.

When using the functionality provided by this extension, depth, stencil,
and depth bounds tests must be disabled, and a multisample draw
framebuffer must not be used.

A fragment's "coverage", or "effective raster samples" is considered to
have "N bits" (as opposed to "one bit" corresponding to the single color
sample) through the fragment shader, in the sample mask output, through
the multisample fragment operations and occlusion query, until the coverage
is finally "reduced" to a single bit in a new "Coverage Reduction" stage
that occurs before blending.

void RasterSamplesEXT(uint samples, boolean fixedsamplelocations);

Accepted by the <cap> parameter of Enable, Disable, IsEnabled:

    RASTER_MULTISAMPLE_EXT                          0x9327

Accepted by the <pname> parameter of GetBooleanv, GetDoublev,
GetIntegerv, and GetFloatv:

    RASTER_SAMPLES_EXT                              0x9328
    MAX_RASTER_SAMPLES_EXT                          0x9329
    RASTER_FIXED_SAMPLE_LOCATIONS_EXT               0x932A
    MULTISAMPLE_RASTERIZATION_ALLOWED_EXT           0x932B
    EFFECTIVE_RASTER_SAMPLES_EXT                    0x932C

Modify Section 14.3.1 (Multisampling), p. 477

(replace the introductory language at the beginning of the section to
 account for the new ability to use multisample rasterization without
 having multisample storage)

Multisampling is a mechanism to antialias all GL primitives: points,
lines, polygons, bitmaps, and images. The technique is to sample all
primitives multiple times at each pixel. The color sample values are
resolved to a single, displayable color. For window system-provided
framebuffers, this occurs each time a pixel is updated, so the
antialiasing appears to be automatic at the application level. For
application-created framebuffers, this must be requested by calling
the BlitFramebuffer command (see section 18.3.1). Because each sample
includes color, depth, and stencil information, the color (including
texture operation), depth, and stencil functions perform
equivalently to the single-sample mode.

When the framebuffer includes a multisample buffer, separate color, depth,
and stencil values are stored in this buffer for each sample location.
Samples contain separate color values for each fragment color.
Framebuffers including a multisample buffer do not include non-multisample
depth or stencil buffers, even if the multisample buffer does not store
depth or stencil values.  Color buffers do coexist with the multisample
buffer, however.

The color sample values are resolved to a single, displayable color each
time a pixel is updated, so the antialiasing appears to be automatic at
the application level. Because each sample includes color, depth, and
stencil information, the color (including texture operation), depth, and
stencil functions perform equivalently to the single-sample mode.

Multisample antialiasing is most valuable for rendering polygons, because
it requires no sorting for hidden surface elimination, and it correctly
handles adjacent polygons, object silhouettes, and even intersecting
polygons. If only points or lines are being rendered, the "smooth"
antialiasing mechanism provided by the base GL may result in a higher
quality image. This mechanism is designed to allow multisample and smooth
antialiasing techniques to be alternated during the rendering of a single
scene.

If the value of MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is TRUE, the
rasterization of all primitives is changed, and is referred to as
multisample rasterization. Otherwise, primitive rasterization is
referred to as single-sample rasterization. The value of MULTISAMPLE-
_RASTERIZATION_ALLOWED_EXT is queried by calling GetIntegerv
with pname set to MULTISAMPLE_RASTERIZATION_ALLOWED_EXT.

During multisample rendering the contents of a pixel fragment are changed
in two ways. First, each fragment includes a coverage value with
EFFECTIVE_RASTER_SAMPLES_EXT bits.  The value of EFFECTIVE_RASTER_-
SAMPLES_EXT is an implementation-dependent constant, and
is queried by calling GetIntegerv with pname set to EFFECTIVE_RASTER-
_SAMPLES_EXT.


---

Multisample rasterization may also be enabled without introducing
additional storage for the multisample buffer, by calling Enable with a
<target> of RASTER_MULTISAMPLE_EXT.  The command:

    void RasterSamplesEXT(uint samples, boolean fixedsamplelocations);

selects the number of samples to be used for rasterization. <samples>
represents a request for a desired minimum number of samples. Since
different implementations may support different sample counts, the actual
sample pattern used is implementation-dependent. However, the resulting
value for RASTER_SAMPLES_EXT is guaranteed to be greater than or equal to
<samples> and no more than the next larger sample count supported by the
implementation. If <fixedsamplelocations> is TRUE, identical sample
locations will be used for all pixels. The sample locations chosen are a
function of only the parameters to RasterSamplesEXT and not of any other
state.

If RASTER_MULTISAMPLE_EXT is enabled, then the sample pattern chosen by
RasterSamplesEXT will be used instead of sampling at the center of the
pixel. The sample locations can be queried with GetMultisamplefv with a
<pname> of SAMPLE_POSITION, similar to normal multisample sample locations.

The value MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is TRUE if SAMPLE_BUFFERS
is one or if RASTER_MULTISAMPLE_EXT is enabled.  The value
EFFECTIVE_RASTER_SAMPLES_EXT is equal to RASTER_SAMPLES_EXT if
RASTER_MULTISAMPLE_EXT is enabled, otherwise is equal to SAMPLES.

Explicit multisample rasterization can not be used in conjunction with
depth, stencil, or depth bounds tests, multisample framebuffers, or if
RASTER_SAMPLES_EXT is zero.  If RASTER_MULTISAMPLE_EXT is enabled, the
error INVALID_OPERATION will be generated by Draw commands if

  - the value of RASTER_SAMPLES_EXT is zero
  - the depth, stencil, or depth bounds test is enabled
  - a multisample draw framebuffer is bound (SAMPLE_BUFFERS is one)

Errors

- An INVALID_VALUE error is generated if <samples> is greater than the
value of MAX_RASTER_SAMPLES_EXT (the implementation-dependent maximum
number of samples).


Add to the end of Section 14.3.1.1 (Sample Shading), p. 479

If RASTER_MULTISAMPLE_EXT is enabled, the number of unique samples to
process is implementation-dependent and need not be more than one.

Modify Section 14.4.3 (Point Multisample Rasterization)

If MULTISAMPLE is enabled and MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is
TRUE, then points are rasterized using the following algorithm, regardless
of whether point antialiasing (POINT_SMOOTH) is enabled or disabled.

Modify Section 14.5.4 (Line Multisample Rasterization)

If MULTISAMPLE is enabled and MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is
TRUE, then lines are rasterized using the following algorithm, regardless
of whether line antialiasing (LINE_SMOOTH) is enabled or disabled.

Modify Section 14.6.6 (Polygon Multisample Rasterization)

If MULTISAMPLE is enabled and MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is
TRUE, then polygons are rasterized using the following algorithm,
regardless of whether polygon antialiasing (POLYGON_SMOOTH) is enabled or
disabled.

Modify Section 14.8.0.1 (Bitmap Multisample Rasterization)

If MULTISAMPLE is enabled and MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is
TRUE, then bitmaps are rasterized using the following algorithm.

Modify Section 15.2.2 (Shader Inputs), p. 512

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(s/32),

where <s> is the maximum number of color or raster samples supported by the
implementation. Bit <n> of element <w> in the array is set if and only if
the raster sample numbered 32<w> + <n> is considered covered for this
fragment shader invocation.

Modify Section 15.2.3 (Shader Outputs), p. 513

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(s/32),

where <s> is the maximum number of color or raster samples supported by the
implementation.

Modify Figure 17.1 (Per-fragment operations)

Add a new stage called "Coverage Reduction" between "Occlusion Query" and
"Blending".

(note: If NV_fragment_coverage_to_color is supported, the "Coverage
Reduction" stage is after the "Fragment coverage to color" stage.)


Modify Section 17.3.3 (Multisample Fragment Operations)

First paragraph:
...No changes to the fragment alpha or coverage values are made at this
step if MULTISAMPLE is disabled or MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is
FALSE.

...

If SAMPLE_ALPHA_TO_COVERAGE is enabled, a temporary coverage value is
generated where each bit is determined by the alpha value at the
corresponding sample location. The coverage value has
EFFECTIVE_RASTER_SAMPLES_EXT bits.


Modify Section 17.3.7 (Occlusion Queries), p.538

When an occlusion query is started with target SAMPLES_PASSED, the samples-
passed count maintained by the GL is set to zero. When an occlusion query
is active, the samples-passed count is incremented for each fragment that
passes the depth test. If MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is FALSE,
then the samples-passed count is incremented by 1 for each fragment. If
MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is TRUE, then the samples-passed
count is incremented by the number of samples whose coverage bit is set.
However, implementations, at their discretion, may instead increase the
samples-passed count by the value of EFFECTIVE_RASTER_SAMPLES_EXT if any
sample in the fragment is covered.  Additionally, if
RASTER_MULTISAMPLE_EXT is enabled, implementations may instead increase
the samples-passed count by one for the entire fragment if any sample 
is covered.


Add a new Section 17.3.Y (Coverage Reduction) after 17.3.7.

If RASTER_MULTISAMPLE_EXT is enabled, a fragment's coverage is reduced
from RASTER_SAMPLES_EXT bits to a single bit, where the new "color
coverage" is 1 if any bit in the fragment's coverage is on, and 0
otherwise. If the color coverage is 0, then blending and writing to the
framebuffer are not performed for that sample.

Modify Section 18.1.3 (Pixel Rectangle Multisample Rasterization)

If MULTISAMPLE is enabled and MULTISAMPLE_RASTERIZATION_ALLOWED_EXT is TRUE,
then pixel rectangles are rasterized using the following algorithm.

                                                  Minimum
Get Value                    Type    Get Command  Value   Description                   Sec.
---------                    ------- -----------  ------- ------------------------      ------
MAX_RASTER_SAMPLES_EXT       Z+      GetIntegerv  2       Maximum number of raster      14.3.1
                                                          samples

Get Value                       Get Command    Type    Initial Value    Description                 Sec.    Attribute
---------                       -----------    ----    -------------    -----------                 ----    ---------
RASTER_MULTISAMPLE_EXT          IsEnabled      B       FALSE            Multisample Rasterization   14.3.1  enable/multisample
                                                                        without multiple color
                                                                        samples
RASTER_SAMPLES_EXT              GetIntegerv    Z+      0                Number of raster samples    14.3.1  multisample

RASTER_FIXED_SAMPLE_-           GetBooleanv    B       FALSE            Require same sample         14.3.1  multisample
    LOCATIONS_EXT                                                       locations
MULTISAMPLE_RASTERIZATION_-     GetBooleanv    B       FALSE            Whether multisample         14.3.1  -
    ALLOWED_EXT                                                         rasterization can be used
EFFECTIVE_RASTER_SAMPLES_EXT    GetIntegerv    Z+      0                How many samples are used   14.3.1  -
                                                                        for rasterization and
                                                                        fragment operations

None.

None.

Modify Section 7.1 (Built-In Language Variables), p. 118

For 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(s/32) elements, where
s is the maximum number of color or raster samples supported by the
implementation.

For OpenGL ES, remove references to images, bitmaps and GetDoublev.
Disregard references to POINT_SMOOTH, LINE_SMOOTH and POLYGON_SMOOTH.

Omit changes to Section 14.8.0.1 (Bitmap Multisample Rasterization).
Also, omit changes to Section 18.1.3 (Pixel Rectangle Multisample Rasterization).

Since OpenGL ES does not support enabling/disabling MULTISAMPLE rasterization
via MULTISAMPLE, read all occurrences of MULTISAMPLE as if it was enabled.

If this extension is implemented on OpenGL ES and OES_sample_shading
is not supported, omit changes to Section 3.3.1 (Sample Shading).

If EXT_depth_bounds_test is not supported, remove the error check for the
depth bounds test enable.

INVALID_OPERATION is generated by Draw commands if RASTER_MULTISAMPLE_EXT
is enabled and any of the following is true:

  - the value of RASTER_SAMPLES_EXT is zero
  - the depth, stencil, or depth bounds test is enabled
  - a multisample draw framebuffer is bound (SAMPLE_BUFFERS is one)

INVALID_VALUE is generated by RasterSamplesEXT if <samples> is greater
than the value of MAX_RASTER_SAMPLES_EXT.

(1) What is the interaction with sample shading?

RESOLVED: Sample shading requires "max(ceil(mss * samples), 1)" shader
invocations. Since <samples> must be one when using this feature, an
implementation is still only required to shade once. However, in case this
functionality were supported with more than one color sample, we don't
require shading at more than one sample.

(2) Where are attributes sampled?

RESOLVED: They are sampled as if normal multisampling were in effect with
the same sample pattern. i.e. attributes can be sampled at the center or
at the centroid, depending on what the shader requests.

(3) During multisample rasterization, what are the values of the GLSL
built-in variables gl_SampleMaskIn[], gl_SampleMask[], gl_SampleID,
gl_NumSamples, gl_SamplePosition?

RESOLVED: There are RASTER_SAMPLES_EXT bits in gl_SampleMaskIn and
gl_SampleMask. gl_SampleID and gl_NumSamples continue to reflect the
number of samples in the framebuffer.

gl_SamplePosition is intended to reflect the location of the fragment being
shaded when MIN_SAMPLE_SHADING is enabled. However, since we don't require
MIN_SAMPLE_SHADING to work in conjunction with this extension,
gl_SamplePosition may just contain the location of the pixel center.

(4) How does multisample rasterization operate?

RESOLVED: Point shape, point anti-aliasing, line smooth, etc. will operate
the same when RASTER_MULTISAMPLE is enabled as they do when SAMPLE_BUFFERS
is one in the absence of this extension.

(5) When using both NV_fragment_coverage_to_color and EXT_raster_multisample
or NV_framebuffer_mixed_samples, how do these features interact?

RESOLVED: Both may be used simultaneously, and the coverage_to_color
functionality is applied before coverage reduction in the pipeline. This
means the full raster sample mask will be written to the color buffer, not
the reduced color sample mask.

Revision 2, 2015/03/27
  - Add ES interactions

Revision 1, September 12, 2014 (jbolz, pbrown, mheyer)

  Internal spec development.