EXT_color_buffer_half_float

GL_EXT_color_buffer_half_float

Contributors to ARB_framebuffer_object and ARB_color_buffer_float
desktop OpenGL extensions from which this extension borrows heavily

Benj Lipchak, Apple (lipchak 'at' apple.com)

Complete

Date: September 26, 2017
Revision: 10

OpenGL ES Extension #97

Requires OpenGL ES 2.0.

Written based on the wording of the OpenGL ES 2.0.25 Full Specification
(November 2, 2010).

OES_texture_half_float affects the definition of this extension.

EXT_texture_rg affects the definition of this extension.

APPLE_framebuffer_multisample affects the definition of this extension.

This extension allows 16-bit floating point formats as defined in
OES_texture_half_float to be rendered to via framebuffer objects.

When using floating-point formats, certain color clamps are disabled.

This extension also updates the framebuffer object API to allow querying
attachment component types.

None

Accepted by the <internalformat> parameter of RenderbufferStorage and
RenderbufferStorageMultisampleAPPLE:

    RGBA16F_EXT                                  0x881A
    RGB16F_EXT                                   0x881B
    RG16F_EXT                                    0x822F
    R16F_EXT                                     0x822D

Accepted by the <pname> parameter of GetFramebufferAttachmentParameteriv:

    FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE_EXT    0x8211

Returned in <params> by GetFramebufferAttachmentParameteriv:

    UNSIGNED_NORMALIZED_EXT                      0x8C17

None

Modify Section 3.8.2 (Shader Execution), p. 87

(modify Shader Outputs, first paragraph, p. 89) ...These are gl_FragColor
and gl_FragData[0]. If the color buffer has fixed-point format, color
values are converted to fixed-point as described in section 2.1.2 for
framebuffer color components; otherwise no type conversion is applied.

Modify Chapter 4 Introduction, p. 90

(modify second paragraph, p. 91) Each pixel in a color buffer consists of
up to four color components. The four color components are named R, G, B,
and A, in that order; color buffers are not required to have all four color
components. R, G, B, and A components may be represented as unsigned
normalized fixed-point or floating-point values; all components must have
the same representation. The number of bitplanes...

Modify Section 4.1.3 (Multisample Fragment Operations), p. 93

(modify third paragraph, p. 93) ...and all 0's corresponding to all alpha
values being 0. The alpha values used to generate a coverage value are
clamped to the range [0,1]. It is also intended...

Modify Section 4.1.6 (Blending), p. 96

(modify second paragraph, p. 96) Source and destination values are combined
according to the blend equation, quadruplets of source and destination
weighting factors determined by the blend functions, and a constant blend
color to obtain a new set of R, G, B, and A values, as described below.

If the color buffer is fixed-point, the components of the source and
destination values and blend factors are clamped to [0, 1] prior to
evaluating the blend equation. If the color buffer is floating-point, no
clamping occurs. The resulting four values are sent to the next operation.

(modify fifth paragraph, p. 97) Fixed-point destination (framebuffer)
components are represented as described in section 2.1.2. Constant color
components, floating-point destination components, and source
(fragment) components are taken to be floating-point values. If source
components are represented internally by the GL as fixed-point values they
are also interpreted according to section 2.1.2.

(modify Blend Color section removing the clamp, p. 98) The constant color
C_c to be used in blending is specified with the command

   void BlendColor(float red, float green, float blue, float alpha);

The constant color can be used in both the source and destination blending
functions.

Replace Section 4.1.7 (Dithering), p. 100

Dithering selects between two representable color values. A representable
value is a value that has an exact representation in the color buffer.
Dithering selects, for each color component, either the largest
representable color value (for that particular color component) that is
less than or equal to the incoming color component value, c, or the
smallest representable color value that is greater than or equal to c. The
selection may depend on the x_w and y_w coordinates of the pixel, as well
as on the exact value of c. If one of the two values does not exist, then
the selection defaults to the other value.

Many dithering selection algorithms are possible, but an individual
selection must depend only on the incoming component value and the
fragment's x and y window coordinates.  If dithering is disabled, then each
incoming color component c is replaced with the largest representable color
value (for that particular component) that is less than or equal to c, or
by the smallest representable value, if no representable value is less than
or equal to c.

