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

Name

    EXT_external_buffer

Name Strings

    GL_EXT_external_buffer

Contact

    Jeff Leger (jleger 'at' qti.qualcomm.com)

Contributors

    Sam Holmes
    Maurice Ribble
    Matt Netsch
    Jeremy Gebben
    John Bates
    Craig Donner
    Jeff Leger
    Rob VanReenen
    Tom Kneeland
    Jesse Hall
    Jan-Harald Fredriksen
    Daniel Koch
    Mathias Heyer

Status

    Complete

Version

    Last Modified Date: May 29, 2017
    Revision: 1.0

Number

    OpenGL ES Extension #284
    OpenGL Extension #508

Dependencies

    OpenGL ES 3.1 and EXT_buffer_storage are required for OpenGL ES
    implementations.

    OpenGL 4.4 is required for OpenGL implementations.

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

    This extension is written against version 3 of EXT_buffer_storage.

    The definition of this extension is affected by the presence of
    GL_EXT_direct_state_access, GL_ARB_direct_state_access, or OpenGL 4.5.


Overview

    Extension EXT_buffer_storage introduced immutable storage buffers to
    OpenGL ES. This extension allows the data store for an immutable buffer to
    be sourced from an external EGLClientBuffer, allowing sharing of EGL client
    buffers across APIs, across processes, and across different processing
    cores such as the GPU, CPU, and DSP.

    Operations can then be performed on the external buffer using standard
    GL buffer object procedures. The data in the allocation is not copied to
    the buffer object's data store; the external allocation represents a single
    memory allocation that can be shared across multiple GL objects -- this
    aspect is similar to EGL external images.  On the other hand, the external
    buffer does not provide lifetime guarantees including orphaning and sibling
    behavior as provided by EGL external images.

    The EGLClientBuffer must be allocated in a way which permits this shared
    access. For example, on Android via a shareable Android hardware buffer.
    This extension does not enable support for arbitrary EGLClientBuffers to be
    used as an external buffer.

    It is the application's responsibility to ensure synchronization between
    operations performed by separate components (DSP / CPU / GPU) and processes
    on the external buffer. Additionally the application is responsible for
    avoiding violating existing GL spec requirements. For example, mapping a
    single shared allocation to two GL buffer objects and then performing
    CopyBufferSubData such that the read and write regions overlap would
    violate the existing CopyBufferSubData spec regarding copies performed
    with the same buffer set for source and destination.

    The application must take any steps necessary to ensure memory access to
    the external buffer behaves as required by the application. For example,
    preventing compilation differences in data padding from causing data to be
    inadvertently corrupted by using defined structure alignment methods such
    as the std140 layout qualifier.  The application is responsible for
    managing the lifetime of the external buffer, ensuring that the external
    buffer is not deleted as long as there are any GL buffer objects referring
    to it.

New Types

    /*
     * GLeglClientBufferEXT is an opaque handle to an EGLClientBuffer
     */
    typedef void* GLeglClientBufferEXT;

New Procedures and Functions

    void BufferStorageExternalEXT(enum               target,
                                  intptr             offset,
                                  sizeiptr           size,
                                  eglClientBufferEXT clientBuffer,
                                  bitfield           flags);

    [[ The following is only added if GL_EXT_direct_state_access,
       GL_ARB_direct_state_access, or OpenGL 4.5 is supported. ]]

    void NamedBufferStorageExternalEXT(uint               buffer,
                                       intptr             offset,
                                       sizeiptr           size,
                                       eglClientBufferEXT clientBuffer,
                                       bitfield           flags);

New Tokens

    None

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

