diff --git a/opengl/specs/EGL_ANDROID_fence_sync.txt b/opengl/specs/EGL_ANDROID_fence_sync.txt new file mode 100644 index 000000000..bb618c92c --- /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 parameter of eglCreateSyncKHR, and returned + in when eglGetSyncAttribKHR is called with + EGL_SYNC_TYPE_KHR: + + EGL_SYNC_ANDROID_FENCE_ANDROID 0x3144 + + Accepted by the parameter of eglGetSyncAttribKHR: + + EGL_SYNC_FENCE_FD_ANDROID 0x3145 + + Returned in when eglGetSyncAttribKHR is called with + 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 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 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 unblock." + + Modify the list of eglCreateSyncKHR errors in Section 3.8.1 (Sync Objects), + added by KHR_fence_sync + + "Errors + ------ + + * If is not the name of a valid, initialized EGLDisplay, + EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is + generated. + * If is EGL_SYNC_FENCE_KHR and is neither NULL nor + empty (containing only EGL_NONE), EGL_NO_SYNC_KHR is returned and an + EGL_BAD_ATTRIBUTE error is generated. + * If is EGL_SYNC_ANDROID_FENCE_ANDROID and 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 is not a supported type of sync object, + EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is + generated. + * If 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 is EGL_SYNC_FENCE_KHR or EGL_SYNC_ANDROID_FENCE_ANDROID and + 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 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 will no + longer be the handle of a valid sync object. Additionally, if 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 16b278fd4..af3f1657f 100644 --- a/opengl/specs/README +++ b/opengl/specs/README @@ -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)