Hp HP-UX 11.x OpenGL 1.1 Reference

OpenGL 1.1 Reference

for HP-UX 11.x

Manufacturing Part Number: B2355-IE001

Edition E0302

© Copyright 2002 by Hewlett-Packard

Legal Notices

The information contained in this document is subject to change without notice.
Hewlett-Packard assumes no responsibility for the use or reliability of its

software on equipment that is not furnished by Hewlett-Packard.
This document contains proprietary information that is protected by copyright.

All rights reserved. No part of this document may be photocopied, reproduced or
translated to another language without the prior written consent of
Hewlett-Packard Company.

Restricted Rights Legend

Use, duplication, or disclosure by the U.S. Government Department of Defense is
subject to restrictions as set forth in paragraph (b)(3)(ii) of the Rights in
Technical Data and Software clause in DFARS

252.227.7013.
This document contains proprietary information that is protected by copyright.

All rights arereserved.No part of this document may be photocopied, reproduced
or translated to another language without the prior written consent of
Hewlett-Packard Company.

UNIX is a registered trademark in the United States of America and other
countries, licensed exclusively through X/Open Company Limited.

This software and documentation is based in part on the Fourth Berkeley
Software Distribution under license from the Regents of the University of
California.

© Copyright 2002 Hewlett-Packard Company. All Rights Reserved.
© Copyright 1980, 1984 AT&T, Inc.

© Copyright 1979, 1980, 1983 The Regents of the University of California.

2

Contents

glAccum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

glAlphaFunc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

glAreaTexturesResident . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

glArrayElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

glBegin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

gluBeginCurve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

gluBeginPolygon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

gluBeginSurface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

gluBeginTrim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

glBindTexture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

glBitMap. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

glBlendColorEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

glBlendFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

gluBuild1DMipmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

gluBuild2DMipmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

glCallList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

glCallLists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

glXChooseVisual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

glClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

glClearAccum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

glClearColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

glClearDepth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54

glClearindex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55

glClearStencil. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

glClipPlane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

glColor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

glColorMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63

glColorMaterial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

glColorPointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66

glXCopyContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

glCopyPixels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70

glCopyTexImage1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

glCopyTexImage2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

glCopyTexSubImage1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

glCopyTexSubImage2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

glCopyTexSubImage3DEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

glXCreateContext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

glXCreateGLXPixmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

3

Contents

glCullFace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

gluCylinder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

glDeleteLists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

gluDeleteNurbsRenderer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

gluDeleteQuadric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

gluDeleteTess. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97

glDeleteTextures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

glDepthFunc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

glDepthMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

glDepthRange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

glXDestroyContext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

glXDestroyGLXPixmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

glDisable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

gluDisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

glDrawArrays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

glDrawArraysSethp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

glDrawBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

glDrawElements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

glDrawPixels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

glEdgeFlag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

glEdgeFlagPointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

glEnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

glEnableClientState. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

glErrorString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

glEvalCoord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

glEvalMesh. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

glEvalPoint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

glFeedbackBuffer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

glFinish. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

glFlush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

glFog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

glFrontFace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

glFrustum. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

glGenLists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

glGenTextures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

glGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

4

Contents

glXGetClientString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

glXGetClipPlane. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

glXGetConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

glXGetCurrentContext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

glXGetCurrentDisplay. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

glXGetCurrentDrawable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

glGetError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

glGetLight. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

glGetMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

glGetMaterial. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

gluGetNurbsProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

glGetPixelMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

glGetPointer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

glGetPolygonStipple. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

glGetString. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

gluGetString. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

gluGetTessProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

glGetTexEnv. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

glGetTexGen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

glGetTexImage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

glGetTexLevelParameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

glGetTexParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

glHint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

glIndex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

glIndexMask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

glIndexPointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

glInitNames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

glInterleavedArrays. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

glXIntro. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

glXIsDirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

glIsEnabled. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

glIsList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

glIsTexture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

glLight. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

glLightModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

glLineStipple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

glLineWidth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

glListBase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

5

Contents

glLoadIdentity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

glLoadMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

glLoadName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

gluLoadSamplingMatrices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

glLogicOp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

gluLookAt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

glXMakeCurrent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

glMap1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

glMap2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

glMapGrid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

glMaterials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

glMatrixMode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

glMultMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

glNewList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

glNextVisibilityTesthp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

gluNewNurbsRenderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

gluNewQuadric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

gluNewTess. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

gluNextContour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

glNormal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

glNormalPointer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

gluNurbsCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

gluNurbsCurve. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

gluNurbsPrperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

gluNurbsSurface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

glOrtho . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

gluOrtho2D. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

gluPartialDisk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

glPassThrough . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

gluPerspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

gluPickMatrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

glPixelMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

glPixelStore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

glPixelTransfer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

glPixelZoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

glPointSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

6

Contents

glPolygonMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

glPolygonOffset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

glPolygonStipple. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

glPrioritizeTextures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

gluProject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

glPushAttrib. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

glPushClientAttrib. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

glPushMatrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

glPushName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

gluPwlCurve. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

gluQuadricCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

gluQuadricDrawStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

gluQuadricNormals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

gluQuadricOrientation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

gluQuadricTexture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

glXQueryExtension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

glXQueryExtensionsString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370

glXQueryServerString. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

glXQueryVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

glRasterPos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

glReadBuffer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

glReadPixels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

glRect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

glRenderMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

glRotate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

glScale. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392

gluScaleImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394

glScissor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

glSelectBuffer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

glShadeModel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

gluSphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

glStencilFunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

glStencilMask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

glStencilOp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

glXSwapBuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408

gluTessBeginContour. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

gluTessBeginPolygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

gluTessCallback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

7

Contents

gluTessEndPolygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

gluTessNormal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

gluTessProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418

gluTessVertex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

glTexCoord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

glTexCoordPointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

glTexEnv. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

glTexGen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

glTexImage1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

glTexImage2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

glTexImage3DEXT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

glTexParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449

glTexSubImage1D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

glTexSubImage2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

glTexSubImage3DEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461

glTranslate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

gluUnProject. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468

glXUseXFont. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470

glVertex. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474

glVertexPointer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477

glViewport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

glVisibilityBufferhp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

glXWaitGL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

glXWaitX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485

8

1A

Chapter 1

9

A

glAccum

glAccum

glAccum: operate on the accumulation buffer.

C Specification

void glAccum(

GLenum op,
GLfloat value)

Parameters

op Specifies the accumulation buffer operation. Symbolic constants

GL_ACCUM, GL_LOAD, GL_ADD, GL_MULT, and GL_RETURN are
accepted.

value Specifies a floating-point value used in the accumulation buffer

operation. op determines how value is used.

Description

The accumulation buffer is an extended-range color buffer. Images are not rendered into
it. Rather, images rendered into one of the color buffers are added to the contents of the
accumulation buffer after rendering. Effects such as anti-aliasing (of points, lines, and
polygons), motion blur, and depth of field can be created by accumulating images
generated with different transformation matrices.

Each pixel in the accumulation buffer consists of red, green, blue, and alpha values. The
number of bits per component in the accumulation buffer depends on the
implementation. You can examine this number by calling glGetIntegerv four times, with
arguments:

GL_ACCUM_RED_BITS,
GL_ACCUM_GREEN_BITS,
GL_ACCUM_BLUE_BITS, and
GL_ACCUM_ALPHA_BITS.

Regardless of the number of bits per component, the range of values stored by each
component is [- 1, 1]. The accumulation buffer pixels are mapped one-to-one with frame
buffer pixels.

glAccum operates on the accumulation buffer. The first argument, op, is a symbolic
constant that selects an accumulation buffer operation. The second argument, value,isa
floating-point value to be used in that operation. Five operations are specified:
GL_ACCUM, GL_LOAD, GL_ADD, GL_MULT, and GL_RETURN.

10

All accumulation buffer operations are limited to the area of the current scissor box and
applied identically to the red, green, blue, and alpha components of each pixel. If a
glAccum operation results in a value outside the range [- 1, 1], the contents of an
accumulation buffer pixel component are undefined.

The operations are as follows:
GL_ACCUM Obtains R, G, B, and A values from the buffer currently selected for

reading (see glReadBuffer).

Chapter 1

glAccum

Each component value is divided by 2n -1, where n is the number of
bits allocated to each color component in the currently selected buffer.
The result is a floating-point value in the range [0, 1], which is
multiplied by value and added to the corresponding pixel component in
the accumulation buffer, thereby updating the accumulation buffer.

GL_LOAD Similar to GL_ACCUM, except that the current value in the

accumulation buffer is not used in the calculation of the new value.
That is, the R, G,B, and A values from the currently selected buffer are

divided by 2n - 1, multiplied by value, and then stored in the

corresponding accumulation buffer cell, overwriting the current value.
GL_ADD Adds value to each R, G, B, and A in the accumulation buffer.
GL_MULT Multiplies each R, G,B, and A in the accumulation buffer by value and

returns the scaled component to its corresponding accumulation buffer

location.
GL_RETURN Transfers accumulation buffer values to the color buffer or buffers

currently selected for writing. Each R, G, B, and A component is

multiplied by value, then multiplied by 2n- 1, clamped to the range [0,

2n - 1], and stored in the corresponding display buffer cell. The only

fragment operations that are applied to this transfer are pixel

ownership, scissor, dithering, and color writemasks.

A

To clear the accumulation buffer, call glClearAccum with R, G, B, and A values to set it
to, then call glClear with the accumulation buffer enabled.

Notes

Only pixels within the current scissor box are updated by a glAccum operation.

Errors

• GL_INVALID_ENUM is generated if op is not an accepted value.

• GL_INVALID_OPERATION is generated if there is no accumulation buffer.

• GL_INVALID_OPERATION is generated if glAccum is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_ACCUM_RED_BITS
glGet with argument GL_ACCUM_GREEN_BITS
glGet with argument GL_ACCUM_BLUE_BITS

glGet with argument GL_ACCUM_ALPHA_BITS

See Also

Chapter 1

glBlendFunc,
glClear,
glClearAccum,
glCopyPixels,
glGet,

11

A

glAccum

glLogicOp,
glPixelStore,
glPixelTransfer,
glReadBuffer,
glReadPixels,
glScissor,
glStencilOp

12

Chapter 1

glAlphaFunc

glAlphaFunc

glAlphaFunc: specify the alpha test function.

C Specification

void glAlphaFunc(

GLenum func,
GLclampf ref)

Parameters

func Specifies the alpha comparison function. Symbolic constants

GL_NEVER, GL_LESS, GL_EQUAL, GL_LEQUAL, GL_GREATER,

GL_NOTEQUAL, GL_GEQUAL, and GL_ALWAYS are accepted. The

initial value is GL_ALWAYS.
ref Specifies the reference value that incoming alpha values are compared

to. This value is clamped to the range 0 through 1, where 0 represents

the lowest possible alpha value and 1 the highest possible value. The

initial reference value is 0.

A

Description

The alpha test discards fragments depending on the outcome of a comparison between
an incoming fragment’s alpha value and a constant reference value.

glAlphaFunc specifies the reference value and the comparison function. The comparison
is performed only if alpha testing is enabled. By default, it is not enabled. (See glEnable
and glDisable of GL_ALPHA_TEST.)

func and ref specify the conditions under which the pixel is drawn. The incoming alpha
value is compared to ref using the function specified by func. If the value passes the
comparison, the incoming fragment is drawn if it also passes subsequent stencil and
depth buffer tests. If the value fails the comparison, no change is made to the frame
buffer at that pixel location. The comparison functions are as follows:

GL_NEVER Never passes.
GL_LESS Passes if the incoming alpha value is less than the reference value.
GL_EQUAL Passes if the incoming alpha value is equal to the reference value.
GL_LEQUAL Passesif the incoming alpha value is less than or equal to the reference

value.
GL_GREATER Passes if the incoming alpha value is greater than the reference value.
GL_NOTEQUAL Passes if the incoming alpha value is not equal to the reference value.
GL_GEQUAL Passes if the incoming alpha value is greater than or equal to the

reference value.

Chapter 1

GL_ALWAYS Always passes (initial value).

13

A

glAlphaFunc

glAlphaFunc operates on all pixel write operations, including those resulting from the
scan conversion of points, lines, polygons, and bitmaps, and from pixel draw and copy
operations. glAlphaFunc does not affect screen-clear operations.

Notes

Alpha testing is performed only in RGBA mode.

Errors

• GL_INVALID_ENUM is generated if func is not an accepted value.

• GL_INVALID_OPERATION is generated if glAlphaFunc is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_ALPHA_TEST_FUNC
glGet with argument GL_ALPHA_TEST_REF

glIsEnabled with argument GL_ALPHA_TEST

See Also

glBlendFunc,
glClear,
glDepthFunc,
glEnable,
glStencilFunc

14

Chapter 1

glAreaTexturesResident

glAreaTexturesResident

glAreaTexturesResident: determine if textures are loaded in texture memory.

C Specification

GLboolean glAreTexturesResident(

GLsizei n,
const GLuint *textures,

GLboolean *residences)

Parameters

n Specifies the number of textures to be queried.
textures Specifies an array containing the names of the textures to be queried.
residences Specifies an array in which the texture residence status is returned.

The residence status of a texture named by an element of textures is

returned in the corresponding element of residences.

A

Description

GL establishes a “working set” of textures that are resident in texture memory. These
textures can be bound to a texture target much more efficiently than textures that are
not resident.

glAreTexturesResident queries the texture residence status of the n textures named by
the elements of textures. If all the named textures are resident, glAreTexturesResident
returns GL_TRUE, and the contents of residences are undisturbed. If not all the named
textures are resident, glAreTexturesResident returns GL_FALSE, and detailed status is
returned in the n elements of residences. If an element of residences is GL_TRUE, then
the texture named by the corresponding element of textures is resident.

