[Previous Section] [Back to Table of Contents] [Next Section]

OpenGL Reference Manual (Addison-Wesley Publishing Company)


Chapter 6
GLU Reference Pages

This chapter contains the reference pages, in alphabetical order, for all the routines comprising the OpenGL Utility Library (GLU).


gluBeginCurve
gluEndCurve

NAME

gluBeginCurve, gluEndCurve - delimit a NURBS curve definition

C SPECIFICATION

void gluBeginCurve( GLUnurbsObj *nobj )
void gluEndCurve( GLUnurbsObj *nobj )

PARAMETERS

nobj

Specifies the NURBS object (created with gluNewNurbsRenderer).

DESCRIPTION

Use gluBeginCurve to mark the beginning of a NURBS curve definition. After calling gluBeginCurve, make one or more calls to gluNurbsCurve to define the attributes of the curve. Exactly one of the calls to gluNurbsCurve must have a curve type of GL_MAP1_VERTEX_3 or GL_MAP1_VERTEX_4. To mark the end of the NURBS curve definition, call gluEndCurve.

OpenGL evaluators are used to render the NURBS curve as a series of line segments. Evaluator state is preserved during rendering with glPushAttrib(GL_EVAL_BIT) and glPopAttrib(). See the "glPushAttrib" reference page for details on exactly what state these calls preserve.

EXAMPLE

The following commands render a textured NURBS curve with normals; texture coordinates and normals are also specified as NURBS curves:

gluBeginCurve(nobj);
   gluNurbsCurve(nobj, ..., GL_MAP1_TEXTURE_COORD_2);
   gluNurbsCurve(nobj, ..., GL_MAP1_NORMAL);
   gluNurbsCurve(nobj, ..., GL_MAP1_VERTEX_4);
gluEndCurve(nobj);

SEE ALSO

"gluBeginSurface", "gluBeginTrim", "gluNewNurbsRenderer", "gluNurbsCurve", "glPopAttrib", "glPushAttrib"


gluBeginPolygon
gluEndPolygon

NAME

gluBeginPolygon, gluEndPolygon - delimit a polygon description

C SPECIFICATION

void gluBeginPolygon( GLUtriangulatorObj *tobj )
void gluEndPolygon( GLUtriangulatorObj *tobj )

PARAMETERS

tobj

Specifies the tessellation object (created with gluNewTess).

DESCRIPTION

gluBeginPolygon and gluEndPolygon delimit the definition of a nonconvex polygon. To define such a polygon, first call gluBeginPolygon. Then define the contours of the polygon by calling gluTessVertex for each vertex and gluNextContour to start each new contour. Finally, call gluEndPolygon to signal the end of the definition. See the "gluTessVertex" and "gluNextContour" reference pages for more details.

Once gluEndPolygon is called, the polygon is tessellated, and the resulting triangles are described through callbacks. See "gluTessCallback" for descriptions of the callback functions.

EXAMPLE

A quadrilateral with a triangular hole in it can be described like this:

gluBeginPolygon(tobj);
   gluTessVertex(tobj, v1, v1);
   gluTessVertex(tobj, v2, v2);
   gluTessVertex(tobj, v3, v3);
   gluTessVertex(tobj, v4, v4);
gluNextContour(tobj, GLU_INTERIOR);
   gluTessVertex(tobj, v5, v5);
   gluTessVertex(tobj, v6, v6);
   gluTessVertex(tobj, v7, v7);
gluEndPolygon(tobj);

SEE ALSO

"gluNewTess", "gluNextContour", "gluTessCallback", "gluTessVertex"


gluBeginSurface
gluEndSurface

NAME

gluBeginSurface, gluEndSurface - delimit a NURBS surface definition

C SPECIFICATION

void gluBeginSurface( GLUnurbsObj *nobj )
void gluEndSurface( GLUnurbsObj *nobj )

PARAMETERS

nobj

Specifies the NURBS object (created with gluNewNurbsRenderer).

DESCRIPTION

Use gluBeginSurface to mark the beginning of a NURBS surface definition. After calling gluBeginSurface, make one or more calls to gluNurbsSurface to define the attributes of the surface. Exactly one of these calls to gluNurbsSurface must have a surface type of GL_MAP2_VERTEX_3 or GL_MAP2_VERTEX_4. To mark the end of the NURBS surface definition, call gluEndSurface.

Trimming of NURBS surfaces is supported with gluBeginTrim, gluPwlCurve, gluNurbsCurve, and gluEndTrim. Refer to the gluBeginTrim reference page for details.

OpenGL evaluators are used to render the NURBS surface as a set of polygons. Evaluator state is preserved during rendering with glPushAttrib(GL_EVAL_BIT) and glPopAttrib(). See the "glPushAttrib" reference page for details on exactly what state these calls preserve.

EXAMPLE

The following commands render a textured NURBS surface with normals; the texture coordinates and normals are also described as NURBS surfaces:

gluBeginSurface(nobj);
   gluNurbsSurface(nobj, ..., GL_MAP2_TEXTURE_COORD_2);
   gluNurbsSurface(nobj, ..., GL_MAP2_NORMAL);
   gluNurbsSurface(nobj, ..., GL_MAP2_VERTEX_4);
gluEndSurface(nobj);

SEE ALSO

"gluBeginCurve", "gluBeginTrim", "gluNewNurbsRenderer", "gluNurbsCurve", "gluNurbsSurface", "gluPwlCurve"


gluBeginTrim
gluEndTrim

NAME

gluBeginTrim, gluEndTrim - delimit a NURBS trimming loop definition

C SPECIFICATION

void gluBeginTrim( GLUnurbsObj *nobj )
void gluEndTrim( GLUnurbsObj *nobj )

PARAMETERS

nobj

Specifies the NURBS object (created with gluNewNurbsRenderer).

DESCRIPTION

Use gluBeginTrim to mark the beginning of a trimming loop, and gluEndTrim to mark the end of a trimming loop. A trimming loop is a set of oriented curve segments (forming a closed curve) that define boundaries of a NURBS surface. You include these trimming loops in the definition of a NURBS surface, between calls to gluBeginSurface and gluEndSurface.

The definition for a NURBS surface can contain many trimming loops. For example, if you wrote a definition for a NURBS surface that resembled a rectangle with a hole punched out, the definition would contain two trimming loops. One loop would define the outer edge of the rectangle; the other would define the hole punched out of the rectangle. The definitions of each of these trimming loops would be bracketed by a gluBeginTrim/gluEndTrim pair.

The definition of a single closed trimming loop can consist of multiple curve segments, each described as a piecewise linear curve (see "gluPwlCurve") or as a single NURBS curve (see "gluNurbsCurve"), or as a combination of both in any order. The only library calls that can appear in a trimming loop definition (between the calls to gluBeginTrim and gluEndTrim) are gluPwlCurve and gluNurbsCurve.

The area of the NURBS surface that is displayed is the region in the domain to the left of the trimming curve as the curve parameter increases. Thus, the retained region of the NURBS surface is inside a counterclockwise trimming loop and outside a clockwise trimming loop. For the rectangle mentioned earlier, the trimming loop for the outer edge of the rectangle runs counterclockwise, while the trimming loop for the punched-out hole runs clockwise.

If you use more than one curve to define a single trimming loop, the curve segments must form a closed loop (that is, the endpoint of each curve must be the starting point of the next curve, and the endpoint of the final curve must be the starting point of the first curve). If the endpoints of the curve are sufficiently close together but not exactly coincident, they will be coerced to match. If the endpoints are not sufficiently close, an error results (see "gluNurbsCallback").

If a trimming loop definition contains multiple curves, the direction of the curves must be consistent (that is, the inside must be to the left of all of the curves). Nested trimming loops are legal as long as the curve orientations alternate correctly. Trimming curves cannot be self-intersecting, nor can they intersect one another (or an error results).

If no trimming information is given for a NURBS surface, the entire surface is drawn.

EXAMPLE

This code fragment defines a trimming loop that consists of one piecewise linear curve, and two NURBS curves:

