xref: /third_party/openGLES/extensions/ARB/ARB_framebuffer_no_attachments.txt

Name

    ARB_framebuffer_no_attachments

Name Strings

    GL_ARB_framebuffer_no_attachments

Contact

    Pat Brown, NVIDIA (pbrown 'at' nvidia.com)

Contributors

    Members of the Khronos OpenGL ARB TSG

Notice

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

Specification Update Policy

    Khronos-approved extension specifications are updated in response to
    issues and bugs prioritized by the Khronos OpenGL 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

Status

    Complete.
    Approved by the ARB on 2012/06/12.

Version

    Last Modified Date:         May 7, 2015
    Revision:                   5

Number

    ARB Extension #130

Dependencies

    OpenGL 3.0 or ARB_framebuffer_object is required.

    This extension is written against the OpenGL 4.2 (Compatibility Profile)
    Specification (January 19, 2012).

    This extension interacts with OpenGL 3.0 and EXT_texture_array.

    This extension interacts with EXT_direct_state_access.

Overview

    Framebuffer objects as introduced by ARB_framebuffer_object and OpenGL 3.0
    provide a generalized mechanism for rendering to off-screen surfaces.
    Each framebuffer object may have depth, stencil and zero or more color
    attachments that can be written to by the GL.  The size of the framebuffer
    (width, height, layer count, sample count) is derived from the attachments
    of that framebuffer.  In unextended OpenGL 4.2, it is not legal to render
    into a framebuffer object that has no attachments.  Such a framebuffer
    would be considered incomplete with the
    FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT status.

    With OpenGL 4.2 and ARB_shader_image_load_store, fragment shaders are
    capable of doing random access writes to buffer and texture memory via
    image loads, stores, and atomics.  This ability enables algorithms using
    the conventional rasterizer to generate a collection of fragments, where
    each fragment shader invocation will write its outputs to buffer or
    texture memory using image stores or atomics.  Such algorithms may have no
    need to write color or depth values to a conventional framebuffer.
    However, a framebuffer with no attachments will be considered incomplete
    and no rasterization or fragment shader exectuion will occur.  To avoid
    such errors, an application may be required to create an otherwise
    unnecessary "dummy" texture and attach it to the framebuffer (possibly
    with color writes masked off).  If the algorithm requires the rasterizer
    to operate over a large number of pixels, this dummy texture will
    needlessly consume a significant amount of memory.

    This extension enables the algorithms described above to work even with a
    framebuffer with no attachments.  Applications can specify default width,
    height, layer count, and sample count parameters for a framebuffer object.
    When a framebuffer with no attachments is bound, it will be considered
    complete as long as the application has specified non-zero default width
    and height parameters.  For the purposes of rasterization, the framebuffer
    will be considered to have a width, height, layer count, and sample count
    derived from its default parameters.  Framebuffers with one or more
    attachments are not affected by these default parameters; the size of the
    framebuffer will still be derived from the sizes of the attachments in
    that case.

    Additionally, this extension provides queryable implementation-dependent
    maximums for framebuffer width, height, layer count, and sample count,
    which may differ from similar limits on textures and renderbuffers.  These
    maximums will be used to error-check the default framebuffer parameters
    and also permit implementations to expose the ability to rasterize to an
    attachment-less framebuffer larger than the maximum supported texture
    size.

IP Status

    No known IP claims.

New Procedures and Functions

    void FramebufferParameteri(enum target, enum pname, int param);
    void GetFramebufferParameteriv(enum target, enum pname, int *params);

    (the following two commands are supported only if EXT_direct_state_access
    is supported)

    void NamedFramebufferParameteriEXT(uint framebuffer, enum pname,
                                       int param);
    void GetNamedFramebufferParameterivEXT(uint framebuffer, enum pname,
                                       int *params);