The residence status of a single bound texture may also be queried by calling
glGetTexParameter with the target argument set to the target to which the texture is
bound, and the p_name argument set to GL_TEXTURE_RESIDENT. This is the only

way that the residence status of a default texture can be queried.

Notes

glAreTexturesResident is available only if the GL version is 1.1 or greater.
glAreTexturesResident returns the residency status of the textures at the time of

invocation. It does not guarantee that the textures will remain resident at any other
time.

If textures reside in virtual memory (there is no texture memory), they are considered
always resident.

Chapter 1

Some implementations may not load a texture until the first use of that texture.

15

A

glAreaTexturesResident

Errors

• GL_INVALID_VALUE is generated if n is negative.

• GL_INVALID_VALUE is generated if any element in textures is 0 or does not name a

• GL_INVALID_OPERATION is generated if glAreTexturesResident is executed

Associated Gets

glGetTexParameter with parameter name GL_TEXTURE_RESIDENT retrieves the
residence status of a currently bound texture.

See Also

glBindTexture,
glGetTexParameter,
glPrioritizeTextures,
glTexImage1D,
glTexImage2D,

glTexParameter

texture. In that case, the function returns GL_FALSE and the contents of residences
is indeterminate.

between the execution of glBegin and the corresponding execution of glEnd.

16

Chapter 1

glArrayElement

glArrayElement

glArrayElement: render a vertex using the specified vertex array element.

C Specification

void glArrayElement(

GLint i)

Parameters

i Specifies an index into the enabled vertex data arrays.

Description

glArrayElement commands are used within glBegin/glEnd pairs to specify vertex and
attribute data for point, line, and polygon primitives. If GL_VERTEX_ARRAY is enabled
when glArrayElement is called, a single vertex is drawn, using vertex and attribute data
taken from location i of the enabled arrays. If GL_VERTEX_ARRAY is not enabled, no
drawing occurs but the attributes corresponding to the enabled arrays are modified.

A

Use glArrayElement to construct primitives by indexing vertex data, rather than by
streaming through arrays of data in first-to-last order. Because each call specifies only a
single vertex, it is possible to explicitly specify per-primitive attributes such as a single
normal per individual triangle.

Changes made to array data between the execution of glBegin and the corresponding
execution of glEnd may affect calls to glArrayElement that are made within the same
glBegin/glEnd period in non-sequential ways. That is, a call to glArrayElement that
precedes a change to array data may access the changed data, and a call that follows a

change to array data may access original data.

Notes

glArrayElement is available only if the GL version is 1.1 or greater.
glArrayElement is included in display lists. If glArrayElement is entered into a display

list, the necessary array data (determined by the array pointers and enables) is also
entered into the display list. Because the array pointers and enables are client-side
state, their values affect display lists when the lists are created, not when the lists are

executed.

See Also

glColorPointer,
glDrawArrays,
glEdgeFlagPointer,
glGetPointer,
glIndexPointer,
glInterleavedArrays,

Chapter 1

17

A

glArrayElement

glNormalPointer,
glTexCoordPointer,

glVertexPointer

18

Chapter 1

2B

Chapter 2

19

B

glBegin

glBegin

glBegin, glEnd: delimit the vertices of a primitive or a group of like primitives.

C Specification

void glBegin(

GLenum mode)

void glEnd(void)

Parameters

mode Specifies the primitive or primitives that will be created from vertices

presented between glBegin and the subsequent glEnd. Ten symbolic

constants are accepted:

GL_POINTS, GL_LINES, GL_LINE_STRIP, GL_LINE_LOOP,

GL_TRIANGLES, GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN,

GL_QUADS, GL_QUAD_STRIP, and GL_POLYGON.

Description

glBegin and glEnd delimit the vertices that define a primitive or a group of like
primitives. glBegin accepts a single argument that specifies in which of ten ways the
vertices are interpreted. Taking n as an integer count starting at one, and n as the total
number of vertices specified, the interpretations are as follows:

GL_POINTS Treats each vertex as a single point. Vertex n defines point n. n points

are drawn.
GL_LINES Treats each pair of vertices as an independent line segment. Vertices

2n - 1 and 2n define line n. n/2 lines are drawn.
GL_LINE_STRIP

Draws a connected group of line segments from the first vertex to the

last. n - 1 lines are drawn.
GL_LINE_LOOP

Draws a connected group of line segments from the first vertex to the

last, then back to the first. Vertices n and n+1 define line n. The last

line, however, is defined by vertices n and 1. n lines are drawn.
GL_TRIANGLES

Treats each triplet of vertices as an independent triangle. Vertices 3n-

2, 3n - 1, and 3n define triangle n. n/3 triangles are drawn.
GL_TRIANGLE_STRIP

Draws a connected group of triangles. One triangle is defined for each

vertex presented after the first two vertices. For odd n, vertices n, n+1,

and n+2 define triangle n. For even n, vertices n+1, n, and n+2 define

triangle n. n2 triangles are drawn.

20

Chapter 2

glBegin

GL_TRIANGLE_FAN

Draws a connected group of triangles. One triangle is defined for each

vertex presented after the first two vertices. Vertices 1, n+1, and n+2

define triangle n. n - 2 triangles are drawn.
GL_QUADS

Treats each group of four vertices as an independent quadrilateral.

Vertices 4n - 3, 4n - 2, 4n - 1, and 4n define quadrilateral n. n/4

quadrilaterals are drawn.
GL_QUAD_STRIP

Draws a connected group of quadrilaterals. One quadrilateral is

defined for each pair of vertices presented after the first pair. Vertices

2n -1, 2n, 2n+2, and 2n+1 define quadrilateral n. n/21 quadrilaterals

are drawn. Note that the order in which vertices are used to construct

a quadrilateral from strip data is different from that used with

independent data.
GL_POLYGON

Draws a single, convex polygon. Vertices 1 through n define this

polygon.
Only a subset of GL commands can be used between glBegin and glEnd. The commands

are glVertex, glColor, glIndex, glNormal, glTexCoord, glEvalCoord, glEvalPoint,
glArrayElement, glMaterial, and glEdgeFlag. Also, it is acceptable to use glCallList or
glCallLists to execute display lists that include only the preceding commands. If any
other GL command is executed between glBegin and glEnd, the error flag is set and the
command is ignored.

B

Regardless of the value chosen for mode, there is no limit to the number of vertices that
can be defined between glBegin and glEnd. Lines,triangles, quadrilaterals, and polygons
that are incompletely specified are not drawn. Incomplete specification results when
either too few vertices are provided to specify even a single primitive or when an
incorrect multiple of vertices is specified. The incomplete primitive is ignored; the rest
are drawn.

The minimum specification of vertices for each primitive is as follows: 1 for a point, 2 for
a line, 3 for a triangle, 4 for a quadrilateral, and 3 for a polygon. Modes that require a
certain multiple of vertices are GL_LINES (2), GL_TRIANGLES (3), GL_QUADS (4),
and GL_QUAD_STRIP (2).

Errors

• GL_INVALID_ENUM is generated if mode is set to an unaccepted value.

• GL_INVALID_OPERATION is generated if glBegin is executed between a glBegin

and the corresponding execution of glEnd.

• GL_INVALID_OPERATION is generated if glEnd is executed without being

preceded by a glBegin.

• GL_INVALID_OPERATION is generated if a command other than glVertex, glColor,

glIndex, glNormal, glTexCoord, glEvalCoord, glEvalPoint, glArrayElement,
glMaterial, glEdgeFlag, glCallList, or glCallLists is executed between the execution
of glBegin and the corresponding execution glEnd.

Chapter 2

21

B

glBegin

Execution of glEnableClientState, glDisableClientState, glEdgeFlagPointer,
glTexCoordPointer, glColorPointer, glIndexPointer, glNormalPointer, glVertexPointer,
glInterleavedArrays, or glPixelStore is not allowed after a call to glBegin and before the

corresponding call to glEnd, but an error may or may not be generated.

See Also

glArrayElement,
glCallList,
glCallLists,
glColor,
glEdgeFlag,
glEvalCoord,
glEvalPoint,
glIndex,
glMaterial,
glNormal,
glTexCoord,

glVertex

22

Chapter 2

gluBeginCurve

gluBeginCurve

gluBeginCurve, gluEndCurve: delimit a NURBS curve definition.

C Specification

void gluBeginCurve(

GLUnurbs* nurb)

void gluEndCurve(

GLUnurbs* nurb)

Parameters

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

B

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

See Also

gluBeginSurface,
gluBeginTrim,
gluNewNurbsRenderer,
gluNurbsCurve,
glPopAttrib,

glPushAttrib

Chapter 2

23

B

gluBeginPolygon

gluBeginPolygon

gluBeginPolygon, gluEndPolygon: delimit a polygon description.

C Specification

void gluBeginPolygon(

GLUtesselator* tess)

void gluEndPolygon(

GLUtesselator* tess)

Parameters

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

Notes

This command is obsolete and is provided for backward compatibility only. Calls to
gluBeginPolygon are mapped to gluTessBeginPolygon followed by gluTessBeginContour.
Calls to gluEndPolygon are mapped to gluTessEndContour followed by

gluTessEndPolygon.

See Also

gluNewTess,
gluNextContour,
gluTessCallback,
gluTessVertex,
gluTessBeginPolygon,

gluTessBeginContour

24

Chapter 2

gluBeginSurface

gluBeginSurface

gluBeginSurface, gluEndSurface: delimit a NURBS surface definition.

C Specification

void gluBeginSurface(

GLUnurbs* nurb)

void gluEndSurface(

GLUnurbs* nurb)

Parameters

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

B

Trimming of NURBS surfaces is supported with gluBeginTrim, gluPwlCurve,
gluNurbsCurve, andgluEndTrim. See the gluBeginTrim reference page for details.

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

See Also

gluBeginCurve,
gluBeginTrim,
gluNewNurbsRenderer,
gluNurbsCurve,
gluNurbsSurface,

gluPwlCurve

Chapter 2

25

B

gluBeginTrim

gluBeginTrim

gluBeginTrim, gluEndTrim: delimit a NURBS trimming loop definition.

C Specification

void gluBeginTrim(

GLUnurbs* nurb)

void gluEndTrim(

GLUnurbs* nurb)

Parameters

nurb 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 piece wise 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).

26

Chapter 2

gluBeginTrim

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. If trimming curves
are self-intersecting, or intersect one another, an error results.

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

See Also

gluBeginSurface,
gluNewNurbsRenderer,
gluNurbsCallback,
gluNurbsCurve,

gluPwlCurve

B

Chapter 2

27

B

glBindTexture

glBindTexture

glBindTexture: bind a named texture to a texture target.

C Specification

void glBindTexture(

GLenum target,
GLuint texture)

Parameters

target Specifies the target to which the texture is bound. Must be either

GL_TEXTURE_1D or GL_TEXTURE_2D. Initially, both

GL_TEXTURE_1D and GL_TEXTURE_2D are bound to texture 0.
texture Specifies the name of a texture.

Description

glBindTexture binds the texture named texture to the specified target. If the name does
not exist, it is created. target must be either GL_TEXTURE_1D or GL_TEXTURE_2D.
When a texture is bound to a target, the previous binding for that target is broken.

Texture names are unsigned integers. The value 0 is reserved to represent the default
texture for each texture target. glGenTextures may be used to generate a set of new
texture names.

When a texture is first bound, it assumes the dimensionality of its target: A texture first
bound to GL_TEXTURE_1D becomes one-dimensional and a texture first bound to
GL_TEXTURE_2D becomes two-dimensional. The state of a one-dimensional texture
immediately after it is first bound is equivalent to the state of the default
GL_TEXTURE_1D at GL initialization, and similarly for two-dimensional textures.

While a texture is bound, GL operations on the target to which it is bound affect the
bound texture, and queries of the target to which it is bound return state from the bound
texture. If texture mapping of the dimensionality of the target to which a texture is
bound is active, the bound texture is used. In effect, the texture targets become aliases
for the textures currently bound to them, and the texture name “0” refers to the default
textures that were bound to them at initialization.

A texture binding created with glBindTexture remains active until a different texture is
bound to the same target, or until the bound texture is deleted with glDeleteTextures.
When a bound texture is deleted, the default texture is bound to that target.

28

Once created, a named texture may be re-bound to the target of the matching
dimensionality as often as needed. It is usually much faster to use glBindTexture to bind
an existing named texture to one of the texture targets than it is to reload the texture
image using glTexImage1D or glTexImage2D. For additional control over performance,
use glPrioritizeTextures.

Chapter 2

glBindTexture

Notes

glBindTexture is available only if the GL version is 1.1 or greater.

Errors

• GL_INVALID_ENUM is generated if target is not one of the allowable values.

• GL_INVALID_OPERATION is generated if texture has a dimensionality that

doesn’t match that of target.

• GL_INVALID_OPERATION is generated if glBindTexture is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_TEXTURE_1D_BINDING
glGet with argument GL_TEXTURE_2D_BINDING

See Also

B

glAreTexturesResident,
glDeleteTextures,
glGenTextures,
glGet,
glGetTexParameter,
glIsTexture,
glPrioritizeTextures,
glTexImage1D,
glTexImage2D,

glTexParameter

Chapter 2

29

B

glBitMap

glBitMap

glBitmap: draw a bitmap.

C Specification

void glBitmap(

GLsizei width,
GLsizei height,
GLfloat xorig,
GLfloat yorig,
GLfloat xmove,
GLfloat ymove,

const GLubyte *bitmap)

Parameters

width, height Specify the pixel width and height of the bitmap image.
xorig, yorig Specify the location of the origin in the bitmap image. The origin is

