Name Strings

cl_ext_image_requirements_info

Contact

Please see the Issues list in the Khronos OpenCL-Docs repository:
https://github.com/KhronosGroup/OpenCL-Docs

Contributors

Kevin Petit, Arm Ltd.
Jeremy Kemp, Imagination Technologies
Alastair Murray, Codeplay Software Ltd.
Balaji Calidas, Qualcomm

Notice

Copyright 2008-2023 The Khronos Group Inc.

This Specification is protected by copyright laws and contains material proprietary to Khronos. Except as described by these terms, it or any components may not be reproduced, republished, distributed, transmitted, displayed, broadcast or otherwise exploited in any manner without the express prior written permission of Khronos.

This Specification has been created under the Khronos Intellectual Property Rights Policy, which is Attachment A of the Khronos Group Membership Agreement available at www.khronos.org/files/member_agreement.pdf and defines the terms 'Scope', 'Compliant Portion', and 'Necessary Patent Claims'.

Khronos grants a conditional copyright license to use and reproduce the unmodified Specification for any purpose, without fee or royalty, EXCEPT no licenses to any patent, trademark or other intellectual property rights are granted under these terms. Parties desiring to implement the Specification and make use of Khronos trademarks in relation to that implementation, and receive reciprocal patent license protection under the Khronos Intellectual Property Rights Policy must become Adopters and confirm the implementation as conformant under the process defined by Khronos for this Specification; see https://www.khronos.org/adopters.

Khronos makes no, and expressly disclaims any, representations or warranties, express or implied, regarding this Specification, including, without limitation: merchantability, fitness for a particular purpose, non-infringement of any intellectual property, correctness, accuracy, completeness, timeliness, and reliability. Under no circumstances will Khronos, or any of its Promoters, Contributors or Members, or their respective partners, officers, directors, employees, agents or representatives be liable for any damages, whether direct, indirect, special or consequential damages for lost revenues, lost profits, or otherwise, arising from or in connection with these materials.

Where this Specification identifies specific sections of external references, only those specifically identified sections define normative functionality. The Khronos Intellectual Property Rights Policy excludes external references to materials and associated enabling technology not created by Khronos from the Scope of this specification, and any licenses that may be required to implement such referenced materials and associated technologies must be obtained separately and may involve royalty payments.

Khronos® and Vulkan® are registered trademarks, and SPIR™, SPIR-V™, and SYCL™ are trademarks of The Khronos Group Inc. OpenCL™ is a trademark of Apple Inc. used under license by Khronos. OpenGL® is a registered trademark and the OpenGL ES™ and OpenGL SC™ logos are trademarks of Hewlett Packard Enterprise used under license by Khronos. All other product names, trademarks, and/or company names are used solely for identification and belong to their respective owners.

Status

Shipping.

Version

Built On: 2023-06-14
Version: 0.5.0

Dependencies

This extension is written against the OpenCL Specification Version 3.0.9.

This extension requires OpenCL 3.0.

Overview

This extension enables applications to query requirements for an image without having to create the image.

New API Functions

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

New API Types

typedef cl_uint cl_image_requirements_info_ext;

New API Enums

Accepted value for the param_name parameter to clGetImageRequirementsInfoEXT:

CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT    0x1290
CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT 0x1292
CL_IMAGE_REQUIREMENTS_SIZE_EXT                   0x12B2
CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT              0x12B3
CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT             0x12B4
CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT              0x12B5
CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT         0x12B6

Modifications to the OpenCL API Specification

(Modify Section 5.3.1, Creating Image Objects)

The following text:

For a 2D image created from a buffer, the pitch specified (or computed if pitch specified is 0) must be a multiple of the maximum of the CL_DEVICE_IMAGE_PITCH_ALIGNMENT value for all devices in the context associated with the buffer specified by mem_object that support images.

is replaced with:

For a 2D image created from a buffer, the pitch specified (or computed if pitch specified is 0) must be a multiple of the CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT value returned for parameters compatible with those used to create the image.

The following text:

If the buffer object specified by mem_object was created with CL_MEM_USE_HOST_PTR, the host_ptr specified to clCreateBuffer or clCreateBufferWithProperties must be aligned to the maximum of the CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT value for all devices in the context associated with the buffer specified by mem_object that support images.

is replaced with:

If the buffer object specified by mem_object was created with CL_MEM_USE_HOST_PTR, the host_ptr specified to clCreateBuffer or clCreateBufferWithProperties must be aligned to the CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT value for the returned for parameters compatible with those used to create the image.

(Modify Section 5.3, Image Objects)
(Add a new subsection 5.3.X, Querying image requirements)
To get information specific to the requirements of an image before creating it call the function 
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);

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

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

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

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

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

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.
TODO: should we require image_width to be 0?

CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT

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.
TODO: should we require image_height to be 0?

CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT

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.
TODO: should we require image_depth to be 0?

CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT

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.
TODO: should we require image_array_size to be 0?

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.

Interactions with Other Extensions

This extension interacts with cl_khr_image2d_from_buffer.

When cl_khr_image2d_from_buffer is supported:

  • The value returned by CL_DEVICE_IMAGE_PITCH_ALIGNMENT after converting in bytes for the supported format with the biggest element size (channel data type size * number of channels) must be greater than or equal to the value returned by CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT for any supported format.

  • The value returned by CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT after converting in bytes for the supported format with the biggest element size (channel data type size * number of channels) must be greater than or equal to the value returned by CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT for any supported format.

Conformance tests

  1. Basic checks for CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT and CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT

    • For all image formats and types

      • Check that the CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT and CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT queries can be performed successfully and that the values returned are a power of two.

  2. Check consistency with cl_khr_image2d_from_buffer

    • When cl_khr_image2d_from_buffer is supported, check that the value returned by CL_DEVICE_IMAGE_PITCH_ALIGNMENT after converting in bytes for the supported format with the biggest element size (channel data type size * number of channels) is greater than or equal to the value returned by CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT for all supported formats.

    • When cl_khr_image2d_from_buffer is supported, check that the value returned by CL_DEVICE_IMAGE_BASE_ADDRESS_ALIGNMENT after converting in bytes for the supported format with the biggest element size (channel data type size * number of channels) is greater than or equal to the value returned by CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT for all supported formats.

  3. Negative tests for CL_IMAGE_REQUIREMENTS_SIZE_EXT

    • Check that attempting to perform the CL_IMAGE_REQUIREMENTS_SIZE_EXT query without specifying the image_format results in CL_INVALID_VALUE being returned.

    • Check that attempting to perform the CL_IMAGE_REQUIREMENTS_SIZE_EXT query without specifying the image_desc results in CL_INVALID_VALUE being returned.

  4. Consistency checks for CL_IMAGE_REQUIREMENTS_SIZE_EXT

    • When creating 2D images from a buffer is supported, for all formats and a selection of image dimensions

      • Check that the CL_IMAGE_REQUIREMENTS_SIZE_EXT query can be performed successfully.

      • Create a buffer with the size returned and check that an image can successfully be created from the buffer.

      • Check that the value returned for CL_MEM_SIZE for the image is the same as the value returned for CL_IMAGE_REQUIREMENTS_SIZE_EXT.

  5. Consistency checks for CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT

    • For all image formats, image types and a selection of values for other members in image_desc (that MUST include 0)

      • Check that the CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT query can be performed successfully

      • Check that the value is smaller than or equal to the value returned for CL_DEVICE_IMAGE_MAX_BUFFER_SIZE for images of CL_MEM_OBJECT_IMAGE1D_BUFFER type or smaller than or equal to the value returned for CL_DEVICE_IMAGE3D_MAX_WIDTH for images of CL_MEM_OBJECT_IMAGE3D type or smaller than or equal to the value returned for CL_DEVICE_IMAGE2D_MAX_WIDTH for all other image types.

  6. Negative tests for CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT

    • Attempt to perform the CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT query on all image types for which it is not valid

    • Check that CL_INVALID_IMAGE_DESCRIPTOR is returned in all cases.

  7. Consistency checks for CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT

    • For all image formats, valid image types and a selection of values for other members in image_desc (that MUST include 0)

      • Check that the CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT query can be performed successfully

      • Check that the value is smaller than or equal to the value returned for CL_DEVICE_IMAGE2D_MAX_HEIGHT for 2D or 2D array images or CL_DEVICE_IMAGE3D_MAX_HEIGHT for 3D images.

  8. Negative testing for CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT

    • Attempt to perform the CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT query on all image types for which it is not valid

    • Check that CL_INVALID_IMAGE_DESCRIPTOR is returned in all cases.

  9. Consistency checks for CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT

    • For all image formats, valid image types and a selection of values for other members in image_desc (that MUST include 0)

      • Check that the CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT query can be performed successfully

      • Check that the value is smaller than or equal to the value returned for CL_DEVICE_IMAGE3D_MAX_DEPTH.

  10. Negative testing for CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT

    • Attempt to perform the CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT query on all image types for which it is not valid

    • Check that CL_INVALID_IMAGE_DESCRIPTOR is returned in all cases.

  11. Consistency checks for CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT

    • For all image formats, valid image types and a selection of values for other members in image_desc (that MUST include 0)

      • Check that the CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT query can be performed successfully

      • Check that the value is smaller than or equal to the value returned for CL_DEVICE_IMAGE_MAX_ARRAY_SIZE.

  12. General negative testing for clGetImageRequirementsInfoEXT

    • Write tests for all possible testable generic error codes.

Issues

None.

Version History

Version Date Author Changes

0.5.0

2022-01-18

Kevin Petit

Initial EXT revision