replicant-frameworks_native/opengl/specs/EGL_ANDROID_fence_sync.txt

Name

    ANDROID_fence_sync

Name Strings

    EGL_ANDROID_fence_sync

Contributors

    Jamie Gennis

Contact

    Jamie Gennis, Google Inc. (jgennis 'at' google.com)

Status

    Draft.

Version

    Version 2, July 23, 2012

Number

    EGL Extension #XXX

Dependencies

    Requires EGL 1.1

    This extension is written against the wording of the EGL 1.2 Specification

    EGL_KHR_fence_sync is required.

Overview

    This extension enables the creation of EGL fence sync objects that are
    associated with an Android Sync HAL fence object.  These EGL fence sync
    objects have nearly identical semantics to those defined by the
    KHR_fence_sync extension, except that they have an additional attribute
    storing the file descriptor referring to the native Android fence object.

New Types

    None.

New Procedures and Functions

    EGLint eglDupAndroidFenceFDANDROID(
                        EGLDisplay dpy,
                        EGLSyncKHR);

New Tokens

    Accepted by the <type> parameter of eglCreateSyncKHR, and returned
    in <value> when eglGetSyncAttribKHR is called with <attribute>
    EGL_SYNC_TYPE_KHR:

    EGL_SYNC_ANDROID_FENCE_ANDROID          0x3144

    Accepted by the <attrib_list> parameter of eglCreateSyncKHR:

    EGL_SYNC_ANDROID_FENCE_FD_ANDROID       0x3145

    Accepted by the <attrib_list> parameter of eglCreateSyncKHR, and returned
    by eglDupAndroidFenceFDANDROID in the event of an error:

    EGL_NO_ANDROID_FENCE_ANDROID            -1

    Returned in <value> when eglGetSyncAttribKHR is called with <attribute>
    EGL_SYNC_CONDITION_KHR:

    EGL_SYNC_ANDROID_FENCE_SIGNALED_ANDROID 0x3146

Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)

    Add the following after the sixth paragraph of Section 3.8.1 (Sync
    Objects), added by KHR_fence_sync

    "If <type> is EGL_SYNC_ANDROID_FENCE_ANDROID, an EGL Android fence sync
    object is created. In this case the EGL_SYNC_ANDROID_FENCE_FD_ANDROID
    attribute may optionally be specified. If this attribute is specified, it
    must be set to either a file descriptor that refers to a native Android
    fence object or to the value EGL_NO_ANDROID_FENCE_ANDROID.

    The default values for the EGL Android fence sync object attributes are as
    follows:

      Attribute Name                     Initial Attribute Value(s)
      ---------------                    --------------------------
      EGL_SYNC_TYPE_KHR                  EGL_SYNC_ANDROID_FENCE_ANDROID
      EGL_SYNC_STATUS_KHR                EGL_UNSIGNALED_KHR
      EGL_SYNC_CONDITION_KHR             EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR
      EGL_SYNC_ANDROID_FENCE_FD_ANDROID  EGL_NO_ANDROID_FENCE_ANDROID

    If the EGL_SYNC_ANDROID_FENCE_FD_ANDROID attribute is not
    EGL_NO_ANDROID_FENCE_ANDROID then the EGL_SYNC_CONDITION_KHR attribute is
    set to EGL_SYNC_ANDROID_FENCE_SIGNALED_ANDROID and the EGL_SYNC_STATUS_KHR
    attribute is set to reflect the signal status of the native Android fence
    object. Additionally, the EGL implementation assumes ownership of the file
    descriptor, so the caller must not use it after calling eglCreateSyncKHR."

    Modify Section 3.8.1 (Sync Objects), added by KHR_fence_sync, starting at
    the seventh paragraph

    "When a fence sync object is created or when an EGL Android fence sync
    object is created with the EGL_SYNC_ANDROID_FENCE_FD_ANDROID attribute set
    to EGL_NO_ANDROID_FENCE_ANDROID, eglCreateSyncKHR also inserts a fence
    command into the command stream of the bound client API's current context
    (i.e., the context returned by eglGetCurrentContext), and associates it
    with the newly created sync object.

    After associating the fence command with an EGL Android fence sync object,
    the next Flush() operation performed by the current client API causes a
    new native Android fence object to be created, and the
    EGL_SYNC_ANDROID_FENCE_ANDROID attribute of the EGL Android fence object
    is set to a file descriptor that refers to the new native Android fence
    object. This new native Android fence object is signaled when the EGL
    Android fence sync object is signaled.

    When the condition of the sync object is satisfied by the fence command,
    the sync is signaled by the associated client API context, causing any
    eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock. If
    the sync object is an EGL Android fence sync object then the native Android
    fence object is also signaled when the condition is satisfied. The
    EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR condition is satisfied by completion
    of the fence command corresponding to the sync object and all preceding
    commands in the associated client API context's command stream. The sync
    object will not be signaled until all effects from these commands on the
    client API's internal and framebuffer state are fully realized. No other
    state is affected by execution of the fence command.

    The EGL_SYNC_ANDROID_FENCE_SIGNALED_ANDROID condition is satisfied by the
    signaling of the native Android fence object referred to by the
    EGL_SYNC_ANDROID_FENCE_FD_ANDROID attribute. When this happens any
    eglClientWaitSyncKHR commands blocking on <sync> unblock."

    Modify the list of eglCreateSyncKHR errors in Section 3.8.1 (Sync Objects),
    added by KHR_fence_sync

    "Errors
    ------

      * If <dpy> is not the name of a valid, initialized EGLDisplay,
        EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is
        generated.
      * If <type> is EGL_SYNC_FENCE_KHR and <attrib_list> is neither NULL nor
        empty (containing only EGL_NONE), EGL_NO_SYNC_KHR is returned and an
        EGL_BAD_ATTRIBUTE error is generated.
      * If <type> is EGL_SYNC_ANDROID_FENCE_ANDROID and <attrib_list> contains
        an attribute other than EGL_SYNC_ANDROID_FENCE_FD_ANDROID, EGL_NO_SYNC_KHR is
        returned and an EGL_BAD_ATTRIBUTE error is generated.
      * If <type> is not a supported type of sync object,
        EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is
        generated.
      * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_ANDROID_FENCE_ANDROID and
        no context is current for the bound API (i.e., eglGetCurrentContext
        returns EGL_NO_CONTEXT), EGL_NO_SYNC_KHR is returned and an
        EGL_BAD_MATCH error is generated.
      * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_ANDROID_FENCE_ANDROID and
        <dpy> does not match the EGLDisplay of the currently bound context for
        the currently bound client API (the EGLDisplay returned by
        eglGetCurrentDisplay()) then EGL_NO_SYNC_KHR is returned and an
        EGL_BAD_MATCH error is generated.
      * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_ANDROID_FENCE_ANDROID and
        the currently bound client API does not support the client API
        extension indicating it can place fence commands, then EGL_NO_SYNC_KHR
        is returned and an EGL_BAD_MATCH error is generated."

    Modify table 3.cc in Section 3.8.1 (Sync Objects), added by KHR_fence_sync

    "
    Attribute                          Description                Supported Sync Objects
    -----------------                  -----------------------    ----------------------
    EGL_SYNC_TYPE_KHR                  Type of the sync object    All
    EGL_SYNC_STATUS_KHR                Status of the sync object  All
    EGL_SYNC_CONDITION_KHR             Signaling condition        EGL_SYNC_FENCE_KHR and
                                                                  EGL_SYNC_ANDROID_FENCE_ANDROID only
    "

    Modify the second paragraph description of eglDestroySyncKHR in Section
    3.8.1 (Sync Objects), added by KHR_fence_sync

    "If no errors are generated, EGL_TRUE is returned, and <sync> will no
    longer be the handle of a valid sync object.  Additionally, if <sync> is an
    EGL Android fence sync object and the EGL_SYNC_ANDROID_FENCE_FD_ANDROID
    attribute is not EGL_NO_ANDROID_FENCE_ANDROID then that file descriptor is
    closed."

    Add the following after the last paragraph of Section 3.8.1 (Sync
    Objects), added by KHR_fence_sync

    The command

        EGLint eglDupAndroidFenceFDANDROID(
                            EGLdisplay dpy,
                            EGLSyncKHR sync);

    duplicates the file descriptor stored in the
    EGL_SYNC_ANDROID_FENCE_FD_ANDROID attribute of an EGL Android fence sync
    object and returns the new file descriptor.

    Errors
    ------

      * If <sync> is not a valid sync object for <dpy>,
        EGL_NO_ANDROID_FENCE_ANDROID is returned and an EGL_BAD_PARAMETER
        error is generated.
      * If the EGL_SYNC_ANDROID_FENCE_FD_ANDROID attribute of <sync> is
        EGL_NO_ANDROID_FENCE_ANDROID, EGL_NO_ANDROID_FENCE_ANDROID is returned
        and an EGL_BAD_PARAMETER error is generated.
      * If <dpy> does not match the display passed to eglCreateSyncKHR
        when <sync> was created, the behaviour is undefined."

