OpenCL™规范 5.3.2. 查询支持的图像格式列表

5.3.2. Querying List of Supported Image Formats

5.3.2. 查询支持的图像格式列表

To get the list of image formats supported by an OpenCL implementation for a specified context, image type, and allocation information, call the function

要获取OpenCL实现支持的指定上下文、图像类型和分配信息的图像格式列表，请调用函数

// Provided by CL_VERSION_1_0
cl_int clGetSupportedImageFormats(
    cl_context context,
    cl_mem_flags flags,
    cl_mem_object_type image_type,
    cl_uint num_entries,
    cl_image_format* image_formats,
    cl_uint* num_image_formats);

• context is a valid OpenCL context on which the image object(s) will be created.

• context是将在其上创建图像对象的有效OpenCL上下文。

• flags is a bit-field that is used to specify usage information about the image formats being queried and is described in the Memory Flags table. flags may be CL_MEM_READ_WRITE to query image formats that may be read from and written to by different kernel instances when correctly ordered by event dependencies, or CL_MEM_READ_ONLY to query image formats that may be read from by a kernel, or CL_MEM_WRITE_ONLY to query image formats that may be written to by a kernel, or CL_MEM_KERNEL_READ_AND_WRITE to query image formats that may be both read from and written to by the same kernel instance. Please see Image Format Mapping for clarification.

• ​flags是一个位字段，用于指定有关正在查询的图像格式的使用信息，并在Memory flags表中进行了描述。标志可以是CL_MEM_READ_WRITE，用于查询在按事件依赖性正确排序时可由不同内核实例读取和写入的图像格式，或者CL_MEM_READ_ONLY，用于查询可由内核读取的图像格式；或者CL_MEM_WRITE_ONLLY，用于查询可以由内核写入的图像形式；或者CL_MEM_KERNEL_READ_AND_WRITE用于查询可同时由同一内核实例读取或写入的图像类型。请参阅图像格式映射以获得澄清。

• image_type describes the image type and must be either CL_MEM_OBJECT_IMAGE1D, CL_MEM_OBJECT_IMAGE1D_BUFFER, CL_MEM_OBJECT_IMAGE2D, CL_MEM_OBJECT_IMAGE3D, CL_MEM_OBJECT_IMAGE1D_ARRAY, or CL_MEM_OBJECT_IMAGE2D_ARRAY.

• ​image_type描述图像类型，并且必须是CL_MEM_OBJECT_IMAGE1D、CL_MEM_OBJECT_IMAGE1D_BUFFER、CL_MEM_OBJECT-IMAGE2D、CL-MEM_OBJECT_IMAGE3D、CL_MEM_OBJECT _IMAGE1D_ARRAY或CL_MEM-OBJECT_IMAGE2D_ARRAY。

• num_entries specifies the number of entries that can be returned in the memory location given by image_formats.

• num_entries指定在image_formats给定的内存位置中可以返回的条目数。

• image_formats is a pointer to a memory location where the list of supported image formats are returned. Each entry describes a cl_image_format structure supported by the OpenCL implementation. If image_formats is NULL, it is ignored.

• ​image_formats是一个指向内存位置的指针，在该位置将返回支持的图像格式列表。每个条目描述OpenCL实现所支持的cl_image_format结构。如果image_formats为NULL，则会忽略它。

• num_image_formats is the actual number of supported image formats for a specific context and values specified by flags. If num_image_formats is NULL, it is ignored.

• num_image_formats是特定上下文和标志指定的值支持的图像格式的实际数量。如果num_image_formats为NULL，则会忽略它。

clGetSupportedImageFormats returns a union of image formats supported by all devices in the context.

clGetSupportedImageFormats返回上下文中所有设备支持的图像格式的并集。

clGetSupportedImageFormats returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

如果函数执行成功，clGetSupportedImageFormats将返回CL_SUCCESS。否则，它将返回以下错误之一：

• CL_INVALID_CONTEXT if context is not a valid context.

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

• CL_INVALID_VALUE if flags or image_type are not valid, or if num_entries is 0 and image_formats is not NULL.

• 如果标志或image_type无效，或者num_entries为0且image_formats不为NULL，则CL_INVALID_VALUE。

• 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_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实现所需的资源失败。

If CL_DEVICE_IMAGE_SUPPORT specified in the Device Queries table is CL_TRUE, the values assigned to CL_DEVICE_MAX_READ_IMAGE_ARGS, CL_DEVICE_MAX_WRITE_IMAGE_ARGS CL_DEVICE_IMAGE2D_MAX_WIDTH, CL_DEVICE_IMAGE2D_MAX_HEIGHT CL_DEVICE_IMAGE3D_MAX_WIDTH, CL_DEVICE_IMAGE3D_MAX_HEIGHT CL_DEVICE_IMAGE3D_MAX_DEPTH, and CL_DEVICE_MAX_SAMPLERS by the implementation must be greater than or equal to the minimum values specified in the Device Queries table.

​如果在“设备查询”表中指定的CL_DEVICE_IMAGE_SUPPORT为CL_TRUE，则由实现分配给CL_DEVICE_MAX_READ_IMAGE_ARGS、CL_DEVICE_MAX_WRITE_IMAGE_ARGS、CL_DEVICE_IMAGE2D_MAX_WIDTH、CL_DEVICE_IMAGE2D_MAX_HEIGHT、CL_DEVICE_IMAGE3D_MAX_WIDTH、CL_DEVICE_IMAGE3D_MAX_DEPTH和CL_DEVICS_MAX_SAMPLERS的值必须大于或等于在“设备询问”表中所指定的最小值。