KHR_cl_event

EGL_KHR_cl_event

Jon Leech, Khronos
Alon Or-bach, Samsung Electronics

Jon Leech (jon 'at' alumni.caltech.edu)

No known claims.

Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at
    http://www.khronos.org/registry/speccopyright.html

This extension is obsolete and has been replaced by EGL_KHR_cl_event2.
Khronos recommends implementers who support this extension also
implement cl_event2, and begin transitioning developers to using that
extension. See issue 17 for the reason.

Complete. Approved by the EGL Working Group on 2013/05/15.
Approved by the Khronos Board of Promoters on 2013/07/19.

Version 10, December 4, 2013

EGL Extension #60

EGL 1.4 and the EGL_KHR_fence_sync extension are required.

This extension is written against the language added to EGL 1.2 by
the EGL_KHR_fence_sync extension.

An OpenCL implementation supporting sharing OpenCL event objects
with EGL is required.

This extension allows creating an EGL fence sync object linked to an
OpenCL event object, potentially improving efficiency of sharing
images between the two APIs. The companion cl_khr_egl_event
extension provides the complementary functionality of creating an
OpenCL event object from an EGL fence sync object.

None. However, event handles of type cl_event, defined in the OpenCL
header files, may be included in the attribute list passed to
eglCreateSyncKHR.

None

Accepted as attribute names in the <attrib_list> argument
of eglCreateSyncKHR:

    EGL_CL_EVENT_HANDLE_KHR         0x309C

Returned in <values> for eglGetSyncAttribKHR <attribute>
EGL_SYNC_TYPE_KHR:

    EGL_SYNC_CL_EVENT_KHR           0x30FE

Returned in <values> for eglGetSyncAttribKHR <attribute>
EGL_SYNC_CONDITION_KHR:

    EGL_SYNC_CL_EVENT_COMPLETE_KHR  0x30FF

Add following the description of fence sync objects in section 3.8.1
(e.g. following the paragraph beginning "<Fence sync objects> are
created..."

Add following the description of fence sync objects (prior to the
"Errors" section for eglCreateSyncKHR):

    Attribute Name          Initial Attribute Value(s)
    -------------           --------------------------
    EGL_SYNC_TYPE_KHR       EGL_SYNC_CL_EVENT_KHR
    EGL_SYNC_STATUS_KHR     Depends on status of <event>
    EGL_SYNC_CONDITION_KHR  EGL_SYNC_CL_EVENT_COMPLETE_KHR

The status of such a sync object depends on <event>. When the status
of <event> is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of
the linked sync object will be EGL_UNSIGNALED_KHR. When the status
of <event> changes to CL_COMPLETE, the status of the linked sync
object will become EGL_SIGNALED_KHR.

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.

However, implementations are not required to validate the OpenCL
event, and passing an invalid event handle in <attrib_list> may
result in undefined behavior up to and including program
termination."

Add to the "Errors" section for eglCreateSyncKHR:

** If EGL_CL_EVENT_HANDLE_KHR is not specified in <attrib_list>
   or is not a valid OpenCL event handle returned by a call to
   clEnqueueReleaseGLObjects or clEnqueueReleaseEGLObjects, then
   EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is
   generated.

Replace the EGL_SYNC_CONDITION_KHR row of table 3.cc with:

Table 3.cc  Attributes Accepted by eglGetSyncAttribKHR Command"


Replace the second paragraph describing eglDestroySync with:

None

None yet

1) Does this extension need to introduce eglWaitSync
   functionality?

RESOLVED: The EGL_KHR_wait_sync extension introduces this, to allow
server-side synchronization, without blocking the client from issuing
commands. Whilst this is not a required dependency, GPU-to-GPU
synchronization is the most likely use of this extension.

2) What should the command to create a sync object linked to an
   OpenCL event look like?

RESOLVED: We reuse the general attribute list mechanism rather than
having a constructor specific to CL events. This was intended in the
sync object design from the start.

3) How will the OpenCL header dependencies interact with
   specifying the API for this extension?

DISCUSSION: To use this extension, OpenCL event handles of type cl_event
are specified in the attribute lists passed to eglCreateSyncKHR. Because
no formal parameters are of type cl_event, the EGL headers do not need
to define this type. Applications must #include the appropriate OpenCL
header files as well as <EGL/eglext.h> when using this extension.

This issue resolution is consistent with the equivalent issue for
GL_ARB_cl_event.

4) 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_egl_event mapping. CL_QUEUED,
CL_SUBMITTED, and CL_RUNNING all map into UNSIGNALED.
CL_COMPLETE maps into SIGNALED.

This issue resolution is consistent with the equivalent issue for
GL_ARB_cl_event.

5) Are there any restrictions on the use of a sync object linked to a CL
   event object?

RESOLVED: No restrictions.

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.

eglDestroySync has a dependency on the completion of the linked event
object, and will not delete the sync objectwhile 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.

This issue resolution is consistent with the equivalent issue for
GL_ARB_cl_event.

7) Should all OpenCL events be supported?

RESOLVED: No. Only events returned by clEnqueueReleaseGLObjects, or
clEnqueueReleaseEGLObjects since those are the only known use cases for
this extension.

8) Why has this extension been obsoleted and replaced by
EGL_KHR_cl_event2?

RESOLVED: Starting with the December 4, 2013 release of EGL 1.4, EGLint
is defined to be the same size as the native platform "int" type. Handle
and pointer attribute values *cannot* be represented in attribute lists
on platforms where sizeof(handle/pointer) > sizeof(int). Existing
extensions which assume this functionality are being replaced with new
extensions specifying new entry points to work around this issue. See
the latest EGL 1.4 Specification for more details.

Version 10, 2013/12/04 (Jon Leech) - add issue 8 explaining that OpenCL
event handles cannot be safely passed in attribute lists on 64-bit
platforms, and suggest using EGL_KHR_cl_event2 instead.

Version 9, 2013/08/12 (Jon Leech) - remove unused cl_event type from the
extension and from <EGL/eglext.h> (Bug 10661).

Version 8, 2013/07/19 (Jon Leech) - assign extension number and
missing enum value, and clean up a few typos for publication.

Version 7, 2013/07/08 (Jon Leech) - assign enums (Bug 10490).

Version 6, 2013/06/11 (Alon Or-bach) - typo correction

Version 5, 2013/05/30 (Alon Or-bach) - wording cleanup

Version 4, 2013/05/15 (Alon Or-bach) - updated issue resolutions as agreed,
consistent with GL_ARB_cl_event, including using typedef for cl_event

Version 3, 2013/04/25 (Alon Or-bach) - remove use of CL context,
accept events from clEnqueueAcquireEGLObjects and minor cleanup

Version 2, 2012/06/26 (Jon Leech) - update link to complementary CL
extension.

Version 1, 2010/05/18 (Jon Leech) - initial version based on
equivalent GL_ARB_cl_event extension.