gpu/GLES2/extensions/CHROMIUM/CHROMIUM_sync_point.txt

Name

    CHROMIUM_sync_point

Name Strings

    GL_CHROMIUM_sync_point

Version

    Last Modifed Date: November 20, 2015

Dependencies

    OpenGL ES 2.0 is required.

Overview

    This extension allows a client to order operations between contexts.

    This extension introduces the concepts of "fence sync" and "sync token".
    An inserted fence sync represents a position in the command stream of a
    context. Sync tokens are generated from fence syncs and allow another
    context to issue a "wait" command on the sync token. This wait command
    will then guarantee that commands before the inserted fence sync are
    submitted before commands after the sync token wait.

    This extension implements a small subset of ARB_sync, with weaker
    guarantees. In particular it doesn't ensure commands are actually executed
    by the server, it only guarantees submission order.

    It does however guarantee operation order with respect to
    ConsumeTextureCHROMIUM and ProduceTextureCHROMIUM from
    CHROMIUM_texture_mailbox, if present.

Issues

    None

New Procedures and Functions

    The command

        uint64 InsertFenceSyncCHROMIUM()

    inserts a fence sync in the current command stream. The fence sync is
    signaled when previous commands have been submitted to the server, or when
    the context is destroyed, whichever happens first. The fence sync name is
    only visible for the current context. The returned fence sync name cannot
    be waited upon directly, but once the command is flushed to the server,
    it can be converted to a sync token using GenSyncTokenCHROMIUM, which is
    waitable.

    The command

        void GenSyncTokenCHROMIUM(uint64 fence_sync, GLbyte *sync_token)

    converts <fence_sync> which is only visible to the current context to a
    sync token which may be waited upon by any contexts on the same server.
    The <fence_sync> command must be flushed before this function may be
    called, otherwise an INVALID_OPERATION error is generated. The use of
    ShallowFlushCHROMIUM is enough for the command to be flushed to the
    server. The generated <sync_token> must be generated on the same context
    as when InsertFenceSyncCHROMIUM was called. The <sync_token> can be passed
    and used by any context on the same server, including other context groups.

    <sync_token> returns a GL_SYNC_TOKEN_SIZE_CHROMIUM byte sized name.

    The command

        void GenUnverifiedSyncTokenCHROMIUM(uint64 fence_sync,
                                            GLbyte *sync_token)

    converts <fence_sync>, which is only visible to the current context, to a
    sync token, which may be waited upon by a context which only needs flush
    order guarantee with respect to the fence sync context. For example, if
    the two contexts are on the same channel but on different streams, flush
    order guarantee is enough to guarantee that the server will receive the
    release command before the wait command. The <fence_sync> command must be
    flushed or separated by an ordering barrier before this function may be
    called, otherwise an INVALID_OPERATION error is generated. For chromium
    specific flushes and ordering barriers, see ShallowFlushCHROMIUM and
    OrderingBarrierCHROMIUM. The generated <sync_token> must be generated on
    the same context as when InsertFenceSyncCHROMIUM was called.

    The command

        void VerifySyncTokensCHROMIUM(GLbyte **sync_tokens, GLsizei count)

    verifies array <sync_tokens> of length <count> and ensures that these
    sync tokens have all been verified. The generated sync token did not have
    to be generated from the same context but it must be from a context which
    flush order guarantee is enough to guarantee order. For example, contexts
    which live on the same channel may verify sync tokens for one another.
    If a sync token was generated by GenUnverifiedSyncTokenCHROMIUM and the
    corresponding context is unable to verify it, an INVALID_OPERATION error
    is generated. Sync tokens which have already been verified are ignored, if
    all sync tokens were already verified then nothing will be done.

    The command

        void WaitSyncTokenCHROMIUM(const GLbyte *sync_token)

    causes the current context to stop submitting commands until the specified
    fence sync becomes signaled. This is implemented as a server-side wait.
    <sync_token> is a sync token generated by GenSyncTokenCHROMIUM. If
    <sync_token> was generated by GenUnverifiedSyncTokenCHROMIUM and the
    corresponding fence sync context required more than just flush ordering
    to guarantee synchronization, an INVALID_OPERATION error is generated. If
    <sync_token> isn't a valid sync token returned by GenSyncTokenCHROMIUM or
    GenUnverifiedSyncTokenCHROMIUM, the result is undefined.

New Tokens

    The size of a sync token name in bytes.

        GL_SYNC_TOKEN_SIZE_CHROMIUM                        24

Errors

    INVALID_VALUE is generated if the <sync_token> parameter of
    GenSyncTokenCHROMIUM or GenUnverifiedSyncTokenCHROMIUM is NULL.

    INVALID_VALUE is generated if the <fence_sync> parameter of
    GenSyncTokenCHROMIUM or GenUnverifiedSyncTokenCHROMIUM is not a
    valid local fence sync name.

    INVALID_OPERATION is generated if the <fence_sync> parameter of
    GenSyncTokenCHROMIUM or has not been flushed to the server.

    INVALID_OPERATION is generated if the <fence_sync> parameter of
    GenUnverifiedSyncTokenCHROMIUM or has not been flushed to the server
    or queued to be flushed using an ordering barrier.

    INVALID_OPERATION is generated if the <sync_token> parameter of
    WaitSyncTokenCHROMIUM or VerifySyncTokensCHROMIUM was generated using
    GenUnverifiedSyncTokenCHROMIUM, but the two contexts must be synchronized
    with more than just flush order.

New State

    None.

Revision History

    2/25/2013    Documented the extension

    9/8/2015     Modified functions InsertFenceSyncCHROMIUM,
    GenSyncTokenCHROMIUM, and WaitSyncTokenCHROMIUM.

    10/12/2015   Added function GenUnverifiedSyncTokenCHROMIUM.

    11/24/2015   Clarified that GenUnverifiedSyncTokenCHROMIUM only needs an
    ordering barrier and added proper error values.

    11/25/2015   Added function VerifySyncTokensCHROMIUM.