New Tokens

    Accepted by the <pname> parameter of FramebufferParameteri,
    GetFramebufferParameteriv, NamedFramebufferParameteriEXT, and
    GetNamedFramebufferParameterivEXT:

        FRAMEBUFFER_DEFAULT_WIDTH                       0x9310
        FRAMEBUFFER_DEFAULT_HEIGHT                      0x9311
        FRAMEBUFFER_DEFAULT_LAYERS                      0x9312
        FRAMEBUFFER_DEFAULT_SAMPLES                     0x9313
        FRAMEBUFFER_DEFAULT_FIXED_SAMPLE_LOCATIONS      0x9314

    Accepted by the <pname> parameter of GetIntegerv, GetBooleanv,
    GetInteger64v, GetFloatv, and GetDoublev:

        MAX_FRAMEBUFFER_WIDTH                           0x9315
        MAX_FRAMEBUFFER_HEIGHT                          0x9316
        MAX_FRAMEBUFFER_LAYERS                          0x9317
        MAX_FRAMEBUFFER_SAMPLES                         0x9318


Additions to Chapter 2 of the OpenGL 4.2 (Compatibility Profile) Specification
(OpenGL Operation)

    None.

Additions to Chapter 3 of the OpenGL 4.2 (Compatibility Profile) Specification
(Rasterization)

    None.

Additions to Chapter 4 of the OpenGL 4.2 (Compatibility Profile) Specification
(Per-Fragment Operations and the Frame Buffer)

    Modify Section 4.4.1, Binding and Managing Framebuffer Objects, p. 425

    (add to third-to-last bullet, p. 427)

    * If the attachment sizes are not identical, ...  for each attachment).
      if there are no attachments, rendering will be limited to a rectangle
      having a lower left of (0,0) and an upper right of (width, height),
      where <width> and <height> are the framebuffer object's default width
      and height.

    (add to next-to-last bullet, p. 427)

    * If the number of layers of each attachment are not identical, ... of any
      attachment.  If there are no attachments, the number of layers will be
      taken from the framebuffer object's default layer count.

    (insert before the last paragraph of the section , p. 428)

    Parameters of a framebuffer object are set using the command

      void FramebufferParameteri(enum target, enum pname, int param);

    <target> must be DRAW_FRAMEBUFFER, READ_FRAMEBUFFER, or FRAMEBUFFER.
    FRAMEBUFFER is equivalent to DRAW_FRAMEBUFFER. <pname> specifies the
    parameter of the framebuffer object bound to target to set. An
    INVALID_OPERATION error is generated if the default (zero) framebuffer
    object is bound to <target>.

    When a framebuffer has one or more attachments, the width, height, layer
    count (section 4.4.7), sample count, and sample location pattern of the
    framebuffer are derived from the properties of the framebuffer
    attachments.  When the framebuffer has no attachments, these properties
    are taken from framebuffer parameters.  When <pname> is
    FRAMEBUFFER_DEFAULT_WIDTH, FRAMEBUFFER_DEFAULT_HEIGHT,
    FRAMEBUFFER_DEFAULT_LAYERS, FRAMEBUFFER_DEFAULT_SAMPLES, or
    FRAMEBUFFER_DEFAULT_FIXED_SAMPLE_LOCATIONS, the value in <param> specifies
    the width, height, layer count, sample count, or sample location pattern,
    repsectively, used when the framebuffer has no attachments.  The error
    INVALID_VALUE will be generated if <param> is less than zero or greater
    the implementation-dependent limits MAX_FRAMEBUFFER_WIDTH,
    MAX_FRAMEBUFFER_HEIGHT, MAX_FRAMEBUFFER_LAYERS, MAX_FRAMEBUFFER_SAMPLES if
    <pname> is FRAMEBUFFER_DEFAULT_WIDTH, FRAMEBUFFER_DEFAULT_HEIGHT,
    FRAMEBUFFER_DEFAULT_LAYERS, or FRAMEBUFFER_DEFAULT_SAMPLES, respectively.

    When a framebuffer has no attachments, it is considered layered (section
    4.4.7) if and only if the value of FRAMEBUFFER_DEFAULT_LAYERS is non-zero.
    It is considered to have sample buffers if and only if the value of
    FRAMEBUFFER_DEFAULT_SAMPLES is non-zero.  The number of samples in the
    framebuffer is derived from the value of FRAMEBUFFER_DEFAULT_SAMPLES in an
    implementation-dependent manner similar to that described for the command
    RenderbufferStorageMultisample (section 4.4.2).  If the framebuffer has
    sample buffers, if the value of FRAMEBUFFER_DEFAULT_FIXED_SAMPLE_LOCATIONS
    is non-zero, it is considered to have a fixed sample location pattern as
    described for TexImage2DMultisample (section 3.10.6).

    The command

      void NamedFramebufferParameteriEXT(uint framebuffer, enum pname,
                                         int param);

    operates exactly like FramebufferParameteri, except that it modifies
    parameters of the framebuffer object named by <framebuffer> instead of a
    specified bound framebuffer object.  The error INVALID_VALUE is generated
    if <framebuffer> is not a name returned by GenFramebuffers.  If a
    framebuffer object named <framebuffer> does not yet exist, it will be
    created.


    Modify Section 4.4.4, Framebuffer Completeness, p. 439

    (modify second bullet in the list of required conditions for attachment
    completeness in "Framebuffer Attachment Completeness", p. 440)

    * The width and height of <image> are greater than zero and are less than
      or equal to the implementation-dependent limits MAX_FRAMEBUFFER_WIDTH
      and MAX_FRAMEBUFFER_HEIGHT, respectively.

    (delete the third and fourth bullets in the list, replacing with new
    bullets at the end of the list)

    (add new bullets to the end of the list, p. 441)

    * If <image> is a three-dimensional, one- or two-dimensional array, or
      cube map array texture and the attachment is not layered, the selected
      layer is less than the depth or layer count of the texture.

    * If <image> is a three-dimensional, one- or two-dimensional array, or
      cube map array texture and the attachment is layered, the depth or
      layer count of the texture is less than or equal to the
      implementation-dependent limit MAX_FRAMEBUFFER_LAYERS.

    * If <image> has multiple samples, its sample count is less than or equal
      to the implementation-dependent limit MAX_FRAMEBUFFER_SAMPLES.

    (modify third bullet of "Whole Framebuffer Completeness", p. 441)

    * There is at least one image attached to the framebuffer, or the
      framebuffer's FRAMEBUFFER_DEFAULT_WIDTH and FRAMEBUFFER_DEFAULT_HEIGHT
      parameters are both non-zero.

      { FRAMEBUFFER_INCOMPLETE_MISSING_ATTACHMENT }


