C Specification

To get information specific to the requirements of an image before creating it call the function

// Provided by cl_ext_image_requirements_info
cl_int clGetImageRequirementsInfoEXT(
    cl_context context,
    const cl_mem_properties* properties,
    cl_mem_flags flags,
    const cl_image_format* image_format,
    const cl_image_desc* image_desc,
    cl_image_requirements_info_ext param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);
clGetImageRequirementsInfoEXT is provided by the cl_ext_image_requirements_info extension.

Parameters

  • context is the OpenCL context in which the query will be performed.

  • properties is an optional list of properties for the image object and their corresponding values. The list is terminated with the special property 0. If no properties are required, properties may be NULL.

  • flags is a bit-field that is used to specify allocation and usage information about the image format being queried and is described in the Memory Flags table. flags may be CL_MEM_READ_WRITE to specialize the query for images that may be read from and written to by different kernel instances when correctly ordered by event dependencies, or CL_MEM_READ_ONLY to specialize the query for images that may be read from by a kernel, or CL_MEM_WRITE_ONLY to specialiaze the query for images that may be written to by a kernel, or CL_MEM_KERNEL_READ_AND_WRITE to specialize the query for images that may be both read from and written to by the same kernel instance. When flags is 0 the value returned for the query must be correct for all possible values of flags.

  • image_format is a pointer to a structure describing the format of the image for which requirements are being queried. Refer to the Image Format Descriptor section for a detailed description.

  • image_desc is a pointer to a structure that describes type and dimensions of the image for which requirements are being queried. Refer to the Image Descriptor section for a detailed description of the image descriptor.

  • param_name specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetImageRequirementsInfoEXT is described in the Image Requirements Queries table.

  • param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

  • param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be ≥ size of return type as described in the Image Requirements Queries table.

  • param_value_size_ret returns the actual size in bytes of data being queried by param_name. If param_value_size_ret is NULL, it is ignored.

Description

Table 1. List of supported param_names by clGetImageRequirementsInfoEXT
Image Format Info Return type Info. returned in param_value

CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT

provided by the cl_ext_image_requirements_info extension.

size_t

Returns the minimum alignment in bytes required for the data store backing an image created using the parameters passed to clGetImageRequirementsInfoEXT. image_format or image_desc are allowed to be NULL. When either or both is NULL the implementation will return an alignment that would be sufficient for all possible values of the missing argument.
The value returned is a power of two.

CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT

provided by the cl_ext_image_requirements_info extension.

size_t

Returns the row pitch alignment required in bytes for images created from a buffer with the parameters passed to clGetImageRequirementsInfoEXT. The value returned is a power of two. image_format or image_desc are allowed to be NULL. When either or both is NULL the value returned is the minimum row pitch alignment that works for all possible values of the missing argument(s).

CL_IMAGE_REQUIREMENTS_SIZE_EXT

provided by the cl_ext_image_requirements_info extension.

size_t

Returns the minimal size in bytes that a buffer would need to be to back an image created using the parameters passed to clGetImageRequirementsInfoEXT.
Both image_format and image_desc must be non-NULL, otherwise CL_INVALID_VALUE is returned.

CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT

provided by the cl_ext_image_requirements_info extension.

cl_uint

Returns the max width supported for creating images with the parameters passed to clGetImageRequirementsInfoEXT. image_format or image_desc are allowed to be NULL. When either or both is NULL the implementation will return a max width that would be supported for all possible values of the missing argument(s).
When image_desc is not NULL, the value of its image_width member is ignored and has no effect on the value returned. The value of all other members, except mem_object may be 0 to require that the value returned be supported for all possible values of the members that are set to 0.

CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT

provided by the cl_ext_image_requirements_info extension.

cl_uint

Returns the max height supported for creating images with the parameters passed to clGetImageRequirementsInfoEXT. image_format or image_desc are allowed to be NULL. When either or both is NULL the implementation will return a max height that would be supported for all possible values of the missing argument(s).
When image_desc is not NULL, the value of its image_height member is ignored and has no effect on the value returned. The value of all other members, except mem_object may be 0 to require that the value returned be supported for all possible values of the members that are set to 0.
If image_desc is not NULL, then image_type must be either 0, CL_MEM_OBJECT_IMAGE2D, CL_MEM_OBJECT_IMAGE2D_ARRAY, or CL_MEM_OBJECT_IMAGE3D, otherwise CL_INVALID_IMAGE_DESCRIPTOR is returned.

CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT

provided by the cl_ext_image_requirements_info extension.

cl_uint

Returns the max depth supported for creating images with the parameters passed to clGetImageRequirementsInfoEXT. image_format or image_desc are allowed to be NULL. When either or both is NULL the implementation will return a max depth that would be supported for all possible values of the missing argument(s).
When image_desc is not NULL, the value of its image_depth member is ignored and has no effect on the value returned. The value of all other members, except mem_object may be 0 to require that the value returned be supported for all possible values of the members that are set to 0.
If image_desc is not NULL, then image_type must be either 0 or CL_MEM_OBJECT_IMAGE3D, otherwise CL_INVALID_IMAGE_DESCRIPTOR is returned.

CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT

provided by the cl_ext_image_requirements_info extension.

cl_uint

Returns the max array size supported for creating images with the parameters passed to clGetImageRequirementsInfoEXT. image_format or image_desc are allowed to be NULL. When either or both is NULL the implementation will return a max array size that would be supported for all possible values of the missing argument(s).
When image_desc is not NULL, the value of its image_array_size member is ignored and has no effect on the value returned. The value of all other members, except mem_object may be 0 to require that the value returned be supported for all possible values of the members that are set to 0.
If image_desc is not NULL, then image_type must be either 0, CL_MEM_OBJECT_IMAGE1D_ARRAY or CL_MEM_OBJECT_IMAGE2D_ARRAY, otherwise CL_INVALID_IMAGE_DESCRIPTOR is returned.

CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT

provided by the cl_ext_image_from_buffer extension.

size_t

Returns the slice pitch alignment required in bytes for images created from a buffer with the parameters passed to clGetImageRequirementsInfoEXT. The value returned is a power of two. image_format and image_desc are allowed to be NULL. When either or both is NULL the value returned is the minimum slice pitch alignment that is supported for all possible values of the missing argument(s).

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

  • CL_INVALID_CONTEXT if context if not a valid context.

  • CL_INVALID_PROPERTY if a property name in properties is not a supported property name, if the value specified for a supported property name is not valid, or if the same property name is specified more than once.

  • CL_INVALID_VALUE if values specified in flags are not valid.

  • CL_INVALID_IMAGE_FORMAT_DESCRIPTOR if values specified in image_format are not valid.

  • CL_INVALID_IMAGE_DESCRIPTOR if values specified in image_desc are not valid.

  • CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in the Image Requirements Queries table and param_value 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.

See Also

cl_context, cl_ext_image_requirements_info, cl_image_desc, cl_image_format, cl_image_requirements_info_ext, cl_mem_flags, cl_mem_properties

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

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0