Drawing in Space: Geometric Primitives and Buffers in OpenGL

This chapter is from the book 

Reference

glBegin

Purpose: Denotes the beginning of a group of vertices that define one or more primitives.

Include File: <gl.h>

Syntax:

void glBegin(GLenum mode);

Description: This function is used in conjunction with glEnd to delimit the vertices of an OpenGL primitive. You can include multiple vertices sets within a single glBegin/glEnd pair, as long as they are for the same primitive type. You can also make other settings with additional OpenGL commands that affect the vertices following them. You can call only these OpenGL functions within a glBegin/glEnd sequence: glVertex, glColor, glNormal, glEvalCoord, glCallList, glCallLists, glTexCoord, glEdgeFlag, and glMaterial. Note that display lists (glCallList(s)) may only contain the other functions listed here.

Parameters:

mode GLenum: This value specifies the primitive to be constructed. It can be any of the values in Table 3.1.

Table 3.1 OpenGL Primitives Supported by glBegin

Mode	Primitive Type
GL_POINTS	The specified vertices are used to create a single point each.
GL_LINES	The specified vertices are used to create line segments. Every two vertices specify a single and separate line segment. If the number of vertices is odd, the last one is ignored.
GL_LINE_STRIP	The specified vertices are used to create a line strip. After the first vertex, each subsequent vertex specifies the next point to which the line is extended.
GL_LINE_LOOP	This mode behaves like GL_LINE_STRIP, except a final line segment is drawn between the last and the first vertex specified. This is typically used to draw closed regions that might violate the rules regarding GL_POLYGON usage.
GL_TRIANGLES	The specified vertices are used to construct triangles. Every three vertices specify a new triangle. If the number of vertices is not evenly divisible by three, the extra vertices are ignored.
GL_TRIANGLE_STRIP	The specified vertices are used to create a strip of triangles. After the first three vertices are specified, each of any subsequent vertices is used with the two preceding ones to construct the next triangle. Each triplet of vertices (after the initial set) is automatically rearranged to ensure consistent winding of the triangles.
GL_TRIANGLE_FAN	The specified vertices are used to construct a triangle fan. The first vertex serves as an origin, and each vertex after the third is combined with the foregoing one and the origin. Any number of triangles may be fanned in this manner.
GL_QUADS	Each set of four vertices is used to construct a quadrilateral (a four-sided polygon). If the number of vertices is not evenly divisible by four, the remaining ones are ignored.
GL_QUAD_STRIP	The specified vertices are used to construct a strip of quadrilaterals. One quadrilateral is defined for each pair of vertices after the first pair. Unlike the vertex ordering for GL_QUADS, each pair of vertices is used in the reverse order specified to ensure consistent winding.
GL_POLYGON	The specified vertices are used to construct a convex polygon. The polygon edges must not intersect. The last vertex is automatically connected to the first vertex to ensure the polygon is closed.

Returns: None.

See Also: glEnd, glVertex

glClearDepth

Purpose: Specifies a depth value to be used for depth buffer clears.

Include File: <gl.h>

Syntax:

void glClearDepth(GLclampd depth);

Description: This function sets the depth value that is used when clearing the depth buffer with glClear(GL_DEPTH_BUFFER_BIT).

Parameters:

depth GLclampd: The clear value for the depth buffer.

Returns: None.

See Also: glClear, glDepthFunc, glDepthMask, glDepthRange

glClearStencil

Purpose: Specifies a stencil value to be used for stencil buffer clears.

Include File: <gl.h>

Syntax:

void glClearStencil(GLint value);

Description: This function sets the stencil value that is used when clearing the stencil buffer with glClear(GL_STENCIL_BUFFER_BIT).

Parameters:

value GLint: The clear value for the stencil buffer.

Returns: None.

See Also: glStencilFunc, glStencilOp

glCullFace

Purpose: Specifies whether the front or back of polygons should be eliminated from drawing.

Include File: <gl.h>

Syntax:

void glCullFace(GLenum mode);

Description: This function eliminates all drawing operations on either the front or back of a polygon. This eliminates unnecessary rendering computations when the back side of polygons are never visible, regardless of rotation or translation of the objects. Culling is enabled or disabled by calling glEnable or glDisable with the GL_CULL_FACE parameter. The front and back of the polygon are defined by use of glFrontFace and by the order in which the vertices are specified (clockwise or counterclockwise winding).

