1Name 2 3 KHR_cl_event 4 5Name Strings 6 7 EGL_KHR_cl_event 8 9Contributors 10 11 Jon Leech, Khronos 12 Alon Or-bach, Samsung Electronics 13 14Contact 15 16 Jon Leech (jon 'at' alumni.caltech.edu) 17 18IP Status 19 20 No known claims. 21 22Notice 23 24 Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at 25 http://www.khronos.org/registry/speccopyright.html 26 27Status 28 29 This extension is obsolete and has been replaced by EGL_KHR_cl_event2. 30 Khronos recommends implementers who support this extension also 31 implement cl_event2, and begin transitioning developers to using that 32 extension. See issue 17 for the reason. 33 34 Complete. Approved by the EGL Working Group on 2013/05/15. 35 Approved by the Khronos Board of Promoters on 2013/07/19. 36 37Version 38 39 Version 10, December 4, 2013 40 41Number 42 43 EGL Extension #60 44 45Dependencies 46 47 EGL 1.4 and the EGL_KHR_fence_sync extension are required. 48 49 This extension is written against the language added to EGL 1.2 by 50 the EGL_KHR_fence_sync extension. 51 52 An OpenCL implementation supporting sharing OpenCL event objects 53 with EGL is required. 54 55Overview 56 57 This extension allows creating an EGL fence sync object linked to an 58 OpenCL event object, potentially improving efficiency of sharing 59 images between the two APIs. The companion cl_khr_egl_event 60 extension provides the complementary functionality of creating an 61 OpenCL event object from an EGL fence sync object. 62 63New Types 64 65 None. However, event handles of type cl_event, defined in the OpenCL 66 header files, may be included in the attribute list passed to 67 eglCreateSyncKHR. 68 69New Procedures and Functions 70 71 None 72 73New Tokens 74 75 Accepted as attribute names in the <attrib_list> argument 76 of eglCreateSyncKHR: 77 78 EGL_CL_EVENT_HANDLE_KHR 0x309C 79 80 Returned in <values> for eglGetSyncAttribKHR <attribute> 81 EGL_SYNC_TYPE_KHR: 82 83 EGL_SYNC_CL_EVENT_KHR 0x30FE 84 85 Returned in <values> for eglGetSyncAttribKHR <attribute> 86 EGL_SYNC_CONDITION_KHR: 87 88 EGL_SYNC_CL_EVENT_COMPLETE_KHR 0x30FF 89 90Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors) 91 92 Add following the description of fence sync objects in section 3.8.1 93 (e.g. following the paragraph beginning "<Fence sync objects> are 94 created..." 95 96 "A <CL event sync object> reflects the status of a corresponding 97 OpenCL event object to which the sync object is linked. This 98 provides another method of coordinating sharing of images between 99 EGL and OpenCL (see Chapter 9 of the OpenCL 1.0 Specification and 100 the cl_khr_egl_sharing extension). Waiting on such a sync object is 101 equivalent to waiting for completion of the linked CL event object." 102 103 Add following the description of fence sync objects (prior to the 104 "Errors" section for eglCreateSyncKHR): 105 106 "If <type> is EGL_SYNC_CL_EVENT_KHR, a CL event sync object is 107 created. In this case <attrib_list> must contain the attribute 108 EGL_CL_EVENT_HANDLE_KHR, set to a valid OpenCL event. Note that 109 EGL_CL_EVENT_HANDLE_KHR is not a queriable property of a sync 110 object. Attributes of the CL event sync objects are set as follows: 111 112 Attribute Name Initial Attribute Value(s) 113 ------------- -------------------------- 114 EGL_SYNC_TYPE_KHR EGL_SYNC_CL_EVENT_KHR 115 EGL_SYNC_STATUS_KHR Depends on status of <event> 116 EGL_SYNC_CONDITION_KHR EGL_SYNC_CL_EVENT_COMPLETE_KHR 117 118 The status of such a sync object depends on <event>. When the status 119 of <event> is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of 120 the linked sync object will be EGL_UNSIGNALED_KHR. When the status 121 of <event> changes to CL_COMPLETE, the status of the linked sync 122 object will become EGL_SIGNALED_KHR. 123 124 Creating a linked sync object places a reference on the linked 125 OpenCL event object. When the sync object is deleted, the reference 126 will be removed from the event object. 127 128 However, implementations are not required to validate the OpenCL 129 event, and passing an invalid event handle in <attrib_list> may 130 result in undefined behavior up to and including program 131 termination." 132 133 Add to the "Errors" section for eglCreateSyncKHR: 134 135 "* If <type> is EGL_SYNC_CL_EVENT_KHR then 136 137 ** If EGL_CL_EVENT_HANDLE_KHR is not specified in <attrib_list> 138 or is not a valid OpenCL event handle returned by a call to 139 clEnqueueReleaseGLObjects or clEnqueueReleaseEGLObjects, then 140 EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is 141 generated. 142 143 Replace the EGL_SYNC_CONDITION_KHR row of table 3.cc with: 144 145 "Attribute Description Supported Sync Objects 146 ----------------- ----------------------- ---------------------- 147 EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR or 148 EGL_SYNC_CL_EVENT_KHR 149 150 Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command" 151 152 153 Replace the second paragraph describing eglDestroySync with: 154 155 "If any eglClientWaitSyncKHR commands are blocking on <sync> when 156 eglDestroySyncKHR is called, <sync> is flagged for deletion and will 157 be deleted when the associated fence command or CL event object has 158 completed, and <sync> is no longer blocking any eglClientWaitSyncKHR 159 command. Otherwise, the sync object is destroyed immediately." 160 161Sample Code 162 163 None 164 165Conformance Tests 166 167 None yet 168 169Issues 170 171 1) Does this extension need to introduce eglWaitSync 172 functionality? 173 174 RESOLVED: The EGL_KHR_wait_sync extension introduces this, to allow 175 server-side synchronization, without blocking the client from issuing 176 commands. Whilst this is not a required dependency, GPU-to-GPU 177 synchronization is the most likely use of this extension. 178 179 2) What should the command to create a sync object linked to an 180 OpenCL event look like? 181 182 RESOLVED: We reuse the general attribute list mechanism rather than 183 having a constructor specific to CL events. This was intended in the 184 sync object design from the start. 185 186 3) How will the OpenCL header dependencies interact with 187 specifying the API for this extension? 188 189 DISCUSSION: To use this extension, OpenCL event handles of type cl_event 190 are specified in the attribute lists passed to eglCreateSyncKHR. Because 191 no formal parameters are of type cl_event, the EGL headers do not need 192 to define this type. Applications must #include the appropriate OpenCL 193 header files as well as <EGL/eglext.h> when using this extension. 194 195 This issue resolution is consistent with the equivalent issue for 196 GL_ARB_cl_event. 197 198 4) Should all possible statuses of the CL event be reflected through to the 199 state of the sync object? 200 201 DISCUSSION: CL event objects have four execution statuses: 202 CL_QUEUED, CL_SUBMITTED, CL_RUNNING, and CL_COMPLETE. GL sync 203 objects have only two statuses: UNSIGNALED and SIGNALED. The 204 cl_khr_gl_event extension maps UNSIGNALED into CL_SUBMITTED, and 205 SIGNALED into CL_COMPLETE. 206 207 RESOLVED: Invert the cl_khr_egl_event mapping. CL_QUEUED, 208 CL_SUBMITTED, and CL_RUNNING all map into UNSIGNALED. 209 CL_COMPLETE maps into SIGNALED. 210 211 This issue resolution is consistent with the equivalent issue for 212 GL_ARB_cl_event. 213 214 5) Are there any restrictions on the use of a sync object linked to a CL 215 event object? 216 217 RESOLVED: No restrictions. 218 219 6) How are sync object lifetimes defined? 220 221 RESOLVED: A sync object linked to a CL event object places a single 222 reference on the event. Deleting the sync object removes that reference. 223 224 eglDestroySync has a dependency on the completion of the linked event 225 object, and will not delete the sync objectwhile the event object has not 226 yet completed. This is equivalent to behavior of deleting a fence sync 227 object, where deletion of the object will be deferred until the underlying 228 fence command has completed. 229 230 This issue resolution is consistent with the equivalent issue for 231 GL_ARB_cl_event. 232 233 7) Should all OpenCL events be supported? 234 235 RESOLVED: No. Only events returned by clEnqueueReleaseGLObjects, or 236 clEnqueueReleaseEGLObjects since those are the only known use cases for 237 this extension. 238 239 8) Why has this extension been obsoleted and replaced by 240 EGL_KHR_cl_event2? 241 242 RESOLVED: Starting with the December 4, 2013 release of EGL 1.4, EGLint 243 is defined to be the same size as the native platform "int" type. Handle 244 and pointer attribute values *cannot* be represented in attribute lists 245 on platforms where sizeof(handle/pointer) > sizeof(int). Existing 246 extensions which assume this functionality are being replaced with new 247 extensions specifying new entry points to work around this issue. See 248 the latest EGL 1.4 Specification for more details. 249 250Revision History 251 252 Version 10, 2013/12/04 (Jon Leech) - add issue 8 explaining that OpenCL 253 event handles cannot be safely passed in attribute lists on 64-bit 254 platforms, and suggest using EGL_KHR_cl_event2 instead. 255 256 Version 9, 2013/08/12 (Jon Leech) - remove unused cl_event type from the 257 extension and from <EGL/eglext.h> (Bug 10661). 258 259 Version 8, 2013/07/19 (Jon Leech) - assign extension number and 260 missing enum value, and clean up a few typos for publication. 261 262 Version 7, 2013/07/08 (Jon Leech) - assign enums (Bug 10490). 263 264 Version 6, 2013/06/11 (Alon Or-bach) - typo correction 265 266 Version 5, 2013/05/30 (Alon Or-bach) - wording cleanup 267 268 Version 4, 2013/05/15 (Alon Or-bach) - updated issue resolutions as agreed, 269 consistent with GL_ARB_cl_event, including using typedef for cl_event 270 271 Version 3, 2013/04/25 (Alon Or-bach) - remove use of CL context, 272 accept events from clEnqueueAcquireEGLObjects and minor cleanup 273 274 Version 2, 2012/06/26 (Jon Leech) - update link to complementary CL 275 extension. 276 277 Version 1, 2010/05/18 (Jon Leech) - initial version based on 278 equivalent GL_ARB_cl_event extension. 279