xref: /third_party/openGLES/extensions/EXT/EXT_buffer_storage.txt

Name

    EXT_buffer_storage

Name Strings

    GL_EXT_buffer_storage

Contact

    Daniel Koch, NVIDIA Corporation (dkoch 'at' nvidia.com)

Contributors

    Jonas Gustavsson, Sony Mobile
    Slawomir Grajewski, Intel
    Klaus Gerlicher, NVIDIA
    Contributors to ARB_buffer_storage

Notice

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

    Portions Copyright (c) 2014 NVIDIA Corporation.

Status

    Complete

Version

    Last Modified Date:   May 1, 2015
    Author Revision:      3

Number

    OpenGL ES Extension #239

Dependencies

    OpenGL ES 3.1 is required.

    This extension is written against the OpenGL ES 3.1 (June 4, 2014)
    Specification.

    The definition of this extension is affected by the presence of
    GL_EXT_direct_state_access.

Overview

    OpenGL ES has long supported buffer objects as a means of storing data
    that may be used to source vertex attributes, pixel data for textures,
    uniforms and other elements. In un-extended ES, buffer data stores
    are mutable - that is, they may be de-allocated or resized while they
    are in use. The GL_EXT_texture_storage extension added immutable storage
    for texture objects (and was subsequently incorporated into OpenGL ES 3.0).
    This extension further applies the concept of immutable storage to
    buffer objects. If an implementation is aware of a buffer's immutability,
    it may be able to make certain assumptions or apply particular
    optimizations in order to increase performance or reliability.

    Furthermore, this extension allows applications to pass additional
    information about a requested allocation to the implementation which it
    may use to select memory heaps, caching behavior or allocation strategies.

    Finally, this extension introduces the concept of persistent client
    mappings of buffer objects, which allow clients to retain pointers to a
    buffer's data store returned as the result of a mapping, and to issue
    drawing commands while those mappings are in place.

New Procedures and Functions

    void BufferStorageEXT(enum target,
                          sizeiptr size,
                          const void * data,
                          bitfield flags);

    When EXT_direct_state_access is present:

    void NamedBufferStorageEXT(uint buffer,
                               sizeiptr size,
                               const void * data,
                               bitfield flags);

New Tokens

    Accepted in the <flags> parameter of BufferStorageEXT and
    NamedBufferStorageEXT:

        MAP_READ_BIT                                0x0001 (existing)
        MAP_WRITE_BIT                               0x0002 (existing)
        MAP_PERSISTENT_BIT_EXT                      0x0040
        MAP_COHERENT_BIT_EXT                        0x0080
        DYNAMIC_STORAGE_BIT_EXT                     0x0100
        CLIENT_STORAGE_BIT_EXT                      0x0200

    Accepted as part of the <access> parameter to MapBufferRange:

        MAP_PERSISTENT_BIT_EXT                      0x0040 (as above)
        MAP_COHERENT_BIT_EXT                        0x0080 (as above)

    Accepted by the <pname> parameter of GetBufferParameter{i|i64}v:

        BUFFER_IMMUTABLE_STORAGE_EXT                0x821F
        BUFFER_STORAGE_FLAGS_EXT                    0x8220

    Accepted by the <barriers> parameter of MemoryBarrier:

        CLIENT_MAPPED_BUFFER_BARRIER_BIT_EXT        0x00004000

IP Status

    No known IP claims.

Additions to Chapter 2 of the OpenGL ES 3.1 Specification
(OpenGL ES Fundamentals)

    Insert before the last line of Section 2.6.2, "Buffer Objects", p. 24:

    Under certain circumstances, the data store of a buffer object may
    be shared between the client and server and accessed simultaneously
    by both.

