D.1.1 EGL images

The EGL_KHR_image_base EGL extension provides the basic mechanism for sharing EGL images.

The EGL_KHR_image_base EGL extension defines two entry points for creating and destroying EGL images:

EGLImageKHR eglCreateImageKHR(
                        EGLDisplay dpy,
                        EGLContext ctx,
                        EGLenum target,
                        EGLClientBuffer buffer,
                        const EGLint *attrib_list)
 
EGLBoolean eglDestroyImageKHR(
                        EGLDisplay dpy,
                        EGLImageKHR image)

The eglCreateImageKHR call returns an opaque handle that the Khronos APIs use for referencing EGL images. Nothing in the extension specification precludes an EGL image from being the storage for the content that is to be shared, but the actual role of EGL images in the DDK is to serve only as references to memory allocations made by a low level API. There are two low level APIs for memory allocation that the DDK actively supports:

The availability of the memory allocation methods depends on the platform, the EGL_KHR_image_base extension relies on additional extensions to define platform-specific values for the target and buffer parameters on the eglCreateImageKHR call.

The EGL_KHR_image_base extension only states that the target parameter is a unique number identifying the content source. The buffer parameter is an extension-specific handle that is cast to EGLClientBuffer, a void pointer on the official Khronos EGL headers.

Preserving EGL images for portability

Applications needing the EGL image contents to be preserved must set EGL_IMAGE_PRESERVED_KHR to EGL_TRUE rather than relying on the default value.

The only attribute defined by the EGL_KHR_image_base extension is EGL_IMAGE_PRESERVED_KHR, which is a boolean defining whether the image contents are undefined after the eglCreateImageKHR call returns. The default value for EGL_IMAGE_PRESERVED_KHR is EGL_FALSE, meaning that undefined contents are acceptable unless the application explicitly sets the value to EGL_TRUE.

Failing to set EGL_IMAGE_PRESERVED_KHR to EGL_TRUE can lead to applications relying on undefined behavior, that is subject to change between Mali™ DDK releases.  

OpenCL support for EGL images

There are two OpenCL mechanisms for supporting data sharing with other APIs from the Khronos ecosystem.

The two OpenCL mechanisms for supporting data sharing with other APIs from the Khronos ecosystem are:

cl_khr_egl_image
Mali DDK supports this API for importing EGL images.
cl_khr_gl_sharing
Mali DDK does not support this API for importing OpenGL or OpenGL ES objects such as vertex buffers, index buffers, textures, or render buffer objects. This API does not add any substantial benefit to the EGL image mechanism and is tightly coupled to the OpenGL semantics.

Because customers can implement all their relevant use cases with the cl_khr_egl_image path, cl_khr_gl_sharing extension is unsupported on the Mali DDK since the r6p0-01rel0 release.

The supported cl_khr_egl_image OpenCL extension defines an entry point for creating cl_mem objects out of EGL images:

cl_mem clCreateFromEGLImageKHR (
    cl_context context,
    CLeglDisplayKHR display,
    CLeglImageKHR image,
    cl_mem_flags flags,
    const cl_egl_image_properties_khr * properties,
    cl_int * errcode_ret)

The image parameter is an EGL image handle that is returned by eglCreateImageKHR. The flags are a subset of the flags that are accepted by clCreateBuffer, where the accepted flags are only CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY and CL_MEM_READ_WRITE. The list of properties is present on the extension for allowing future additions, but no such properties currently exist.

Synchronization when using the cl_khr_egl_image extension

Applications are responsible for flushing the work when one Khronos API consumes the output from another.

For example, if an application produces an OpenGL ES render that OpenCL has to consume, then it is the responsibility of the application to issue a glFinish before the OpenCL access happens.

The same application responsibility is also required when OpenCL outputs data that OpenGL is going to use. For example, an OpenGL ES rendering application that consumes some OpenCL output needs to ensure that it calls clFinish or clWaitForEvents to guarantee that the data is available for consumption before using OpenGL ES to access it.

In addition to flushing, there are GPU architectures that require the EGL images that are consumed or produced by OpenCL to be transferred between different device memories. That kind of architecture is common on discrete graphics cards for desktop PCs. The Mali implementations, on the other hand, uses the same main memory as the application processor, rather than a dedicated memory. Therefore there is no requirement to transfer data between the application processor and any dedicated GPU memory.

The OpenCL API delegates to the applications to choose the times at which the transfers happen by explicitly signaling when the accesses start and end.

The start and end of the EGL image accesses by OpenCL applications must be signaled by enqueuing clEnqueueAcquireEGLObjectsKHR and clEnqueueReleaseEGLObjectsKHR commands on an OpenCL command queue before and after a kernel accesses the EGL image data. An OpenCL kernel that uses an EGL image that it has not previously acquired gets an error at kernel enqueue time, for ensuring portability and compliance with the OpenCL standard, even on Mali implementations.

EGL images limitation

It is not possible to query an EGL image for its format or dimensions through the EGL API. The Mali™ OpenCL driver, on the other hand, allows querying for the format and dimensions of an OpenCL image created out of an EGL image.

However, the reported OpenCL format is only meaningful for formats that have a mapping between the EGL image source format and a format defined in the OpenCL specification.

A second limitation is that OpenCL images created out of EGL images cannot be memory mapped by means of clEnqueueImageMap and clEnqueueUnmapMemObject. The Khronos specifications do not explicitly say whether the memory mapping must be supported for this kind of OpenCL images. The DDK does not support memory mapping.

Non-ConfidentialPDF file icon PDF version101574_0301_00_en
Copyright © 2019 Arm Limited or its affiliates. All rights reserved.