C Specification

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

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);

Parameters

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

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

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

• num_entries specifies the number of entries that can be returned in the memory location given by 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.

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

Description

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

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

• CL_​INVALID_​CONTEXT if context is not a valid context.

• CL_​INVALID_​VALUE if flags or image_type are not valid, or if num_entries is 0 and image_formats is not NULL.

• CL_​OUT_​OF_​RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

• CL_​OUT_​OF_​HOST_​MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

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.