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

Name

    ARB_clear_buffer_object

Name Strings

    GL_ARB_clear_buffer_object

Contact

    Graham Sellers (graham.sellers 'at' amd.com)

Contributors

    Jon Leech
    Piers Daniell, NVIDIA
    Mark Kilgard, NVIDIA

Notice

    Copyright (c) 2012-2014 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: February 18, 2014
    Version: 13

Number

    ARB Extension #121

Dependencies

    OpenGL 1.5 is required.

    The definition of this extension is dependent on EXT_direct_state_access.

    This extension is written against the OpenGL 4.2 (Core) Specification.

Overview

    Buffer objects are fundamental to the operation of OpenGL. Buffers are used
    as a source of data for vertices and indices, read through buffer textures
    in shaders, used to transfer texture and image data into and out of
    textures and framebuffers, and may be written to by operations such as
    transform feedback. OpenGL contains mechanisms to copy sections of buffers
    from one to another, but it has no mechanism to initialize the content
    of a buffer to a known value. In effect, it has memcpy, but not memset.

    This extension adds such a mechanism and has several use cases. Examples
    include clearing a pixel unpack buffer before transferring data to
    a texture or resetting buffer data to a known value before sparse updates
    through shader image stores or transform feedback.

IP Status

    No known IP claims.

New Procedures and Functions

        void ClearBufferData(enum target,
                             enum internalformat,
                             enum format,
                             enum type,
                             const void * data);

        void ClearBufferSubData(enum target,
                                enum internalformat,
                                intptr offset,
                                sizeiptr size,
                                enum format,
                                enum type,
                                const void * data);

    When EXT_direct_state_access is present:

        void ClearNamedBufferDataEXT(uint buffer,
                                     enum internalformat,
                                     enum format,
                                     enum type,
                                     const void * data);

        void ClearNamedBufferSubDataEXT(uint buffer,
                                        enum internalformat,
                                        intptr offset,
                                        sizeiptr size,
                                        enum format,
                                        enum type,
                                        const void * data);

New Tokens

    None.

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

Append to the end of Section 2.9.2, "Creating Buffer Object Stores"

    To fill all or part of an existing buffer object's data store with a
    constant value, call

        void ClearBufferSubData(enum target,
                                enum internalformat,
                                sizeiptr offset,
                                sizeiptr size,
                                enum format,
                                enum type,
                                const void * data);

    with <target> set to the target to which the destination buffer is bound.
    <target> must be one of the targets listed in Table 2.8.
    <internalformat> must be set to one of the format tokens listed in Table
    3.15, "Internal formats for buffer textures". <format> and <type> specify
    the format and type of the source data and are interpreted as described in
    Section 3.7.2. <offset> set to the offset, measured in basic
    machine units, into the buffer object's data store from which to begin
    filling, and <size> set to the size, also in basic machine units, of the
    range to fill. Both <offset> and <range> must be multiples of the number
    of basic machine units per-element for that internal format specified by
    <internalformat>, otherwise the error INVALID_VALUE is generated.
    <data> is a pointer to an array of between one and four components
    containing the data to be used as the source of the constant fill value.
    The elements of <data> are converted by the GL into the format specified by
    <internalformat> in the manner described in section 2.3.1, and then used to
    fill the specified range of the destination buffer. If <data> is NULL, then
    the pointer is ignored and the sub-range of the buffer is filled with zeros.

    If <offset> or <size> is less than zero, or if <offset> + <size> is
    greater than the value of BUFFER_SIZE for the buffer bound to <target>
    then the error INVALID_VALUE is generated. The command

    An INVALID_OPERATION error is generated if any part of the specified
    range of the buffer bound to <target> is currently mapped.

        void ClearBufferData(enum target,
                             enum internalformat,
                             enum format,
                             enum type,
                             const void * data);

    is equivalent to calling ClearBufferSubData with <target>,
    <internalformat> and <data> as specified, with <offset> set to zero,
    and <size> set to the value of BUFFER_SIZE for the buffer bound to
    <target>.

        The commands:

        void ClearNamedBufferDataEXT(uint buffer,
                                     enum internalformat,
                                     enum format,
                                     enum type,
                                     const void * data);

    and

        void ClearNamedBufferSubDataEXT(uint buffer,
                                        enum internalformat,
                                        sizeiptr offset,
                                        sizeiptr size,
                                        enum format,
                                        enum type,
                                        const void * data);

    are equivalent to calling ClearBufferData and ClearBufferSubData,
    respectively, except that the buffer object to be accessed is specified
    in the <buffer> parameter rather than being derived from the <target>
    buffer binding point.

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

    None.

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

    None.

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

    None.

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

    None.