measured from the lower left corner of the bitmap, with right and up

being the positive axes.
xmove, ymove Specify the x and y offsets to be added to the current raster position

after the bitmap is drawn.
bitmap Specifies the address of the bitmap image.

Description

A bitmap is a binary image. When drawn,the bitmap is positioned relative to the current
raster position, and frame buffer pixels corresponding to 1s in the bitmap are written
using the current raster color or index. Frame buffer pixels corresponding to 0s in the
bitmap are not modified.

glBitmap takes seven arguments. The first pair specifies the width and height of the
bitmap image. The second pair specifies the location of the bitmap origin relative to the
lower left corner of the bitmap image. The third pair of arguments specifies x and y
offsets to be added to the current raster position after the bitmap has been drawn. The
final argument is a pointer to the bitmap image itself.

The bitmap image is interpreted like image data for the glDrawPixels command, with
width and height corresponding to the width and height arguments of that command,
and with type set to GL_BITMAP and format set to GL_COLOR_INDEX.

Modes specified using glPixelStore affect the interpretation of bitmap image data; modes
specified using glPixelTransfer do not.

30

If the current raster position is invalid, glBitmap is ignored. Otherwise, the lower left
corner of the bitmap image is positioned at the window coordinates

xw =xr - x
yw = yr - y



o



o

Chapter 2

glBitMap

where (xr, yr) is the raster position and (xo, yo) is the bitmap origin. Fragments are then
generated for each pixel corresponding to a 1 (one) in the bitmap image. These fragments

are generated using the current raster z coordinate, color or color index, and current
raster texture coordinates. They are then treated just as if they had been generated by a
point, line, or polygon, including texture mapping, fogging, and all per-fragment
operations such as alpha and depth testing.

After the bitmap has been drawn, the x and y coordinates of the current raster position
are offset by xmove and ymove. No change is made to the z coordinate of the current

raster position, or to the current raster color, texture coordinates, or index.

Notes

To set a valid raster position outside the viewport, first set a valid raster position inside
the viewport, then call glBitmap with NULL as the bitmap parameter and with xmove
and ymove set to the offsets of the new raster position. This technique is useful when

panning an image around the viewport.

Errors

B

• GL_INVALID_VALUE is generated if width or height is negative.

• GL_INVALID_OPERATION is generated if glBitmap is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_CURRENT_RASTER_POSITION
glGet with argument GL_CURRENT_RASTER_COLOR
glGet with argument GL_CURRENT_RASTER_INDEX
glGet with argument GL_CURRENT_RASTER_TEXTURE_COORDS

glGet with argument GL_CURRENT_RASTER_POSITION_VALID

See Also

glDrawPixels,
glPixelStore,
glPixelTransfer,

glRasterPos

Chapter 2

31

B

glBlendColorEXT

glBlendColorEXT

glBlendColorEXT: set the blend color.

C Specification

void glBlendColorEXT(

GLclampf red,
GLclampf green,
GLclampf blue,
GLclampf alpha)

Parameters

red, green, blue, alpha Specify the components of GL_BLEND_COLOR_EXT.

Description

The GL_BLEND_COLOR_EXT may be used to calculate the source and destination
blending factors. See glBlendFunc for a complete description of the blending operations.

Initially the GL_BLEND_COLOR_EXT is set to (0, 0, 0, 0).

Notes

glBlendColorEXT is part of the EXT_blend_color extension, not part of the core GL
command set. If GL_EXT_blend_color is included in the string returned by glGetString,
when called with argument GL_EXTENSIONS, extension EXT_blend_color is supported

by the connection.

Errors

• GL_INVALID_OPERATION is generated if glBlendColorEXT is executed between

the execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with an argument of GL_BLEND_COLOR_EXT.

See Also

glBlendFunc,
glGetString

32

Chapter 2

glBlendFunc

glBlendFunc

glBlendFunc: specify pixel arithmetic.

C Specification

void glBlendFunc(

GLenum sfactor,
GLenum dfactor)

Parameters

sfactor Specifies how the red, green, blue, and alpha source blending factors

are computed. Nine symbolic constants are accepted:

GL_ZERO, GL_ONE, GL_DST_COLOR,

GL_ONE_MINUS_DST_COLOR, GL_SRC_ALPHA,

GL_ONE_MINUS_SRC_ALPHA, GL_DST_ALPHA,

GL_ONE_MINUS_DST_ALPHA, and GL_SRC_ALPHA_SATURATE.

The initial value is GL_ONE.

B

dfactor Specifies how the red, green, blue, and alpha destination blending

factors are computed. Eight symbolic constants are accepted:

GL_ZERO, GL_ONE, GL_SRC_COLOR,

GL_ONE_MINUS_SRC_COLOR, GL_SRC_ALPHA,

GL_ONE_MINUS_SRC_ALPHA, GL_DST_ALPHA, and

GL_ONE_MINUS_DST_ALPHA.

The initial value is GL_ZERO.

Description

In RGBA mode, pixels can be drawn using a function that blends the incoming (source)
RGBA values with the RGBA values that are already in the frame buffer (the
destination values). Blending is initially disabled. Use glEnable and glDisable with
argument GL_BLEND to enable and disable blending.

glBlendFunc defines the operation of blending when it is enabled. sfactor specifies which
of nine methods is used to scale the source color components. dfactor specifies which of
eight methods is used to scale the destination color components. The eleven possible
methods are described in the following table. Each method defines four scale factors, one
each for red, green, blue, and alpha.

In the table and in subsequent equations, source and destination color components are
referred to as (Rs, Gs, Bs, As) and (Rd, Gd, Bd, Ad). They are understood to have integer

values between 0 and (kR, kG, kB, kA), where

Chapter 2

kc= 2mc - 1
and (mR, mG, mB, mA) is the number of red, green, blue, and alpha bitplanes.
Source and destination scale factors are referred to as (sR,sG,sB,sA) and (dR,dG,dB,dA).

The scale factors described in the table, denoted (fR,fG,fB,fA), represent either source or
destination factors. All scale factors have range [0,1].

33

B

glBlendFunc

Table 2-1

Parameters

Parameter

(fR, fG, fB, fA)

GL_ZERO (0, 0, 0, 0)
GL_ONE (1, 1, 1, 1)
GL_SRC_COLOR (Rs/kR, Gs/kG, Bs/kB, As/kA)

GL_ONE_MINUS_SRC_COLOR (1,1,1,1) - (Rs/kR, Gs/kG, Bs/kB, As/kA)
GL_DST_COLOR (Rd/kR, Gd/kG, Bd/kB, Ad/kA)
GL_ONE_MINUS_DST_COLOR (1, 1, 1, 1) - (Rd/kR, Gd/kG, Bd/kB, Ad/kA)
GL_SRC_ALPHA (As/kA, As/kA, As/kA, As/kA)
GL_ONE_MINUS_SRC_ALPHA (1, 1, 1, 1) - (As/kA, As/kA, As/kA, As/kA)
GL_DST_ALPHA (Ad/kA, Ad/kA,Ad/kA,Ad/kA)
GL_ONE_MINUS_DST_ALPHA (1, 1, 1, 1) - (Ad/kA, Ad/kA,Ad/kA,Ad/kA)
GL_SRC_ALPHA_SATURATE (i, i, i,1)

In the table,
i = min(As, kA - Ad) / k

A

To determine the blended RGBA values of a pixel when drawing in RGBA mode, the
system uses the following equations:

Rd = min(kR, Rs sR + Rd dR)
Gd = min(kG, Gs sG + Gd dG)
Bd = min(kB, BssB + Bd dB)
Ad = min(kA, As sA + Ad dA)
Despite the apparent precision of the above equations, blending arithmetic is not exactly

specified, because blending operates with imprecise integer color values. However, a
blend factor that should be equal to 1 is guaranteed not to modify its multiplicand, and a
blend factor equal to 0 reduces its multiplicand to 0. For example, when sfactor is
GL_SRC_ALPHA, dfactor is GL_ONE_MINUS_SRC_ALPHA, and Asis equal to kA, the

equations reduce to simple replacement:
Rd = R

Gd = G
Bd = B

Ad = A

s

s

s

s

34

Chapter 2

glBlendFunc

Examples

Blend function (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) is also useful for
rendering anti-aliased points and lines in arbitrary order.

Polygon anti-aliasing is optimized using blend function (GL_SRC_ALPHA_SATURATE,
GL_ONE) with polygons sorted from nearest to farthest. (See the glEnable, glDisable
reference page and the GL_POLYGON_SMOOTH argument for information on polygon
anti-aliasing.) Destination alpha bitplanes, which must be present for this blend

function to operate correctly, store the accumulated coverage.

Notes

Incoming (source) alpha is correctly thought of as a material opacity, ranging from 1.0
(KA), representing complete opacity, to 0.0 (0), representing complete transparency.

When more than one color buffer is enabled for drawing, the GL performs blending
separately for each enabled buffer, using the contents of that buffer for destination color.
(See glDrawBuffer.)

Blending affects only RGBA rendering. It is ignored by color index renderers.

B

Errors

• GL_INVALID_ENUM is generated if either sfactor or dfactor is not an accepted

value.

• GL_INVALID_OPERATION is generated if glBlendFunc is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_BLEND_SRC
glGet with argument GL_BLEND_DST

glIsEnabled with argument GL_BLEND

See Also

glAlphaFunc,
glClear,
glDrawBuffer,
glEnable,
glLogicOp,

glStencilFunc

Chapter 2

35

B

gluBuild1DMipmaps

gluBuild1DMipmaps

gluBuild1DMipmaps: create 1D mipmaps.

C Specification

GLint gluBuild1DMipmaps(

GLenum target,
GLint component,
GLsizei width,
GLenum format,
GLenum type,

const void *data)

Parameters

target Specifies the target texture. Must be GL_TEXTURE_1D.
component 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 builds a series of pre-filtered 1D texture maps of decreasing
resolution. Mipmaps can be used so that textures don’t appear aliased.

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

gluBuild1DMipmaps first checks whether the width of data is a power of 2. If not, it
scales a copy of data (up or down) to the nearest power of two. This copy is used as the
base for subsequent mipmapping operations. For example, if width is 57, a copy of data
scales up to 64 before mipmapping takes place. (If width is exactly between powers of 2,
the copy of data is scaled upward.)

36

If the GL version is 1.1 or greater, gluBuild1DMipmaps uses proxy textures (see
glTexImage1D) to determine if the implementation can store the requested texture in
texture memory. If there isn’t enough room, width is halved (and halved again) until it
fits.

Chapter 2

gluBuild1DMipmaps

Next, gluBuild1DMipmaps builds a series of mipmap levels; it halves a copy of data (or a
scaled version of data, if necessary) until size 1 is reached. At each level, each texel in
the halved image is an average of the corresponding two texels in the larger image.

glTexImage1D is called to load each of these images by level. If width is a power of 2
which fits in the implementation, level 0 is a copy of data, and the highest level is log2
width. For example, if width is 64, the following images are built: 64x1, 32x1, 16x1, 8x1,
4x1, 2x1 and 1x1. These correspond to levels 0 through 6, respectively.

See the glTexImage1D reference page for a description of the acceptable values for type.
See the glDrawPixels reference page for a description of the acceptable values for data.

Notes

