upstream-doc/man2/glLineStipple.xml

   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="glLineStipple">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glLineStipple</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glLineStipple</refname>
  17         <refpurpose>specify the line stipple pattern</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glLineStipple</function></funcdef>
  23                 <paramdef>GLint <parameter>factor</parameter></paramdef>
  24                 <paramdef>GLushort <parameter>pattern</parameter></paramdef>
  25             </funcprototype>
  26         </funcsynopsis>
  27     </refsynopsisdiv>
  28     <!-- eqn: ignoring delim $$ -->
  29     <refsect1 id="parameters"><title>Parameters</title>
  30         <variablelist>
  31         <varlistentry>
  32             <term><parameter>factor</parameter></term>
  33             <listitem>
  34                 <para>
  35                     Specifies a multiplier for each bit in the line stipple pattern.
  36                     If <parameter>factor</parameter> is 3,
  37                     for example,
  38                     each bit in the pattern is used three times
  39                     before the next bit in the pattern is used.
  40                     <parameter>factor</parameter> is clamped to the range [1, 256] and defaults to 1.
  41                 </para>
  42             </listitem>
  43         </varlistentry>
  44         <varlistentry>
  45             <term><parameter>pattern</parameter></term>
  46             <listitem>
  47                 <para>
  48                     Specifies a 16-bit integer whose bit pattern determines
  49                     which fragments of a line will be drawn when the line is rasterized.
  50                     Bit zero is used first; the default pattern is all 1's.
  51                 </para>
  52             </listitem>
  53         </varlistentry>
  54         </variablelist>
  55     </refsect1>
  56     <refsect1 id="description"><title>Description</title>
  57         <para>
  58             Line stippling masks out certain fragments produced by rasterization;
  59             those fragments will not be drawn.
  60             The masking is achieved by using three parameters:
  61             the 16-bit line stipple pattern <parameter>pattern</parameter>,
  62             the repeat count <parameter>factor</parameter>,
  63             and an integer stipple counter
  64             <inlineequation><mml:math><mml:mi mathvariant="italic">s</mml:mi></mml:math></inlineequation>.
  65         </para>
  66         <para>
  67             Counter
  68             <inlineequation><mml:math><mml:mi mathvariant="italic">s</mml:mi></mml:math></inlineequation>
  69             is reset to 0 whenever <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> is called
  70             and before each line segment of a <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>(<constant>GL_LINES</constant>)/<citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>
  71             sequence is generated.
  72             It is incremented after each fragment of a unit width aliased line segment
  73             is generated
  74             or after each
  75             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
  76             fragments of an
  77             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
  78             width line segment are generated.
  79             The
  80             <inlineequation><mml:math><mml:mi mathvariant="italic">i</mml:mi></mml:math></inlineequation>
  81             fragments associated with count
  82             <inlineequation><mml:math><mml:mi mathvariant="italic">s</mml:mi></mml:math></inlineequation>
  83             are masked out if
  84         </para>
  85         <para>
  86             <parameter>pattern</parameter> bit
  87             <inlineequation><mml:math>
  88                 <!-- eqn: (s  /  factor)  mod  16:-->
  89                 <mml:mrow>
  90                     <mml:mfenced open="(" close=")">
  91                         <mml:mfrac>
  92                             <mml:mi mathvariant="italic">s</mml:mi>
  93                             <mml:mi mathvariant="italic">factor</mml:mi>
  94                         </mml:mfrac>
  95                     </mml:mfenced>
  96                     <mml:mo>%</mml:mo>
  97                     <mml:mn>16</mml:mn>
  98                 </mml:mrow>
  99             </mml:math></inlineequation>
 100         </para>
 101         <para>
 102             is 0, otherwise these fragments are sent to the frame buffer.
 103             Bit zero of <parameter>pattern</parameter> is the least significant bit.
 104         </para>
 105         <para>
 106             Antialiased lines are treated as a sequence of
 107             <inlineequation><mml:math>
 108                 <!-- eqn: 1 times width:-->
 109                 <mml:mrow>
 110                     <mml:mn>1</mml:mn>
 111                     <mml:mo>&times;</mml:mo>
 112                     <mml:mi mathvariant="italic">width</mml:mi>
 113                 </mml:mrow>
 114             </mml:math></inlineequation>
 115             rectangles
 116             for purposes of stippling.
 117             Whether rectangle
 118             <inlineequation><mml:math><mml:mi mathvariant="italic">s</mml:mi></mml:math></inlineequation>
 119             is rasterized or not depends on the fragment rule
 120             described for aliased lines,
 121             counting rectangles rather than groups of fragments.
 122         </para>
 123         <para>
 124             To enable and disable line stippling, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry>
 125             with argument <constant>GL_LINE_STIPPLE</constant>.
 126             When enabled,
 127             the line stipple pattern is applied as described above.
 128             When disabled,
 129             it is as if the pattern were all 1's.
 130             Initially, line stippling is disabled.
 131         </para>
 132     </refsect1>
 133     <refsect1 id="errors"><title>Errors</title>
 134         <para>
 135             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glLineStipple</function>
 136             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 137             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 138         </para>
 139     </refsect1>
 140     <refsect1 id="associatedgets"><title>Associated Gets</title>
 141         <para>
 142             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_LINE_STIPPLE_PATTERN</constant>
 143         </para>
 144         <para>
 145             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_LINE_STIPPLE_REPEAT</constant>
 146         </para>
 147         <para>
 148             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_LINE_STIPPLE</constant>
 149         </para>
 150     </refsect1>
 151     <refsect1 id="seealso"><title>See Also</title>
 152         <para>
 153             <citerefentry><refentrytitle>glLineWidth</refentrytitle></citerefentry>,
 154             <citerefentry><refentrytitle>glPolygonStipple</refentrytitle></citerefentry>
 155         </para>
 156     </refsect1>
 157     <refsect1 id="Copyright"><title>Copyright</title>
 158         <para>
 159             Copyright <trademark class="copyright"></trademark> 1991-2006
 160             Silicon Graphics, Inc. This document is licensed under the SGI
 161             Free Software B License. For details, see
 162             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 163         </para>
 164     </refsect1>
 165 </refentry>