gpu/GLES2/extensions/CHROMIUM/CHROMIUM_nonblocking_readback.txt

Name

    CHROMIUM_nonblocking_readback

Name Strings

    GL_CHROMIUM_nonblocking_readback

Version

    Last Modifed Date: May 21, 2018

Dependencies

    OpenGL ES 3.0 is required.

Overview

    This extension provides a query mechanism that allows for non-blocking
    device-to-host readback of GL buffer object contents.

    In Chromium's multiprocess GL architecture, buffer readback
    (MapBufferRange(MAP_READ_BIT)) may be accelerated by a shared-memory shadow
    copy of a GL buffer object's memory. This shadow copy is allocated based on
    the buffer allocation usage hint (*_READ). The contents of the shadow copy
    are updated based on the usage of the
    READBACK_SHADOW_COPIES_UPDATED_CHROMIUM query and
    InvalidateReadbackBufferShadowDataCHROMIUM command. (The management of the
    shadow copies is purely internal to the implementation, and not actually
    exposed by this extension.)

    When a buffer is read back, if such a shadow copy is up-to-date with the
    contents of the real buffer, then the MapBufferRange operation can return
    that shadow copy.

    The READBACK_SHADOW_COPIES_UPDATED_CHROMIUM query provides:
    (1) a signal from client to service (EndQuery) that any previously written
    *_READ buffers might be read back later, and that their shadow copies should
    be updated.
    (2) a signal from service to client (QUERY_RESULT_AVAILABLE) that it will no
    longer use any of the shadow copies it received from the command buffer
    client prior to the point in the command stream when the query was issued,
    and that any previously written *_READ buffers' shadow copies have been
    updated to mirror the contents of the buffers (at a point in the command
    stream no earlier than the query was issued).
    (The QUERY_RESULT is undefined.)

    Except in the presence of transform feedback operations (see below), this
    query, and the existence of shadow copies, affect only the performance of
    the GL, and not its observable semantic behavior. The semantic behavior of
    READBACK_SHADOW_COPIES_UPDATED_CHROMIUM is otherwise equivalent to that of
    the COMMANDS_COMPLETED_CHROMIUM query from CHROMIUM_sync_query, except that
    it is a distinct query target, and the QUERY_RESULT may return a different
    value.

    When a buffer is written by any OpenGL ES 3.0 mechanism aside from transform
    feedback - ReadPixels with a PIXEL_PACK_BUFFER bound, MapBufferRange with
    MAP_WRITE_BIT, BufferData, BufferSubData, and CopyBufferSubData - the
    buffer's shadow copy will be automatically invalidated.

    If the buffer's shadow copy is invalidated by a transform feedback operation
    writing to the buffer, the application must manually invalidate it via
    InvalidateReadbackBufferShadowDataCHROMIUM.

New Procedures and Functions

    The command

        void InvalidateReadbackBufferShadowDataCHROMIUM(GLuint buffer_id)

    manually invalidates the shadow copy associated with a given buffer,
    preventing it from being returned for readbacks.

    This is necessary only when a buffer is written by transform feedback; all
    other OpenGL ES 3.0 mechanisms which write to the buffer will automatically
    invalidate the shadow copy.

Errors

    None.

New Tokens

    Accepted by the <target> parameter of BeginQuery, EndQuery, and GetQueryiv:

        READBACK_SHADOW_COPIES_UPDATED_CHROMIUM         0x84F8

New State

    None.

Revision History

    5/21/2018   Documented the extension