OES_fixed_point

GL_OES_fixed_point

David Blythe (blythe 'at' bluevoid.com)

Copyright (c) 2002-2013 The Khronos Group Inc. Copyright terms at
    http://www.khronos.org/registry/speccopyright.html

Khronos-approved extension specifications are updated in response to
issues and bugs prioritized by the Khronos OpenGL ES Working Group. For
extensions which have been promoted to a core Specification, fixes will
first appear in the latest version of that core Specification, and will
eventually be backported to the extension document. This policy is
described in more detail at
    https://www.khronos.org/registry/OpenGL/docs/update_policy.php

Ratified by the Khronos BOP, July 23, 2003.
Ratified by the Khronos BOP, Aug 5, 2004.

Last Modifed Date: 27 April 2015
Author Revision: 1.0

OpenGL ES Extension #9 (formerly ARB Extension #292)

None
The extension is written against the OpenGL 1.3 Specification.

This extension provides the capability, for platforms that do
not have efficient floating-point support, to input data in a
fixed-point format, i.e.,  a scaled-integer format.  There are
several ways a platform could try to solve the problem, such as
using integer only commands, but there are many OpenGL commands
that have only floating-point or double-precision floating-point
parameters.  Also, it is likely that any credible application
running on such a platform will need to perform some computations
and will already be using some form of fixed-point representation.
This extension solves the problem by adding new ``fixed', and
``clamp fixed''  data types based on a a two's complement
S15.16 representation.  New versions of commands are created
with an 'x' suffix that take fixed or clampx parameters.

None

NOTE:  `T' expands to 'const fixed*' or `fixed' as appropriate

void Vertex{234}x[v]OES(T coords);
void Normal3x[v]OES(T coords);
void TexCoord{1234}x[v]OES(T coords);
void MultiTexCoord{1234}x[v]OES(enum texture, T coords);
void Color{34}x[v]OES(T components);
void Indexx[v]OES(T component);
void RectxOES(fixed x1, fixed y1, fixed x2, fixed y2);
void RectxvOES(const fixed v1[2], const fixed v2[2]);

void DepthRangexOES(clampx n, clampx f);
void LoadMatrixxOES(const fixed m[16]);
void MultMatrixxOES(const fixed m[16]);
void LoadTransposeMatrixxOES(const fixed m[16]);
void MultTransposeMatrixxOES(const fixed m[16]);
void RotatexOES(fixed angle, fixed x, fixed y, fixed z);
void ScalexOES(fixed x, fixed y, fixed z);
void TranslatexOES(fixed x, fixed y, fixed z);
void FrustumxOES(fixed l, fixed r, fixed b, fixed t, fixed n, fixed f);
void OrthoxOES(fixed l, fixed r, fixed b, fixed t, fixed n, fixed f);
void TexGenx[v]OES(enum coord, enum pname, T param);
void GetTexGenxvOES(enum coord, enum pname, T* params);

void ClipPlanexOES(enum plane, const fixed* equation);
void GetClipPlanexOES(enum plane, fixed* equation);

void RasterPos{234}x[v]OES(T coords);

void Materialx[v]OES(enum face, enum pname, T param);
void GetMaterialxOES(enum face, enum pname, T param);
void Lightx[v]OES(enum light, enum pname, T* params);
void GetLightxOES(enum light, enum pname, T* params);
void LightModelx[v]OES(enum pname, T param);

void PointSizexOES(fixed size);
void PointParameterxvOES(enum pname, const fixed *params)
void LineWidthxOES(fixed width);
void PolygonOffsetxOES(fixed factor, fixed units);

void PixelStorex{enum pname, T param);
void PixelTransferxOES(enum pname, T param);
void PixelMapx{enum map int size T* values);
void GetPixelMapxv{enum map int size T* values);

void ConvolutionParameterx[v]OES(enum target, enum pname, T param);
void GetConvolutionParameterxvOES(enum target, enum pname, T* params);
void GetHistogramParameterxvOES(enum target, enum pname, T *params);

void PixelZoomxOES(fixed xfactor, fixed yfactor);

