xref: /third_party/openGLES/extensions/EXT/WGL_EXT_multisample.txt

Name

    EXT_multisample

Name Strings

    GL_EXT_multisample
    WGL_EXT_multisample

Version

    Last Modified Date: January 4, 1999
    Author Revision: 1.2

    Based on:  SGIS_Multisample Specification Revision 1.14

Number

    209

Dependencies

    WGL_EXT_extensions_string is required.
    WGL_EXT_pixel_format is required.

Overview

    This extension provides 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 each time a pixel
    is updated, so the antialiasing appears to be automatic at the
    application level.  Because each sample includes depth and stencil
    information, the depth and stencil functions perform equivalently
    to the single-sample mode.

    An additional buffer, called the multisample buffer, is added to
    the framebuffer.  Pixel sample values, including color, depth, and
    stencil values, are stored in this buffer.  When the framebuffer
    includes a multisample buffer, it does not also include separate
    depth or stencil buffers, even if the multisample buffer does not
    store depth or stencil values.  Color buffers (left/right, front/
    back, and aux) do coexist with the multisample buffer, however.

    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 extension is designed
    to allow multisample and smooth antialiasing techniques to be
    alternated during the rendering of a single scene.

Issues

    * Should SamplePatternEXT be eliminated?  Does anyone use this feature?

    * Should WGL_SAMPLE_BUFFERS_EXT and SAMPLE_BUFFERS_EXT be eliminated?
      Given the current specification, applications that query only
      WGL_SAMPLES_EXT will be written, taking zero to mean that there is
      no multisample buffer.

New Procedures and Functions

    void SampleMaskEXT(clampf value,
                       boolean invert);

    void SamplePatternEXT(enum pattern);

New Tokens

    Accepted by the <attribute> parameter of wglGetPixelFormatAttribivEXT,
    wglGetPixelFormatAttribfvEXT, and wglChoosePixelFormatExEXT:

      WGL_SAMPLE_BUFFERS_EXT               0x2041
      WGL_SAMPLES_EXT                      0x2042

    Accepted by the <cap> parameter of Enable, Disable, and IsEnabled, and
    by the <pname> parameter of GetBooleanv, GetIntegerv, GetFloatv, and
    GetDoublev:

      MULTISAMPLE_EXT                      0x809D
      SAMPLE_ALPHA_TO_MASK_EXT             0x809E
      SAMPLE_ALPHA_TO_ONE_EXT              0x809F
      SAMPLE_MASK_EXT                      0x80A0

    Accepted by the <mask> parameter of PushAttrib:

      MULTISAMPLE_BIT_EXT                  0x20000000

    Accepted by the <pattern> parameter of SamplePatternEXT:

      1PASS_EXT                            0x80A1
      2PASS_0_EXT                          0x80A2
      2PASS_1_EXT                          0x80A3
      4PASS_0_EXT                          0x80A4
      4PASS_1_EXT                          0x80A5
      4PASS_2_EXT                          0x80A6
      4PASS_3_EXT                          0x80A7

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

      SAMPLE_BUFFERS_EXT                   0x80A8
      SAMPLES_EXT                          0x80A9
      SAMPLE_MASK_VALUE_EXT                0x80AA
      SAMPLE_MASK_INVERT_EXT               0x80AB
      SAMPLE_PATTERN_EXT                   0x80AC

Additions to Chapter 2 of the 1.2 Specification (OpenGL Operation)

    None

