1 <?xml version=
"1.0" encoding=
"UTF-8"?>
2 <!DOCTYPE book PUBLIC
"-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
3 "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
4 <refentry id=
"glPolygonStipple">
9 <holder>Silicon Graphics, Inc.
</holder>
12 <refentrytitle>glPolygonStipple
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glPolygonStipple
</refname>
17 <refpurpose>set the polygon stippling pattern
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glPolygonStipple
</function></funcdef>
23 <paramdef>const GLubyte *
<parameter>pattern
</parameter></paramdef>
27 <!-- eqn: ignoring delim $$ -->
28 <refsect1 id=
"parameters"><title>Parameters
</title>
31 <term><parameter>pattern
</parameter></term>
34 Specifies a pointer to a
35 <inlineequation><mml:math>
36 <!-- eqn: 32 times 32:-->
39 <mml:mo>×</mml:mo>
42 </mml:math></inlineequation>
43 stipple pattern that will be unpacked
44 from memory in the same way that
<citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry> unpacks pixels.
50 <refsect1 id=
"description"><title>Description
</title>
54 (see
<citerefentry><refentrytitle>glLineStipple
</refentrytitle></citerefentry>),
55 masks out certain fragments produced by rasterization,
57 Stippling is independent of polygon antialiasing.
60 <parameter>pattern
</parameter> is a pointer to a
61 <inlineequation><mml:math>
62 <!-- eqn: 32 times 32:-->
65 <mml:mo>×</mml:mo>
68 </mml:math></inlineequation>
69 stipple pattern that is stored
70 in memory just like the pixel data supplied to a
<citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry>
75 <emphasis>width
</emphasis>
76 both equal to
32, a pixel format
77 of
<constant>GL_COLOR_INDEX
</constant>, and data type
78 of
<constant>GL_BITMAP
</constant>.
80 the stipple pattern is represented as a
81 <inlineequation><mml:math>
82 <!-- eqn: 32 times 32:-->
85 <mml:mo>×</mml:mo>
88 </mml:math></inlineequation>
90 of
1-bit color indices packed in unsigned bytes.
91 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry> parameters like
<constant>GL_UNPACK_SWAP_BYTES
</constant>
92 and
<constant>GL_UNPACK_LSB_FIRST
</constant> affect the assembling of the bits into a
94 Pixel transfer operations
95 (shift, offset, pixel map)
96 are not applied to the stipple image,
100 If a non-zero named buffer object is bound to the
<constant>GL_PIXEL_UNPACK_BUFFER
</constant> target
101 (see
<citerefentry><refentrytitle>glBindBuffer
</refentrytitle></citerefentry>) while a stipple pattern is
102 specified,
<parameter>pattern
</parameter> is treated as a byte offset into the buffer object's data store.
105 To enable and disable polygon stippling, call
106 <citerefentry><refentrytitle>glEnable
</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>glDisable
</refentrytitle></citerefentry>
107 with argument
<constant>GL_POLYGON_STIPPLE
</constant>. Polygon stippling is initially
108 disabled. If it's enabled,
109 a rasterized polygon fragment with window coordinates
110 <inlineequation><mml:math>
111 <!-- eqn: x sub w:-->
112 <mml:msub><mml:mi mathvariant=
"italic">x
</mml:mi>
113 <mml:mi mathvariant=
"italic">w
</mml:mi>
115 </mml:math></inlineequation>
117 <inlineequation><mml:math>
118 <!-- eqn: y sub w:-->
119 <mml:msub><mml:mi mathvariant=
"italic">y
</mml:mi>
120 <mml:mi mathvariant=
"italic">w
</mml:mi>
122 </mml:math></inlineequation>
123 is sent to the next stage of the GL if and only if the
124 (
<inlineequation><mml:math>
125 <!-- eqn: x sub w mod 32:-->
127 <mml:msub><mml:mi mathvariant=
"italic">x
</mml:mi>
128 <mml:mi mathvariant=
"italic">w
</mml:mi>
133 </mml:math></inlineequation>)th
135 (
<inlineequation><mml:math>
136 <!-- eqn: y sub w mod 32:-->
138 <mml:msub><mml:mi mathvariant=
"italic">y
</mml:mi>
139 <mml:mi mathvariant=
"italic">w
</mml:mi>
144 </mml:math></inlineequation>)th
146 of the stipple pattern is
1 (one).
147 When polygon stippling is disabled, it is as if the stipple pattern
151 <refsect1 id=
"errors"><title>Errors
</title>
153 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
154 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the buffer object's data store is currently mapped.
157 <constant>GL_INVALID_OPERATION
</constant> is generated if a non-zero buffer object name is bound to the
158 <constant>GL_PIXEL_UNPACK_BUFFER
</constant> target and the data would be unpacked from the buffer
159 object such that the memory reads required would exceed the data store size.
162 <constant>GL_INVALID_OPERATION
</constant> is generated if
<function>glPolygonStipple
</function>
163 is executed between the execution of
<citerefentry><refentrytitle>glBegin
</refentrytitle></citerefentry>
164 and the corresponding execution of
<citerefentry><refentrytitle>glEnd
</refentrytitle></citerefentry>.
167 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
169 <citerefentry><refentrytitle>glGetPolygonStipple
</refentrytitle></citerefentry>
172 <citerefentry><refentrytitle>glIsEnabled
</refentrytitle></citerefentry> with argument
<constant>GL_POLYGON_STIPPLE
</constant>
175 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_PIXEL_UNPACK_BUFFER_BINDING
</constant>
178 <refsect1 id=
"seealso"><title>See Also
</title>
180 <citerefentry><refentrytitle>glDrawPixels
</refentrytitle></citerefentry>,
181 <citerefentry><refentrytitle>glLineStipple
</refentrytitle></citerefentry>,
182 <citerefentry><refentrytitle>glPixelStore
</refentrytitle></citerefentry>,
183 <citerefentry><refentrytitle>glPixelTransfer
</refentrytitle></citerefentry>
186 <refsect1 id=
"Copyright"><title>Copyright
</title>
188 Copyright
<trademark class=
"copyright"></trademark> 1991-
2006
189 Silicon Graphics, Inc. This document is licensed under the SGI
190 Free Software B License. For details, see
191 <ulink url=
"http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/
</ulink>.