1Name 2 3 OES_fixed_point 4 5Name Strings 6 7 GL_OES_fixed_point 8 9Contact 10 11 David Blythe (blythe 'at' bluevoid.com) 12 13Notice 14 15 Copyright (c) 2002-2013 The Khronos Group Inc. Copyright terms at 16 http://www.khronos.org/registry/speccopyright.html 17 18Specification Update Policy 19 20 Khronos-approved extension specifications are updated in response to 21 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 22 extensions which have been promoted to a core Specification, fixes will 23 first appear in the latest version of that core Specification, and will 24 eventually be backported to the extension document. This policy is 25 described in more detail at 26 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 27 28Status 29 30 Ratified by the Khronos BOP, July 23, 2003. 31 Ratified by the Khronos BOP, Aug 5, 2004. 32 33Version 34 35 Last Modifed Date: 27 April 2015 36 Author Revision: 1.0 37 38Number 39 40 OpenGL ES Extension #9 (formerly ARB Extension #292) 41 42Dependencies 43 44 None 45 The extension is written against the OpenGL 1.3 Specification. 46 47Overview 48 49 This extension provides the capability, for platforms that do 50 not have efficient floating-point support, to input data in a 51 fixed-point format, i.e., a scaled-integer format. There are 52 several ways a platform could try to solve the problem, such as 53 using integer only commands, but there are many OpenGL commands 54 that have only floating-point or double-precision floating-point 55 parameters. Also, it is likely that any credible application 56 running on such a platform will need to perform some computations 57 and will already be using some form of fixed-point representation. 58 This extension solves the problem by adding new ``fixed', and 59 ``clamp fixed'' data types based on a a two's complement 60 S15.16 representation. New versions of commands are created 61 with an 'x' suffix that take fixed or clampx parameters. 62 63 64IP Status 65 66 None 67 68Issues 69 70* Add double-precision (S31.32) form too? 71 NO 72 73* Additional InterleavedArray formats? 74 NO 75 76* Should newly suffixed commands, e.g., PointSize, get an alias with 77 a float or double suffix for consistency? 78 NO 79 80* Are enums converted to fixed by scaling by 2^16. 81 NO. An enums are passed through as if they are already in 82 S15.16 form. Requiring scaling is too error prone. 83 84New Procedures and Functions 85 86 NOTE: `T' expands to 'const fixed*' or `fixed' as appropriate 87 88 void Vertex{234}x[v]OES(T coords); 89 void Normal3x[v]OES(T coords); 90 void TexCoord{1234}x[v]OES(T coords); 91 void MultiTexCoord{1234}x[v]OES(enum texture, T coords); 92 void Color{34}x[v]OES(T components); 93 void Indexx[v]OES(T component); 94 void RectxOES(fixed x1, fixed y1, fixed x2, fixed y2); 95 void RectxvOES(const fixed v1[2], const fixed v2[2]); 96 97 void DepthRangexOES(clampx n, clampx f); 98 void LoadMatrixxOES(const fixed m[16]); 99 void MultMatrixxOES(const fixed m[16]); 100 void LoadTransposeMatrixxOES(const fixed m[16]); 101 void MultTransposeMatrixxOES(const fixed m[16]); 102 void RotatexOES(fixed angle, fixed x, fixed y, fixed z); 103 void ScalexOES(fixed x, fixed y, fixed z); 104 void TranslatexOES(fixed x, fixed y, fixed z); 105 void FrustumxOES(fixed l, fixed r, fixed b, fixed t, fixed n, fixed f); 106 void OrthoxOES(fixed l, fixed r, fixed b, fixed t, fixed n, fixed f); 107 void TexGenx[v]OES(enum coord, enum pname, T param); 108 void GetTexGenxvOES(enum coord, enum pname, T* params); 109 110 void ClipPlanexOES(enum plane, const fixed* equation); 111 void GetClipPlanexOES(enum plane, fixed* equation); 112 113 void RasterPos{234}x[v]OES(T coords); 114 115 void Materialx[v]OES(enum face, enum pname, T param); 116 void GetMaterialxOES(enum face, enum pname, T param); 117 void Lightx[v]OES(enum light, enum pname, T* params); 118 void GetLightxOES(enum light, enum pname, T* params); 119 void LightModelx[v]OES(enum pname, T param); 120 121 void PointSizexOES(fixed size); 122 void PointParameterxvOES(enum pname, const fixed *params) 123 void LineWidthxOES(fixed width); 124 void PolygonOffsetxOES(fixed factor, fixed units); 125 126 void PixelStorex{enum pname, T param); 127 void PixelTransferxOES(enum pname, T param); 128 void PixelMapx{enum map int size T* values); 129 void GetPixelMapxv{enum map int size T* values); 130 131 void ConvolutionParameterx[v]OES(enum target, enum pname, T param); 132 void GetConvolutionParameterxvOES(enum target, enum pname, T* params); 133 void GetHistogramParameterxvOES(enum target, enum pname, T *params); 134 135 void PixelZoomxOES(fixed xfactor, fixed yfactor); 136 137 void BitmapxOES(sizei width, sizei height, fixed xorig, fixed yorig, 138 fixed xmove, fixed ymove, const ubyte* bitmap); 139 140 void TexParameterx[v]OES(enum target, enum pname, T param); 141 void GetTexParameterxvOES(enum target, enum pname, T* params); 142 void GetTexLevelParameterxvOES(enum target, int level, enum pname, T* params); 143 void PrioritizeTexturesxOES(sizei n, uint* textures, clampx* priorities); 144 void TexEnvx[v]OES(enum target, enum pname, T param); 145 void GetTexEnvxvOES(enum target, enum pname, T* params); 146 147 void Fogx[v]OES(enum pname, T param); 148 149 void SampleCoveragexOES(clampx value, boolean invert); 150 void AlphaFuncxOES(enum func, clampx ref); 151 152 void BlendColorxOES(clampx red, clampx green, clampx blue, clampx alpha); 153 154 void ClearColorxOES(clampx red, clampx green, clampx blue, clampx alpha); 155 void ClearDepthxOES(clampx depth); 156 void ClearAccumxOES(clampx red, clampx green, clampx blue, clampx alpha); 157 void AccumxOES(enum op, fixed value); 158 159 void Map1xOES(enum target, T u1, T u2, int stride, int order, T points); 160 void Map2xOES(enum target, T u1, T u2, int ustride, int uorder, 161 T v1, T v2, int vstride, int vorder, T points); 162 void MapGrid1xOES(int n, T u1, T u2); 163 void MapGrid2xOES(int n, T u1, T u2, T v1, T v2); 164 void GetMapxvOES(enum target, enum query, T* v); 165 void EvalCoord{12}x[v]OES(T coord); 166 167 void FeedbackBufferxOES(sizei n, enum type, fixed* buffer); 168 void PassThroughxOES(fixed token); 169 170 GetFixedvOES(enum pname, fixed* params); 171 172 173New Tokens 174 175 FIXED_OES 0x140C 176 177Additions to Chapter 2 of the OpenGL 1.3 Specification (OpenGL Operation) 178 179 Section 2.1.1 Floating-Point Computation 180 181 Add the following paragraphs: 182 183 On some platforms, floating-point computations are not sufficiently 184 well supported to be used in an OpenGL implementation. On such 185 platforms, fixed-point representations may be a viable substitute for 186 floating-point. Internal computations can use either fixed-point 187 or floating-point arithmetic. Fixed-point computations must be 188 accurate to within +/-2^-15. The maximum representable magnitude 189 for a fixed-point number used to represent positional or normal 190 coordinates must be at least 2^15; the maximum representable 191 magnitude for colors or texture coordinates must be at least 2^10. 192 The maximum representable magnitude for all other fixed-point 193 values must be at least 2^15. x*0 = 0*x = 0. 1*x = x*1 = x. x + 194 0 = 0 + x = x. 0^0 = 1. Fixed-point computations may lead to 195 overflows or underflows. The results of such computations are 196 undefined, but must not lead to GL interruption or termination. 197 198 199 Section 2.3 GL Command Syntax 200 201 Paragraph 3 is updated to include the 'x' suffix and 202 203 Table 2.1 is modified to include the row: 204 205 --------------- 206 | x | fixed | 207 --------------- 208 209 Table 2.2 is modified to include the rows: 210 211 -------------------------------------------------------------- 212 | fixed | 32 | signed 2's complement S15.16 scaled integer| 213 -------------------------------------------------------------- 214 | clampx | 32 | S15.16 scaled integer clamped to [0, 1] | 215 -------------------------------------------------------------- 216 217 and the count of the number of rows in the text is changed to 16. 218 219 Add paragraph 220 221 The mapping of GL data types to data types of a specific 222 language binding are part of the language binding definition and 223 may be platform-dependent. Type conversion and type promotion 224 behavior when mixing actual and formal arguments of different 225 data types are specific to the language binding and platform. 226 For example, the C language includes automatic conversion 227 between integer and floating-point data types, but does not 228 include automatic conversion between the int and fixed or 229 float and fixed GL types since the fixed data type is not a 230 distinct built-in type. Regardless of language binding, 231 the enum type converts to fixed-point without scaling and 232 integer types are converted by multiplying by 2^16. 233 234 235 236 Section 2.7 Vertex Specification 237 238 Commands are revised to included 'x' suffix. 239 240 Section 2.8 Vertex Arrays 241 242 Table 2.4 Vertex Array Sizes is revised to include the 'fixed' type 243 for all commands except EdgeFlagPointer. 244 245 References to Vertex command suffixes are revised to include 'x'. 246 247 Section 2.9 Rectangles 248 249 Revise to include 'x' suffix. 250 251 Section 2.10 Coordinate Transformations 252 253 Revise to include 'x' suffix. Section 2.10.1 describes clampx. 254 Add alternate suffixed versions of Ortho and Frustum. 255 256 Section 2.11 Clipping 257 258 Add alternate suffixed version of ClipPlane. 259 260 Section 2.12 Current Raster Position 261 262 Revise to include 'x' suffix. 263 264 Section 2.13 Colors and Coloring 265 266 Revise to include 'x' suffix and 267 Table 2.6 is modified to include row: 268 269 --------------- 270 | fixed | c | 271 --------------- 272 273 274Additions to Chapter 3 of the OpenGL 1.3 Specification (Rasterization) 275 276 Section 3.3 Points 277 278 Add alternate suffixed PointSize command. 279 280 Section 3.4 Line Segments 281 282 Add alternate suffixed LineWidth command. 283 284 Section 3.5 Polygons 285 286 Add alternate suffixed PolygonOffset command. 287 288 Section 3.6 Pixel Rectangles 289 290 Revise to include 'x' suffix on PixelStore, PixelTransfer, PixelMap, 291 ConvolutionParameter. 292 293 Table 3.5 is modified to include row: 294 295 ---------------------- 296 | FIXED | fixed | No | 297 ---------------------- 298 299 Add alternate suffixed PixelZoom to Section 3.6.5 300 301 Section 3.7 Bitmaps 302 303 Add alternate suffixed Bitmap command. 304 305 Section 3.8 Texturing 306 307 Revise to include 'x' suffix in TexParameter (Section 3.8.4). 308 309 Add alternate suffixed PrioritizeTextures command (Section 3.8.11). 310 311 Revise to include 'x' suffix in TexEnv (Section 3.8.12). 312 313 Section 3.10 Fog 314 315 Revise to include ;x; suffix in Fog command. 316 317 318Additions to Chapter 4 of the OpenGL 1.3 Specification (Per-Fragment 319Operations and the Frame Buffer) 320 321 Section 4.1 Fragment Operations 322 323 Add alternate suffixed SampleCoveragex (Section 4.1.3), AlphaFunc 324 (Section 4.1.4), and BlendColor (Section 4.1.7) commands. 325 326 Section 4.2 Whole Framebuffer Operations 327 328 Add alternate suffixed ClearColor, ClearDepth, and ClearAccum commands 329 (Section 4.2.3). 330 331 Add alternate suffixed Accum command (Section 4.2.4). 332 333 334Additions to Chapter 5 of the OpenGL 1.3 Specification (Special Functions) 335 336 Section 5.1 Evaluators 337 338 Revise to include 'x' suffix on Map1, Map2, Map1Grid, and Map2Grid 339 commands. 340 341 Section 5.3 Feedback 342 343 Add alternate suffixed FeedbackBuffer and PassThrough commands. 344 Revise Figure 5.2 to indicate 'f' values may also be 'x' values. 345 346Additions to Chapter 6 of the OpenGL 1.3 Specification (State and 347State Requests) 348 349 Add GetFixedv to Section 6.1.1. Revise Section 6.1.2 to 350 include implied conversions for GetFixedv. 351 352 Revise to include 'x' suffix for GetClipPlane, GetLightm GetMaterial, 353 GetTexEnv, GetTexGen, GetTexParameter, GetTexLevelParameter, 354 GetPixelMap, and GetMap in Section 6.1.3. 355 356 Revise to include 'x' suffix for GetHistogramParameter (Section 6.1.9). 357 358 Section 6.2 State Tables 359 360 Revise intro paragraph to include GetFixedv. 361 362Additions to Appendix A of the OpenGL 1.3 Specification (Invariance) 363 364 None 365 366Additions to the AGL/GLX/WGL Specifications 367 368 None 369 370Additions to the WGL Specification 371 372 None 373 374Additions to the AGL Specification 375 376 None 377 378Additions to Chapter 2 of the GLX 1.3 Specification (GLX Operation) 379 380 The data representation is client-side only. The GLX layer 381 performs translation between fixed and float representations. 382 383Additions to Chapter 3 of the GLX 1.3 Specification (Functions and Errors) 384 385Additions to Chapter 4 of the GLX 1.3 Specification (Encoding on the X 386Byte Stream) 387 388Additions to Chapter 5 of the GLX 1.3 Specification (Extending OpenGL) 389 390Additions to Chapter 6 of the GLX 1.3 Specification (GLX Versions) 391 392GLX Protocol 393 394 Fixed type entry points are mapped on the client-side to the 395 appropriate floating-point command protocol. To preserve precision, 396 double-precision protocol is encouraged, but not required. 397 398Errors 399 400 None 401 402New State 403 404 None 405 406New Implementation Dependent State 407 408 None 409 410Revision History 411 412 12/15/2002 0.1 413 - Original draft. 414 415 03/31/2003 0.2 416 - Corrected a typo in GetClipPlanex and FIXED_OES. 417 418 04/24/2003 0.3 419 - Added clarification that enums must be converted to fixed 420 by scaling when passed in a fixed parameter type. Corrected 421 some typos. 422 423 05/29/2003 0.4 424 - Changed enums to be passed unscaled when passed to a 425 fixed formal parameter. 426 427 07/08/2003 0.5 428 - Removed bogus Dependencies on section 429 - Added extension number and enumerant value 430 431 07/11/2003 0.6 432 - Added OES suffixes 433 434 07/12/2003 0.7 435 - Added note about GLX protocol 436 437 06/16/2004 0.8 438 - Added ClipPlanex, and various Get functions 439 440 04/27/2015 1.0 (Jon Leech) 441 - Replace SampleCoverageOES with SampleCoveragexOES, to match the 442 specfile / headers (Bug 13591). 443