Additions to Chapter 6 of the OpenGL ES 3.1 Specification (Buffer Objects)

    Modify Section 6.1 (Creating and Binding Buffer Objects)

    Append to Table 6.2, "Buffer object parameters and their values", p.49:

        +------------------------------+---------+---------+------------------+
        |                              |         | Initial | Legal            |
        | Name                         | Type    | Value   | Values           |
        +------------------------------+---------+---------+------------------+
        | BUFFER_IMMUTABLE_STORAGE_EXT | boolean | FALSE   | TRUE, FALSE      |
        | BUFFER_STORAGE_FLAGS_EXT     | int     | 0       | See section 6.2  |
        +------------------------------+---------+---------+------------------+


    Modify Section 6.2, (Creating and Modifying Buffer Object Data Stores),
    p. 57 as follows:

    The data store of a buffer object is created by calling

        void BufferStorageEXT(enum target,
                              sizeiptr size,
                              const void * data,
                              bitfield flags);

    with <target> set to one of the targets listed in Table 6.1, <size> set to
    the size of the data store in basic machine units and <flags> containing
    a bitfield describing the intended usage of the data store. The data
    store of the buffer object bound to <target> is allocated as a result of
    a call to this function and cannot be de-allocated until the buffer is
    deleted with a call to DeleteBuffers. Such a store may not be
    re-allocated through further calls to BufferStorageEXT or BufferData.

    <data> specifies the address in client memory of the data that should
    be used to initialize the buffer's data store. If <data> is NULL, the
    data store of the buffer is created, but contains undefined data.
    Otherwise, <data> should point to an array of at least <size> basic
    machine units.

    <flags> is the bitwise OR of flags describing the intended usage
    of the buffer object's data store by the application. Valid flags and
    their meanings are as follows:

        DYNAMIC_STORAGE_BIT_EXT   The contents of the data store may be
    updated after creation through calls to BufferSubData. If this bit is not
    set, the buffer content may not be directly updated by the client. The
    <data> argument may be used to specify the initial content of the buffer's
    data store regardless of the presence of the DYNAMIC_STORAGE_BIT_EXT.
    Regardless of the presence of this bit, buffers may always be updated
    with server-side calls such as CopyBufferSubData.

        MAP_READ_BIT  The data store may be mapped by the client for
    read access and a pointer in the client's address space obtained that may
    be read from.

        MAP_WRITE_BIT  The data store may be mapped by the client for
    write access and a pointer in the client's address space obtained that may
    be written to.

        MAP_PERSISTENT_BIT_EXT  The client may request that the server read from
    or write to the buffer while it is mapped. The client's pointer to the
    data store remains valid so long as the data store is mapped, even during
    execution of drawing or dispatch commands.

        MAP_COHERENT_BIT_EXT  Shared access to buffers that are simultaneously
    mapped for client access and are used by the server will be coherent, so
    long as that mapping is performed using MapBufferRange. That is, data
    written to the store by either the client or server will be visible to any
    subsequently issued GL commands with no further action taken by the
    application. In particular:

        - If MAP_COHERENT_BIT_EXT is not set and the client performs a write
          followed by a call to one of the FlushMapped*BufferRange commands
          with a range including the written range, then in subsequent
          commands the server will see the writes.

        - If MAP_COHERENT_BIT_EXT is set and the client performs a write, then in
          subsequent commands the server will see the writes.

        - If MAP_COHERENT_BIT_EXT is not set and the server performs a write, the
          application must call MemoryBarrier with the
          CLIENT_MAPPED_BUFFER_BARRIER_BIT_EXT set and then call FenceSync with
          SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the CPU will see the
          writes after the sync is complete.

        - If MAP_COHERENT_BIT_EXT is set and the server does a write, the app must
          call FenceSync with SYNC_GPU_COMMANDS_COMPLETE (or Finish). Then the
          CPU will see the writes after the sync is complete.

        CLIENT_STORAGE_BIT_EXT  When all other criteria for the buffer storage
    allocation are met, this bit may be used by an implementation to determine
    whether to use storage that is local to the server or to the client to
    serve as the backing store for the buffer.

    If <flags> contains MAP_PERSISTENT_BIT_EXT, it must also contain at least one
    of MAP_READ_BIT or MAP_WRITE_BIT.

    It is an error to specify MAP_COHERENT_BIT_EXT without also specifying
    MAP_PERSISTENT_BIT_EXT.

    BufferStorageEXT deletes any existing data store, and sets the values of
    the buffer object's state variables as shown in table 6.3.

    If any portion of the buffer object is mapped in the current context or
    any context current to another thread, it is as though UnmapBuffer (see
    section 6.3.1) is executed in each such context prior to deleting the
    existing data store.

    Name                         | Value for               | Value for
                                 | BufferData              | *BufferStorageEXT
    -----------------------------+-------------------------+------------------
    BUFFER_SIZE                  | <size>                  | <size>
    BUFFER_USAGE                 | <usage>                 | DYNAMIC_DRAW
    BUFFER_ACCESS                | READ_WRITE              | READ_WRITE
    BUFFER_ACCESS_FLAGS          | 0                       | 0
    BUFFER_IMMUTABLE_STORAGE_EXT | FALSE                   | TRUE
    BUFFER_MAPPED                | FALSE                   | FALSE
    BUFFER_MAP_POINTER           | NULL                    | NULL
    BUFFER_MAP_OFFSET            | 0                       | 0
    BUFFER_MAP_LENGTH            | 0                       | 0
    BUFFER_STORAGE_FLAGS_EXT     | MAP_READ_BIT |          | <flags>
                                 | MAP_WRITE_BIT |         |
                                 | DYNAMIC_STORAGE_BIT_EXT |
        Table 6.3: Buffer object state after calling BufferData,
        BufferStorageEXT, or NamedBufferStorageEXT.

    A mutable data store may be allocated for a buffer object by calling

        void BufferData(...)

        <include the remainder of Section 6.2 as written, and then append>.

    Calling BufferData is equivalent to calling BufferStorageEXT with
    <target>, <size> and <data> as specified, and <flags> set to the logical
    OR of DYNAMIC_STORAGE_BIT_EXT, MAP_READ_BIT and MAP_WRITE_BIT. The GL will
    use the value of <usage> parameter to BufferData as a hint to further
    determine the intended use of the buffer. However, BufferStorageEXT
    allocates immutable storage whereas BufferData allocates mutable storage.
    Thus, when a buffer's data store is allocated through a call to BufferData,
    the buffer's BUFFER_IMMUTABLE_STORAGE_EXT flags is set to FALSE.

    Add the following errors:

    An INVALID_OPERATION error is generated by BufferData and BufferStorageEXT
    if the BUFFER_IMMUTABLE_STORAGE_EXT flag of the buffer bound to <target> is
    set to TRUE.

    An INVALID_OPERATION error is generated by BufferSubData if the
    BUFFER_IMMUTABLE_STORAGE_EXT flag of the buffer bound to <target> is TRUE
    and the value of BUFFER_STORAGE_FLAGS_EXT for the buffer does not have
    the DYNAMIC_STORAGE_BIT_EXT set.

    The command:

        void NamedBufferStorageEXT(uint buffer,
                                   sizeiptr size,
                                   const void * data,
                                   bitfield flags);

    behaves similarly to BufferStorageEXT, except that the buffer whose storage
    is to be defined is specified by <buffer> rather than by the current
    binding to <target>.

    Add the following error:

    An INVALID_OPERATION error is generated by NamedBufferStorageEXT if
    the BUFFER_IMMUTABLE_STORAGE_EXT flag of <buffer> is set to TRUE.


    Modify Section 6.3, (Mapping and Unmapping Buffer Data)

    Add to the bulleted list describing flags that modify buffer mappings,
    p.54.

        * MAP_PERSISTENT_BIT_EXT indicates that it is not an error for the GL to
          read data from or write data to the buffer while it is mapped (see
          section 6.3.2). If this bit is set, the value of
          BUFFER_STORAGE_FLAGS_EXT for the buffer being mapped must include
          MAP_PERSISTENT_BIT_EXT.

        * MAP_COHERENT_BIT_EXT indicates that the mapping should be performed
          coherently. That is, such a mapping follows the rules set forth in
          section 6.2, "Creating and Modifying Buffer Object Data Stores".
          If this bit is set, the value of BUFFER_STORAGE_FLAGS_EXT for the
          buffer being mapped must include MAP_COHERENT_BIT.


    Add the following to the description of FlushMappedBufferRange, p.56:

    If a buffer range is mapped with both the MAP_PERSISTENT_BIT_EXT and
    MAP_FLUSH_EXPLICIT_BIT set, then FlushMappedBufferRange may be called to
    ensure that data written by the client into the flushed region becomes
    visible to the server. Data written to a coherent store will always
    become visible to the server after an unspecified period of time.


    Modify Section 6.3.2, "Effects of Mapping Buffers on Other GL Commands"
    to read:

    Any GL command which attempts to read from, write to, or change the state
    of a buffer object may generate an INVALID_OPERATION error if all or part
    of the buffer object is mapped, unless it was allocated by a call to
    *BufferStorageEXT with the MAP_PERSISTENT_BIT_EXT included in <flags>.
    However, only commands which explicitly describe this error are required
    to do so. If an error is not generated, using such commands to perform
    invalid reads, writes, or state changes will have undefined results and
    may result in GL interruption or termination.


    Modify Section 6.7, (Buffer Object State), p. 62:

        Add the following required state to a buffer object:

        ..., a boolean indicating whether or not buffer storage is
    immutable, an unsigned integer storing the flags with which it was
    allocated, ...

