xref: /third_party/EGL/extensions/KHR/EGL_KHR_cl_event.txt

Name

    KHR_cl_event

Name Strings

    EGL_KHR_cl_event

Contributors

    Jon Leech, Khronos
    Alon Or-bach, Samsung Electronics

Contact

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

IP Status

    No known claims.

Notice

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

Status

    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

    Version 10, December 4, 2013

Number

    EGL Extension #60

Dependencies

    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.

Overview

    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.

New Types

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

New Procedures and Functions

    None

New Tokens

    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

Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)

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

   "A <CL event sync object> reflects the status of a corresponding
    OpenCL event object to which the sync object is linked. This
    provides another method of coordinating sharing of images between
    EGL and OpenCL (see Chapter 9 of the OpenCL 1.0 Specification and
    the cl_khr_egl_sharing extension). Waiting on such a sync object is
    equivalent to waiting for completion of the linked CL event object."

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

   "If <type> is EGL_SYNC_CL_EVENT_KHR, a CL event sync object is
    created. In this case <attrib_list> must contain the attribute
    EGL_CL_EVENT_HANDLE_KHR, set to a valid OpenCL event. Note that
    EGL_CL_EVENT_HANDLE_KHR is not a queriable property of a sync
    object. Attributes of the CL event sync objects are set as follows:

        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 <type> is EGL_SYNC_CL_EVENT_KHR then

    ** 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:

   "Attribute              Description                Supported Sync Objects
    -----------------      -----------------------    ----------------------
    EGL_SYNC_CONDITION_KHR Signaling condition        EGL_SYNC_FENCE_KHR or
                                                      EGL_SYNC_CL_EVENT_KHR

    Table 3.cc  Attributes Accepted by eglGetSyncAttribKHR Command"


    Replace the second paragraph describing eglDestroySync with:

   "If any eglClientWaitSyncKHR commands are blocking on <sync> when
    eglDestroySyncKHR is called, <sync> is flagged for deletion and will
    be deleted when the associated fence command or CL event object has
    completed, and <sync> is no longer blocking any eglClientWaitSyncKHR
    command. Otherwise, the sync object is destroyed immediately."

Sample Code

    None

Conformance Tests

    None yet

Issues

    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.

Revision History

    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.