Parameters:

mode GLenum: Specifies which face of polygons should be culled. May be either GL_FRONT or GL_BACK.

Returns: None.

See Also: glFrontFace, glLightModel

glDepthFunc

Purpose: Specifies the depth-comparison function used against the depth buffer to decide whether color fragments should be rendered.

Include File: <gl.h>

Syntax:

void glDepthFunc(GLenum func);

Description: Depth testing is the primary means of hidden surface removal in OpenGL. When a color value is written to the color buffer, a corresponding depth value is written to the depth buffer. When depth testing is enabled by calling glEnable(GL_DEPTH_TEST), color values are not written to the color buffer unless the corresponding depth value passes the depth test with the depth value already present. This function allows you to tweak the function used for depth buffer comparisons. The default function is GL_LESS.

Parameters:

func GLenum: Specifies which depth-comparison function to use. Valid values are listed in Table 3.2.

Table 3.2 Depth Function Enumerants

Depth Function	Meaning
GL_NEVER	Fragments never pass the depth test.
GL_LESS	Fragments pass only if the incoming z value is less than the z value already present in the z buffer. This is the default value.
GL_LEQUAL	Fragments pass only if the incoming z value is less than or equal to the z value already present in the z buffer.
GL_EQUAL	Fragments pass only if the incoming z value is equal to the z value already present in the z buffer.
GL_GREATER	Fragments pass only if the incoming z value is greater than the z value already present in the z buffer.
GL_NOTEQUAL	Fragments pass only if the incoming z value is not equal to the z value already present in the z buffer.
GL_GEQUAL	Fragments pass only if the incoming z value is greater than or equal to the z value already present in the z buffer.
GL_ALWAYS	Fragments always pass regardless of any z value.

Returns: None.

See Also: glClearDepth, glDepthMask, glDepthRange

glDepthMask

Purpose: Selectively allows or disallows changes to the depth buffer.

Include File: <gl.h>

Syntax:

void glDepthMask(GLBoolean flag);

Description: If a depth buffer is created for an OpenGL rendering context, OpenGL will calculate and store depth values. Even when depth testing is disabled, depth values are still calculated and stored in the depth buffer by default. This function allows you to selectively enable and disable writing to the depth buffer.

Parameters:

flag GLboolean: When this parameter is set to GL_TRUE, depth buffer writes are enabled (default). Setting this parameter to GL_FALSE disables changes to the depth buffer.

Returns: None.

See Also: glClearDepth, glDepthFunc, glDepthRange

glDepthRange

Purpose: Allows a mapping of z values to window coordinates from normalized device coordinates.

Include File: <gl.h>

Syntax:

void glDepthRange(GLclampd zNear, GLclampd zFar);

Description: Normally, depth buffer values are stored internally in the range from –1.0 to 1.0. This function allows a specific linear mapping of depth values to a normalized range of window z coordinates. The default range for window z values is 0 to 1 corresponding to the near and far clipping planes.

Parameters:

zNear GLclampd: A clamped value that represents the nearest possible window z value.

zFar GLclampd: A clamped value that represents the largest possible window z value.

Returns: None.

See Also: glClearDepth, glDepthMask, glDepthFunc

glDrawBuffer

Purpose: Redirects OpenGL rendering to a specific color buffer.

Include File: <gl.h>

Syntax:

void glDrawBuffer(GLenum mode);

Description: By default, OpenGL renders to the back color buffer for double-buffered rendering contexts and to the front for single-buffered rendering contexts. This function allows you to direct OpenGL rendering to any available color buffer. Note that many implementations do not support left and right (stereo) or auxiliary color buffers. In the case of stereo contexts, the modes that omit references to the left and right channels will render to both channels. For example, specifying GL_FRONT for a stereo context will actually render to both the left and right front buffers, and GL_FRONT_AND_BACK will render to up to four buffers simultaneously.

Parameters:

mode GLenum: A constant flag that specifies which color buffer should be the render target. Valid values for this parameter are listed in Table 3.3.

Table 3.3 Color Buffer Destinations