Additions to Chapter 3 of the 1.2 Specification (Rasterization)

    If SAMPLE_BUFFERS_EXT is one, the rasterization of all GL primitives
    is changed, and is referred to as multisample rasterization.  Otherwise
    primitive rasterization operates as it is described in the GL
    specification, and is referred to as single-sample rasterization.  The
    value of SAMPLE_BUFFERS_EXT is an implementation dependent constant, and
    is queried by calling GetIntegerv with <pname> set to SAMPLE_BUFFERS_EXT.

    During multisample rendering the contents of a pixel fragment are
    changed in two ways.  First, each fragment includes a coverage mask
    with SAMPLES_EXT bits.  The value of SAMPLES_EXT is an implementation
    dependent constant, and is queried by calling GetIntegerv with <pname>
    set to SAMPLES_EXT.  Second, each fragment includes SAMPLES_EXT depth
    values, instead of the single depth value that is maintained in
    single-sample rendering mode.  Each pixel fragment thus consists of
    integer x and y grid coordinates, a color, SAMPLES_EXT depth values,
    texture coordinates, a coverage value, and the SAMPLES_EXT-bit mask.

    The behavior of multisample rasterization is a function of
    MULTISAMPLE_EXT, which is enabled and disabled by calling Enable or
    Disable, with <cap> set to MULTISAMPLE_EXT.  Its value is queried using
    IsEnabled, with <cap> set to MULTISAMPLE_EXT.

    If MULTISAMPLE_EXT is disabled, multisample rasterization of all
    primitives is equivalent to single-sample rasterization, except that the
    fragment coverage mask is set to all ones.  The depth values may all
    be set to the single value that would have been assigned by single-sample
    rasterization, or they may be assigned as described below for
    MULTISAMPLE_EXT-enabled multisample rasterization.

    If MULTISAMPLE_EXT is enabled, multisample rasterization of all
    primitives differs substantially from single-sample rasterization.
    It is understood that each pixel in the framebuffer has SAMPLES_EXT
    locations associated with it.  These locations are exact positions,
    rather than regions or areas, and each is referred to as a sample point.
    The sample points associated with a pixel may be located inside or
    outside of the unit square that is considered to bound the pixel.
    Furthermore, the pattern (relative location) of sample points may
    be identical for each pixel in the framebuffer, or it may differ.

    The locations of the sample points are relatively static; they change
    only when SamplePatternEXT is called, as a repeatable function of
    parameter <pattern>.  The default pattern 1PASS_EXT is designed to
    produce a well antialiased result in a single rendering pass.  Patterns
    2PASS_0_EXT and 2PASS_1_EXT together specify twice the number of
    sample points per pixel.  It is intended that a scene be completely
    rendered using pattern 2PASS_0_EXT, then completely rendered again
    using 2PASS_1_EXT.  When these two images are averaged using the
    accumulation buffer, the result is as if a single pass had been
    rendered with a filter of twice SAMPLES_EXT sample points.  Patterns
    4PASS_0_EXT, 4PASS_1_EXT, 4PASS_2_EXT, and 4PASS_3_EXT together define
    a pattern of four times SAMPLES_EXT sample points. They can be used
    to accumulate an image after four complete rendering passes.  It is
    not possible to query the actual sample locations of a pixel.  The
    sample pattern mode is queried by calling GetIntegerv with <pname>
    set to SAMPLE_PATTERN_EXT.  By default the sample pattern is 1PASS_EXT.

    If the sample patterns differ per pixel, they should be aligned to
    window, not screen, boundaries.  Otherwise rendering results will be
    window-position specific.  The invariance requirement described
    in section 3.1 is relaxed for all enabled multisample rendering,
    because the sample patterns may be a function of pixel location.

    3.3.2 Point Multisample Rasterization

    If MULTISAMPLE_EXT is enabled, and SAMPLE_BUFFERS_EXT is one, then
    points are rasterized using the following algorithm, regardless of
    whether point antialiasing (POINT_SMOOTH) is enabled or disabled.
    Point rasterization produces a fragment for each framebuffer pixel
    with one or more sample points that intersect the region lying within
    the circle having diameter equal to the current point width and
    centered at the point's (Xw,Yw).  The coverage value for each fragment
    is 1.  Mask bits that correspond to sample points that intersect the
    circular region are 1, other mask bits are 0.  All depth values of the
    fragment are assigned the depth value of the point being rasterized.
    The data associated with each fragment are otherwise the data
    associated with the point being rasterized.

    Point size range and number of gradations are equivalent to those
    supported for antialiased points.

    3.4.4 Line Multisample Rasterization

    If MULTISAMPLE_EXT is enabled, and SAMPLE_BUFFERS_EXT is one, then
    lines are rasterized using the following algorithm, regardless of
    whether line antialiasing (LINE_SMOOTH) is enabled or disabled.  Line
    rasterization produces a fragment for each framebuffer pixel with one
    or more sample points that intersect the rectangular region that is
    described in the Antialiasing section of 3.4.2 (Other Line Segment
    Features).  If line stippling is enabled, the rectangular region is
    subdivided into adjacent unit-length rectangles, with some rectangles
    eliminated according to the procedure given under Line Stipple, where
    "fragment" is replaced by "rectangle".

    The coverage value for each fragment is 1.  Mask bits that correspond
    to sample points that intersect a retained rectangle are 1, other mask
    bits are 0.  Each depth value is produced by substituting the
    corresponding sample location into equation 3.1, then using the
    result to evaluate equation 3.3.  The data associated with each
    fragment are otherwise computed by evaluating equation 3.1 at the
    fragment center, then substituting into equation 3.2.

    Line width range and number of gradations are equivalent to those
    supported for antialiased lines.

    3.5.7 Polygon Multisample Rasterization

    If MULTISAMPLE_EXT is enabled, and SAMPLE_BUFFERS_EXT is one, then
    polygons are rasterized using the following algorithm, regardless of
    whether polygon antialiasing (POLYGON_SMOOTH) is enabled or disabled.
    Polygon rasterization produces a fragment for each framebuffer pixel
    with one or more sample points that satisfy the point sampling
    criteria described in section 3.5.1, including the special treatment
    for sample points that lie on a polygon boundary edge.  If a polygon
    is culled, based on its orientation and the CullFace mode, then no
    fragments are produced during rasterization.  Fragments are culled
    by the polygon stipple just as they are for aliased and antialiased
    polygons.

    The coverage value for each fragment is 1.  Mask bits that correspond
    to sample points that satisfy the point sampling criteria are 1, other
    mask bits are 0.  Each depth value is produced by substituting the
    corresponding sample location into the barycentric equations described
    in section 3.5.1, using the approximation to equation 3.4 that omits
    w components.  The data associated with each fragment are otherwise
    computed by barycentric evaluation using the fragment's center point.

    The rasterization described above applies only to the FILL state of
    PolygonMode.  For POINT and LINE, the rasterizations described in
    3.3.2 (Point Multisample Rasterization) and 3.4.4 (Line Multisample
    Rasterization) apply.

    3.6.6 Multisample Rasterization of Pixel Rectangles

    If MULTISAMPLE_EXT is enabled, and SAMPLE_BUFFERS_EXT is one, then
    pixel rectangles are rasterized using the following algorithm.
    Let (Xrp,Yrp) be the current raster position.  (If the current raster
    position is invalid, then DrawPixels is ignored.)  If a particular
    group (index or components) is the nth in a row and belongs to the
    mth row, consider the region in window coordinates bounded by the
    rectangle with corners

      (Xrp + Zx*n, Yrp + Zy*m)

    and

      (Xrp + Zx*(n+1), Yrp + Zy*(m+1))

    where Zx and Zy are the pixel zoom factors specified by PixelZoom,
    and may each be either positive or negative.  A fragment representing
    group n,m is produced for each framebuffer pixel with one or more
    sample points that lie inside, or on the bottom or left boundary, of
    this rectangle.  Each fragment so produced takes its associated data
    from the group and from the current raster position, in a manner
    consistent with the discussion in the Conversion to Fragments
    subsection of section 3.6.4 of the GL specification.  All depth
    sample values are assigned the same value, taken either from the
    group (if it is a depth component group) or from the current raster
    position (if it is not).

    A single pixel rectangle will generate multiple, perhaps very many
    fragments for the same framebuffer pixel, depending on the pixel zoom
    factors.

    3.7.1 Bitmap Multisample Rasterization

    If MULTISAMPLE_EXT is enabled, and SAMPLE_BUFFERS_EXT is one, then
    bitmaps are rasterized using the following algorithm.  If the current
    raster position is invalid, the bitmap is ignored.  Otherwise, a
    screen-aligned array of pixel-size rectangles is constructed, with its
    lower-left corner at (Xrp,Yrp), and its upper right corner at
    (Xrp+w,Yrp+h), where w and h are the width and height of the bitmap.
    Rectangles in this array are eliminated if the corresponding bit in the
    bitmap is zero, and are retained otherwise.  Bitmap rasterization
    produces a fragment for each framebuffer pixel with one or more sample
    points either inside or on the bottom or left edge of a retained
    rectangle.

    The coverage value for each fragment is 1.  Mask bits that correspond
    to sample points either inside or on the bottom or left edge of a
    retained rectangle are 1, other mask bits are 0.  The associated data
    for each fragment are those associated with the current raster
    position.  Once the fragments have been produced, the current raster
    position is updated exactly as it is in the single-sample rasterization
    case.

Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations
and the Frame Buffer)

    4.1.2.5 Multisample Fragment Operations

    [This section follows section 4.1.2 (Scissor test) and precedes section
     4.1.3 (Alpha test)]

    This step modifies fragment alpha and mask values, based on the values
    of SAMPLE_ALPHA_TO_MASK_EXT, SAMPLE_ALPHA_TO_ONE_EXT, SAMPLE_MASK_EXT,
    SAMPLE_MASK_VALUE_EXT, and SAMPLE_MASK_INVERT_EXT.  No changes to the
    fragment alpha or mask values are made at this step if MULTISAMPLE_EXT
    is disabled, or if SAMPLE_BUFFERS_EXT is zero.

    SAMPLE_ALPHA_TO_MASK_EXT, SAMPLE_ALPHA_TO_ONE_EXT, and SAMPLE_MASK_EXT
    are enabled and disabled by calling Enable and Disable with <cap>
    specified as one of the three token values.  All three values are
    queried by calling IsEnabled, with <cap> set to the desired token value.
    If SAMPLE_ALPHA_TO_MASK_EXT is enabled, the fragment alpha value is
    used to generate a temporary mask value, which is then ANDed with the
    fragment mask value.  Otherwise the fragment mask value is unchanged at
    this point.

    This specification does not require a specific algorithm for converting
    an alpha value to a temporary mask value.  It is intended that the number
    of 1's in the temporary mask be proportional to the alpha value, with
    all 1's corresponding to the maximum alpha value, and all 0's
    corresponding to an alpha value of 0.  It is also intended that the
    algorithm be pseudo-random in nature, to avoid image artifacts due
    to regular mask patterns.  The algorithm can and probably should be
    different at different pixel locations.  If it does differ, it should
    be defined relative to window, not screen, coordinates, so that
    rendering results are invariant with respect to window position.

    Next, if SAMPLE_ALPHA_TO_ONE_EXT is enabled, fragment alpha is replaced
    by the maximum representable alpha value.  Otherwise, fragment alpha
    value is not changed.

    Finally, if SAMPLE_MASK_EXT is enabled, the fragment mask is ANDed
    with another temporary mask.  This temporary mask is generated in the
    same manner as the one described above, but as a function of the value
    of SAMPLE_MASK_VALUE_EXT.  The function need not be identical, but it
    must have the same properties of proportionality and invariance.  If
    SAMPLE_MASK_INVERT_EXT is TRUE, the temporary mask is inverted (all
    bit values are inverted) before it is ANDed with the fragment mask.

    The values of SAMPLE_MASK_VALUE_EXT and SAMPLE_MASK_INVERT_EXT are
    specified simultaneously by calling SampleMaskEXT, with <value> set
    to the desired mask value, and <invert> set to TRUE or FALSE.  <value>
    is clamped to [0,1] before being stored as SAMPLE_MASK_VALUE_EXT.
    SAMPLE_MASK_VALUE_EXT is queried by calling GetFloatv with <pname> set
    to SAMPLE_MASK_VALUE_EXT.  SAMPLE_MASK_INVERT_EXT is queried by calling
    GetBooleanv with <pname> set to SAMPLE_MASK_INVERT_EXT.

    4.1.9 Multisample Fragment Operations

    If the DrawBuffers mode is NONE, no change is made to any multisample
    or color buffer.  Otherwise, fragment processing is as described below.

    If MULTISAMPLE_EXT is enabled, and SAMPLE_BUFFERS_EXT is one, the
    stencil test, depth test, blending, and dithering operations described
    in sections 4.1.4, 4.1.5, 4.1.6, and 4.1.7 are performed for each
    pixel sample, rather than just once for each fragment.  Failure
    of the stencil or depth test results in termination of the processing
    of that sample, rather than discarding of the fragment.  All operations
    are performed on the color, depth, and stencil values stored in the
    multisample buffer (to be described in a following section).  The
    contents of the color buffers are not modified at this point.

    Stencil, depth, blending, and dithering operations are performed
    for a pixel sample only if that sample's fragment mask bit is 1.  If
    the corresponding mask bit is 0, no operations are performed for that
    sample.  Depth operations use the fragment depth value that is
    specific to each sample.  The single fragment color value is used for
    all sample operations, however, as is the current stencil value.

    If MULTISAMPLE_EXT is disabled, and SAMPLE_BUFFERS_EXT is one, the
    fragment may be treated exactly as described above, with optimization
    possible because the fragment mask must be all 1's.  Further
    optimization is allowed, however.  An implementation may choose to
    identify a centermost sample, and to perform stencil and depth tests
    on only that sample.  Regardless of the outcome of the stencil test,
    all multisample buffer stencil sample values are set to the appropriate
    new stencil value.  If the depth test passes, all multisample buffer
    depth sample values are set to the depth of the fragment's centermost
    sample's depth value, and all multisample buffer color sample values
    are set to the color value of the incoming fragment.  Otherwise, no
    change is made to any multisample buffer color or depth value.

    After all operations have been completed on the multisample buffer,
    the color sample values are combined to produce a single color value,
    and that value is written into each color buffer that is currently
    enabled, based on the DrawBuffers mode.  The method of combination is
    not specified, though a simple average computed independently for each
    color component is recommended.

    4.2.2.5 Fine Control of Multisample Buffer Updates

    When SAMPLE_BUFFERS_EXT is one, ColorMask, DepthMask, and StencilMask
    control the modification of values in the multisample buffer.  The
    color mask has no effect on modifications to the color buffers.  If
    the color mask is entirely disabled, the color sample values must
    still be combined (as described above) and the result used to replace
    the color values of the buffers enabled by DrawBuffers.

    4.2.3.5 Clearing the Multisample Buffer

    The color samples of the multisample buffer are cleared when one or
    more color buffers are cleared, as specified by the Clear mask bit
    COLOR_BUFFER_BIT and the DrawBuffers mode.  If the DrawBuffers mode is
    NONE, the color samples of the multisample buffer cannot be cleared.

    Clear mask bits DEPTH_BUFFER_BIT and STENCIL_BUFFER_BIT indicate that
    the depth and stencil samples of the multisample buffer are to be
    cleared.  If Clear mask bit DEPTH_BUFFER_BIT is specified, and if
    the DrawBuffers mode is not NONE, then the multisample depth buffer
    samples are cleared.  Likewise, if Clear mask bit STENCIL_BUFFER_BIT
    is specified, and if the DrawBuffers mode is not NONE, then the
    multisample stencil buffer is cleared.

    4.3.2 Reading Pixels

    [These changes are made to the text in section 4.3.2, following the
    subheading Obtaining Pixels from the Framebuffer.]

    Follow the sentence "If there is no depth buffer, the error
    INVALID_OPERATION occurs." with: If there is a multisample buffer
    (SAMPLE_BUFFERS_EXT is 1) then values are obtained from the depth
    samples in this buffer.  It is recommended that the depth value
    of the centermost sample be used, though implementations may choose
    any function of the depth sample values at each pixel.

    Follow the sentence "if there is no stencil buffer, the error
    INVALID_OPERATION occurs." with: If there is a multisample buffer,
    then values are obtained from the stencil samples in this buffer.
    It is recommended that the stencil value of the centermost sample
    be used, though implementations may choose any function of the stencil
    sample values at each pixel.

    This extension makes no change to the way that color values are
    obtained from the framebuffer.

