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