Constant	Description
GL_NONE	Do not write anything to any color buffer.
GL_FRONT_LEFT	Write only to the front-left color buffer.
GL_FRONT_RIGHT	Write only to the front-right color buffer.
GL_BACK_LEFT	Write only to the back-left color buffer.
GL_BACK_RIGHT	Write only to the back-right color buffer.
GL_FRONT	Write only to the front color buffer. This is the default value for single-buffered rendering contexts.
GL_BACK	Write only to the back color buffer. This is the default value for double-buffered rendering contexts.
GL_LEFT	Write only to the left color buffer.
GL_RIGHT	Write only to the right color buffer.
GL_FRONT_AND_BACK	Write to both the front and back color buffers.
GL_AUXi	Write only to the auxiliary buffer i, with i being a value between 0 and GL_AUX_BUFFERS – 1.

Returns: None.

See Also: glClear, glColorMask

glEdgeFlag

Purpose: Flags polygon edges as either boundary or nonboundary edges. You can use this to determine whether interior surface lines are visible.

Include File: <gl.h>

Variations:

void glEdgeFlag(GLboolean flag);
void glEdgeFlagv(const GLboolean *flag);

Description: When two or more polygons are joined to form a larger region, the edges on the outside define the boundary of the newly formed region. This function flags inside edges as nonboundary. This is used only when the polygon mode is set to either GL_LINE or GL_POINT.

Parameters:

flag GLboolean: Sets the edge flag to this value, True or False.

*flag const GLboolean *: A pointer to a value that is used for the edge flag.

Returns: None.

See Also: glBegin, glPolygonMode

glEnd

Purpose: Terminates a list of vertices that specify a primitive initiated by glBegin.

Include File: <gl.h>

Syntax:

void glEnd();

Description: This function is used in conjunction with glBegin to delimit the vertices of an OpenGL primitive. You can include multiple vertices sets within a single glBegin/glEnd pair, as long as they are for the same primitive type. You can also make other settings with additional OpenGL commands that affect the vertices following them. You can call only these OpenGL functions within a glBegin/glEnd sequence: glVertex, glColor, glIndex, glNormal, glEvalCoord, glCallList, glCallLists, glTexCoord, glEdgeFlag, and glMaterial.

Returns: None.

See Also: glBegin

glFrontFace

Purpose: Defines which side of a polygon is the front or back.

Include File: <gl.h>

Syntax:

void glFrontFace(GLenum mode);

Description: When a scene is made up of objects that are closed (you cannot see the inside), color or lighting calculations on the inside of the object are unnecessary. The glCullFace function turns off such calculations for either the front or back of polygons. The glFrontFace function determines which side of the polygons is considered the front. If the vertices of a polygon as viewed from the front are specified so that they travel clockwise around the polygon, the polygon is said to have clockwise winding. If the vertices travel counterclockwise, the polygon is said to have counterclockwise winding. This function allows you to specify either the clockwise or counterclockwise wound face to be the front of the polygon.

Parameters:

mode GLenum: Specifies the orientation of front-facing polygons: clockwise (GL_CW) or counterclockwise (GL_CCW).

Returns: None.

See Also: glCullFace, glLightModel, glPolygonMode, glMaterial

glGetPolygonStipple

Purpose: Returns the current polygon stipple pattern.

Include File: <gl.h>

Syntax:

void glGetPolygonStipple(GLubyte *mask);

Description: This function copies a 32-by-32-bit pattern that represents the polygon stipple pattern into a user-specified buffer. The pattern is copied to the memory location pointed to by mask. The packing of the pixels is affected by the last call to glPixelStore.

Parameters:

*mask GLubyte: A pointer to the place where the polygon stipple pattern is to be copied.

Returns: None.

See Also: glPolygonStipple, glLineStipple, glPixelStore

glLineStipple

Purpose: Specifies a line stipple pattern for line-based primitives GL_LINES, GL_LINE_STRIP, and GL_LINE_LOOP.

Include File: <gl.h>

Syntax:

void glLineStipple(GLint factor, GLushort pattern);

Description: This function uses the bit pattern to draw stippled (dotted and dashed) lines. The bit pattern begins with bit 0 (the rightmost bit), so the actual drawing pattern is the reverse of what is specified. The factor parameter is used to widen the number of pixels drawn or not drawn along the line specified by each bit in pattern. By default, each bit in the pattern specifies one pixel. To use line stippling, you must first enable stippling by calling

	glEnable(GL_LINE_STIPPLE);

