Back to the OpenGL extension cross reference
WGL_EXT_multisample
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.
void SampleMaskEXT(clampf value,
boolean invert);
void SamplePatternEXT(enum pattern);
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.
Implementation Support
List of OpenGL implementations supporting the WGL_EXT_multisample extension
Original File
Original text file for the WGL_EXT_multisample extension
Page generated on Sun Nov 20 18:37:53 2005