glLineStipple Subroutine

OpenGL 1.1 for AIX: Reference Manual

glLineStipple Subroutine

Purpose

Specifies the line stipple pattern.

Library

OpenGL C bindings library: libGL.a

C Syntax

void glLineStipple(GLint Factor, 
                  GLushort Pattern)

Parameters

Factor	Specifies a multiplier for each bit in the line stipple pattern. If Factor is 3, for example, each bit in the pattern is used three times before the next bit in the pattern is used. Factor is clamped to the range [1, 255] and defaults to 1.
Pattern	Specifies a 16-bit integer whose bit pattern determines which fragments of a line is drawn when the line is rasterized. Bit 0 is used first, and the default pattern is all 1s.

Description

Line stippling masks out certain fragments produced by rasterization; those fragments are not drawn. The masking is achieved by using three parameters: the 16-bit line stipple pattern (the Pattern parameter), the repeat count (the Factor parameter), and an integer stipple counter s.

Counter s is reset to 0 (zero) whenever the glBegin subroutine is called, and before each line segment of a glBegin(GL_LINES)glEnd sequence is generated. It is incremented after each fragment of a unit width aliased line segment is generated, or after each of the i fragments of an i width line segment are generated. The i fragments associated with count s are masked out if

Pattern bit floor (s/Factor) mod 16

is 0, otherwise these fragments are sent to the frame buffer. Bit 0 of the Pattern parameter is the least significant bit.

Antialiased lines are treated as a sequence of 1 times width rectangles for purposes of stippling. Rectangle s is rasterized or not rasterized, based on the fragment rule described for aliased lines, counting rectangles rather than groups of fragments.

Line stippling is enabled or disabled using the glEnable and glDisable subroutines with the GL_LINE_STIPPLE argument. When enabled, the line stipple pattern is applied as described in the preceding section. When disabled, it is as if the pattern were all 1s. Initially, line stippling is disabled.

Errors

GL_INVALID_OPERATION

The glLineStipple subroutine is called between a call to glBegin and the corresponding call to glEnd.

Associated Gets

Associated gets for the glLineStipple subroutine are as follows. (See the glGet subroutine for more information.)

glGet with argument GL_LINE_STIPPLE_PATTERN

glGet with argument GL_LINE_STIPPLE_REPEAT

glIsEnabled with argument GL_LINE_STIPPLE.

Files

/usr/include/GL/gl.h

Contains C language constants, variable type definitions, and ANSI function prototypes for OpenGL.

Related Information

The glBegin subroutine, glEnable or Disable subroutine, glLineWidth subroutine, glPolygonStipple subroutine.

OpenGL Overview.