Issues

    1. Should EGLSyncKHR objects that wrap Android fence objects use the
    EGL_SYNC_FENCE_KHR type?

    RESOLVED: A new sync object type will be added.

    We don't want to require all EGL fence sync objects to wrap Android fence
    objects, so we need some way to tell the EGL implementation at sync object
    creation whether the sync object should support querying the Android fence
    FD attribute. We could do this with either a new sync object type or with a
    boolean attribute. It might be nice to pick up future signaling conditions
    that might be added for fence sync objects, but there may be things that
    get added that don't make sense in the context of Android fence objects.

    2. Who is responsible for dup'ing the Android fence file descriptors?

    RESOLVED: Whenever a file descriptor is passed into or returned from an
    EGL call in this extension, ownership of that file descriptor is
    transfered. The recipient of the file descriptor must close it when it is
    no longer needed, and the provider of the file descriptor must dup it
    before providing it if they require continued use of the native Android
    fence.

    3. Can the EGL_SYNC_ANDROID_FENCE_FD_ANDROID attribute be queried?

    RESOLVED: No.

    Returning the file descriptor owned by the EGL implementation would
    violate the file descriptor ownership rule described in issue #2. Having
    eglGetSyncAttribKHR return a different (dup'd) file descriptor each time
    it's called seems wrong, so a new function was added to explicitly dup the
    file descriptor.

    That said, the attribute is useful both as a way to pass an existing file
    descriptor to eglCreateSyncKHR and as a way to describe the subsequent
    behavior of EGL Android fence sync objects, so it is left as an attribute
    for which the value cannot be queried.

Revision History

#2 (Jamie Gennis, July 23, 2012)
    - Changed the file descriptor ownership transferring behavior.
    - Added the eglDupAndroidFenceFDANDROID function.
    - Removed EGL_SYNC_ANDROID_FENCE_FD_ANDROID from the table of gettable
    attributes.
    - Added language specifying that a native Android fence is created at the
    flush following the creation of an EGL Android fence sync object that is
    not passed an existing native fence.

#1 (Jamie Gennis, May 29, 2012)
    - Initial draft.