xref: /third_party/openGLES/extensions/SGIS/SGIS_multisample.txt

Name

    SGIS_multisample

Name Strings

    GL_SGIS_multisample
    GLX_SGIS_multisample

Version

    $Date: 1994/11/22 02:31:01 $ $Revision: 1.14 $

Number

    25

Dependencies

    SGIX_pixel_texture affects the definition of this extension.

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 SamplePatternSGIS be eliminated?  Does anyone use this feature?

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

New Procedures and Functions

    void SampleMaskSGIS(clampf value,
		        boolean invert);

    void SamplePatternSGIS(enum pattern);

New Tokens

    Accepted by the <attribList> parameter of glXChooseVisual, and by the
    <attrib> parameter of glXGetConfig:

        GLX_SAMPLE_BUFFERS_SGIS         100000
        GLX_SAMPLES_SGIS                100001

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

        MULTISAMPLE_SGIS                0x809D
        SAMPLE_ALPHA_TO_MASK_SGIS       0x809E
        SAMPLE_ALPHA_TO_ONE_SGIS        0x809F
        SAMPLE_MASK_SGIS                0x80A0

    Accepted by the <mask> parameter of PushAttrib:

	MULTISAMPLE_BIT_EXT		0x20000000

    Accepted by the <pattern> parameter of SamplePatternSGIS:

        1PASS_SGIS                      0x80A1
        2PASS_0_SGIS                    0x80A2
        2PASS_1_SGIS                    0x80A3
        4PASS_0_SGIS                    0x80A4
        4PASS_1_SGIS                    0x80A5
        4PASS_2_SGIS                    0x80A6
        4PASS_3_SGIS                    0x80A7

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

        SAMPLE_BUFFERS_SGIS             0x80A8
        SAMPLES_SGIS                    0x80A9
        SAMPLE_MASK_VALUE_SGIS          0x80AA
        SAMPLE_MASK_INVERT_SGIS         0x80AB
        SAMPLE_PATTERN_SGIS             0x80AC

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

    None

Additions to Chapter 3 of the 1.0 Specification (Rasterization)

    If SAMPLE_BUFFERS_SGIS 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_SGIS is an implementation dependent constant, and
    is queried by calling GetIntegerv with <pname> set to SAMPLE_BUFFERS_SGIS.

    During multisample rendering the contents of a pixel fragment are
    changed in two ways.  First, each fragment includes a coverage mask
    with SAMPLES_SGIS bits.  The value of SAMPLES_SGIS is an implementation
    dependent constant, and is queried by calling GetIntegerv with <pname>
    set to SAMPLES_SGIS.  Second, each fragment includes SAMPLES_SGIS 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_SGIS depth values,
    texture coordinates, a coverage value, and the SAMPLES_SGIS-bit mask.

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

    If MULTISAMPLE_SGIS 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_SGIS-enabled multisample rasterization.

    If MULTISAMPLE_SGIS is enabled, multisample rasterization of all
    primitives differs substantially from single-sample rasterization.
    It is understood that each pixel in the framebuffer has SAMPLES_SGIS
    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 SamplePatternSGIS is called, as a repeatable function of
    parameter <pattern>.  The default pattern 1PASS_SGIS is designed to
    produce a well antialiased result in a single rendering pass.  Patterns
    2PASS_0_SGIS and 2PASS_1_SGIS together specify twice the number of
    sample points per pixel.  It is intended that a scene be completely
    rendered using pattern 2PASS_0_SGIS, then completely rendered again
    using 2PASS_1_SGIS.  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_SGIS sample points.  Patterns
    4PASS_0_SGIS, 4PASS_1_SGIS, 4PASS_2_SGIS, and 4PASS_3_SGIS together define
    a pattern of four times SAMPLES_SGIS 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_SGIS.  By default the sample pattern is 1PASS_SGIS.

    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_SGIS is enabled, and SAMPLE_BUFFERS_SGIS 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_SGIS is enabled, and SAMPLE_BUFFERS_SGIS 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.6 Polygon Multisample Rasterization

    If MULTISAMPLE_SGIS is enabled, and SAMPLE_BUFFERS_SGIS 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.4 Multisample Rasterization of Pixel Rectangles

    If MULTISAMPLE_SGIS is enabled, and SAMPLE_BUFFERS_SGIS 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 SGIX_pixel_texture (if it is implemented) or in a
    manner consistent with the discussion in the Conversion to Fragments
    subsection of section 3.6.3 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_SGIS is enabled, and SAMPLE_BUFFERS_SGIS 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_SGIS, SAMPLE_ALPHA_TO_ONE_SGIS, SAMPLE_MASK_SGIS,
    SAMPLE_MASK_VALUE_SGIS, and SAMPLE_MASK_INVERT_SGIS.  No changes to the
    fragment alpha or mask values are made at this step if MULTISAMPLE_SGIS
    is disabled, or if SAMPLE_BUFFERS_SGIS is zero.

    SAMPLE_ALPHA_TO_MASK_SGIS, SAMPLE_ALPHA_TO_ONE_SGIS, and SAMPLE_MASK_SGIS
    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_SGIS 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_SGIS is enabled, fragment alpha is replaced
    by the maximum representable alpha value.  Otherwise, fragment alpha
    value is not changed.

    Finally, if SAMPLE_MASK_SGIS 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_SGIS.  The function need not be identical, but it
    must have the same properties of proportionality and invariance.  If
    SAMPLE_MASK_INVERT_SGIS 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_SGIS and SAMPLE_MASK_INVERT_SGIS are
    specified simultaneously by calling SampleMaskSGIS, 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_SGIS.
    SAMPLE_MASK_VALUE_SGIS is queried by calling GetFloatv with <pname> set
    to SAMPLE_MASK_VALUE_SGIS.  SAMPLE_MASK_INVERT_SGIS is queried by calling
    GetBooleanv with <pname> set to SAMPLE_MASK_INVERT_SGIS.

    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_SGIS is enabled, and SAMPLE_BUFFERS_SGIS 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_SGIS is disabled, and SAMPLE_BUFFERS_SGIS 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_SGIS 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_SGIS 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_SGIS, is defined
    by this extension.  When PushAttrib is called with bit MULTISAMPLE_BIT_SGIS
    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
    SGIS_multisample, ALL_ATTRIB_BITS does not include MULTISAMPLE_BIT_SGIS.