Additions to Chapter 7 of the OpenGL ES 3.1 Specification,
(Programs and Shaders)

    Add to the list of flags accepted by the <barriers> parameter to
    MemoryBarrier in Section 7.11.2, "Shader Memory Access Synchronization":

        * CLIENT_MAPPED_BUFFER_BARRIER_BIT_EXT: Access by the client to
          persistent mapped regions of buffer objects will reflect data written
          by shaders prior to the barrier. Note that this may cause additional
          synchronization operations.

New State

    Append to Table 20.4, "Buffer Object State", p.355:

    +------------------------------+------+----------------------+---------------+---------------------------------+------------+
    | Get Value                    | Type | Get Command          | Initial Value | Description                     | Sec.       |
    +------------------------------+------+----------------------+---------------+---------------------------------+------------+
    | BUFFER_IMMUTABLE_STORAGE_EXT | B    | GetBufferParameteriv | FALSE         | TRUE if buffer's data store is  | 6          |
    |                              |      |                      |               | immutable, FALSE otherwise      |            |
    | BUFFER_STORAGE_FLAGS_EXT     | Z+   | GetBufferParameteriv | 0             | The buffer object's storage     | 6          |
    |                              |      |                      |               | flags.                          |            |
    +------------------------------+------+----------------------+---------------+---------------------------------+------------+

