Add the EGL_ANDROID_fence_sync spec.

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 1, May 29, 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

    None.

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 <attribute> parameter of eglGetSyncAttribKHR:

    EGL_SYNC_FENCE_FD_ANDROID               0x3145

    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_FENCE_FD_ANDROID attribute may

    optionally be specified. If this attribute is specified, it must be set to

    a file descriptor that refers to a native Android fence object.

    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

    Upon creation of an EGL Android fence sync object, the

    EGL_SYNC_FENCE_FD_ANDROID attribute is set to a newly generated file

    descriptor that refers to a native Android fence object. If the

    EGL_SYNC_FENCE_FD_ANDROID attribute is specified in the eglCreateSyncKHR

    call then the generated file descriptor refers to the same native Android

    fence object as the file descriptor passed to eglCreateSyncKHR.  Note,

    however, that the value of the sync object attribute is *not* the same file

    descriptor as the one passed to eglCreateSyncKHR - it simply refers to the

    same underlying native Android fence object. Additionally, if the

    EGL_SYNC_FENCE_FD_ANDROID attribute is specified 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."

    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 without specifying the EGL_SYNC_FENCE_FD_ANDROID

    attribute, 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.

    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. 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_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

    EGL_SYNC_FENCE_FD_ANDROID Native Android fence       EGL_SYNC_ANDROID_FENCE_ANDROID only

                              object file descriptor

    "

    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 then the file descriptor stored in the

    EGL_SYNC_FENCE_FD_ANDROID attribute is closed and is no longer a valid file

    descriptor."

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: The recipient of a file descriptor is responsible for dup'ing it

    if it wishes to maintain a reference to the Android fence object.

    This means that when eglCreateSyncKHR is called with an existing file

    descriptor, the EGL implementation must dup it. On the other hand, when

    eglGetSyncAttribKHR is called to query the file descriptor, it is the

    responsibility of the caller to dup the file descriptor if it wishes to

    maintain a reference that will outlast the EGLSyncKHR object.

Revision History

#1 (Jamie Gennis, May 29, 2012)

    - Initial draft.

0x3141               (unused)

0x3142               EGL_ANDROID_recordable

0x3143               EGL_VERSION_HW_ANDROID (internal use)

0x3144 - 0x314F      (unused)

0x3144               EGL_SYNC_ANDROID_FENCE_ANDROID

0x3145               EGL_SYNC_FENCE_FD_ANDROID

0x3146               EGL_SYNC_ANDROID_FENCE_SIGNALED_ANDROID

0x3147 - 0x314F      (unused)