Add the EGL_ANDROID_fence_sync spec.

Change-Id: I8c26e5caaf8d89a60a09a5308d55e336537b916e

2 files changed, 217 insertions, 1 deletions

diff --git a/opengl/specs/EGL_ANDROID_fence_sync.txt b/opengl/specs/EGL_ANDROID_fence_sync.txt
new file mode 100644
index 0000000..bb618c9
--- /dev/null
+++ b/opengl/specs/EGL_ANDROID_fence_sync.txt
@@ -0,0 +1,213 @@
+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.
diff --git a/opengl/specs/README b/opengl/specs/README
index 16b278f..af3f165 100644
--- a/opengl/specs/README
+++ b/opengl/specs/README
@@ -10,4 +10,7 @@ for use by Android extensions.
 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)