Name
gl.PolygonStipple -- set the polygon stippling pattern
Synopsis
gl.PolygonStipple(maskArray)
Function
Polygon stippling, like line stippling (See gl.LineStipple for details.), masks out certain fragments produced by rasterization, creating a pattern. Stippling is independent of polygon antialiasing.

maskArray is a table containing a 32*32 stipple pattern stored as a monochrome bitmap that uses only 1 bit per pixel. The bitmap is passed in a table that consists of chunks of 8 pixels packed into one byte. Thus, for a 32*32 stipple pattern you'll have to pass a table that contains 128 byte elements containing 8 pixels each. This can be either a one-dimensional table containing 128 byte entries or a two-dimensional table containing 32 subtables of 4 byte entries each (those 4 byte entries describe a row of 32 pixels each.) The data is passed to the GL in a contiguous memory block without any padding or special alignments so make sure that no exotic settings with gl.PixelStore() are active because gl.PolygonStipple() expects the pattern data to be stored in memory just like the pixel data supplied to a gl.DrawPixels() call with height and width both equal to 32, a pixel format of #GL_COLOR_INDEX, and data type of #GL_BITMAP. That is, the stipple pattern is represented as a 32x32 array of 1-bit color indices packed in unsigned bytes. gl.PixelStore() parameters like #GL_UNPACK_SWAP_BYTES and #GL_UNPACK_LSB_FIRST affect the assembling of the bits into a stipple pattern. Pixel transfer operations (shift, offset, pixel map) are not applied to the stipple image, however.

To enable and disable polygon stippling, call gl.Enable() and gl.Disable() with argument #GL_POLYGON_STIPPLE. Polygon stippling is initially disabled. If it's enabled, a rasterized polygon fragment with window coordinates xw and yw is sent to the next stage of the GL if and only if the (xw%32)th bit in the (yw%32)th row of the stipple pattern is 1 (one). When polygon stippling is disabled, it is as if the stipple pattern consists of all 1's.

Please consult an OpenGL reference manual for more information.

Inputs
maskArray
specifies a table that contains a 32x32 stipple pattern
Errors
#GL_INVALID_OPERATION is generated if gl.PolygonStipple() is executed between the execution of gl.Begin() and the corresponding execution of gl.End().

Associated gets
gl.GetPolygonStipple()

gl.IsEnabled() with argument #GL_POLYGON_STIPPLE


Show TOC