Add the EGL_ANDROID_fence_sync spec.
Change-Id: I8c26e5caaf8d89a60a09a5308d55e336537b916e
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 @@
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)