void BitmapxOES(sizei width, sizei height, fixed xorig, fixed yorig,
             fixed xmove, fixed ymove, const ubyte* bitmap);

void TexParameterx[v]OES(enum target, enum pname, T param);
void GetTexParameterxvOES(enum target, enum pname, T* params);
void GetTexLevelParameterxvOES(enum target, int level, enum pname, T* params);
void PrioritizeTexturesxOES(sizei n, uint* textures, clampx* priorities);
void TexEnvx[v]OES(enum target, enum pname, T param);
void GetTexEnvxvOES(enum target, enum pname, T* params);

void Fogx[v]OES(enum pname, T param);

void SampleCoveragexOES(clampx value, boolean invert);
void AlphaFuncxOES(enum func, clampx ref);

void BlendColorxOES(clampx red, clampx green, clampx blue, clampx alpha);

void ClearColorxOES(clampx red, clampx green, clampx blue, clampx alpha);
void ClearDepthxOES(clampx depth);
void ClearAccumxOES(clampx red, clampx green, clampx blue, clampx alpha);
void AccumxOES(enum op, fixed value);

void Map1xOES(enum target, T u1, T u2, int stride, int order, T points);
void Map2xOES(enum target, T u1, T u2, int ustride, int uorder,
                        T v1, T v2, int vstride, int vorder, T points);
void MapGrid1xOES(int n, T u1, T u2);
void MapGrid2xOES(int n, T u1, T u2, T v1, T v2);
void GetMapxvOES(enum target, enum query, T* v);
void EvalCoord{12}x[v]OES(T coord);

void FeedbackBufferxOES(sizei n, enum type, fixed* buffer);
void PassThroughxOES(fixed token);

GetFixedvOES(enum pname, fixed* params);

FIXED_OES                0x140C

Section 2.1.1 Floating-Point Computation

  Add the following paragraphs:

  On some platforms, floating-point computations are not sufficiently
  well supported to be used in an OpenGL implementation.  On such
  platforms, fixed-point representations may be a viable substitute for
  floating-point.  Internal computations can use either fixed-point
  or floating-point arithmetic.  Fixed-point computations must be
  accurate to within +/-2^-15.  The maximum representable magnitude
  for a fixed-point number used to represent positional or normal
  coordinates must be at least 2^15; the maximum representable
  magnitude for colors or texture coordinates must be at least 2^10.
  The maximum representable magnitude for all other fixed-point
  values must be at least 2^15.  x*0 = 0*x = 0. 1*x = x*1 = x. x +
  0 = 0 + x = x. 0^0 = 1. Fixed-point computations may lead to
  overflows or underflows.  The results of such computations are
  undefined, but must not lead to GL interruption or termination.


Section 2.3 GL Command Syntax

  Paragraph 3 is updated to include the 'x' suffix and

  Table 2.1 is modified to include the row:

  ---------------
  | x |  fixed  |
  ---------------

  Table 2.2 is modified to include the rows:

  --------------------------------------------------------------
  | fixed  |  32  | signed 2's complement S15.16 scaled integer|
  --------------------------------------------------------------
  | clampx |  32  | S15.16 scaled integer clamped to [0, 1]    |
  --------------------------------------------------------------

  and the count of the number of rows in the text is changed to 16.

  Add paragraph

  The mapping of GL data types to data types of a specific
  language binding are part of the language binding definition and
  may be platform-dependent.  Type conversion and type promotion
  behavior when mixing actual and formal arguments of different
  data types are specific to the language binding and platform.
  For example, the C language includes automatic conversion
  between integer and floating-point data types, but does not
  include automatic conversion between the int and fixed or
  float and fixed GL types since the fixed data type is not a
  distinct built-in type.  Regardless of language binding,
  the enum type converts to fixed-point without scaling and
  integer types are converted by multiplying by 2^16.



Section 2.7 Vertex Specification

  Commands are revised to included 'x' suffix.

Section 2.8 Vertex Arrays

  Table 2.4 Vertex Array Sizes is revised to include the 'fixed' type
  for all commands except EdgeFlagPointer.

  References to Vertex command suffixes are revised to include 'x'.