Additions to Chapter 5 of the 1.0 Specification (Special Functions)

    None

Additions to Chapter 6 of the 1.0 Specification (State and State Requests)

    An additional group of state variables, MULTISAMPLE_BIT_EXT, is defined
    by this extension.  When PushAttrib is called with bit MULTISAMPLE_BIT_EXT
    set, the multisample group of state variables is pushed onto the
    attribute stack.  When PopAttrib is called, these state variables are
    restored to their previous values if they were pushed.  Some multisample
    state is included in the ENABLE_BIT group as well.  In order to avoid
    incompatibility with GL implementations that do not support
    EXT_multisample, ALL_ATTRIB_BITS does not include MULTISAMPLE_BIT_EXT.

Additions to the WGL Specification

    The parameter WGL_SAMPLE_BUFFERS_EXT is added to wglGetPixelFormatAttrib*v.
    When queried, by calling wglGetPixelFormatAttrib*v with <attributes> set
    to WGL_SAMPLE_BUFFERS_EXT, it returns the number of multisample buffers
    included in the pixel format.  For a normal visual, the return value is
    zero.  A return value of one indicates that a single multisample buffer
    is available.  The number of samples per pixel is queried by calling
    wglGetPixelFormatAttrib*v with <attrib> set to WGL_SAMPLES_EXT.  It is
    understood that the number of color, depth, and stencil bits per sample
    in the multisample buffer are as specified by the WGL_*_SIZE parameters.
    It is also understood that there are no single-sample depth or stencil
    buffers associated with this visual -- the only depth and stencil
    buffers are those in the multisample buffer.  WGL_SAMPLES_EXT is zero
    if WGL_SAMPLE_BUFFERS_EXT is zero.

    wglChoosePixelFormatEx accepts WGL_SAMPLE_BUFFERS_EXT in <attributes>,
    followed by the minimum number of multisample buffers that can be
    accepted.  Pixel formats with the smallest number of multisample buffers
    that meets or exceeds the specified minimum number are preferred.
    Currently operation with more than one multisample buffer is undefined,
    so the returned value will be either zero or one.

    wglChoosePixelFormatEx accepts WGL_SAMPLES_EXT in <attributes>, followed
    by the minimum number of samples that can be accepted in the multisample
    buffer.  Visuals with the smallest number of samples that meets or
    exceeds the specified minimum number are preferred.

    If the color samples in the multisample buffer store fewer bits than
    are stored in the color buffers, this fact will not be reported
    accurately.  Presumably a compression scheme is being employed, and is
    expected to maintain an aggregate resolution equal to that of the
    color buffers.

