C Specification

To create an EGLImage target of type cl_mem from the EGLImage source provided as image, call the function

// Provided by cl_khr_egl_image
cl_mem clCreateFromEGLImageKHR(
    cl_context context,
    CLeglDisplayKHR egldisplay,
    CLeglImageKHR eglimage,
    cl_mem_flags flags,
    const cl_egl_image_properties_khr* properties,
    cl_int* errcode_ret);
clCreateFromEGLImageKHR is provided by the cl_khr_egl_image extension.

Parameters

  • display should be of type EGLDisplay, cast into the type CLeglDisplayKHR.

  • image should be of type EGLImageKHR, cast into the type CLeglImageKHR. Assuming no errors are generated in this function, the resulting image object will be an EGLImage target of the specified EGLImage image. The resulting cl_mem is an image object which may be used normally by all OpenCL operations. This maps to an image2d_t type in OpenCL kernel code.

  • flags is a bit-field that is used to specify usage information about the memory object being created. Refer to the Memory Flags table for a description of flags. Accepted values in flags are described below.

  • properties specifies a list of property names and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. No properties are currently supported with this version of the extension. properties can be NULL.

  • errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

Description

Accepted for flags are CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY, CL_MEM_IMMUTABLE_EXT, and CL_MEM_READ_WRITE. If OpenCL 1.2 is supported, flags also accepts CL_MEM_HOST_WRITE_ONLY, CL_MEM_HOST_READ_ONLY, and CL_MEM_HOST_NO_ACCESS.

cl_khr_egl_image only requires support for CL_MEM_READ_ONLY, and for CL_MEM_HOST_NO_ACCESS if OpenCL 1.2 or later is supported. For OpenCL 1.1, a CL_INVALID_OPERATION will be returned for images which do not support host mapping.

If the value passed in flags is not supported by the OpenCL implementation, it will return CL_INVALID_VALUE. The accepted flags may be dependent upon the texture format used.

If CL_MEM_IMMUTABLE_EXT is set in flags, the image created is an immutable memory object that cannot be modified by the implementation after creation.

clCreateFromEGLImageKHR returns a valid non-zero OpenCL image object and errcode_ret is set to CL_SUCCESS if the image object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

  • CL_INVALID_CONTEXT if context is not a valid OpenCL context.

  • CL_INVALID_VALUE if properties contains invalid values, if display is not a valid display object or if flags are not in the set defined above.

  • CL_INVALID_EGL_OBJECT_KHR if image is not a valid EGLImage object.

  • CL_IMAGE_FORMAT_NOT_SUPPORTED if the OpenCL implementation is not able to create a cl_mem compatible with the provided CLeglImageKHR for an implementation-dependent reason (this could be caused by, but not limited to, reasons such as unsupported texture formats, etc).

  • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

  • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

  • CL_INVALID_OPERATION if there are no devices in context that support images (i.e. CL_DEVICE_IMAGE_SUPPORT specified in table 4.3 is CL_FALSE) or if the flags passed are not supported for that image type.

  • CL_INVALID_VALUE if CL_MEM_IMMUTABLE_EXT is set in flags and CL_MEM_READ_WRITE, CL_MEM_WRITE_ONLY, or CL_MEM_HOST_WRITE_ONLY is set in flags.

See Also

CLeglDisplayKHR, CLeglImageKHR, cl_context, cl_egl_image_properties_khr, cl_int, cl_khr_egl_image, cl_mem_flags

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0