1Name 2 3 KHR_cl_event2 4 5Name Strings 6 7 EGL_KHR_cl_event2 8 9Contributors 10 11 Jon Leech, Khronos 12 Alon Or-bach, Samsung Electronics 13 Tom Cooksey, ARM 14 15Contact 16 17 Jon Leech (jon 'at' alumni.caltech.edu) 18 19IP Status 20 21 No known claims. 22 23Notice 24 25 Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at 26 http://www.khronos.org/registry/speccopyright.html 27 28Status 29 30 Complete. 31 Approved by the EGL Working Group on December 4, 2013. 32 33Version 34 35 Version 5, December 4, 2013 36 37Number 38 39 EGL Extension #65 40 41Dependencies 42 43 EGL 1.4 and the EGL_KHR_fence_sync extension are required. 44 45 This extension is written against the language added to EGL 1.2 by 46 the EGL_KHR_fence_sync extension. 47 48 An OpenCL implementation supporting sharing OpenCL event objects 49 with EGL is required. 50 51 Khronos recommends obsoleting and replacing implementations of 52 EGL_KHR_cl_event with this extension as soon as possible. 53 54Overview 55 56 This extension allows creating an EGL sync object linked to an OpenCL 57 event object, potentially improving efficiency of sharing images between 58 the two APIs. The companion cl_khr_egl_event extension provides the 59 complementary functionality of creating an OpenCL event object from an 60 EGL sync object. 61 62 This extension is functionally identical to EGL_KHR_cl_event, but is 63 intended to replace that extension. It exists only to address an 64 implementation issue on 64-bit platforms where passing OpenCL event 65 handles in an EGLint attribute list value is impossible, because the 66 implementations use a 32-bit type for EGLint. 67 68 This extension also incorporates some required functionality from the 69 EGL_KHR_fence_sync extension, similarly modified for 64-bit platforms. 70 71New Types 72 73 /* 74 * EGLAttribKHR is a integer type used to pass arrays of attribute 75 * name/value pairs which may include pointer and handle attribute 76 * values. 77 */ 78 #include <khrplatform.h> 79 typedef intptr_t EGLAttribKHR; 80 81 Event handles of type cl_event, defined in the OpenCL header files, may 82 be included in the attribute list passed to eglCreateSync64KHR. 83 84New Procedures and Functions 85 86 EGLSyncKHR eglCreateSync64KHR( 87 EGLDisplay dpy, 88 EGLenum type, 89 const EGLAttribKHR *attrib_list); 90 91New Tokens 92 93 Accepted as attribute names in the <attrib_list> argument 94 of eglCreateSync64KHR: 95 96 EGL_CL_EVENT_HANDLE_KHR 0x309C 97 98 Returned in <values> for eglGetSyncAttribKHR <attribute> 99 EGL_SYNC_TYPE_KHR: 100 101 EGL_SYNC_CL_EVENT_KHR 0x30FE 102 103 Returned in <values> for eglGetSyncAttribKHR <attribute> 104 EGL_SYNC_CONDITION_KHR: 105 106 EGL_SYNC_CL_EVENT_COMPLETE_KHR 0x30FF 107 108Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) 109 110 Modify the language in section 3.8.1 (Sync Objects) starting at the 111 sixth paragraph, describing commands to create sync objects: 112 113 "The commands 114 115 EGLSyncKHR eglCreateSync64KHR( 116 EGLDisplay dpy, 117 EGLenum type, 118 const EGLAttribKHR *attrib_list); 119 120 and 121 122 EGLSyncKHR eglCreateSyncKHR( 123 EGLDisplay dpy, 124 EGLenum type, 125 const EGLint *attrib_list); 126 127 create a sync object ... 128 129 ... When a fence sync object is created, eglCreateSyncKHR and 130 eglCreateSync64KHR also insert a fence command into... " 131 132 Add following the eigth paragraph (the paragraph beginning "<Fence sync 133 objects> are created..."): 134 135 "A <CL event sync object> reflects the status of a corresponding OpenCL 136 event object to which the sync object is linked. This provides another 137 method of coordinating sharing of images between EGL and OpenCL (see 138 Chapter 9 of the OpenCL 1.0 Specification and the cl_khr_egl_sharing 139 extension). Waiting on such a sync object is equivalent to waiting for 140 completion of the linked CL event object. 141 142 CL event sync objects may only be created using the command 143 eglCreateSync64KHR, because they require an attribute which may not be 144 representable in the attrib_list argument of eglCreateSyncKHR." 145 146 Add following the description of fence sync objects (prior to the 147 "Errors" section for eglCreateSyncKHR): 148 149 "If <type> is EGL_SYNC_CL_EVENT_KHR, a CL event sync object is 150 created. In this case <attrib_list> must contain the attribute 151 EGL_CL_EVENT_HANDLE_KHR, set to a valid OpenCL event. Note that 152 EGL_CL_EVENT_HANDLE_KHR is not a queriable property of a sync 153 object. Attributes of the CL event sync objects are set as follows: 154 155 Attribute Name Initial Attribute Value(s) 156 ------------- -------------------------- 157 EGL_SYNC_TYPE_KHR EGL_SYNC_CL_EVENT_KHR 158 EGL_SYNC_STATUS_KHR Depends on status of <event> 159 EGL_SYNC_CONDITION_KHR EGL_SYNC_CL_EVENT_COMPLETE_KHR 160 161 The status of such a sync object depends on <event>. When the status 162 of <event> is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of 163 the linked sync object will be EGL_UNSIGNALED_KHR. When the status 164 of <event> changes to CL_COMPLETE, the status of the linked sync 165 object will become EGL_SIGNALED_KHR. 166 167 Creating a linked sync object places a reference on the linked 168 OpenCL event object. When the sync object is deleted, the reference 169 will be removed from the event object. 170 171 However, implementations are not required to validate the OpenCL 172 event, and passing an invalid event handle in <attrib_list> may 173 result in undefined behavior up to and including program 174 termination." 175 176 The command eglCreateSync64KHR must be used to create a CL event sync 177 object[fn1]. 178 179 [fn1] If the implementation also supports the older EGL_KHR_cl_event 180 extension, then eglCreateSyncKHR may also be used to create a CL 181 event sync object. However, this use is not recommended because it 182 is not portable to platforms where OpenCL event handles are larger 183 than 32 bits." 184 185 Modify the ninth and tenth paragraphs, starting "When the condition": 186 187 "When the condition of the sync object is satisfied, the sync is 188 signaled by the associated client API context, causing any 189 eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock. 190 191 The only condition supported for fence sync objects is 192 EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, which is satisfied by completion 193 of the fence command corresponding to the sync object, and all preceding 194 commands in the associated client API context's command stream. The sync 195 object will not be signaled until all effects from these commands on the 196 client API's internal and framebuffer state are fully realized. No other 197 state is affected by execution of the fence command. 198 199 Each client API which supports fence commands indicates this support 200 in the form of a client API extension. If the GL_OES_EGL_sync 201 extension is supported by OpenGL ES (either version 1.x or 2.0), a 202 fence sync object may be created when the currently bound API is 203 OpenGL ES. If the VG_KHR_EGL_sync extension is supported by OpenVG, 204 a fence sync object may be created when the currently bound API is 205 OpenVG. 206 207 The only condition supported for CL event sync objects is 208 EGL_SYNC_CL_EVENT_COMPLETE_KHR, which is satisfied when the status of 209 the OpenCL event associated with the sync object changes to CL_COMPLETE." 210 211 Add to the "Errors" section for eglCreateSyncKHR and eglCreateSync64KHR: 212 213 "* If <type> is EGL_SYNC_CL_EVENT_KHR then 214 215 ** If eglCreateSyncKHR was called, then EGL_NO_SYNC_KHR is returned and 216 an EGL_BAD_ATTRIBUTE error is generated. 217 218 ** If eglCreateSync64KHR was called and EGL_CL_EVENT_HANDLE_KHR is not 219 specified in <attrib_list>, or its attribute value is not a valid 220 OpenCL event handle returned by a call to clEnqueueReleaseGLObjects 221 or clEnqueueReleaseEGLObjects, then EGL_NO_SYNC_KHR is returned and 222 an EGL_BAD_ATTRIBUTE error is generated." 223 224 Replace the EGL_SYNC_CONDITION_KHR row of table 3.cc with: 225 226 "Attribute Description Supported Sync Objects 227 ----------------- ----------------------- ---------------------- 228 EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR or 229 EGL_SYNC_CL_EVENT_KHR 230 231 Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command" 232 233 234 Replace the second paragraph describing eglDestroySync with: 235 236 "If any eglClientWaitSyncKHR commands are blocking on <sync> when 237 eglDestroySyncKHR is called, <sync> is flagged for deletion and will 238 be deleted when the associated fence command or CL event object has 239 completed, and <sync> is no longer blocking any eglClientWaitSyncKHR 240 command. Otherwise, the sync object is destroyed immediately." 241 242Sample Code 243 244 None 245 246Conformance Tests 247 248 None yet 249 250Issues 251 252 Note that some issues from the EGL_KHR_cl_event and EGL_KHR_fence_sync 253 extensions also apply to this extension, which incorporates 254 functionality from both of those extensions while making it usable on a 255 64-bit architecture. Issues specific to this extension are below. 256 257 1) Why does this extension exist? 258 259 The existence of this extension is an unfortunate necessity. Khronos did 260 not define EGLint as a 64-bit type in the version of <khrplatform.h> we 261 provided, assuming that vendors on those platforms would do so. By the 262 time we discovered that not all vendors had done this, it was too late 263 to fix, because ABI considerations made it impossible for those vendors 264 to change to a 64-bit EGLint type. Our only option was to define new 265 extensions and commands using a new attribute type, EGLAttribKHR, which 266 is explicitly large enough to hold a pointer or handle. 267 268 2) What is the relationship of this extension to EGL_KHR_cl_event? 269 270 RESOLVED: The only functional difference is that the new 271 eglCreateSync64KHR command must be used to create CL event sync objects. 272 This is necessary because some 64-bit platforms define EGLint as a 273 32-bit type, making it impossible to pass an arbitrary OpenCL event 274 handle in the EGLint *attrib_list passed to eglCreateSyncKHR. 275 276 3) How are pointer- and handle-sized attributes represented? 277 278 RESOLVED: Using the new type EGLAttribKHR, which is explicitly defined 279 as an integer type large enough to hold a pointer. 280 281 EGLAttribKHR is defined as an alias of the ISO C intptr_t type, rather 282 than using one of the explicitly-sized types from khrplatform.h. 283 Requiring this means that khrplatform.h must make sure to include the 284 appropriate header file (probably <stdint.h>) and that a C compiler 285 supporting intptr_t must be used. In the past we were concerned about 286 older C/C++ compilers, but this seems an acceptable choice in 2013. 287 288 We could choose to use intptr_t as the base type of attribute lists, 289 instead of the EGLAttribKHR alias. As Ian Romanick has pointed out 290 passionately in ARB discussions, modern C compilers are required to 291 support a well-defined set of scalar types. There is no requirement to 292 use API-specific scalar types when explicitly defining a C API. 293 294 However, there is some value in semantically tagging parameters with EGL 295 types. Also, using 'intptr_t *attrib_list' would be cosmetically 296 objectionable due to mixing EGL* and C native scalar types in EGL APIs. 297 298 We probably want to wait until there's an EGL API compatibility break - 299 a hypothetical "EGL 2.0" - before moving to native ISO C types in our 300 interfaces. 301 302 4) Why is the new fence sync creation function defined here, instead of 303 in a separate EGL_KHR_fence_sync2 extension? 304 305 RESOLVED: eglCreateSync64KHR is defined here because this is the only 306 functionality requiring it, and we expect this extension to be a stopgap 307 for 64-bit platforms until the time that EGL 1.5 is defined. The EGL 1.5 308 core will presumably include only the EGLAttribKHR-based version of this 309 command. 310 311 If there are any new extensions using handle or pointer attributes in 312 the meantime, they should copy the EGLAttribKHR and eglCreateSync64KHR 313 language here as required. There is no harm in defining the same type or 314 command in multiple extensions, so long as the definitions are 315 compatible. 316 317 5) Why is the new command called eglCreateSync64KHR? 318 319 UNRESOLVED: For consistency with OpenGL, which has '64'-suffixed 320 commands for representing 64-bit integers and arbitrary offsets into GPU 321 memory. If we ever support EGL on 128-bit platforms this would be a 322 silly naming convention, but that time is probably many decades away and 323 by then EGL 1.5 should be defined and widely supported. The name 324 eglCreateSync2KHR was originally suggested. 325 326 6) Why is there no command for querying EGLAttribKHR attributes from 327 sync objects? 328 329 RESOLVED: Because the only sync attribute which requires the extra bits 330 in an EGLAttribKHR type is EGL_CL_EVENT_HANDLE_KHR, which is not 331 queryable. Sync attributes which are queryable will all fit into the 332 EGLint returned by eglGetSyncAttribKHR. 333 334 NOTE: It's unfortunate that this name is used, since it uses the 335 "AttribKHR" name for command returning EGLints. In EGL 1.5 we should use 336 a different name for the query. 337 338 7) Does this extension replace EGL_KHR_fence_sync and EGL_KHR_cl_event? 339 340 RESOLVED: It does not replace EGL_KHR_fence_sync, but extends it to 341 support creation of a new type of sync object, the CL event sync object. 342 343 RESOLVED: It is intended to replace EGL_KHR_cl_event; this extension 344 must be used for OpenCL interop on 64-bit platforms, and we hope all 345 vendors will implement it even on 32-bit platforms, for maximum code 346 portability. 347 348Revision History 349 350 Version 5, 20130/12/04 (Jon Leech) - minor cleanup for public release. 351 352 Version 4, 20130/10/16 (Jon Leech) - add Dependencies and Overview text 353 noting that this extension obsoletes and should replace 354 EGL_KHR_cl_event. 355 356 Version 3, 20130/10/15 (Jon Leech) - change type of EGLAttribKHR from 357 uintptr to intptr (Bug 11027). 358 359 Version 2, 20130/10/12 (Jon Leech) - merge EGL_KHR_fence_sync2 with this 360 extension, change the naming scheme, define EGLAttribKHR as uintptr_t, 361 and add a new issues list. 362 363 Version 1, 2010/10/02 (Tom Cooksey) - initial version based on 364 EGL_KHR_cl_event and adding 64-bit EGLAttrKHR variants. 365