Line stippling is disabled by default. If you are drawing multiple line segments, the pattern is reset for each new segment. That is, if a line segment is drawn such that it terminates halfway through the pattern, the next specified line segment is unaffected.

Parameters:

factor GLint: Specifies a multiplier that determines how many pixels will be affected by each bit in the pattern parameter. Thus, the pattern width is multiplied by this value. The default value is 1, and the maximum value is clamped to 255.

pattern GLushort: Sets the 16-bit stippling pattern. The least significant bit (bit 0) is used first for the stippling pattern. The default pattern is all 1s.

Returns: None.

See Also: glPolygonStipple

glLineWidth

Purpose: Sets the width of lines drawn with GL_LINES, GL_LINE_STRIP, or GL_LINE_LOOP.

Include File: <gl.h>

Syntax:

void glLineWidth(GLfloat width );

Description: This function sets the width in pixels of lines drawn with any of the line-based primitives.

You can get the current line width setting by calling

GLfloat fSize;
...
glGetFloatv(GL_LINE_WIDTH, &fSize);

The current line width setting will be returned in fSize. In addition, you can find the minimum and maximum supported line widths by calling

GLfloat fSizes[2];
...
glGetFloatv(GL_LINE_WIDTH_RANGE,fSizes);

In this instance, the minimum supported line width will be returned in fSizes[0], and the maximum supported width will be stored in fSizes[1]. Finally, you can find the smallest supported increment between line widths by calling

GLfloat fStepSize;
...
glGetFloatv(GL_LINE_WIDTH_GRANULARITY,&fStepSize);

For any implementation of OpenGL, the only line width guaranteed to be supported is 1.0. For the Microsoft Windows generic implementation, the supported line widths range from 0.5 to 10.0, with a granularity of 0.125.

Parameters:

width GLfloat: Sets the width of lines that are drawn with the line primitives. The default value is 1.0.

Returns: None.

See Also: glPointSize

glPointSize

Purpose: Sets the point size of points drawn with GL_POINTS.

Include File: <gl.h>

Syntax:

void glPointSize(GLfloat size);

Description: This function sets the diameter in pixels of points drawn with the GL_POINTS primitive. You can get the current pixel size setting by calling

GLfloat fSize;
...
glGetFloatv(GL_POINT_SIZE, &fSize);

The current pixel size setting will be returned in fSize. In addition, you can find the minimum and maximum supported pixel sizes by calling

GLfloat fSizes[2];
...
glGetFloatv(GL_POINT_SIZE_RANGE,fSizes);

In this instance, the minimum supported point size will be returned in fSizes[0], and the maximum supported size will be stored in fSizes[1]. Finally, you can find the smallest supported increment between pixel sizes by calling

GLfloat fStepSize;
...
glGetFloatv(GL_POINT_SIZE_GRANULARITY,&fStepSize);

For any implementation of OpenGL, the only point size guaranteed to be supported is 1.0. For the Microsoft Windows generic implementation, the point sizes range from 0.5 to 10.0, with a granularity of 0.125.

Parameters:

size GLfloat: Sets the diameter of drawn points. The default value is 1.0.

Returns: None.

See Also: glLineWidth

glPolygonMode

Purpose: Sets the rasterization mode used to draw polygons.

Include File: <gl.h>

Syntax:

void glPolygonMode(GLenum face, GLenum mode);

Description: This function allows you to change how polygons are rendered. By default, polygons are filled or shaded with the current color or material properties. However, you may also specify that only the outlines or only the vertices are drawn. Furthermore, you may apply this specification to the front, back, or both sides of polygons.

Parameters:

face GLenum: Specifies which face of polygons is affected by the mode change: GL_FRONT, GL_BACK, or GL_FRONT_AND_BACK.

mode GLenum: Specifies the new drawing mode. GL_FILL is the default, producing filled polygons. GL_LINE produces polygon outlines, and GL_POINT plots only the points of the vertices. The lines and points drawn by GL_LINE and GL_POINT are affected by the edge flag set by glEdgeFlag.

Returns: None.

See Also: glEdgeFlag, glLineStipple, glLineWidth, glPointSize, glPolygonStipple

glPolygonOffset

Purpose: Sets the scale and units used to calculate depth values.

