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