| 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. |