glPolygonStipple.3   [plain text]

'\" e  
'\"macro stdmacro
.ds Vn Version 1.2
.ds Dt 24 September 1999
.ds Re Release 1.2.1
.ds Dp May 22 14:46
.ds Dm 8 May 22 14:
.ds Xs 22714     4
.TH GLPOLYGONSTIPPLE 3G
.SH NAME
.B "glPolygonStipple
\- set the polygon stippling pattern

.SH C SPECIFICATION
void \f3glPolygonStipple\fP(
const GLubyte \fI*mask\fP )
.nf
.fi

.EQ
delim $$
.EN
.SH PARAMETERS
.TP \w'\f2mask\fP\ \ 'u 
\f2mask\fP
Specifies a pointer to a $32 ~times~ 32$ stipple pattern that will be unpacked
from memory in the same way that \%\f3glDrawPixels\fP unpacks pixels.
.SH DESCRIPTION
Polygon stippling,
like line stippling
(see \%\f3glLineStipple\fP),
masks out certain fragments produced by rasterization,
creating a pattern.
Stippling is independent of polygon antialiasing.
.P
\f2mask\fP is a pointer to a $32 ~times~ 32$ stipple pattern that is stored
in memory just like the pixel data supplied to a \%\f3glDrawPixels\fP
call with 
.I
height
and
.I width
both equal to 32, a pixel 
of \%\f3GL_COLOR_INDEX\fP, and data type 
of \%\f3GL_BITMAP\fP.
That is,
the stipple pattern is represented as a $32 ~times~ 32$ array
of 1-bit color indices packed in unsigned bytes.
\%\f3glPixelStore\fP parameters like \%\f3GL_UNPACK_SWAP_BYTES\fP
and \%\f3GL_UNPACK_LSB_FIRST\fP 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.
.P
To enable and disable polygon stippling, call
\%\f3glEnable\fP and \%\f3glDisable\fP
with argument \%\f3GL_POLYGON_STIPPLE\fP. Polygon stippling is initially
disabled. If it's enabled,
a rasterized polygon fragment with window coordinates $x sub w$ and $y sub w$
is sent to the next stage of the GL if and only if the
($x sub w~roman mod~32$)th bit in the ($y sub w~roman mod~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.
.SH ERRORS
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glPolygonStipple\fP
is executed between the execution of \%\f3glBegin\fP
and the corresponding execution of \%\f3glEnd\fP.
.SH ASSOCIATED GETS
\%\f3glGetPolygonStipple\fP
.br
\%\f3glIsEnabled\fP with argument \%\f3GL_POLYGON_STIPPLE\fP
.SH SEE ALSO
\%\f3glDrawPixels\fP,
\%\f3glLineStipple\fP,
\%\f3glPixelStore\fP,
\%\f3glPixelTransfer\fP