Additions to Chapter 5 of the OpenGL 4.2 (Compatibility Profile) Specification
(Special Functions)

    None.

    (NOTE:  GetFramebufferParameteriv is not compiled in a display list, but
    no spec language is required due to the blanket language covering all Get*
    commands.)

Additions to Chapter 6 of the OpenGL 4.2 (Compatibility Profile) Specification
(State and State Requests)

    Modify Section 6.1.19, Framebuffer Object Queries, p. 501

    (add to end of the section, p. 504)

    The command

      void GetFramebufferParameteriv(enum target, enum pname, int *params)

    returns the values of the framebuffer parameter <pname> of the framebuffer
    object bound to <target>.

    <target> must be DRAW_FRAMEBUFFER, READ_FRAMEBUFFER, or FRAMEBUFFER.
    FRAMEBUFFER is equivalent to DRAW_FRAMEBUFFER. <pname> specifies the
    parameter of the framebuffer object bound to target to return. An
    INVALID_OPERATION error is generated if the default (zero) framebuffer
    object is bound to <target>.

    The command

      void GetNamedFramebufferParameterivEXT(uint framebuffer, enum pname,
                                             int *params);

    operates exactly like GetFramebufferParameteriv, except that it queries
    parameters of the framebuffer object named by <framebuffer> instead of a
    specified bound framebuffer object.  The error INVALID_VALUE is generated
    if <framebuffer> is not a name returned by GenFramebuffers.  If a
    framebuffer object named <framebuffer> does not yet exist, it will be
    created.


Additions to Appendix A of the OpenGL 4.2 (Compatibility Profile) Specification
(Invariance)

    None.

Additions to Appendix D of the OpenGL 4.2 (Compatibility Profile) Specification
(Shared Objects and Multiple Contexts)

    None.

Additions to the AGL/EGL/GLX/WGL Specifications

    None

GLX Protocol

   TBD

Dependencies on OpenGL 3.0 and EXT_texture_array

    If OpenGL 3.0 and EXT_texture_array are not supported, references to the
    framebuffer parameter FRAMEBUFFER_DEFAULT_LAYERS should be removed.

Dependencies on EXT_direct_state_access

    If EXT_direct_state_access is not supported, the commands
    NamedFramebufferParameteriEXT and GetNamedFramebufferParameterivEXT are
    not supported.

