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 Complete 20 21 Version 22 23 Version 3, September 4, 2012 24 25 Number 26 27 EGL Extension #50 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_FD_ANDROID 104 105 If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute is not 106 EGL_NO_NATIVE_FENCE_FD_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_FD_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, 161 EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is 162 generated. 163 * If <type> is not a supported type of sync object, 164 EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is 165 generated. 166 * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and 167 no context is current for the bound API (i.e., eglGetCurrentContext 168 returns EGL_NO_CONTEXT), EGL_NO_SYNC_KHR is returned and an 169 EGL_BAD_MATCH error is generated. 170 * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and 171 <dpy> does not match the EGLDisplay of the currently bound context for 172 the currently bound client API (the EGLDisplay returned by 173 eglGetCurrentDisplay()) then EGL_NO_SYNC_KHR is returned and an 174 EGL_BAD_MATCH error is generated. 175 * If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and 176 the currently bound client API does not support the client API 177 extension indicating it can place fence commands, then EGL_NO_SYNC_KHR 178 is returned and an EGL_BAD_MATCH error is generated." 179 180 Modify table 3.cc in Section 3.8.1 (Sync Objects), added by KHR_fence_sync 181 182 " 183 Attribute Description Supported Sync Objects 184 ----------------- ----------------------- ---------------------- 185 EGL_SYNC_TYPE_KHR Type of the sync object All 186 EGL_SYNC_STATUS_KHR Status of the sync object All 187 EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR and 188 EGL_SYNC_NATIVE_FENCE_ANDROID only 189 " 190 191 Modify the second paragraph description of eglDestroySyncKHR in Section 192 3.8.1 (Sync Objects), added by KHR_fence_sync 193 194 "If no errors are generated, EGL_TRUE is returned, and <sync> will no 195 longer be the handle of a valid sync object. Additionally, if <sync> is an 196 EGL native fence sync object and the EGL_SYNC_NATIVE_FENCE_FD_ANDROID 197 attribute is not EGL_NO_NATIVE_FENCE_FD_ANDROID then that file descriptor 198 is closed." 199 200 Add the following after the last paragraph of Section 3.8.1 (Sync 201 Objects), added by KHR_fence_sync 202 203 The command 204 205 EGLint eglDupNativeFenceFDANDROID( 206 EGLDisplay dpy, 207 EGLSyncKHR sync); 208 209 duplicates the file descriptor stored in the 210 EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of an EGL native fence sync 211 object and returns the new file descriptor. 212 213 Errors 214 ------ 215 216 * If <sync> is not a valid sync object for <dpy>, 217 EGL_NO_NATIVE_FENCE_FD_ANDROID is returned and an EGL_BAD_PARAMETER 218 error is generated. 219 * If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of <sync> is 220 EGL_NO_NATIVE_FENCE_FD_ANDROID, EGL_NO_NATIVE_FENCE_FD_ANDROID is 221 returned and an EGL_BAD_PARAMETER error is generated. 222 * If <dpy> does not match the display passed to eglCreateSyncKHR 223 when <sync> was created, the behaviour is undefined." 224 225 Issues 226 227 1. Should EGLSyncKHR objects that wrap native fence objects use the 228 EGL_SYNC_FENCE_KHR type? 229 230 RESOLVED: A new sync object type will be added. 231 232 We don't want to require all EGL fence sync objects to wrap native fence 233 objects, so we need some way to tell the EGL implementation at sync object 234 creation whether the sync object should support querying the native fence 235 FD attribute. We could do this with either a new sync object type or with a 236 boolean attribute. It might be nice to pick up future signaling conditions 237 that might be added for fence sync objects, but there may be things that 238 get added that don't make sense in the context of native fence objects. 239 240 2. Who is responsible for dup'ing the native fence file descriptors? 241 242 RESOLVED: Whenever a file descriptor is passed into or returned from an 243 EGL call in this extension, ownership of that file descriptor is 244 transfered. The recipient of the file descriptor must close it when it is 245 no longer needed, and the provider of the file descriptor must dup it 246 before providing it if they require continued use of the native fence. 247 248 3. Can the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute be queried? 249 250 RESOLVED: No. 251 252 Returning the file descriptor owned by the EGL implementation would 253 violate the file descriptor ownership rule described in issue #2. Having 254 eglGetSyncAttribKHR return a different (dup'd) file descriptor each time 255 it's called seems wrong, so a new function was added to explicitly dup the 256 file descriptor. 257 258 That said, the attribute is useful both as a way to pass an existing file 259 descriptor to eglCreateSyncKHR and as a way to describe the subsequent 260 behavior of EGL native fence sync objects, so it is left as an attribute 261 for which the value cannot be queried. 262 263 Revision History 264 265 #3 (Jamie Gennis, September 4, 2012) 266 - Reworded the extension to refer to "native fence" objects rather than 267 "Android fence" objects. 268 - Added a paragraph to the overview that describes assumptions about the 269 native fence sync objects. 270 271 #2 (Jamie Gennis, July 23, 2012) 272 - Changed the file descriptor ownership transferring behavior. 273 - Added the eglDupAndroidFenceFDANDROID function. 274 - Removed EGL_SYNC_NATIVE_FENCE_FD_ANDROID from the table of gettable 275 attributes. 276 - Added language specifying that a native Android fence is created at the 277 flush following the creation of an EGL Android fence sync object that is 278 not passed an existing native fence. 279 280 #1 (Jamie Gennis, May 29, 2012) 281 - Initial draft. 282
