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.

See Also

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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.