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)
|
||||
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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user