gluBeginCurve, gluEndCurve - delimit a NURBS curve definition

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

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.

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);

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

gluBeginPolygon, gluEndPolygon - delimit a polygon description

void gluBeginPolygon( GLUtriangulatorObj *tobj )

void gluEndPolygon( GLUtriangulatorObj *tobj )

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.

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);

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

gluBeginSurface, gluEndSurface - delimit a NURBS surface definition

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

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.

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);

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

gluBeginTrim, gluEndTrim - delimit a NURBS trimming loop definition

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

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.

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);

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

gluBuild1DMipmaps - create 1-D mipmaps

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

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.

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

gluBuild2DMipmaps - create 2-D mipmaps

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

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.

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

gluCylinder - draw a cylinder

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

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.

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

gluDeleteNurbsRenderer - destroy a NURBS object

void gluDeleteNurbsRenderer( GLUnurbsObj *nobj )

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

"gluNewNurbsRenderer"

gluDeleteQuadric - destroy a quadrics object

void gluDeleteQuadric( GLUquadricObj *state )

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

"gluNewQuadric"

gluDeleteTess - destroy a tessellation object

void gluDeleteTess( GLUtriangulatorObj *tobj )

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

"gluBeginPolygon" , "gluNewTess" , "gluTessCallback"

gluDisk - draw a disk

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

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).

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

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

const GLubyte* gluErrorString( GLenum errorCode )

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.

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

gluGetNurbsProperty - get a NURBS property

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

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.

"gluNewNurbsRenderer" , "gluNurbsProperty"

gluLoadSamplingMatrices - load NURBS sampling and culling matrices

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

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.)

"gluGetNurbsProperty" , "gluNewNurbsRenderer" , "gluNurbsProperty"

gluLookAt - define a viewing transformation

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

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.

"glFrustum" , "gluPerspective"

gluNewNurbsRenderer - create a NURBS object

GLUnurbsObj* gluNewNurbsRenderer( void )

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.

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

gluNewQuadric - create a quadrics object

GLUquadricObj* gluNewQuadric( void )

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.

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

gluNewTess - create a tessellation object

GLUtriangulatorObj* gluNewTess( void )

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.

"gluBeginPolygon" , "gluDeleteTess" , "gluTessCallback"

gluNextContour - mark the beginning of another contour

void gluNextContour( GLUtriangulatorObj *tobj, GLenum type )

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:

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.

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);

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

gluNurbsCallback - define a callback for a NURBS object

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

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:

"gluErrorString" , "gluNewNurbsRenderer"

gluNurbsCurve - define the shape of a NURBS curve

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

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.

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);

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

gluNurbsProperty - set a NURBS property

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

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:

"gluGetNurbsProperty" , "gluLoadSamplingMatrices" , "gluNewNurbsRenderer"

gluNurbsSurface - define the shape of a NURBS surface

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 )

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.

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);

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

gluOrtho2D - define a 2-D orthographic projection matrix

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

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

"glOrtho" , "gluPerspective"

gluPartialDisk - draw an arc of a disk

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

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).

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

gluPerspective - set up a perspective projection matrix

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

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.

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

gluPickMatrix - define a picking region

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

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.

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 */

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

gluProject - map object coordinates to window coordinates

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 )

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.

"glGet" , "gluUnProject"

gluPwlCurve - describe a piecewise linear NURBS trimming curve

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

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.

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

gluQuadricCallback - define a callback for a quadrics object

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

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:

"gluErrorString" , "gluNewQuadric"

gluQuadricDrawStyle - specify the draw style desired for quadrics

void gluQuadricDrawStyle( GLUquadricObj *quadObject, GLenum drawStyle )

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

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

gluQuadricNormals - specify what kind of normals are desired for quadrics

void gluQuadricNormals( GLUquadricObj *quadObject, GLenum normals )

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

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

gluQuadricOrientation - specify inside/outside orientation for quadrics

void gluQuadricOrientation( GLUquadricObj *quadObject, GLenum orientation )

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

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

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

gluQuadricTexture - specify if texturing is desired for quadrics

void gluQuadricTexture( GLUquadricObj *quadObject, GLboolean textureCoords )

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.

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

gluScaleImage - scale an image to an arbitrary size

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

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.

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

gluSphere - draw a sphere

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

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.

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

gluTessCallback - define a callback for a tessellation object

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

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:

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.

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

gluTessVertex - specify a vertex on a polygon

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

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).

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);

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

gluUnProject - map window coordinates to object coordinates

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 )

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.

"glGet" , "gluProject"