Include File: <gl.h>

Syntax:

void glPolygonOffset(GLfloat factor, GLfloat units);

Description: This function allows you to add or subtract an offset to a fragment's calculated depth value. The amount of offset is calculated by the following formula:

offset = (m * factor) + (r * units)

The value of m is calculated by OpenGL and represents the maximum depth slope of the polygon. The r value is the minimum value that will create a resolvable difference in the depth buffer, and is implementation dependent. Polygon offset applies only to polygons but affects lines and points when rendered as a result of a call to glPolygonMode. You enable or disable the offset value for each mode by using glEnable/glDisable with GL_POLYGON_OFFSET_FILL, GL_POLYGON_OFFSET_LINE, or GL_POLYGON_OFFSET_POINT.

Parameters:

factor GLfloat: Scaling factor used to create a depth buffer offset for each polygon. Zero by default.

units GLfloat: Value multiplied by an implementation-specific value to create a depth offset. Zero by default.

Returns: None.

See Also: glDepthFunc, glDepthRange, glPolygonMode

glPolygonStipple

Purpose: Sets the pattern used for polygon stippling.

Include File: <gl.h>

Syntax:

void glPolygonStipple(const GLubyte *mask );

Description: You can use a 32-by-32-bit stipple pattern for filled polygons by using this function and enabling polygon stippling by calling glEnable(GL_POLYGON_STIPPLE). The 1s in the stipple pattern are filled with the current color, and 0s are not drawn.

Parameters:

*mask const GLubyte: Points to a 32-by-32-bit storage area that contains the stipple pattern. The packing of bits within this storage area is affected by glPixelStore. By default, the MSB (most significant bit) is read first when determining the pattern.

Returns: None.

See Also: glLineStipple, glGetPolygonStipple, glPixelStore

glScissor

Purpose: Defines a scissor box in window coordinates outside of which no drawing occurs.

Include File: <gl.h>

Syntax:

void glScissor(GLint x, GLint y, GLint width, GLint height);

Description: This function defines a rectangle in window coordinates called the scissor box. When the scissor test is enabled with glEnable(GL_SCISSOR_TEST), OpenGL drawing commands and buffer operations occur only within the scissor box.

Parameters:

x,y GLint: The lower-left corner of the scissor box, in window coordinates.

width GLint: The width of the scissor box in pixels.

height GLint: The height of the scissor box in pixels.

Returns: None.

See Also: glStencilFunc, glStencilOp

glStencilFunc

Purpose: Sets the comparison function, reference value, and mask for a stencil test.

Include File: <gl.h>

Syntax:

void glStencilFunc(GLenum func, GLint ref, GLuint mask);

Description: When the stencil test is enabled using glEnable(GL_STENCIL_TEST), the stencil function is used to determine whether a color fragment should be discarded or kept (drawn). The value in the stencil buffer is compared to the reference value ref, using the comparison function specified by func. Both the reference value and stencil buffer value may be bitwise ANDed with the mask. Valid comparison functions are given in Table 3.4. The result of the stencil test also causes the stencil buffer to be modified according to the behavior specified in the function glStencilOp.

Parameters:

func GLenum: Stencil comparison function. Valid values are listed in Table 3.4.

ref GLint: Reference value against which the stencil buffer value is compared.

mask GLuint: Binary mask value applied to both the reference and stencil buffer values.

Table 3.4 Stencil Test Comparison Functions

Constant	Meaning
GL_NEVER	Never pass the stencil test.
GL_ALWAYS	Always pass the stencil test.
GL_LESS	Pass only if the reference value is less than the stencil buffer value.
GL_LEQUAL	Pass only if the reference value is less than or equal to the stencil buffer value.
GL_EQUAL	Pass only if the reference value is equal to the stencil buffer value.
GL_GEQUAL	Pass only if the reference value is greater than or equal to the stencil buffer value.
GL_GREATER	Pass only if the reference value is greater than the stencil buffer value.
GL_NOTEQUAL	Pass only if the reference value is not equal to the stencil buffer value.

Returns: None.

See Also: glStencilOp, glClearStencil

glStencilMask

Purpose: Selectively allows or disallows changes to the stencil buffer.

Include File: <gl.h>

Syntax:

void glStencilMask(GLboolean flag);