Errors

    The error INVALID_ENUM is generated by FramebufferParameteri and
    GetFramebufferParameteriv if <target> is not DRAW_FRAMEBUFFER,
    READ_FRAMEBUFFER, or FRAMEBUFFER.

    The error INVALID_OPERATION is generated by FramebufferParameteri and
    GetFramebufferParameteriv if the default (zero) framebuffer is bound to
    target.

    The error INVALID_VALUE is generated by FramebufferParameteri and
    NamedFramebufferParameteriEXT if <param> is less than zero or greater the
    implementation-dependent limits MAX_FRAMEBUFFER_WIDTH,
    MAX_FRAMEBUFFER_HEIGHT, MAX_FRAMEBUFFER_LAYERS, MAX_FRAMEBUFFER_SAMPLES if
    <pname> is FRAMEBUFFER_DEFAULT_WIDTH, FRAMEBUFFER_DEFAULT_HEIGHT,
    FRAMEBUFFER_DEFAULT_LAYERS, or FRAMEBUFFER_DEFAULT_SAMPLES, respectively.

    The error INVALID_VALUE is generated by NamedFramebufferParameteriEXT and
    GetNamedFramebufferParameterivEXT if <framebuffer> is not a name returned
    by GenFramebuffers.

New State

    Add to Table 6.33, Framebuffer (state per framebuffer object), p. 537

                                                        Initial
    Get Value                    Type  Get Command      Value   Description               Sec.   Attrib.
    ---------------------------- ----  ---------------  ------- ------------------------  -----  ---------
    FRAMEBUFFER_DEFAULT_WIDTH     Z+   GetFramebuffer-    0     default width of frame-   4.4.1     -
                                       Parameteriv              buffer w/o attachments
    FRAMEBUFFER_DEFAULT_HEIGHT    Z+   GetFramebuffer-    0     default height of frame-  4.4.1     -
                                       Parameteriv              buffer w/o attachments
    FRAMEBUFFER_DEFAULT_LAYERS    Z+   GetFramebuffer-    0     default layer count of    4.4.1     -
                                       Parameteriv              framebuffer w/o
                                                                attachments
    FRAMEBUFFER_DEFAULT_SAMPLES   Z+   GetFramebuffer-    0     default sample count of   4.4.1     -
                                       Parameteriv              framebuffer w/o
                                                                attachments
    FRAMEBUFFER_DEFAULT_FIXED_    B    GetFramebuffer-  FALSE   default sample location   4.4.1     -
      SAMPLE_LOCATIONS                 Parameteriv              pattern of framebuffer
                                                                w/o attachments


New Implementation Dependent State

    Get Value                         Type  Get Command    Minimum Value  Description                Sec.
    -----------------------           ----  -----------    -------------  -------------------------  -----
    MAX_FRAMEBUFFER_WIDTH             Z+    GetIntegerv    16384 (*)      maximum width for          4.4.1
                                                                          framebuffer object
    MAX_FRAMEBUFFER_HEIGHT            Z+    GetIntegerv    16384 (*)      maximum height for         4.4.1
                                                                          framebuffer object
    MAX_FRAMEBUFFER_LAYERS            Z+    GetIntegerv    2048 (*)       maximum layer count for    4.4.1
                                                                          layered framebuffer object
    MAX_FRAMEBUFFER_SAMPLES           Z+    GetIntegerv    4 (*)          maximum sample count for   4.4.1
                                                                          framebuffer object

    (*) Note:  These minimum values are the ones applicable to this extension
    on top of OpenGL 4.2 and higher.  The minimum values may be lower on
    implementations supporting only older versions of OpenGL.  For
    implementations supporting this extension on older versions, the minimums
    can be determined from the table below.

      the minimum for           is the minimum defined for
      -----------------------   --------------------------
      MAX_FRAMEBUFFER_WIDTH     MAX_TEXTURE_SIZE
      MAX_FRAMEBUFFER_HEIGHT    MAX_TEXTURE_SIZE
      MAX_FRAMEBUFFER_LAYERS    MAX_ARRAY_TEXTURE_LAYERS
      MAX_FRAMEBUFFER_SAMPLES   MAX_SAMPLES