While you can’t query the maximum level directly, you can derive it indirectly by calling
glGetTexLevelParameter. First, query for the width actually used at level 0. (The width
may be unequal to width since gluBuild1DMipmaps might have shrunk or expanded
width if width isn’t a power of 2 or if the implementation only supports smaller textures.

The maximum level can then be derived using the formula log2width.

Errors

B

• GLU_INVALID_VALUE is returned if width is negative.

• GLU_INVALID_ENUM is returned if format or type is not one of the accepted

values.

Bugs

PassingGL_STENCIL_INDEX or GL_DEPTH_COMPONENT as format will incorrectly
return 0 and set the error code to GL_INVALID_ENUM. It should return

GLU_INVALID_ENUM and not set an error code.

See Also

glTexImage1D,
gluBuild2DMipmaps,
gluErrorString,
gluScaleImage

Chapter 2

37

B

gluBuild2DMipmaps

gluBuild2DMipmaps

gluBuild2DMipmaps: create 2D mipmaps.

C Specification

GLint gluBuild2DMipmaps(

GLenum target,
GLint component,
GLsizei width,
GLsizei height,
GLenum format,
GLenum type,

const void *data)

Parameters

target Specifies the target texture. Must be GL_TEXTURE_2D.
component Specifies the number of color components in the texture. Must be 1, 2,

3, or 4.

target Specifies the target texture. Must be GL_TEXTURE_2D.
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 builds a series of pre-filtered 2D texture maps of decreasing
resolution. Mipmaps can be used so that textures don’t appear aliased.

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

gluBuild2DMipmaps first check whether width and height of data are both powers of 2.
If not, gluBuild2DMipmaps scales a copy of data up or down to the nearest power of 2.
This copy is then used as the base for subsequent mipmapping operations. For example,
if width is 57 and height is 23, then a copy of data scales up to 64 and down to 16,
respectively, before mipmapping takes place. (If width or height is exactly between
powers of 2, the copy of data is scaled upward.)

38

Chapter 2

gluBuild2DMipmaps

If the GL version is 1.1 or greater, gluBuild2DMipmaps then uses proxy textures (see
glTexImage1D) to determine whether there’s enough room for the requested texture in
the implementation. If not, width is halved (and halved again) until it fits.

gluBuild2DMipmaps then uses proxy textures (see glTexImage2D) to determine if the
implementation can store the requested texture in texture memory. If not, both
dimensions are continually halved until it fits.

Next, gluBuild2DMipmaps builds a series of images; it halves a copy of type (or a scaled
version of type, if necessary) along both dimensions until size 11 is reached. At each
level, each texel in the halved mipmap is an average of the corresponding four texels in
the larger mipmap. (In the case of rectangular images, halving the images repeatedly
eventually results in an n 1 or 1n configuration. Here, two texels are averaged instead.)

glTexImage2D is called to load each of these images by level. If width and height are
both powers of 2 which fit in the implementation, level 0 is a copy of data, and the
highest level is log2(max(width, height)). For example, if width is 64 and height is 16, the

following mipmaps are built: 64×16, 32×8, 16×4, 8×2, 4×1, 2×1 and 1×1. These correspond
to levels 0 through 6, respectively.

See the glTexImage1D reference page for a description of the acceptable values for

format. See the glDrawPixels reference page for a description of the acceptable values for
type.

B

Notes

While you can’t query the maximum level directly, you can derive it indirectly by calling
glGetTexLevelParameter. First, query for the width and height actually used at level 0.
(The width and height may be unequal to width and height since proxy textures might
have shrunk or expanded them if width or height are not powers of 2 or if the
implementation only supports smaller textures.) The maximum level can then be

derived using the formula log2(max(width, height)).

Errors

• GLU_INVALID_VALUE is returned if width or height are negative.

• GLU_INVALID_ENUM is returned if format or type is not one of the accepted

values.

See Also

glDrawPixels,
glTexImage1D,
glTexImage2D,
gluBuild1DMipmaps,
gluErrorString,

gluScaleImage

Chapter 2

39

B

gluBuild2DMipmaps

40

Chapter 2

3C

Chapter 3

41

C

glCallList

glCallList

glCallList: execute a display list.

C Specification

void glCallList(

GLuint list)

Parameters

list Specifies the integer name of the display list to be executed.

Description

glCallList causes the named display list to be executed. The commands saved in the
display list are executed in order, just as if they were called without using a display list.
If list has not been defined as a display list, glCallList is ignored.

glCallList can appear inside a display list. To avoid the possibility of infinite recursion
resulting from display lists calling one another, a limit is placed on the nesting level of
display lists during display-list execution. This limit is at least 64, and it depends on the
implementation.

GL state is not saved and restored across a call to glCallList. Thus, changes made to GL
state during the execution of a display list remain after execution of the display list is
completed. Use glPushAttrib, glPopAttrib, glPushMatrix, and glPopMatrix to preserve

GL state across glCallList calls.

Notes

Display lists can be executed between a call to glBegin and the corresponding call to
glEnd, as long as the display list includes only commands that are allowed in this

interval.

Associated Gets

glGet with argument GL_MAX_LIST_NESTING glIsList

See Also

glCallLists,
glDeleteLists,
glGenLists,
glNewList,
glPushAttrib,

glPushMatrix

42

Chapter 3

glCallLists

glCallLists

glCallLists: execute a list of display lists.

C Specification

void glCallLists(

GLsizei n,
GLenum type,

const GLvoid *lists)

Parameters

n Specifies the number of display lists to be executed.
type Specifies the type of values in lists. Symbolic constants GL_BYTE,

GL_UNSIGNED_BYTE, GL_SHORT, GL_UNSIGNED_SHORT,

GL_INT, GL_UNSIGNED_INT, GL_FLOAT, GL_2_BYTES,

GL_3_BYTES, and GL_4_BYTES are accepted.

C

lists Specifies the address of an array of name offsets in the displaylist. The

pointer type is void because the offsets can be bytes, shorts, ints, or

floats, depending on the value of type.

Description

glCallLists causes each display list in the list of names passed as lists to be executed. As
a result, the commands saved in each display list are executed in order, just as if they
were called without using a display list. Names of display lists that have not been
defined are ignored.

glCallLists provides an efficient means for executing more than one display list. type
allows lists with various name formats to be accepted. The formats are as follows:

GL_BYTE lists is treated as an array of signed bytes, each in the range - 128

through 127.
GL_UNSIGNED_BYTE

lists is treated as an array of unsigned bytes, each in the range 0

through 255.
GL_SHORT lists is treated as an array of signed two-byte integers, each in the

range - 32768 through 32767.
GL_UNSIGNED_SHORT

lists is treated as an array of unsigned two-byte integers, each in the

range 0 through 65535.

Chapter 3

GL_INT lists is treated as an array of signed four-byte integers.
GL_UNSIGNED_INT

lists is treated as an array of unsigned four-byte integers.
GL_FLOAT lists is treated as an array of four-byte floating-point values.

43

C

glCallLists

GL_2_BYTES lists is treated as an array of unsigned bytes. Each pair of bytes

specifies a single display-list name. The value of the pair is computed

as 256 times the unsigned value of the first byte plus the unsigned

value of the second byte.
GL_3_BYTES lists is treated as an array of unsigned bytes. Each triplet of bytes

specifies a single display-list name. The value of the triplet is computed

as 65536 times the unsigned value of the first byte, plus 256 times the

unsigned value of the second byte, plus the unsigned value of the third

byte.
GL_4_BYTES lists is treated as an array of signed bytes, each in the range 128

through 127.
The list of display-list names is not null-terminated. Rather,n specifies how many names

are to be taken from lists.
An additional level of indirection is made available with the glListBase command, which

specifies an unsigned offset that is added to each display-list name specified in lists
before that display list is executed.

glCallLists can appear inside a display list. To avoid the possibility of infinite recursion
resulting from display list scaling one another, a limit is placed on the nesting level of
display lists during display-list execution. This limit must be at least 64, and it depends
on the implementation.

GL state is not saved and restored across a call to glCallLists. Thus, changes made to GL
state during the execution of the display lists remain after execution is completed. Use
glPushAttrib, glPopAttrib, glPushMatrix, and glPopMatrix to preserve GL state across

glCallLists calls.

Notes

Display lists can be executed between a call to glBegin and the corresponding call to
glEnd, as long as the display list includes only commands that are allowed in this

interval.

Errors

• GL_INVALID_VALUE is generated if n is negative.

• GL_INVALID_ENUM is generated if type is not one of GL_BYTE,

GL_UNSIGNED_BYTE, GL_SHORT, GL_UNSIGNED_SHORT, GL_INT,
GL_UNSIGNED_INT, GL_FLOAT, GL_2_BYTES, GL_3_BYTES, GL_4_BYTES.

Associated Gets

glGet with argument GL_LIST_BASE
glGet with argument GL_MAX_LIST_NESTING

glIsList

44

Chapter 3

See Also

glCallList,
glDeleteLists,
glGenLists,
glListBase,
glNewList,
glPushAttrib,

glPushMatrix

C

glCallLists

Chapter 3

45

C

glXChooseVisual

glXChooseVisual

glXChooseVisual: return a visual that matches specified attributes.

C Specification

XVisualInfo *glXChooseVisual(

Display *dpy,
int screen,

int *attribList)

Parameters

dpy Specifies the connection to the X server.
screen Specifies the screen number.
attribList Specifies a list of boolean attributes and integer attribute/value pairs.

The last attribute must be None.

Description

glXChooseVisual returns a pointer to an XVisualInfo structure describing the visual that
best meets a minimum specification. The boolean GLX attributes of the visual that is
returned will match the specified values, and the integer GLX attributes will meet or
exceed the specified minimum values. If all other attributes are equivalent, then
TrueColor and PseudoColor visuals have priority over DirectColor and StaticColor
visuals, respectively. If no conforming visual exists, NULL is returned. To free the data
returned by this function, use XFree.

All boolean GLX attributes default to False except GLX_USE_GL, which defaults to
True. All integer GLX attributes default to zero. Default specifications are superseded by
attributes included in attribList. Boolean attributes included in attribList are
understood to be True. Integer attributes and enumerated type attributes are followed
immediately by the corresponding desired or minimum value. The list must be
terminated with None.

The interpretations of the various GLX visual attributes are as follows:
GLX_USE_GL
Ignored. Only visuals that can be rendered with GLX are considered.
GLX_BUFFER_SIZE
Must be followed by a non-negative integer that indicates the desired color index buffer

size. The smallest index buffer of at least the specified size is preferred. Ignored if
GLX_RGBA is asserted.

46

GLX_LEVEL
Must be followed by an integer buffer-level specification. This specification is honored

exactly. Buffer level zero corresponds to the main frame buffer of the display. Buffer level
one is the first overlay frame buffer,level two the second overlay frame buffer, and so on.
Negative buffer levels correspond to underlay frame buffers.

Chapter 3

glXChooseVisual

GLX_RGBA
If present, only TrueColor and DirectColor visuals are considered. Otherwise, only

PseudoColor and StaticColor visuals are considered.
GLX_DOUBLEBUFFER
If present, only double-buffered visuals are considered. Otherwise, only single-buffered

visuals are considered.
GLX_STEREO
If present, only stereo visuals are considered. Otherwise, only monoscopic visuals are

considered.
GLX_AUX_BUFFERS
Must be followed by a nonnegative integer that indicates the desired number of auxiliary

buffers. Visuals with the smallest number of auxiliary buffers that meets or exceeds the
specified number are preferred.

GLX_RED_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero, the

smallest available red buffer is preferred. Otherwise, the largest available red buffer of
at least the minimum size is preferred.

C

GLX_GREEN_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero, the

smallest available green buffer is preferred. Otherwise, the largest available green
buffer of at least the minimum size is preferred.

GLX_BLUE_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero, the

smallest available blue buffer is preferred.Otherwise, the largest available blue buffer of
at least the minimum size is preferred.

GLX_ALPHA_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero, the

smallest available alpha buffer is preferred. Otherwise, the largest available alpha
buffer of at least the minimum size is preferred.

GLX_DEPTH_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero,

visuals with no depth buffer are preferred. Otherwise, the largest available depth buffer
of at least the minimum size is preferred.

GLX_STENCIL_SIZE
Must be followed by a nonnegative integer that indicates the desired number of stencil

bitplanes. The smallest stencil buffer of at least the specified size is preferred. If the
desired value is zero, visuals with no stencil buffer are preferred.

Chapter 3

GLX_ACCUM_RED_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero,

visuals with no red accumulation buffer are preferred. Otherwise, the largest possible
red accumulation buffer of at least the minimum size is preferred.

47

C

glXChooseVisual

GLX_ACCUM_GREEN_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero,

visuals with no green accumulation buffer are preferred. Otherwise, the largest possible
green accumulation buffer of at least the minimum size is preferred.

GLX_ACCUM_BLUE_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero,

visuals with no blue accumulation buffer are preferred. Otherwise, the largest possible
blue accumulation buffer of at least the minimum size is preferred.

GLX_ACCUM_ALPHA_SIZE
Must be followed by a nonnegative minimum size specification. If this value is zero,

visuals with no alpha accumulation buffer are preferred. Otherwise, the largest possible
alpha accumulation buffer of at least the minimum size is preferred.

Examples

attribList =
GLX_RGBA,
GLX_RED_SIZE, 4,
GLX_GREEN_SIZE, 4,
GLX_BLUE_SIZE, 4,
None};

Specifies a single-buffered RGB visual in the normal frame buffer, not an overlay or
underlay buffer. The returned visual supports at least four bits each of red, green, and
blue, and possibly no bits of alpha. It does not support color index mode,
double-buffering, or stereo display. It may or may not have one or more auxiliary color

buffers, a depth buffer, a stencil buffer, or an accumulation buffer.

Notes

XVisualInfo is defined in Xutil.h. It is a structure that includes visual, visualID, screen,
and depth elements.

glXChooseVisual is implemented as a client-side utility using only XGetVisualInfo and
glXGetConfig. Calls to these two routines can be used to implement selection algorithms
other than the generic one implemented by glXChooseVisual.

GLX implementers are strongly discouraged, but not proscribed, from changing the
selection algorithm used by glXChooseVisual. Therefore, selections may change from
release to release of the client-side library.

There is no direct filter for picking only visuals that support GLXPixmaps. GLXPixmaps
are supported for visuals whose GLX_BUFFER_SIZE is one of the pixmap depths

supported by the X server.

Errors

48

• NULL is returned if an undefined GLX attribute is encountered in attribList.

Chapter 3

See Also

glXCreateContext,
glXGetConfig

C

glXChooseVisual

Chapter 3

49

C

glClear

glClear

glClear: clear buffers to preset values.

C Specification

void glClear(

GLbitfield mask)

Parameters

mask Bitwise OR of masks that indicate the buffers to be cleared. The four

masks are GL_COLOR_BUFFER_BIT, GL_DEPTH_BUFFER_BIT,

GL_ACCUM_BUFFER_BIT, and GL_STENCIL_BUFFER_BIT.

Description

glClear sets the bitplane area of the window to values previously selected by
glClearColor, glClearIndex, glClearDepth, glClearStencil, and glClearAccum. Multiple
color buffers can be cleared simultaneously by selecting more than one buffer at a time
using glDrawBuffer.

The pixel ownership test, the scissor test, dithering, and the buffer writemasks affect the
operation of glClear. The scissor box bounds the cleared region. Alpha function, blend
function, logical operation, stenciling, texture mapping, and depth-buffering are ignored
by glClear.

glClear takes a single argument that is the bitwise or of several values indicating which
buffer is to be cleared. The values are as follows:

GL_COLOR_BUFFER_BIT
Indicates the buffers currently enabled for color writing.
GL_DEPTH_BUFFER_BIT
Indicates the depth buffer.
GL_ACCUM_BUFFER_BIT
Indicates the accumulation buffer.
GL_STENCIL_BUFFER_BIT
Indicates the stencil buffer.
The value to which each buffer is cleared depends on the setting of the clear value for

that buffer.

Notes

50

If a buffer is not present, then a glClear directed at that buffer has no effect.

