diff options
Diffstat (limited to 'glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_cl_event2.txt')
| -rw-r--r-- | glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_cl_event2.txt | 364 |
1 files changed, 364 insertions, 0 deletions
diff --git a/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_cl_event2.txt b/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_cl_event2.txt new file mode 100644 index 0000000..953487c --- /dev/null +++ b/glew/auto/EGL-Registry/extensions/KHR/EGL_KHR_cl_event2.txt @@ -0,0 +1,364 @@ +Name + + KHR_cl_event2 + +Name Strings + + EGL_KHR_cl_event2 + +Contributors + + Jon Leech, Khronos + Alon Or-bach, Samsung Electronics + Tom Cooksey, ARM + +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 + + Complete. + Approved by the EGL Working Group on December 4, 2013. + +Version + + Version 5, December 4, 2013 + +Number + + EGL Extension #65 + +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. + + Khronos recommends obsoleting and replacing implementations of + EGL_KHR_cl_event with this extension as soon as possible. + +Overview + + This extension allows creating an EGL 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 sync object. + + This extension is functionally identical to EGL_KHR_cl_event, but is + intended to replace that extension. It exists only to address an + implementation issue on 64-bit platforms where passing OpenCL event + handles in an EGLint attribute list value is impossible, because the + implementations use a 32-bit type for EGLint. + + This extension also incorporates some required functionality from the + EGL_KHR_fence_sync extension, similarly modified for 64-bit platforms. + +New Types + + /* + * EGLAttribKHR is a integer type used to pass arrays of attribute + * name/value pairs which may include pointer and handle attribute + * values. + */ + #include <khrplatform.h> + typedef intptr_t EGLAttribKHR; + + Event handles of type cl_event, defined in the OpenCL header files, may + be included in the attribute list passed to eglCreateSync64KHR. + +New Procedures and Functions + + EGLSyncKHR eglCreateSync64KHR( + EGLDisplay dpy, + EGLenum type, + const EGLAttribKHR *attrib_list); + +New Tokens + + Accepted as attribute names in the <attrib_list> argument + of eglCreateSync64KHR: + + 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) + + Modify the language in section 3.8.1 (Sync Objects) starting at the + sixth paragraph, describing commands to create sync objects: + + "The commands + + EGLSyncKHR eglCreateSync64KHR( + EGLDisplay dpy, + EGLenum type, + const EGLAttribKHR *attrib_list); + + and + + EGLSyncKHR eglCreateSyncKHR( + EGLDisplay dpy, + EGLenum type, + const EGLint *attrib_list); + + create a sync object ... + + ... When a fence sync object is created, eglCreateSyncKHR and + eglCreateSync64KHR also insert a fence command into... " + + Add following the eigth paragraph (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. + + CL event sync objects may only be created using the command + eglCreateSync64KHR, because they require an attribute which may not be + representable in the attrib_list argument of eglCreateSyncKHR." + + 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." + + The command eglCreateSync64KHR must be used to create a CL event sync + object[fn1]. + + [fn1] If the implementation also supports the older EGL_KHR_cl_event + extension, then eglCreateSyncKHR may also be used to create a CL + event sync object. However, this use is not recommended because it + is not portable to platforms where OpenCL event handles are larger + than 32 bits." + + Modify the ninth and tenth paragraphs, starting "When the condition": + + "When the condition of the sync object is satisfied, the sync is + signaled by the associated client API context, causing any + eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock. + + The only condition supported for fence sync objects is + EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, which is satisfied by completion + of the fence command corresponding to the sync object, and all preceding + commands in the associated client API context's command stream. The sync + object will not be signaled until all effects from these commands on the + client API's internal and framebuffer state are fully realized. No other + state is affected by execution of the fence command. + + Each client API which supports fence commands indicates this support + in the form of a client API extension. If the GL_OES_EGL_sync + extension is supported by OpenGL ES (either version 1.x or 2.0), a + fence sync object may be created when the currently bound API is + OpenGL ES. If the VG_KHR_EGL_sync extension is supported by OpenVG, + a fence sync object may be created when the currently bound API is + OpenVG. + + The only condition supported for CL event sync objects is + EGL_SYNC_CL_EVENT_COMPLETE_KHR, which is satisfied when the status of + the OpenCL event associated with the sync object changes to CL_COMPLETE." + + Add to the "Errors" section for eglCreateSyncKHR and eglCreateSync64KHR: + + "* If <type> is EGL_SYNC_CL_EVENT_KHR then + + ** If eglCreateSyncKHR was called, then EGL_NO_SYNC_KHR is returned and + an EGL_BAD_ATTRIBUTE error is generated. + + ** If eglCreateSync64KHR was called and EGL_CL_EVENT_HANDLE_KHR is not + specified in <attrib_list>, or its attribute value 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 + + Note that some issues from the EGL_KHR_cl_event and EGL_KHR_fence_sync + extensions also apply to this extension, which incorporates + functionality from both of those extensions while making it usable on a + 64-bit architecture. Issues specific to this extension are below. + + 1) Why does this extension exist? + + The existence of this extension is an unfortunate necessity. Khronos did + not define EGLint as a 64-bit type in the version of <khrplatform.h> we + provided, assuming that vendors on those platforms would do so. By the + time we discovered that not all vendors had done this, it was too late + to fix, because ABI considerations made it impossible for those vendors + to change to a 64-bit EGLint type. Our only option was to define new + extensions and commands using a new attribute type, EGLAttribKHR, which + is explicitly large enough to hold a pointer or handle. + + 2) What is the relationship of this extension to EGL_KHR_cl_event? + + RESOLVED: The only functional difference is that the new + eglCreateSync64KHR command must be used to create CL event sync objects. + This is necessary because some 64-bit platforms define EGLint as a + 32-bit type, making it impossible to pass an arbitrary OpenCL event + handle in the EGLint *attrib_list passed to eglCreateSyncKHR. + + 3) How are pointer- and handle-sized attributes represented? + + RESOLVED: Using the new type EGLAttribKHR, which is explicitly defined + as an integer type large enough to hold a pointer. + + EGLAttribKHR is defined as an alias of the ISO C intptr_t type, rather + than using one of the explicitly-sized types from khrplatform.h. + Requiring this means that khrplatform.h must make sure to include the + appropriate header file (probably <stdint.h>) and that a C compiler + supporting intptr_t must be used. In the past we were concerned about + older C/C++ compilers, but this seems an acceptable choice in 2013. + + We could choose to use intptr_t as the base type of attribute lists, + instead of the EGLAttribKHR alias. As Ian Romanick has pointed out + passionately in ARB discussions, modern C compilers are required to + support a well-defined set of scalar types. There is no requirement to + use API-specific scalar types when explicitly defining a C API. + + However, there is some value in semantically tagging parameters with EGL + types. Also, using 'intptr_t *attrib_list' would be cosmetically + objectionable due to mixing EGL* and C native scalar types in EGL APIs. + + We probably want to wait until there's an EGL API compatibility break - + a hypothetical "EGL 2.0" - before moving to native ISO C types in our + interfaces. + + 4) Why is the new fence sync creation function defined here, instead of + in a separate EGL_KHR_fence_sync2 extension? + + RESOLVED: eglCreateSync64KHR is defined here because this is the only + functionality requiring it, and we expect this extension to be a stopgap + for 64-bit platforms until the time that EGL 1.5 is defined. The EGL 1.5 + core will presumably include only the EGLAttribKHR-based version of this + command. + + If there are any new extensions using handle or pointer attributes in + the meantime, they should copy the EGLAttribKHR and eglCreateSync64KHR + language here as required. There is no harm in defining the same type or + command in multiple extensions, so long as the definitions are + compatible. + + 5) Why is the new command called eglCreateSync64KHR? + + UNRESOLVED: For consistency with OpenGL, which has '64'-suffixed + commands for representing 64-bit integers and arbitrary offsets into GPU + memory. If we ever support EGL on 128-bit platforms this would be a + silly naming convention, but that time is probably many decades away and + by then EGL 1.5 should be defined and widely supported. The name + eglCreateSync2KHR was originally suggested. + + 6) Why is there no command for querying EGLAttribKHR attributes from + sync objects? + + RESOLVED: Because the only sync attribute which requires the extra bits + in an EGLAttribKHR type is EGL_CL_EVENT_HANDLE_KHR, which is not + queryable. Sync attributes which are queryable will all fit into the + EGLint returned by eglGetSyncAttribKHR. + + NOTE: It's unfortunate that this name is used, since it uses the + "AttribKHR" name for command returning EGLints. In EGL 1.5 we should use + a different name for the query. + + 7) Does this extension replace EGL_KHR_fence_sync and EGL_KHR_cl_event? + + RESOLVED: It does not replace EGL_KHR_fence_sync, but extends it to + support creation of a new type of sync object, the CL event sync object. + + RESOLVED: It is intended to replace EGL_KHR_cl_event; this extension + must be used for OpenCL interop on 64-bit platforms, and we hope all + vendors will implement it even on 32-bit platforms, for maximum code + portability. + +Revision History + + Version 5, 20130/12/04 (Jon Leech) - minor cleanup for public release. + + Version 4, 20130/10/16 (Jon Leech) - add Dependencies and Overview text + noting that this extension obsoletes and should replace + EGL_KHR_cl_event. + + Version 3, 20130/10/15 (Jon Leech) - change type of EGLAttribKHR from + uintptr to intptr (Bug 11027). + + Version 2, 20130/10/12 (Jon Leech) - merge EGL_KHR_fence_sync2 with this + extension, change the naming scheme, define EGLAttribKHR as uintptr_t, + and add a new issues list. + + Version 1, 2010/10/02 (Tom Cooksey) - initial version based on + EGL_KHR_cl_event and adding 64-bit EGLAttrKHR variants. |