1Name 2 3 EXT_sync_reuse 4 5Name Strings 6 7 EGL_EXT_sync_reuse 8 9Contributors 10 11 Daniel Kartch 12 Jeff Vigil 13 Ray Smith 14 15Contacts 16 17 Daniel Kartch, NVIDIA Corporation (dkartch 'at' nvidia.com) 18 19Status 20 21 Complete 22 23Version 24 25 Version 4, May 16, 2018 26 27Number 28 29 EGL Extension #128 30 31Extension type 32 33 EGL display extension 34 35Dependencies 36 37 Requires EGL 1.5 or EGL 1.4 with EGL_KHR_fence_sync 38 39 Interacts with EGL_KHR_reusable_sync 40 Interacts with EGL_ANDROID_native_fence_sync 41 Interacts with EGL_NV_cuda_event 42 43 This extension is written against the wording of the EGL 1.5 44 Specification. 45 46Overview 47 48 The original EGLSync extensions separated sync objects into two 49 types: fence sync objects signaled by one time events in an 50 API command pipeline; and reusable sync objects signaled by commands 51 which can be issued again and again. However, this conflates 52 reusability of the event triggering a sync object with the EGLSync 53 object itself. 54 55 Although the event associated with a fence sync object will only 56 occur once, there is no reason that it can't be replaced with a new 57 event. Doing so would avoid unnecessary allocation and free 58 operations in an application that repeatedly waits for events. With 59 the current interfaces, such applications must constantly create and 60 destroy new EGLSync objects. 61 62 This extension allows all sync objects to be reusable. When a sync 63 object is in the signaled state, it can be reset back to an 64 unsignaled state, regenerating or reevaluating the events that 65 trigger them. For fence sync objects, this means generating a new 66 fence in the current API. For OpenCL event sync objects, this means 67 waiting for a new OpenCL event handle. This mechanism also allows 68 sync objects to be created in the signaled state with no associated 69 fence/event, and have one applied later. Thus all EGLSyncs required 70 by an application can be allocated up front, before any rendering 71 operations have begun. 72 73New Types 74 75 None 76 77New Tokens 78 79 None 80 81New Procedures and Functions 82 83 EGLBoolean eglUnsignalSyncEXT( 84 EGLDisplay dpy, 85 EGLSync sync, 86 const EGLAttrib *attrib_list); 87 88Replace text of subsections of 3.8.1 through 3.8.1.2 of EGL 1.5 89Specification. Existing tables are preserved. 90 91 3.8.1 Sync Objects 92 93 In addition to the aforementioned synchronization functions, which 94 provide an efficient means of serializing client and native API 95 operations within a thread, <sync objects> are provided to enable 96 synchronization of client API operations between threads and/or 97 between API contexts. Sync objects may be tested or waited upon by 98 application threads. 99 100 Sync objects have a status with two possible states: <signaled> and 101 <unsignaled>, and may initially be in either state. EGL may be asked 102 to wait for a sync object to become signaled, or a sync object�s 103 status may be queried. 104 105 Depending on the type of a sync object, its status may be changed 106 either by an external event, or by explicitly signaling and/or 107 unsignaling the sync. All sync objects are reusable. Once they enter 108 the signaled state, they may be changed back to unsignaled, possibly 109 replacing the associated external event that signals them. 110 111 Sync objects are associated with an EGLDisplay when they are 112 created, and have <attributes> defining additional aspects of the 113 sync object. All sync objects include attributes for their type and 114 their status. Additional attributes are discussed below for 115 different types of sync objects. If a sync object is created in the 116 signaled state, its initial attribute list may be incomplete, with 117 attributes necessary for its type provided when it is changed to 118 unsignaled. 119 120 <Fence sync objects> have an associated fence command in a client 121 API. A new fence command is generated whenever the sync object 122 enters the unsignaled state. When the client API executes the fence 123 command, an event is generated which signals the corresponding fence 124 sync object. Fence sync objects may not be explicitly signaled. 125 Fence sync objects may be used to wait for partial completion of a 126 client API command stream, as a more flexible form of glFinish or 127 vgFinish. 128 129 An <OpenCL event sync object> reflects the status of a corresponding 130 OpenCL event object to which the sync object is linked. This 131 provides another method of coordinating sharing of images between 132 EGL and OpenCL (see Chapter 9 of the OpenCL 1.0 Specification and 133 the cl_khr_egl_image extension). Waiting on such a sync object is 134 equivalent to waiting for completion of the linked OpenCL event 135 object. 136 137 The command 138 139 EGLSync eglCreateSync(EGLDisplay dpy, EGLenum type, const 140 EGLAttrib *attrib_list); 141 142 creates a sync object of the specified <type> associated with the 143 specified display <dpy>, and returns a handle to the new object. 144 <attrib list> is NULL or an attribute-value list specifying other 145 attributes of the sync object, terminated by an attribute entry 146 EGL_NONE. Attributes not specified in the list will be assigned 147 their default values. 148 149 The EGL_SYNC_STATUS attribute is defined for all sync types, but may 150 only be specified explicitly at creation time for some types of sync 151 objects, as discussed below. Other attributes are only allowed as 152 indicated below for the sync type. 153 154 Errors 155 156 eglCreateSync returns EGL_NO_SYNC on failure. 157 If <dpy> is not the name of a valid, initialized EGLDisplay, an 158 EGL_BAD_DISPLAY error is generated. 159 If <attrib_list> contains an attribute name not defined or not 160 allowed for the type of sync object being created, an 161 EGL_BAD_ATTRIBUTE error is generated. 162 If <type> is not a supported type of sync object, an 163 EGL_BAD_PARAMETER error is generated. 164 If <type> is EGL_SYNC_FENCE, the EGL_SYNC_STATUS attribute is 165 set to EGL_UNSIGNALED, and any of the following are true of the 166 current context for the bound API (the context returned by 167 eglGetCurrentContext), an EGL_BAD_MATCH error is generated: 168 * There is no current context (i.e., eglGetCurrentContext 169 returns EGL_NO_CONTEXT). 170 * <dpy> does not match the EGLDisplay of the context (the 171 EGLDisplay returned by eglGetCurrentDisplay). 172 * The context does not support fence commands. 173 174 While in the unsignaled state, the synchronization event associated 175 with a sync object cannot be changed. When the <condition> of a sync 176 object in the unsignaled state is satisfied, the sync is signaled, 177 causing any eglClientWaitSync or eglWaitSync commands (see below) 178 blocking on the sync to unblock. 179 180 Once signaled, a sync object may be reused for a new synchronization 181 event by switching it back to unsignaled. The command 182 183 EGLBoolean eglUnsignalSyncEXT(EGLDisplay dpy, EGLSync sync, 184 const EGLAttrib *attrib_list); 185 186 can be used to change the <sync> associated with display <dpy> from 187 the signaled state to the unsignaled state. The attribute list may 188 be used to provide or replace attributes specific to the sync type 189 as discussed below. The sync object's type and condition may not be 190 changed. 191 192 Errors 193 194 eglUnsignalSyncEXT returns EGL_FALSE on failure, and has no 195 effect on <sync>. 196 If <dpy> is not the name of a valid, initialized EGLDisplay, an 197 EGL_BAD_DISPLAY error is generated. 198 If <sync> is not a valid sync object associated with <dpy>, an 199 EGL_BAD_PARAMETER error is generated. 200 If <attrib_list> contains an attribute name not defined for the 201 type of <sync>, an EGL_BAD_ATTRIBUTE error is generated. 202 If <sync> is already in the unsignaled state, an EGL_BAD_ACCESS 203 error is generated. 204 If <sync>'s type is EGL_SYNC_FENCE and any of the following are 205 true of the current context for the bound API (the context 206 returned by eglGetCurrentContext), an EGL_BAD_MATCH error is 207 generated: 208 * There is no current context (i.e., eglGetCurrentContext 209 returns EGL_NO_CONTEXT). 210 * <dpy> does not match the EGLDisplay of the context (the 211 EGLDisplay returned by eglGetCurrentDisplay). 212 * The context does not support fence commands. 213 If <sync>'s type is EGL_SYNC_CL_EVENT and EGL_CL_EVENT_HANDLE 214 is not specified in <attrib_list>, then an EGL_BAD_ATTRIBUTE 215 error is generated. 216 217 3.8.1.1 Creating and Signaling Fence Sync Objects 218 219 If type is EGL_SYNC_FENCE, a fence sync object is created. The 220 EGL_SYNC_STATUS attribute may be specified as either EGL_UNSIGNALED 221 or EGL_SIGNALED, and will default to EGL_UNSIGNALED. No other 222 attributes may be specified for a fence sync object, either with 223 eglCreateSync or eglUnsignalSyncEXT. Queriable attributes of the 224 fence sync object are set as shown in table 3.7. 225 226 When a fence sync object is created in the unsignaled state, or 227 switched to that state with eglUnsignalSyncEXT, a fence command is 228 inserted into the command stream of the bound client API�s current 229 context (i.e., the context returned by eglGetCurrentContext), and is 230 associated with the sync object. 231 232 The only condition supported for fence sync objects is 233 EGL_SYNC_PRIOR_COMMANDS_COMPLETE, which is satisfied by completion 234 of the fence command corresponding to the sync object, and all 235 preceding commands in the associated client API context�s command 236 stream. The sync object will not be signaled until all effects from 237 these commands on the client API�s internal and framebuffer state 238 are fully realized. No other state is affected by execution of the 239 fence command. 240 241 Generation of fence commands for fence sync objects requires support 242 from the bound client API, and will not succeed unless the client 243 API satisfies one of the following properties. Note that eglWaitSync 244 (see section 3.8.1.3) also requires satisfying these conditions. 245 * client API is OpenGL, and either the OpenGL version is 3.2 or 246 greater, or the GL_ARB_sync extension is supported. 247 * client API is OpenGL ES, and either the OpenGL ES version is 3.0 248 or greater, or the GL_OES_EGL_sync extension is supported. 249 * client API is OpenVG, and the VG_KHR_EGL_sync extension is 250 supported. 251 252 3.8.1.2 Creating and Signaling OpenCL Event Sync Objects 253 254 If type is EGL_SYNC_CL_EVENT, an OpenCL event sync object is 255 created. The EGL_SYNC_STATUS attribute may not be explicitly 256 specified during creation of this type of sync object. If no 257 EGL_CL_EVENT_HANDLE attribute is specified at creation time, the 258 sync object will be created in the signaled state. Otherwise its 259 status will be determined by the provided OpenCL event, as described 260 below. An EGL_CL_EVENT_HANDLE must always be specified for 261 eglUnsignalSyncEXT. 262 263 To use an OpenCL event sync object, the EGL_SYNC_CL_EVENT attribute 264 must be set to a valid OpenCL <event> handle returned by a call to 265 clEnqueueReleaseGLObjects or clEnqueueReleaseEGLObjects; other types 266 of OpenCL event handles are not supported. Implementations are not 267 required to validate the OpenCL event, and passing an invalid event 268 handle in <attrib_list> may result in undefined behavior up to and 269 including program termination. Note that EGL_CL_EVENT_HANDLE is not 270 a queriable property of a sync object. Queriable attributes of the 271 OpenCL event sync object are set as shown in table 3.8. 272 273 The status of such a sync object depends on <event>. When the status 274 of <event> is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of 275 the linked sync object will be EGL_UNSIGNALED. When the status of 276 <event> changes to CL_COMPLETE, the status of the linked sync object 277 will become EGL_SIGNALED. 278 279 The only condition supported for OpenCL event sync objects is 280 EGL_SYNC_CL_EVENT_COMPLETE, which is satisfied when the status of 281 the OpenCL event associated with the sync object changes to 282 CL_COMPLETE. 283 284 Associating an OpenCL event handle with a sync object places a 285 reference on the linked OpenCL object. When the sync object is 286 deleted or the event handle is replaced, the reference will be 287 removed from the OpenCL object. 288 289If EGL_KHR_reusable_sync is present, then for sync objects of type 290EGL_SYNC_REUSABLE_KHR, the initial value of EGL_SYNC_STATUS may be 291set to either EGL_UNSIGNALED or EGL_SIGNALED, and will default to 292EGL_UNSIGNALED. 293 294If EGL_ANDROID_native_fence_sync is present, then for native fence sync 295objects, the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute may be specified 296in eglUnsignalSyncEXT as well as eglCreateSync. If it is set to anything 297other than EGL_NO_NATIVE_FENCE_FD_ANDROID at creation time, then its 298initial EGL_SYNC_STATUS will reflect the current status of the provided 299fence FD, and it is an error to specifically set the status. If it is 300set to EGL_NO_NATIVE_FENCE_FD_ANDROID, then its EGL_SYNC_STATUS may be 301set to either EGL_UNSIGNALED (the default) or EGL_SIGNALED. If the 302status is signaled, then no native fence will be generated until after 303it is switched to unsignaled. If eglUnsignalSyncEXT is called for a 304native fence sync object with an FD of EGL_NO_NATIVE_FENCE_FD_ANDROID, 305then a new native fence will be generated at the next Flush(), as 306described for eglCreateSync. 307 308If EGL_NV_cuda_event is present, then for CUDA event sync objects, the 309EGL_CUDA_EVENT_HANDLE_NV may be specified in eglUnsignalSyncEXT as well 310as eglCreateSync. The current CUDA event handle is evaluated at the time 311the EGL sync object becomes unsignaled, and subsequent modification of 312the CUDA object with cudaEventRecord has no effect on the sync object 313until it is signaled. Subsequently restoring the sync object to 314unsignaled will cause the CUDA object to be reevaluated. 315 316Issues 317 318 1. Should a new attribute be required to specify a sync object as 319 reusable? 320 321 RESOLVED: No. The presence of this extension is sufficient to 322 indicate reusability of all sync objects. This will not create 323 any incompatibilities with existing applications that use sync 324 objects only once. 325 326 2. Can we leverage the existing eglSignalSyncKHR function from 327 EGL_KHR_reusable_sync for this extension? 328 329 RESOLVED: No. Some types of sync objects require attributes 330 which are themselves single-use objects, and must be replaced 331 for the sync object to be reused. Therefore a new function which 332 takes an attribute list is required. 333 334 3. Should the function for unsignaling be based on eglSignalSyncKHR 335 from the KHR_reusable_sync extension, and take a mode parameter 336 to distinguish signaling/unsignaling? 337 338 RESOLVED: No. While all sync objects will support unsignaling, 339 the reusable sync object is the only known one that supports 340 direct signaling, rather than signaling through some condition 341 being achieved. Therefore it is simplest to have the new 342 function only support unsignaling, and continue to use the old 343 extension for the one case where signaling is required. 344 345 4. If the initial attribute list is incomplete (e.g. an OpenCL 346 event handle is not provided during creation of an OpenCL event 347 sync object), should the EGL_SYNC_STATUS default to EGL_SIGNALED 348 rather than generating an error if it is left unspecified? 349 350 RESOLVED: Handling of allowed/default values for EGL_SYNC_STATUS 351 is based on the sync type. For fence syncs, either value is 352 allowed, defaulting to EGL_UNSIGNALED. For OpenCL event syncs, 353 the value may not be specified, and instead is determined by 354 whether an OpenCL event is provided at creation time, and if so 355 by the status of that event. 356 357Revision History 358 359 #4 (May 16, 2018) Daniel Kartch 360 - Minor corrections to wording 361 362 #3 (April 20, 2018) Daniel Kartch 363 - Renamed to EXT 364 - Fixed grammatical errors and prepared for publication 365 366 #2 (January 23, 2018) Daniel Kartch 367 - Rewrote some sections for clarity, and fixed typos 368 - Changed default/allowed behavior for signal state at creation 369 time to be determined by the sync type and other attributes. 370 - Simplified interaction with EGL_KHR_reusable_sync. 371 - Refined interaction with EGL_ANDROID_native_fence_sync to 372 clarify allowed initial states for the sync status and fix the 373 description of when new native fences are generated. 374 375 #1 (January 16, 2018) Daniel Kartch 376 - Initial draft as XXX 377