Chapter 3

glClear

Errors

• GL_INVALID_VALUE is generated if any bit other than the four defined bits is set

in mask.

• GL_INVALID_OPERATION is generated if glClear is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated gets

glGet with argument GL_ACCUM_CLEAR_VALUE
glGet with argument GL_DEPTH_CLEAR_VALUE
glGet with argument GL_INDEX_CLEAR_VALUE
glGet with argument GL_COLOR_CLEAR_VALUE

glGet with argument GL_STENCIL_CLEAR_VALUE

See Also

glClearAccum,
glClearColor,
glClearDepth,
glClearIndex,
glClearStencil,
glDrawBuffer,

glScissor

C

Chapter 3

51

C

glClearAccum

glClearAccum

glClearAccum: specify clear values for the accumulation buffer.

C Specification

void glClearAccum(

GLfloat red,
GLfloat green,
GLfloat blue,

GLfloat alpha)

Parameters

red, green, blue, alpha

Specify the red, green, blue, and alpha values used when the

accumulation buffer is cleared. The initial values are all 0.

Description

glClearAccum specifies the red, green, blue, and alpha values used by glClear to clear
the accumulation buffer.

Values specified by glClearAccum are clamped to the range [-1, 1].

Errors

• GL_INVALID_OPERATION is generated if glClearAccum is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_ACCUM_CLEAR_VALUE

See Also

glClear

52

Chapter 3

glClearColor

glClearColor: specify clear values for the color buffers.

C Specification

void glClearColor(

GLclampf red,
GLclampf green,
GLclampf blue,

GLclampf alpha)

Parameters

red, green, blue, alpha

Specify the red, green, blue, and alpha values used when the color

buffers are cleared. The initial values are all 0.

C

glClearColor

Description

glClearColor specifies the red, green, blue, and alpha values used by glClear to clear the

color buffers. Values specified by glClearColor are clamped to the range [0, 1].

Errors

• GL_INVALID_OPERATION is generated if glClearColor is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_COLOR_CLEAR_VALUE

See Also

glClear

Chapter 3

53

C

glClearDepth

glClearDepth

glClearDepth: specify the clear value for the depth buffer.

C Specification

void glClearDepth(

GLclampd depth)

Parameters

depth Specifies the depth value used when the depth buffer is cleared. The

initial value is 1.

Description

glClearDepth specifies the depth value used by glClear to clear the depth buffer. Values
specified by glClearDepth are clamped to the range [0, 1].

Errors

• GL_INVALID_OPERATION is generated if glClearDepth is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_DEPTH_CLEAR_VALUE

See Also

glClear

54

Chapter 3

glClearindex

glClearindex

glClearIndex: specify the clear value for the color index buffers.

C Specification

void glClearIndex(

GLfloat c)

Parameters

c Specifies the index used when the color index buffers are cleared. The

initial value is 0.

Description

glClearIndex specifies the index used by glClear to clear the color index buffers. c is not
clamped. Rather, c is converted to a fixed-point value with unspecified precision to the

right of the binary point. The integer part of this value is then masked with 2m - 1,
where m is the number of bits in a color index stored in the frame buffer.

C

Errors

• GL_INVALID_OPERATION is generated if glClearIndex is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_INDEX_CLEAR_VALUE
glGet with argument GL_INDEX_BITS

See Also

glClear

Chapter 3

55

C

glClearStencil

glClearStencil

glClearStencil: specify the clear value for the stencil buffer.

C Specification

void glClearStencil(

GLint s)

Parameters

s Specifies the index used when the stencil buffer is cleared. The initial

value is 0.

Description

glClearStencil specifies the index used by glClear to clear the stencil buffer. s is masked
with 2m - 1, where m is the number of bits in the stencil buffer.

Errors

• GL_INVALID_OPERATION is generated if glClearStencil is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_STENCIL_CLEAR_VALUE
glGet with argument GL_STENCIL_BITS

See Also

glClear

56

Chapter 3

glClipPlane

glClipPlane

glClipPlane: specify a plane against which all geometry is clipped.

C Specification

void glClipPlane(

GLenum plane,
const GLdouble *equation)

Parameters

plane Specifies which clipping plane is being positioned. Symbolic names of

the form GL_CLIP_PLANEi, where i is an integer between 0 and

GL_MAX_CLIP_PLANES --1, are accepted.
equation Specifies the address of an array of four double-precision floating-point

values. These values are interpreted as a plane equation.

C

Description

Geometry is always clipped against the boundaries of a six-plane frustum in x, y, and z.
glClipPlane allows the specification of additional planes, not necessarily perpendicular
to the x, y, or Z axis, against which all geometry is clipped. To determine the maximum
number of additional clipping planes, call glGetIntegerv with argument
GL_MAX_CLIP_PLANES.All implementations support at least six such clipping planes.
Because the resulting clipping region is the intersection of the defined half-spaces, it is
always convex.

glClipPlane specifies a half-space using a four-component plane equation. When
glClipPlane is called, equation is transformed by the inverse of the modelview matrix
and stored in the resulting eye coordinates. Subsequent changes to the modelview
matrix have no effect on the stored plane-equation components. If the dot product of the
eye coordinates of a vertex with the stored plane equation components is positive or zero,
the vertex is \f2in\f1 with respect to that clipping plane. Otherwise, it is out.

To enable and disable clipping planes, call glEnable and glDisable with the argument
GL_CLIP_PLANEi, where i is the plane number.

All clipping planes are initially defined as (0, 0, 0, 0) in eye coordinates and are disabled.

Notes

It is always the case that GL_CLIP_PLANEi = GL_CLIP_PLANE0 + i.

Chapter 3

Errors

• GL_INVALID_ENUM is generated if plane is not an accepted value.

• GL_INVALID_OPERATION is generated if glClipPlane is executed between the

execution of glBegin and the corresponding execution of glEnd.

57

C

glClipPlane

Associated gets

glGetClipPlane
glIsEnabled with argument GL_CLIP_PLANE\f2i\fP

See Also

glEnable

58

Chapter 3

glColor

glColor

glColor3b, glColor3d, glColor3f, glColor3i, glColor3s, glColor3ub,
glColor3ui, glColor3us, glColor4b, glColor4d, glColor4f, glColor4i,
glColor4s, glColor4ub, glColor4ui, glColor4us, glColor3bv,
glColor3dv, glColor3fv, glColor3iv, glColor3sv, glColor3ubv,
glColor3uiv, glColor3usv, glColor4bv, glColor4dv, glColor4fv,
glColor4iv, glColor4sv, glColor4ubv, glColor4uiv, glColor4usv: set the

current color.

C Specification

void glColor3b(

GLbyte red,
GLbyte green,
GLbyte blue)

void glColor3d(

GLdouble red,
GLdouble green,
GLdouble blue)

void glColor3f(

GLfloat red,
GLfloat green,
GLfloat blue)

void glColor3i(

GLint red,
GLint green,
GLint blue)

void glColor3s(

GLshort red,
GLshort green,
GLshort blue)

void glColor3ub(

GLubyte red,
GLubyte green,
GLubyte blue)

void glColor3ui(

GLuint red,
GLuint green,
GLuint blue)

void glColor3us(

GLushort red,
GLushort green,
GLushort blue)

void glColor4b(

GLbyte red,
GLbyte green,
GLbyte blue,
GLbyte alpha)

void glColor4d(

GLdouble red,

C

Chapter 3

59

C

glColor

GLdouble green,
GLdouble blue,
GLdouble alpha)

void glColor4f(

GLfloat red,
GLfloat green,
GLfloat blue,
GLfloat alpha)

void glColor4i(

GLint red,
GLint green,
GLint blue,
GLint alpha)

void glColor4s(

GLshort red,
GLshort green,
GLshort blue,
GLshort alpha)

void glColor4ub(

GLubyte red,
GLubyte green,
GLubyte blue,
GLubyte alpha)

void glColor4ui(

GLuint red,
GLuint green,
GLuint blue,
GLuint alpha)

void glColor4us(

GLushort red,
GLushort green,
GLushort blue,

GLushort alpha)

void glColor3bv(

const GLbyte *v)

void glColor3dv(

const GLdouble *v)

void glColor3fv(

const GLfloat *v)

void glColor3iv(

const GLint *v)

void glColor3sv(

const GLshort *v)

void glColor3ubv(

const GLubyte *v)

void glColor3uiv(

const GLuint *v)

void glColor3usv(

const GLushort *v)

void glColor4bv(

const GLbyte *v)

void glColor4dv(

const GLdouble *v)

60

Chapter 3

glColor

void glColor4fv(

const GLfloat *v)

void glColor4iv(

const GLint *v)

void glColor4sv(

const GLshort *v)

void glColor4ubv(

const GLubyte *v)

void glColor4uiv(

const GLuint *v)

void glColor4usv(

const GLushort *v)

Parameters

red, green, blue Specify new red, green, and blue values for the current color.
alpha Specifies a new alpha value for the current color. Included only in the

four-argument glColor4 commands.
v Specifies a pointer to an array that contains red, green, blue, and

(sometimes) alpha values.

C

Description

The GL stores both a current single-valued color index and a current four-valued RGBA
color. glColor sets a new four-valued RGBA color. glColor has two major variants:
glColor3 and glColor4. glColor3 variants specify new red, green, and blue values
explicitly and set the current alpha value to 1.0 (full intensity) implicitly. glColor4
variants specify all four color components explicitly.

glColor3b, glColor4b, glColor3s, glColor4s, glColor3i, and glColor4i take three or four
signed byte, short, or long integers as arguments. When v is appended to the name, the
color commands can take a pointer to an array of such values.

Current color values are stored in floating-point format, with unspecified mantissa and
exponent sizes. Unsigned integer color components, when specified, are linearly mapped
to floating-point values such that the largest representable value maps to 1.0 (full
intensity), and 0 maps to 0.0 (zero intensity). Signed integer color components, when
specified, are linearly mapped to floating-point values such that the most positive
representable value maps to 1.0, and the most negative representable value maps to

-1.0. (Note that this mapping does not convert 0 precisely to 0.0.) Floating-point values
are mapped directly.

Neither floating-point nor signed integer values are clamped to the range [0, 1] before
the current color is updated. However,color components are clamped to this range before

they are interpolated or written into a color buffer.

Notes

Chapter 3

The initial value for the current color is (1, 1, 1, 1).
The current color can be updated at any time. In particular, glColor can be called

between a call to glBegin and the corresponding call to glEnd.

61

C

glColor

Associated Gets

glGet with argument GL_CURRENT_COLOR
glGet with argument GL_RGBA_MODE

See Also

glIndex

62

Chapter 3

glColorMask

glColorMask: enable and disable writing of frame buffer color components.

C Specification

void glColorMask(

GLboolean red,
GLboolean green,
GLboolean blue,

GLboolean alpha)

Parameters

red, green, blue, alpha

Specify whether red, green, blue, and alpha can or cannot be written

into the frame buffer. The initial values are all GL_TRUE, indicating

that the color components can be written.

C

glColorMask

Description

glColorMask specifies whether the individual color components in the frame buffer can
or cannot be written. If red is GL_FALSE, for example, no change is made to the red
component of any pixel in any of the color buffers, regardless of the drawing operation
attempted.

Changes to individual bits of components cannot be controlled. Rather, changes are
either enabled or disabled for entire color components.

Errors

• GL_INVALID_OPERATION is generated if glColorMask is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_COLOR_WRITEMASK
glGet with argument GL_RGBA_MODE

See Also

glColor,
glColorPointer,
glDepthMask,
glIndex,
glIndexPointer,
glIndexMask,

glStencilMask

Chapter 3

63

C

glColorMaterial

glColorMaterial

glColorMaterial: cause a material color to track the current color.

C Specification

void glColorMaterial(

GLenum face,
GLenum mode)

Parameters

face Specifies whether front, back, or both front and back material

parameters should track the current color. Accepted values are

GL_FRONT, GL_BACK, and GL_FRONT_AND_BACK. The initial

value is GL_FRONT_AND_BACK.
mode Specifies which of several material parameters track the current color.

Accepted values are GL_EMISSION, GL_AMBIENT, GL_DIFFUSE,

GL_SPECULAR, and GL_AMBIENT_AND_DIFFUSE. The initial

value is GL_AMBIENT_AND_DIFFUSE.

Description

glColorMaterial specifies which material parameters track the current color. When
GL_COLOR_MATERIAL is enabled, the material parameter or parameters specified by
mode, of the material or materials specified by face, track the current color at all times.

To enable and disable GL_COLOR_MATERIAL, call glEnable and glDisable with
argument GL_COLOR_MATERIAL. GL_COLOR_MATERIAL is initially disabled.

Notes

glColorMaterial makes it possible to change a subset of material parameters for each
vertex using only the glColor command, without calling glMaterial. If only such a subset
of parameters is to be specified for each vertex, calling glColorMaterial is preferable to
calling glMaterial.

Call glColorMaterial before enabling GL_COLOR_MATERIAL.
Calling glDrawElements may leave the current color indeterminate. If glColorMaterial

is enabled while the current color is indeterminate, the lighting material state specified
by face and mode is also indeterminate.

If the GL version is 1.1 or greater, and GL_COLOR_MATERIAL is enabled, evaluated
color values affect the results of the lighting equation as if the current color were being

modified, but no change is made to the tracking lighting parameter of the current color.

64

Errors

• GL_INVALID_ENUM is generated if face or mode is not an accepted value.

Chapter 3

glColorMaterial

• GL_INVALID_OPERATION is generated if glColorMaterial is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glIsEnabled with argument GL_COLOR_MATERIAL
glGet with argument GL_COLOR_MATERIAL_PARAMETER