gluBeginTrim(nobj);
   gluPwlCurve(..., GLU_MAP1_TRIM_2);
   gluNurbsCurve(..., GLU_MAP1_TRIM_2);
   gluNurbsCurve(..., GLU_MAP1_TRIM_3);
gluEndTrim(nobj);

SEE ALSO

"gluBeginSurface", "gluNewNurbsRenderer", "gluNurbsCallback", "gluNurbsCurve", "gluPwlCurve"


gluBuild1DMipmaps

NAME

gluBuild1DMipmaps - create 1-D mipmaps

C SPECIFICATION

int gluBuild1DMipmaps( GLenum target, GLint components, GLint width, GLenum format, GLenum type, void *data )

PARAMETERS

target

Specifies the target texture. Must be GL_TEXTURE_1D.

components

Specifies the number of color components in the texture. Must be 1, 2, 3, or 4.

width

Specifies the width of the texture image.

format

Specifies the format of the pixel data. Must be one of GL_COLOR_INDEX, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, and GL_LUMINANCE_ALPHA.

type

Specifies the data type for data. Must be one of GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, or GL_FLOAT.

data

Specifies a pointer to the image data in memory.

DESCRIPTION

gluBuild1DMipmaps obtains the input image and generates all mipmap images (using gluScaleImage) so that the input image can be used as a mipmapped texture image. glTexImage1D is then called to load each of the images. If the width of the input image is not a power of two, then the image is scaled to the nearest power of two before the mipmaps are generated.

A return value of zero indicates success. Otherwise, a GLU error code is returned (see "gluErrorString").

Please refer to the glTexImage1D reference page for a description of the acceptable values for the format parameter. See the "glDrawPixels" reference page for a description of the acceptable values for the type parameter.

SEE ALSO

"glTexImage1D", "gluBuild2DMipmaps", "gluErrorString", "gluScaleImage"


gluBuild2DMipmaps

NAME

gluBuild2DMipmaps - create 2-D mipmaps

C SPECIFICATION

int gluBuild2DMipmaps( GLenum target, GLint components, GLint width, GLint height, GLenum format, GLenum type, void *data )

PARAMETERS

target

Specifies the target texture. Must be GL_TEXTURE_2D.

components

Specifies the number of color components in the texture. Must be 1, 2, 3, or 4.

width, height

Specifies the width and height, respectively, of the texture image.

format

Specifies the format of the pixel data. Must be one of: GL_COLOR_INDEX, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, and GL_LUMINANCE_ALPHA.

type

Specifies the data type for data. Must be one of: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, or GL_FLOAT.

data

Specifies a pointer to the image data in memory.

DESCRIPTION

gluBuild2DMipmaps obtains the input image and generates all mipmap images (using gluScaleImage) so that the input image can be used as a mipmapped texture image. glTexImage2D is then called to load each of the images. If the dimensions of the input image are not powers of two, then the image is scaled so that both the width and height are powers of two before the mipmaps are generated.

A return value of 0 indicates success. Otherwise, a GLU error code is returned (see "gluErrorString").

Please refer to the glTexImage1D reference page for a description of the acceptable values for the format parameter. See the "glDrawPixels" reference page for a description of the acceptable values for the type parameter.

SEE ALSO

"glDrawPixels", "glTexImage1D", "glTexImage2D", "gluBuild1DMipmaps", "gluErrorString", "gluScaleImage"


gluCylinder

NAME

gluCylinder - draw a cylinder

C SPECIFICATION

void gluCylinder( GLUquadricObj *qobj, GLdouble baseRadius, GLdouble topRadius, GLdouble height, GLint slices, GLint stacks )

PARAMETERS

qobj

Specifies the quadrics object (created with gluNewQuadric).

baseRadius

Specifies the radius of the cylinder at z = 0.

topRadius

Specifies the radius of the cylinder at z = height.

height

Specifies the height of the cylinder.

slices

Specifies the number of subdivisions around the z axis.

stacks

Specifies the number of subdivisions along the z axis.

DESCRIPTION

gluCylinder draws a cylinder oriented along the z axis. The base of the cylinder is placed at z = 0, and the top at z = height . Like a sphere, a cylinder is subdivided around the z axis into slices, and along the z axis into stacks.

Note that if topRadius is set to zero, then this routine will generate a cone.

If the orientation is set to GLU_OUTSIDE (with gluQuadricOrientation), then any generated normals point away from the z axis. Otherwise, they point toward the z axis.

If texturing is turned on (with gluQuadricTexture), then texture coordinates are generated so that t ranges linearly from 0.0 at z = 0 to 1.0 at z = height, and s ranges from 0.0 at the +y axis, to 0.25 at the +x axis, to 0.5 at the -y axis, to 0.75 at the -x axis, and back to 1.0 at the +y axis.

SEE ALSO

"gluDisk", "gluNewQuadric", "gluPartialDisk", "gluQuadricTexture", "gluSphere"


gluDeleteNurbsRenderer

NAME

gluDeleteNurbsRenderer - destroy a NURBS object

C SPECIFICATION

void gluDeleteNurbsRenderer( GLUnurbsObj *nobj )

PARAMETERS

nobj

Specifies the NURBS object to be destroyed (created with gluNewNurbsRenderer).

DESCRIPTION

gluDeleteNurbsRenderer destroys the NURBS object and frees any memory used by it. Once gluDeleteNurbsRenderer has been called, nobj cannot be used again.

SEE ALSO

"gluNewNurbsRenderer"


gluDeleteQuadric

NAME

gluDeleteQuadric - destroy a quadrics object

C SPECIFICATION

void gluDeleteQuadric( GLUquadricObj *state )

PARAMETERS

state

Specifies the quadrics object to be destroyed (created with gluNewQuadric).

DESCRIPTION

gluDeleteQuadric destroys the quadrics object and frees any memory used by it. Once gluDeleteQuadric has been called, state cannot be used again.

SEE ALSO

"gluNewQuadric"


gluDeleteTess

NAME

gluDeleteTess - destroy a tessellation object

C SPECIFICATION

void gluDeleteTess( GLUtriangulatorObj *tobj )

PARAMETERS

tobj

Specifies the tessellation object to destroy (created with gluNewTess).

DESCRIPTION

gluDeleteTess destroys the indicated tessellation object and frees any memory that it used.

SEE ALSO

"gluBeginPolygon", "gluNewTess", "gluTessCallback"


gluDisk

NAME

gluDisk - draw a disk

C SPECIFICATION

void gluDisk( GLUquadricObj *qobj, GLdouble innerRadius, GLdouble outerRadius, GLint slices, GLint loops )

PARAMETERS

qobj

Specifies the quadrics object (created with gluNewQuadric).

innerRadius

Specifies the inner radius of the disk (may be 0).

outerRadius

Specifies the outer radius of the disk.

slices

Specifies the number of subdivisions around the z axis.

loops

Specifies the number of concentric rings about the origin into which the disk is subdivided.

DESCRIPTION

gluDisk renders a disk on the z = 0 plane. The disk has a radius of outerRadius, and contains a concentric circular hole with a radius of innerRadius. If innerRadius is 0, then no hole is generated. The disk is subdivided around the z axis into slices (like pizza slices), and also about the z axis into rings (as specified by slices and loops, respectively).

With respect to orientation, the +z side of the disk is considered to be "outside" (see "gluQuadricOrientation"). This means that if the orientation is set to GLU_OUTSIDE, then any normals generated point along the +z axis. Otherwise, they point along the -z axis.

If texturing is turned on (with gluQuadricTexture), texture coordinates are generated linearly such that where r = outerRadius , the value at (r, 0, 0) is (1, 0.5), at (0, r, 0) it is (0.5, 1), at (-r, 0, 0) it is (0, 0.5), and at (0, -r, 0) it is (0.5, 0).

SEE ALSO

"gluCylinder", "gluNewQuadric", "gluPartialDisk", "gluQuadricOrientation", "gluQuadricTexture", "gluSphere"


gluErrorString

NAME

gluErrorString - produce an error string from an OpenGL or GLU error code

C SPECIFICATION

const GLubyte* gluErrorString( GLenum errorCode )

PARAMETERS

errorCode

Specifies an OpenGL or GLU error code.

DESCRIPTION