Additions to the GLX Specification

    The parameter GLX_SAMPLE_BUFFERS_SGIS is added to glXGetConfig.  When
    queried, by calling glXGetConfig with <attrib> set to
    GLX_SAMPLE_BUFFERS_SGIS, it returns the number of multisample buffers
    included in the visual.  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
    glXGetConfig with <attrib> set to GLX_SAMPLES_SGIS.  It is understood
    that the number of color, depth, and stencil bits per sample in the
    multisample buffer are as specified by the GLX_*_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.  GLX_SAMPLES_SGIS is zero
    if GLX_SAMPLE_BUFFERS_SGIS is zero.

    glXChooseVisual accepts GLX_SAMPLE_BUFFERS_SGIS in <attribList>,
    followed by the minimum number of multisample buffers that can be
    accepted.  Visuals 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.

    glXChooseVisual accepts GLX_SAMPLES_SGIS in <attribList>, 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.

Dependencies on SGIX_pixel_texture

    As described in the text in section 3.6.4, located in the Rasterization
    section of this document.

Errors

    INVALID_ENUM is generated if SamplePatternSGIS parameter <pattern> is
    not 1PASS_SGIS, 2PASS_0_SGIS, 2PASS_1_SGIS, 4PASS_0_SGIS, 4PASS_1_SGIS,
    4PASS_2_SGIS, or 4PASS_3_SGIS.

    INVALID_OPERATION is generated if SampleMaskSGIS or SamplePatternSGIS
    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_SGIS		IsEnabled	B	TRUE		multisample/enable
    SAMPLE_ALPHA_TO_MASK_SGIS	IsEnabled	B	FALSE		multisample/enable
    SAMPLE_ALPHA_TO_ONE_SGIS	IsEnabled	B	FALSE		multisample/enable
    SAMPLE_MASK_SGIS		IsEnabled	B	FALSE		multisample/enable
    SAMPLE_MASK_VALUE_SGIS	GetFloatv	R+	1		multisample
    SAMPLE_MASK_INVERT_SGIS	GetBooleanv	B	FALSE		multisample
    SAMPLE_PATTERN_SGIS		GetIntegerv	Z7	1PASS_SGIS	multisample

New Implementation Dependent State

    Get Value		Get Command	Type	Minimum Value
    ---------		-----------	----	-------------
    SAMPLE_BUFFERS_SGIS	GetIntegerv	Z+	0
    SAMPLES_SGIS	GetIntegerv	Z+	0