1 Name 2 3 ANDROID_native_fence_sync 4 5 Name Strings 6 7 EGL_ANDROID_native_fence_sync 8 9 Contributors 10 11 Jamie Gennis 12 13 Contact 14 15 Jamie Gennis, Google Inc. (jgennis 'at' google.com) 16 17 Status 18 19 Draft. 20 21 Version 22 23 Version 3, September 4, 2012 24 25 Number 26 27 EGL Extension #XXX 28 29 Dependencies 30 31 Requires EGL 1.1 32 33 This extension is written against the wording of the EGL 1.2 Specification 34 35 EGL_KHR_fence_sync is required. 36 37 Overview 38 39 This extension enables the creation of EGL fence sync objects that are 40 associated with a native synchronization fence object that is referenced 41 using a file descriptor. These EGL fence sync objects have nearly 42 identical semantics to those defined by the KHR_fence_sync extension, 43 except that they have an additional attribute storing the file descriptor 44 referring to the native fence object. 45 46 This extension assumes the existence of a native fence synchronization 47 object that behaves similarly to an EGL fence sync object. These native 48 objects must have a signal status like that of an EGLSyncKHR object that 49 indicates whether the fence has ever been signaled. Once signaled the 50 native object's signal status may not change again. 51 52 New Types 53 54 None. 55 56 New Procedures and Functions 57 58 EGLint eglDupNativeFenceFDANDROID( 59 EGLDisplay dpy, 60 EGLSyncKHR); 61 62 New Tokens 63 64 Accepted by the <type> parameter of eglCreateSyncKHR, and returned 65 in <value> when eglGetSyncAttribKHR is called with <attribute> 66 EGL_SYNC_TYPE_KHR: 67 68 EGL_SYNC_NATIVE_FENCE_ANDROID 0x3144 69 70 Accepted by the <attrib_list> parameter of eglCreateSyncKHR: 71 72 EGL_SYNC_NATIVE_FENCE_FD_ANDROID 0x3145 73 74 Accepted by the <attrib_list> parameter of eglCreateSyncKHR, and returned 75 by eglDupNativeFenceFDANDROID in the event of an error: 76 77 EGL_NO_NATIVE_FENCE_FD_ANDROID -1 78 79 Returned in <value> when eglGetSyncAttribKHR is called with <attribute> 80 EGL_SYNC_CONDITION_KHR: 81 82 EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID 0x3146 83 84 Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) 85 86 Add the following after the sixth paragraph of Section 3.8.1 (Sync 87 Objects), added by KHR_fence_sync 88 89 "If <type> is EGL_SYNC_NATIVE_FENCE_ANDROID, an EGL native fence sync 90 object is created. In this case the EGL_SYNC_NATIVE_FENCE_FD_ANDROID 91 attribute may optionally be specified. If this attribute is specified, it 92 must be set to either a file descriptor that refers to a native fence 93 object or to the value EGL_NO_NATIVE_FENCE_FD_ANDROID. 94 95 The default values for the EGL native fence sync object attributes are as 96 follows: 97 98 Attribute Name Initial Attribute Value(s) 99 --------------- -------------------------- 100 EGL_SYNC_TYPE_KHR EGL_SYNC_NATIVE_FENCE_ANDROID 101 EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR 102 EGL_SYNC_CONDITION_KHR EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR 103 EGL_SYNC_NATIVE_FENCE_FD_ANDROID EGL_NO_NATIVE_FENCE_ANDROID 104 105 If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute is not 106 EGL_NO_NATIVE_FENCE_ANDROID then the EGL_SYNC_CONDITION_KHR attribute is 107 set to EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID and the EGL_SYNC_STATUS_KHR 108 attribute is set to reflect the signal status of the native fence object. 109 Additionally, the EGL implementation assumes ownership of the file 110 descriptor, so the caller must not use it after calling eglCreateSyncKHR." 111 112 Modify Section 3.8.1 (Sync Objects), added by KHR_fence_sync, starting at 113 the seventh paragraph 114 115 "When a fence sync object is created or when an EGL native fence sync 116 object is created with the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute set 117 to EGL_NO_NATIVE_FENCE_ANDROID, eglCreateSyncKHR also inserts a fence 118 command into the command stream of the bound client API's current context 119 (i.e., the context returned by eglGetCurrentContext), and associates it 120 with the newly created sync object. 121 122 After associating the fence command with an EGL native fence sync object, 123 the next Flush() operation performed by the current client API causes a 124 new native fence object to be created, and the 125 EGL_SYNC_NATIVE_FENCE_ANDROID attribute of the EGL native fence object is 126 set to a file descriptor that refers to the new native fence object. This 127 new native fence object is signaled when the EGL native fence sync object 128 is signaled. 129 130 When the condition of the sync object is satisfied by the fence command, 131 the sync is signaled by the associated client API context, causing any 132 eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock. 133 If the sync object is an EGL native fence sync object then the native 134 fence object is also signaled when the condition is satisfied. The 135 EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR condition is satisfied by completion 136 of the fence command corresponding to the sync object and all preceding 137 commands in the associated client API context's command stream. The sync 138 object will not be signaled until all effects from these commands on the 139 client API's internal and framebuffer state are fully realized. No other 140 state is affected by execution of the fence command. 141 142 The EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID condition is satisfied by the 143 signaling of the native fence object referred to by the 144 EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute. When this happens any 145 eglClientWaitSyncKHR commands blocking on <sync> unblock." 146 147 Modify the list of eglCreateSyncKHR errors in Section 3.8.1 (Sync Objects), 148 added by KHR_fence_sync 149 150 "Errors 151 ------ 152 153 * If <dpy> is not the name of a valid, initialized EGLDisplay, 154 EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is 155 generated. 156 * If <type> is EGL_SYNC_FENCE_KHR and <attrib_list> is neither NULL nor 157 empty (containing only EGL_NONE), EGL_NO_SYNC_KHR is returned and an 158 EGL_BAD_ATTRIBUTE error is generated. 159 * If <type> is EGL_SYNC_NATIVE_FENCE_ANDROID and <attrib_list> contains 160 an attribute other than EGL_SYNC_NATIVE_FENCE_FD_ANDROID, EGL_NO_SYNC_KHR is 161 returned and an EGL_BAD_ATTRIBUTE error is generated. 162 * If <type> is not a supported type of sync object, 163 EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is 164 generated. 165 * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and 166 no context is current for the bound API (i.e., eglGetCurrentContext 167 returns EGL_NO_CONTEXT), EGL_NO_SYNC_KHR is returned and an 168 EGL_BAD_MATCH error is generated. 169 * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and 170 <dpy> does not match the EGLDisplay of the currently bound context for 171 the currently bound client API (the EGLDisplay returned by 172 eglGetCurrentDisplay()) then EGL_NO_SYNC_KHR is returned and an 173 EGL_BAD_MATCH error is generated. 174 * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and 175 the currently bound client API does not support the client API 176 extension indicating it can place fence commands, then EGL_NO_SYNC_KHR 177 is returned and an EGL_BAD_MATCH error is generated." 178 179 Modify table 3.cc in Section 3.8.1 (Sync Objects), added by KHR_fence_sync 180 181 " 182 Attribute Description Supported Sync Objects 183 ----------------- ----------------------- ---------------------- 184 EGL_SYNC_TYPE_KHR Type of the sync object All 185 EGL_SYNC_STATUS_KHR Status of the sync object All 186 EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR and 187 EGL_SYNC_NATIVE_FENCE_ANDROID only 188 " 189 190 Modify the second paragraph description of eglDestroySyncKHR in Section 191 3.8.1 (Sync Objects), added by KHR_fence_sync 192 193 "If no errors are generated, EGL_TRUE is returned, and <sync> will no 194 longer be the handle of a valid sync object. Additionally, if <sync> is an 195 EGL native fence sync object and the EGL_SYNC_NATIVE_FENCE_FD_ANDROID 196 attribute is not EGL_NO_NATIVE_FENCE_ANDROID then that file descriptor is 197 closed." 198 199 Add the following after the last paragraph of Section 3.8.1 (Sync 200 Objects), added by KHR_fence_sync 201 202 The command 203 204 EGLint eglDupNativeFenceFDANDROID( 205 EGLDisplay dpy, 206 EGLSyncKHR sync); 207 208 duplicates the file descriptor stored in the 209 EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of an EGL native fence sync 210 object and returns the new file descriptor. 211 212 Errors 213 ------ 214 215 * If <sync> is not a valid sync object for <dpy>, 216 EGL_NO_NATIVE_FENCE_ANDROID is returned and an EGL_BAD_PARAMETER 217 error is generated. 218 * If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of <sync> is 219 EGL_NO_NATIVE_FENCE_ANDROID, EGL_NO_NATIVE_FENCE_ANDROID is returned 220 and an EGL_BAD_PARAMETER error is generated. 221 * If <dpy> does not match the display passed to eglCreateSyncKHR 222 when <sync> was created, the behaviour is undefined." 223 224 Issues 225 226 1. Should EGLSyncKHR objects that wrap native fence objects use the 227 EGL_SYNC_FENCE_KHR type? 228 229 RESOLVED: A new sync object type will be added. 230 231 We don't want to require all EGL fence sync objects to wrap native fence 232 objects, so we need some way to tell the EGL implementation at sync object 233 creation whether the sync object should support querying the native fence 234 FD attribute. We could do this with either a new sync object type or with a 235 boolean attribute. It might be nice to pick up future signaling conditions 236 that might be added for fence sync objects, but there may be things that 237 get added that don't make sense in the context of native fence objects. 238 239 2. Who is responsible for dup'ing the native fence file descriptors? 240 241 RESOLVED: Whenever a file descriptor is passed into or returned from an 242 EGL call in this extension, ownership of that file descriptor is 243 transfered. The recipient of the file descriptor must close it when it is 244 no longer needed, and the provider of the file descriptor must dup it 245 before providing it if they require continued use of the native fence. 246 247 3. Can the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute be queried? 248 249 RESOLVED: No. 250 251 Returning the file descriptor owned by the EGL implementation would 252 violate the file descriptor ownership rule described in issue #2. Having 253 eglGetSyncAttribKHR return a different (dup'd) file descriptor each time 254 it's called seems wrong, so a new function was added to explicitly dup the 255 file descriptor. 256 257 That said, the attribute is useful both as a way to pass an existing file 258 descriptor to eglCreateSyncKHR and as a way to describe the subsequent 259 behavior of EGL native fence sync objects, so it is left as an attribute 260 for which the value cannot be queried. 261 262 Revision History 263 264 #3 (Jamie Gennis, September 4, 2012) 265 - Reworded the extension to refer to "native fence" objects rather than 266 "Android fence" objects. 267 - Added a paragraph to the overview that describes assumptions about the 268 native fence sync objects. 269 270 #2 (Jamie Gennis, July 23, 2012) 271 - Changed the file descriptor ownership transferring behavior. 272 - Added the eglDupAndroidFenceFDANDROID function. 273 - Removed EGL_SYNC_NATIVE_FENCE_FD_ANDROID from the table of gettable 274 attributes. 275 - Added language specifying that a native Android fence is created at the 276 flush following the creation of an EGL Android fence sync object that is 277 not passed an existing native fence. 278 279 #1 (Jamie Gennis, May 29, 2012) 280 - Initial draft. 281