gluErrorString produces an error string from an OpenGL or GLU error code. The string is in an ISO Latin 1 format. For example, gluErrorString(GL_OUT_OF_MEMORY) returns the string out of memory.

The standard GLU error codes are GLU_INVALID_ENUM, GLU_INVALID_VALUE, and GLU_OUT_OF_MEMORY. Certain other GLU functions can return specialized error codes through callbacks. Refer to the glGetError reference page for the list of OpenGL error codes.

SEE ALSO

"glGetError", "gluNurbsCallback", "gluQuadricCallback", "gluTessCallback"


gluGetNurbsProperty

NAME

gluGetNurbsProperty - get a NURBS property

C SPECIFICATION

void gluGetNurbsProperty( GLUnurbsObj *nobj, GLenum property, GLfloat *value )

PARAMETERS

nobj

Specifies the NURBS object (created with gluNewNurbsRenderer).

property

Specifies the property whose value is to be fetched. Valid values are GLU_CULLING, GLU_SAMPLING_TOLERANCE, GLU_DISPLAY_MODE, and GLU_AUTO_LOAD_MATRIX.

value

Specifies a pointer to the location into which the value of the named property is written.

DESCRIPTION

gluGetNurbsProperty is used to retrieve properties stored in a NURBS object. These properties affect the way that NURBS curves and surfaces are rendered. Please refer to the gluNurbsProperty reference page for information about what the properties are and what they do.

SEE ALSO

"gluNewNurbsRenderer", "gluNurbsProperty"


gluGetString

NAME

gluGetString - return a string describing the GLU version or GLU extensions

C SPECIFICATION

const GLubyte *gluGetString( GLenum name )

Parameters

name

Specifies a symbolic constant, one of GLU_VERSION, or GLU_EXTENSIONS.

DESCRIPTION

The gluGetString subroutine returns a pointer to a static string describing the GLU version or the GLU extensions that are supported.

The version number is one of the following forms:

<major_number>.<minor_number>
<major_number>.<minor_number>.<release_number>

The version string is of the following form:

<version number><space><vendor-specific information>

Vendor-specific information is optional. Its format and contents depend on the implementation.

The standard GLU contains a basic set of features and capabilities. If a company or group of companies wish to support other features, these may be included as extensions to the GLU. If name is GLU_EXTENSIONS, then gluGetString returns a space-separated list of names of supported GLU extensions. (Extension names never contain spaces.)

All strings are null-terminated.

NOTES

The gluGetString subroutine only returns information about GLU extensions. Call glGetString to get a list of GL extensions.

The gluGetString subroutine is an initialization routine. Calling it after a glNewList results in undefined behavior.

ERRORS

NULL is returned if name is not GLU_VERSION or GLU_EXTENSIONS.

SEE ALSO

"glGetString"


gluGetTessProperty

NAME

gluGetTessProperty - get a tessellation object property

C SPECIFICATION

void gluGetTessProperty( GLUtesselator* tess, GLenum which, GLdouble* data )

PARAMETERS

tess

Specifies the tessellation object (created with gluNewTess).

which

Specifies the property whose value is to be fetched. Valid values are GLU_TESS_WINDING_RULE, GLU_TESS_BOUNDARY_ONLY, and GLU_TESS_TOLERANCE.

data

Specifies a pointer to the location into which the value of the named property is written.

DESCRIPTION

The gluGetTessProperty subroutine retrieves properties stored in a tessellation object. These properties affect the way that tessellation objects are interpreted and rendered. See the gluTessProperty reference page for information about the properties and what they do.

SEE ALSO

"gluNewTess", "gluTessProperty"


gluLoadSamplingMatrices

NAME

gluLoadSamplingMatrices - load NURBS sampling and culling matrices

C SPECIFICATION

void gluLoadSamplingMatrices( GLUnurbsObj *nobj, const GLfloat modelMatrix[16], const GLfloat projMatrix[16], const GLint viewport[4]); )

PARAMETERS

nobj

Specifies the NURBS object (created with gluNewNurbsRenderer).

modelMatrix

Specifies a modelview matrix (as from a glGetFloatv call).

projMatrix

Specifies a projection matrix (as from a glGetFloatv call).

viewport;

Specifies a viewport (as from a glGetIntegerv call).

DESCRIPTION

gluLoadSamplingMatrices uses modelMatrix, projMatrix, and viewport; to recompute the sampling and culling matrices stored in nobj. The sampling matrix determines how finely a NURBS curve or surface must be tessellated to satisfy the sampling tolerance (as determined by the GLU_SAMPLING_TOLERANCE property). The culling matrix is used in deciding if a NURBS curve or surface should be culled before rendering (when the GLU_CULLING property is turned on).

gluLoadSamplingMatrices is necessary only if the GLU_AUTO_LOAD_MATRIX property is turned off (see "gluNurbsProperty"). Although it can be convenient to leave the GLU_AUTO_LOAD_MATRIX property turned on, there can be a performance penalty for doing so. (A round trip to the OpenGL server is needed to fetch the current values of the modelview matrix, projection matrix, and viewport.)

SEE ALSO

"gluGetNurbsProperty", "gluNewNurbsRenderer", "gluNurbsProperty"


gluLookAt

NAME

gluLookAt - define a viewing transformation

C SPECIFICATION

void gluLookAt( GLdouble eyex, GLdouble eyey, GLdouble eyez, GLdouble centerx, GLdouble centery, GLdouble centerz, GLdouble upx, GLdouble upy, GLdouble upz )

PARAMETERS

eyex, eyey, eyez

Specifies the position of the eye point.

centerx, centery, centerz

Specifies the position of the reference point.

upx, upy, upz

Specifies the direction of the up vector.

DESCRIPTION

gluLookAt creates a viewing matrix derived from an eye point, a reference point indicating the center of the scene, and an up vector. The matrix maps the reference point to the negative z axis and the eye point to the origin, so that, when a typical projection matrix is used, the center of the scene maps to the center of the viewport. Similarly, the direction described by the up vector projected onto the viewing plane is mapped to the positive y axis so that it points upward in the viewport. The up vector must not be parallel to the line of sight from the eye to the reference point.

The matrix generated by gluLookAt postmultiplies the current matrix.

SEE ALSO

"glFrustum", "gluPerspective"


gluNewNurbsRenderer

NAME

gluNewNurbsRenderer - create a NURBS object

C SPECIFICATION

GLUnurbsObj* gluNewNurbsRenderer( void )

DESCRIPTION

gluNewNurbsRenderer creates and returns a pointer to a new NURBS object. This object must be referred to when calling NURBS rendering and control functions. A return value of zero means that there is not enough memory to allocate the object.

SEE ALSO

"gluBeginCurve", "gluBeginSurface", "gluBeginTrim", "gluDeleteNurbsRenderer", "gluNurbsCallback", "gluNurbsProperty"


gluNewQuadric

NAME

gluNewQuadric - create a quadrics object

C SPECIFICATION

GLUquadricObj* gluNewQuadric( void )

DESCRIPTION

gluNewQuadric creates and returns a pointer to a new quadrics object. This object must be referred to when calling quadrics rendering and control functions. A return value of zero means that there is not enough memory to allocate the object.

SEE ALSO

"gluCylinder", "gluDeleteQuadric", "gluDisk", "gluPartialDisk", "gluQuadricCallback", "gluQuadricDrawStyle", "gluQuadricNormals", "gluQuadricOrientation", "gluQuadricTexture", "gluSphere"


gluNewTess

NAME

gluNewTess - create a tessellation object

C SPECIFICATION

GLUtriangulatorObj* gluNewTess( void )

DESCRIPTION

gluNewTess creates and returns a pointer to a new tessellation object. This object must be referred to when calling tessellation functions. A return value of zero means that there is not enough memory to allocate the object.

SEE ALSO

"gluBeginPolygon", "gluDeleteTess", "gluTessCallback"


gluNextContour

NAME

gluNextContour - mark the beginning of another contour

C SPECIFICATION

void gluNextContour( GLUtriangulatorObj *tobj, GLenum type )

PARAMETERS

tobj

Specifies the tessellation object (created with gluNewTess).

