1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2 <html> 3 <head> 4 <title>Mini GLX Specification</title> 5 </head> 6 <body> 7 <span style="font-style: italic;"></span><span 8 style="font-weight: bold;"></span> 9 <h1> 10 <center>Mesa Subset Specification</center> 11 </h1> 12 <h2> 13 <center> 14 <h3>Tungsten Graphics, Inc.</h3> 15 <h3>February 26, 2003<br> 16 </h3> 17 </center> 18 </h2> 19 <p> Copyright © 2002-2003 by Tungsten Graphics, Inc., 20 Cedar Park, Texas. All Rights Reserved. <br> 21 <br> 22 Permission is granted to make and distribute verbatim copies of this 23 document provided the copyright notice and this permission notice are 24 preserved on all copies.<br> 25 </p> 26 <p> OpenGL is a trademark of <a href="http://www.sgi.com">Silicon 27 Graphics, Inc.</a>.</p> 28 <h1>1. Introduction</h1> 29 This document describes a subset of the Mesa implemented by Tungsten 30 Graphics, Inc. for embedded devices. Prior to reading this 31 document the reader should be familiar with the OpenGL 1.2.1 32 specification dated April 1, 1999 (available from <a 33 href="http://www.opengl.org/developers/documentation/specs.html">http://www.opengl.org/developers/documentation/specs.html</a>.) 34 Experience with OpenGL programming is highly advisable.<a 35 href="http://www.opengl.org/developers/documentation/specs.html"><br> 36 </a><br> 37 Tungsten Graphics, Inc. is working with industry standards 38 organizations +in an attempt to standardize this Mesa subset and any 39 other possible subsets +as a result of this work. <br> 40 <br> 41 Appendix A contains a list of issues of which some may not be resolved.<br> 42 <br> 43 To summarize, the following major features of Mesa are omitted from the 44 subset:<br> 45 <ul> 46 <li>Vertex arrays</li> 47 <li>Texture coordinate generation</li> 48 <li>Lighting</li> 49 <li>Point size</li> 50 <li>Polygon stipple</li> 51 <li>DrawPixels, CopyPixels, PixelZoom</li> 52 <li>1-D and 3-D textures</li> 53 <li>CopyTex[Sub]Image</li> 54 <li>Fog</li> 55 <li>Depth test</li> 56 <li>Color Index mode</li> 57 <li>Accumulation buffer</li> 58 <li>Feedback mode</li> 59 <li>Evaluators</li> 60 <li>Push/Pop attributes</li> 61 <li>Display lists<br> 62 </li> 63 </ul> 64 <p>Further reductions are made at a lower level of detail.<br> 65 </p> 66 <p>Mesa function names are printed in <span style="font-weight: bold;">bold 67 face</span>. Function parameters are printed in <span 68 style="font-style: italic;">italics</span>.<br> 69 </p> 70 <p>The Tungsten Graphics, Inc. Mesa subset library is hereafter 71 referred to as <span style="font-style: italic;">the subset.</span><br> 72 <br> 73 </p> 74 <h1>2. Primitive Specification</h1> 75 <h2>2.1 glBegin, glEnd and glVertex Commands</h2> 76 The basic rendering primitives are points, lines and triangles. 77 Quadrilaterals and polygons are composed of triangles. 78 Primitives are drawn with the <span style="font-weight: bold;">glBegin</span> 79 and <span style="font-weight: bold;">glEnd</span> commands and a subset 80 of the <span style="font-weight: bold;">glVertex</span> commands:<br> 81 <br> 82 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glBegin</span>(GLenum<span 83 style="font-style: italic;">mode</span>)<br> 84 void <span style="font-weight: bold;">glEnd</span>(void)<br> 85 <br> 86 void <span style="font-weight: bold;">glVertex2f</span>(GLfloat <span 87 style="font-style: italic;">x</span>, GLfloat <span 88 style="font-style: italic;">y</span>)<br> 89 void <span style="font-weight: bold;">glVertex2fv</span>(const GLfloat 90 *<span style="font-style: italic;">v</span>)<br> 91 void <span style="font-weight: bold;">glVertex3f</span>(GLfloat <span 92 style="font-style: italic;">x</span>, GLfloat <span 93 style="font-style: italic;">y</span>, GLfloat <span 94 style="font-style: italic;">z</span>)<br> 95 void <span style="font-weight: bold;">glVertex3fv</span>(const GLfloat 96 *<span style="font-style: italic;">v</span>)<br> 97 </div> 98 <br> 99 The <span style="font-style: italic;">mode</span> parameter to <span 100 style="font-weight: bold;">glBegin</span> may be one of the following<br> 101 <br> 102 <div style="margin-left: 40px;">GL_POINTS - a series of individual 103 points<br> 104 GL_LINES - a series of disjoint line segments<br> 105 GL_LINE_STRIP - series of connected line segments<br> 106 GL_LINE_LOOP - a closed loop of line segments<br> 107 GL_TRIANGLES - a series of individual triangles<br> 108 GL_TRIANGLE_STRIP - a connected strip of triangles<br> 109 GL_TRIANGLE_FAN - a sequence of triangles all sharing a common vertex<br> 110 GL_QUADS - a sequence of individual quadrilaterals<br> 111 GL_QUAD_STRIP - a connected strip of quadrilaterals<br> 112 GL_POLYGON - a closed, convex polygon<br> 113 <br> 114 </div> 115 <br> 116 The <span style="font-weight: bold;">glVertex</span> commands take two 117 or three floating point coordinates, or a pointer to an array of two or 118 three floating point coordinates. Vertices are actually 4-element 119 homogeneous coordinates. The fourth component, unspecified by the 120 subset's <span style="font-weight: bold;">glVertex</span> commands, is 121 one.<br> 122 <br> 123 <span style="font-weight: bold;"></span> 124 <h2>2.2 Other Per-vertex Commands<br> 125 </h2> 126 The <span style="font-weight: bold;">glColor</span> and <span 127 style="font-weight: bold;">glTexCoord</span> commands may be used to 128 specify colors and texture coordinates for each vertex:<br> 129 <br> 130 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glColor3f</span>(GLfloat<span 131 style="font-style: italic;">red</span>, GLfloat <span 132 style="font-style: italic;">green</span>, GLfloat <span 133 style="font-style: italic;">blue</span>)<br> 134 void <span style="font-weight: bold;">glColor3fv</span>(const GLfloat *<span 135 style="font-style: italic;">rgb</span>)<br> 136 void <span style="font-weight: bold;">glColor4f</span>(GLfloat <span 137 style="font-style: italic;">red,</span> GLfloat <span 138 style="font-style: italic;">green,</span> GLfloat <span 139 style="font-style: italic;">blue,</span> GLfloat <span 140 style="font-style: italic;">alpha</span>)<br> 141 void <span style="font-weight: bold;">glColor4fv</span>(const GLfloat *<span 142 style="font-style: italic;">rgba</span>)<br> 143 void <span style="font-weight: bold;">glTexCoord2f</span>(GLfloat <span 144 style="font-style: italic;">s</span>, GLfloat<span 145 style="font-style: italic;"> t</span>)<br> 146 void <span style="font-weight: bold;">glTexCoord2fv</span>(const 147 GLfloat *<span style="font-style: italic;">c</span>)<br> 148 <br> 149 </div> 150 The <span style="font-weight: bold;">glColor</span> commands specify 151 the color and optionally, the alpha value, for subsequent vertices. 152 For the <span style="font-weight: bold;">glColor3</span> commands, 153 alpha is set to one.<br> 154 <br> 155 The <span style="font-weight: bold;">glTexCoord2</span> commands 156 specify the texture coordinate for subsequent vertices. Texture 157 coordinates are actually four-component coordinates: (s, t, r, q). 158 The <span style="font-weight: bold;">glTexCoord2</span> commands 159 set s and t explicitly. The r and q components are zero and one, 160 respectively.<br> 161 <br> 162 <span style="font-weight: bold;"></span>Only <span 163 style="font-weight: bold;">glVertex, glColor</span> and <span 164 style="font-weight: bold;">glTexCoord</span> commands are allowed 165 between <span style="font-weight: bold;">glBegin</span> and <span 166 style="font-weight: bold;">glEnd.</span> Calling any other 167 command between <span style="font-weight: bold;">glBegin</span> and <span 168 style="font-weight: bold;">glEnd</span> will result in the error 169 GL_INVALID_OPERATION.<br> 170 <br> 171 <h2>2.3 Unsupported Commands</h2> 172 None of the following commands related to primitive specification are 173 supported by the subset:<br> 174 <br> 175 <div style="margin-left: 40px;">Per-Vertex commands:<br> 176 </div> 177 <div style="margin-left: 40px;"> 178 <div style="margin-left: 40px;"><span style="font-weight: bold;">glVertex2d, 179 glVertex2i, glVertex2s, glVertex3d, glVertex3i, glVertex3s, glVertex4d, 180 glVertex4i, glVertex4s, glVertex2dv, glVertex2iv, glVertex2sv, 181 glVertex3dv, glVertex3iv, glVertex3sv, glVertex4dv, glVertex4iv, 182 glVertex4sv,<br> 183 glNormal3b, glNormal3d, glNormal3f, glNormal3i, glNormal3s, </span><span 184 style="font-weight: bold;">glNormal3bv, glNormal3dv, glNormal3fv, 185 glNormal3iv, glNormal3sv,<br> 186 glIndexd, glIndexf, glIndexi, glIndexs, glIndexub, glIndexdv, 187 glIndexfv, glIndexiv, glIndexsv, glIndexubv,<br> 188 glColor3b, glColor3d, glColor3i, glColor3s, glColor3ub, glColor3ui, 189 glColor3us, </span><span style="font-weight: bold;">glColor3bv, 190 glColor3dv, glColor3iv, glColor3sv, glColor3ubv, glColor3uiv, 191 glColor3usv,</span><span style="font-weight: bold;"> lColor4b, 192 glColor4d, glColor4i, glColor4s, glColor4ub, glColor4ui, glColor4us, </span><span 193 style="font-weight: bold;">glColor4bv, glColor4dv, glColor4iv, 194 glColor4sv, glColor4ubv, glColor4uiv, glColor4usv,<br> 195 </span><span style="font-weight: bold;">glTexCoord1d, glTexCoord1f, 196 glTexCoord1i, glTexCoord1s, glTexCoord2d, glTexCoord2i, glTexCoord2s, 197 glTexCoord3d, glTexCoord3f, glTexCoord3i, glTexCoord3s, glTexCoord4d, 198 glTexCoord4f, glTexCoord4i, glTexCoord4s, glTexCoord1dv, glTexCoord1fv, 199 glTexCoord1iv, glTexCoord1sv, glTexCoord2dv, glTexCoord2iv, 200 glTexCoord2sv, glTexCoord3dv, glTexCoord3fv, glTexCoord3iv, 201 glTexCoord3sv, glTexCoord4dv, glTexCoord4fv, glTexCoord4iv, 202 glTexCoord4sv,<br> 203 glEdgeFlag, glEdgeFlagv</span><br style="font-weight: bold;"> 204 <br> 205 </div> 206 Vertex array commands:<br> 207 <div style="margin-left: 40px;"><span style="font-weight: bold;">glVertexPointer, 208 glColorPointer, glIndexPointer, glTexCoordPointer, glEdgeFlagPointer, 209 glNormalPointer, glInterleavedArrays, glArrayElement, glDrawArrays, 210 glDrawElements, glDrawRangeElements, glEnableClientState, 211 glDisableClientState</span><br> 212 </div> 213 </div> 214 <div style="margin-left: 40px;"><br> 215 Rectangle commands:<br> 216 <div style="margin-left: 40px;"><span style="font-weight: bold;">glRects, 217 glRecti, glRectf, glRectd, glRectsv, glRectiv, glRectfv, glRectdv,<br> 218 <br> 219 </span></div> 220 </div> 221 <div style="margin-left: 40px;">Lighting commands:<br> 222 </div> 223 <div style="margin-left: 80px;"><span style="font-weight: bold;">glMaterialf, 224 glMateriali, glMaterialfv, glMaterialiv<br> 225 </span><br> 226 </div> 227 <div style="margin-left: 40px;"> Evaluator commands:<br> 228 <div style="margin-left: 40px;"><span style="font-weight: bold;">glEvalCoord1d, 229 glEvalCoord1f, glEvalCoord1dv, glEvalCoord1fv, </span><span 230 style="font-weight: bold;">glEvalCoord2d, glEvalCoord2f, 231 glEvalCoord2dv, glEvalCoord2fv,<br> 232 </span><span style="font-weight: bold;">glEvalPoint1, glEvalPoint2</span><br> 233 <br> 234 </div> 235 </div> 236 <h1>3. Coordinate Transformation</h1> 237 <h2>3.1 Vertex Transformation</h2> 238 Vertex coordinates are transformed by the current modelview and 239 projection matrices then mapped to window coordinates as specified by 240 the viewport. The following coordinate transformation commands are 241 supported by the subset<br> 242 <br> 243 <div style="margin-left: 40px; font-weight: bold;">glMatrixMode<span 244 style="font-weight: normal;">(GLenum <span style="font-style: italic;">mode</span>)</span><br> 245 glLoadIdentity<span style="font-weight: normal;">(void)</span><br> 246 glPushMatrix<span style="font-weight: normal;">(void)</span><br> 247 glPopMatrix<span style="font-weight: normal;">(void)</span><br> 248 glLoadMatrixf<span style="font-weight: normal;">(const GLfloat *<span 249 style="font-style: italic;">m</span>)</span><br> 250 glMultMatrixf<span style="font-weight: normal;">(const GLfloat *<span 251 style="font-style: italic;">m</span>)</span><br> 252 glRotatef<span style="font-weight: normal;">(GLfloat <span 253 style="font-style: italic;">angle</span>, GLfloat <span 254 style="font-style: italic;">x</span>, GLfloat <span 255 style="font-style: italic;">y</span>, GLfloat <span 256 style="font-style: italic;">z</span>)</span><br> 257 glTranslatef<span style="font-weight: normal;">(GLfloat <span 258 style="font-style: italic;">x</span>, GLfloat <span 259 style="font-style: italic;">y</span>, GLfloat <span 260 style="font-style: italic;">z</span>)</span><br> 261 glScalef<span style="font-weight: normal;">(GLfloat <span 262 style="font-style: italic;">x</span>, GLfloat <span 263 style="font-style: italic;">y</span>, GLfloat <span 264 style="font-style: italic;">z</span>)<br> 265 <span style="font-weight: bold;">glFrustum(</span>GLdouble <span 266 style="font-style: italic;">left,</span> GLdouble <span 267 style="font-style: italic;">right,</span> GLdouble <span 268 style="font-style: italic;">bottom,</span> GLdouble <span 269 style="font-style: italic;">top,</span> GLdouble <span 270 style="font-style: italic;">near,</span> GLdouble <span 271 style="font-style: italic;">far</span>)</span><br> 272 <span style="font-weight: normal;"><span style="font-weight: bold;">glOrtho(</span>GLdouble<span 273 style="font-style: italic;"> left,</span> GLdouble <span 274 style="font-style: italic;">right,</span> GLdouble <span 275 style="font-style: italic;">bottom,</span> GLdouble <span 276 style="font-style: italic;">top,</span> GLdouble <span 277 style="font-style: italic;">near,</span> GLdouble <span 278 style="font-style: italic;">far</span>)</span><br> 279 glViewport<span style="font-weight: normal;">(GLint <span 280 style="font-style: italic;">x</span>, GLint <span 281 style="font-style: italic;">y</span>, GLsize <span 282 style="font-style: italic;">width,</span> GLsizei <span 283 style="font-style: italic;">height</span>)</span><br> 284 </div> 285 <br> 286 The <span style="font-weight: bold;">glMatrixMode</span> command 287 specifies the <span style="font-style: italic;">current matrix.</span> 288 The mode parameter may be GL_MODELVIEW or GL_PROJECTION to specify 289 the modelview matrix or projection matrix. Subsequent matrix 290 commands will effect the current matrix. Also associated with the 291 modelview and projection matrices are a modelview matrix stack and 292 projection matrix stack.<br> 293 <br> 294 The <span style="font-weight: bold;">glLoadIdentity</span> command 295 replaces the current matrix with the identity matrix. The matrix 296 elements are specified in column-major order.<br> 297 <br> 298 The <span style="font-weight: bold;">glPushMatrix</span> command pushes 299 a copy of the current matrix onto either the modelview matrix stack or 300 the projection matrix stack. The <span style="font-weight: bold;">glPopMatrix</span> 301 command replaces the current matrix with a copy of the top matrix off 302 the modelview matrix stack or projection matrix stack, the pops the 303 stack. Matrix stacks are useful for traversing and rendering 304 hierarchical models.<br> 305 <br> 306 The <span style="font-weight: bold;">glMultMatrixf</span> command 307 post-multiplies the current matrix by the specified matrix. The 308 matrix elements are specified in column-major order.<br> 309 <br> 310 The <span style="font-weight: bold;">glRotatef</span> command 311 post-multiplies the current matrix by a rotation matrix defined by the 312 angle and rotation axis defined by x, y and z.<br> 313 <br> 314 The <span style="font-weight: bold;">glTranslatef</span> command 315 post-multiplies the current matrix by a translation matrix defined by 316 the <span style="font-style: italic;">x</span>, <span 317 style="font-style: italic;">y</span> and <span 318 style="font-style: italic;">z</span> translation parameters.<br> 319 <span style="font-weight: bold;"></span><br> 320 The <span style="font-weight: bold;">glScalef</span> command 321 post-multiplies the current matrix by a scaling matrix defined by the <span 322 style="font-style: italic;">x</span>, <span 323 style="font-style: italic;">y</span> and <span 324 style="font-style: italic;">z</span> scale factors.<br> 325 <span style="font-weight: bold;"></span><br> 326 The <span style="font-weight: bold;">glFrustum</span> command 327 post-multiplies the current matrix by a perspective projection matrix. 328 The <span style="font-style: italic;">near</span> and <span 329 style="font-style: italic;">far</span> values specify the position of 330 the hither and yon Z-axis clipping planes. The <span 331 style="font-style: italic;">left, right, bottom</span> and <span 332 style="font-style: italic;">top</span> parameters are the X and Y 333 extents at the near clipping plane. <span 334 style="font-weight: bold;">glFrustum</span> is normally used to modify 335 the projection matrix.<br> 336 <br> 337 The <span style="font-weight: bold;">glOrtho</span> command 338 post-multiplies the current matrix by an orthographic projection matrix. 339 The <span style="font-style: italic;">near</span> and <span 340 style="font-style: italic;">far</span> values specify the position of 341 the hither and yon Z-axis clipping planes. The <span 342 style="font-style: italic;">left, right, bottom</span> and <span 343 style="font-style: italic;">top</span> parameters specify the X and 344 Y-axis clipping planes. <span style="font-weight: bold;">glOrtho</span> 345 is normally used to modify the projection matrix.<br> 346 <br> 347 The <span style="font-weight: bold;">glViewport</span> command 348 specifies the mapping of coordinates from normalized device coordinates 349 to window coordinates. The <span style="font-style: italic;">x</span> 350 and <span style="font-style: italic;">y</span> parameters specify the 351 viewport's lower-left corner in the window and the <span 352 style="font-style: italic;">width</span> and <span 353 style="font-style: italic;">height</span> parameters specify the size 354 of the viewport. <span style="font-weight: bold;">glViewport</span> 355 does not effect the current matrix.<br> 356 <br> 357 A coordinate transformed to window coordinates is hereafter known as (x<sub>w</sub>, 358 y<sub>w</sub>, z<sub>w</sub>).<br> 359 <br> 360 <h2>3.2 Clipping</h2> 361 View-volume clipping automatically discards or trims primitives which 362 lie completely or partially outside of the view volume specified by <span 363 style="font-weight: bold;">glFrustum</span> and <span 364 style="font-weight: bold;">glOrtho</span>. Note that the <span 365 style="font-weight: bold;">glViewport</span> command does not define a 366 clipping region.<br> 367 <br> 368 Clipping occurs in <span style="font-style: italic;">clip coordinate 369 space - </span>the coordinates produced after applying the projection 370 matrix.<br> 371 <br> 372 <h2>3.3 Current Raster Position</h2> 373 The current raster position specifies the location for drawing images 374 with <span style="font-weight: bold;">glBitmap.</span> The current 375 raster position is set with the commands:<br> 376 <br> 377 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glRasterPos2f</span>(GLfloat<span 378 style="font-style: italic;">x</span>, GLfloat <span 379 style="font-style: italic;">y</span>)<br> 380 void <span style="font-weight: bold;">glRasterPos2fv</span>(const 381 GLfloat *<span style="font-style: italic;">v</span>)<br> 382 void <span style="font-weight: bold;">glRasterPos2i</span>(GLint <span 383 style="font-style: italic;">x</span>, GLint <span 384 style="font-style: italic;">y</span>)<br> 385 void <span style="font-weight: bold;">glRasterPos2iv</span>(const 386 GLint *<span style="font-style: italic;">v</span>)<br> 387 </div> 388 <br> 389 <span style="font-weight: bold;">glRasterPos</span> specifies a 390 4-component coordinate (x, y, 0, 1). The coordinate is processed 391 like a vertex; it is transformed by the modelview matrix, the projection 392 matrix and mapped to the viewport. The resulting window coordinate 393 is stored as the current raster position. The coordinate is 394 clipped-tested against the frustum like a vertex. If the 395 coordinate is clipped, then the current raster position becomes invalid 396 and subsequent <span style="font-weight: bold;">glBitmap</span> commands 397 have no effect.<br> 398 <br> 399 <span style="font-weight: bold;">glRasterPos</span> also updates the 400 current raster color and current raster texture coordinates. The 401 current raster color is updated (copied) from the current color (as 402 specified by <span style="font-weight: bold;">glColor</span>). 403 The current raster texture coordinate is updated (copied) from the 404 current texture coordinate (as specified by <span 405 style="font-weight: bold;">glTexCoord</span>).<br> 406 <br> 407 <h2>3.4 Unsupported Commands</h2> 408 The following commands related to vertex transformation are not 409 supported by the subset:<br> 410 <br> 411 <div style="margin-left: 40px;">User-defined clip plane commands:<br> 412 <div style="margin-left: 40px;"><span style="font-weight: bold;">glClipPlane</span><br> 413 </div> 414 <span style="font-weight: bold;"></span></div> 415 <br> 416 <div style="margin-left: 40px;">Lighting and material commands:</div> 417 <div style="margin-left: 80px;"><span style="font-weight: bold;">glLightModeli, 418 glLightModelf, </span><span style="font-weight: bold;">glLightModeliv, 419 glLightModelfv,</span><span style="font-weight: bold;"> glLightf, 420 glLighti, glLightfv, glLightiv, glColorMaterial</span><br> 421 </div> 422 <br> 423 <div style="margin-left: 40px;">Automatic texture coordinate generation 424 commands:<br> 425 </div> 426 <div style="margin-left: 40px;"> 427 <div style="margin-left: 40px;"><span style="font-weight: bold;">glTexGend, 428 glTexGenf, glTexGeni, </span><span style="font-weight: bold;">glTexGendv, 429 glTexGenfv, glTexGeniv, </span><br> 430 <br style="font-weight: bold;"> 431 </div> 432 Double-valued commands:<br> 433 <div style="margin-left: 40px;"><span style="font-weight: bold;">glLoadMatrixd, 434 glMultMatrixd, glRotated, glTranslated, glScaled</span><br 435 style="font-weight: bold;"> 436 </div> 437 <br> 438 Depth Range command:<br> 439 <div style="margin-left: 40px;"><span style="font-weight: bold;">glDepthRange</span> 440 (the near value is always 0.0 and the far value is always 1.0)<br> 441 </div> 442 <br> 443 Extra RasterPos commands:<br> 444 <div style="margin-left: 40px;"><span style="font-weight: bold;">glRasterPos2d, 445 glRasterPos2s, glRasterPos3d, glRasterPos3f, glRasterPos3i, 446 glRasterPos3s, glRasterPos4d, glRasterPos4f, glRasterPos4i, 447 glRasterPos4s, glRasterPos2dv, glRasterPos2sv, glRasterPos3dv, 448 glRasterPos3fv, glRasterPos3iv, glRasterPos3sv, glRasterPos4dv, 449 glRasterPos4fv, glRasterPos4iv, glRasterPos4sv</span><br> 450 </div> 451 <br> 452 <br> 453 </div> 454 <h1>4. Rasterization</h1> 455 This section describes the commands and options for drawing points, 456 lines, triangles and bitmaps. <span style="font-style: italic;">Rasterization</span> 457 is the term for the process which produces fragments from the geometric 458 description of a primitive (a point, line, polygon or bitmap). For 459 example, given the two coordinates for the end-points of a line segment, 460 rasterization determines which pixels in the frame buffer are modified 461 to <span style="font-style: italic;">draw</span> the line. A 462 fragment is a tuple which consists of a window coordinate, colors and 463 texture coordinates. The fragments produced by rasterization are 464 subsequently processed by the per-fragment operations described later.<br> 465 <br> 466 <h2>4.1 Point Rasterization</h2> 467 Points are rendered with the command sequence <span 468 style="font-weight: bold;">glBegin</span>(GL_POINTS), <span 469 style="font-weight: bold;">glVertex</span>, ... <span 470 style="font-weight: bold;">glEnd</span>. The window coordinate (x<sub>w</sub>, 471 y<sub>w</sub>, z<sub>w</sub>) is truncated to rasterize the point. 472 The truncated coordinate with its associated color and texture 473 coordinate is sent as a single fragment to the per-fragment processing 474 stages.<br> 475 <br> 476 The <span style="font-weight: bold;">glPointSize</span> command is not 477 supported; only 1-pixel points are supported.<br> 478 <br> 479 Point smoothing (antialiasing) is also not supported.<br> 480 <br> 481 <h2>4.2 Line Rasterization</h2> 482 Lines are rendered with the command sequence <span 483 style="font-weight: bold;">glBegin</span>(<span 484 style="font-style: italic;">mode</span>), <span 485 style="font-weight: bold;">glVertex</span>, <span 486 style="font-weight: bold;">glVertex</span>, ... <span 487 style="font-weight: bold;">glEnd</span> where <span 488 style="font-style: italic;">mode</span> is one of GL_LINES, 489 GL_LINE_STRIP or GL_LINE_LOOP. Lines are rasterized as described 490 in the OpenGL specification. Note that OpenGL specifies the <span 491 style="font-style: italic;">half-open</span> convention for drawing 492 lines: the last fragment in a line segment is omitted so that endpoint 493 pixels shared by two line segments will only be drawn once instead of 494 twice.<br> 495 <br> 496 <h3>4.2.1 Line Width</h3> 497 The width of lines can be controlled by<br> 498 <br> 499 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glLineWidth</span>(GLfloat<span 500 style="font-style: italic;">width</span>)<br> 501 </div> 502 <br> 503 where <span style="font-style: italic;">width</span> is the line width 504 in pixels. The width defaults to 1.0. Attempting to set the 505 width to a value less than or equal to zero will raise the error 506 GL_INVALID_VALUE.<br> 507 <br> 508 <h3>4.2.2 Line Stipple<br> 509 </h3> 510 Lines may be stippled (i.e. dashed) with the command<br> 511 <br> 512 <div style="margin-left: 40px;"><span style="font-weight: bold;">glLineStipple</span>(GLint<span 513 style="font-style: italic;">factor</span>, GLushort <span 514 style="font-style: italic;">pattern</span>)<br> 515 </div> 516 <br> 517 <span style="font-style: italic;">pattern</span> describes an on/off 518 pattern for the fragments produced by rasterization and <span 519 style="font-style: italic;">factor</span> specifies how many subsequent 520 fragments are kept or culled for each pattern bit. Line stippling 521 can be enabled or disabled by the commands <span 522 style="font-weight: bold;">glEnable</span>(GL_LINE_STIPPLE) and <span 523 style="font-weight: bold;">glDisable</span>(GL_LINE_STIPPLE).<br> 524 <br> 525 <h3>4.2.3 Line Antialiasing</h3> 526 Lines may be antialiased. For antialiased lines, each fragment 527 produced by rasterization is assigned a <span 528 style="font-style: italic;">coverage value</span> which describes how 529 much of the fragment's area is considered to be <span 530 style="font-style: italic;">inside</span> the line. Later, the 531 alpha value of each fragment is multiplied by the coverage value. 532 By blending the fragments into the frame buffer, the edges of 533 lines appear smoothed.<br> 534 <br> 535 Line antialiasing can be enabled or disabled with the commands <span 536 style="font-weight: bold;">glEnable</span>(GL_LINE_SMOOTH) and <span 537 style="font-weight: bold;">glDisable</span>(GL_LINE_SMOOTH).<br> 538 <br> 539 <h2>4.3 Polygon Rasterization</h2> 540 Polygons, quadrilaterals and triangles share the same polygon 541 rasterization options. <br> 542 <br> 543 Triangles are rendered by the command sequence <span 544 style="font-weight: bold;">glBegin</span><span 545 style="font-style: italic;"><span style="font-style: italic;">(mode</span></span>),<span 546 style="font-weight: bold;">glVertex</span>, <span 547 style="font-weight: bold;">glVertex</span>, ... <span 548 style="font-weight: bold;">glEnd</span> where <span 549 style="font-style: italic;">mode</span> may be one of GL_TRIANGLES, 550 GL_TRIANGLE_STRIP or GL_TRIANGLE_FAN.<span style="font-weight: bold;"></span> 551 For GL_TRIANGLES mode, the number of vertices should be a multiple 552 of three - extra vertices will be ignored. For GL_TRIANGLE_STRIP 553 and GL_TRIANGLE_FAN, at least three vertices should be specified. 554 If less than three are specified, nothing is drawn. <br> 555 <br> 556 Quadrilaterals are <span style="font-weight: bold;"></span>rendered by 557 the command sequence <span style="font-weight: bold;">glBegin</span>(<span 558 style="font-style: italic;"><span style="font-style: italic;">mode</span></span>),<span 559 style="font-weight: bold;">glVertex</span>, <span 560 style="font-weight: bold;">glVertex</span>, ... <span 561 style="font-weight: bold;">glEnd</span> where <span 562 style="font-style: italic;">mode</span> may be one of GL_QUADS or 563 GL_QUAD_STRIP.<span style="font-weight: bold;"></span> For 564 GL_QUADS, the number of vertices should be a multiple of four - extra 565 vertices will be ignored. For GL_QUAD_STRIP, the number of 566 vertices should be even and at least four. Extra vertices (one) 567 will be ignored.<br> 568 <br> 569 Convex polygons are <span style="font-weight: bold;"></span>rendered 570 by the command sequence <span style="font-weight: bold;">glBegin</span><span 571 style="font-style: italic;"><span style="font-style: italic;"></span></span>(GL_POLYGON),<span 572 style="font-weight: bold;">glVertex</span>, <span 573 style="font-weight: bold;">glVertex</span>, ... <span 574 style="font-weight: bold;">glEnd</span>.<span 575 style="font-style: italic;"></span><span style="font-weight: bold;"></span> 576 If less than three vertices are specified, nothing is drawn.<br> 577 <br> 578 <h3>4.3.1 Polygon Orientation</h3> 579 The <span style="font-style: italic;">winding order</span> of vertices 580 (clockwise or counter-clockwise) is significant. It is used to 581 determine the <span style="font-style: italic;">front-facing</span> or <span 582 style="font-style: italic;">back-facing</span> orientation of polygons. 583 By default, a front-facing polygon's vertices are in 584 counter-clockwise order (in window coordinates). Figures 2.4 and 585 2.5 of the OpenGL 1.2.1 specification illustrate the winding order for 586 front-facing triangles and quadrilaterals, respectively.<br> 587 <br> 588 The command<br> 589 <br> 590 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glFrontFace</span>(GLenum<span 591 style="font-style: italic;"> mode</span>)<br> 592 </div> 593 <br> 594 specifies whether clockwise or counter-clockwise winding indicates a 595 front-facing polygon. If <span style="font-style: italic;">mode</span> 596 is GL_CW then polygons with clockwise winding are front-facing. If <span 597 style="font-style: italic;">mode</span> is GL_CCW then polygons with 598 counter-clockwise winding are front-facing. The default value is 599 GL_CCW. If <span style="font-style: italic;">mode</span> is not 600 GL_CCW or GL_CW then the error GL_INVALID_ENUM will be raised.<span 601 style="font-style: italic;"></span><span style="font-style: italic;"></span><br> 602 <br> 603 <h3>4.3.2 Polygon Culling</h3> 604 Polygons may be culled (discarded) depending on whether they are 605 front-facing or back-facing. The command<br> 606 <br> 607 <div style="margin-left: 40px;">void<span style="font-weight: bold;"> 608 glCullFace</span>(GLenum <span style="font-style: italic;">mode</span>)<br> 609 </div> 610 <br> 611 specifies whether front-facing, back-facing or all polygons should be 612 culled. If <span style="font-style: italic;">mode</span> is 613 GL_FRONT then front-facing polygons will be culled. If <span 614 style="font-style: italic;">mode</span> is GL_BACK then back-facing 615 polygons will be culled. Otherwise, if <span style="font-style: italic;">mode</span> 616 is GL_FRONT_AND_BACK then all polygons will be culled. Any other 617 value for <span style="font-style: italic;">mode</span> will raise the 618 error GL_INVALID_ENUM.<br> 619 <br> 620 Polygon culling is enabled and disabled with the commands <span 621 style="font-weight: bold;">glEnable</span>(GL_CULL_FACE) and <span 622 style="font-weight: bold;">glDisable</span>(GL_CULL_FACE), 623 respectively.<br> 624 <br> 625 <h3>4.3.3 Polygon Antialiasing</h3> 626 Polygons may be antialiased in order to smooth their edges. 627 Polygon antialiasing is enabled and disabled with the commands <span 628 style="font-weight: bold;">glEnable</span>(GL_POLYGON_SMOOTH) and <span 629 style="font-weight: bold;">glDisable</span>(GL_POLYGON_SMOOTH).<br> 630 <br> 631 When polygon antialiasing is enabled each fragment produced by polygon, 632 triangle and quadrilateral rasterization will be given a <span 633 style="font-style: italic;">coverage</span> value which indicates how 634 much of the fragment is covered by the polygon. Fragments 635 completely inside the polygon have coverage 1.0. Fragments 636 completely outside the polygon have zero coverage (in theory). 637 Fragments which intersect the polygon's edge have a coverage value 638 in the range (0, 1).<br> 639 <br> 640 The fragment's alpha value is multiplied by the coverage value. 641 By enabling the appropriate blending mode, polygon edges will 642 appear smoothed.<br> 643 <br> 644 <h2>4.4 Shading</h2> 645 The command<br> 646 <br> 647 <div style="margin-left: 40px;"> void <span style="font-weight: bold;">glShadeModel</span>(GLenum<span 648 style="font-style: italic;">mode</span>)<br> 649 </div> 650 <br> 651 determines whether colors are interpolated between vertices during 652 rasterization. If <span style="font-style: italic;">mode</span> is 653 GL_FLAT then vertex colors are not interpolated. The color used 654 for drawing lines, triangles and quadrilaterals is that of the last 655 vertex used to specify each primitive. For polygons, the color of 656 the first vertex specifies the color for the entire polygon. If <span 657 style="font-style: italic;">mode</span> is GL_SMOOTH then vertex colors 658 are linearly interpolated to produce the fragment colors.<br> 659 <br> 660 <h2>4.5 Bitmap Rasterization</h2> 661 A bitmap is a monochromatic, binary image in which each image element 662 (or pixel) is represented by one bit. Fragments are only generated 663 for the bits (pixels) which are set. Bitmaps are commonly used to 664 draw text (glyphs) and markers.<br> 665 <br> 666 A bitmap is drawn with the command<br> 667 <br> 668 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glBitmap</span>(GLsizei<span 669 style="font-style: italic;">width</span>, GLsizei <span 670 style="font-style: italic;">height</span>, GLfloat <span 671 style="font-style: italic;">xOrig</span>, GLfloat <span 672 style="font-style: italic;">yOrig</span>, GLfloat <span 673 style="font-style: italic;">xMove</span>, GLfloat <span 674 style="font-style: italic;">yMove</span>, const GLubyte *<span 675 style="font-style: italic;">image</span>)<br> 676 </div> 677 <br> 678 <span style="font-style: italic;">width </span>and <span 679 style="font-style: italic;">height</span> specify the image size in 680 pixels. <span style="font-style: italic;">xOrig</span> and <span 681 style="font-style: italic;">yOrig</span> specify the bitmap origin. 682 <span style="font-style: italic;">xMove</span> and <span 683 style="font-style: italic;">yMove</span> are added to the current 684 raster position after the bitmap is rasterized. <span 685 style="font-style: italic;">image</span> is a pointer to the bitmap 686 data.<br> 687 <br> 688 If the current raster position is not valid, <span 689 style="font-weight: bold;">glBitmap</span> has no effect.<br> 690 <br> 691 <h3>4.5.1 Bitmap Unpacking</h3> 692 The first step in bitmap rendering is <span style="font-style: italic;">unpacking. 693 </span>Unpacking is the process of extracting image data from 694 client memory subject to byte swapping, non-default row strides, etc. 695 The unpacking parameters are specified with the command<br> 696 <br> 697 <div style="margin-left: 40px;">void<span style="font-weight: bold;"> 698 glPixelStorei</span>(GLenum pname, GLint value)<br> 699 </div> 700 <span style="font-style: italic;"></span><br> 701 The following unpacking parameters may be set:<br> 702 <br> 703 <table cellpadding="2" cellspacing="2" border="1" 704 style="text-align: left; width: 90%; margin-left: auto; margin-right: auto;"> 705 <tbody> 706 <tr> 707 <td style="vertical-align: top;">Parameter (<span 708 style="font-style: italic;">pname</span>)<br> 709 </td> 710 <td style="vertical-align: top;">Value (<span 711 style="font-style: italic;">value</span>)<br> 712 </td> 713 <td style="vertical-align: top;">Default<br> 714 </td> 715 </tr> 716 <tr> 717 <td style="vertical-align: top;">GL_UNPACK_ROW_LENGTH<br> 718 </td> 719 <td style="vertical-align: top;">Width of the image in memory, in 720 pixels.<br> 721 </td> 722 <td style="vertical-align: top;">0<br> 723 </td> 724 </tr> 725 <tr> 726 <td style="vertical-align: top;">GL_UNPACK_LSB_FIRST<br> 727 </td> 728 <td style="vertical-align: top;">GL_FALSE indicates that the most 729 significant bit is unpacked first from each byte. GL_TRUE 730 indicates that the least significant bit is unpacked first from each 731 byte. <br> 732 </td> 733 <td style="vertical-align: top;">GL_FALSE<br> 734 </td> 735 </tr> 736 </tbody> 737 </table> 738 <br> 739 <br> 740 The GL_UNPACK_ROW_LENGTH specifies the stride (in pixels) for advancing 741 from one row of the image to the next. If it's zero, the <span 742 style="font-style: italic;">width</span> parameter to <span 743 style="font-weight: bold;">glBitmap</span> specifies the width of the 744 image in memory.<br> 745 <br> 746 GL_UNPACK_LSB_FIRST determines whether the least significant or most 747 significant bit in each byte is unpacked first. Unpacking occurs 748 in left to right order (in image space).<br> 749 <br> 750 The value of bit (i, j) of the image (where i is the image row and j is 751 the image column) is found as follows:<br> 752 <br> 753 <div style="margin-left: 40px;">rowLength = (GL_UNPACK_ROW_LENGTH != 0) 754 ? GL_UNPACK_ROW_LENGTH : <span style="font-style: italic;">width</span>;<br> 755 <br> 756 byte = <span style="font-style: italic;">image</span>[((rowLength + 7) 757 / 8) * i + j / 8];<br> 758 <br> 759 if (GL_UNPACK_LSB_FIRST != 0)<br> 760 bitMask = 1 << (j % 8);<br> 761 else<br> 762 bitMask = 128 >> (j % 8);<br> 763 <br> 764 if (byte & bitMask)<br> 765 bit = 1;<br> 766 else<br> 767 bit = 0;<br> 768 <br> 769 </div> 770 <span style="font-style: italic;"><span style="font-style: italic;"></span></span> 771 <h3>4.5.2 Rasterization</h3> 772 If the current raster position is (x<sub>rp</sub>, y<sub>rp</sub>, z<sub>rp</sub>, 773 w<sub>rp</sub>), then the bitmap is rasterized according to the 774 following algorithm:<br> 775 <br> 776 for (j = 0; j < <span style="font-style: italic;">height</span>; 777 j++) {<br> 778 for (i = 0; i < <span style="font-style: italic;">width</span>; 779 i++) {<br> 780 if (bit(i,j)) {<br> 781 fragment.x = 782 floor(x<sub>rp</sub> - <span style="font-style: italic;">xOrig</span>) 783 + i;<br> 784 fragment.y = 785 floor(y<sub>rp</sub> - <span style="font-style: italic;">yOrig</span>) 786 + j;<br> 787 fragment.color 788 = GL_CURRENT_RASTER_COLOR;<br> 789 790 fragment.texture = GL_CURRENT_RASTER_TEXTURE_COORDS;<br> 791 792 ProcessFragment(fragment)<br> 793 }<br> 794 }<br> 795 }<br> 796 <br> 797 After the bitmap has been rendered the current raster position is 798 updated as follows:<br> 799 <br> 800 <div style="margin-left: 40px;">x<sub>rp</sub> = x<sub>rp</sub> + <span 801 style="font-style: italic;">xMove</span><br> 802 y<sub>rp</sub> = y<sub>rp</sub> + <span style="font-style: italic;">yMove</span><br> 803 </div> 804 <br> 805 <h3>4.5.3 Per-fragment Operations</h3> 806 XXX supported? See issue in appendix A.<br> 807 <br> 808 <h2>4.6 Unsupported Commands</h2> 809 The following commands related to rasterization are not supported by 810 the subset.<br> 811 <br> 812 <div style="margin-left: 40px;">Point commands:<br> 813 <div style="margin-left: 40px;"><span style="font-weight: bold;">glPointSize</span><br> 814 </div> 815 <br> 816 Polygon commands:<br> 817 <div style="margin-left: 40px; font-weight: bold;">glPolygonStipple<br> 818 glPolygonOffset<br> 819 glPolygonMode<br> 820 <br> 821 </div> 822 </div> 823 <div style="margin-left: 40px;">Pixel storage commands:<br> 824 </div> 825 <div style="font-weight: bold; margin-left: 80px;">glPixelStoref<br> 826 </div> 827 <br> 828 <br> 829 <h1>5. Texture Mapping<br> 830 </h1> 831 There are four elements to texture mapping: texture coordinate 832 specification, texture image specification, texture sampling and texture 833 application.<br> 834 <br> 835 Texture mapping is enabled and disabled with the commands <span 836 style="font-weight: bold;">glEnable</span>(GL_TEXTURE_2D) and <span 837 style="font-weight: bold;">glDisable</span>(GL_TEXTURE_2D).<br> 838 <br> 839 <h2>5.1 Texture Image Specification</h2> 840 A texture image is specified with the command:<br> 841 <br> 842 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glTexImage2D</span>(GLenum<span 843 style="font-style: italic;"> target</span>, GLint <span 844 style="font-style: italic;">level</span>, GLint <span 845 style="font-style: italic;">internalFormat,</span> GLsizei <span 846 style="font-style: italic;">width,</span> GLsizei <span 847 style="font-style: italic;">height,</span> GLint <span 848 style="font-style: italic;">border,</span> GLenum <span 849 style="font-style: italic;">format,</span> GLenum <span 850 style="font-style: italic;">type,</span> const GLvoid *<span 851 style="font-style: italic;">pixels</span> )<br> 852 </div> 853 <br> 854 <span style="font-style: italic;">target</span> must be GL_TEXTURE_2D. 855 <span style="font-style: italic;">level </span>indicates the 856 mipmap level for mipmap textures. <span style="font-style: italic;">internalFormat</span> 857 is a hint to indicate the preferred internal storage format for the 858 texture. <span style="font-style: italic;">width</span> and <span 859 style="font-style: italic;">height </span>indicate the image size in 860 pixels (or texels). <span style="font-style: italic;">border </span>must 861 be zero. <span style="font-style: italic;">format</span> and <span 862 style="font-style: italic;">type</span> describe the pixel format and 863 data type for the incoming image. <span style="font-style: italic;">pixels</span> 864 points to the incoming texture image. These parameters are 865 described in more detail below.<br> 866 <br> 867 <h3>5.1.1 Texture Image Size and Mipmaps</h3> 868 <h3><span style="font-style: italic;"></span></h3> 869 Texture images must have dimensions (width and height) that are powers 870 of two. For example: 256 x 256, 32 x 1024, 1 x 8, etc. That is, it 871 must be the case that <span style="font-style: italic;">width </span>= 872 2<sup>n</sup> and <span style="font-style: italic;">height</span> = 2<sup>m</sup> 873 for some positive integers n and m.<br> 874 <br> 875 Mipmapping is a method of antialiasing or filtering textures to improve 876 their appearance. A mipmap is a set of images consisting of a base 877 image and a set of filtered, reduced-resolution images. If the 878 base image (<span style="font-style: italic;">level</span>=0) is of 879 width 2<sup>n</sup> and height 2<sup>m</sup> then the level 1 image must 880 be of width 2<sup>n-1</sup> and height 2<sup>m-1</sup>. Each mipmap 881 level is half the width and height of the previous level, or at least 882 one. The last mipmap level has a width and height of one.<br> 883 <br> 884 The following is an example of a mipmap's image levels:<br> 885 <br> 886 <table cellpadding="2" cellspacing="2" border="1" 887 style="text-align: left; width: 50%; margin-left: auto; margin-right: auto;"> 888 <tbody> 889 <tr> 890 <td style="vertical-align: top;">mipmap level<br> 891 </td> 892 <td style="vertical-align: top;">width<br> 893 </td> 894 <td style="vertical-align: top;">height<br> 895 </td> 896 </tr> 897 <tr> 898 <td style="vertical-align: top;">0<br> 899 </td> 900 <td style="vertical-align: top;">256<br> 901 </td> 902 <td style="vertical-align: top;">64<br> 903 </td> 904 </tr> 905 <tr> 906 <td style="vertical-align: top;">1<br> 907 </td> 908 <td style="vertical-align: top;">128<br> 909 </td> 910 <td style="vertical-align: top;">32<br> 911 </td> 912 </tr> 913 <tr> 914 <td style="vertical-align: top;">2<br> 915 </td> 916 <td style="vertical-align: top;">64<br> 917 </td> 918 <td style="vertical-align: top;">16<br> 919 </td> 920 </tr> 921 <tr> 922 <td style="vertical-align: top;">3<br> 923 </td> 924 <td style="vertical-align: top;">32<br> 925 </td> 926 <td style="vertical-align: top;">8<br> 927 </td> 928 </tr> 929 <tr> 930 <td style="vertical-align: top;">4<br> 931 </td> 932 <td style="vertical-align: top;">16<br> 933 </td> 934 <td style="vertical-align: top;">4<br> 935 </td> 936 </tr> 937 <tr> 938 <td style="vertical-align: top;">5<br> 939 </td> 940 <td style="vertical-align: top;">8<br> 941 </td> 942 <td style="vertical-align: top;">2<br> 943 </td> 944 </tr> 945 <tr> 946 <td style="vertical-align: top;">6<br> 947 </td> 948 <td style="vertical-align: top;">4<br> 949 </td> 950 <td style="vertical-align: top;">1<br> 951 </td> 952 </tr> 953 <tr> 954 <td style="vertical-align: top;">7<br> 955 </td> 956 <td style="vertical-align: top;">2<br> 957 </td> 958 <td style="vertical-align: top;">1<br> 959 </td> 960 </tr> 961 <tr> 962 <td style="vertical-align: top;">8<br> 963 </td> 964 <td style="vertical-align: top;">1<br> 965 </td> 966 <td style="vertical-align: top;">1<br> 967 </td> 968 </tr> 969 </tbody> 970 </table> 971 <br> 972 If the <span style="font-style: italic;">width</span> or <span 973 style="font-style: italic;">height</span> parameters are not powers of 974 two, the error GL_INVALID_VALUE is raised. If the image levels in 975 a mipmap do not satisfy the restrictions listed above the texture is 976 considered to be <span style="font-style: italic;">inconsistent</span> 977 and the system will behave as if the texturing is disabled.<br> 978 <br> 979 <h3>5.1.2 Texture Image Formats and Unpacking</h3> 980 The <span style="font-weight: bold;">glTexImage2D</span> command's <span 981 style="font-style: italic;"><span style="font-weight: bold;"></span></span><span 982 style="font-style: italic;">format</span> and <span 983 style="font-style: italic;">type</span> parameters describe the format 984 of the incoming texture image. Accepted values for <span 985 style="font-style: italic;">format</span> are GL_INTENSITY, GL_RGB and 986 GL_RGBA. The <span style="font-style: italic;">type</span> 987 parameter must be GL_UNSIGNED_BYTE. Pixel component values are 988 thus in the range 0 through 255.<br> 989 <br> 990 If <span style="font-style: italic;">format</span> is GL_INTENSITY then 991 the image has one byte per pixel which specifies the pixel's red, green, 992 blue and alpha values.<span style="font-style: italic;"></span><br> 993 <br> 994 If <span style="font-style: italic;">format</span> is GL_RGB then the 995 image has three bytes per pixel which specify the pixel's red, green and 996 blue values (in that order). The alpha value defaults to 255.<br> 997 <br> 998 If <span style="font-style: italic;">format</span> is GL_RGBA then the 999 image has four bytes per pixel which specify the pixel's red, green, 1000 blue and alpha values (in that order).<br> 1001 <br> 1002 The command<br> 1003 <br> 1004 <div style="margin-left: 40px;">void<span style="font-weight: bold;"> 1005 glPixelStorei</span>(GLenum <span style="font-style: italic;">pname</span>, 1006 GLint <span style="font-style: italic;">value</span>)<br> 1007 </div> 1008 <br> 1009 controls the unpacking of texture image data from client memory. <span 1010 style="font-style: italic;">pname</span> may be GL_UNPACK_ROW_LENGTH to 1011 indicate the stride, in pixels, between subsequent rows of the image in 1012 client memory. If GL_UNPACK_ROW_LENGTH is zero (the default) then 1013 the <span style="font-style: italic;">width</span> parameter to <span 1014 style="font-weight: bold;">glTexImage2D </span>determines the stride.<span 1015 style="font-style: italic;"></span><br> 1016 <br> 1017 <h3>5.1.3 Internal Texture Format</h3> 1018 <span style="font-weight: bold;">glTexImage2D<span 1019 style="font-style: italic;"> </span></span>converts the incoming 1020 texture image to one of the supported internal texture formats.<br> 1021 <br> 1022 The <span style="font-style: italic;">internalFormat</span> parameter 1023 indicates the desired internal format for the texture and may be either 1024 GL_INTENSITY8, GL_RGB5 or GL_RGBA8.<br> 1025 <br> 1026 If <span style="font-style: italic;">internalFormat</span> is 1027 GL_INTENSITY8 then the texture has one byte per texel (texture element) 1028 which indicates the texel's intensity (or brightness). The 1029 intensity is obtained from the incoming image's red channel.<br> 1030 <br> 1031 If <span style="font-style: italic;">internalFormat</span> is GL_RGB5 1032 then the texture is stored with two bytes per texel: 5 bits per 1033 red value, 5 bits per green value and 5 bits per blue value.<br> 1034 <br> 1035 If <span style="font-style: italic;">internalFormat </span>is 1036 GL_RGBA8 then the texture is stored with four bytes per texel: 8 1037 bits for each of the red, green, blue and alpha values.<br> 1038 <br> 1039 The internal format is also significant to texture application (see 1040 section 5.4).<br> 1041 <br> 1042 <h2>5.2 Texture Coordinates</h2> 1043 Texture coordinates control the mapping from local polygon space to 1044 texture image space. Texture coordinates are set for each vertex 1045 with the <span style="font-weight: bold;">glTexCoord</span> commands. 1046 During line and polygon rasterization the vertex's texture 1047 coordinates are interpolated across the primitive to produce a texture 1048 coordinate for each fragment. The fragment texture coordinates are 1049 used to sample the current texture image.<br> 1050 <br> 1051 Texture coordinates are normally in the range [0, 1]. Values 1052 outside that range are processed according to the <span 1053 style="font-style: italic;">texture wrap mode</span>. The 1054 texture wrap mode is set with the command<br> 1055 <br> 1056 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glTexParameteri</span>(GLenum<span 1057 style="font-style: italic;"> target</span>, GLenum <span 1058 style="font-style: italic;">pname</span>, GLint <span 1059 style="font-style: italic;">value</span>)<br> 1060 <br> 1061 </div> 1062 <span style="font-style: italic;">target</span> must be GL_TEXTURE_2D. 1063 If <span style="font-style: italic;">pname</span> is 1064 GL_TEXTURE_WRAP_S or GL_TEXTURE_WRAP_T then <span 1065 style="font-style: italic;">value</span> must be either 1066 GL_CLAMP_TO_EDGE or GL_REPEAT.<br> 1067 <br> 1068 For GL_CLAMP_TO_EDGE, texture coordinates are effectively clamped to 1069 the interval [0, 1].<br> 1070 <br> 1071 For GL_REPEAT, the integer part of texture coordinates is ignored; only 1072 the fractional part of the texture coordinates is used. This 1073 allows texture images to repeated or tiled across an object.<br> 1074 <br> 1075 <h2>5.3 Texture Sampling</h2> 1076 Texture sampling is the process of using texture coordinates to extract 1077 a color from the texture image. Multiple, weighted samples may be 1078 taken from the texture and combined during the filtering step.<br> 1079 <br> 1080 During texture coordinate interpolation a <span 1081 style="font-style: italic;">level of detail</span> value (lambda) is 1082 computed for each fragment. For a mipmapped texture, lambda 1083 determines which level (or levels) of the mipmap will be sampled to 1084 obtain the texture color.<br> 1085 <br> 1086 If lambda indicates that multiple texels map to a single screen pixel, 1087 then the texture <span style="font-style: italic;">minification</span> 1088 filter will be used. Otherwise, if lambda indicates that a single 1089 texel maps to multiple screen pixels, then the texture <span 1090 style="font-style: italic;">magnification</span> filter will be used.<br> 1091 <span style="font-weight: bold;"></span><span 1092 style="font-style: italic;"></span><br> 1093 <h3>5.3.1 Texture Minification</h3> 1094 The texture minification filter is set with the <span 1095 style="font-weight: bold;">glTexParameteri </span><span 1096 style="font-style: italic;"></span><span style="font-weight: bold;"></span><span 1097 style="font-style: italic;"></span> command by setting <span 1098 style="font-style: italic;">target</span> to GL_TEXTURE_2D, setting <span 1099 style="font-style: italic;">pname</span> to GL_TEXTURE_MIN_FILTER and 1100 setting <span style="font-style: italic;">value</span> to GL_NEAREST, 1101 GL_LINEAR, GL_NEAREST_MIPMAP_NEAREST, 1102 GL_NEAREST_MIPMAP_LINEAR, GL_LINEAR_MIPMAP_NEAREST or 1103 GL_LINEAR_MIPMAP_LINEAR.<br> 1104 <br> 1105 GL_NEAREST samples the texel nearest the texture coordinate in the 1106 level 0 texture image.<br> 1107 <br> 1108 GL_LINEAR samples the four texels around the texture coordinate in the 1109 level 0 texture image. The four texels are linearly weighted to 1110 compute the final texel value.<br> 1111 <br> 1112 GL_NEAREST_MIPMAP_NEAREST samples the texel nearest the texture 1113 coordinate in the level N texture image. N is the level of detail 1114 and is computed by the partial derivatives of the texture coordinates 1115 with respect to the window coordinates.<br> 1116 <br> 1117 GL_NEAREST_MIPMAP_LINEAR samples two texels nearest the texture 1118 coordinates in the level N and N+1 texture images. The two texels 1119 are linearly weighted to compute the final texel value. N is the 1120 level of detail and is computed by the partial derivatives of the 1121 texture coordinates with respect to the window coordinates.<br> 1122 <br> 1123 GL_LINEAR_MIPMAP_NEAREST samples four texels around the texture 1124 coordinate in the level N texture image. The four texels are 1125 linearly weighted to compute the final texel value. N is the level 1126 of detail and is computed by the partial derivatives of the texture 1127 coordinates with respect to the window coordinates.<br> 1128 <br> 1129 GL_LINEAR_MIPMAP_LINEAR samples four texels around the texture 1130 coordinate in the level N texture image and four texels around the 1131 texture coordinate in the level N+1 texture image. The eight 1132 texels are linearly weighted to compute the final texel value. N 1133 is the level of detail and is computed by the partial derivatives of the 1134 texture coordinates with respect to the window coordinates.<br> 1135 <br> 1136 Filter modes other than GL_LINEAR and GL_NEAREST requires that the 1137 texture have a complete set of mipmaps. If the mipmap is 1138 incomplete, it is as if texturing is disabled.<br> 1139 <br> 1140 <h3>5.3.2 Texture Magnification</h3> 1141 The texture magnification filter is set with the <span 1142 style="font-weight: bold;">glTexParameteri </span><span 1143 style="font-style: italic;"></span><span style="font-weight: bold;"></span>command 1144 by setting <span style="font-style: italic;">target</span> to 1145 GL_TEXTURE_2D, setting <span style="font-style: italic;">pname</span> to 1146 GL_TEXTURE_MAG_FILTER and setting <span style="font-style: italic;">value</span> 1147 to GL_NEAREST or GL_LINEAR.<br> 1148 <br> 1149 GL_NEAREST samples the texel nearest the texture coordinate in the 1150 level 0 texture image.<br> 1151 <br> 1152 GL_LINEAR samples the four texels around the texture coordinate in the 1153 level 0 texture image. The four texels are linearly weighted to 1154 compute the final texel value.<br> 1155 <br> 1156 <h2>5.4 Texture Application</h2> 1157 The sampled texture value is combined with the incoming fragment color 1158 to produce a new fragment color. The fragment and texture colors 1159 are combined according to the texture environment mode and the current 1160 texture's base internal format. The texture environment mode is 1161 set with the command<br> 1162 <br> 1163 <div style="margin-left: 40px;">void<span style="font-weight: bold;"> 1164 glTexEnvi</span>(GLenum <span style="font-style: italic;">target</span>, 1165 GLenum <span style="font-style: italic;">pname</span>, GLint <span 1166 style="font-style: italic;">value</span>)<br> 1167 </div> 1168 <br> 1169 <span style="font-style: italic;">target</span> must be GL_TEXTURE_ENV. 1170 If <span style="font-style: italic;">pname</span> is 1171 GL_TEXTURE_ENV_MODE then <span style="font-style: italic;">value</span> 1172 must be one of GL_REPLACE, GL_MODULATE, GL_DECAL, or GL_BLEND.<br> 1173 <br> 1174 There is also a <span style="font-style: italic;">texture environment 1175 color</span> that can factor into texture application. The texture 1176 environment color can be set with the command<br> 1177 <br> 1178 <div style="margin-left: 40px;">void<span style="font-weight: bold;"> 1179 glTexEnvfv</span>(GLenum <span style="font-style: italic;">target</span>, 1180 GLenum <span style="font-style: italic;">pname</span>, const GLfloat *<span 1181 style="font-style: italic;">value</span>)<br> 1182 </div> 1183 <span style="font-style: italic;"></span><br> 1184 <span style="font-style: italic;">target</span> must be GL_TEXTURE_ENV. 1185 If <span style="font-style: italic;">pname</span> is 1186 GL_TEXTURE_ENV_COLOR then <span style="font-style: italic;">value </span>must 1187 point to an array of four values which specify the red, green, blue, 1188 and alpha values of the texture environment color. The values are 1189 clamped to the range [0, 1]. The default color is (0, 0, 0, 0).<br> 1190 <span style="font-style: italic;"></span><br> 1191 The following table describes the arithmetic used for each combination 1192 of environment mode and base internal format. (Rf, Gf, Bf, Af) is 1193 the incoming fragment color. (Rt, Gt, Bt, At) is the sampled 1194 texture color. Lt is the sampled texture luminance. <span 1195 style="font-style: italic;"></span>'It' is the sampled texture 1196 intensity. (Rc, Gc, Bc, Ac) is the texture environment color. 1197 (Rv, Gv, Bv, Av) is the resulting value.<br> 1198 <br> 1199 <br> 1200 <table cellpadding="2" cellspacing="2" border="1" 1201 style="text-align: left; width: 90%; margin-left: auto; margin-right: auto;"> 1202 <tbody> 1203 <tr> 1204 <td style="vertical-align: top;">Base Internal Format<br> 1205 </td> 1206 <td style="vertical-align: top;">GL_REPLACE<br> 1207 </td> 1208 <td style="vertical-align: top;">GL_MODULATE<br> 1209 </td> 1210 <td style="vertical-align: top;">GL_DECAL<br> 1211 </td> 1212 <td style="vertical-align: top;">GL_BLEND<br> 1213 </td> 1214 </tr> 1215 <tr> 1216 <td style="vertical-align: top;">GL_INTENSITY<br> 1217 </td> 1218 <td style="vertical-align: top;">Rv = It<br> 1219 Gv = It<br> 1220 Bv = It<br> 1221 Bf = It<br> 1222 </td> 1223 <td style="vertical-align: top;">Rv = Rf * It<br> 1224 Gv = Gf * It<br> 1225 Bv = Bf * It<br> 1226 Av = Af * It</td> 1227 <td style="vertical-align: top;">undefined<br> 1228 </td> 1229 <td style="vertical-align: top;">Rv = Rf*(1-It) + Rc*It<br> 1230 Gv = Gf*(1-It) + Gc*It<br> 1231 Bv = Bf*(1-It) + Bc*It<br> 1232 Av = Af*(1-It) + Ac*It</td> 1233 </tr> 1234 <tr> 1235 <td style="vertical-align: top;">GL_RGB<br> 1236 </td> 1237 <td style="vertical-align: top;">Rv = Rt<br> 1238 Gv = Gt<br> 1239 Bv = Bt<br> 1240 Av = Af<br> 1241 </td> 1242 <td style="vertical-align: top;">Rv = Rf * Rt<br> 1243 Gv = Gf * Gt<br> 1244 Bv = Bf * Bt<br> 1245 Av = Af<br> 1246 </td> 1247 <td style="vertical-align: top;">Rv = Rt<br> 1248 Gv = Gt<br> 1249 Bv = Bt<br> 1250 Av = Af</td> 1251 <td style="vertical-align: top;">Rv = Rf*(1-Rt) + Rc*Rt<br> 1252 Gv = Gf*(1-Gt) + Gc*Gt<br> 1253 Bv = Bf*(1-Bt) + Bc*Bt<br> 1254 Av = Af</td> 1255 </tr> 1256 <tr> 1257 <td style="vertical-align: top;">GL_RGBA<br> 1258 </td> 1259 <td style="vertical-align: top;">Rv = Rt<br> 1260 Gv = Gt<br> 1261 Bv = Bt<br> 1262 Av = At<br> 1263 </td> 1264 <td style="vertical-align: top;">Rv = Rf * Rt<br> 1265 Gv = Gf * Gt<br> 1266 Bv = Bf * Bt<br> 1267 Av = Af * At</td> 1268 <td style="vertical-align: top;">Rv = Rf*(1-At) + Rt*At<br> 1269 Gv = Gf*(1-At) + Gt*At<br> 1270 Bv = Bf*(1-At) + Bt*At<br> 1271 Av = Af<br> 1272 </td> 1273 <td style="vertical-align: top;">Rv = Rf*(1-Rt) + Rc*Rt<br> 1274 Gv = Gf*(1-Gt) + Gc*Gt<br> 1275 Bv = Bf*(1-Bt) + Bc*Bt<br> 1276 Av = Af*At</td> 1277 </tr> 1278 </tbody> 1279 </table> 1280 <br> 1281 <br> 1282 <br> 1283 <h2>5.5 Texture Objects</h2> 1284 Texture objects encapsulate a set of texture images (mipmap) and 1285 related state into a named object. This facilitates use of 1286 multiple textures in an application. Texture objects are named 1287 with GLuints (unsigned integers). There is a default texture 1288 object with the name/identifier zero which can never be deleted.<br> 1289 <br> 1290 <h3>5.5.1 Creating Texture Objects</h3> 1291 A texture object is created by binding a new GLuint identifier to the 1292 GL_TEXTURE_2D target with the command:<br> 1293 <br> 1294 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glBindTexture</span>(GLenum<span 1295 style="font-style: italic;"> target</span>, GLuint <span 1296 style="font-style: italic;">textureID</span>)<br> 1297 </div> 1298 <br> 1299 <span style="font-style: italic;">target</span> must be GL_TEXTURE_2D. 1300 <span style="font-style: italic;">textureID</span> may be any 1301 unsigned integer. If <span style="font-style: italic;">textureID</span> 1302 does not name an existing texture object, a new texture object with that 1303 ID will be created, initialized to the default state. Whether the 1304 ID is new or existed previously, that named texture object is bound as 1305 the <span style="font-style: italic;">current texture object</span>. 1306 Subsequent <span style="font-weight: bold;">glTexParameter </span>and<span 1307 style="font-weight: bold;">glTexImage2D<span 1308 style="font-style: italic;"> </span></span>calls will effect the 1309 current texture object.<br> 1310 <span style="font-style: italic;"></span><span 1311 style="font-weight: bold;"><span style="font-style: italic;"> </span></span><br> 1312 <h3>5.5.2 Deleting Texture Objects</h3> 1313 One or more texture objects may be deleted with the command:<br> 1314 <br> 1315 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glDeleteTextures</span>(GLsizei<span 1316 style="font-style: italic;">n</span>, const GLuint *<span 1317 style="font-style: italic;">textureIDs</span>)<br> 1318 </div> 1319 <br> 1320 <span style="font-style: italic;">textureIDs</span> is an array of <span 1321 style="font-style: italic;">n</span> texture IDs. The named 1322 texture objects will be deleted. If the current texture object is 1323 deleted the default texture object (number 0) will be bound as the 1324 current texture object.<br> 1325 <br> 1326 <h3>5.5.3 Allocating Texture Object Identifiers</h3> 1327 A list of new, unused texture IDs can be obtained by calling the command<br> 1328 <br> 1329 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glGenTextures</span>(GLsizei<span 1330 style="font-style: italic;"> n</span>, GLuint *<span 1331 style="font-style: italic;">textureIDs</span>)<br> 1332 </div> 1333 <br> 1334 An array of <span style="font-style: italic;">n</span> unused texture 1335 IDs will be returned in the <span style="font-style: italic;">textureIDs</span> 1336 array.<br> 1337 <br> 1338 <br> 1339 <h1>6. Per-fragment Operations</h1> 1340 The fragments produced by rasterization are subjected to a number of 1341 operations which either modify the fragment or test the fragment 1342 (discarding the fragment if the test fails.) This chapter 1343 describes the per-fragment operations. They are presented in the 1344 order in which they're performed. If a fragment fails a test it is 1345 discarded and not subjected to subsequent tests or modifications.<br> 1346 <br> 1347 <h2>6.1 Scissor Test</h2> 1348 The scissor test limits rendering to a 2-D rectangular region of the 1349 framebuffer. The command<br> 1350 <br> 1351 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glScissor</span>(GLint<span 1352 style="font-style: italic;">x</span>, GLint <span 1353 style="font-style: italic;">y</span>, GLsizei <span 1354 style="font-style: italic;">width</span>, GLsizei<span 1355 style="font-style: italic;"> height</span>)<br> 1356 </div> 1357 <br> 1358 defines a clipping region with the lower-left corner at (<span 1359 style="font-style: italic;">x, y</span>) and the given <span 1360 style="font-style: italic;">width</span> and <span 1361 style="font-style: italic;">height</span>. The scissor test is 1362 enabled and disabled with the command <span style="font-weight: bold;">glEnable</span>(GL_SCISSOR_TEST) 1363 and <span style="font-weight: bold;">glDisable</span>(GL_SCISSOR_TEST).<br> 1364 <br> 1365 If the incoming fragment's position is (x<sub>f</sub>, y<sub>f</sub>) 1366 then the fragment will pass the test if <span 1367 style="font-style: italic;">x</span> <= x<sub>f</sub> < <span 1368 style="font-style: italic;">x</span> + <span 1369 style="font-style: italic;">width</span> and <span 1370 style="font-style: italic;">y</span> <= y<sub>f</sub> < <span 1371 style="font-style: italic;">y</span> + <span 1372 style="font-style: italic;">height. </span>Otherwise, the 1373 fragment is discarded.<br> 1374 <br> 1375 If <span style="font-style: italic;">width</span> or <span 1376 style="font-style: italic;">height</span> is less than zero the error 1377 GL_INVALID_VALUE is raised. The default scissor rectangle bounds 1378 are (0, 0, w, h) where w is the initial window width and h is the 1379 initial window height. The scissor test is disabled by default.<br> 1380 <br> 1381 <h2>6.2 Alpha Test</h2> 1382 The alpha test compares the fragment's alpha value against a reference 1383 value and discards the fragment if the comparison fails. The test 1384 is specified by the command<br> 1385 <br> 1386 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glAlphaFunc</span>(GLenum<span 1387 style="font-style: italic;">mode</span>, GLclampf <span 1388 style="font-style: italic;">reference</span>)<br> 1389 </div> 1390 <br> 1391 <span style="font-style: italic;">mode</span> specifies an inequality 1392 and <span style="font-style: italic;">reference</span> specifies a value 1393 to compare against. The following table lists all possible 1394 modes <span style="font-style: italic;"></span>and the 1395 corresponding test:<br> 1396 <br> 1397 <table cellpadding="2" cellspacing="2" border="1" 1398 style="text-align: left; width: 50%; margin-left: auto; margin-right: auto;"> 1399 <tbody> 1400 <tr> 1401 <td style="vertical-align: top;">Comparison mode<br> 1402 </td> 1403 <td style="vertical-align: top;">The test passes if<br> 1404 </td> 1405 </tr> 1406 <tr> 1407 <td style="vertical-align: top;">GL_LESS<br> 1408 </td> 1409 <td style="vertical-align: top;">alpha < <span 1410 style="font-style: italic;">reference</span><br> 1411 </td> 1412 </tr> 1413 <tr> 1414 <td style="vertical-align: top;">GL_LEQUAL<br> 1415 </td> 1416 <td style="vertical-align: top;">alpha <= <span 1417 style="font-style: italic;">reference</span></td> 1418 </tr> 1419 <tr> 1420 <td style="vertical-align: top;">GL_GREATER<br> 1421 </td> 1422 <td style="vertical-align: top;">alpha > <span 1423 style="font-style: italic;">reference</span></td> 1424 </tr> 1425 <tr> 1426 <td style="vertical-align: top;">GL_GEQUAL<br> 1427 </td> 1428 <td style="vertical-align: top;">alpha >= <span 1429 style="font-style: italic;">reference</span></td> 1430 </tr> 1431 <tr> 1432 <td style="vertical-align: top;">GL_EQUAL<br> 1433 </td> 1434 <td style="vertical-align: top;">alpha == <span 1435 style="font-style: italic;">reference</span></td> 1436 </tr> 1437 <tr> 1438 <td style="vertical-align: top;">GL_NOTEQUAL<br> 1439 </td> 1440 <td style="vertical-align: top;">alpha != <span 1441 style="font-style: italic;">reference</span></td> 1442 </tr> 1443 <tr> 1444 <td style="vertical-align: top;">GL_NEVER<br> 1445 </td> 1446 <td style="vertical-align: top;">never pass<br> 1447 </td> 1448 </tr> 1449 <tr> 1450 <td style="vertical-align: top;">GL_ALWAYS<br> 1451 </td> 1452 <td style="vertical-align: top;">always passes<br> 1453 </td> 1454 </tr> 1455 </tbody> 1456 </table> 1457 <br> 1458 The <span style="font-style: italic;">reference</span> parameter is 1459 clamped to the range [0, 1].<br> 1460 <br> 1461 The alpha test is enabled and disabled with the commands <span 1462 style="font-weight: bold;">glEnable</span>(GL_ALPHA_TEST) and <span 1463 style="font-weight: bold;">glDisable</span>(GL_ALPHA_TEST).<br> 1464 <br> 1465 The default mode is GL_ALWAYS and the default reference value is 0.<br> 1466 <br> 1467 <h2>6.3 Stencil Test</h2> 1468 The stencil buffer stores an N-bit integer value for each pixel in the 1469 frame buffer. The stencil test compares the stencil buffer value 1470 at the fragment's position to a reference value and possibly discards 1471 the fragment based on the outcome. Furthermore, the stencil buffer 1472 value may be updated or modified depending on the outcome. If 1473 there is no stencil buffer the stencil test is bypassed.<br> 1474 <br> 1475 Stenciling is controlled by the commands<br> 1476 <br> 1477 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glStencilFunc</span>(GLenum<span 1478 style="font-style: italic;">func</span>, GLint <span 1479 style="font-style: italic;">ref</span>, GLuint <span 1480 style="font-style: italic;">mask</span>)<br> 1481 void <span style="font-weight: bold;">glStencilOp</span>(GLenum <span 1482 style="font-style: italic;">stencilFail</span>, GLenum <span 1483 style="font-style: italic;">depthTestFail</span>, GLenum <span 1484 style="font-style: italic;">depthTestPass</span>)<br> 1485 </div> 1486 <br> 1487 The <span style="font-weight: bold;">glStencilFunc<span 1488 style="font-style: italic;"> </span></span>command controls the 1489 stencil test while <span style="font-weight: bold;">glStencilOp</span> 1490 command controls the how the stencil buffer is updated/modified after 1491 the test.<br> 1492 <br> 1493 <span style="font-style: italic;">ref</span> is clamped to the range [0, 1494 2<sup>N</sup>-1] where N is the number of bits per stencil value in the 1495 stencil buffer.<span style="font-style: italic;"></span><br> 1496 <br> 1497 The following table lists all possible values for the <span 1498 style="font-style: italic;">func</span> parameter and when the stencil 1499 test will pass. Both the stencil buffer value and the stencil 1500 reference value are bit-wise ANDed with the <span 1501 style="font-style: italic;">mask</span> parameter before the test.<br> 1502 <br> 1503 <span style="font-style: italic;"></span><span 1504 style="font-style: italic;"></span><span style="font-style: italic;"></span> 1505 <table 1506 style="text-align: left; margin-left: auto; margin-right: auto; width: 70%;" 1507 border="1" cellspacing="2" cellpadding="2"> 1508 <tbody> 1509 <tr> 1510 <td style="vertical-align: top;">Stencil <span 1511 style="font-style: italic;">func</span> value<br> 1512 </td> 1513 <td style="vertical-align: top;">Stencil test passes if<br> 1514 </td> 1515 </tr> 1516 <tr> 1517 <td style="vertical-align: top;">GL_LESS<br> 1518 </td> 1519 <td style="vertical-align: top;"><span style="font-style: italic;">(ref</span>&<span 1520 style="font-style: italic;">mask)</span> < (stencil buffer value 1521 & <span style="font-style: italic;">mask)</span><br> 1522 </td> 1523 </tr> 1524 <tr> 1525 <td style="vertical-align: top;">GL_LEQUAL<br> 1526 </td> 1527 <td style="vertical-align: top;"><span style="font-style: italic;">(ref</span> 1528 & <span style="font-style: italic;">mask) </span><= (stencil 1529 buffer value & <span style="font-style: italic;">mask)</span></td> 1530 </tr> 1531 <tr> 1532 <td style="vertical-align: top;">GL_GREATER<br> 1533 </td> 1534 <td style="vertical-align: top;"><span style="font-style: italic;">(ref</span> 1535 & <span style="font-style: italic;">mask) </span>> (stencil 1536 buffer value & <span style="font-style: italic;">mask)</span></td> 1537 </tr> 1538 <tr> 1539 <td style="vertical-align: top;">GL_GEQUAL<br> 1540 </td> 1541 <td style="vertical-align: top;"><span style="font-style: italic;">(ref</span> 1542 & <span style="font-style: italic;">mask) </span>>= (stencil 1543 buffer value & <span style="font-style: italic;">mask)</span></td> 1544 </tr> 1545 <tr> 1546 <td style="vertical-align: top;">GL_EQUAL<br> 1547 </td> 1548 <td style="vertical-align: top;"><span style="font-style: italic;">(ref</span> 1549 & <span style="font-style: italic;">mask) </span>== (stencil 1550 buffer value & <span style="font-style: italic;">mask)</span></td> 1551 </tr> 1552 <tr> 1553 <td style="vertical-align: top;">GL_NOTEQUAL<br> 1554 </td> 1555 <td style="vertical-align: top;"><span style="font-style: italic;">(ref</span> 1556 & <span style="font-style: italic;">mask) </span>!= (stencil 1557 buffer value & <span style="font-style: italic;">mask)</span></td> 1558 </tr> 1559 <tr> 1560 <td style="vertical-align: top;">GL_NEVER<br> 1561 </td> 1562 <td style="vertical-align: top;">never passes<br> 1563 </td> 1564 </tr> 1565 <tr> 1566 <td style="vertical-align: top;">GL_ALWAYS<br> 1567 </td> 1568 <td style="vertical-align: top;">always passes<br> 1569 </td> 1570 </tr> 1571 </tbody> 1572 </table> 1573 <br> 1574 <span style="font-style: italic;"></span><br> 1575 If the stencil test passes, the fragment is passed to the next 1576 per-fragment operation. Otherwise, if the stencil test fails, the 1577 value in the stencil buffer is updated according to the value of the <span 1578 style="font-style: italic;">stencilFail</span> parameter to <span 1579 style="font-weight: bold;">glStencilOp</span>.<br> 1580 <br> 1581 <table cellpadding="2" cellspacing="2" border="1" 1582 style="text-align: left; width: 70%; margin-left: auto; margin-right: auto;"> 1583 <tbody> 1584 <tr> 1585 <td style="vertical-align: top;"><span style="font-style: italic;">stencilFail</span> 1586 value<br> 1587 </td> 1588 <td style="vertical-align: top;">New stencil buffer value<br> 1589 </td> 1590 </tr> 1591 <tr> 1592 <td style="vertical-align: top;">GL_KEEP<br> 1593 </td> 1594 <td style="vertical-align: top;">originalValue<br> 1595 </td> 1596 </tr> 1597 <tr> 1598 <td style="vertical-align: top;">GL_ZERO<br> 1599 </td> 1600 <td style="vertical-align: top;">0<br> 1601 </td> 1602 </tr> 1603 <tr> 1604 <td style="vertical-align: top;">GL_INVERT<br> 1605 </td> 1606 <td style="vertical-align: top;">BitWiseInvert(originalValue) 1607 i.e. ~originalValue<br> 1608 </td> 1609 </tr> 1610 <tr> 1611 <td style="vertical-align: top;">GL_REPLACE<br> 1612 </td> 1613 <td style="vertical-align: top;"><span style="font-style: italic;">ref</span><br> 1614 </td> 1615 </tr> 1616 <tr> 1617 <td style="vertical-align: top;">GL_INCR<br> 1618 </td> 1619 <td style="vertical-align: top;">originalValue + 1, clamped to 1620 [0, 2<sup>N</sup>-1]</td> 1621 </tr> 1622 <tr> 1623 <td style="vertical-align: top;">GL_DECR<br> 1624 </td> 1625 <td style="vertical-align: top;">originalValue - 1, clamped to 1626 [0, 2<sup>N</sup>-1]</td> 1627 </tr> 1628 </tbody> 1629 </table> 1630 <span style="font-style: italic;"></span><span 1631 style="font-style: italic;"></span><br> 1632 <br> 1633 The <span style="font-style: italic;">depthTestFail</span> and <span 1634 style="font-style: italic;">depthTestPass</span> parameters to <span 1635 style="font-weight: bold;">glStencilOp</span> are ignored. Values 1636 for <span style="font-style: italic;">func</span> and <span 1637 style="font-style: italic;">stencilFail</span> other than those listed 1638 in the table will cause the error GL_INVALID_ENUM to be raised.<br> 1639 <br> 1640 The stencil test is enabled and disabled with the commands <span 1641 style="font-weight: bold;">glEnable</span>(GL_STENCIL_TEST) and <span 1642 style="font-weight: bold;">glDisable</span>(GL_STENCIL_TEST).<br> 1643 <br> 1644 The default stencil function is GL_ALWAYS. The default stencil 1645 reference value is 0. The default stencil mask is ~0. The 1646 default stencil fail operation is GL_KEEP.<br> 1647 <br> 1648 Values written into the stencil buffer are masked with the command<br> 1649 <br> 1650 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glStencilMask</span>(GLuint<span 1651 style="font-style: italic;">mask</span>)<br> 1652 </div> 1653 <br> 1654 Only the bits which are set in <span style="font-style: italic;">mask</span> 1655 will be modified in the stencil buffer when written to. If each 1656 stencil buffer value has N bits, only the least significant N bits of <span 1657 style="font-style: italic;">mask</span> are relevant. The default 1658 stencil mask is ~0.<br> 1659 <br> 1660 <h2>6.4 Blending and Logicop</h2> 1661 Blending or a logic operation combines the incoming fragment color with 1662 the destination frame buffer color according to a blending equation or 1663 bit-wise Boolean logical operation.<br> 1664 <br> 1665 Blending is enabled and disabled with the commands <span 1666 style="font-weight: bold;">glEnable</span>(GL_BLEND) and <span 1667 style="font-weight: bold;">glDisable</span>(GL_BLEND).<br> 1668 <br> 1669 The logic operation is enabled and disabled with the commands <span 1670 style="font-weight: bold;">glEnable</span>(GL_LOGIC_OP) and <span 1671 style="font-weight: bold;">glDisable</span>(GL_LOGIC_OP).<br> 1672 <br> 1673 If both blending and the logic operation are enabled, the logic 1674 operation has higher priority; blending is bypassed.<br> 1675 <br> 1676 <h3>6.4.1 Logic Op</h3> 1677 The command<br> 1678 <br> 1679 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glLogicop</span>(GLenum<span 1680 style="font-style: italic;">mode</span>)<br> 1681 <br> 1682 </div> 1683 Specifies the Boolean logic operation for combining the incoming 1684 fragment color with the destination frame buffer color. Both the 1685 incoming fragment color and destination frame buffer colors are 1686 interpreted as four-tuples of unsigned integer color components in the 1687 range [0, 2<sup>N</sup>-1] where N is the number of bits per color 1688 channel. N may not be the same for all color channels.<br> 1689 <br> 1690 The following table lists all values for <span 1691 style="font-style: italic;">mode</span> and the boolean arithmetic used 1692 to combine the incoming fragment color value (src)<span 1693 style="font-style: italic;"></span><span style="font-style: italic;"></span><span 1694 style="font-style: italic;"></span><span style="font-style: italic;"></span><span 1695 style="font-style: italic;"></span> with the destination framebuffer 1696 color value (dst). Standard ANSI C operators used.<br> 1697 <br> 1698 <table cellpadding="2" cellspacing="2" border="1" 1699 style="text-align: left; width: 50%; margin-left: auto; margin-right: auto;"> 1700 <tbody> 1701 <tr> 1702 <td style="vertical-align: top;">LogicOp <span 1703 style="font-style: italic;">mode</span><br> 1704 </td> 1705 <td style="vertical-align: top;">Resulting channel value<br> 1706 </td> 1707 </tr> 1708 <tr> 1709 <td style="vertical-align: top;">GL_CLEAR<br> 1710 </td> 1711 <td style="vertical-align: top;">0<br> 1712 </td> 1713 </tr> 1714 <tr> 1715 <td style="vertical-align: top;">GL_SET<br> 1716 </td> 1717 <td style="vertical-align: top;">~0<br> 1718 </td> 1719 </tr> 1720 <tr> 1721 <td style="vertical-align: top;">GL_COPY<br> 1722 </td> 1723 <td style="vertical-align: top;">src<br> 1724 </td> 1725 </tr> 1726 <tr> 1727 <td style="vertical-align: top;">GL_COPY_INVERTED<br> 1728 </td> 1729 <td style="vertical-align: top;">~s<br> 1730 </td> 1731 </tr> 1732 <tr> 1733 <td style="vertical-align: top;">GL_NOOP<br> 1734 </td> 1735 <td style="vertical-align: top;">dst<br> 1736 </td> 1737 </tr> 1738 <tr> 1739 <td style="vertical-align: top;">GL_INVERT<br> 1740 </td> 1741 <td style="vertical-align: top;">~dst<br> 1742 </td> 1743 </tr> 1744 <tr> 1745 <td style="vertical-align: top;">GL_AND<br> 1746 </td> 1747 <td style="vertical-align: top;">src & dst<br> 1748 </td> 1749 </tr> 1750 <tr> 1751 <td style="vertical-align: top;">GL_NAND<br> 1752 </td> 1753 <td style="vertical-align: top;">~(src & dst)<br> 1754 </td> 1755 </tr> 1756 <tr> 1757 <td style="vertical-align: top;">GL_AND_REVERSE<br> 1758 </td> 1759 <td style="vertical-align: top;">src & ~dst<br> 1760 </td> 1761 </tr> 1762 <tr> 1763 <td style="vertical-align: top;">GL_AND_INVERTED<br> 1764 </td> 1765 <td style="vertical-align: top;">~src & dst<br> 1766 </td> 1767 </tr> 1768 <tr> 1769 <td style="vertical-align: top;">GL_OR<br> 1770 </td> 1771 <td style="vertical-align: top;">src | dst<br> 1772 </td> 1773 </tr> 1774 <tr> 1775 <td style="vertical-align: top;">GL_NOR<br> 1776 </td> 1777 <td style="vertical-align: top;">~(src | dst)<br> 1778 </td> 1779 </tr> 1780 <tr> 1781 <td style="vertical-align: top;">GL_OR_REVERSE<br> 1782 </td> 1783 <td style="vertical-align: top;">src | ~dst<br> 1784 </td> 1785 </tr> 1786 <tr> 1787 <td style="vertical-align: top;">GL_OR_INVERTED<br> 1788 </td> 1789 <td style="vertical-align: top;">~src | dst<br> 1790 </td> 1791 </tr> 1792 <tr> 1793 <td style="vertical-align: top;">GL_XOR<br> 1794 </td> 1795 <td style="vertical-align: top;">src ^ dst<br> 1796 </td> 1797 </tr> 1798 <tr> 1799 <td style="vertical-align: top;">GL_EQUIV<br> 1800 </td> 1801 <td style="vertical-align: top;">~(src ^ dst)<br> 1802 </td> 1803 </tr> 1804 </tbody> 1805 </table> 1806 <br> 1807 The fragment's color is replaced by the result of the logic operation.<br> 1808 <br> 1809 Specifying any value for <span style="font-style: italic;">mode</span> 1810 other than those listed in the above table will cause the error 1811 GL_INVALID_ENUM to be raised.<br> 1812 <br> 1813 The default value for <span style="font-style: italic;">mode</span> is 1814 GL_COPY. The logic operation is disabled by default.<br> 1815 <br> 1816 <h3>6.4.2 Blending</h3> 1817 The command<br> 1818 <br> 1819 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glBlendFunc</span>(GLenum<span 1820 style="font-style: italic;">srcTerm</span>, GLenum <span 1821 style="font-style: italic;">dstTerm</span>)<br> 1822 </div> 1823 <br> 1824 specifies the terms of the blending equation. If Cf = (Rf, Gf, 1825 Bf, Af) is the incoming fragment color and Cb = (Rb, Gb, Bb, Ab) is the 1826 frame buffer color, then the resulting color Cv = (Rv, Gv, Bv, Av) is 1827 computed by:<br> 1828 <br> 1829 <div style="margin-left: 40px;">Cv = Cf * <span 1830 style="font-style: italic;">srcTerm</span> + Cb * <span 1831 style="font-style: italic;">dstTerm</span><br> 1832 <span style="font-style: italic;"></span></div> 1833 <span style="font-style: italic;"> </span><br> 1834 All possible values for <span style="font-style: italic;">srcTerm</span> 1835 and the corresponding arithmetic term are listed in the following table:<br> 1836 <br> 1837 <table cellpadding="2" cellspacing="2" border="1" 1838 style="text-align: left; width: 70%; margin-left: auto; margin-right: auto;"> 1839 <tbody> 1840 <tr> 1841 <td style="vertical-align: top;"><span style="font-style: italic;">srcTerm</span><br> 1842 </td> 1843 <td style="vertical-align: top;"><span style="font-style: italic;">srcTerm</span>Arithmetic<br> 1844 </td> 1845 </tr> 1846 <tr> 1847 <td style="vertical-align: top;">GL_ZERO<br> 1848 </td> 1849 <td style="vertical-align: top;">(0, 0, 0, 0)<br> 1850 </td> 1851 </tr> 1852 <tr> 1853 <td style="vertical-align: top;">GL_ONE<br> 1854 </td> 1855 <td style="vertical-align: top;">(1, 1, 1, 1)<br> 1856 </td> 1857 </tr> 1858 <tr> 1859 <td style="vertical-align: top;">GL_DST_COLOR<br> 1860 </td> 1861 <td style="vertical-align: top;">(Rb, Gb, Bb, Ab)<br> 1862 </td> 1863 </tr> 1864 <tr> 1865 <td style="vertical-align: top;">GL_ONE_MINUS_DST_COLOR<br> 1866 </td> 1867 <td style="vertical-align: top;">(1-Rb, 1-Gb, 1-Bb, 1-Ab)<br> 1868 </td> 1869 </tr> 1870 <tr> 1871 <td style="vertical-align: top;">GL_SRC_ALPHA<br> 1872 </td> 1873 <td style="vertical-align: top;">(Af, Af, Af, AF)<br> 1874 </td> 1875 </tr> 1876 <tr> 1877 <td style="vertical-align: top;">GL_ONE_MINUS_SRC_ALPHA<br> 1878 </td> 1879 <td style="vertical-align: top;">(1-Af, 1-Af, 1-Af, 1-Af)<br> 1880 </td> 1881 </tr> 1882 <tr> 1883 <td style="vertical-align: top;">GL_DST_ALPHA<br> 1884 </td> 1885 <td style="vertical-align: top;">(Ab, Ab, Ab, Ab)<br> 1886 </td> 1887 </tr> 1888 <tr> 1889 <td style="vertical-align: top;">GL_ONE_MINUS_DST_ALPHA<br> 1890 </td> 1891 <td style="vertical-align: top;">(1-Ab, 1-Ab, 1-Ab, 1-Ab)<br> 1892 </td> 1893 </tr> 1894 <tr> 1895 <td style="vertical-align: top;">GL_SRC_ALPHA_SATURATE<br> 1896 </td> 1897 <td style="vertical-align: top;">(m, m, m, 1) where m = MIN(Af, 1898 1-Ab)<br> 1899 </td> 1900 </tr> 1901 </tbody> 1902 </table> 1903 <br> 1904 All possible values for <span style="font-style: italic;">srcTerm</span> 1905 and the corresponding arithmetic term are listed in the following table:<br> 1906 <br> 1907 <table cellpadding="2" cellspacing="2" border="1" 1908 style="text-align: left; width: 70%; margin-left: auto; margin-right: auto;"> 1909 <tbody> 1910 <tr> 1911 <td style="vertical-align: top;"><span style="font-style: italic;">dstTerm</span><br> 1912 </td> 1913 <td style="vertical-align: top;"><span style="font-style: italic;">dstTerm</span>Arithmetic<br> 1914 </td> 1915 </tr> 1916 <tr> 1917 <td style="vertical-align: top;">GL_ZERO<br> 1918 </td> 1919 <td style="vertical-align: top;">(0, 0, 0, 0)<br> 1920 </td> 1921 </tr> 1922 <tr> 1923 <td style="vertical-align: top;">GL_ONE<br> 1924 </td> 1925 <td style="vertical-align: top;">(1, 1, 1, 1)<br> 1926 </td> 1927 </tr> 1928 <tr> 1929 <td style="vertical-align: top;">GL_SRC_COLOR<br> 1930 </td> 1931 <td style="vertical-align: top;">(Rf, Gf, Bf, Af)<br> 1932 </td> 1933 </tr> 1934 <tr> 1935 <td style="vertical-align: top;">GL_ONE_MINUS_SRC_COLOR<br> 1936 </td> 1937 <td style="vertical-align: top;">(1-Rf, 1-Gf, 1-Bf, 1-Af)<br> 1938 </td> 1939 </tr> 1940 <tr> 1941 <td style="vertical-align: top;">GL_SRC_ALPHA<br> 1942 </td> 1943 <td style="vertical-align: top;">(Af, Af, Af, AF)<br> 1944 </td> 1945 </tr> 1946 <tr> 1947 <td style="vertical-align: top;">GL_ONE_MINUS_SRC_ALPHA<br> 1948 </td> 1949 <td style="vertical-align: top;">(1-Af, 1-Af, 1-Af, 1-Af)<br> 1950 </td> 1951 </tr> 1952 <tr> 1953 <td style="vertical-align: top;">GL_DST_ALPHA<br> 1954 </td> 1955 <td style="vertical-align: top;">(Ab, Ab, Ab, Ab)<br> 1956 </td> 1957 </tr> 1958 <tr> 1959 <td style="vertical-align: top;">GL_ONE_MINUS_DST_ALPHA<br> 1960 </td> 1961 <td style="vertical-align: top;">(1-Ab, 1-Ab, 1-Ab, 1-Ab)<br> 1962 </td> 1963 </tr> 1964 </tbody> 1965 </table> 1966 <br> 1967 The fragment's color is replaced by the result of the blending equation.<br> 1968 <br> 1969 Values for <span style="font-style: italic;">srcTerm</span> and <span 1970 style="font-style: italic;">dstTerm</span> other than those listed in 1971 the table will cause the error GL_INVALID_ENUM to be raised.<br> 1972 <br> 1973 The default value for <span style="font-style: italic;">srcTerm</span> 1974 is GL_ONE. The default value for <span style="font-style: italic;">dstTerm</span> 1975 is GL_ZERO. Blending is disabled by default.<br> 1976 <br> 1977 <h2>6.5 Color Mask</h2> 1978 The final fragment color is written into the current color buffer at 1979 the end of the per-fragment operations. Normally, all color 1980 channels in the frame buffer are replaced with the final fragment color. 1981 However, the command<br> 1982 <br> 1983 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glColorMask</span>(GLboolean<span 1984 style="font-style: italic;">redMask</span>, GLboolean <span 1985 style="font-style: italic;">greenMask</span>, GLboolean <span 1986 style="font-style: italic;">blueMask</span>, GLboolean <span 1987 style="font-style: italic;">alphaMask</span>)<br> 1988 </div> 1989 <br> 1990 allows selective writing to individual color channels. If <span 1991 style="font-style: italic;">redMask</span> is GL_TRUE then writing to 1992 the red color channel is enabled, otherwise it's disabled. 1993 Similarly, the green, blue and alpha channels can also be masked.<br> 1994 <br> 1995 Initially all four mask values are GL_TRUE.<br> 1996 <br> 1997 Color masking is not enabled/disabled with the <span 1998 style="font-weight: bold;">glEnable</span>/<span 1999 style="font-weight: bold;">glDisable</span> commands.<br> 2000 <br> 2001 <h1>7. Frame Buffer Operations</h1> 2002 The frame buffer is considered to be a two-dimensional array of pixels. 2003 The frame buffer is also organized into layers or logical buffers. 2004 There may be a front color buffer, back color buffer and stencil 2005 buffer. A double-buffered frame buffer has both a front color 2006 buffer and back color buffer. A single-buffered framebuffer only 2007 has a front color buffer. Each pixel in a color buffer has a red, 2008 green and blue value and an optional alpha value.<br> 2009 <br> 2010 <h2>7.1 Clearing Buffers</h2> 2011 Buffers are cleared (set to uniform values) with the command<br> 2012 <br> 2013 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glClear</span>(GLbitfield<span 2014 style="font-style: italic;">buffers</span>)<br> 2015 </div> 2016 <br> 2017 <span style="font-style: italic;">buffers</span> is a bitmask for which 2018 the value may be the bitwise-OR of the values GL_COLOR_BUFFER_BIT and 2019 GL_STENCIL_BUFFER_BIT. If the GL_COLOR_BUFFER_BIT bit is 2020 specified, the current color buffer will be cleared. If the 2021 GL_STENCIL_BUFFER_BIT bit is specified, the stencil buffer will be 2022 cleared.<br> 2023 <br> 2024 The current color buffer is specified with the command<br> 2025 <br> 2026 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glDrawBuffer</span>(GLenum<span 2027 style="font-style: italic;"> buffer</span>)<br> 2028 </div> 2029 <br> 2030 <span style="font-style: italic;">buffer</span> may be either GL_FRONT, 2031 GL_BACK or GL_NONE. GL_FRONT indicates that the front color buffer 2032 will be modified by <span style="font-weight: bold;">glClear</span> and 2033 any drawing command. GL_BACK indicates that the back color buffer 2034 will be modified by <span style="font-weight: bold;">glClear</span> and 2035 any drawing command. GL_NONE indicates that neither color buffer 2036 will be modified by <span style="font-weight: bold;">glClear</span> or 2037 any drawing command. GL_BACK is only valid for double-buffered 2038 frame buffers.<br> 2039 <br> 2040 The current scissor rectangle, set by the <span 2041 style="font-weight: bold;">glScissor</span> command, effects <span 2042 style="font-weight: bold;">glClear</span><span 2043 style="font-style: italic;">,</span><span style="font-style: italic;"> </span>limiting 2044 the clear to the scissor rectangle, if it's enabled. Furthermore, <span 2045 style="font-weight: bold;"></span>only the color channels enabled by <span 2046 style="font-weight: bold;">glColorMask</span> will be effected by <span 2047 style="font-weight: bold;">glClear</span>(GL_COLOR_BUFFER_BIT). 2048 Likewise, only the stencil bits enabled by <span 2049 style="font-weight: bold;">glStencilMask</span> will be effected by <span 2050 style="font-weight: bold;">glClear</span>(GL_STENCIL_BUFFER_BIT).<br> 2051 <br> 2052 The current clear color is set with the command<br> 2053 <br> 2054 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glClearColor</span>(GLclampf<span 2055 style="font-style: italic;">red</span>, GLclampf <span 2056 style="font-style: italic;">green</span>, GLclampf <span 2057 style="font-style: italic;">blue</span>, GLclampf <span 2058 style="font-style: italic;">alpha</span>)<br> 2059 </div> 2060 <br> 2061 Subsequent calls to <span style="font-weight: bold;">glClear</span> 2062 will use the color (<span style="font-style: italic;">red, green, blue, 2063 alpha</span>) to clear the front or back color buffers.<br> 2064 <span style="font-style: italic;"></span><br> 2065 The current stencil clear value is set with the command<br> 2066 <br> 2067 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glClearStencil</span>(GLint<span 2068 style="font-style: italic;">clearValue</span>)<br> 2069 </div> 2070 <br> 2071 If the stencil buffer is N bits deep, the least significant N bits of <span 2072 style="font-style: italic;">clearValue</span> will be used to clear the 2073 stencil buffer.<br> 2074 <br> 2075 <br> 2076 <h1>8. Other Features</h1> 2077 <h2>8.1 Frame Buffer Readback</h2> 2078 A rectangular region of pixels can be read from the frame buffer and 2079 placed in client memory with the command<br> 2080 <br> 2081 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glReadPixels</span>(GLint<span 2082 style="font-style: italic;">x</span>, GLint <span 2083 style="font-style: italic;">y</span>, GLsizei <span 2084 style="font-style: italic;">width</span>, GLsizei <span 2085 style="font-style: italic;">height</span>, GLenum <span 2086 style="font-style: italic;">format</span>, GLenum <span 2087 style="font-style: italic;">type</span>, GLvoid *<span 2088 style="font-style: italic;">data</span>)<br> 2089 </div> 2090 <br> 2091 <span style="font-style: italic;">x</span> and <span 2092 style="font-style: italic;">y</span> specify the coordinate of the 2093 lower-left corner of the region to read and <span 2094 style="font-style: italic;">width</span> and <span 2095 style="font-style: italic;">height</span> specify the size of the 2096 rectangular region to read. <span style="font-style: italic;">format</span> 2097 specifies the format of image data and must be either GL_RGB or 2098 GL_RGBA. <span style="font-style: italic;">type</span> specify the 2099 data type of the image data and must be either GL_UNSIGNED_BYTE or 2100 GL_FLOAT. Other values for <span style="font-style: italic;">format</span> 2101 or <span style="font-style: italic;">type</span> will cause the error 2102 GL_INVALID_ENUM to be raised.<br> 2103 <br> 2104 The framebuffer may contain 3-component colors (red, green, blue) or 2105 4-component colors (red, green, blue, alpha). If an alpha channel 2106 is not present, alpha values default to 1.0.<br> 2107 <br> 2108 The frame buffer color components (red, green, blue, alpha) are either 2109 converted to 8-bit unsigned integers in the range[0, 255] if <span 2110 style="font-style: italic;">type </span>is GL_UNSIGNED_BYTE or 2111 converted to floating point values in the range [0, 1] if <span 2112 style="font-style: italic;">type</span> is GL_FLOAT. The (red, 2113 green, blue, alpha) tuples are then stored as GL_RGB triplets (by 2114 dropping the alpha component) or GL_RGBA quadruples in client memory.<br> 2115 <br> 2116 Image data is <span style="font-style: italic;">packed</span> into 2117 client memory according to the pixel packing parameters which are set by 2118 the command<br> 2119 <br> 2120 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glPixelStorei</span>(GLenum<span 2121 style="font-style: italic;"> pname</span>, GLint <span 2122 style="font-style: italic;">value</span>)<br> 2123 </div> 2124 <br> 2125 <span style="font-style: italic;">pname</span> must be 2126 GL_PACK_ROW_LENGTH. <span style="font-style: italic;">value</span> 2127 indicates the stride (in pixels) between subsequent rows in the 2128 destination image. If GL_PACK_ROW_LENGTH is zero (the default) 2129 then the <span style="font-style: italic;">width</span> parameter to <span 2130 style="font-weight: bold;">glReadPixels</span> indicates the row stride.<br> 2131 <br> 2132 Pixel readback takes place as follows:<br> 2133 <br> 2134 <div style="margin-left: 40px;">if (GL_PACK_ROW_LENGTH == 0)<br> 2135 rowLength = <span style="font-style: italic;">width</span>;<br> 2136 else<br> 2137 rowLength = GL_PACK_ROW_LENGTH<br> 2138 <br> 2139 if (<span style="font-style: italic;">format</span> == GL_RGB) {<br> 2140 for (i = 0; i < <span style="font-style: italic;">height</span>; 2141 i++) {<br> 2142 for (j = 0; j < <span 2143 style="font-style: italic;">width</span>; j++) {<br> 2144 k = (i * 2145 rowLength + j) * 3;<br> 2146 <span 2147 style="font-style: italic;">data</span>[k+0] = FrameBuffer(<span 2148 style="font-style: italic;">x</span> + j, <span 2149 style="font-style: italic;">y</span> + i).red;<br> 2150 <span 2151 style="font-style: italic;">data</span>[k+1] = FrameBuffer(<span 2152 style="font-style: italic;">x</span> + j, <span 2153 style="font-style: italic;">y</span> + i).green;<br> 2154 <span 2155 style="font-style: italic;">data</span>[k+2] = FrameBuffer(<span 2156 style="font-style: italic;">x</span> + j, <span 2157 style="font-style: italic;">y</span> + i).blue;<span 2158 style="font-style: italic;"></span><br> 2159 }<br> 2160 }<br> 2161 }<br> 2162 else {<br> 2163 for (i = 0; i < <span style="font-style: italic;">height</span>; 2164 i++) {<br> 2165 for (j = 0; j < <span 2166 style="font-style: italic;">width</span>; j++) {<br> 2167 k = (i * 2168 rowLength + j) * 4;<br> 2169 <span 2170 style="font-style: italic;">data</span>[k+0] = FrameBuffer(<span 2171 style="font-style: italic;">x</span> + j, <span 2172 style="font-style: italic;">y</span> + i).red;<br> 2173 <span 2174 style="font-style: italic;">data</span>[k+1] = FrameBuffer(<span 2175 style="font-style: italic;">x</span> + j, <span 2176 style="font-style: italic;">y</span> + i).green;<br> 2177 <span 2178 style="font-style: italic;">data</span>[k+2] = FrameBuffer(<span 2179 style="font-style: italic;">x</span> + j, <span 2180 style="font-style: italic;">y</span> + i).blue;<span 2181 style="font-style: italic;"></span><br> 2182 <span 2183 style="font-style: italic;">data</span>[k+3] = FrameBuffer(<span 2184 style="font-style: italic;">x</span> + j, <span 2185 style="font-style: italic;">y</span> + i).alpha;<span 2186 style="font-style: italic;"></span><br> 2187 }<br> 2188 }<br> 2189 }<br> 2190 </div> 2191 <br> 2192 The function FrameBuffer(<span style="font-style: italic;">c, r</span>) 2193 returns the pixel in the frame buffer at column <span 2194 style="font-style: italic;">c</span> of row <span 2195 style="font-style: italic;">r. </span><span 2196 style="font-style: italic;">data</span> is considered to be either a 2197 GLubyte pointer or a GLfloat pointer, depending on the <span 2198 style="font-style: italic;">type</span> parameter. Similarly, the 2199 FrameBuffer function returns either GLubyte values in the range [0, 255] 2200 or GLfloat values in the range [0,1], depending on the <span 2201 style="font-style: italic;">type</span> parameter.<br> 2202 <br> 2203 Pixels may be read from either the front or back color buffer. 2204 The command<br> 2205 <br> 2206 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glReadBuffer</span>(GLenum<span 2207 style="font-style: italic;">buffer</span>)<br> 2208 </div> 2209 <br> 2210 specifies the source for reading images with <span 2211 style="font-weight: bold;">glReadPixels</span>. If <span 2212 style="font-style: italic;">buffer</span> is GL_FRONT then front color 2213 buffer is the source. If <span style="font-style: italic;">buffer</span> 2214 is GL_BACK then the back color buffer is the source. It is illegal 2215 to specify GL_BACK when the color buffer is not double buffered. 2216 Any invalid value for <span style="font-style: italic;">buffer</span> 2217 will raise the error GL_INVALID_ENUM.<br> 2218 <br> 2219 The default read source is GL_BACK if the frame buffer is double 2220 buffered. Otherwise, the default read source is GL_FRONT.<br> 2221 <br> 2222 <h2>8.2 Selection Mode</h2> 2223 Selection mode is typically used to implement <span 2224 style="font-style: italic;">picking</span>: determining which 2225 primitive(s) are present at particular window positions. The 2226 command<br> 2227 <br> 2228 <div style="margin-left: 40px;">GLint <span style="font-weight: bold;">glRenderMode</span>(GLenum<span 2229 style="font-style: italic;">mode</span>)<br> 2230 </div> 2231 <br> 2232 is used to enable selection mode. If <span 2233 style="font-style: italic;">mode</span> is GL_SELECTION the graphics 2234 library is put into selection mode. If <span 2235 style="font-style: italic;">mode</span> is GL_RENDER the graphic 2236 library is put into normal rendering mode. Any other value for <span 2237 style="font-style: italic;">mode</span> will raise the error 2238 GL_INVALID_ENUM.<br> 2239 <br> 2240 When in selection mode rendering commands will not effect the 2241 framebuffer. Instead, a record of the primitives that would have 2242 been drawn is placed in the <span style="font-style: italic;">selection</span> <span 2243 style="font-style: italic;">buffer</span>. The selection buffer 2244 is specified with the command<br> 2245 <br> 2246 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glSelectionBuffer</span>(GLsizei<span 2247 style="font-style: italic;">n</span>, GLuint *<span 2248 style="font-style: italic;">buffer</span>)<br> 2249 </div> 2250 <span style="font-style: italic;"></span><span 2251 style="font-style: italic;"><br> 2252 buffer</span> is an array of <span style="font-style: italic;">n</span> 2253 unsigned integers. No more than <span style="font-style: italic;">n</span> 2254 values will be placed in the buffer.<br> 2255 <br> 2256 The <span style="font-style: italic;">name stack</span> is a stack 2257 (LIFO) of unsigned integer names. The following commands 2258 manipulate the name stack:<br> 2259 <br> 2260 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glInitNames</span>(void)<br> 2261 void <span style="font-weight: bold;">glPushName</span>(GLuint <span 2262 style="font-style: italic;">name</span>)<br> 2263 void <span style="font-weight: bold;">glPopName</span>(void)<br> 2264 void <span style="font-weight: bold;">glLoadName</span>(GLuint <span 2265 style="font-style: italic;">name</span>)<br> 2266 </div> 2267 <br> 2268 <span style="font-weight: bold;">glInitNames</span> resets the name 2269 stack to an empty state. <span style="font-weight: bold;">glPushName<span 2270 style="font-style: italic;"> </span></span>pushes the given <span 2271 style="font-style: italic;">name</span> value onto the stack. <span 2272 style="font-weight: bold;">glPopName</span> pops the top name from the 2273 stack. <span style="font-weight: bold;">glLoadName<span 2274 style="font-style: italic;"> </span></span>replaces the top value on 2275 the stack with the specified <span style="font-style: italic;">name</span>. 2276 Stack underflow and overflow conditions cause the errors 2277 GL_STACK_OVERFLOW and GL_STACK_UNDERFLOW to be raised.<br> 2278 <br> 2279 While in selection mode, primitives (points, lines, polygons) are 2280 transformed and clip-tested normally. Primitives which aren't 2281 discarded by clipping cause the <span style="font-style: italic;">hit</span> <span 2282 style="font-style: italic;">data</span> to be updated. The hit 2283 data consists of three pieces of information: a hit flag, a minimum Z 2284 value and a maximum Z value. First, the hit flag is set. 2285 Then, for each of the primitive's vertices, the vertex Z value is 2286 compared to the minimum and maximum Z values. The minimum Z value 2287 is updated if the vertex's Z value is less than the minimum Z value. 2288 The maximum Z value is updated if the vertex's Z value is greater 2289 than the maximum Z value.<br> 2290 <br> 2291 When any of <span style="font-weight: bold;">glInitNames</span><span 2292 style="font-style: italic;"><span style="font-style: italic;">, </span></span><span 2293 style="font-weight: bold;">glPushName</span>, <span 2294 style="font-weight: bold;">glPopName</span>, <span 2295 style="font-weight: bold;">glLoadName</span> or <span 2296 style="font-weight: bold;">glRenderMode</span> are called and the hit 2297 flag is set, a <span style="font-style: italic;">hit record</span> is 2298 written to the selection buffer.<br> 2299 <br> 2300 A hit record consists of a sequence of unsigned integers. The 2301 first value is the size of the name stack. The second value is the 2302 minimum Z value multiplied by 2<sup>32</sup>-1. The third value is 2303 the maximum Z value multiplied by 2<sup>32</sup>-1. The remaining 2304 values are the values in the name stack, in bottom to top order. 2305 The hit flag is cleared after a hit record is written to the 2306 selection buffer. Hit records are places sequentially into the 2307 selection buffer until it is full or selection mode is terminated.<br> 2308 <br> 2309 Selection mode is terminated by calling <span 2310 style="font-weight: bold;">glRenderMode</span>(GL_RENDER). The 2311 return value of <span style="font-weight: bold;">glRenderMode</span> 2312 will be -1 if the selection buffer overflowed. Otherwise, the 2313 return value will indicate the number of values written into the 2314 selection buffer.<br> 2315 <br> 2316 <h2>8.3 Synchronization</h2> 2317 The command<br> 2318 <br> 2319 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glFlush</span>(void)<br> 2320 </div> 2321 <br> 2322 makes the graphics library to flush all pending graphics commands. 2323 The command<br> 2324 <div style="margin-left: 40px;"><br> 2325 void <span style="font-weight: bold;">glFinish</span>(void)<br> 2326 </div> 2327 <br> 2328 makes the graphics library flush the command queue and wait until those 2329 commands are completed. <span style="font-weight: bold;">glFlush</span> 2330 will not return until all previous graphics commands have been fully 2331 completed.<br> 2332 <br> 2333 These commands are typically used to force completion of rendering to 2334 the front color buffer. Otherwise, rendering to the front color 2335 buffer may not appear. The <span style="font-style: italic;">swapbuffers</span> 2336 command (part of the window system binding library) does an implicit 2337 flush before swapping the front and back color buffers. The <span 2338 style="font-weight: bold;">glReadPixels</span> command also does an 2339 implicit flush before reading pixel data from the frame buffer.<br> 2340 <br> 2341 <h1>9. State Queries</h1> 2342 The current value of nearly all library state variables can be queried. 2343 This chapter describes the commands used for querying the value of 2344 state variables.<br> 2345 <br> 2346 <h2>9.1 General State Queries</h2> 2347 The command<br> 2348 <br> 2349 <div style="margin-left: 40px;">void <span style="font-weight: bold;">glGetFloatv</span>(GLenum<span 2350 style="font-style: italic;">pname</span>, GLfloat *<span 2351 style="font-style: italic;">values</span>)<br> 2352 </div> 2353 <br> 2354 returns the value(s) of the state variable specified by <span 2355 style="font-style: italic;">pname</span>. The following table 2356 lists all accepted values for <span style="font-style: italic;">pname</span> 2357 and a description of the value(s). Specifying any other value for <span 2358 style="font-style: italic;">pname</span> causes the error 2359 GL_INVALID_ENUM to be raised.<br> 2360 <br> 2361 <table cellpadding="2" cellspacing="2" border="1" 2362 style="text-align: left; width: 90%; margin-left: auto; margin-right: auto;"> 2363 <tbody> 2364 <tr> 2365 <td style="vertical-align: top;">Variable (<span 2366 style="font-style: italic;">pname)</span><br> 2367 </td> 2368 <td style="vertical-align: top;">Number of values<br> 2369 </td> 2370 <td style="vertical-align: top;">Value(s) Description<br> 2371 </td> 2372 </tr> 2373 <tr> 2374 <td style="vertical-align: top;">GL_ALPHA_BITS<br> 2375 </td> 2376 <td style="vertical-align: top;">1<br> 2377 </td> 2378 <td style="vertical-align: top;">Number of bits per alpha value 2379 in the frame buffer.<br> 2380 </td> 2381 </tr> 2382 <tr> 2383 <td style="vertical-align: top;">GL_ALPHA_TEST<br> 2384 </td> 2385 <td style="vertical-align: top;">1<br> 2386 </td> 2387 <td style="vertical-align: top;">Zero if the alpha test is 2388 disabled.<br> 2389 One if the alpha test is enabled.<br> 2390 </td> 2391 </tr> 2392 <tr> 2393 <td style="vertical-align: top;">GL_ALPHA_TEST_FUNC<br> 2394 </td> 2395 <td style="vertical-align: top;">1<br> 2396 </td> 2397 <td style="vertical-align: top;">The alpha test function.<br> 2398 </td> 2399 </tr> 2400 <tr> 2401 <td style="vertical-align: top;">GL_BLEND<br> 2402 </td> 2403 <td style="vertical-align: top;">1<br> 2404 </td> 2405 <td style="vertical-align: top;">Zero if blending is disabled.<br> 2406 One if blending is enabled.<br> 2407 </td> 2408 </tr> 2409 <tr> 2410 <td style="vertical-align: top;">GL_BLEND_DST<br> 2411 </td> 2412 <td style="vertical-align: top;">1<br> 2413 </td> 2414 <td style="vertical-align: top;">Blend destination function/term.<br> 2415 </td> 2416 </tr> 2417 <tr> 2418 <td style="vertical-align: top;">GL_BLEND_SRC<br> 2419 </td> 2420 <td style="vertical-align: top;">1<br> 2421 </td> 2422 <td style="vertical-align: top;">Blend source function/term.<br> 2423 </td> 2424 </tr> 2425 <tr> 2426 <td style="vertical-align: top;">GL_BLUE_BITS<br> 2427 </td> 2428 <td style="vertical-align: top;">1<br> 2429 </td> 2430 <td style="vertical-align: top;">Number of bits per blue value in 2431 the frame buffer.<br> 2432 </td> 2433 </tr> 2434 <tr> 2435 <td style="vertical-align: top;">GL_COLOR_CLEAR_VALUE<br> 2436 </td> 2437 <td style="vertical-align: top;">4<br> 2438 </td> 2439 <td style="vertical-align: top;">Clear color (red, green, blue, 2440 alpha).<br> 2441 </td> 2442 </tr> 2443 <tr> 2444 <td style="vertical-align: top;">GL_COLOR_WRITE_MASK<br> 2445 </td> 2446 <td style="vertical-align: top;">4<br> 2447 </td> 2448 <td style="vertical-align: top;">Color buffer writemask (red, 2449 green, blue, alpha).<br> 2450 Zero if writing is disabled.<br> 2451 One if writing is enabled.<br> 2452 </td> 2453 </tr> 2454 <tr> 2455 <td style="vertical-align: top;">GL_CULL_FACE<br> 2456 </td> 2457 <td style="vertical-align: top;">1<br> 2458 </td> 2459 <td style="vertical-align: top;">Zero if polygon culling is 2460 disabled.<br> 2461 One if polygon culling is enabled.<br> 2462 </td> 2463 </tr> 2464 <tr> 2465 <td style="vertical-align: top;">GL_CULL_FACE_MODE<br> 2466 </td> 2467 <td style="vertical-align: top;">1<br> 2468 </td> 2469 <td style="vertical-align: top;">Polygon cull mode: GL_FRONT, 2470 GL_BACK or GL_FRONT_AND_BACK.<br> 2471 </td> 2472 </tr> 2473 <tr> 2474 <td style="vertical-align: top;">GL_CURRENT_COLOR<br> 2475 </td> 2476 <td style="vertical-align: top;">4<br> 2477 </td> 2478 <td style="vertical-align: top;">Current color (red, green, blue, 2479 alpha).<br> 2480 </td> 2481 </tr> 2482 <tr> 2483 <td style="vertical-align: top;">GL_CURRENT_RASTER_COLOR<br> 2484 </td> 2485 <td style="vertical-align: top;">4<br> 2486 </td> 2487 <td style="vertical-align: top;">Current raster position color 2488 (red, green, blue, alpha).<br> 2489 </td> 2490 </tr> 2491 <tr> 2492 <td style="vertical-align: top;">GL_CURRENT_RASTER_TEXTURE_COORDS<br> 2493 </td> 2494 <td style="vertical-align: top;">4<br> 2495 </td> 2496 <td style="vertical-align: top;">Current raster position texture 2497 coordinates (s, t, r, q).<br> 2498 </td> 2499 </tr> 2500 <tr> 2501 <td style="vertical-align: top;">GL_CURRENT_RASTER_POSITION<br> 2502 </td> 2503 <td style="vertical-align: top;">4<br> 2504 </td> 2505 <td style="vertical-align: top;">Current raster position (x, y, 2506 z, w).<br> 2507 </td> 2508 </tr> 2509 <tr> 2510 <td style="vertical-align: top;">GL_CURRENT_POSITION_VALID<br> 2511 </td> 2512 <td style="vertical-align: top;">1<br> 2513 </td> 2514 <td style="vertical-align: top;">Zero if current raster position 2515 is invalid.<br> 2516 One if current raster position is valid.<br> 2517 </td> 2518 </tr> 2519 <tr> 2520 <td style="vertical-align: top;">GL_CURRENT_TEXTURE_COORDS<br> 2521 </td> 2522 <td style="vertical-align: top;">4<br> 2523 </td> 2524 <td style="vertical-align: top;">Current texture coordinates (s, 2525 t, r, q)<br> 2526 </td> 2527 </tr> 2528 <tr> 2529 <td style="vertical-align: top;">GL_DOUBLEBUFFER<br> 2530 </td> 2531 <td style="vertical-align: top;">1<br> 2532 </td> 2533 <td style="vertical-align: top;">Zero if color buffer is 2534 single-buffered.<br> 2535 One if color buffer is double-buffered.<br> 2536 </td> 2537 </tr> 2538 <tr> 2539 <td style="vertical-align: top;">GL_DRAW_BUFFER<br> 2540 </td> 2541 <td style="vertical-align: top;">1<br> 2542 </td> 2543 <td style="vertical-align: top;">Current color draw buffer: 2544 GL_FRONT or GL_BACK.<br> 2545 </td> 2546 </tr> 2547 <tr> 2548 <td style="vertical-align: top;">GL_FRONT_FACE</td> 2549 <td style="vertical-align: top;">1<br> 2550 </td> 2551 <td style="vertical-align: top;">Polygon front-face winding: 2552 GL_CW or GL_CCW.<br> 2553 </td> 2554 </tr> 2555 <tr> 2556 <td style="vertical-align: top;">GL_GREEN_BITS<br> 2557 </td> 2558 <td style="vertical-align: top;">1<br> 2559 </td> 2560 <td style="vertical-align: top;">Number of bits per green value 2561 in the frame buffer.<br> 2562 </td> 2563 </tr> 2564 <tr> 2565 <td style="vertical-align: top;">GL_LINE_SMOOTH<br> 2566 </td> 2567 <td style="vertical-align: top;">1<br> 2568 </td> 2569 <td style="vertical-align: top;">Zero if line smoothing is 2570 disabled.<br> 2571 One if line smoothing is enabled.<br> 2572 </td> 2573 </tr> 2574 <tr> 2575 <td style="vertical-align: top;">GL_LINE_STIPPLE<br> 2576 </td> 2577 <td style="vertical-align: top;">1<br> 2578 </td> 2579 <td style="vertical-align: top;">Zero if line stippling is 2580 disabled.<br> 2581 One if line stippling is enabled.<br> 2582 </td> 2583 </tr> 2584 <tr> 2585 <td style="vertical-align: top;">GL_LINE_STIPPLE_PATTERN<br> 2586 </td> 2587 <td style="vertical-align: top;">1<br> 2588 </td> 2589 <td style="vertical-align: top;">Line stipple pattern.<br> 2590 </td> 2591 </tr> 2592 <tr> 2593 <td style="vertical-align: top;">GL_LINE_STIPPLE_REPEAT<br> 2594 </td> 2595 <td style="vertical-align: top;">1<br> 2596 </td> 2597 <td style="vertical-align: top;">Line stipple repeat factor.<br> 2598 </td> 2599 </tr> 2600 <tr> 2601 <td style="vertical-align: top;">GL_LINE_WIDTH<br> 2602 </td> 2603 <td style="vertical-align: top;">1<br> 2604 </td> 2605 <td style="vertical-align: top;">Line width in pixels.<br> 2606 </td> 2607 </tr> 2608 <tr> 2609 <td style="vertical-align: top;">GL_LINE_WIDTH_GRANULARITY<br> 2610 </td> 2611 <td style="vertical-align: top;">1<br> 2612 </td> 2613 <td style="vertical-align: top;">Aliased line width granularity.<br> 2614 </td> 2615 </tr> 2616 <tr> 2617 <td style="vertical-align: top;">GL_LINE_WIDTH_RANGE<br> 2618 </td> 2619 <td style="vertical-align: top;">2<br> 2620 </td> 2621 <td style="vertical-align: top;">Minimum and maximum aliased line 2622 widths.<br> 2623 </td> 2624 </tr> 2625 <tr> 2626 <td style="vertical-align: top;">GL_ALIASED_LINE_WIDTH_RANGE<br> 2627 </td> 2628 <td style="vertical-align: top;">2<br> 2629 </td> 2630 <td style="vertical-align: top;">Minimum and maximum antialiased 2631 line widths.</td> 2632 </tr> 2633 <tr> 2634 <td style="vertical-align: top;">GL_COLOR_LOGIC_OP<br> 2635 </td> 2636 <td style="vertical-align: top;">1<br> 2637 </td> 2638 <td style="vertical-align: top;">Zero if logicop is disabled.<br> 2639 One if logicop is enabled.<br> 2640 </td> 2641 </tr> 2642 <tr> 2643 <td style="vertical-align: top;">GL_LOGIC_OP_MODE<br> 2644 </td> 2645 <td style="vertical-align: top;">1<br> 2646 </td> 2647 <td style="vertical-align: top;">Logicop function.<br> 2648 </td> 2649 </tr> 2650 <tr> 2651 <td style="vertical-align: top;">GL_MATRIX_MODE<br> 2652 </td> 2653 <td style="vertical-align: top;">1<br> 2654 </td> 2655 <td style="vertical-align: top;">Matrix mode: GL_MODELVIEW or 2656 GL_PROJECTION.<br> 2657 </td> 2658 </tr> 2659 <tr> 2660 <td style="vertical-align: top;">GL_MAX_MODELVIEW_STACK_DEPTH<br> 2661 </td> 2662 <td style="vertical-align: top;">1<br> 2663 </td> 2664 <td style="vertical-align: top;">Maximum size of the modelview 2665 matrix stack.<br> 2666 </td> 2667 </tr> 2668 <tr> 2669 <td style="vertical-align: top;">GL_MAX_NAME_STACK_DEPTH<br> 2670 </td> 2671 <td style="vertical-align: top;">1<br> 2672 </td> 2673 <td style="vertical-align: top;">Maximum size of the selection 2674 name stack.<br> 2675 </td> 2676 </tr> 2677 <tr> 2678 <td style="vertical-align: top;">GL_MAX_PROJECTION_STACK_DEPTH<br> 2679 </td> 2680 <td style="vertical-align: top;">1<br> 2681 </td> 2682 <td style="vertical-align: top;">Maximum size of the projection 2683 matrix stack.<br> 2684 </td> 2685 </tr> 2686 <tr> 2687 <td style="vertical-align: top;">GL_MAX_TEXTURE_SIZE<br> 2688 </td> 2689 <td style="vertical-align: top;">1<br> 2690 </td> 2691 <td style="vertical-align: top;">Maximum 2D texture image width 2692 and height.<br> 2693 </td> 2694 </tr> 2695 <tr> 2696 <td style="vertical-align: top;">GL_MAX_VIEWPORT_DIMS<br> 2697 </td> 2698 <td style="vertical-align: top;">2</td> 2699 <td style="vertical-align: top;">Maximum viewport width and 2700 height in pixels.<br> 2701 </td> 2702 </tr> 2703 <tr> 2704 <td style="vertical-align: top;">GL_MODELVIEW_MATRIX<br> 2705 </td> 2706 <td style="vertical-align: top;">16<br> 2707 </td> 2708 <td style="vertical-align: top;">Current/top modelview matrix 2709 values.<br> 2710 </td> 2711 </tr> 2712 <tr> 2713 <td style="vertical-align: top;">GL_MODELVIEW_MATRIX_STACK_DEPTH<br> 2714 </td> 2715 <td style="vertical-align: top;">1<br> 2716 </td> 2717 <td style="vertical-align: top;">Current size of the modelview 2718 matrix stack.<br> 2719 </td> 2720 </tr> 2721 <tr> 2722 <td style="vertical-align: top;">GL_NAME_STACK_DEPTH<br> 2723 </td> 2724 <td style="vertical-align: top;">1<br> 2725 </td> 2726 <td style="vertical-align: top;">Current size of the selection 2727 name stack.<br> 2728 </td> 2729 </tr> 2730 <tr> 2731 <td style="vertical-align: top;">GL_PACK_ROW_LENGTH<br> 2732 </td> 2733 <td style="vertical-align: top;">1<br> 2734 </td> 2735 <td style="vertical-align: top;">Pixel packing row length.<br> 2736 </td> 2737 </tr> 2738 <tr> 2739 <td style="vertical-align: top;">GL_POLYGON_SMOOTH<br> 2740 </td> 2741 <td style="vertical-align: top;">1<br> 2742 </td> 2743 <td style="vertical-align: top;">Zero if polygon smoothing is 2744 disabled.<br> 2745 One if polygon smoothing is enabled.<br> 2746 </td> 2747 </tr> 2748 <tr> 2749 <td style="vertical-align: top;">GL_PROJECTION_MATRIX<br> 2750 </td> 2751 <td style="vertical-align: top;">16<br> 2752 </td> 2753 <td style="vertical-align: top;">Current/top projection matrix 2754 values.<br> 2755 </td> 2756 </tr> 2757 <tr> 2758 <td style="vertical-align: top;">GL_PROJECTION_STACK_DEPTH<br> 2759 </td> 2760 <td style="vertical-align: top;">1<br> 2761 </td> 2762 <td style="vertical-align: top;">Current size of projection 2763 matrix stack.<br> 2764 </td> 2765 </tr> 2766 <tr> 2767 <td style="vertical-align: top;">GL_READ_BUFFER<br> 2768 </td> 2769 <td style="vertical-align: top;">1<br> 2770 </td> 2771 <td style="vertical-align: top;">Current read buffer: GL_FRONT or 2772 GL_BACK.<br> 2773 </td> 2774 </tr> 2775 <tr> 2776 <td style="vertical-align: top;">GL_RED_BITS<br> 2777 </td> 2778 <td style="vertical-align: top;">1<br> 2779 </td> 2780 <td style="vertical-align: top;">Number of bits per red value in 2781 the frame buffer.<br> 2782 </td> 2783 </tr> 2784 <tr> 2785 <td style="vertical-align: top;">GL_RENDER_MODE<br> 2786 </td> 2787 <td style="vertical-align: top;">1<br> 2788 </td> 2789 <td style="vertical-align: top;">Current rendering mode: 2790 GL_RENDER or GL_SELECTION.<br> 2791 </td> 2792 </tr> 2793 <tr> 2794 <td style="vertical-align: top;">GL_RGBA_MODE<br> 2795 </td> 2796 <td style="vertical-align: top;">1<br> 2797 </td> 2798 <td style="vertical-align: top;">Always one.<br> 2799 </td> 2800 </tr> 2801 <tr> 2802 <td style="vertical-align: top;">GL_SCISSOR_BOX<br> 2803 </td> 2804 <td style="vertical-align: top;">4<br> 2805 </td> 2806 <td style="vertical-align: top;">Scissor box (x, y, width, 2807 height).<br> 2808 </td> 2809 </tr> 2810 <tr> 2811 <td style="vertical-align: top;">GL_SCISSOR_TEST<br> 2812 </td> 2813 <td style="vertical-align: top;">1<br> 2814 </td> 2815 <td style="vertical-align: top;">Zero if scissor test is disabled.<br> 2816 One if scissor test is enabled.<br> 2817 </td> 2818 </tr> 2819 <tr> 2820 <td style="vertical-align: top;">GL_SELECTION_BUFFER_SIZE<br> 2821 </td> 2822 <td style="vertical-align: top;">1<br> 2823 </td> 2824 <td style="vertical-align: top;">Size of selection buffer.<br> 2825 </td> 2826 </tr> 2827 <tr> 2828 <td style="vertical-align: top;">GL_SHADE_MODEL<br> 2829 </td> 2830 <td style="vertical-align: top;">1<br> 2831 </td> 2832 <td style="vertical-align: top;">Shade model: GL_FLAT or 2833 GL_SMOOTH.<br> 2834 </td> 2835 </tr> 2836 <tr> 2837 <td style="vertical-align: top;">GL_STENCIL_BITS<br> 2838 </td> 2839 <td style="vertical-align: top;">1<br> 2840 </td> 2841 <td style="vertical-align: top;">Number of bits per stencil value 2842 in the frame buffer.<br> 2843 </td> 2844 </tr> 2845 <tr> 2846 <td style="vertical-align: top;">GL_STENCIL_CLEAR_VALUE<br> 2847 </td> 2848 <td style="vertical-align: top;">1<br> 2849 </td> 2850 <td style="vertical-align: top;">Stencil buffer clear value.<br> 2851 </td> 2852 </tr> 2853 <tr> 2854 <td style="vertical-align: top;">GL_STENCIL_FAIL<br> 2855 </td> 2856 <td style="vertical-align: top;">1<br> 2857 </td> 2858 <td style="vertical-align: top;">Stencil fail operation.<br> 2859 </td> 2860 </tr> 2861 <tr> 2862 <td style="vertical-align: top;">GL_STENCIL_FUNC<br> 2863 </td> 2864 <td style="vertical-align: top;">1<br> 2865 </td> 2866 <td style="vertical-align: top;">Stencil function.<br> 2867 </td> 2868 </tr> 2869 <tr> 2870 <td style="vertical-align: top;">GL_STENCIL_REF<br> 2871 </td> 2872 <td style="vertical-align: top;">1<br> 2873 </td> 2874 <td style="vertical-align: top;">Stencil reference value.<br> 2875 </td> 2876 </tr> 2877 <tr> 2878 <td style="vertical-align: top;">GL_STENCIL_TEST<br> 2879 </td> 2880 <td style="vertical-align: top;">1<br> 2881 </td> 2882 <td style="vertical-align: top;">Zero if stencil test is disabled.<br> 2883 One if stencil test is enabled.<br> 2884 </td> 2885 </tr> 2886 <tr> 2887 <td style="vertical-align: top;">GL_STENCIL_VALUE_MASK<br> 2888 </td> 2889 <td style="vertical-align: top;">1<br> 2890 </td> 2891 <td style="vertical-align: top;">Stencil mask value.<br> 2892 </td> 2893 </tr> 2894 <tr> 2895 <td style="vertical-align: top;">GL_STENCIL_WRITE_MASK<br> 2896 </td> 2897 <td style="vertical-align: top;">1<br> 2898 </td> 2899 <td style="vertical-align: top;">Stencil buffer write mask.<br> 2900 </td> 2901 </tr> 2902 <tr> 2903 <td style="vertical-align: top;">GL_TEXTURE_2D<br> 2904 </td> 2905 <td style="vertical-align: top;">1<br> 2906 </td> 2907 <td style="vertical-align: top;">Zero if 2D texture mapping is 2908 disabled.<br> 2909 One if 2D texture mapping is enabled.<br> 2910 </td> 2911 </tr> 2912 <tr> 2913 <td style="vertical-align: top;">GL_TEXTURE_BINDING_2D</td> 2914 <td style="vertical-align: top;">1<br> 2915 </td> 2916 <td style="vertical-align: top;">Name of currently bound 2D 2917 texture object.<br> 2918 </td> 2919 </tr> 2920 <tr> 2921 <td style="vertical-align: top;">GL_TEXTURE_ENV_COLOR<br> 2922 </td> 2923 <td style="vertical-align: top;">4<br> 2924 </td> 2925 <td style="vertical-align: top;">Texture environment color (red, 2926 green, blue, alpha).<br> 2927 </td> 2928 </tr> 2929 <tr> 2930 <td style="vertical-align: top;">GL_TEXTURE_ENV_MODE<br> 2931 </td> 2932 <td style="vertical-align: top;">1<br> 2933 </td> 2934 <td style="vertical-align: top;">Texture environment mode.<br> 2935 </td> 2936 </tr> 2937 <tr> 2938 <td style="vertical-align: top;">GL_UNPACK_ROW_LENGTH<br> 2939 </td> 2940 <td style="vertical-align: top;">1<br> 2941 </td> 2942 <td style="vertical-align: top;">Pixel unpacking row length.<br> 2943 </td> 2944 </tr> 2945 <tr> 2946 <td style="vertical-align: top;">GL_UNPACK_LSB_FIRST<br> 2947 </td> 2948 <td style="vertical-align: top;">1<br> 2949 </td> 2950 <td style="vertical-align: top;">Zero if most significant bit is 2951 unpacked first for bitmaps.<br> 2952 One if least significant bit is unpacked first for bitmaps.<br> 2953 </td> 2954 </tr> 2955 <tr> 2956 <td style="vertical-align: top;">GL_VIEWPORT<br> 2957 </td> 2958 <td style="vertical-align: top;">4<br> 2959 </td> 2960 <td style="vertical-align: top;">Current viewport (x, y, width, 2961 height).<br> 2962 </td> 2963 </tr> 2964 </tbody> 2965 </table> 2966 <br> 2967 <br> 2968 <h2>9.2 String Queries</h2> 2969 The command<br> 2970 <br> 2971 <div style="margin-left: 40px;">const GLubyte *<span 2972 style="font-weight: bold;">glGetString</span>(GLenum <span 2973 style="font-style: italic;">name</span>)<br> 2974 </div> 2975 <br> 2976 is used to query string-valued values. The legal values for <span 2977 style="font-style: italic;">name</span> are described in the following 2978 table:<br> 2979 <br> 2980 <table cellpadding="2" cellspacing="2" border="1" 2981 style="text-align: left; width: 80%; margin-left: auto; margin-right: auto;"> 2982 <tbody> 2983 <tr> 2984 <td style="vertical-align: top;"><span style="font-style: italic;">name</span><br> 2985 </td> 2986 <td style="vertical-align: top;">Return value<br> 2987 </td> 2988 </tr> 2989 <tr> 2990 <td style="vertical-align: top;">GL_VERSION<br> 2991 </td> 2992 <td style="vertical-align: top;">The library version, such as 2993 "1.2".<br> 2994 </td> 2995 </tr> 2996 <tr> 2997 <td style="vertical-align: top;">GL_RENDERER<br> 2998 </td> 2999 <td style="vertical-align: top;">The renderer, such as "Mesa DRI 3000 Radeon".<br> 3001 </td> 3002 </tr> 3003 <tr> 3004 <td style="vertical-align: top;">GL_VENDOR<br> 3005 </td> 3006 <td style="vertical-align: top;">The vendor of this 3007 implementation, such as "Tungsten Graphics, Inc."<br> 3008 </td> 3009 </tr> 3010 <tr> 3011 <td style="vertical-align: top;">GL_EXTENSIONS<br> 3012 </td> 3013 <td style="vertical-align: top;">A white-space separated list of 3014 the supported extensions. </td> 3015 </tr> 3016 </tbody> 3017 </table> 3018 <br> 3019 <h2>9.3 Error Queries</h2> 3020 The command<br> 3021 <br> 3022 <div style="margin-left: 40px;">GLenum <span style="font-weight: bold;">glGetError</span>(void)<br> 3023 </div> 3024 <br> 3025 returns the current error code. The current error code will be 3026 set by a GL command when an error condition has been detected. If 3027 the current error code is already set, subsequent errors will not be 3028 recorded. The error code is reset/cleared to GL_NO_ERROR when <span 3029 style="font-weight: bold;">glGetError</span> returns. The 3030 following error codes are possible:<br> 3031 <br> 3032 <table cellpadding="2" cellspacing="2" border="1" 3033 style="text-align: left; width: 80%; margin-left: auto; margin-right: auto;"> 3034 <tbody> 3035 <tr> 3036 <td style="vertical-align: top;">Error code<br> 3037 </td> 3038 <td style="vertical-align: top;">Meaning<br> 3039 </td> 3040 </tr> 3041 <tr> 3042 <td style="vertical-align: top;">GL_NO_ERROR<br> 3043 </td> 3044 <td style="vertical-align: top;">No error has been recorded.<br> 3045 </td> 3046 </tr> 3047 <tr> 3048 <td style="vertical-align: top;">GL_INVALID_ENUM<br> 3049 </td> 3050 <td style="vertical-align: top;">An enum parameter had an invalid 3051 value.<br> 3052 </td> 3053 </tr> 3054 <tr> 3055 <td style="vertical-align: top;">GL_INVALID_VALUE<br> 3056 </td> 3057 <td style="vertical-align: top;">A numeric parameter had an 3058 invalid value.<br> 3059 </td> 3060 </tr> 3061 <tr> 3062 <td style="vertical-align: top;">GL_INVALID_OPERATION<br> 3063 </td> 3064 <td style="vertical-align: top;">A function was called when not 3065 legal to do so.<br> 3066 </td> 3067 </tr> 3068 <tr> 3069 <td style="vertical-align: top;">GL_STACK_OVERFLOW<br> 3070 </td> 3071 <td style="vertical-align: top;">The current transformation 3072 matrix stack is full.<br> 3073 </td> 3074 </tr> 3075 <tr> 3076 <td style="vertical-align: top;">GL_STACK_UNDERFLOW<br> 3077 </td> 3078 <td style="vertical-align: top;">The current transformation 3079 matrix stack is empty.<br> 3080 </td> 3081 </tr> 3082 <tr> 3083 <td style="vertical-align: top;">GL_OUT_OF_MEMORY<br> 3084 </td> 3085 <td style="vertical-align: top;">The system ran out of dynamic 3086 memory.<br> 3087 </td> 3088 </tr> 3089 </tbody> 3090 </table> 3091 <br> 3092 <br> 3093 <h1>10. Unsupported Features</h1> 3094 This section lists other features and functions which are not supported 3095 and not previously discussed.<br> 3096 <br> 3097 <h2>10.1 Feedback Mode</h2> 3098 Feedback mode and the following related functions are not supported.<br> 3099 <br> 3100 <div style="margin-left: 40px;"><span style="font-weight: bold;">glFeedbackBuffer</span><br> 3101 <span style="font-weight: bold;">glPassThrough</span><br> 3102 </div> 3103 <br> 3104 <h2>10.2 1D and 3D Textures<br> 3105 </h2> 3106 Only 2D texture images are supported. The following functions 3107 used to specify 1D and 3D texture images are not supported:<br> 3108 <br> 3109 <div style="margin-left: 40px;"><span style="font-weight: bold;">glTexImage1D</span><br 3110 style="font-weight: bold;"> 3111 <span style="font-weight: bold;">glTexImage3D</span><br 3112 style="font-weight: bold;"> 3113 <span style="font-weight: bold;">glTexSubImage1D</span><br 3114 style="font-weight: bold;"> 3115 <span style="font-weight: bold;"> glTexSubImage3D</span><br 3116 style="font-weight: bold;"> 3117 <span style="font-weight: bold;">glCopyTexImage1D</span><br 3118 style="font-weight: bold;"> 3119 <span style="font-weight: bold;"> glCopyTexSubImage1D</span><br 3120 style="font-weight: bold;"> 3121 <span style="font-weight: bold;"> glCopyTexSubImage3D</span><br> 3122 </div> 3123 <br> 3124 <h2>10.3 Alternate Texture Image Commands<br> 3125 </h2> 3126 Texture images may only be specified with <span 3127 style="font-weight: bold;">glTexImage2D</span>. The following 3128 alternate texture image commands are not supported:<br> 3129 <br> 3130 <div style="margin-left: 40px; font-weight: bold;">glTexSubImage2D<br> 3131 glCopyTexImage2D<br> 3132 glCopyTexSubImage2D<br> 3133 </div> 3134 <br> 3135 <h2>10.4 Proxy Textures</h2> 3136 Proxy textures are not supported and the GL_PROXY_TEXTURE_2D token is 3137 not supported by any function.<br> 3138 <br> 3139 <br> 3140 <h2>10.5 Other Texture Commands</h2> 3141 The following commands related to texture mapping are not supported by 3142 the subset:<br> 3143 <br> 3144 <div style="margin-left: 40px; font-weight: bold;"> glPrioritizeTextures<br> 3145 glAreTexturesResident<br> 3146 glIsTexture<br> 3147 glTexEnviv<br> 3148 glTexEnvf<br> 3149 glTexParameterf<br> 3150 glTexParameteriv<br> 3151 glTexParameterfv<br> 3152 </div> 3153 <br> 3154 <br> 3155 <h2>10.6 Copy and Draw Pixels<br> 3156 </h2> 3157 The following commands are not supported:<br> 3158 <br> 3159 <div style="margin-left: 40px;"><span style="font-weight: bold;">glDrawPixels<br> 3160 glCopyPixels<br> 3161 glPixelZoom<br> 3162 <br> 3163 </span></div> 3164 <h2>10.7 Color Index Mode<br> 3165 </h2> 3166 Color index mode and the following related commands are not supported:<br> 3167 <br> 3168 <span style="font-weight: bold;"></span> 3169 <div style="margin-left: 40px;"><span style="font-weight: bold;">glIndexub<br> 3170 </span><span style="font-weight: bold;">glIndexi</span><br> 3171 <span style="font-weight: bold;">glIndexs<br> 3172 glIndexf<br> 3173 glIndexd<br> 3174 </span><span style="font-weight: bold;">glIndexubv<br> 3175 </span><span style="font-weight: bold;">glIndexiv</span><br> 3176 <span style="font-weight: bold;">glIndexsv<br> 3177 glIndexfv<br> 3178 glIndexdv</span><span style="font-weight: bold;"><br> 3179 glIndexMask<br> 3180 </span><span style="font-weight: bold;">glClearIndex<br> 3181 glIndexPointer</span><br style="font-weight: bold;"> 3182 <br> 3183 </div> 3184 <h2>10.8 Pixel Transfer Operations</h2> 3185 The pixel transfer operations (scale, bias, look-up table, etc) are not 3186 supported and the following commands are omitted:<br> 3187 <br style="font-weight: bold;"> 3188 <div style="margin-left: 40px;"><span style="font-weight: bold;">glPixelTransferf</span><br 3189 style="font-weight: bold;"> 3190 <span style="font-weight: bold;">glPixelTransferi</span><br 3191 style="font-weight: bold;"> 3192 <span style="font-weight: bold;">glPixelMapfv</span><br 3193 style="font-weight: bold;"> 3194 <span style="font-weight: bold;">glPixelMapuiv</span><br 3195 style="font-weight: bold;"> 3196 <span style="font-weight: bold;">glPixelMapusv</span><br 3197 style="font-weight: bold;"> 3198 <span style="font-weight: bold;">glGetPixelMapfv</span><br 3199 style="font-weight: bold;"> 3200 <span style="font-weight: bold;">glGetPixelMapuiv</span><br 3201 style="font-weight: bold;"> 3202 <span style="font-weight: bold;">glGetPixelMapusv</span><br> 3203 </div> 3204 <br> 3205 <h2>10.9 Hints</h2> 3206 Hints and the following related command is not supported:<br> 3207 <br> 3208 <div style="margin-left: 40px;"><span style="font-weight: bold;">glHint<br> 3209 </span><br> 3210 </div> 3211 <h2>10.10 State Query Commands<br> 3212 </h2> 3213 The following state query commands are not supported:<br> 3214 <br> 3215 <div style="margin-left: 40px; font-weight: bold;">glGetBooleanv<br> 3216 glGetIntegerv<br> 3217 glGetDoublev<br> 3218 glGetPointerv<br> 3219 glGetTexEnvi<br> 3220 glGetTexEnvf<br> 3221 glGetTexParameteriv<br> 3222 glGetTexParameterfv<br> 3223 glGetTexLevelParameteriv<br> 3224 glGetTexLevelParameterfv<br> 3225 glGetTexImage<br> 3226 glGetClipPlane<br> 3227 </div> 3228 <br> 3229 <h2>10.11 Attribute Stacks</h2> 3230 State attribute stacks and the following related commands are not 3231 supported:<br> 3232 <br> 3233 <div style="margin-left: 40px;"><span style="font-weight: bold;">glPushAttrib</span><br 3234 style="font-weight: bold;"> 3235 <span style="font-weight: bold;">glPopAtttrib</span><br> 3236 <br style="font-weight: bold;"> 3237 </div> 3238 <h2>10.12 Double-Valued Functions</h2> 3239 All functions which take double-precision floating point values, but 3240 for which there is an equivalent single-precision valued function, are 3241 omitted. This includes, but is not limited to:<br> 3242 <br> 3243 <div style="margin-left: 40px;"><span style="font-weight: bold;">glVertex2d</span><br 3244 style="font-weight: bold;"> 3245 <span style="font-weight: bold;">glVertex2dv</span><br 3246 style="font-weight: bold;"> 3247 <span style="font-weight: bold;">glVertex3d</span><br 3248 style="font-weight: bold;"> 3249 <span style="font-weight: bold;"> glVertex3dv</span><br 3250 style="font-weight: bold;"> 3251 <span style="font-weight: bold;">glVertex4d</span><br 3252 style="font-weight: bold;"> 3253 <span style="font-weight: bold;"> glVertex4dv</span><br 3254 style="font-weight: bold;"> 3255 <span style="font-weight: bold;">glColor3d</span><br 3256 style="font-weight: bold;"> 3257 <span style="font-weight: bold;">glColor3d</span><span 3258 style="font-weight: bold;">v</span><br style="font-weight: bold;"> 3259 <span style="font-weight: bold;">glColor4d</span><br 3260 style="font-weight: bold;"> 3261 <span style="font-weight: bold;"> glColor4dv</span><br 3262 style="font-weight: bold;"> 3263 <span style="font-weight: bold;">glTexCoord1d</span><br 3264 style="font-weight: bold;"> 3265 <span style="font-weight: bold;">glTexCoord1d</span><span 3266 style="font-weight: bold;">v</span><br style="font-weight: bold;"> 3267 <span style="font-weight: bold;">glTexCoord2d</span><br 3268 style="font-weight: bold;"> 3269 <span style="font-weight: bold;"> glTexCoord2dv</span><br 3270 style="font-weight: bold;"> 3271 <span style="font-weight: bold;">glTexCoord3d</span><br 3272 style="font-weight: bold;"> 3273 <span style="font-weight: bold;"> glTexCoord3dv</span><br 3274 style="font-weight: bold;"> 3275 <span style="font-weight: bold;">glTexCoord4d</span><br 3276 style="font-weight: bold;"> 3277 <span style="font-weight: bold;"> glTexCoord4dv</span><br 3278 style="font-weight: bold;"> 3279 <span style="font-weight: bold;">glRasterPos2d</span><br 3280 style="font-weight: bold;"> 3281 <span style="font-weight: bold;"> glRasterPos2dv</span><br 3282 style="font-weight: bold;"> 3283 <span style="font-weight: bold;">glRasterPos3d</span><br 3284 style="font-weight: bold;"> 3285 <span style="font-weight: bold;"> glRasterPos3dv</span><br 3286 style="font-weight: bold;"> 3287 <span style="font-weight: bold;">glRasterPos4d</span><br 3288 style="font-weight: bold;"> 3289 <span style="font-weight: bold;"> glRasterPos4dv</span><br 3290 style="font-weight: bold;"> 3291 <span style="font-weight: bold;">glLoadMatrixd</span><br 3292 style="font-weight: bold;"> 3293 <span style="font-weight: bold;">glMultMatrixd</span><br 3294 style="font-weight: bold;"> 3295 <span style="font-weight: bold;">glScaled</span><br 3296 style="font-weight: bold;"> 3297 <span style="font-weight: bold;">glRotated</span><br 3298 style="font-weight: bold;"> 3299 <span style="font-weight: bold;">glTranslated<br> 3300 glRectd<br> 3301 glRectdv<br> 3302 </span> <span style="font-weight: bold;"><br> 3303 </span> </div> 3304 <h2>10.13 Evaluators</h2> 3305 Evaluators and the following related commands are not supported:<br> 3306 <br> 3307 <div style="margin-left: 40px;"><span style="font-weight: bold;">glMap1f</span><br 3308 style="font-weight: bold;"> 3309 <span style="font-weight: bold;">glMap2d</span><br 3310 style="font-weight: bold;"> 3311 <span style="font-weight: bold;">glMap2f</span><br 3312 style="font-weight: bold;"> 3313 <span style="font-weight: bold;">glGetMapdv</span><br 3314 style="font-weight: bold;"> 3315 <span style="font-weight: bold;">glGetMapfv</span><br 3316 style="font-weight: bold;"> 3317 <span style="font-weight: bold;">glGetMapiv</span><br 3318 style="font-weight: bold;"> 3319 <span style="font-weight: bold;">glEvalCoord1d</span><br 3320 style="font-weight: bold;"> 3321 <span style="font-weight: bold;">glEvalCoord1f</span><br 3322 style="font-weight: bold;"> 3323 <span style="font-weight: bold;">glEvalCoord1dv</span><br 3324 style="font-weight: bold;"> 3325 <span style="font-weight: bold;">glEvalCoord1fv</span><br 3326 style="font-weight: bold;"> 3327 <span style="font-weight: bold;">glEvalCoord2d</span><br 3328 style="font-weight: bold;"> 3329 <span style="font-weight: bold;">glEvalCoord2f</span><br 3330 style="font-weight: bold;"> 3331 <span style="font-weight: bold;">glEvalCoord2dv</span><br 3332 style="font-weight: bold;"> 3333 <span style="font-weight: bold;">glEvalCoord2fv</span><br 3334 style="font-weight: bold;"> 3335 <span style="font-weight: bold;">glMapGrid1d</span><br 3336 style="font-weight: bold;"> 3337 <span style="font-weight: bold;">glMapGrid1f</span><br 3338 style="font-weight: bold;"> 3339 <span style="font-weight: bold;">glMapGrid2d</span><br 3340 style="font-weight: bold;"> 3341 <span style="font-weight: bold;">glMapGrid2f</span><br 3342 style="font-weight: bold;"> 3343 <span style="font-weight: bold;">glEvalPoint1</span><br 3344 style="font-weight: bold;"> 3345 <span style="font-weight: bold;">glEvalPoint2</span><br 3346 style="font-weight: bold;"> 3347 <span style="font-weight: bold;">glEvalMesh1</span><br 3348 style="font-weight: bold;"> 3349 <span style="font-weight: bold;">glEvalMesh2</span><br 3350 style="font-weight: bold;"> 3351 </div> 3352 <br> 3353 <h2>10.14 Display Lists</h2> 3354 Display lists and the following related commands are not supported:<br> 3355 <br> 3356 <div style="margin-left: 40px; font-weight: bold;">glIsList<br> 3357 glDeleteLists<br> 3358 glGenLists<br> 3359 glNewList<br> 3360 glEndList<br> 3361 glCallList<br> 3362 glCallLists<br> 3363 glListBase<br> 3364 </div> 3365 <br> 3366 <h2>10.15 Accumulation Buffer</h2> 3367 The accumulation buffer and the following related commands are not 3368 supported:<br> 3369 <br style="font-weight: bold;"> 3370 <div style="margin-left: 40px;"><span style="font-weight: bold;">glAccum</span><br 3371 style="font-weight: bold;"> 3372 <span style="font-weight: bold;">glClearAccum</span><br> 3373 </div> 3374 <br> 3375 <h2>10.16 Fog</h2> 3376 Fog and the following related commands are not supported:<br> 3377 <br> 3378 <div style="margin-left: 40px; font-weight: bold;"> glFogi<br> 3379 glFogf<br> 3380 glFogiv<br> 3381 glFogfv<br> 3382 </div> 3383 <br> 3384 <h2>10.17 Depth Test</h2> 3385 Depth testing and the following related commands are not supported:<br> 3386 <br> 3387 <div style="margin-left: 40px;"><span style="font-weight: bold;">glDepthFunc</span><br 3388 style="font-weight: bold;"> 3389 <span style="font-weight: bold;">glDepthMask</span><br 3390 style="font-weight: bold;"> 3391 <span style="font-weight: bold;">glDepthRange</span><br 3392 style="font-weight: bold;"> 3393 <span style="font-weight: bold;">glClearDepth</span><br> 3394 </div> 3395 <br> 3396 <h2>10.18 Imaging Subset</h2> 3397 The OpenGL imaging subset (which implements features such as 3398 convolution, histogram, min/max recording, color matrix and color 3399 tables) is not supported.<br> 3400 <br> 3401 <br> 3402 <h1>Appendix A: Issues</h1> 3403 This appendix lists documentation and subset issues with their current 3404 status. For items which are still open, the documentation (above) 3405 follows the recommended solution.<br> 3406 <br> 3407 <h2>A.1 Vertex Arrays</h2> 3408 Should vertex arrays be supported? Is there a performance 3409 advantage?<br> 3410 <br> 3411 RESOLUTION: No, there isn't enough of a performance advantage to 3412 justify them.<br> 3413 <br> 3414 <h2>A.2 Polygon Antialiasing and Edge Flags</h2> 3415 Should edge flags be supported for antialiasing?<br> 3416 <br> 3417 Edge flags don't effect antialiasing, at least not normally. A 3418 number of approaches to antialiasing have been summarized in email.<br> 3419 <br> 3420 RECOMMENDATION: don't support edge flags. They don't effect 3421 polygon antialiasing.<br> 3422 <br> 3423 RESOLUTION: closed, as of 26 Feb 2003.<br> 3424 <br> 3425 <h2>A.3 glRasterPos vs. glWindowPos</h2> 3426 Should glRasterPos and/or glWindowPos commands be supported?<br> 3427 <br> 3428 RESOLUTION: Closed: implement glRasterPos commands, but not glWindowPos 3429 commands.<br> 3430 <br> 3431 <h2>A.4 GL_IBM_rasterpos_clip extension</h2> 3432 Should the GL_IBM_rasterpos_clip extension be implemented?<br> 3433 <br> 3434 RESOLUTION: No. It's not required.<br> 3435 <br> 3436 <h2>A.5 Image Formats and Types</h2> 3437 Which image formats and types should be supported for <span 3438 style="font-weight: bold;">glTexImage2D</span> and <span 3439 style="font-weight: bold;">glReadPixels</span>?<br> 3440 <br> 3441 OpenGL specifies a <span style="font-weight: bold;">large</span> 3442 variety of image formats and data types. Only a few are commonly 3443 used.<br> 3444 <br> 3445 RECOMMENDATION: we propose a subset:<br> 3446 <br> 3447 For <span style="font-weight: bold;">glTexImage2D</span> only allow <span 3448 style="font-style: italic;">type</span>=GL_UNSIGNED_BYTE and <span 3449 style="font-style: italic;">format</span>=GL_RGBA, GL_RGB, 3450 GL_INTENSITY. Only allow <span style="font-style: italic;">internalFormat</span> 3451 to be GL_RGBA, GL_RGB or GL_INTENSITY as well. Basically, only 3452 support image formats/types that are directly supported by the Radeon 3453 hardware. This will allow <span style="font-weight: bold;">glTexImage2D</span> 3454 to basically just use <span style="font-weight: bold;">memcpy</span> to 3455 copy texture images.<br> 3456 <br> 3457 For <span style="font-weight: bold;">glReadPixels</span>, only allow <span 3458 style="font-style: italic;">type</span> = GL_UNSIGNED_BYTE or GL_FLOAT. 3459 Only allow <span style="font-style: italic;">format</span> = 3460 GL_RGB or GL_RGBA. This is just enough to support the OpenGL 3461 conformance tests.<br> 3462 <br> 3463 RESOLUTION: open<br> 3464 <br> 3465 <h2>A.6 Texture Environment Modes</h2> 3466 Which texture environment modes should be supported? OpenGL 1.2 3467 has GL_REPLACE, GL_MODULATE, GL_DECAL and GL_BLEND. GL_DECAL isn't 3468 defined for all base internal texture formats. GL_ADD is another 3469 useful mode. Perhaps drop GL_DECAL mode and add GL_ADD mode.<br> 3470 <br> 3471 RECOMMENDATION: implement the standard modes GL_REPLACE, GL_MODULATE, 3472 GL_DECAL and GL_BLEND.<br> 3473 <br> 3474 RESOLUTION: open<br> 3475 <br> 3476 <h2>A.7 Truncated Mipmaps and LOD Control</h2> 3477 Should we support the GL_TEXTURE_BASE_LEVEL, GL_TEXTURE_MAX_LEVEL, 3478 GL_TEXTURE_MIN_LOD and GL_TEXTURE_MAX_LOD texture parameters?<br> 3479 <br> 3480 RECOMMENDATION: We propose omitting these features at this time, 3481 in the interest of simplifying the driver.<br> 3482 <br> 3483 RESOLUTION: open<br> 3484 <br> 3485 <h2>A.8 Texture Priorities and Residency</h2> 3486 Should the subset support texture priorities via <span 3487 style="font-weight: bold;">glPrioritizeTextures</span> and the <span 3488 style="font-weight: bold;">glAreTexturesResident</span> command?<br> 3489 <br> 3490 RECOMMENDATION: Few applications use these features and 3491 functions. We propose omitting them to simplify the driver.<br> 3492 <br> 3493 RESOLUTION: open<br> 3494 <br> 3495 <h2>A.9 Pixel Pack/Unpack Alignment Control</h2> 3496 Should we support the GL_PACK_ALIGNMENT and GL_UNPACK_ALIGNMENT options?<br> 3497 <br> 3498 These are used to align pixel data addresses to 1, 2 and 4-byte 3499 multiples for <span style="font-weight: bold;">glBitmap, glTexImage2D</span> 3500 and <span style="font-weight: bold;">glReadPixels</span>. These 3501 aren't strictly needed since the user can provide a 1, 2 or 4-byte 3502 aligned address and appropriate GL_PACK_ROW_LENGTH or 3503 GL_UNPACK_ROW_LENGTH values instead.<br> 3504 <br> 3505 RECOMMENDATION: We recommend omitting them to simplify the driver.<br> 3506 <br> 3507 RESOLUTION: open<br> 3508 <br> 3509 <h2>A.10 Pixel Pack/Unpack Skip Rows/Pixels Control</h2> 3510 Should we support the GL_UNPACK_SKIP_PIXELS, GL_UNPACK_SKIP_ROWS, 3511 GL_PACK_SKIP_PIXELS and GL_PACK_SKIP_ROWS options for pixel 3512 unpacking/packing?<br> 3513 <br> 3514 These options aren't really needed since the user can adjust the start 3515 address and GL_PACK/UNPACK_ROW_LENGTH parameters to achieve the same 3516 effect.<br> 3517 <br> 3518 RECOMMENDATION: omit these parameters.<br> 3519 <br> 3520 RESOLUTION: open<br> 3521 <br> 3522 <h2>A.11 Texture State Queries</h2> 3523 Should we support the command <span style="font-weight: bold;">glGetTexEnvi/fv, 3524 glGetTexParameteri/fv</span> and <span style="font-weight: bold;">glGetTexLevelParameteri/fv</span>?<br> 3525 <br> 3526 RECOMMENDATION: No. They're seldom needed and their 3527 implementation is several hundred lines of code in length.<br> 3528 <br> 3529 RESOLUTION: open<br> 3530 <br> 3531 <h2>A.12 glGetIntegerv, glGetBooleanv and glGetDoublev</h2> 3532 Should we support the commands <span style="font-weight: bold;">glGetIntegerv, 3533 glGetBooleanv </span>and <span style="font-weight: bold;">glGetDoublev</span> 3534 in addition to <span style="font-weight: bold;">glGetFloatv</span>?<br> 3535 <br> 3536 RECOMMENDATION: Omit the boolean, integer and double-valued 3537 functions. All state values which can be queried by these commands can 3538 be expressed as floating point values and queried with <span 3539 style="font-weight: bold;">glGetFloatv</span>. The 3540 implementation of the other three commands involves many lines of code.<br> 3541 <br> 3542 RESOLUTION: open<br> 3543 <br> 3544 <h2>A.13 glBitmap and Per-Fragment Operations</h2> 3545 Should bitmaps rendered with <span style="font-weight: bold;">glBitmap</span> 3546 be subjected to the per-fragment operations?<br> 3547 <br> 3548 If bitmaps are implemented with points it will be easy to implement the 3549 per-fragment operations. Otherwise, it could be difficult.<br> 3550 <br> 3551 RECOMMENDATION: Implement glBitmap by drawing points/pixels with 3552 the hardware. This will make supporting the per-fragments 3553 trivially easy. Also, it makes portrait-mode display relatively 3554 easy.<br> 3555 <br> 3556 RESOLUTION: open<br> 3557 <br> 3558 <h2>A.14 Reduced gl.h Header File</h2> 3559 Should we produce a reduced gl.h header file which only defines the 3560 tokens and functions which are implemented by the subset?<br> 3561 <br> 3562 RECOMMENDATION: yes. It would be a useful reference to 3563 programmers to quickly determine which functions and tokens are 3564 supported.<br> 3565 <br> 3566 RESOLUTION: open<br> 3567 <br> 3568 <h2>A.15 glPolygonMode</h2> 3569 Is <span style="font-weight: bold;">glPolygonMode</span> needed?<br> 3570 <br> 3571 RECOMMENDATION: No. Omit it.<br> 3572 <br> 3573 RESOLUTION: closed, as of 26 Feb 2003<br> 3574 <br> 3575 <br> 3576 <p> </p> 3577 </body> 3578 </html> 3579
