Add the EGL_ANDROID_fence_sync spec.
Change-Id: I8c26e5caaf8d89a60a09a5308d55e336537b916e
This commit is contained in:
Jamie Gennis
parent
24adb709b7
commit
1401ad526c
213
opengl/specs/EGL_ANDROID_fence_sync.txt
Normal file
213
opengl/specs/EGL_ANDROID_fence_sync.txt
Normal file
@ -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.
|
||||||
@ -10,4 +10,7 @@ for use by Android extensions.
|
|||||||
0x3141 (unused)
|
0x3141 (unused)
|
||||||
0x3142 EGL_ANDROID_recordable
|
0x3142 EGL_ANDROID_recordable
|
||||||
0x3143 EGL_VERSION_HW_ANDROID (internal use)
|
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)
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user