New Implementation Dependent State

    None.

Errors

    INVALID_OPERATION is generated by BufferStorageEXT if zero is bound to
    <target>.

    INVALID_OPERATION is generated by BufferStorageEXT, NamedBufferStorageEXT
    and BufferData if the BUFFER_IMMUTABLE_STORAGE flag of the buffer bound to
    <target> is TRUE.

    INVALID_VALUE is generated by BufferStorageEXT and NamedBufferStorageEXT
    if <size> is less than or equal to zero.

    INVALID_VALUE is generated by BufferStorageEXT and NamedBufferStorageEXT
    if <flags> has any bits set other than those defined above.

    INVALID_VALUE is generated by BufferStorageEXT and NamedBufferStorageEXT if
    <flags> contains MAP_PERSISTENT_BIT_EXT but does not contain
    at least one of MAP_READ_BIT or
    MAP_WRITE_BIT.

    INVALID_VALUE is generated by BufferStorageEXT and NamedBufferStorageEXT if
    <flags> contains MAP_COHERENT_BIT_EXT, but does not also
    contain MAP_PERSISTENT_BIT_EXT.

    INVALID_OPERATION is generated by MapBufferRange if any of MAP_READ_BIT,
    MAP_WRITE_BIT, MAP_PERSISTENT_BIT_EXT, or MAP_COHERENT_BIT_EXT are included in
    <access>, but the same bit is not included in the buffer's storage
    flags.

    OUT_OF_MEMORY is generated by BufferStorageEXT and NamedBufferStorageEXT if
    the GL is not able to allocate a data store with the properties requested
    in <flags>.

    *REMOVE* all errors generated by any command should they detect access to
    a mapped buffer and replace with language such as:

    INVALID_OPERATION is generated by <command> if the buffer is currently
    mapped by MapBufferRange unless it was mapped with the
    MAP_PERSISTENT_BIT_EXT included in <access>.


Dependencies on GL_EXT_direct_state_access

    If GL_EXT_direct_state_access is not supported, remove all references to
    NamedBufferStorageEXT.

Conformance Tests

    TBD