Section 2.9 Rectangles

  Revise to include 'x' suffix.

Section 2.10 Coordinate Transformations

  Revise to include 'x' suffix.  Section 2.10.1 describes clampx.
  Add alternate suffixed versions of Ortho and Frustum.

Section 2.11 Clipping

  Add alternate suffixed version of ClipPlane.

Section 2.12 Current Raster Position

  Revise to include 'x' suffix.

Section 2.13 Colors and Coloring

  Revise to include 'x' suffix and
  Table 2.6 is modified to include row:

  ---------------
  | fixed |  c  |
  ---------------

Section 3.3 Points

  Add alternate suffixed PointSize command.

Section 3.4 Line Segments

  Add alternate suffixed LineWidth command.

Section 3.5 Polygons

  Add alternate suffixed PolygonOffset command.

Section 3.6 Pixel Rectangles

  Revise to include 'x' suffix on PixelStore, PixelTransfer, PixelMap,
  ConvolutionParameter.

  Table 3.5 is modified to include row:

  ----------------------
  | FIXED | fixed | No |
  ----------------------

  Add alternate suffixed PixelZoom to Section 3.6.5

Section 3.7 Bitmaps

  Add alternate suffixed Bitmap command.

Section 3.8 Texturing

  Revise to include 'x' suffix in TexParameter (Section 3.8.4).

  Add alternate suffixed PrioritizeTextures command (Section 3.8.11).

  Revise to include 'x' suffix in TexEnv (Section 3.8.12).

Section 3.10 Fog

  Revise to include ;x; suffix in Fog command.

Section 4.1 Fragment Operations

  Add alternate suffixed SampleCoveragex (Section 4.1.3), AlphaFunc
  (Section 4.1.4), and BlendColor (Section 4.1.7) commands.

Section 4.2 Whole Framebuffer Operations

  Add alternate suffixed ClearColor, ClearDepth, and ClearAccum commands
  (Section 4.2.3).

  Add alternate suffixed Accum command (Section 4.2.4).

Section 5.1 Evaluators

  Revise to include 'x' suffix on Map1, Map2, Map1Grid, and Map2Grid
  commands.

Section 5.3 Feedback

  Add alternate suffixed FeedbackBuffer and PassThrough commands.
  Revise Figure 5.2 to indicate 'f' values may also be 'x' values.

  Add GetFixedv to Section 6.1.1.  Revise Section 6.1.2 to
  include implied conversions for GetFixedv.

  Revise to include 'x' suffix for GetClipPlane, GetLightm GetMaterial,
  GetTexEnv, GetTexGen, GetTexParameter, GetTexLevelParameter,
  GetPixelMap, and GetMap in Section 6.1.3.

  Revise to include 'x' suffix for GetHistogramParameter (Section 6.1.9).

Section 6.2 State Tables

  Revise intro paragraph to include GetFixedv.

None

None

None

None

The data representation is client-side only.  The GLX layer
performs translation between fixed and float representations.

Fixed type entry points are mapped on the client-side to the
appropriate floating-point command protocol.  To preserve precision,
double-precision protocol is encouraged, but not required.

None

None

None

12/15/2002    0.1
    - Original draft.

03/31/2003    0.2
    - Corrected a typo in GetClipPlanex and FIXED_OES.

04/24/2003    0.3
    - Added clarification that enums must be converted to fixed
      by scaling when passed in a fixed parameter type.  Corrected
      some typos.

05/29/2003    0.4
    - Changed enums to be passed unscaled when passed to a
      fixed formal parameter.

07/08/2003    0.5
    - Removed bogus Dependencies on section
    - Added extension number and enumerant value

07/11/2003    0.6
    - Added OES suffixes

07/12/2003    0.7
    - Added note about GLX protocol

06/16/2004    0.8
    - Added ClipPlanex, and various Get functions

04/27/2015    1.0 (Jon Leech)
    - Replace SampleCoverageOES with SampleCoveragexOES, to match the
      specfile / headers (Bug 13591).