type

Specifies the type of the contour being defined. Valid values are GLU_EXTERIOR, GLU_INTERIOR, GLU_UNKNOWN, GLU_CCW, and GLU_CW.

DESCRIPTION

gluNextContour is used in describing polygons with multiple contours. After the first contour has been described through a series of gluTessVertex calls, a gluNextContour call indicates that the previous contour is complete and that the next contour is about to begin. Another series of gluTessVertex calls is then used to describe the new contour. This process can be repeated until all contours have been described.

type defines what type of contour follows. The legal contour types are as follows:

GLU_EXTERIOR

An exterior contour defines an exterior boundary of the polygon.

GLU_INTERIOR

An interior contour defines an interior boundary of the polygon (such as a hole).

GLU_UNKNOWN

An unknown contour is analyzed by the library to determine if it is interior or exterior.

GLU_CCW, GLU_CW

The first GLU_CCW or GLU_CW contour defined is considered to be exterior. All other contours are considered to be exterior if they are oriented in the same direction (clockwise or counterclockwise) as the first contour, and interior if they are not. If one contour is of type GLU_CCW or GLU_CW, then all contours must be of the same type (if they are not, then all GLU_CCW and GLU_CW contours will be changed to GLU_UNKNOWN). Note that there is no real difference between the GLU_CCW and GLU_CW contour types.

gluNextContour can be called before the first contour is described to define the type of the first contour. If gluNextContour is not called before the first contour, then the first contour is marked GLU_EXTERIOR.

EXAMPLE

A quadrilateral with a triangular hole in it can be described as follows:

gluBeginPolygon(tobj);
   gluTessVertex(tobj, v1, v1);
   gluTessVertex(tobj, v2, v2);
   gluTessVertex(tobj, v3, v3);
   gluTessVertex(tobj, v4, v4);
gluNextContour(tobj, GLU_INTERIOR);
   gluTessVertex(tobj, v5, v5);
   gluTessVertex(tobj, v6, v6);
   gluTessVertex(tobj, v7, v7);
gluEndPolygon(tobj);

SEE ALSO

"gluBeginPolygon", "gluNewTess", "gluTessCallback", "gluTessVertex"


gluNurbsCallback

NAME

gluNurbsCallback - define a callback for a NURBS object

C SPECIFICATION