Modify Section 6.2, (Creating and Modifying Buffer Object Data Stores).  After
the section describing BufferStorageEXT, insert the following:

    The command

        void BufferStorageExternalEXT(enum target, intptr offset,
             sizeiptr size, eglClientBufferEXT clientBuffer,
             bitfield flags);

    behaves similar to BufferStorageEXT, but rather than allocate an immutable
    data store, the specified client buffer is referenced as the immutable
    data store.  Such a store may not be modified through further calls to
    BufferStorageExternalEXT, BufferStorageEXT, or BufferData.

    <target> Specifies the target buffer object. The symbolic constant must be
    one of the targets listed in table 6.1.  <offset> and <size> specify, in
    basic machine units, the range of the client buffer to be bound to the data
    store. <offset> must be zero.

    <clientBuffer> Is the handle of a valid EGLClientBuffer resource (cast
    into type eglClientBufferEXT).  The EGLClientBuffer must be allocated in a
    platform-specific way which permits shared access.  For example, on Android
    via a sharable Android hardware buffer (struct AHardwareBuffer), converted
    into EGLClientBuffer via extension EGL_ANDROID_get_native_client_buffer.
    Other platforms would require a similar mechanism. This extension does not
    enable support for arbitrary EGLClientBuffers to be used as a shared buffer.
    <flags> is the bitwise OR of flags describing the intended usage of the buffer
    object's external data store by the application. Valid flags and their
    meanings are as described for BufferStorageEXT.

    The values of the buffer object's state variables will match those for other
    *BufferStorageEXT calls, as specified in table 6.3.

    The behavior follows other immutable buffers; BufferStorageExternalEXT sets the
    created buffer's BUFFER_IMMUTABLE_STORAGE_EXT to TRUE.

    [[ The following is only added if GL_EXT_direct_state_access,
       GL_ARB_direct_state_access, or OpenGL 4.5 is supported. ]]

    The command

        void NamedBufferStorageExternalEXT(uint buffer, intptr offset,
             sizeiptr size, eglClientBufferEXT clientBuffer,
             bitfield flags);

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


Errors

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

    INVALID_OPERATION is generated by BufferStorageExternalEXT, if the
    BUFFER_IMMUTABLE_STORAGE flag of the buffer bound to <target> is TRUE.

    INVALID_VALUE is generated by BufferStorageExternalEXT if <offset> is not 0.

    INVALID_VALUE is generated by BufferStorageExternalEXT if <size> is 0
    or negative.

    INVALID_VALUE is generated by BufferStorageExternalEXT if <offset> + <size>
    exceeds the size of the EGLClientBuffer.

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

    INVALID_VALUE is generated by BufferStorageExternalEXT 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 BufferStorageExternalEXT if <flags> contains
    MAP_COHERENT_BIT_EXT, but does not also contain MAP_PERSISTENT_BIT_EXT.

    INVALID_ENUM is generated by BufferStorageExternalEXT if <target> is not one
    of the accepted buffer targets.

    INVALID_OPERATION is generated by BufferStorageExternalEXT if the shared
    buffer is not allocated in a way which permits shared access by the GPU.

    [[ The following is only added if GL_EXT_direct_state_access or
       GL_ARB_direct_state_access is supported. ]]

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

Interactions with GL_EXT_direct_state_access, GL_ARB_direct_state_access and
OpenGL 4.5

    If none of GL_EXT_direct_state_access, GL_ARB_direct_state_access, or
    OpenGL 4.5, the NamedBufferStorageExternalEXT entry-point is not
    added and all references to it should be ignored.

Issues

    1. How are possible GPU cache interactions handled?

    The application is responsible for synchronizing writes to the shared buffer
    by other processing cores (e.g. DSP), and making those available to CPU
    reads for the processing of client-side GL commands (e.g., BufferSubData).
    The GL implementation should guarantee that available writes by other cores
    (e.g., DSP) are visible to the GPU when server-side commands read from the
    shared buffer.

    PROPOSED: The exact granularity with which available writes from other cores
    e.g., DSP) become visible to the CPU and GPU is implementation dependent.

    2. Should EGLClientBuffers, be directly referenced by the GL API?

    For images, a set of EGL and client API extensions provide import/export
    of EGLImages from client APIs and native buffers.  The EGLImage also provides
    lifetime guarantees including orphaning and sibling behavior.  This extension
    is more narrowly focused, specifically targeted to the import of EGLClientBuffers
    as GL buffers, and requiring the application to manage the resource lifetime.
    As such, it may not warrant a new EGL object or EGL extension.

    RESOLVED:  A corresponding EGL object and extension is not required.  When
    using this extension, applications are expected to cast EGLClientBuffer as
    GLeglClientBufferEXT.

Revision History

      Rev.    Date      Author    Changes
      ----  ----------  --------  -----------------------------------------
      0.1   04/18/2017  sholmes   Initial version. Based on QCOM_shared_buffer.
      0.2   05/16/2017  jleger    Renamed the extension and reworked it to to
                                  be an extension to EXT_buffer_storage.
      0.3   05/24/2017  jleger    Add offset parameter and other cleanup.
      0.4   05/25/2017  jleger    Add DSA entrypoint and minor cleanup.
      1.0   05/29/2017  dgkoch    Add interactions with GL, minor cleanup.