From 8cb6cfd87eb95e4ac5f2b54dbfce3087deeb617f Mon Sep 17 00:00:00 2001 From: Kevin Petit Date: Wed, 15 Jan 2025 17:23:35 +0000 Subject: [PATCH 1/4] Integrate cl_ext_image_from_buffer into unified specification Also add version notes for all CL_IMAGE_REQUIREMENTS_* enums. Signed-off-by: Kevin Petit Change-Id: I7b7b093034121a9215786beff7318b18e7d0c24a --- api/cl_ext_image_from_buffer.asciidoc | 67 +++- api/footnotes.asciidoc | 2 +- api/opencl_runtime_layer.asciidoc | 107 ++++++- extensions/cl_ext_image_from_buffer.asciidoc | 302 ------------------- extensions/extensions.txt | 2 - 5 files changed, 162 insertions(+), 318 deletions(-) delete mode 100644 extensions/cl_ext_image_from_buffer.asciidoc diff --git a/api/cl_ext_image_from_buffer.asciidoc b/api/cl_ext_image_from_buffer.asciidoc index 6bd6fa9bd..a241bd1cf 100644 --- a/api/cl_ext_image_from_buffer.asciidoc +++ b/api/cl_ext_image_from_buffer.asciidoc @@ -1,4 +1,4 @@ -// Copyright 2018-2024 The Khronos Group Inc. +// Copyright 2018-2025 The Khronos Group Inc. // SPDX-License-Identifier: CC-BY-4.0 include::{generated}/meta/{refprefix}cl_ext_image_from_buffer.txt[] @@ -6,14 +6,73 @@ include::{generated}/meta/{refprefix}cl_ext_image_from_buffer.txt[] === Other Extension Metadata *Last Modified Date*:: - 2022-01-25 + 2025-01-15 *IP Status*:: No known IP claims. +*Contributors*:: + - Kevin Petit, Arm Ltd. + - Jeremy Kemp, Imagination Technologies + - Alastair Murray, Codeplay Software Ltd. + - Balaji Calidas, Qualcomm === Description -The latest published specification for this extension is available on -the https://registry.khronos.org/OpenCL/extensions/ext/cl_ext_image_from_buffer.html[OpenCL registry]. +This extension enables all types of images to be created from an existing buffer +object. + +=== New Enums + + * {cl_image_requirements_info_ext_TYPE} + ** {CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT} + +=== Conformance tests + +. Test access from kernel + - For all image types + - For a few/all image formats + - For several values of row/slice pitch + - With or without a host_ptr + - Create buffer and fill with data + - Optionally create a sub-buffer with a randomly selected offset? + - Create an image from the buffer + - Read the image from a kernel and compare with values read using the buffer and direct addressing. They must match. + +. TODO Test access via read/write/map commands? + +. TODO Test copy to/from buffer? + +. TODO Test fill? + +. TODO Test copy to/from another image? + +. Test clGetImageInfo + - For all image types (one format per element size) + - For a few different row/pitch sizes (image dimensions being equal or not) + - Create an image from a buffer + - Check that the returned values for {CL_IMAGE_ROW_PITCH} and {CL_IMAGE_SLICE_PITCH} are correct. + +. Test clGetMemObjectInfo + - For all image types (1 format only) + - Create an image from a buffer + - Check that {CL_MEM_ASSOCIATED_MEMOBJECT} correctly returns the buffer that was used. + +. Negative testing for {clCreateImage} (alignment) + - For a few/all image formats + - For all image types + - Query row pitch, slice pitch and base image address alignment for the format + - Create an image from a buffer with invalid row pitch (not a multiple of required alignment) and check that {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} is returned. + - Create an image from a buffer with invalid slice pitch (not a multiple of required alignment) and check that {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} is returned. + - Create an image from a buffer with invalid base address alignment (not a multiple of required alignment) and check that {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} is returned. + +. Negative testing for {clCreateImage} (buffer size) + - For a few image formats (at least smallest and biggest element types) + - For all image types + - Create a buffer too small + - Check that image creation from that buffer is rejected with {CL_INVALID_IMAGE_SIZE} + +=== Issues + +None. === Version History diff --git a/api/footnotes.asciidoc b/api/footnotes.asciidoc index 4f7de3ec1..01114e8d6 100644 --- a/api/footnotes.asciidoc +++ b/api/footnotes.asciidoc @@ -53,7 +53,7 @@ Note that reading and writing 2D image arrays from a kernel with `image_array_si ] :fn-image-from-buffer: pass:n[ \ -To create a 2D image from a buffer object that share the data store between the image and buffer object. \ +To create an image from a buffer object that share the data store between the image and buffer object. \ ] :fn-image-from-image: pass:n[ \ diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 22978b83e..eb28e687d 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -1933,8 +1933,16 @@ include::{generated}/api/version-notes/clCreateImageWithProperties.asciidoc[] the <> table. * _image_format_ is a pointer to a structure that describes format properties of the image to be allocated. - A 1D image buffer or 2D image can be created from a buffer by specifying a - buffer object in the __image_desc__->__mem_object__. + A 1D image buffer can be created from a buffer by specifying a buffer object + in __image_desc__->__mem_object__. + If the {cl_khr_image2d_from_buffer_EXT} extension is supported, a 2D image + can be created from a buffer by specifying a buffer object in + __image_desc__->__mem_object__. +ifdef::cl_ext_image_from_buffer[] + If the {cl_ext_image_from_buffer_EXT} extension is supported, an image of + any type can be created from a buffer by specifying a buffer object in + __image_desc__->__mem_object__. +endif::cl_ext_image_from_buffer[] A 2D image can be created from another 2D image object by specifying an image object in the __image_desc__->__mem_object__. Refer to the <> section @@ -2071,9 +2079,23 @@ returned in _errcode_ret_: * {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 or if _image_format_ is `NULL`. +ifndef::cl_ext_image_from_buffer[] * {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if a 2D image is created from a buffer and the row pitch and base address alignment does not follow the rules described for creating a 2D image from a buffer. +endif::cl_ext_image_from_buffer[] +ifdef::cl_ext_image_from_buffer[] + * {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if an image is created from a + buffer and the row pitch, or slice pitch, if the + {cl_ext_image_from_buffer_EXT} extension is supported, or base address + alignment do not follow the rules described for creating an image from a + buffer. + * {CL_INVALID_IMAGE_SIZE} if the {cl_ext_image_from_buffer_EXT} extension is + supported and an image is created from a buffer and the buffer passed in + _image_desc->_mem_object_ is too small to be used as a data store for the + image, e.g. if its size is smaller than the value returned for + {CL_IMAGE_REQUIREMENTS_SIZE_EXT} for the parameters used to create the image. +endif::cl_ext_image_from_buffer[] * {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if a 2D image is created from a 2D image object and the rules described above are not followed. * {CL_INVALID_IMAGE_DESCRIPTOR} if values specified in _image_desc_ are not @@ -2660,9 +2682,9 @@ ifndef::cl_ext_image_requirements_info[] for all devices in the context that support images. endif::cl_ext_image_requirements_info[] ifdef::cl_ext_image_requirements_info[] - For a 2D image created from a buffer, the image row pitch must also + For an image created from a buffer, the image row pitch must also - Be a multiple of the {CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT} value - returned for parameters compatible with those used to create the image, if + for the _image_format_, _image_type_ and _flags_ used to create the image, if the {cl_ext_image_requirements_info_EXT} extension is supported, or - Be a multiple of the maximum of the {CL_DEVICE_IMAGE_PITCH_ALIGNMENT} value for all devices in the context that support images, otherwise. @@ -2685,6 +2707,12 @@ endif::cl_khr_external_memory[] _image_height_ for a 2D image array or a 3D image, must be {geq} the image row pitch for a 1D image array, and must be a multiple of the image row pitch. +ifdef::cl_ext_image_from_buffer[] + For an image created from a buffer, the image slice pitch must be a multiple + of the {CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT} value for the + _image_format_, _image_type_ and _flags_ used to create the image, if the + {cl_ext_image_from_buffer_EXT} extension is supported. +endif::cl_ext_image_from_buffer[] * _num_mip_levels_ must be `0`, indicating that the image has a single ifndef::cl_khr_mipmap_image[] mipmap level. @@ -2699,7 +2727,12 @@ endif::cl_khr_mipmap_image[] * _mem_object_ may refer to a valid buffer or image memory object. `mem_object` can be a buffer memory object if `image_type` is {CL_MEM_OBJECT_IMAGE1D_BUFFER} or - {CL_MEM_OBJECT_IMAGE2D} footnote:[{fn-image-from-buffer}]. + {CL_MEM_OBJECT_IMAGE2D} +ifdef::cl_ext_image_from_buffer[] + , or any other `image_type` if the {cl_ext_image_from_buffer_EXT} extension + is supported. +endif::cl_ext_image_from_buffer[] + footnote:[{fn-image-from-buffer}] `mem_object` can be an image object if `image_type` is {CL_MEM_OBJECT_IMAGE2D} footnote:[{fn-image-from-image}]. Otherwise it must be `NULL`. @@ -2713,6 +2746,19 @@ size of element in bytes must be {leq} size of the buffer object. The image data in the buffer object is stored as a single scanline which is a linear sequence of adjacent elements. +ifdef::cl_ext_image_from_buffer[] +For a 1D image created from a buffer object, the `image_width` {times} size of +element in bytes must be {leq} size of the buffer object. The image data in the +buffer object is stored as a single scanline which is a linear sequence of +adjacent elements. + +For a 1D image array created from a buffer object, the `image_slice_pitch` {times} +`image_array_size` must be {leq} size of the buffer object specified by `mem_object`. +The image data in the buffer object is stored as a linear sequence of adjacent 1D +slices. Each slice is a single scanline padded to `image_slice_pitch` bytes. +Each scanline is a linear sequence of image elements. +endif::cl_ext_image_from_buffer[] + For a 2D image created from a buffer object, the `image_row_pitch` {times} `image_height` must be {leq} size of the buffer object specified by `mem_object`. @@ -2721,6 +2767,22 @@ adjacent scanlines. Each scanline is a linear sequence of image elements padded to `image_row_pitch` bytes. +ifdef::cl_ext_image_from_buffer[] +For a 2D image array created from a buffer object, the `image_slice_pitch` {times} +`image_array_size` must be {leq} size of the buffer object specified by `mem_object`. +The image data in the buffer object is stored as a linear sequence of adjacent 2D +slices. Each slice is a linear sequence of adjacent scanlines padded to +`image_slice_pitch` bytes. Each scanline is a linear sequence of image elements padded +to `image_row_pitch` bytes. + +For a 3D image created from a buffer object, the `image_slice_pitch` {times} +`image_depth` must be {leq} size of the buffer object specified by `mem_object`. +The image data in the buffer object is stored as a linear sequence of adjacent 2D +slices padded to `image_slice_pitch` bytes. Each slice is a linear sequence of adjacent +scanlines. Each scanline is a linear sequence of image elements padded to +`image_row_pitch` bytes. +endif::cl_ext_image_from_buffer[] + For an image object created from another image object, the values specified in the image descriptor except for `mem_object` must match the image descriptor information associated with `mem_object`. @@ -2796,10 +2858,9 @@ stored in the image can be accessed as linear RGB or sRGB values. [NOTE] ==== Concurrent reading from, writing to and copying between both a buffer object -and 1D image buffer or 2D image object associated with the buffer object is -undefined. -Only reading from both a buffer object and 1D image buffer or 2D image -object associated with the buffer object is defined. +and buffer or image object associated with the buffer object is undefined. +Only reading from both a buffer object and buffer or image object associated +with the buffer object is defined. Writing to an image created from a buffer and then reading from this buffer in a kernel even if appropriate synchronization operations (such as a @@ -5190,6 +5251,8 @@ include::{generated}/api/version-notes/clGetImageRequirementsInfoEXT.asciidoc[] | Image Format Info | Return type | Info. returned in _param_value_ | {CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT_anchor} + +include::{generated}/api/version-notes/CL_IMAGE_REQUIREMENTS_BASE_ADDRESS_ALIGNMENT_EXT.asciidoc[] | `size_t` | Returns the minimum alignment in bytes required for the data store backing an image created using the parameters passed to {clGetImageRequirementsInfoEXT}. @@ -5199,6 +5262,8 @@ include::{generated}/api/version-notes/clGetImageRequirementsInfoEXT.asciidoc[] The value returned is a power of two. |{CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT_anchor} + +include::{generated}/api/version-notes/CL_IMAGE_REQUIREMENTS_ROW_PITCH_ALIGNMENT_EXT.asciidoc[] | `size_t` | Returns the row pitch alignment required in bytes for images created from a buffer with the parameters passed to {clGetImageRequirementsInfoEXT}. @@ -5208,6 +5273,8 @@ include::{generated}/api/version-notes/clGetImageRequirementsInfoEXT.asciidoc[] argument(s). | {CL_IMAGE_REQUIREMENTS_SIZE_EXT_anchor} + +include::{generated}/api/version-notes/CL_IMAGE_REQUIREMENTS_SIZE_EXT.asciidoc[] | `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}. @@ -5216,6 +5283,8 @@ include::{generated}/api/version-notes/clGetImageRequirementsInfoEXT.asciidoc[] {CL_INVALID_VALUE} is returned. | {CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT_anchor} + +include::{generated}/api/version-notes/CL_IMAGE_REQUIREMENTS_MAX_WIDTH_EXT.asciidoc[] | `cl_uint` | Returns the max width supported for creating images with the parameters passed to {clGetImageRequirementsInfoEXT}. @@ -5229,6 +5298,8 @@ include::{generated}/api/version-notes/clGetImageRequirementsInfoEXT.asciidoc[] // TODO: should we require _image_width_ to be `0`? | {CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT_anchor} + +include::{generated}/api/version-notes/CL_IMAGE_REQUIREMENTS_MAX_HEIGHT_EXT.asciidoc[] | `cl_uint` | Returns the max height supported for creating images with the parameters passed to {clGetImageRequirementsInfoEXT}. @@ -5245,6 +5316,8 @@ include::{generated}/api/version-notes/clGetImageRequirementsInfoEXT.asciidoc[] // TODO: should we require _image_height_ to be `0`? | {CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT_anchor} + +include::{generated}/api/version-notes/CL_IMAGE_REQUIREMENTS_MAX_DEPTH_EXT.asciidoc[] | `cl_uint` | Returns the max depth supported for creating images with the parameters passed to {clGetImageRequirementsInfoEXT}. @@ -5260,6 +5333,8 @@ include::{generated}/api/version-notes/clGetImageRequirementsInfoEXT.asciidoc[] // TODO: should we require _image_depth_ to be `0`? | {CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT_anchor} + +include::{generated}/api/version-notes/CL_IMAGE_REQUIREMENTS_MAX_ARRAY_SIZE_EXT.asciidoc[] | `cl_uint` | Returns the max array size supported for creating images with the parameters passed to {clGetImageRequirementsInfoEXT}. @@ -5274,6 +5349,20 @@ include::{generated}/api/version-notes/clGetImageRequirementsInfoEXT.asciidoc[] {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`? + +ifdef::cl_ext_image_from_buffer[] +| {CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT_anchor} + +include::{generated}/api/version-notes/CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT.asciidoc[] +| `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). +endif::cl_ext_image_from_buffer[] + |==== // refError diff --git a/extensions/cl_ext_image_from_buffer.asciidoc b/extensions/cl_ext_image_from_buffer.asciidoc deleted file mode 100644 index 1ef094c5d..000000000 --- a/extensions/cl_ext_image_from_buffer.asciidoc +++ /dev/null @@ -1,302 +0,0 @@ -// Copyright 2018-2024 The Khronos Group. This work is licensed under a -// Creative Commons Attribution 4.0 International License; see -// http://creativecommons.org/licenses/by/4.0/ - -:data-uri: -:icons: font -include::../config/attribs.txt[] -include::{generated}/api/api-dictionary-no-links.asciidoc[] -:source-highlighter: coderay - -= cl_ext_image_from_buffer -:R: pass:q,r[^(R)^] -Khronos{R} OpenCL Working Group - -== Name Strings - -`cl_ext_image_from_buffer` - -== 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 - -include::../copyrights.txt[] - -== Status - -Shipping. - -== Version - -Built On: {docdate} + -Version: 1.0.0 - -== Dependencies - -This extension is written against the OpenCL Specification version 3.0.9. - -This extension requires OpenCL 3.0. - -This extension requires `cl_ext_image_requirements_info`. - -== Overview - -This extension enables all types of images to be created from an existing buffer -object. - -== New API Enums - -Accepted value for the _param_name_ parameter to {clGetImageRequirementsInfoEXT}: - -[source,c] ----- -CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT 0x1291 ----- - -== Modifications to the OpenCL API Specification - -(Modify Section 5.3.1, *Creating Image Objects*) :: -+ --- -The following text: - --- -_image_format_ is a pointer to a structure that describes format properties of the image to be -allocated. A 1D image buffer or 2D image can be created from a buffer by specifying a buffer -object in the image_desc→mem_object. A 2D image can be created from another 2D image object -by specifying an image object in the image_desc→mem_object. Refer to the Image Format -Descriptor section for a detailed description of the image format descriptor. --- - -is replaced with: - --- -_image_format_ is a pointer to a structure that describes format properties of -the image to be allocated. An image can be created from a buffer by specifying -a buffer object in the _image_desc_->_mem_object_. A 2D image can be created from -another 2D image object by specifying an image object in the -_image_desc_->_mem_object_. Refer to the Image Format Descriptor section for a -detailed description of the image format descriptor. --- - -The following text: - --- -{CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if a 2D image is created from a buffer and -the row pitch and base address alignment does not follow the rules described -for creating a 2D image from a buffer. --- - -is replaced with: - --- -{CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if an image is created from a buffer and -the row or slice pitch and base address alignment do not follow the rules -described for creating an image from a buffer. --- - -The following text is added to the list of error conditions for {clCreateImageWithProperties}: - --- -{CL_INVALID_IMAGE_SIZE} if an image is created from a buffer and the buffer -passed in _image_desc->_mem_object_ is too small to be used as a data store -for the image, e.g. if its size is smaller than the value returned for -{CL_IMAGE_REQUIREMENTS_SIZE_EXT} for the parameters used to create the image. --- - - -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 an 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 for the _image_format_, -_image_type_ and _flags_ used to create the image. --- - - -The following text is added to the description for `image_slice_pitch`: - --- -For an image created from a buffer, the pitch specified (or computed if -pitch specified is 0) must be a multiple of the -{CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT} value for the _image_format_, -_image_type_ and _flags_ used to create the image. --- - -The following text: - --- -`mem_object` may refer to a valid buffer or image memory object. `mem_object` -can be a buffer memory object if image_type is {CL_MEM_OBJECT_IMAGE1D_BUFFER} -or {CL_MEM_OBJECT_IMAGE2D}. `mem_object` can be an image object if _image_type_ -is {CL_MEM_OBJECT_IMAGE2D}. Otherwise it must be `NULL`. The image pixels are -taken from the memory objects data store. When the contents of the specified -memory objects data store are modified, those changes are reflected in the -contents of the image object and vice-versa at corresponding synchronization -points. --- - -is replaced with: - --- -`mem_object` may refer to a valid buffer or image memory object. `mem_object` -can be an image object if _image_type_ is {CL_MEM_OBJECT_IMAGE2D}. -Otherwise it must be `NULL`. The image pixels are taken from the memory objects -data store. When the contents of the specified memory objects data store are -modified, those changes are reflected in the contents of the image object and -vice-versa at corresponding synchronization points. --- - -The following text is added: - --- -For a 1D image created from a buffer object, the `image_width` {times} size of -element in bytes must be {leq} size of the buffer object. The image data in the -buffer object is stored as a single scanline which is a linear sequence of -adjacent elements. - -For a 1D image array created from a buffer object, the `image_slice_pitch` {times} -`image_array_size` must be {leq} size of the buffer object specified by `mem_object`. -The image data in the buffer object is stored as a linear sequence of adjacent 1D -slices. Each slice is a single scanline padded to `image_slice_pitch` bytes. -Each scanline is a linear sequence of image elements. - -For a 2D image array created from a buffer object, the `image_slice_pitch` {times} -`image_array_size` must be {leq} size of the buffer object specified by `mem_object`. -The image data in the buffer object is stored as a linear sequence of adjacent 2D -slices. Each slice is a linear sequence of adjacent scanlines padded to -`image_slice_pitch` bytes. Each scanline is a linear sequence of image elements padded -to `image_row_pitch` bytes. - -For a 3D image created from a buffer object, the `image_slice_pitch` {times} -`image_depth` must be {leq} size of the buffer object specified by `mem_object`. -The image data in the buffer object is stored as a linear sequence of adjacent 2D -slices padded to `image_slice_pitch` bytes. Each slice is a linear sequence of adjacent -scanlines. Each scanline is a linear sequence of image elements padded to -`image_row_pitch` bytes. --- - -The following text: - --- -Concurrent reading from, writing to and copying between both a buffer object and -1D image buffer or 2D image object associated with the buffer object is undefined. -Only reading from both a buffer object and 1D image buffer or 2D image object -associated with the buffer object is defined. --- - -is replaced with: - --- -Concurrent reading from, writing to and copying between both a buffer object and -an image object associated with the buffer object is undefined. Only reading from -both a buffer object and image object associated with the buffer object is defined. --- - -(Modify section 5.3.X, *Querying image requirements*) :: -+ --- -The following is added to the _List of supported param_names by -*clGetImageRequirementsInfoEXT*: - -[width="100%",cols="<34%,<33%,<33%",options="header"] -|==== -| Image Requirement Info | Return type | Info. returned in _param_value_ - -| {CL_IMAGE_REQUIREMENTS_SLICE_PITCH_ALIGNMENT_EXT} -| `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). - -|==== --- --- - -== Interactions with Other Extensions - -None. - -== Conformance tests - - -. Test access from kernel - - For all image types - - For a few/all image formats - - For several values of row/slice pitch - - With or without a host_ptr - - Create buffer and fill with data - - Optionally create a sub-buffer with a randomly selected offset? - - Create an image from the buffer - - Read the image from a kernel and compare with values read using the buffer and direct addressing. They must match. - -. TODO Test access via read/write/map commands? - -. TODO Test copy to/from buffer? - -. TODO Test fill? - -. TODO Test copy to/from another image? - -. Test clGetImageInfo - - For all image types (one format per element size) - - For a few different row/pitch sizes (image dimensions being equal or not) - - Create an image from a buffer - - Check that the returned values for {CL_IMAGE_ROW_PITCH} and {CL_IMAGE_SLICE_PITCH} are correct. - -. Test clGetMemObjectInfo - - For all image types (1 format only) - - Create an image from a buffer - - Check that {CL_MEM_ASSOCIATED_MEMOBJECT} correctly returns the buffer that was used. - -. Negative testing for {clCreateImage} (alignment) - - For a few/all image formats - - For all image types - - Query row pitch, slice pitch and base image address alignment for the format - - Create an image from a buffer with invalid row pitch (not a multiple of required alignment) and check that {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} is returned. - - Create an image from a buffer with invalid slice pitch (not a multiple of required alignment) and check that {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} is returned. - - Create an image from a buffer with invalid base address alignment (not a multiple of required alignment) and check that {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} is returned. - -. Negative testing for {clCreateImage} (buffer size) - - For a few image formats (at least smallest and biggest element types) - - For all image types - - Create a buffer too small - - Check that image creation from that buffer is rejected with {CL_INVALID_IMAGE_SIZE} - -== Issues - -None. - -== Version History - -[cols="5,15,15,70"] -[grid="rows"] -[options="header"] -|==== -| Version | Date | Author | Changes -| 1.0.0 | 2022-01-25 | Kevin Petit | *Initial EXT revision* -|==== - diff --git a/extensions/extensions.txt b/extensions/extensions.txt index 6414878d7..cf5c98519 100644 --- a/extensions/extensions.txt +++ b/extensions/extensions.txt @@ -36,8 +36,6 @@ Khronos{R} OpenCL Working Group <<< include::cl_ext_float_atomics.asciidoc[] <<< -include::cl_ext_image_from_buffer.asciidoc[] -<<< include::cl_ext_image_raw10_raw12.asciidoc[] // Vendor Extensions From 99473e1794488a9417ce5f8102043adaffca5a09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Fri, 24 Jan 2025 09:56:03 +0000 Subject: [PATCH 2/4] Update api/opencl_runtime_layer.asciidoc Co-authored-by: Ben Ashbaugh --- api/opencl_runtime_layer.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index eb28e687d..92af20156 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -2092,7 +2092,7 @@ ifdef::cl_ext_image_from_buffer[] buffer. * {CL_INVALID_IMAGE_SIZE} if the {cl_ext_image_from_buffer_EXT} extension is supported and an image is created from a buffer and the buffer passed in - _image_desc->_mem_object_ is too small to be used as a data store for the + __image_desc__->__mem_object__ is too small to be used as a data store for the image, e.g. if its size is smaller than the value returned for {CL_IMAGE_REQUIREMENTS_SIZE_EXT} for the parameters used to create the image. endif::cl_ext_image_from_buffer[] From c406fd9ba43cf7cdab9f0fb0d4929dda5eda6542 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Fri, 24 Jan 2025 09:56:12 +0000 Subject: [PATCH 3/4] Update api/footnotes.asciidoc Co-authored-by: Ben Ashbaugh --- api/footnotes.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/footnotes.asciidoc b/api/footnotes.asciidoc index 01114e8d6..15fe29a34 100644 --- a/api/footnotes.asciidoc +++ b/api/footnotes.asciidoc @@ -53,7 +53,7 @@ Note that reading and writing 2D image arrays from a kernel with `image_array_si ] :fn-image-from-buffer: pass:n[ \ -To create an image from a buffer object that share the data store between the image and buffer object. \ +To create an image from a buffer object that shares the data store between the image and buffer object. \ ] :fn-image-from-image: pass:n[ \ From 55cad3fc8f1b710fd9501764a7a4b83617d19047 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Petit?= Date: Fri, 24 Jan 2025 09:56:47 +0000 Subject: [PATCH 4/4] Update api/cl_ext_image_from_buffer.asciidoc --- api/cl_ext_image_from_buffer.asciidoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/api/cl_ext_image_from_buffer.asciidoc b/api/cl_ext_image_from_buffer.asciidoc index a241bd1cf..1c39426a8 100644 --- a/api/cl_ext_image_from_buffer.asciidoc +++ b/api/cl_ext_image_from_buffer.asciidoc @@ -37,13 +37,13 @@ object. - Create an image from the buffer - Read the image from a kernel and compare with values read using the buffer and direct addressing. They must match. -. TODO Test access via read/write/map commands? +//. TODO Test access via read/write/map commands? -. TODO Test copy to/from buffer? +//. TODO Test copy to/from buffer? -. TODO Test fill? +//. TODO Test fill? -. TODO Test copy to/from another image? +//. TODO Test copy to/from another image? . Test clGetImageInfo - For all image types (one format per element size)