glGet with argument GL_COLOR_MATERIAL_FACE

See Also

glColor,
glColorPointer,
glDrawElements,
glEnable,
glLight,
glLightModel,

glMaterial

C

Chapter 3

65

C

glColorPointer

glColorPointer

glColorPointer: define an array of colors.

C Specification

void glColorPointer(

GLint size,
GLenum type,
GLsizei stride,

const GLvoid *pointer)

Parameters

size Specifies the number of components per color. Must be 3 or 4.
type Specifies the data type of each color component in the array. Symbolic

constants GL_BYTE, GL_UNSIGNED_BYTE, GL_SHORT,

GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT,

and GL_DOUBLE are accepted.
stride Specifies the byte offset between consecutive colors. If stride is 0, (the

initial value), the colors are understood to be tightly packed in the

array.
pointer Specifies a pointer to the first component of the first color element in

the array.

Description

glColorPointer specifies the location and data format of an array of color components to
use when rendering. size specifies the number of components per color, and must be 3 or

4. type specifies the data type of each color component, and stride specifies the byte stride
from one color to the next allowing vertexes and attributes to be packed into a single
array or stored in separate arrays. (Single-array storage may be more efficient on some
implementations; see glInterleavedArrays.)

When a color array is specified, size, type, stride, and pointer are saved as client-side
state.

Toenable and disable the color array, call glEnableClientState and glDisableClientState
with the argument GL_COLOR_ARRAY. If enabled, the color array is used when

glDrawArrays, glDrawElements, or glArrayElement is called.

Notes

glColorPointer is available only if the GL version is 1.1 or greater.

66

The color array is initially disabled and isn’t accessed when glArrayElement,
glDrawArrays, or glDrawElements is called.

Chapter 3

glColorPointer

Execution of glColorPointer is not allowed between the execution of glBegin and the
corresponding execution of glEnd, but an error may or may not be generated. If no error
is generated, the operation is undefined.

glColorPointer is typically implemented on the client side.
Color array parameters are client-side state and are therefore not saved or restored by

glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.

Errors

• GL_INVALID_VALUE is generated if size is not 3 or 4.

• GL_INVALID_ENUM is generated if type is not an accepted value.

• GL_INVALID_VALUE is generated if stride is negative.

Associated Gets

glIsEnabled with argument GL_COLOR_ARRAY
glGet with argument GL_COLOR_ARRAY_SIZE
glGet with argument GL_COLOR_ARRAY_TYPE
glGet with argument GL_COLOR_ARRAY_STRIDE

glGetPointerv with argument GL_COLOR_ARRAY_POINTER

C

See Also

glArrayElement,
glDrawArrays,
glDrawElements,
glEdgeFlagPointer,
glEnable,
glGetPointer,
glIndexPointer,
glInterleavedArrays,
glNormalPointer,
glPopClientAttrib,
glPushClientAttrib,
glTexCoordPointer,

glVertexPointer

Chapter 3

67

C

glXCopyContext

glXCopyContext

glXCopyContext: copy state from one rendering context to another.

C Specification

void glXCopyContext(

Display *dpy,
GLXContext src,
GLXContext dst,

unsigned long mask)

Parameters

dpy Specifies the connection to the X server.
src Specifies the source context.
dst Specifies the destination context.
mask Specifies which portions of src state are to be copied to dst.

Description

glXCopyContext copies selected groups of state variables from src to dst. mask indicates
which groups of state variables are to be copied. mask contains the bitwise OR of the
same symbolic names that are passed to the GL command glPushAttrib. The single
symbolic constant GL_ALL_ATTRIB_BITS can be used to copy the maximum possible
portion of rendering state.

The copy can be done only if the renderers named by src and dst share an address space.
Two rendering contexts share an address space if both are non-direct using the same
server, or if both are direct and owned by a single process. Note that in the non-direct
case it is not necessary for the calling threads to share an address space, only for their
related rendering contexts to share an address space.

Not all values for GL state can be copied. For example, pixel pack and unpack state,
render mode state, and select and feedback state are not copied. The state that can be
copied is exactly the state that is manipulated by the GL command glPushAttrib.

An implicit glFlush is done by glXCopyContext if src is the current context for the calling
thread.

Notes

A process is a single execution environment, implemented in a single address space,
consisting of one or more threads.

68

A thread is one of a set of subprocesses that share a single address space, but maintain
separate program counters, stack spaces, and other related global data. A thread that is

the only member of its subprocess group is equivalent to a process.

Chapter 3

glXCopyContext

Errors

• BadMatch is generated if rendering contexts src and dst do not share an address

space or were not created with respect to the same screen.

• BadAccess is generated if dst is current to any thread (including the calling thread)

at the time glXCopyContext is called.

• GLXBadCurrentWindow is generated if src is the current context and the current

drawable is a window that is no longer valid.

• GLXBadContext is generated if either src or dst is not a valid GLX context.

See Also

glPushAttrib,
glXCreateContext,

glXIsDirect

C

Chapter 3

69

C

glCopyPixels

glCopyPixels

glCopyPixels: copy pixels in the frame buffer.

C Specification

void glCopyPixels(

GLint x,
GLint y,
GLsizei width,
GLsizei height,

GLenum type)

Parameters

x, y Specify the window coordinates of the lower left corner of the

rectangular region of pixels to be copied.
width, height Specify the dimensions of the rectangular region of pixels to be copied.

Both must be nonnegative.
type Specifies whether color values, depth values, or stencil values are to be

copied. Symbolic constants GL_COLOR, GL_DEPTH, and

GL_STENCIL are accepted.

Description

glCopyPixels copies a screen-aligned rectangle of pixels from the specified frame buffer
location to a region relative to the current raster position. Its operation is well defined
only if the entire pixel source region is within the exposed portion of the window.Results
of copies from outside the window, or from regions of the window that are not exposed,
are hardware dependent and undefined.

x and y specify the window coordinates of the lower left corner of the rectangular region
to be copied. width and height specify the dimensions of the rectangular region to be
copied. Both width and height must not be negative.

Several parameters control the processing of the pixel data while it is being copied.
These parameters are set with three commands: glPixelTransfer, glPixelMap, and
glPixelZoom. This reference page describes the effects on glCopyPixels of most, but not
all, of the parameters specified by these three commands.

glCopyPixels copies values from each pixel with the lower left-hand corner at (x + i,y+j)
for 0 ≥ i<width and 0 ≥ j<height. This pixel is said to be the ith pixel in the jth row. Pixels
are copied in row order from the lowest to the highest row, left to right in each row.

type specifies whether color, depth, or stencil data is to be copied. The details of the
transfer for each data type are as follows:

70

GL_COLOR
Indices or RGBA colors are read from the buffer currently specified as the read source

buffer (see glReadBuffer). If the GL is in color index mode, each index that is read from
this buffer is converted to a fixed-point format with an unspecified number of bits to the

Chapter 3

glCopyPixels

right of the binary point. Each index is then shifted left by GL_INDEX_SHIFT bits, and
added toGL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right.
In either case, zero bits fill otherwise unspecified bit locations in the result. If
GL_MAP_COLOR is true, the index is replaced with the value that it references in
lookup table GL_PIXEL_MAP_I_TO_I. Whether the lookup replacement of the index is

done or not, the integer part of the index is then ANDed with 2b - 1, where b is the
number of bits in a color index buffer.

If the GL is in RGBA mode, the red, green, blue, and alpha components of each pixel that
is read are converted to an internal floating-point format with unspecified precision. The
conversion maps the largest representable component value to 1.0, and component value
0 to 0.0. The resulting floating-point color values are then multiplied by GL_c_SCALE
and added to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the
respective color components. The results are clamped to the range [0, 1]. If
GL_MAP_COLOR is true, each color component is scaled by the size of lookup table
GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is
R, G, B, or A.

The GL then converts the resulting indices or RGBA colors to fragments by attaching the
current raster position z coordinate and texture coordinates to each pixel, then assigning
window coordinates (xr + i, yr + j), where (xr, yr) is the current raster position, and the

pixel was the ith pixel in the jth row. These pixel fragments are then treated just like the
fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and
all the fragment operations are applied before the fragments are written to the frame
buffer.

C

GL_DEPTH
Depth values are read from the depth buffer and converted directly to an internal

floating-point format with unspecified precision. The resulting floating-point depth value
is then multiplied by GL_DEPTH_SCALE and added to GL_DEPTH_BIAS. The result is
clamped to the range [0, 1].

The GL then converts the resulting depth components to fragments by attaching the
current raster position color or color index and texture coordinates to each pixel, then
assigning window coordinates (xr + i, yr + j), where (xr, yr) is the current raster position,

and the pixel was the ith pixel in the jth row.These pixel fragments are then treated just
like the fragments generated by rasterizing points, lines, or polygons. Texture mapping,
fog, and all the fragment operations are applied before the fragments are written to the
frame buffer.

GL_STENCIL
Stencil indices are read from the stencil buffer and converted to an internal fixed-point

format with an unspecified number of bits to the right of the binary point. Each
fixed-point index is then shifted left by GL_INDEX_SHIFT bits, and added to
GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right. In
either case, zero bits fill otherwise unspecified bit locations in the result. If
GL_MAP_STENCIL is true, the index is replaced with the value that it references in
lookup table GL_PIXEL_MAP_S_TO_S. Whether the lookup replacement of the index is

done or not, the integer part of the index is then ANDed with 2b - 1, where b is the
number of bits in the stencil buffer. The resulting stencil indices are then written to the
stencil buffer such that the index read from the ith location of the jth row is written to
location (xr + i, yr + j), where (xr, yr) is the current raster position. Only the pixel

ownership test, the scissor test, and the stencil writemask affect these write operations.

Chapter 3

71

C

glCopyPixels

The rasterization described thus far assumes pixel zoom factors of 1.0. If glPixelZoom is
used to change the x and y pixel zoom factors, pixels are converted to fragments as
follows. If (xr, yr) is the current raster position, and a given pixel is in the ith location in

the jth row of the source pixel rectangle, then fragments are generated for pixels whose
centers are in the rectangle with corners at

(xr + zoomxi, yr + zoomy j)
and

(xr + zoomx(i+1), yr+ zoomy (j+1))
where zoomx is the value of GL_ZOOM_X and zoomyis the value of GL_ZOOM_Y.

Examples

To copy the color pixel in the lower left corner of the window to the current raster
position, use

glCopyPixels(0, 0, 1, 1, GL_COLOR);

Notes

Modes specified by glPixelStore have no effect on the operation of glCopyPixels.

Errors

• GL_INVALID_ENUM is generated if type is not an accepted value.

• GL_INVALID_VALUE is generated if either width or height is negative.

• GL_INVALID_OPERATION is generated if type is GL_DEPTH and there is no depth

buffer.

• GL_INVALID_OPERATION is generated if type is GL_STENCIL and there is no

stencil buffer.

• GL_INVALID_OPERATION is generated if glCopyPixels is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGet with argument GL_CURRENT_RASTER_POSITION
glGet with argument GL_CURRENT_RASTER_POSITION_VALID

See Also

glDepthFunc,
glDrawBuffer,
glDrawPixels,
glPixelMap,
glPixelTransfer,
glPixelZoom,
glRasterPos,

72

Chapter 3

glReadBuffer,
glReadPixels,

glStencilFunc

C

glCopyPixels

Chapter 3

73

C

glCopyTexImage1D

glCopyTexImage1D

glCopyTexImage1D: copy pixels into a 1D texture image.

C Specification

void glCopyTexImage1D(

GLenum target,
GLint level,
GLenum internalFormat,
GLint x,
GLint y,
GLsizei width,

GLint border)

Parameters

target Specifies the target texture. Must be GL_TEXTURE_1D.
level Specifies the level-of-detail number. Level 0 is the base image level.

Level n is the nth mipmap reduction image.

internalFormat Specifies the internal format of the texture. Must be one of the

following symbolic constants: GL_ALPHA, GL_ALPHA4,
GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_LUMINANCE,
GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12,
GL_LUMINANCE16,GL_LUMINANCE_ALPHA,
GL_LUMINANCE4_ALPHA4, GL_LUMINANCE6_ALPHA2,
GL_LUMINANCE8_ALPHA8,
GL_LUMINANCE12_ALPHA4,GL_LUMINANCE12_ALPHA12,
GL_LUMINANCE16_ALPHA16, GL_INTENSITY, GL_INTENSITY4,
GL_INTENSITY8, GL_INTENSITY12, GL_INTENSITY16, GL_RGB,
GL_R3_G3_B2, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10,
GL_RGB12, GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4,
GL_RGB5_A1,GL_RGBA8, GL_RGB10_A2, GL_RGBA12, or
GL_RGBA16. Additionally, internalFormat maybe one of the symbolic
constants GL_DEPTH_COMPONENT,
GL_DEPTH_COMPONENT16_EXT,
GL_DEPTH_COMPONENT24_EXT, or
GL_DEPTH_COMPONENT32_EXT.

x, y Specify the window coordinates of the left corner of the row of pixels to

be copied.

width Specifies the width of the texture image. Must be 0 or 2n + 2 × border

for some integer n. The height of the texture image is 1.

74

border Specifies the width of the border. Must be either 0 or 1.

Description

glCopyTexImage1D defines a one-dimensional texture image with pixels from the
current GL_READ_BUFFER.

Chapter 3

glCopyTexImage1D

The screen-aligned pixel row with left corner at (x, y) and with a length of width+2 ×
border defines the texture array at the mipmap level specified by level. internalFormat
specifies the internal format of the texture array.

The pixels in the row are processed exactly as if glCopyPixels had been called, but the
process stops just before final conversion. At this point all pixel component values are
clamped to the range [0, 1] and then converted to the texture’s internal format for
storage in the texel array.

