OpenCL™规范 5.3.13. 从EGL图像创建OpenCL图像对象

5.3.13. Creating OpenCL Image Objects From EGL Images

5.3.13. 从EGL图像创建OpenCL图像对象

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

要从作为图像提供的EGLImage源创建cl_mem类型的EGLImage目标，请调用函数

// 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. clCreateFromEGLImageKHR由cl_khr_egl_image扩展提供。

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

• display应为EGLDisplay类型，转换为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.

• image应为EGLImageKHR类型，并转换为CLeglImageKHR类型。假设在该函数中没有生成错误，则生成的图像对象将是指定EGLImage图像的EGLIimage目标。所得到的cl_mem是可以由所有OpenCL操作正常使用的图像对象。这映射到OpenCL内核代码中的image2d_t类型。

• 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.

• ​flags是一个位字段，用于指定有关正在创建的内存对象的使用信息。有关标志的说明，请参阅内存标志表。标志中的可接受值如下所述。

• 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.

• properties指定属性名称及其相应值的列表。每个属性名称后面紧跟着相应的所需值。列表以0终止。此版本的扩展当前不支持任何属性。properties可以为NULL。

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

• errcode_ret将返回相应的错误代码。如果errcode_ret为NULL，则不会返回任何错误代码。

Accepted for flags are CL_MEM_READ_ONLY, CL_MEM_WRITE_ONLY 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.

​接受的flags为CL_MEM_READ_ONLY、CL_MEM_WRITE_ONLY和CL_MEM_READ_WRITE。如果支持OpenCL 1.2，则标志也接受CL_MEM_HOST_WRITE_ONLY、CL_MEM_HOST_READ_ONLY和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.

cl_khr_egl_image只需要支持CL_MEM_READ_ONLY，如果支持OpenCL 1.2或更高版本，则需要支持CL_MEM_HOST_NO_ACCESS。对于OpenCL 1.1，对于不支持主机映射的映像，将返回CL_INVALID_OPERATION。

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.

​如果OpenCL实现不支持在flags中传递的值，它将返回CL_INVALID_VALUE。所接受的flags可以取决于所使用的纹理格式。

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:

​clCreateFromEGLImageKHR返回有效的非零OpenCL映像对象，如果映像对象创建成功，则errcode_ret设置为CL_SUCCESS。否则，它将返回一个NULL值，并在errcode_ret中返回以下错误值之一：

• CL_INVALID_CONTEXT if context is not a valid OpenCL context.

• CL_INVALID_CONTEXT（如果context不是有效的OpenCL上下文）。

• 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_VALUE如果properties包含无效值，如果display不是有效的显示对象，或者如果flags不在上面定义的集合中。

• CL_INVALID_EGL_OBJECT_KHR if image is not a valid EGLImage object.

• CL_INVALID_EGL_OBJECT_KHR，如果image不是有效的EGLImage对象。

• 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_IMAGE_FORMAT_NOT_SUPPORTED，如果OpenCL实现由于与实现相关的原因（这可能是但不限于不支持的纹理格式等原因）而无法创建与所提供的CLeglImageKHR兼容的cl_mem。

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

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

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

• CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。

• 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.

• 如果context中没有支持图像的设备（即表4.3中指定的CL_DEVICE_IMAGE_SUPPORT为CL_FALSE），或者该图像类型不支持传递的标志，则为CL_INVALID_OPERATION。