Usage Examples

    Example 1: Updating the content of a buffer which does not have the
    DYNAMIC flag set:

    // Allocate two buffers, one of which will be our 'staging buffer'.
    GLuint bufs[2];
    glGenBuffers(2, &bufs[0]);

    // Client can map this buffer for write.
    // One could possibly make this mapping persistent.
    glBindBuffer(GL_COPY_READ_BUFFER, bufs[0]);
    glBufferStorageEXT(GL_COPY_READ_BUFFER, size, NULL,
                    GL_MAP_WRITE_BIT);

    // Client cannot read or write this buffer, server can do both.
    glBindBuffer(GL_COPY_WRITE_BUFFER, bufs[1]);
    glBufferStorageEXT(GL_COPY_WRITE_BUFFER, size, NULL, 0);

    // Now, map the staging buffer to put data into it.
    void * data = glMapBufferRange(GL_COPY_READ_BUFFER, 0, size,
                                   GL_MAP_WRITE_BIT |
                                   GL_MAP_INVALIDATE_BUFFER_BIT);
    memcpy(data, source_data, size);
    glUnmapBuffer(GL_COPY_READ_BUFFER);

    // Copy from the staging buffer to the server-side buffer.
    glCopyBufferSubData(GL_COPY_READ_BUFFER, GL_COPY_WRITE_BUFFER, 0, 0, size);

    Example 2: Read from framebuffer into a buffer mapped into client's
    address space:

    // Create buffer, allocate storage, and create a persistent map.
    GLuint pbo;
    glGenBuffers(1, &pbo);
    glBindBuffer(GL_PIXEL_PACK_BUFFER, pbo);
    glBufferStorageEXT(GL_PIXEL_PACK_BUFFER, size, NULL,
                    GL_MAP_READ_BIT |
                    GL_MAP_PERSISTENT_BIT_EXT);

    void * data = glMapBufferRange(GL_PIXEL_PACK_BUFFER,
                                   GL_MAP_READ_BIT |
                                   GL_MAP_PERSISTENT_BIT_EXT);

    glReadPixels(0, 0, width, height, format, type, NULL);
    glMemoryBarrier(GL_CLIENT_MAPPED_BUFFER_BARRIER_BIT_EXT);
    GLsync fence = glFenceSync(GL_SYNC_GPU_COMMANDS_COMPLETE, 0);

    // Do stuff to use time...
    ReallyExpensiveFunction();

    glClientWaitSync(fence);

    // Use the data written to the buffer
    UseDataInMemory(data);


Issues

    Note: These issues apply specifically to the definition of the
    EXT_buffer_storage specification, which is based on the OpenGL
    extension ARB_buffer_storage as updated in OpenGL 4.5. For the full
    set of historical issues, see ARB_buffer_storage which can be found
    in the OpenGL Registry.

    (1) What functionality was changed relative to ARB_buffer_storage?

       - added EXT suffixes
       - rebased against ES 3.1
       - removed passing reference to ClearBufferSubData which doesn't exist
         in OpenGL ES yet.

    (2) What commands are affected by the relaxed errors for persistently
        mapped buffers?

        RESOLVED: In GL 4.5 the following commands have the relaxed
        language BufferSubData, ClearBufferSubData, CopyBufferSubData,
        GetBufferSubData and InvalidateBufferSubData. Of these commands
        the only ones that apply to ES 3.1 are BufferSubData and
        CopyBufferSubData. However, if additional extensions add any of
        the other commands and EXT_buffer_storage is supported, they
        would have the same behavior in ES.

    (3) Should we keep interactions with the NamedBufferStorageEXT
        DSA command and interactions with EXT_direct_state_access?

        UNRESOLVED. TBD if there is interest in a DSA extension
        based on ARB_direct_state_access.


Revision History

    Rev.    Date    Author    Changes
    ----  --------  --------  -----------------------------------------
     1    09/17/14  dkoch     EXT version based on ARB_buffer_storage v.24

     2    03/27/15  dkoch     Update status, clarify dependencies and tokens

     3    05/01/15  dkoch     Change description of MAP_COHERENT_BIT for
                              buffer storage so that barriers with 
                              CLIENT_MAPPED_BUFFER_BARRIER_BIT do not need
                              to make CPU writes visible to the GPU in
                              this case without an explicit flush (Bug
                              13578, sync w/ ARB_buffer_storage v.25).