Pixel ordering is such that lower x screen coordinates correspond to lower texture
coordinates.

If any of the pixels within the specified row of the current GL_READ_BUFFER are
outside the window associated with the current rendering context, then the values

obtained for those pixels are undefined.

Notes

glCopyTexImage1D is available only if the GL version is 1.1 or greater.
Texturing has no effect in color index mode.
1, 2, 3, and 4 are not accepted values for internalFormat.

C

The GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16_EXT,
GL_DEPTH_COMPONENT24_EXT, and GL_DEPTH_COMPONENT32_EXT values of
internalFormat may be used.

An image with 0 width indicates a NULL texture.

Errors

• GL_INVALID_ENUM is generated if target is not one of the allowable values.

• GL_INVALID_VALUE is generated if level is less than 0.

• GL_INVALID_VALUE may be generated if level is greater than log2max, where max

is the returned value of GL_MAX_TEXTURE_SIZE.

• GL_INVALID_VALUE is generated if internalFormat is not an allowable value.

• GL_INVALID_VALUE is generated if width is less than 0 or greater than 2 +

GL_MAX_TEXTURE_SIZE, or if it cannot be represented as 2n+2 ×border for some
integer value of n.

• GL_INVALID_VALUE is generated if border is not 0 or 1.

• GL_INVALID_OPERATION is generated if glCopyTexImage1Dis executed between

the execution of glBegin and the corresponding execution of glEnd.

Associated Gets

Chapter 3

glGetTexImage
glIsEnabled with argument GL_TEXTURE_1D

75

C

glCopyTexImage1D

See Also

glCopyPixels,
glCopyTexImage2D,
glCopyTexSubImage1D,
glCopyTexSubImage2D,
glPixelStore
glPixelTransfer,
glTexEnv,
glTexGen,
glTexImage1D,
glTexImage2D,
glTexSubImage1D,
glTexSubImage2D,
glTexParameter

76

Chapter 3

glCopyTexImage2D

glCopyTexImage2D: copy pixels into a 2D texture image.
C Specification

C Specification

void glCopyTexImage2D(

GLenum target,
GLint level,
GLenum internalFormat,
GLint x,
GLint y,
GLsizei width,
GLsizei height,

GLint border)

Parameters

C

glCopyTexImage2D

target Specifies the target texture. Must be GL_TEXTURE_2D.
level Specifies the level-of-detail number. Level 0 is the base image level.

Level n is the nth mipmap reduction image.

internalFormat Specifies the internal format of the texture. Must be one of the

following symbolic constants: GL_ALPHA, GL_ALPHA4,
GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_LUMINANCE,
GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12,
GL_LUMINANCE16, GL_LUMINANCE_ALPHA,
GL_LUMINANCE4_ALPHA4, GL_LUMINANCE6_ALPHA2,
GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4,
GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16,
GL_INTENSITY, GL_INTENSITY4, GL_INTENSITY8,
GL_INTENSITY12, GL_INTENSITY16, GL_RGB, GL_R3_G3_B2,
GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12,
GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1,
GL_RGBA8, GL_RGB10_A2, GL_RGBA12, or GL_RGBA16.
Additionally, internalFormat may be one of the symbolic constants
GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16_EXT,
GL_DEPTH_COMPONENT24_EXT, or
GL_DEPTH_COMPONENT32_EXT.

x, y Specify the window coordinates of the lower left corner of the

rectangular region of pixels to be copied.

width Specifies the width of the texture image. Must be 0 or 2n + 2 × border

for some integer n.

Chapter 3

height Specifies the height of the texture image. Must be 0 or 2m + 2 × border

for some integer m.

border Specifies the width of the border. Must be either 0 or 1.

77

C

glCopyTexImage2D

Description

glCopyTexImage2D defines a two-dimensional texture image with pixels from the
current GL_READ_BUFFER.

The screen-aligned pixel rectangle with lower left corner at (x, y) and with a width of
width + 2 × border and a height of height + 2 × border defines the texture array at the
mipmap level specified by level. internalFormat specifies the internal format of the
texture array.

The pixels in the rectangle are processed exactly as if glCopyPixels had been called, but
the process stops just before final conversion. At this point all pixel component values
are clamped to the range [0, 1] and then converted to the texture’s internal format for
storage in the texel array.

Pixel ordering is such that lower x and y screen coordinates correspond to lower s and t
texture coordinates.

If any of the pixels within the specified rectangle of the current GL_READ_BUFFER are
outside the window associated with the current rendering context, then the values

obtained for those pixels are undefined.

Notes

glCopyTexImage2D is available only if the GL version is 1.1 or greater.
Texturing has no effect in color index mode.
1, 2, 3, and 4 are not accepted values for internalFormat.
The GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16_EXT,

GL_DEPTH_COMPONENT24_EXT, and GL_DEPTH_COMPONENT32_EXT values of
internalFormat may be used.

An image with height or width of 0 indicates a NULL texture.

Errors

• GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D.

• GL_INVALID_VALUE is generated if level is less than 0.

• GL_INVALID_VALUE may be generated if level is greater than log2max, where max

is the returned value of GL_MAX_TEXTURE_SIZE.

• GL_INVALID_VALUE is generated if width or height is less than 0, greater than 2 +

GL_MAX_TEXTURE_SIZE, or if width or height cannot be represented as 2k + 2 ×
border for some integer k.

• GL_INVALID_VALUE is generated if border is not 0 or 1.

78

• GL_INVALID_VALUE is generated if internalFormat is not one of the allowable

values.

• GL_INVALID_OPERATION is generated if glCopyTexImage2Dis executed between

the execution of glBegin and the corresponding execution of glEnd.

Chapter 3

Associated Gets

glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D

See Also

glCopyPixels,
glCopyTexImage1D,
glCopyTexSubImage1D,
glCopyTexSubImage2D,
glPixelStore,
glPixelTransfer,
glTexEnv,
glTexGen,
glTexImage1D,
glTexImage2D,
glTexSubImage1D,
glTexSubImage2D,

glTexParameter

C

glCopyTexImage2D

Chapter 3

79

C

glCopyTexSubImage1D

glCopyTexSubImage1D

glCopyTexSubImage1D: copy a one-dimensional texture sub image.

C Specification

void glCopyTexSubImage1D(

GLenum target,
GLint level,
GLint xoffset,
GLint x,
GLint y,

GLsizei width)

Parameters

target Specifies the target texture. Must be GL_TEXTURE_1D.
level Specifies the level-of-detail number. Level 0 is the base image level.

Level n is the nth mipmap reduction image.
xoffset Specifies the texel offset within the texture array.
x, y Specify the window coordinates of the left corner of the row of pixels to

be copied.
width Specifies the width of the texture sub image.

Description

glCopyTexSubImage1D replaces a portion of a one-dimensional texture image with
pixels from the current GL_READ_BUFFER (rather than from main memory, as is the
case for glTexSubImage1D).

The screen-aligned pixel row with left corner at (x, y), and with length width replaces the
portion of the texture array with X indices xoffset through xoffset + width - 1, inclusive.
The destination in the texture array may not include any texels outside the texture
array as it was originally specified. The pixels in the row are processed exactly as if
glCopyPixels had been called, but the process stops just before final conversion. At this
point all pixel component values are clamped to the range [0, 1] and then converted to
the texture’s internal format for storage in the texel array.

It is not an error to specify a subtexture with zero width, but such a specification has no
effect. If any of the pixels within the specified row of the current GL_READ_BUFFER
are outside the read window associated with the current rendering context, then the
values obtained for those pixels are undefined.

No change is made to the internalformat, width, or border parameters of the specified
texture array or to texel values outside the specified subregion.

80

Notes

glCopyTexSubImage1D is available only if the GL version is 1.1 or greater.

Chapter 3

glCopyTexSubImage1D

Texturing has no effect in color index mode.
glPixelStore and glPixelTransfer modes affect texture images in exactly the way they

affect glDrawPixels.

Errors

• GL_INVALID_ENUM is generated if target is not GL_TEXTURE_1D.

• GL_INVALID_OPERATION is generated if the texture array has not been defined

by a previous glTexImage1D or glCopyTexImage1D operation.

• GL_INVALID_VALUE is generated if level is less than 0.

• GL_INVALID_VALUE may be generated if level>log2 max, where max is the

returned value of GL_MAX_TEXTURE_SIZE.

• GL_INVALID_VALUE is generated if y < - b or if width < - b, where b is the border

width of the texture array. GL_INVALID_VALUE is generated if xoffset < - b, or
(xoffset + width) > (w - b), where w is the GL_TEXTURE_WIDTH, and b is the
GL_TEXTURE_BORDER of the texture image being modified. Note that w includes
twice the border width.

C

Associated Gets

glGetTexImage
glIsEnabled with argument GL_TEXTURE_1D

See Also

glCopyPixels,
glCopyTexImage1D,
glCopyTexImage2D,
glCopyTexSubImage2D,
glPixelStore,
glPixelTransfer,
glTexEnv,
glTexGen,
glTexImage1D,
glTexImage2D,
glTexParameter,
glTexSubImage1D,

glTexSubImage2D

Chapter 3

81

C

glCopyTexSubImage2D

glCopyTexSubImage2D

glCopyTexSubImage2D: copy a two-dimensional texture sub image.

C Specification

void glCopyTexSubImage2D(

GLenum target,
GLint level,
GLint xoffset,
GLint yoffset,
GLint x,
GLint y,
GLsizei width,

GLsizei height)

Parameters

target Specifies the target texture. Must be GL_TEXTURE_2D
level Specifies the level-of-detail number. Level 0 is the base image level.

Level n is the nth mipmap reduction image.
xoffset Specifies a texel offset in the X direction within the texture array.
yoffset Specifies a texel offset in the Y direction within the texture array.
x, y Specify the window coordinates of the lower left corner of the

rectangular region of pixels to be copied.

width Specifies the width of the texture sub image.
height Specifies the height of the texture sub image.

Description

glCopyTexSubImage2D replaces a rectangular portion of a two-dimensional texture
image with pixels from the current GL_READ_BUFFER (rather than from main
memory, as is the case for glTexSubImage2D).

The screen-aligned pixel rectangle with lower left corner at (x, y) and with width width
and height height, replaces the portion of the texture array with X indices xoffset
through xoffset + width - 1, inclusive, and Y indices yoffset through yoffset + height - 1,
inclusive, at the mipmap level specified by level.

The pixels in the rectangle are processed exactly as if glCopyPixels had been called, but
the process stops just before final conversion. At this point, all pixel component values
are clamped to the range [0, 1] and then converted to the texture’s internal format for
storage in the texel array.

82

The destination rectangle in the texture array may not include any texels outside the
texture array as it was originally specified. It is not an error to specify a subtexture with
zero width or height, but such a specification has no effect.

Chapter 3

glCopyTexSubImage2D

If any of the pixels within the specified rectangle of the current GL_READ_BUFFER are
outside the read window associated with the current rendering context, then the values
obtained for those pixels are undefined.

No change is made to the internalformat, width, height, or border parameters of the
specified texture array or to texel values outside the specified subregion.

Notes

glCopyTexSubImage2D is available only if the GL version is 1.1 or greater.
Texturing has no effect in color index mode.
glPixelStore and glPixelTransfer modes affect texture images in exactly the way they

affect glDrawPixels.

Errors

• GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D.

• GL_INVALID_OPERATION is generated if the texture array has not been defined

by a previous glTexImage2D or glCopyTexImage2D operation.

C

• GL_INVALID_VALUE is generated if level is less than 0.

• GL_INVALID_VALUE may be generated if level is greater than log2max, where max

is the returned value of GL_MAX_TEXTURE_SIZE.

• GL_INVALID_VALUE is generated if x<-bor if y<-b, where b is the border width

of the texture array.

• GL_INVALID_VALUE is generated if xoffset < - b,(xoffset + width)>(w- b), yoffset <

- b, or (yoffset + height) > (h - b), where w is the GL_TEXTURE_WIDTH, h is the
GL_TEXTURE_HEIGHT, and b is the GL_TEXTURE_BORDER of the texture
image being modified. Note that w and h include twice the border width.

• GL_INVALID_OPERATION is generated if glCopyTexSubImage2D is executed

between the execution of glBegin and the corresponding execution of glEnd.

Associated gets

glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D

See Also

glCopyPixels,
glCopyTexImage1D,
glCopyTexImage2D,
glCopyTexSubImage1D,
glPixelStore,
glPixelTransfer,
glTexEnv,
glTexGen,
glTexImage1D,
glTexImage2D,

Chapter 3

83

C

glCopyTexSubImage2D

glTexParameter,
glTexSubImage1D,

glTexSubImage2D

84

Chapter 3

glCopyTexSubImage3DEXT

glCopyTexSubImage3DEXT

glCopyTexSubImage3DEXT: copy pixels into a 3D texture sub image.

C Specification

void glCopyTexSubImage3DEXT(

GLenum target,
GLint level,
GLint xoffset,
GLint yoffset,
GLint zoffset,
GLint x,
GLint y,
GLsizei width,

GLsizei height)

Parameters

C

target The target texture. Must be GL_TEXTURE_3D_EXT.
level The level-of-detail number. Level 0 is the base image level, and level n

is the nth mipmap reduction image.
xoffset Texel offset in the X direction within the texture array.
yoffset Texel offset in the Y direction within the texture array.
zoffset Texel offset in the Z direction within the texture array.
x The X coordinate of the lower-left corner of the pixel rectangle to be

transferred to the texture array.
y The Y coordinate of the lower-left corner of the pixel rectangle to be

transferred to the texture array.

width The width of the texture sub image.
height The height of the texture sub image.

Description

