214 lines
8.8 KiB
Plaintext
214 lines
8.8 KiB
Plaintext
|
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.
|