1Name 2 3 ARB_cl_event 4 5Name Strings 6 7 GL_ARB_cl_event 8 9Contributors 10 11 Jon Leech, Khronos 12 13Contact 14 15 Jon Leech (jon 'at' alumni.caltech.edu) 16 17Notice 18 19 Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at 20 http://www.khronos.org/registry/speccopyright.html 21 22Specification Update Policy 23 24 Khronos-approved extension specifications are updated in response to 25 issues and bugs prioritized by the Khronos OpenGL Working Group. For 26 extensions which have been promoted to a core Specification, fixes will 27 first appear in the latest version of that core Specification, and will 28 eventually be backported to the extension document. This policy is 29 described in more detail at 30 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 31 32Status 33 34 Complete. Approved by the ARB on June 9, 2010. 35 Approved by the Khronos Board of Promoters on July 23, 2010. 36 37Version 38 39 Version 5, May 7, 2013 40 41Number 42 43 ARB Extension #103 44 45Dependencies 46 47 OpenGL 3.2, or an earlier OpenGL version supporting the GL_ARB_sync 48 extension, is required. 49 50 An OpenCL implementation supporting sharing event objects 51 with OpenGL is required. 52 53Overview 54 55 This extension allows creating OpenGL sync objects linked to OpenCL 56 event objects, potentially improving efficiency of sharing images 57 and buffers between the two APIs. The companion cl_khr_gl_event 58 OpenCL extension provides the complementary functionality of 59 creating an OpenCL event object from an OpenGL fence sync object. 60 That extension is located in the OpenCL API Registry. 61 62IP Status 63 64 No known IP claims. 65 66New Procedures and Functions 67 68 sync CreateSyncFromCLeventARB(cl_context context, cl_event event, 69 bitfield flags) 70 71New Tokens 72 73 Returned in <values> for GetSynciv <pname> OBJECT_TYPE: 74 75 SYNC_CL_EVENT_ARB 0x8240 76 77 Returned in <values> for GetSynciv <pname> SYNC_CONDITION: 78 79 SYNC_CL_EVENT_COMPLETE_ARB 0x8241 80 81 82Additions to Chapter 5 of the OpenGL 3.1 Specification (Special Functions) 83 84 Add following the description of fence sync objects in section 5.2 85 (e.g. following the paragraph beginning "If FenceSync fails to 86 create a sync object..."): 87 88 "Sync Objects Linked to OpenCL Events 89 ------------------------------------ 90 91 A sync object may also be created which reflects the status of an 92 OpenCL event object. This provides another method of coordinating 93 sharing of buffers and images between OpenGL and OpenCL (see Chapter 94 9 of the OpenCL 1.0 Specification). Waiting on such a sync object is 95 equivalent to waiting for completion of the linked CL event object. 96 97 The command 98 99 sync CreateSyncFromCLeventARB(cl_context context, cl_event event, 100 bitfield flags) 101 102 creates a linked sync object. <context> and <event> must be handles 103 to a valid OpenCL context and a valid event in that context, 104 respectively. <context> must support sharing with GL, and must have 105 been created with respect to the current GL context, or to a share 106 group including the current GL context. 107 108 <flags> must be 0[fn1]. 109 [fn1: <flags> is a placeholder for anticipated future extensions 110 of sync object capabilities.] 111 112 The status of such a sync object depends on <event>. When the status 113 of <event> is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of 114 the linked sync object will be UNSIGNALED. When the status of 115 <event> changes to CL_COMPLETE, the status of the linked sync object 116 will become SIGNALED. 117 118 The initial property values for a sync object created by 119 CreateSyncFromCLeventARB are shown in table 5.clprops. Note that 120 <context> and <event> are not queriable properties of a sync object. 121 122 Property Name Property Value 123 ------------- -------------- 124 OBJECT_TYPE SYNC_CL_EVENT_ARB 125 SYNC_CONDITION SYNC_CL_EVENT_COMPLETE_ARB 126 SYNC_STATUS Depends on status of <event> 127 SYNC_FLAGS <flags> 128 ---------------------------------------------- 129 Table 5.clprops: Initial properties of a sync 130 object created with CreateSyncFromCLeventARB. 131 132 Creating a linked sync object places a reference on the linked 133 OpenCL event object. When the sync object is deleted, the reference 134 will be removed from the event object. 135 136 If CreateSyncFromCLeventARB fails to create a sync object, zero will 137 be returned and a GL error will be generated as described. An 138 INVALID_VALUE error is generated if <context> is not a valid OpenCL 139 context created with respect to the current GL context or the share 140 group containing the current GL context, if <event> is not a valid 141 OpenCL event handle in <context>, or if <flags> is not zero. An 142 INVALID_OPERATION error is generated if <event> is a valid OpenCL 143 event handle but was not returned by a call to 144 clEnqueueReleaseGLObjects. 145 146 However, implementations are not required to validate <context> or 147 <event>, and passing an invalid <context> or <event> handle may 148 result in undefined behavior up to and including program 149 termination." 150 151 Replace the first paragraph describing DeleteSync with: 152 153 "A sync object can be deleted by passing its name to the command 154 155 void DeleteSync(sync sync) 156 157 If the fence command or OpenCL event object corresponding to the 158 specified sync object has completed, or if no ClientWaitSync or 159 WaitSync commands are blocking on <sync>, the object is deleted 160 immediately. Otherwise, <sync> is flagged for deletion and will be 161 deleted when it is no longer associated with any fence command or 162 non-completed OpenCL event object, and is no longer blocking any 163 ClientWaitSync or WaitSync command. In either case, after returning 164 from DeleteSync the <sync> name is invalid and can no longer be used 165 to refer to the sync object." 166 167 Replace the first paragraph of section 5.2.2 "Signaling" with 168 169 "A sync object can be in the signaled state only once the 170 corresponding fence command or OpenCL event object has completed and 171 signaled the sync object." 172 173 Replace the list of sync object state in the last paragraph of 174 section 5.2 with: 175 176 "State must be maintained to indicate which sync object names are 177 currently in use. The state require for each sync object in use is 178 an integer for the specific type, an integer for the condition, an 179 integer for the flags, and a bit indicating whether the object is 180 signaled or unsignaled. Additionally, sync objects linked to OpenCL 181 events require implementation-specific, non-queriable internal state 182 identifying the OpenCL context and event. The initial values of sync 183 object state are defined as specified by FenceSync and 184 CreateSyncFromCLeventARB." 185 186Additions to Chapter 6 of the OpenGL 3.1 Specification (State and State Requests) 187 188 Replace the third paragraph of section 6.1.7 "Sync Object Queries" 189 with: 190 191 "If <pname> is OBJECT_TYPE, a single value representing the specific 192 type of the sync object is placed in <values>. The only types 193 supported are SYNC_FENCE and SYNC_CL_EVENT_ARB." 194 195Additions to Appendix D (Shared Objects and Multiple Contexts) 196 197 Replace section D.2.1 "Sync Object Deletion Behavior" with: 198 199 "Deleting sync objects is similar to other shared object types in 200 that the name of the deleted object immediately becomes invalid but 201 the underlying object will not be deleted until it is no longer in 202 use. Unlike other shared object types, a sync object is determined 203 to be in use if there is a corresponding fence command or linked 204 OpenCL event which has not yet completed (signaling the sync 205 object), or if there are any GL clients and/or servers blocked on 206 the sync object as a result of ClientWaitSync or WaitSync commands. 207 Once any corresponding fence commands or linked OpenCL events have 208 completed, a sync object has been signaled, and all clients and/or 209 servers blocked on that sync object have been unblocked, the object 210 may then be deleted." 211 212Additions to the AGL/EGL/GLX/WGL Specifications: 213 214 None 215 216GLX Protocol 217 218 <TBD> 219 220Errors 221 222 INVALID_VALUE is generated if the <context> parameter of 223 CreateSyncFromCLeventARB is not a valid OpenCL context created with 224 respect to the current GL context or the share group containing the 225 current GL context. 226 227 INVALID_VALUE is generated if <event> is not a valid OpenCL event 228 handle in <context>. 229 230 INVALID_VALUE is generated if <flags> is not zero. 231 232 INVALID_OPERATION is generated if <event> is a valid OpenCL event 233 handle in <context>, but was not generated by a call to 234 clEnqueueReleaseGLObjects. 235 236New State 237 238 Change the "Type" field for OBJECT_TYPE in table 6.X "Sync Objects" 239 from "Z_1" to "Z_2". Change the "Initial Value" fields for 240 OBJECT_TYPE and SYNC_STATUS to "(see sec. 5.2)". 241 242New Implementation Dependent State 243 244 None 245 246Sample Code 247 248 None 249 250Issues 251 252 1) What should the command to create a sync object linked to an 253 OpenCL event look like? 254 255 DISCUSSION: In earlier versions of the ARB_sync extension, a 256 generic constructor taking an attribute list was proposed. This 257 could be used to pass the necessary CL event-specific parameters 258 (CL context and event handle), or a CL event-specific command 259 taking explicit parameters could be used. 260 261 The explicit parameter approach is more typesafe and requires 262 marginally less coding to use, but introduces header file 263 dependency concerns (see issue 2 below). The generic approach 264 eliminates header file concerns and provides the groundwork for 265 new types of GL sync objects in the future. 266 267 RESOLVED: use explicit parameters. 268 269 2) How will the OpenCL header dependencies interact with 270 specifying the API for this extension? 271 272 DISCUSSION: GL extensions are specified in the Khronos-supplied 273 "glext.h" and "gl3ext.h" headers. Normally these headers are 274 self-contained, requiring only that <GL/gl.h> or <GL3/gl3.h> be 275 #included first to define necessary GL types. However, 276 specifying an event interface using the CL cl_context and 277 cl_event data types introduces a dependency on cl.h. Even worse, 278 there may be a dependency loop between CL and GL headers in 279 order to define both the cl_khr_gl_event and the GL_ARB_cl_event 280 extensions. 281 282 RESOLVED: glext.h and gl3.h will use the same incomplete struct 283 pointer types as cl.h does, based on these definitions from the 284 official Khronos headers: 285 286 typedef struct _cl_context *cl_context; 287 typedef struct _cl_event *cl_event; 288 289 If this turns out to be a problem on implementations that use 290 other declarations of these types we will reconsider but there's 291 no obvious reason this won't work. 292 293 3) Should all possible statuses of the CL event be reflected through 294 to the state of the sync object? 295 296 DISCUSSION: CL event objects have four execution statuses: 297 CL_QUEUED, CL_SUBMITTED, CL_RUNNING, and CL_COMPLETE. GL sync 298 objects have only two statuses: UNSIGNALED and SIGNALED. The 299 cl_khr_gl_event extension maps UNSIGNALED into CL_SUBMITTED, and 300 SIGNALED into CL_COMPLETE. 301 302 RESOLVED: Invert the cl_khr_gl_event mapping. CL_QUEUED, 303 CL_SUBMITTED, and CL_RUNNING all map into UNSIGNALED. 304 CL_COMPLETE maps into SIGNALED. 305 306 4) What is the sync type of a sync object linked to a CL event? 307 308 DISCUSSION: The GL sync interface anticipates the creation of 309 many types of sync objects although the only currently defined 310 type is the fence sync. From a functional perspective, a sync 311 created from a CL event is equivalent to a fence sync: it starts 312 in the UNSIGNALED state and can only transition once, to the 313 SIGNALED state. But it may be useful to distinguish between the 314 two types of syncs in the query API. 315 316 RESOLVED: The OBJECT_TYPE of a GL sync object created from a CL 317 event is SYNC_CL_EVENT_ARB. 318 319 5) Are there any restrictions on the use of a sync object linked to 320 a CL event object? 321 322 RESOLVED: No restrictions. The implementation may make different 323 choices depending on the sync object type, however. For example, 324 WaitSync might be able to wait in the GPU for a fence sync 325 object and be forced to wait in the CPU for a sync object linked 326 to a CL event, which may affect performance. But in terms of the 327 public API, there are no restrictions compared to how a fence 328 sync object may be used. 329 330 6) How are sync object lifetimes defined? 331 332 RESOLVED: A sync object linked to a CL event object places a 333 single reference on the event. Deleting the sync object removes 334 that reference. 335 336 DeleteSync has a dependency on the completion of the linked 337 event object, and will not delete the sync object while the 338 event object has not yet completed. This is equivalent to 339 behavior of deleting a fence sync object, where deletion of the 340 object will be deferred until the underlying fence command has 341 completed. 342 343 7) Should all OpenCL events be supported? 344 345 RESOLVED: No. Only events returned by clEnqueueReleaseGLObjects, 346 since that's the only known use case for this extension and 347 since this mirrors a recent restriction in the GL sync -> CL 348 event OpenCL extension which only allows events generated from 349 syncs to be used with clEnqueueAcquireGLObjects. 350 351Revision History 352 353 Version 5, 2013/05/07 (Jon Leech) - some resolved issues were 354 mistakenly still labelled as proposed. Fix labelling. 355 356 Version 4, 2010/07/24 (Jon Leech) - resolve issue 2. 357 358 Version 3, 2010/07/17 (Jon Leech) - fix misordering of command 359 parameters in New Procedures section. 360 361 Version 2, 2010/03/17 (Jon Leech) - restrict the extension to only 362 support OpenCL events generated by clEnqueueReleaseGLObjects. 363 Cleanup Errors section. 364 365 Version 1, 2009/09/15 (Jon Leech) - initial version. 366