Description: If a stencil buffer is created for an OpenGL rendering context, OpenGL will calculate, store, and make use of stencil values when stenciling is enabled. When the stencil test is disabled, values are still calculated and stored in the stencil buffer. This function allows you to selectively enable and disable writing to the stencil buffer.

Parameters:

flag GLboolean: When this parameter is set to GL_TRUE, stencil buffer writes are enabled (default). Setting this parameter to GL_FALSE disables changes to the depth buffer.

Returns: None.

See Also: glStencilOp, glClearStencil, glStencilMask

glStencilOp

Purpose: Specifies what action to take in regards to the stored value in the stencil buffer for a rendered fragment.

Include File: <gl.h>

Syntax:

void glStencilOp(GLenum sfail, GLenum zfail, GLenum zpass);

Description: This function describes what action to take when a fragment fails the stencil test. Even when fragments do not pass the stencil test and are not produced in the color buffer, the stencil buffer can still be modified by setting the appropriate action for the sfail parameter. In addition, even when the stencil test passes, the zfail and zpass parameters describe the desired action based on that fragment's depth buffer test. The valid actions and their constants are given in Table 3.5.

Parameters:

sfail GLenum: Operation to perform when the stencil test fails.

zfail GLenum: Operation to perform when the depth test fails.

zPass GLenum: Operation to perform when the depth test passes.

Table 3.5 Stencil Operation Constants

Constant	Description
GL_KEEP	Keep the current stencil buffer value.
GL_ZERO	Set the current stencil buffer value to 0.
GL_REPLACE	Replace the stencil buffer value with the reference value specified in glStencilFunc.
GL_INCR	Increment the stencil buffer value. Clamped to the bit range of the stencil buffer.
GL_DECR	Decrement the stencil buffer value. Clamped to the bit range of the stencil buffer.
GL_INVERT	Bitwise-invert the current stencil buffer value.
GL_INCR_WRAP	Increment the current stencil buffer value. When the maximum representable value for the given stencil buffer's bit depth is reached, the value wraps back to 0.
GL_DECR_WRAP	Decrement the current stencil buffer value. When the value is decremented below 0, the stencil buffer value wraps to the highest possible positive representation for its bit depth.

Returns: None.

See Also: glStencilFunc, glClearStencil

glVertex

Purpose: Specifies the 3D coordinates of a vertex.

Include File: <gl.h>

Variations:

void glVertex2d(GLdouble x, GLdouble y);
void glVertex2f(GLfloat x, GLfloat y);
void glVertex2i(GLint x, GLint y);
void glVertex2s(GLshort x, GLshort y);
void glVertex3d(GLdouble x, GLdouble y, GLdouble z);
void glVertex3f(GLfloat x, GLfloat y, GLfloat z);
void glVertex3i(GLint x, GLint y, GLint z);
void glVertex3s(GLshort x, GLshort y, GLshort z);
void glVertex4d(GLdouble x, GLdouble y, GLdouble z, GLdouble w);
void glVertex4f(GLfloat x, GLfloat y, GLfloat z, GLfloat w);
void glVertex4i(GLint x, GLint y, GLint z, GLint w);
void glVertex4s(GLshort x, GLshort y, GLshort z, GLshort w);
void glVertex2dv(const GLdouble *v);
void glVertex2fv(const GLfloat *v);
void glVertex2iv(const GLint *v);
void glVertex2sv(const GLshort *v);
void glVertex3dv(const GLdouble *v);
void glVertex3fv(const GLfloat *v);
void glVertex3iv(const GLint *v);
void glVertex3sv(const GLshort *v);
void glVertex4dv(const GLdouble *v);
void glVertex4fv(const GLfloat *v);
void glVertex4iv(const GLint *v);
void glVertex4sv(const GLshort *v);

Description: This function is used to specify the vertex coordinates of the points, lines, and polygons specified by a previous call to glBegin. You cannot call this function outside the scope of a glBegin/glEnd pair.

Parameters:

x, y, z The x, y, and z coordinates of the vertex. When z is not specified, the default value is 0.0.

w The w coordinate of the vertex. This coordinate is used for scaling purposes and by default is set to 1.0. Scaling occurs by dividing the other three coordinates by this value.

*v An array of values that contain the two, three, or four values needed to specify the vertex.

Returns: None.

See Also: glBegin, glEnd