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 parameter of glXChooseVisual, and by the parameter of glXGetConfig: GLX_SAMPLE_BUFFERS_SGIS 100000 GLX_SAMPLES_SGIS 100001 Accepted by the parameter of Enable, Disable, and IsEnabled, and by the 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 parameter of PushAttrib: MULTISAMPLE_BIT_EXT 0x20000000 Accepted by the 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 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 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 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 set to MULTISAMPLE_SGIS. Its value is queried using IsEnabled, with 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 . 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 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 specified as one of the three token values. All three values are queried by calling IsEnabled, with 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 set to the desired mask value, and set to TRUE or FALSE. is clamped to [0,1] before being stored as SAMPLE_MASK_VALUE_SGIS. SAMPLE_MASK_VALUE_SGIS is queried by calling GetFloatv with set to SAMPLE_MASK_VALUE_SGIS. SAMPLE_MASK_INVERT_SGIS is queried by calling GetBooleanv with 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 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 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 , 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 , 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 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