clGetSupportedImageFormats

Get the list of image formats supported by an OpenCL implementation.

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

A valid OpenCL context on which the image object(s) will be created.

flags

A bit-field that is used to specify allocation and usage information about the image memory object being created and is described in the List of supported cl_mem_flags values for clCreateBuffer

image_type

Describes the image type and must be either CL_MEM_OBJECT_IMAGE2D or CL_MEM_OBJECT_IMAGE3D.

num_entries

Specifies the number of entries that can be returned in the memory location given by image_formats.

image_formats

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

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.

Notes

clGetSupportedImageFormats can be used to get the list of image formats supported by an OpenCL implementation when the following information about an image memory object is specified:

  • Context
  • Image type - 2D or 3D image
  • Image object allocation information

The minimum list of supported image formats is given by the table below:

image_num_channels

image_channel_order

image_channel_data_type

4

CL_RGBA

CL_UNORM_INT8
CL_UNORM_INT16

CL_SIGNED_INT8
CL_SIGNED_INT16
CL_SIGNED_INT32

CL_UNSIGNED_INT8
CL_UNSIGNED_INT16
CL_UNSIGNED_INT32

CL_HALF_FLOAT
CL_FLOAT

4

CL_BGRA

CL_UNORM_INT8

If CL_DEVICE_IMAGE_SUPPORT specified in the table of OpenCL Device Queries for clGetDeviceInfo is CL_TRUE, the values assigned to the following constants by the implementation must be greater than or equal to the minimum values specified in the table of OpenCL Device Queries for clGetDeviceInfo: 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, CL_DEVICE_MAX_SAMPLERS.

Errors

Returns CL_SUCCESS if the function is executed 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 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.

Specification

OpenCL Specification

Also see

cl_image_format

Copyright © 2007-2010 The Khronos Group Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.