Dithering is enabled with Enable and disabled with Disable using the
symbolic constant DITHER. The state required is thus a single bit.
Initially dithering is enabled.

Modify Section 4.2.3 (Clearing the Buffers), p. 103

(modify second paragraph, p. 103, removing clamp of clear color)

   void ClearColor(float r, float g, float b, float a);

sets the clear value for the color buffer. The specified components are
stored as floating-point values.

(add to the end of fifth paragraph, p. 103) ...then a Clear directed at
that buffer has no effect. Fixed-point color buffers are cleared to color
values derived by clamping each component of the clear color to the range
[0,1], then converting to fixed-point according to section 2.1.2.

Modify Section 4.3.1 (Reading Pixels), p. 104

(modify first paragraph, p 104) ...Only two combinations of format and type
are accepted. The first varies depending on the format of the currently
bound rendering surface. For normalized fixed-point rendering surfaces,
the combination format RGBA and type UNSIGNED_BYTE is accepted. For
floating-point rendering surfaces, the combination format RGBA and type
FLOAT is accepted. The second is an implementation-chosen format...

(modify "Conversion of RGBA Values", p. 106)  The R, G, B, and A values
form a group of elements. For a fixed-point color buffer, each element is
converted to floating-point according to section 2.1.2. For a floating-
point color buffer, the elements are unmodified.

Add to Table 4.4, p. 106:

    type Parameter                 Component
    Token Name      GL Data Type   Conversion Formula
    --------------  -------------  ------------------
    HALF_FLOAT_OES  half           c = f

(modify "Final Conversion", p. 106) If type is not FLOAT or HALF_FLOAT_OES,
each component is first clamped to [0,1]. Then the appropriate conversion...

Add to Table 4.5, p. 117:

    Sized            Renderable        R     G     B     A     D     S
    Internal Format  Type              bits  bits  bits  bits  bits  bits
    ---------------  ----------------  ----  ----  ----  ----  ----  ----
    R16F_EXT         color-renderable  f16
    RG16F_EXT        color-renderable  f16   f16
    RGB16F_EXT       color-renderable  f16   f16   f16
    RGBA16F_EXT      color-renderable  f16   f16   f16   f16

(modify table description) Table 4.5: Renderbuffer image formats, showing
their renderable type (color-, depth-, or stencil-renderable) and the number
of bits each format contains for color (R, G, B, A), depth (D), and stencil
(S) components. The component resolution prefix indicates the internal data
type: f is floating-point, no prefix is unsigned normalized fixed-point.

None

Modify Section 6.1.3 (Enumerated Queries), p. 125

(modify second paragraph, p. 126) ...pname must be one of the following:
FRAMEBUFFER_ATTACHMENT_OBJECT_TYPE, FRAMEBUFFER_ATTACHMENT_OBJECT_NAME,
FRAMEBUFFER_ATTACHMENT_TEXTURE_LEVEL, FRAMEBUFFER_ATTACHMENT_TEXTURE_CUBE_-
MAP_FACE, or FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE_EXT.

(insert after fourth paragraph, p. 126) If the value of FRAMEBUFFER_-
ATTACHMENT_OBJECT_TYPE is not NONE, then

* If <pname> is FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE_EXT, <params> will
contain the type of components of the specified attachment, either FLOAT or
UNSIGNED_NORMALIZED_EXT for floating-point or unsigned fixed-point
components respectively.

If OES_texture_half_float is not supported, then all references to
RGBA16F_EXT, RGB16F_EXT, RG16F_EXT, R16F_EXT, HALF_FLOAT_OES and 
half should be ignored.

If OES_texture_half_float is supported, textures created with:

    <internalformat> = RGBA
    <format> = RGBA
    <type> = HALF_FLOAT_OES
    
are renderable.

If EXT_texture_rg is not supported, then all references to
RG16F_EXT and R16F_EXT should be ignored.

If APPLE_framebuffer_multisample is not supported, then all references to
RenderbufferStorageMultisampleAPPLE should be ignored.

None

(modify Table 6.24, "Framebuffer State")