Issues

    (1) Should we specify the default framebuffer parameters in one command or
        via separate FramebufferParameter* commands?

      RESOLVED:  Separate parameters provide for a more future-proof API, in
      case we need new defaults in the future.

    (2) Should the default framebuffer parameters affect only framebuffers
        with no attachments?

      RESOLVED:  As specified, they affect only framebuffers with no
      attachments.

      Alternately, one could have treated these default parameters as
      specifying an extra unusable attachment whose values would be used in
      various intersection/consistency tests.  In that approach, if a
      framebuffer had a single attachment and default parameters were also
      specified:

        * the renderable area would be the intersection of the rectangle/layer
          count derived from the attachment and the rectangle/layer count from
          the framebuffer defaults;

        * the sample count and fixed sample location state would have to match
          between the attachment and framebuffer default.

      This specification is not using such an "intersection" approach, which
      doesn't seem to introduce significant value.

    (3) Should we check the default framebuffer parameters against
        implementation-dependent limits when they are specified, when testing
        for completeness, or both?

      RESOLVED:  We will expose implementation-dependent limits on the maximum
      framebuffer width, height, layer count, and sample count, and check the
      values passed the FramebufferParameteri against them.

      As specified, implementations are required to support all legal
      combinations of default framebuffer width, height, sample count, and
      layer count as long as they are under their respective implementation
      limits.  This requirement could be a problem if a hypothetical
      implementation could support larger values for one default parameter as
      long as others stayed small.  For example, if an implementation could
      support a 64Kx64K single-sample framebuffer, but could only support a
      16Kx16K framebuffer with 8 samples, this extension would only permit
      them to expose a maximum width/height of 16K.  The most obvious way to
      support this would be to add a feature allowing larger default sizes,
      but treating a framebuffer with an unsupported combination (e.g.,
      64Kx64K at 8xAA) as incomplete.  Such a capability will not be
      incorporated into this extension, however.

    (4) How do the new implementation-dependent limits for maximum framebuffer
        width, height, layer count, and sample count affect framebuffers with
        attachments?

      RESOLVED:  If implementation limits permit the creation of attachable
      surfaces larger than the maximum framebuffer size, such images will be
      considered not to be framebuffer attachment complete.  We don't expect
      this to be a common case, as the minimum maximums for framebuffer sizes
      equals the minimum maximums for texture sizes.

    (5) The ClampColor setting FIXED_ONLY depends on the framebuffer.  How is
        this value intepreted in a framebuffer with no attachments?

      RESOLVED:  Given current spec language, clamping should be enabled in
      this case, as there are no enabled color buffers with non-fixed-point
      components:

        If clamp is FIXED_ONLY, fragment color clamping is enabled if
        all enabled color buffers have fixed-point components.

      This isn't really a new issue in this extension; it could also arise
      when using a complete framebuffer with no color attachments.

      Note that this issue has no effect on the core profile of OpenGL.
      CLAMP_VERTEX_COLOR and CLAMP_FRAGMENT_COLOR are compatibility-only.
      CLAMP_READ_COLOR has no effect as ReadPixels will always generate an
      error due to the lack of framebuffer attachments.

    (6) What should be returned on the compatibility profile queries of
        RED_BITS, GREEN_BITS, BLUE_BITS, and ALPHA_BITS on a framebuffer with
        no attachments?

      RESOLVED:  Zero should be returned, which is also the case for
      DEPTH_BITS and STENCIL_BITS.  As in issue (5), this isn't a new issue in
      this spec.

Revision History

    Revision 5, May 7, 2015 (Jon Leech)
      - Restore missing cube map arrays to new framebuffer attachment
        completeness conditions (Bug 11201).

    Revision 4, September 12, 2012 (Jon Leech)
      - Clarify legal <target> values (Bug 9344).

    Revision 3, June 4, 2012 (pbrown)
      - Mark issues (4) through (6) as resolved.

    Revision 2, June 1, 2012 (pbrown)
      - Add new implementation-dependent limits on framebuffer width, height,
        layer count, and sample count.
      - Assign enumerant values for all the new tokens.
      - Specify that the default framebuffer parameters are error-checked
        against the new implementation limits.
      - Add new checks treating framebuffer attachments as incomplete in the
        unlikely event that they exceed the new implementation limits.
      - Mark issues (1) through (3) as resolved.
      - Add new issues (4) through (6).
      - Add overview text.

    Revision 1, May 14, 2012 (pbrown)
      - Initial revision, for discussion purposes.