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