glCopyTexSubImage3DEXT replaces a rectangular portion of a three-dimensional
texture image with pixels from the current GL_READ_BUFFER (rather than from main
memory, as is the case for glTexSubImage3DEXT).

The screen-aligned pixel rectangle with lower-left corner at (x, y) having width width
and height height replaces the rectangular area of the S-T slice located at zoffset with X
indices xoffset through xoffset + width - 1, inclusive, and Y indices yoffset through yoffset
+ height - 1, inclusive.

Chapter 3

The destination rectangle in the texture array may not include any texels outside the
texture array as it was originally specified. It is not an error to specify a subtexture with
zero width or height, but such a specification has no effect.

85

C

glCopyTexSubImage3DEXT

The pixels in the rectangle are processed exactly as if glCopyPixels had been called, but
the process stops just before final conversion. At this point all pixel component values
are clamped to the range [0, 1] and then converted to the texture’s internal format for
storage in the texel array.

If any of the pixels within the specified rectangle of the current GL_READ_BUFFER are
outside the read window associated with the current rendering context, then the values

obtained for those pixels are undefined.

Notes

glCopyTexSubImage3DEXT is part of the EXT_copy_texture extension.

Errors

• GL_INVALID_ENUM is generated when target is not one of the allowable values.

• GL_INVALID_VALUE is generated if level is less than zero or greater than log2max,

• GL_INVALID_VALUE is generated if xoffset <- TEXTURE_BORDER, (xoffset +

where max is the returned value of GL_MAX_TEXTURE_SIZE.

width) > (TEXTURE_WIDTH - TEXTURE_BORDER), yoffset < ­TEXTURE_BORDER, or if zoffset < - TEXTURE_BORDER, where
TEXTURE_WIDTH, TEXTURE_HEIGHT, and TEXTURE_BORDER are the state
values of the texture image being modified, and interlace is 1 if
GL_INTERLACE_SGIX is disabled, and 2 otherwise. Note that TEXTURE_WIDTH
and TEXTURE_HEIGHT include twice the border width.

• GL_INVALID_VALUE is generated if width or height is negative.

• GL_INVALID_OPERATION is generated when the texture array has not been

defined by a previous glTexImage3D (or equivalent) operation.

• GL_INVALID_OPERATION is generated if glCopyTexSubImage3DEXT is executed

between the execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGetTexImage

See Also

glTexImage3D,
glTexSubImage3DEXT,
glCopyPixels.

86

Chapter 3

glXCreateContext

glXCreateContext

glXCreateContext: create a new GLX rendering context.

C Specification

GLXContext glXCreateContext(

Display *dpy,
XVisualInfo *vis,
GLXContext shareList,

Bool direct)

Parameters

dpy Specifies the connection to the X server.
vis Specifies the visual that defines the frame buffer resources available to

the rendering context. It is a pointer to an XVisualInfo structure, not a

visualID or a pointer to a Visual.

C

sharelist Specifies the context with which to share display lists. NULL indicates

that no sharing is to take place.
direct Specifies whether rendering is to be done with a direct connection to

the graphics system if possible (True) or through the X server (False).

Description

glXCreateContext creates a GLX rendering context and returns its handle. This context
can be used to render into both windows and GLX pixmaps. If glXCreateContext fails to
create a rendering context, NULL is returned.

If direct is True, then a direct rendering context is created if the implementation
supports direct rendering, if the connection is to an X server that is local, and if a direct
rendering context is available. (An implementation may return an indirect context when
direct is True). If direct is False, then a rendering context that renders through the X
server is always created. Direct rendering provides a performance advantage in some
implementations. However, direct rendering contexts cannot be shared outside a single
process, and they may be unable to render to GLX pixmaps.

If shareList is not NULL, then all display-list indexes and definitions are shared by
context shareList and by the newly created context. An arbitrary number of contexts can
share a single display-list space. However, all rendering contexts that share a single
display-list space must themselves exist in the same address space. Two rendering
contexts share an address space if both are non-direct using the same server, or if both
are direct and owned by a single process. Note that in the non-direct case, it is not
necessary for the calling threads to share an address space, only for their related
rendering contexts to share an address space.

Chapter 3

If the GL version is 1.1 or greater, then all texture objects except object 0, are shared by
any contexts that share display lists.

87

C

glXCreateContext

Notes

XVisualInfo is defined in Xutil.h. It is a structure that includes visual, visualID, screen,
and depth elements.

A process is a single execution environment, implemented in a single address space,
consisting of one or more threads.

A thread is one of a set of subprocesses that share a single address space, but maintain
separate program counters, stack spaces, and other related global data. A thread that is
the only member of its subprocess group is equivalent to a process.

It may not be possible to render to a GLX pixmap with a direct rendering context.

Errors

• NULL is returned if execution fails on the client side.

• BadMatch is generated if the context to be created would not share the address

space or the screen of the context specified by shareList.

• BadValue is generated if vis is not a valid visual (for example, if a particular GLX

implementation does not support it).

• GLXBadContext is generated if shareList is not a GLX context and is not NULL.

• BadAlloc is generated if the server does not have enough resources to allocate the

new context.

See Also

glXDestroyContext,
glXGetConfig,
glXIsDirect,

glXMakeCurrent

88

Chapter 3

glXCreateGLXPixmap

glXCreateGLXPixmap

glXCreateGLXPixmap: create an off-screen GLX rendering area.

C Specification

GLXPixmap glXCreateGLXPixmap(

Display *dpy,
XVisualInfo *vis,

Pixmap pixmap)

Parameters

dpy Specifies the connection to the X server.
vis Specifies the visual that defines the structure of the rendering area. It

is a pointer to an XVisualInfo structure, not a visual ID or a pointer to

a Visual.

C

pixmap Specifiesthe X pixmap that will be used as the front left color buffer of

the off-screen rendering area.

Description

glXCreateGLXPixmap creates an off-screen rendering area and returns its XID. Any
GLX rendering context that was created with respect to vis can be used to render into
this off-screen area. Use glXMakeCurrent to associate the rendering area with a GLX
rendering context.

The X pixmap identified by pixmap is used as the front left buffer of the resulting
off-screen rendering area. All other buffers specified by vis, including color buffers other
than the front left buffer, are created without externally visible names. GLX pixmaps
with double-buffering are supported. However, glXSwapBuffers is ignored by these
pixmaps.

Some implementations may not support GLX pixmaps with direct rendering contexts.

Notes

XVisualInfo is defined in Xutil.h. It is a structure that includes visual, visualID, screen,
and depth elements.

Errors

Chapter 3

• BadMatch is generated if the depth of pixmap does not match the depth value

reported by core X11 for vis, or if pixmap was not created with respect to the same
screen as vis.

• BadValue is generated if vis is not a valid XVisualInfo pointer (for example, if a

particular GLX implementation does not support this visual).

• BadPixmap is generated if pixmap is not a valid pixmap.

89

C

glXCreateGLXPixmap

• BadAlloc is generated if the server cannot allocate the GLX pixmap.

See Also

glXCreateContext,
glXIsDirect,

glXMakeCurrent

90

Chapter 3

glCullFace

glCullFace

glCullFace: specify whether front- or back-facing facets can be culled.

C Specification

void glCullFace(

GLenum mode)

Parameters

mode Specifies whether front- or back-facing facets are candidates for

culling. Symbolic constants GL_FRONT, GL_BACK, and

GL_FRONT_AND_BACK are accepted. The initial value is GL_BACK.

Description

glCullFacespecifies whether front- or back-facing facets are culled (as specified by mode)
when facet culling is enabled. Facet culling is initially disabled. To enable and disable
facet culling, call the glEnable and glDisable commands with the argument
GL_CULL_FACE. Facets include triangles, quadrilaterals, polygons, and rectangles.

C

glFrontFace specifies which of the clockwise and counterclockwise facets are front-facing
and back-facing. See glFrontFace.

Notes

If mode is GL_FRONT_AND_BACK, no facets are drawn, but other primitives such as
points and lines are drawn.

Errors

• GL_INVALID_ENUM is generated if mode is not an accepted value.

• GL_INVALID_OPERATION is generated if glCullFace is executed between the

execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glIsEnabled with argument GL_CULL_FACE
glGet with argument GL_CULL_FACE_MODE

See Also

glEnable,
glFrontFace

Chapter 3

91

C

gluCylinder

gluCylinder

gluCylinder: draw a cylinder.

C Specification

void gluCylinder(

GLUquadric* quad,
GLdouble base,
GLdouble top,
GLdouble height,
GLint slices,

GLint stacks)

Parameters

quad Specifies the quadrics object (created with gluNewQuadric).
base Specifies the radius of the cylinder at z = 0.
top 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 top is set to 0.0, this routine generates 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, to0.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

92

Chapter 3

4D

Chapter 4

93

D

glDeleteLists

glDeleteLists

glDeleteLists: delete a contiguous group of display lists.

C Specification

void glDeleteLists(

GLuint list,
GLsizei range)

Parameters

list Specifies the integer name of the first display list to delete.
range Specifies the number of display lists to delete.

Description

glDeleteLists causes a contiguous group of display lists to be deleted. list is the name of
the first display list to be deleted, and range is the number of display lists to delete. All
display lists d with list ≥ d ≥ list + range - 1 are deleted.

All storage locations allocated to the specified display lists are freed, and the names are
available for reuse at a later time. Names within the range that do not have an

associated display list are ignored. If range is 0, nothing happens.

Errors

• GL_INVALID_VALUE is generated if range is negative.

• GL_INVALID_OPERATION is generated if glDeleteLists is executed between the

execution of glBegin and the corresponding execution of glEnd.

See Also

glCallList,
glCallLists,
glGenLists,
glIsList,

glNewList

94

Chapter 4

gluDeleteNurbsRenderer

gluDeleteNurbsRenderer

gluDeleteNurbsRenderer: destroy a NURBS object.

C Specification

void gluDeleteNurbsRenderer(

GLUnurbs* nurb)

Parameters

nurb Specifies the NURBS object to be destroyed.

Description

gluDeleteNurbsRenderer destroys the NURBS object (which was created with
gluNewNurbsRenderer) and frees any memory it uses. Once gluDeleteNurbsRenderer

has been called, nurb cannot be used again.

D

See Also

gluNewNurbsRenderer

Chapter 4

95

D

gluDeleteQuadric

gluDeleteQuadric

gluDeleteQuadric: destroy a quadrics object.

C Specification

void gluDeleteQuadric(

GLUquadric* quad)

Parameters

quad Specifies the quadrics object to be destroyed.

Description

gluDeleteQuadric destroys the quadrics object (created with gluNewQuadric) and frees
any memory it uses. Once gluDeleteQuadric has been called, quad cannot be used again.

See Also

gluNewQuadric

96

Chapter 4

gluDeleteTess

gluDeleteTess

gluDeleteTess: destroy a tessellation object.

C Specification

void gluDeleteTess(

GLUtesselator* tess)

Parameters

tess Specifies the tessellation object to destroy.

Description

gluDeleteTess destroys the indicated tessellation object (which was created with
gluNewTess) and frees any memory that it used.

D

See Also

gluBeginPolygon,
gluNewTess,

gluTessCallback

Chapter 4

97

D

glDeleteTextures

glDeleteTextures

glDeleteTextures: delete named textures.

C Specification

void glDeleteTextures(

GLsizei n,
const GLuint *textures)

Parameters

n Specifies the number of textures to be deleted.
textures Specifies an array of textures to be deleted.

Description

glDeleteTexturesdeletes n textures named by the elements of the array textures. After a
texture is deleted, it has no contents or dimensionality, and its name is free for reuse (for
example by glGenTextures). If a texture that is currently bound is deleted, the binding
everts to 0 (the default texture).

glDeleteTextures silently ignores 0s and names that do not correspond to existing
textures.

Notes

glDeleteTextures is available only if the GL version is 1.1 or greater.

Errors

• GL_INVALID_VALUE is generated if n is negative.

• GL_INVALID_OPERATION is generated if glDeleteTextures is executed between

the execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glIsTexture

See Also

glAreTexturesResident,
glBindTexture,
glCopyTexImage1D,
glCopyTexImage2D,
glGenTextures,
glGet,
glGetTexParameter,
glPrioritizeTextures,

98

Chapter 4

glTexImage1D,
glTexImage2D,

glTexParameter

D

glDeleteTextures

Chapter 4

99

D

glDepthFunc

glDepthFunc

glDepthFunc: specify the value used for depth buffer comparisons.

C Specification

void glDepthFunc(

GLenum func)

Parameters

func Specifies the depth comparison function. Symbolic constants

GL_NEVER, GL_LESS, GL_EQUAL, GL_LEQUAL, GL_GREATER,
GL_NOTEQUAL, GL_GEQUAL, and GL_ALWAYS are accepted. The

initial value is GL_LESS.

Description

glDepthFunc specifies the function used to compare each incoming pixel depth value
with the depth value present in the depth buffer. The comparison is performed only if
depth testing is enabled. (See glEnable and glDisable of GL_DEPTH_TEST.)

func specifies the conditions under which the pixel will be drawn. The comparison
functions are as follows:

GL_NEVER
Never passes.
GL_LESS
Passes if the incoming depth value is less than the stored depth value.
GL_EQUAL
Passes if the incoming depth value is equal to the stored depth value.
GL_LEQUAL
Passes if the incoming depth value is less than or equal to the stored depth value.
GL_GREATER
Passes if the incoming depth value is greater than the stored depth value.
GL_NOTEQUAL
Passes if the incoming depth value is not equal to the stored depth value.
GL_GEQUAL

100

Passes if the incoming depth value is greater than or equal to the stored depth value.
GL_ALWAYS
Always passes.

The initial value of func is GL_LESS. Initially, depth testing is disabled.

Chapter 4