Errors

    INVALID_ENUM is generated by ClearBufferSubData if <internalformat>
    is not one of the sized internal format identifiers listed in Table 3.15.

    INVAILD_ENUM is generated by ClearBufferSubData <target> is not a legal
    buffer binding point.

    INVALID_ENUM is generated by ClearBufferSubData if <format> or <type> is
    not one of the supported format or type tokens.

    INVALID_VALUE is generated by ClearBufferSubData if <offset>
    or <size> is less than zero.

    INVALID_VALUE is generated by ClearBufferSubData if no buffer is bound
    to the binding point indicated by <target>.

    INVALID_VALUE is generated by ClearBufferSubData if <offset> +
    <size> is greater than the value of BUFFER_SIZE for the buffer bound to
    <target>.

    INVALID_VALUE is generated by ClearBufferSubData if <offset> or <size>
    is not an integer multiple of the element size indicated by
    <internalformat>. The element size is the number of components for
    <internalformat> from table 3.15 multiplied by the size of the base type
    for <internalformat> in that table.

    INVALID_OPERATION is generated by ClearBufferSubData if any part of the
    specified range of the buffer bound to <target> is currently mapped.

New State

    None.

Dependencies on EXT_direct_state_access

    If EXT_direct_state_access is not supported, then remove all references to
    ClearNamedBufferDataEXT and ClearNamedBufferSubDataEXT.

Conformance Tests

    TBD

Issues

    1) Do we need to have restrictions on the alignment of <offset> and/or
       <size> for ClearBufferSubData

       RESOLVED: Yes, we restrict both <offset> and <size> to be integer
       multiples of the element size for the format indicated by
       <internalformat>.

    2) Should the ClearBufferObject take int/float/uint types, or take
       format + type poarameters more like glTexImage2D etc.?

       RESOLVED: ClearBufferSubData takes an <internalformat> parameter
       to indicate the internal storage format for the buffer, and
       a <format> and <type> parameter for the application-supplied data.
       This is consistent with APIs such as TexSubImagenD.

    3) Currently, the legal tokens for <internalformat> are taken from the
       texture internal format types in table 3.12. Is this sufficient?
       Do we need to also allow other formats such as those in table 3.22
       (image formats), or table 3.2 (packed pixel formats).

       RESOLVED: Updated in revision 4 to use table 3.15, which is actually
       more concise than 3.12. However, it represents the complete list
       of formats that are reasonably easily filled by existing hardware.
       If the application bit-packs other formats, this should be sufficient
       for the intended use-cases of this extension.

    4) Do we want DSA-style ClearNamedBufferSubData, ClearNamedBufferData?

       RESOLVED: Yes. Documented dependency on EXT_dsa.

    5) How do we specify data formats that are not supported for buffer
       textures - for example, R3_G3_B2 or RGB10_A2?

       RESOLVED: It is the application's responsibility to bit-pack the
       components of the source data into a number of native types (unsigned
       bytes, shorts or ints), and then pass them using a supported internal
       format.

Revision History

    Rev.  Date        Author    Changes
    ----  ----------  --------  ---------------------------------------------
    13    02/18/2014  Jon Leech Change order of ClearBufferSubData arguments
                                in spec body to be consistent with New
                                Procedures declaration ((offset,size,format,
                                type) instead of the erroneous (format,type,
                                offset,size)) (Public Bug 1122).

    12    12/12/2013  Jon Leech Change order of ClearNamedBufferSubDataEXT
                                arguments in spec body to be consistent with
                                New Procedures declaration ((offset,
                                size,format,type) instead of the erroneous
                                (format,type,offset,size)) (Bug 11378).

    11    08/07/2013  mjk       Better indicate DSA entrypoints

    10    09/12/2012  Jon Leech Modify error condition when the target buffer
                                is mapped to only be generated when the
                                mapped region intersects the region being
                                cleared (bug 9343).

     9    07/25/2012  Jon Leech Fix typos from bug 8935.

     8    07/23/2012  Jon Leech Clarify offset/alignment constraints as
                                based on the total size of a texel in
                                <internalformat>.

     7    06/28/2012  pdaniell  Modify the parameter order of the *SubData
                                functions to match the ordering of
                                TexSubImage parameters. Also change the
                                <offset> parameter to intptr.

     6    05/29/2012  Jon Leech Fix capitalization of <internalformat>.

     5    05/15/2012  Jon Leech Fix typo in error condition.

     4    04/26/2012  gsellers  Add interaction with EXT_dsa, resolve issue 4.
                                Document <format> and <type> parameters.
                                Correct reference to Table 3.15 (Internal
                                formats for buffer textures).
                                Resolve issue 3. Add issue 5.
                                Change behavior of NULL for <data> to fill the
                                buffer subrange with zeros.
     3    04/02/2012  gsellers  Delete 'either/or' approach.
                                Change API to texture-like ClearBufferSubData.
                                Resolve issues (1) + (2).
                                Address feedback from bug 8132.
                                Add issues (3) and (4).
     2    12/19/2011  gsellers  Rename to ARB. Strip suffixes from APIs.
                                Add format + type versions of APIs for
                                consideration. Allow NULL for <data> in
                                ClearBufferRange.
     1    09/27/2011  gsellers  Initial draft