Errors

    INVALID_ENUM is generated if SamplePatternEXT parameter <pattern> is
    not 1PASS_EXT, 2PASS_0_EXT, 2PASS_1_EXT, 4PASS_0_EXT, 4PASS_1_EXT,
    4PASS_2_EXT, or 4PASS_3_EXT.

    INVALID_OPERATION is generated if SampleMaskEXT or SamplePatternEXT
    is called between the execution of Begin and the execution of the
    corresponding End.

New State

    Get Value                 Get Command  Type  Initial Value  Attribute
    ---------                 -----------  ----  -------------  ---------
    MULTISAMPLE_EXT           IsEnabled    B     TRUE           multisample/enable
    SAMPLE_ALPHA_TO_MASK_EXT  IsEnabled    B     FALSE          multisample/enable
    SAMPLE_ALPHA_TO_ONE_EXT   IsEnabled    B     FALSE          multisample/enable
    SAMPLE_MASK_EXT           IsEnabled    B     FALSE          multisample/enable
    SAMPLE_MASK_VALUE_EXT     GetFloatv    R+    1              multisample
    SAMPLE_MASK_INVERT_EXT    GetBooleanv  B     FALSE          multisample
    SAMPLE_PATTERN_EXT        GetIntegerv  Z7    1PASS_EXT      multisample

New Implementation Dependent State

    Get Value           Get Command  Type  Minimum Value
    ---------           -----------  ----  -------------
    SAMPLE_BUFFERS_EXT  GetIntegerv  Z+    0
    SAMPLES_EXT         GetIntegerv  Z+    0

Revision History

    April 19, 2000 - assigned extension #209.
    June 1999 - added to the OpenGL extension registry.
    January 1999 - Written by Intergraph.