void gluNurbsCallback( GLUnurbsObj *nobj, GLenum which, void (*fn)( )

PARAMETERS

nobj

Specifies the NURBS object (created with gluNewNurbsRenderer).

which

Specifies the callback being defined. The only valid value is GLU_ERROR.

fn

Specifies the function that the callback calls.

DESCRIPTION

gluNurbsCallback is used to define a callback to be used by a NURBS object. If the specified callback is already defined, then it is replaced. If fn is NULL, then any existing callback is erased.

The one legal callback is GLU_ERROR:

GLU_ERROR

The error function is called when an error is encountered. Its single argument is of type GLenum, and it indicates the specific error that occurred. There are 37 errors unique to NURBS named GLU_NURBS_ERROR1 through GLU_NURBS_ERROR37. Character strings describing these errors can be retrieved with gluErrorString.

SEE ALSO

"gluErrorString", "gluNewNurbsRenderer"


gluNurbsCurve

NAME

gluNurbsCurve - define the shape of a NURBS curve

C SPECIFICATION

void gluNurbsCurve( GLUnurbsObj *nobj, GLint nknots, GLfloat *knot, GLint stride, GLfloat *ctlarray, GLint order, GLenum type )

PARAMETERS

nobj

Specifies the NURBS object (created with gluNewNurbsRenderer).

nknots

Specifies the number of knots in knot. nknots equals the number of control points plus the order.

knot

Specifies an array of nknots nondecreasing knot values.

stride

Specifies the offset (as a number of single-precision floating-point values) between successive curve control points.

ctlarray

Specifies a pointer to an array of control points. The coordinates must agree with type, specified below.

order

Specifies the order of the NURBS curve. order equals degree + 1, hence a cubic curve has an order of 4.

type

Specifies the type of the curve. If this curve is defined within a gluBeginCurve/gluEndCurve pair, then the type can be any of the valid one-dimensional evaluator types (such as GL_MAP1_VERTEX_3 or GL_MAP1_COLOR_4). Between a gluBeginTrim/gluEndTrim pair, the only valid types are GLU_MAP1_TRIM_2 and GLU_MAP1_TRIM_3.

DESCRIPTION

Use gluNurbsCurve to describe a NURBS curve.

When gluNurbsCurve appears between a gluBeginCurve/gluEndCurve pair, it is used to describe a curve to be rendered. Positional, texture, and color coordinates are associated by presenting each as a separate gluNurbsCurve between a gluBeginCurve/gluEndCurve pair. No more than one call to gluNurbsCurve for each of color, position, and texture data can be made within a single gluBeginCurve/gluEndCurve pair. Exactly one call must be made to describe the position of the curve (a type of GL_MAP1_VERTEX_3 or GL_MAP1_VERTEX_4).

When gluNurbsCurve appears between a gluBeginTrim/gluEndTrim pair, it is used to describe a trimming curve on a NURBS surface. If type is GLU_MAP1_TRIM_2, then it describes a curve in two-dimensional (u and v) parameter space. If it is GLU_MAP1_TRIM_3, then it describes a curve in two-dimensional homogeneous (u, v, and w) parameter space. See the "gluBeginTrim" reference page for more discussion about trimming curves.

EXAMPLE

The following commands render a textured NURBS curve with normals:

gluBeginCurve(nobj);
   gluNurbsCurve(nobj, ..., GL_MAP1_TEXTURE_COORD_2);
   gluNurbsCurve(nobj, ..., GL_MAP1_NORMAL);
   gluNurbsCurve(nobj, ..., GL_MAP1_VERTEX_4);
gluEndCurve(nobj);

SEE ALSO

"gluBeginCurve", "gluBeginTrim", "gluNewNurbsRenderer", "gluPwlCurve"


gluNurbsProperty

NAME

gluNurbsProperty - set a NURBS property

C SPECIFICATION

void gluNurbsProperty( GLUnurbsObj *nobj, GLenum property, GLfloat value )

PARAMETERS

nobj

Specifies the NURBS object (created with gluNewNurbsRenderer).

property

Specifies the property to be set. Valid values are GLU_SAMPLING_TOLERANCE, GLU_DISPLAY_MODE, GLU_CULLING, and GLU_AUTO_LOAD_MATRIX.

value

Specifies the value to which to set the indicated property.

DESCRIPTION

gluNurbsProperty is used to control properties stored in a NURBS object. These properties affect the way that a NURBS curve is rendered. The legal values for property are as follows:

GLU_SAMPLING_TOLERANCE

value specifies the maximum length, in pixels, of line segments or edges of polygons used to render NURBS curves or surfaces. The NURBS code is conservative when rendering a curve or surface, so the actual length can be somewhat shorter. The default value is 50.0 pixels.

GLU_DISPLAY_MODE

value defines how a NURBS surface should be rendered. value can be set to GLU_FILL, GLU_OUTLINE_POLYGON, or GLU_OUTLINE_PATCH. When set to GLU_FILL, the surface is rendered as a set of polygons. GLU_OUTLINE_POLYGON instructs the NURBS library to draw only the outlines of the polygons created by tessellation. GLU_OUTLINE_PATCH causes just the outlines of patches and trim curves defined by the user to be drawn. The default value is GLU_FILL.

GLU_CULLING

value is a Boolean value that, when set to GL_TRUE, indicates that a NURBS curve should be discarded prior to tessellation if its control points lie outside the current viewport. The default is GL_FALSE (because a NURBS curve cannot fall entirely within the convex hull of its control points).

GLU_AUTO_LOAD_MATRIX

value is a Boolean value. When set to GL_TRUE, the NURBS code downloads the projection matrix, the modelview matrix, and the viewport from the OpenGL server to compute sampling and culling matrices for each NURBS curve that is rendered. Sampling and culling matrices are required to determine the tesselation of a NURBS surface into line segments or polygons and to cull a NURBS surface if it lies outside of the viewport. If this mode is set to GL_FALSE, then the user needs to provide a projection matrix, a modelview matrix, and a viewport for the NURBS renderer to use to construct sampling and culling matrices. This can be done with the gluLoadSamplingMatrices function. The default for this mode is GL_TRUE. Changing this mode from GL_TRUE to GL_FALSE does not affect the sampling and culling matrices until gluLoadSamplingMatrices is called.

SEE ALSO

"gluGetNurbsProperty", "gluLoadSamplingMatrices", "gluNewNurbsRenderer"


gluNurbsSurface

NAME

gluNurbsSurface - define the shape of a NURBS surface

C SPECIFICATION

void gluNurbsSurface( GLUnurbsObj *nobj, GLint sknot_count, GLfloat *sknot, GLint tknot_count, GLfloat *tknot, GLint s_stride, GLint t_stride, GLfloat *ctlarray, GLint sorder, GLint torder, GLenum type )

PARAMETERS

nobj

Specifies the NURBS object (created with gluNewNurbsRenderer).

sknot_count

Specifies the number of knots in the parametric u direction.

sknot

Specifies an array of sknot_count nondecreasing knot values in the parametric u direction.

tknot_count

Specifies the number of knots in the parametric v direction.

tknot

Specifies an array of tknot_count nondecreasing knot values in the parametric v direction.

s_stride

Specifies the offset (as a number of single-precision floating point values) between successive control points in the parametric u direction in ctlarray.

t_stride

Specifies the offset (in single-precision floating-point values) between successive control points in the parametric v direction in ctlarray.

ctlarray

Specifies an array containing control points for the NURBS surface. The offsets between successive control points in the parametric u and v directions are given by s_stride and t_stride.

sorder

Specifies the order of the NURBS surface in the parametric u direction. The order is one more than the degree, hence a surface that is cubic in u has a u order of 4.

torder

Specifies the order of the NURBS surface in the parametric v direction. The order is one more than the degree, hence a surface that is cubic in v has a v order of 4.

type

Specifies type of the surface. type can be any of the valid two-dimensional evaluator types (such as GL_MAP2_VERTEX_3 or GL_MAP2_COLOR_4).

DESCRIPTION

Use gluNurbsSurface within a NURBS (Non-Uniform Rational B-Spline) surface definition to describe the shape of a NURBS surface (before any trimming). To mark the beginning of a NURBS surface definition, use the gluBeginSurface command. To mark the end of a NURBS surface definition, use the gluEndSurface command. Call gluNurbsSurface within a NURBS surface definition only.

Positional, texture, and color coordinates are associated with a surface by presenting each as a separate gluNurbsSurface between a gluBeginSurface/gluEndSurface pair. No more than one call to gluNurbsSurface for each of color, position, and texture data can be made within a single gluBeginSurface/gluEndSurface pair. Exactly one call must be made to describe the position of the surface (a type of GL_MAP2_VERTEX_3 or GL_MAP2_VERTEX_4).

A NURBS surface can be trimmed by using the commands gluNurbsCurve and gluPwlCurve between calls to gluBeginTrim and gluEndTrim.

Note that a gluNurbsSurface with sknot_count knots in the u direction and tknot_count knots in the v direction with orders sorder and torder must have (sknot_count - sorder) x (tknot_count - torder) control points.

EXAMPLE

The following commands render a textured NURBS surface with normals; the texture coordinates and normals are also NURBS surfaces:

gluBeginSurface(nobj);
   gluNurbsSurface(nobj, ..., GL_MAP2_TEXTURE_COORD_2);
   gluNurbsSurface(nobj, ..., GL_MAP2_NORMAL);
   gluNurbsSurface(nobj, ..., GL_MAP2_VERTEX_4);
gluEndSurface(nobj);

SEE ALSO

"gluBeginSurface", "gluBeginTrim", "gluNewNurbsRenderer", "gluNurbsCurve", "gluPwlCurve"


gluOrtho2D

NAME

gluOrtho2D - define a 2-D orthographic projection matrix

C SPECIFICATION

void gluOrtho2D( GLdouble left, GLdouble right, GLdouble bottom, GLdouble top )

PARAMETERS

left, right

Specify the coordinates for the left and right vertical clipping planes.

bottom, top

Specify the coordinates for the bottom and top horizontal clipping planes.

DESCRIPTION

gluOrtho2D sets up a two-dimensional orthographic viewing region. This is equivalent to calling glOrtho with near = -1 and far = 1 .

SEE ALSO

"glOrtho", "gluPerspective"


gluPartialDisk

NAME

gluPartialDisk - draw an arc of a disk

C SPECIFICATION

void gluPartialDisk( GLUquadricObj *qobj, GLdouble innerRadius, GLdouble outerRadius, GLint slices, GLint loops, GLdouble startAngle, GLdouble sweepAngle )

PARAMETERS

qobj

Specifies a quadrics object (created with gluNewQuadric).

innerRadius

Specifies the inner radius of the partial disk (can be zero).

outerRadius

Specifies the outer radius of the partial disk.

slices

Specfies the number of subdivisions around the z axis.

loops

Specifies the number of concentric rings about the origin into which the partial disk is subdivided.

startAngle

Specifies the starting angle, in degrees, of the disk portion.

sweepAngle

Specifies the sweep angle, in degrees, of the disk portion.

DESCRIPTION

gluPartialDisk renders a partial disk on the z = 0 plane. A partial disk is similar to a full disk, except that only the subset of the disk from startAngle through startAngle + sweepAngle is included (where 0 degrees is along the +yaxis, 90 degrees along the +x axis, 180 along the -y axis, and 270 along the -x axis).

The partial disk has a radius of outerRadius, and contains a concentric circular hole with a radius of innerRadius. If innerRadius is zero, then no hole is generated. The partial disk is subdivided around the z axis into slices (like pizza slices), and also about the z axis into rings (as specified by slices and loops, respectively).

With respect to orientation, the +z side of the partial disk is considered to be outside (see "gluQuadricOrientation"). This means that if the orientation is set to GLU_OUTSIDE, then any normals generated point along the +z axis. Otherwise, they point along the -z axis.

If texturing is turned on (with gluQuadricTexture), texture coordinates are generated linearly such that where r = outerRadius , the value at (r, 0, 0) is (1, 0.5), at (0, r, 0) it is (0.5, 1), at (-r, 0, 0) it is (0, 0.5), and at (0, -r, 0) it is (0.5, 0).

SEE ALSO

"gluCylinder", "gluDisk", "gluNewQuadric", "gluQuadricOrientation", "gluQuadricTexture", "gluSphere"


gluPerspective

NAME

gluPerspective - set up a perspective projection matrix

C SPECIFICATION

void gluPerspective( GLdouble fovy, GLdouble aspect, GLdouble zNear, GLdouble zFar )

PARAMETERS

fovy

Specifies the field of view angle, in degrees, in the y direction.

aspect

Specifies the aspect ratio that determines the field of view in the x direction. The aspect ratio is the ratio of x (width) to y (height).

zNear

Specifies the distance from the viewer to the near clipping plane (always positive).

zFar

Specifies the distance from the viewer to the far clipping plane (always positive).

DESCRIPTION

gluPerspective specifies a viewing frustum into the world coordinate system. In general, the aspect ratio in gluPerspective should match the aspect ratio of the associated viewport. For example, aspect = 2.0 means the viewer's angle of view is twice as wide in x as it is in y. If the viewport is twice as wide as it is tall, it displays the image without distortion.

The matrix generated by gluPerspective is multipled by the current matrix, just as if glMultMatrix were called with the generated matrix. To load the perspective matrix onto the current matrix stack instead, precede the call to gluPerspective with a call to glLoadIdentity.

SEE ALSO

"glFrustum", "glLoadIdentity", "glMultMatrix", "gluOrtho2D"


gluPickMatrix

NAME

gluPickMatrix - define a picking region

C SPECIFICATION

void gluPickMatrix( GLdouble x, GLdouble y, GLdouble width, GLdouble height, GLint viewport[4] )

PARAMETERS

x, y

Specify the center of a picking region in window coordinates.

width, height

Specify the width and height, respectively, of the picking region in window coordinates.

viewport

Specifies the current viewport (as from a glGetIntegerv call).

DESCRIPTION

gluPickMatrix creates a projection matrix that can be used to restrict drawing to a small region of the viewport. This is typically useful to determine what objects are being drawn near the cursor. Use gluPickMatrix to restrict drawing to a small region around the cursor. Then, enter selection mode (with glRenderMode and rerender the scene. All primitives that would have been drawn near the cursor are identified and stored in the selection buffer.

The matrix created by gluPickMatrix is multiplied by the current matrix just as if glMultMatrix is called with the generated matrix. To effectively use the generated pick matrix for picking, first call glLoadIdentity to load an identity matrix onto the perspective matrix stack. Then call gluPickMatrix, and finally, call a command (such as gluPerspective) to multiply the perspective matrix by the pick matrix.

When using gluPickMatrix to pick NURBS, be careful to turn off the NURBS property GLU_AUTO_LOAD_MATRIX. If GLU_AUTO_LOAD_MATRIX is not turned off, then any NURBS surface rendered is subdivided differently with the pick matrix than the way it was subdivided without the pick matrix.

EXAMPLE

When rendering a scene as follows:

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPerspective(...);
glMatrixMode(GL_MODELVIEW);
/* Draw the scene */

a portion of the viewport can be selected as a pick region like this:

glMatrixMode(GL_PROJECTION);
glLoadIdentity();
gluPickMatrix(x, y, width, height, viewport);
gluPerspective(...);
glMatrixMode(GL_MODELVIEW);
/* Draw the scene */

SEE ALSO

"glGet", "glLoadIdentity", "glMultMatrix", "glRenderMode", "gluPerspective"


gluProject

NAME

gluProject - map object coordinates to window coordinates

C SPECIFICATION

int gluProject( GLdouble objx, GLdouble objy, GLdouble objz, const GLdouble modelMatrix[16], const GLdouble projMatrix[16], const GLint viewport[4], GLdouble *winx, GLdouble *winy, GLdouble *winz )

PARAMETERS

objx, objy, objz

Specify the object coordinates.

modelMatrix

Specifies the current modelview matrix (as from a glGetDoublev call).

projMatrix

Specifies the current projection matrix (as from a glGetDoublev call).

viewport

Specifies the current viewport (as from a glGetIntegerv call).

winx, winy, winz

Return the computed window coordinates.

DESCRIPTION

gluProject transforms the specified object coordinates into window coordinates using modelMatrix, projMatrix, and viewport. The result is stored in winx, winy, and winz. A return value of GL_TRUE indicates success, and GL_FALSE indicates failure.

SEE ALSO

"glGet", "gluUnProject"


gluPwlCurve

NAME

gluPwlCurve - describe a piecewise linear NURBS trimming curve

C SPECIFICATION

void gluPwlCurve( GLUnurbsObj *nobj, GLint count, GLfloat *array, GLint stride, GLenum type )

PARAMETERS

nobj

Specifies the NURBS object (created with gluNewNurbsRenderer).

count

Specifies the number of points on the curve.

array

Specifies an array containing the curve points.

stride

Specifies the offset (a number of single-precision floating-point values) between points on the curve.

type

Specifies the type of curve. Must be either GLU_MAP1_TRIM_2 or GLU_MAP1_TRIM_3.

DESCRIPTION

gluPwlCurve describes a piecewise linear trimming curve for a NURBS surface. A piecewise linear curve consists of a list of coordinates of points in the parameter space for the NURBS surface to be trimmed. These points are connected with line segments to form a curve. If the curve is an approximation to a real curve, the points should be close enough that the resulting path appears curved at the resolution used in the application.

If type is GLU_MAP1_TRIM_2, then it describes a curve in two-dimensional (u and v) parameter space. If it is GLU_MAP1_TRIM_3, then it describes a curve in two-dimensional homogeneous (u, v, and w) parameter space. Please refer to the gluBeginTrim reference page for more information about trimming curves.

SEE ALSO

"gluBeginCurve", "gluBeginTrim", "gluNewNurbsRenderer", "gluNurbsCurve"


gluQuadricCallback

NAME

gluQuadricCallback - define a callback for a quadrics object

C SPECIFICATION

void gluQuadricCallback( GLUquadricObj *qobj, GLenum which, void (*fn)( )

PARAMETERS

qobj

Specifies the quadrics object (created with gluNewQuadric).

which

Specifies the callback being defined. The only valid value is GLU_ERROR.

fn

Specifies the function to be called.

DESCRIPTION

gluQuadricCallback is used to define a new callback to be used by a quadrics object. If the specified callback is already defined, then it is replaced. If fn is NULL, then any existing callback is erased.

The one legal callback is GLU_ERROR:

GLU_ERROR

The function is called when an error is encountered. Its single argument is of type GLenum, and it indicates the specific error that occurred. Character strings describing these errors can be retrieved with the gluErrorString call.

SEE ALSO

"gluErrorString", "gluNewQuadric"


gluQuadricDrawStyle

NAME

gluQuadricDrawStyle - specify the draw style desired for quadrics

C SPECIFICATION

void gluQuadricDrawStyle( GLUquadricObj *quadObject, GLenum drawStyle )

PARAMETERS

quadObject

Specifies the quadrics object (created with gluNewQuadric).

drawStyle

Specifies the desired draw style. Valid values are GLU_FILL, GLU_LINE, GLU_SILHOUETTE, and GLU_POINT.

DESCRIPTION

gluQuadricDrawStyle specifies the draw style for quadrics rendered with quadObject. The legal values are as follows:

GLU_FILL

Quadrics are rendered with polygon primitives. The polygons are drawn in a counterclockwise fashion with respect to their normals (as defined with gluQuadricOrientation).

GLU_LINE

Quadrics are rendered as a set of lines.

GLU_SILHOUETTE

Quadrics are rendered as a set of lines, except that edges separating coplanar faces will not be drawn.

GLU_POINT

Quadrics are rendered as a set of points.

SEE ALSO

"gluNewQuadric", "gluQuadricNormals", "gluQuadricOrientation", "gluQuadricTexture"


gluQuadricNormals

NAME

gluQuadricNormals - specify what kind of normals are desired for quadrics

C SPECIFICATION

void gluQuadricNormals( GLUquadricObj *quadObject, GLenum normals )

PARAMETERS

quadObject

Specifes the quadrics object (created with gluNewQuadric).

normals

Specifies the desired type of normals. Valid values are GLU_NONE, GLU_FLAT, and GLU_SMOOTH.

DESCRIPTION

gluQuadricNormals specifies what kind of normals are desired for quadrics rendered with quadObject. The legal values are as follows:

GLU_NONE

No normals are generated.

GLU_FLAT

One normal is generated for every facet of a quadric.

GLU_SMOOTH

One normal is generated for every vertex of a quadric. This is the default.

SEE ALSO

"gluNewQuadric", "gluQuadricDrawStyle", "gluQuadricOrientation", "gluQuadricTexture"


gluQuadricOrientation

NAME

gluQuadricOrientation - specify inside/outside orientation for quadrics

C SPECIFICATION

void gluQuadricOrientation( GLUquadricObj *quadObject, GLenum orientation )

PARAMETERS

quadObject

Specifies the quadrics object (created with gluNewQuadric).

orientation

Specifies the desired orientation. Valid values are GLU_OUTSIDE and GLU_INSIDE.

DESCRIPTION

gluQuadricOrientation specifies what kind of orientation is desired for quadrics rendered with quadObject. The orientation values are as follows:

GLU_OUTSIDE

Quadrics are drawn with normals pointing outward.

GLU_INSIDE

Normals point inward. The default is GLU_OUTSIDE.

Note that the interpretation of outward and inward depends on the quadric being drawn.

SEE ALSO

"gluNewQuadric", "gluQuadricDrawStyle", "gluQuadricNormals", "gluQuadricTexture"


gluQuadricTexture

NAME

gluQuadricTexture - specify if texturing is desired for quadrics

C SPECIFICATION

void gluQuadricTexture( GLUquadricObj *quadObject, GLboolean textureCoords )

PARAMETERS

quadObject

Specifies the quadrics object (created with gluNewQuadric).

textureCoords

Specifies a flag indicating if texture coordinates should be generated.

DESCRIPTION

gluQuadricTexture specifies if texture coordinates should be generated for quadrics rendered with quadObject. If the value of textureCoords is GL_TRUE, then texture coordinates are generated, and if textureCoords is GL_FALSE, they are not. The default is GL_FALSE.

The manner in which texture coordinates are generated depends upon the specific quadric rendered.

SEE ALSO

"gluNewQuadric", "gluQuadricDrawStyle", "gluQuadricNormals", "gluQuadricOrientation"


gluScaleImage

NAME

gluScaleImage - scale an image to an arbitrary size

C SPECIFICATION

int gluScaleImage( GLenum format, GLint widthin, GLint heightin, GLenum typein, const void *datain, GLint widthout, GLint heightout, GLenum typeout, void *dataout )

PARAMETERS

format

Specifies the format of the pixel data. The following symbolic values are valid: GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, and GL_LUMINANCE_ALPHA.

widthin, heightin

Specify the width and height, respectively, of the source image that is scaled.

typein

Specifies the data type for datain. Must be one of GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, or GL_FLOAT.

datain

Specifies a pointer to the source image.

widthout, heightout

Specify the width and height, respectively, of the destination image.

typeout

Specifies the data type for dataout. Must be one of GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, or GL_FLOAT.

dataout

Specifies a pointer to the destination image.

DESCRIPTION

gluScaleImage scales a pixel image using the appropriate pixel store modes to unpack data from the source image and pack data into the destination image.

When shrinking an image, gluScaleImage uses a box filter to sample the source image and create pixels for the destination image. When magnifying an image, the pixels from the source image are linearly interpolated to create the destination image.

A return value of zero indicates success, otherwise a GLU error code is returned indicating what the problem was (see "gluErrorString").

Please refer to the glReadPixels reference page for a description of the acceptable values for the format, typein, and typeout parameters.

SEE ALSO

"glDrawPixels", "glReadPixels", "gluBuild1DMipmaps", "gluBuild2DMipmaps", "gluErrorString"


gluSphere

NAME

gluSphere - draw a sphere

C SPECIFICATION

void gluSphere( GLUquadricObj *qobj, GLdouble radius, GLint slices, GLint stacks )

PARAMETERS

qobj

Specifies the quadrics object (created with gluNewQuadric).

radius

Specifies the radius of the sphere.

slices

Specifies the number of subdivisions around the z axis (similar to lines of longitude).

stacks

Specifies the number of subdivisions along the z axis (similar to lines of latitude).

DESCRIPTION

gluSphere draws a sphere of the given radius centered around the origin. The sphere is subdivided around the z axis into slices and along the z axis into stacks (similar to lines of longitude and latitude).

If the orientation is set to GLU_OUTSIDE (with gluQuadricOrientation), then any normals generated point away from the center of the sphere. Otherwise, they point toward the center of the sphere.

If texturing is turned on (with gluQuadricTexture), then texture coordinates are generated so that t ranges from 0.0 at z = -radius to 1.0 at z = radius (t increases linearly along longitudinal lines), and s ranges from 0.0 at the +y axis, to 0.25 at the +x axis, to 0.5 at the -y axis, to 0.75 at the -x axis, and back to 1.0 at the +y axis.

SEE ALSO

"gluCylinder", "gluDisk", "gluNewQuadric", "gluPartialDisk", "gluQuadricOrientation", "gluQuadricTexture"


gluTessBeginContour
gluTessEndContour

NAME

gluTessBeginContour, gluTessEndContour - delimit a contour description

C SPECIFICATION

void gluTessBeginContour( GLUtesselator* tess )
void gluTessEndContour( GLUtesselator* tess )

PARAMETERS

tess

Specifies the tessellation object (created with gluNewTess).

DESCRIPTION

The gluTessBeginContour subroutine and gluTessEndContour subroutine delimit the definition of a polygon contour. Within each gluTessBeginContour/gluTessEndContour pair, there can be zero or more calls to gluTessVertex. The vertices specify a closed contour (the last vertex of each contour is automatically linked to the first). See the gluTessVertex reference page for more details. gluTessBeginContour can only be called between gluTessBeginPolygon and gluTessEndPolygon.

SEE ALSO

"gluNewTess", "gluTessBeginPolygon", "gluTessVertex", "gluTessCallback", "gluTessProperty", "gluTessNormal", "gluTessEndPolygon"


gluTessBeginPolygon
gluTessEndPolygon

NAME

gluTessBeginPolygon, gluTessEndPolygon - delimit a polygon description

C SPECIFICATION

void gluTessBeginPolygon( GLUtesselator* tess, GLvoid* data )
void gluTessEndPolygon( GLUtesselator* tess )

PARAMETERS

tess

Specifies the tessellation object (created with gluNewTess).

data

Specifies a pointer to user polygon data.

DESCRIPTION

The gluTessBeginPolygon and gluTessEndPolygon routines delimit the definition of a nonconvex polygon. Within each gluTessBeginPolygon/gluTessEndPolygon pair, there must be one or more calls to gluTessBeginContour/gluTessEndContour. Within each contour, there are zero or more calls to gluTessVertex. The vertices specify a closed contour (the last vertex of each contour is automatically linked to the first). See the gluTessVertex, gluTessBeginContour, and gluTessEndContour reference pages for more details.

The parameter data is a pointer to a user-defined data structure. If the appropriate callback(s) are specified (see gluTessCallback), then this pointer is returned to the callback function(s). Thus, it is a convenient way to store per-polygon information.

Once gluTessEndPolygon is called, the polygon is tessellated, and the resulting triangles are described through callbacks. See gluTessCallback for descriptions of the callback functions.

SEE ALSO

"gluNewTess", "gluTessBeginContour", "gluTessVertex", "gluTessCallback", "gluTessProperty", "gluTessNormal", "gluTessEndPolygon"


gluTessCallback

NAME

gluTessCallback - define a callback for a tessellation object

C SPECIFICATION

void gluTessCallback( GLUtriangulatorObj *tobj, GLenum which, void (*fn)( )

PARAMETERS

tobj

Specifies the tessellation object (created with gluNewTess).

which

Specifies the callback being defined. The following values are valid: GLU_BEGIN, GLU_EDGE_FLAG, GLU_VERTEX, GLU_END, and GLU_ERROR.

fn

Specifies the function to be called.

DESCRIPTION

gluTessCallback is used to indicate a callback to be used by a tessellation object. If the specified callback is already defined, then it is replaced. If fn is NULL, then the existing callback is erased.

These callbacks are used by the tessellation object to describe how a polygon specified by the user is broken into triangles.

The legal callbacks are as follows:

GLU_BEGIN

The begin callback is invoked like glBegin to indicate the start of a (triangle) primitive. The function takes a single argument of type GLenum that is either GL_TRIANGLE_FAN, GL_TRIANGLE_STRIP, or GL_TRIANGLES.

GLU_EDGE_FLAG

The edge flag callback is similar to glEdgeFlag. The function takes a single Boolean flag that indicates which edges of the created triangles were part of the original polygon defined by the user, and which were created by the tessellation process. If the flag is GL_TRUE, then each vertex that follows begins an edge that was part of the original polygon. If the flag is GL_FALSE, then each vertex that follows begins an edge that was generated by the tessellator. The edge flag callback (if defined) is invoked before the first vertex callback is made.


Since triangle fans and triangle strips do not support edge flags, the begin callback is not called with GL_TRIANGLE_FAN or GL_TRIANGLE_STRIP if an edge flag callback is provided. Instead, the fans and strips are converted to independent triangles.

GLU_VERTEX

The vertex callback is invoked between the begin and end callbacks. It is similar to glVertex, and it defines the vertices of the triangles created by the tessellation process. The function takes a pointer as its only argument. This pointer is identical to the opaque pointer provided by the user when the vertex was described (see "gluTessVertex").

GLU_END

The end callback serves the same purpose as glEnd. It indicates the end of a primitive and it takes no arguments.

GLU_ERROR

The error callback is called when an error is encountered. The one argument is of type GLenum, and it indicates the specific error that occurred. There are eight errors unique to polygon tessellation, named GLU_TESS_ERROR1 through GLU_TESS_ERROR8. Character strings describing these errors can be retrieved with the gluErrorString call.

EXAMPLE

Polygons tessellated can be rendered directly like this:

gluTessCallback(tobj, GLU_BEGIN, glBegin);
gluTessCallback(tobj, GLU_VERTEX, glVertex3dv);
gluTessCallback(tobj, GLU_END, glEnd);
gluBeginPolygon(tobj);
   gluTessVertex(tobj, v, v);
   ...
gluEndPolygon(tobj);

Typically, the tessellated polygon should be stored in a display list so that it does not need to be retessellated every time it is rendered.

SEE ALSO

"glBegin", "glEdgeFlag", "glVertex", "gluDeleteTess", "gluErrorString", "gluNewTess", "gluTessVertex"


gluTessNormal

NAME

gluTessNormal - specify a normal for a polygon

C SPECIFICATION

void gluTessNormal( GLUtesselator* tess, GLdouble valueX, GLdouble valueY, GLdouble valueZ )

PARAMETERS

tess

Specifies the tessellation object (created with gluNewTess).

valueX

Specifies the first component of the normal.

valueY

Specifies the second component of the normal.

valueZ

Specifies the third component of the normal.

DESCRIPTION

The gluTessNormal subroutine describes a normal for a polygon that the program is defining. All input data will be projected onto a plane perpendicular to one of the three coordinate axes before tessellation and all output triangles will be oriented CCW with respect to the normal (CW orientation can be obtained by reversing the sign of the supplied normal). For example, if you know that all polygons lie in the XY plane, call gluTessNormal(tess, 0.0, 0.0, 1.0) before rendering any polygons.

If the supplied normal is (0.0, 0.0, 0.0) (the initial value), the normal is determined as follows. The direction of the normal, up to its sign, is found by fitting a plane to the vertices, without regard to how the vertices are connected. It is expected that the input data lies approximately in the plane; otherwise, projection perpendicular to one of the three coordinate axes may substantially change the geometry. The sign of the normal is chosen so that the sum of the signed areas of all input contours is nonnegative (where a CCW contour has positive area).

The supplied normal persists until it is changed by another call to gluTessNormal.

SEE ALSO

"gluTessBeginPolygon", "gluTessEndPolygon"


gluTessProperty

NAME

gluTessProperty - set a tessellation object property

C SPECIFICATION

void gluTessProperty( GLUtesselator* tess, GLenum which, GLdouble data )

PARAMETERS

tess

Specifies the tessellation object (created with gluNewTess).

which

Specifies the property to be set. Valid values are GLU_TESS_WINDING_RULE, GLU_TESS_BOUNDARY_ONLY, GLU_TESS_TOLERANCE.

data

Specifies the value of the indicated property.

DESCRIPTION

The gluTessProperty subroutine is used to control properties stored in a tessellation object. These properties affect the way that the polygons are interpreted and rendered. The legal values for which are as follows:

GLU_TESS_WINDING_RULE

Determines which parts of the polygon are on the "interior". data may be set to one of GLU_TESS_WINDING_ODD, GLU_TESS_WINDING_NONZERO, GLU_TESS_WINDING_POSITIVE, or GLU_TESS_WINDING_NEGATIVE, or GLU_TESS_WINDING_ABS_GEQ_TWO.

To understand how the winding rule works, consider that the input contours partition the plane into regions. The winding rule determines which of these regions are inside the polygon.

For a single contour C, the winding number of a point x is simply the signed number of revolutions we make around x as we travel once around C (where CCW is positive). When there are several contours, the individual winding numbers are summed. This procedure associates a signed integer value with each point x in the plane. Note that the winding number is the same for all points in a single region.

The winding rule classifies a region as "inside" if its winding number belongs to the chosen category (odd, nonzero, positive, negative, or absolute value of at least two). The previous GLU tessellator (prior to GLU 1.2) used the "odd" rule. The "nonzero" rule is another common way to define the interior. The other three rules are useful for polygon CSG operations.


GLU_TESS_BOUNDARY_ONLY

Is a boolean value ("value" should be set to GL_TRUE or GL_FALSE). When set to GL_TRUE, a set of closed contours separating the polygon interior and exterior are returned instead of a tessellation. Exterior contours are oriented CCW with respect to the normal; interior contours are oriented CW. The GLU_TESS_BEGIN and GLU_TESS_BEGIN_DATA callbacks use the type GL_LINE_LOOP for each contour.

GLU_TESS_TOLERANCE

Specifies a tolerance for merging features to reduce the size of the output. For example, two vertices that are very close to each other might be replaced by a single vertex. The tolerance is multiplied by the largest coordinate magnitude of any input vertex; this specifies the maximum distance that any feature can move as the result of a single merge operation. If a single feature takes part in several merge operations, the total distance moved could be larger.

Feature merging is completely optional; the tolerance is only a hint. The implementation is free to merge in some cases and not in others, or to never merge features at all. The initial tolerance is 0.

The current implementation merges vertices only if they are exactly coincident, regardless of the current tolerance. A vertex is spliced into an edge only if the implementation is unable to distinguish which side of the edge the vertex lies on. Two edges are merged only when both endpoints are identical.

SEE ALSO

"gluGetTessProperty"


gluTessVertex

NAME

gluTessVertex - specify a vertex on a polygon

C SPECIFICATION

void gluTessVertex( GLUtriangulatorObj *tobj, GLdouble v[3], void *data )

PARAMETERS

tobj

Specifies the tessellation object (created with gluNewTess).

v

Specifies the location of the vertex.

data

Specifies an opaque pointer passed back to the user with the vertex callback (as specified by gluTessCallback).

DESCRIPTION

gluTessVertex describes a vertex on a polygon that the user is defining. Successive gluTessVertex calls describe a closed contour. For example, if the user wants to describe a quadrilateral, then gluTessVertex should be called four times. gluTessVertex can only be called between gluBeginPolygon and gluEndPolygon.

data normally points to a structure containing the vertex location, as well as other per-vertex attributes such as color and normal. This pointer is passed back to the user through the GLU_VERTEX callback after tessellation (see the "gluTessCallback" reference page).

EXAMPLE

A quadrilateral with a triangular hole in it can be described as follows:

gluBeginPolygon(tobj);
   gluTessVertex(tobj, v1, v1);
   gluTessVertex(tobj, v2, v2);
   gluTessVertex(tobj, v3, v3);
   gluTessVertex(tobj, v4, v4);
gluNextContour(tobj, GLU_INTERIOR);
   gluTessVertex(tobj, v5, v5);
   gluTessVertex(tobj, v6, v6);
   gluTessVertex(tobj, v7, v7);
gluEndPolygon(tobj);

SEE ALSO

"gluBeginPolygon", "gluNewTess", "gluNextContour", "gluTessCallback"


gluUnProject

NAME

gluUnProject - map window coordinates to object coordinates

C SPECIFICATION

int gluUnProject( GLdouble winx, GLdouble winy, GLdouble winz, const GLdouble modelMatrix[16], const GLdouble projMatrix[16], const GLint viewport[4], GLdouble *objx, GLdouble *objy, GLdouble *objz )

PARAMETERS

winx, winy, winz

Specify the window coordinates to be mapped.

modelMatrix

Specifies the modelview matrix (as from a glGetDoublev call).

projMatrix

Specifies the projection matrix (as from a glGetDoublev call).

viewport

Specifies the viewport (as from a glGetIntegerv call).

objx, objy, objz

Returns the computed object coordinates.

DESCRIPTION

gluUnProject maps the specified window coordinates into object coordinates using modelMatrix, projMatrix, and viewport. The result is stored in objx, objy, and objz. A return value of GL_TRUE indicates success, and GL_FALSE indicates failure.

SEE ALSO

"glGet", "gluProject"


[Previous Section] [Back to Table of Contents] [Next Section]

OpenGL Reference Manual (Addison-Wesley Publishing Company)