Get Value                                    Type  Get Command                          Initial Value  Description        Section
-------------------------------------------  ----  -----------------------------------  -------------  -----------------  -------
FRAMEBUFFER_ATTACHMENT_COMPONENT_TYPE_EXT    Z_2   GetFramebufferAttachmentParameteriv  -              Data type of       6.1.3  
                                                                                                       components in the
                                                                                                       attached image

None

1. Should this extension add rendering to 32 bit floating-point formats?

   RESOLVED:  No. This extension only explicitly adds HALF_FLOAT_OES
   formats, as hardware implementations exist that support rendering to
   those formats but not 32 bit floating-point formats. Support for
   32 bit formats could be added by a layered extension.

2. Should this extension require specific floating-point formats?

   RESOLVED:  No. Although it is expected that all implementations
   supporting this extension support rendering to at least one
   HALF_FLOAT_OES format, applications must check framebuffer completeness
   to determine which formats are supported.

3. Should this extension add formats to RenderbufferStorageMultisampleAPPLE?

   RESOLVED:  Yes. Formats added to Table 4.5 for RenderbufferStorage are
   also accepted by RenderbufferStorageMultisampleAPPLE. However, there
   is no guarantee that floating-point multisample formats are renderable;
   applications must check framebuffer completeness to determine which
   multisample formats are supported.

4. Should clamping be automatically inferred based on the format of the
   color buffer?

   RESOLVED:  Yes. Previous extensions such as ARB_color_buffer_float
   support explicit vertex, fragment and read clamping controls. This
   extension does not:
   * The vertex clamp is not appropriate for ES where all varyings are
     generic.
   * The fragment clamp can be automatically inferred based on the format
     of the color buffer; manual clamping can also be performed in the
     fragment shader if desired.
   * The read clamp is not appropriate for ES where ReadPixels accepts a
     limited set of params; RGBA, UNSIGNED_BYTE will clamp, and RGBA,
     FLOAT or an implementation-chosen combination such as RGBA,
     HALF_FLOAT_OES will not clamp.

5. Should this extension modify the clamping of clear colors?

   RESOLVED:  Yes. The clear color is not clamped when specified. When
   clearing color buffers, the clear color is converted to the format of
   the color buffer.

6. How does this extension interact with multisample ALPHA_TO_COVERAGE,
   where an alpha value expected to be in the range [0,1] is turned into a
   set of coverage bits?

   RESOLVED: For the purposes of generating sample coverage from fragment
   alpha, the alpha values are effectively clamped to [0,1]. Negative alpha
   values correspond to no coverage; alpha values greater than one
   correspond to full coverage.

7. How does clamping affect the blending equation?

   RESOLVED:  The constant blend color is not clamped when specified. For
   fixed-point color buffers, the inputs and the result of the blending
   equation are clamped. For floating-point color buffers, no clamping
   occurs.

8. If certain colors in the OpenGL state vector were clamped in previous
   versions of the spec, but now have the clamping removed, do queries need
   to return clamped values for compatibility with older ES versions?

   RESOLVED:  No. Queries will return unclamped values.

9. Should CopyTex[Sub]Image be supported for floating-point formats?
    
   RESOLVED: Yes. OES_texture_half_float mentions in Issue 3 that this
   should not be allowed, but did not update the specification to error.
   Conversion between unsigned normalized and floating point formats
   is fully supported, subject to the existing constraints on adding
   components.

Rev.  Date     Author     Changes
----  -------- ---------  -----------------------------------------
  1   04/05/11  aeddy     Initial version based on ARB_fbo, ARB_cbf.
  2   04/09/11  aeddy     Added missing rows to Table 4.4.
  3   04/12/11  aeddy     Fixed typos.
  4   04/14/11  aeddy     Cleanup.
  5   04/27/11  aeddy     Update ReadPixels to accept RGBA, FLOAT.
  6   05/04/11  aeddy     Update Issue 9 resolution.
  7   06/15/11  benj      Update interactions.
  8   07/22/11  benj      Rename from APPLE to EXT.
  9   07/26/11  benj      Move content that belongs in OES_texture_float.
 10   09/26/17  tobias    Clarified creation of a renderable texture when OES_texture_half_float is supported