Name ARB_cl_event Name Strings GL_ARB_cl_event Contributors Jon Leech, Khronos Contact Jon Leech (jon 'at' alumni.caltech.edu) Notice Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at http://www.khronos.org/registry/speccopyright.html Status Complete. Approved by the ARB on June 9, 2010. Approved by the Khronos Board of Promoters on July 23, 2010. Version Version 5, May 7, 2013 Number ARB Extension #103 Dependencies OpenGL 3.2, or an earlier OpenGL version supporting the GL_ARB_sync extension, is required. An OpenCL implementation supporting sharing event objects with OpenGL is required. Overview This extension allows creating OpenGL sync objects linked to OpenCL event objects, potentially improving efficiency of sharing images and buffers between the two APIs. The companion cl_khr_gl_event OpenCL extension provides the complementary functionality of creating an OpenCL event object from an OpenGL fence sync object. That extension is located in the OpenCL API Registry. IP Status No known IP claims. New Procedures and Functions sync CreateSyncFromCLeventARB(cl_context context, cl_event event, bitfield flags) New Tokens Returned in for GetSynciv OBJECT_TYPE: SYNC_CL_EVENT_ARB 0x8240 Returned in for GetSynciv SYNC_CONDITION: SYNC_CL_EVENT_COMPLETE_ARB 0x8241 Additions to Chapter 5 of the OpenGL 3.1 Specification (Special Functions) Add following the description of fence sync objects in section 5.2 (e.g. following the paragraph beginning "If FenceSync fails to create a sync object..."): "Sync Objects Linked to OpenCL Events ------------------------------------ A sync object may also be created which reflects the status of an OpenCL event object. This provides another method of coordinating sharing of buffers and images between OpenGL and OpenCL (see Chapter 9 of the OpenCL 1.0 Specification). Waiting on such a sync object is equivalent to waiting for completion of the linked CL event object. The command sync CreateSyncFromCLeventARB(cl_context context, cl_event event, bitfield flags) creates a linked sync object. and must be handles to a valid OpenCL context and a valid event in that context, respectively. must support sharing with GL, and must have been created with respect to the current GL context, or to a share group including the current GL context. must be 0[fn1]. [fn1: is a placeholder for anticipated future extensions of sync object capabilities.] The status of such a sync object depends on . When the status of is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of the linked sync object will be UNSIGNALED. When the status of changes to CL_COMPLETE, the status of the linked sync object will become SIGNALED. The initial property values for a sync object created by CreateSyncFromCLeventARB are shown in table 5.clprops. Note that and are not queriable properties of a sync object. Property Name Property Value ------------- -------------- OBJECT_TYPE SYNC_CL_EVENT_ARB SYNC_CONDITION SYNC_CL_EVENT_COMPLETE_ARB SYNC_STATUS Depends on status of SYNC_FLAGS ---------------------------------------------- Table 5.clprops: Initial properties of a sync object created with CreateSyncFromCLeventARB. Creating a linked sync object places a reference on the linked OpenCL event object. When the sync object is deleted, the reference will be removed from the event object. If CreateSyncFromCLeventARB fails to create a sync object, zero will be returned and a GL error will be generated as described. An INVALID_VALUE error is generated if is not a valid OpenCL context created with respect to the current GL context or the share group containing the current GL context, if is not a valid OpenCL event handle in , or if is not zero. An INVALID_OPERATION error is generated if is a valid OpenCL event handle but was not returned by a call to clEnqueueReleaseGLObjects. However, implementations are not required to validate or , and passing an invalid or handle may result in undefined behavior up to and including program termination." Replace the first paragraph describing DeleteSync with: "A sync object can be deleted by passing its name to the command void DeleteSync(sync sync) If the fence command or OpenCL event object corresponding to the specified sync object has completed, or if no ClientWaitSync or WaitSync commands are blocking on , the object is deleted immediately. Otherwise, is flagged for deletion and will be deleted when it is no longer associated with any fence command or non-completed OpenCL event object, and is no longer blocking any ClientWaitSync or WaitSync command. In either case, after returning from DeleteSync the name is invalid and can no longer be used to refer to the sync object." Replace the first paragraph of section 5.2.2 "Signaling" with "A sync object can be in the signaled state only once the corresponding fence command or OpenCL event object has completed and signaled the sync object." Replace the list of sync object state in the last paragraph of section 5.2 with: "State must be maintained to indicate which sync object names are currently in use. The state require for each sync object in use is an integer for the specific type, an integer for the condition, an integer for the flags, and a bit indicating whether the object is signaled or unsignaled. Additionally, sync objects linked to OpenCL events require implementation-specific, non-queriable internal state identifying the OpenCL context and event. The initial values of sync object state are defined as specified by FenceSync and CreateSyncFromCLeventARB." Additions to Chapter 6 of the OpenGL 3.1 Specification (State and State Requests) Replace the third paragraph of section 6.1.7 "Sync Object Queries" with: "If is OBJECT_TYPE, a single value representing the specific type of the sync object is placed in . The only types supported are SYNC_FENCE and SYNC_CL_EVENT_ARB." Additions to Appendix D (Shared Objects and Multiple Contexts) Replace section D.2.1 "Sync Object Deletion Behavior" with: "Deleting sync objects is similar to other shared object types in that the name of the deleted object immediately becomes invalid but the underlying object will not be deleted until it is no longer in use. Unlike other shared object types, a sync object is determined to be in use if there is a corresponding fence command or linked OpenCL event which has not yet completed (signaling the sync object), or if there are any GL clients and/or servers blocked on the sync object as a result of ClientWaitSync or WaitSync commands. Once any corresponding fence commands or linked OpenCL events have completed, a sync object has been signaled, and all clients and/or servers blocked on that sync object have been unblocked, the object may then be deleted." Additions to the AGL/EGL/GLX/WGL Specifications: None GLX Protocol Errors INVALID_VALUE is generated if the parameter of CreateSyncFromCLeventARB is not a valid OpenCL context created with respect to the current GL context or the share group containing the current GL context. INVALID_VALUE is generated if is not a valid OpenCL event handle in . INVALID_VALUE is generated if is not zero. INVALID_OPERATION is generated if is a valid OpenCL event handle in , but was not generated by a call to clEnqueueReleaseGLObjects. New State Change the "Type" field for OBJECT_TYPE in table 6.X "Sync Objects" from "Z_1" to "Z_2". Change the "Initial Value" fields for OBJECT_TYPE and SYNC_STATUS to "(see sec. 5.2)". New Implementation Dependent State None Sample Code None Issues 1) What should the command to create a sync object linked to an OpenCL event look like? DISCUSSION: In earlier versions of the ARB_sync extension, a generic constructor taking an attribute list was proposed. This could be used to pass the necessary CL event-specific parameters (CL context and event handle), or a CL event-specific command taking explicit parameters could be used. The explicit parameter approach is more typesafe and requires marginally less coding to use, but introduces header file dependency concerns (see issue 2 below). The generic approach eliminates header file concerns and provides the groundwork for new types of GL sync objects in the future. RESOLVED: use explicit parameters. 2) How will the OpenCL header dependencies interact with specifying the API for this extension? DISCUSSION: GL extensions are specified in the Khronos-supplied "glext.h" and "gl3ext.h" headers. Normally these headers are self-contained, requiring only that or be #included first to define necessary GL types. However, specifying an event interface using the CL cl_context and cl_event data types introduces a dependency on cl.h. Even worse, there may be a dependency loop between CL and GL headers in order to define both the cl_khr_gl_event and the GL_ARB_cl_event extensions. RESOLVED: glext.h and gl3.h will use the same incomplete struct pointer types as cl.h does, based on these definitions from the official Khronos headers: typedef struct _cl_context *cl_context; typedef struct _cl_event *cl_event; If this turns out to be a problem on implementations that use other declarations of these types we will reconsider but there's no obvious reason this won't work. 3) Should all possible statuses of the CL event be reflected through to the state of the sync object? DISCUSSION: CL event objects have four execution statuses: CL_QUEUED, CL_SUBMITTED, CL_RUNNING, and CL_COMPLETE. GL sync objects have only two statuses: UNSIGNALED and SIGNALED. The cl_khr_gl_event extension maps UNSIGNALED into CL_SUBMITTED, and SIGNALED into CL_COMPLETE. RESOLVED: Invert the cl_khr_gl_event mapping. CL_QUEUED, CL_SUBMITTED, and CL_RUNNING all map into UNSIGNALED. CL_COMPLETE maps into SIGNALED. 4) What is the sync type of a sync object linked to a CL event? DISCUSSION: The GL sync interface anticipates the creation of many types of sync objects although the only currently defined type is the fence sync. From a functional perspective, a sync created from a CL event is equivalent to a fence sync: it starts in the UNSIGNALED state and can only transition once, to the SIGNALED state. But it may be useful to distinguish between the two types of syncs in the query API. RESOLVED: The OBJECT_TYPE of a GL sync object created from a CL event is SYNC_CL_EVENT_ARB. 5) Are there any restrictions on the use of a sync object linked to a CL event object? RESOLVED: No restrictions. The implementation may make different choices depending on the sync object type, however. For example, WaitSync might be able to wait in the GPU for a fence sync object and be forced to wait in the CPU for a sync object linked to a CL event, which may affect performance. But in terms of the public API, there are no restrictions compared to how a fence sync object may be used. 6) How are sync object lifetimes defined? RESOLVED: A sync object linked to a CL event object places a single reference on the event. Deleting the sync object removes that reference. DeleteSync has a dependency on the completion of the linked event object, and will not delete the sync object while the event object has not yet completed. This is equivalent to behavior of deleting a fence sync object, where deletion of the object will be deferred until the underlying fence command has completed. 7) Should all OpenCL events be supported? RESOLVED: No. Only events returned by clEnqueueReleaseGLObjects, since that's the only known use case for this extension and since this mirrors a recent restriction in the GL sync -> CL event OpenCL extension which only allows events generated from syncs to be used with clEnqueueAcquireGLObjects. Revision History Version 5, 2013/05/07 (Jon Leech) - some resolved issues were mistakenly still labelled as proposed. Fix labelling. Version 4, 2010/07/24 (Jon Leech) - resolve issue 2. Version 3, 2010/07/17 (Jon Leech) - fix misordering of command parameters in New Procedures section. Version 2, 2010/03/17 (Jon Leech) - restrict the extension to only support OpenCL events generated by clEnqueueReleaseGLObjects. Cleanup Errors section. Version 1, 2009/09/15 (Jon Leech) - initial version.