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