Integrate cl_ext_image_tiling_control into unified spec

Change-Id: Id434000fdf949c76af92dff17829462e4bc9dd0f

api/cl_ext_image_tiling_control.asciidoc

@@ -0,0 +1,58 @@
+// Copyright 2021-2025 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}cl_ext_image_tiling_control.txt[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+    2025-01-06
+*IP Status*::
+    No known IP claims.
+*Contributors*::
+  - Kevin Petit, Arm Ltd.
+  - Plamen Petkov, Arm Ltd.
+  - Ben Ashbaugh, Intel
+  - Balaji Calidas, Qualcomm
+  - Jeremy Kemp, Google
+  - Nikhil Joshi, NVIDIA
+
+=== Description
+
+This extension gives applications explicit control over how image data is laid out in memory.
+
+=== New Types
+
+  * {cl_image_tiling_ext_TYPE}
+  * {cl_device_image_tiling_capabilities_ext_TYPE}
+
+=== New Enums
+
+  * {cl_device_info_TYPE}
+  ** {CL_DEVICE_IMAGE_TILING_CAPABILITIES_EXT}
+  * {cl_mem_properties_TYPE}
+  ** {CL_MEM_IMAGE_TILING_EXT}
+  * {cl_image_info_TYPE}
+  ** {CL_IMAGE_TILING_EXT}
+  * {cl_image_tiling_ext_TYPE}
+  ** {CL_IMAGE_TILING_LINEAR_EXT}
+  ** {CL_IMAGE_TILING_OPTIMAL_EXT}
+  * {cl_device_image_tiling_capabilities_ext_TYPE}
+  ** {CL_DEVICE_IMAGE_TILING_DEVICE_ACCESS_EXT}
+  ** {CL_DEVICE_IMAGE_TILING_HOST_ACCESS_EXT}
+
+=== Issues
+
+. How can an application get a view of tiled image data?
++
+--
+*RESOLVED*: An application wishing to get visibility of tiled data can do so by
+creating images from a buffer and mapping the buffer directly.
+--
+
+=== Version History
+
+  * Revision 0.1.0, 2021-11-01
+  ** Initial revision
+  * Revision 0.2.0, 2025-01-06
+  ** WIP discussion with other vendors

api/opencl_platform_layer.asciidoc

@@ -2097,6 +2097,24 @@ include::{generated}/api/version-notes/CL_DEVICE_CXX_FOR_OPENCL_NUMERIC_VERSION_
     | Returns the version of the C++ for OpenCL language supported by the
       device compiler.
 endif::cl_ext_cxx_for_opencl[]
+
+ifdef::cl_ext_image_tiling_control[]
+| {CL_DEVICE_IMAGE_TILING_CAPABILITIES_EXT_anchor}
+
+include::{generated}/api/version-notes/CL_DEVICE_IMAGE_TILING_CAPABILITIES_EXT.asciidoc[]
+  | {cl_device_image_tiling_capabilities_ext_TYPE}
+    | Returns the image tiling capabilities supported by the device. +
+
+      {CL_DEVICE_IMAGE_TILING_DEVICE_ACCESS_EXT_anchor} is always set indicating
+      that all implementations that support {cl_ext_image_tiling_control_EXT}
+      must support device access to tiled images.
+
+      {CL_DEVICE_IMAGE_TILING_HOST_ACCESS_EXT_anchor} is set when it is allowed
+      to pass {CL_MEM_IMAGE_TILING_EXT} with a value different from
+      {CL_IMAGE_TILING_LINEAR_EXT} in the _properties_ given to
+      {clCreateImageWithProperties} when creating host-accessible images.
+      Host-accessible images are all images created without {CL_MEM_HOST_NO_ACCESS}.
+endif::cl_ext_image_tiling_control[]
 |====
 
 ifdef::cl_khr_integer_dot_product[]

api/opencl_runtime_layer.asciidoc

@@ -1996,6 +1996,39 @@ The following restrictions apply when mipmapped images are created with
     images, depth images or multi-sampled (i.e. msaa) images.
 endif::cl_khr_mipmap_image[]
 
+ifdef::cl_ext_image_tiling_control[]
+*Tiling Control*
+
+{CL_MEM_IMAGE_TILING_EXT_anchor} can be passed as part of the _properties_ parameter
+to {clCreateImageWithProperties} to control the tiling used for the image being
+created. The following values are accepted:
+
+  * {CL_IMAGE_TILING_LINEAR_EXT_anchor}, which is the default value used if
+    {CL_MEM_IMAGE_TILING_EXT} is not specified in the _properties_. Image data
+    is laid out in so-called raster order, one row after the other, one slice or
+    array layer after the other in memory according to the pitches provided by
+    the application or calculated.
+
+  * {CL_IMAGE_TILING_OPTIMAL_EXT_anchor} requires image data be laid out in an
+    implementation-defined format which can vary depending on the type of image,
+    its format and/or dimensions. The implementation will attempt to select the
+    best layout for the image.
+
+If {CL_MEM_IMAGE_TILING_EXT} is passed and set to a value different from
+{CL_IMAGE_TILING_LINEAR_EXT}, {CL_MEM_USE_HOST_PTR} must not be set in _mem_flags_.
+
+If {CL_MEM_IMAGE_TILING_EXT} is passed and set to a value different from
+{CL_IMAGE_TILING_LINEAR_EXT} and {CL_MEM_COPY_HOST_PTR} is set in _mem_flags_, the data
+pointed to by _host_ptr_ is laid out using linear tiling and its layout is described
+in the same way as for case whe {CL_MEM_IMAGE_TILING_EXT} is not set or set to
+{CL_IMAGE_TILING_LINEAR_EXT}.
+
+When creating an image from a buffer, _image_row_pitch_ and _image_slice_pitch_
+must both be `0` if {CL_MEM_IMAGE_TILING_EXT} is passed and set to
+{CL_IMAGE_TILING_OPTIMAL_EXT}. The data in the buffer and its underlying memory
+are reused as-is and the exact behaviour is implementation-defined.
+endif::cl_ext_image_tiling_control[]
+
 *Image Data in Host Memory*
 
 For a 3D image or 2D image array, the image data specified by _host_ptr_ is
@@ -4091,6 +4124,14 @@ execution status of the map command.
 When the map command is completed, the application can access the contents
 of the mapped region using the pointer returned by {clEnqueueMapImage}.
 
+ifdef::cl_ext_image_tiling_control[]
+If the image object is created with {CL_MEM_IMAGE_TILING_EXT} set to a value
+different from {CL_IMAGE_TILING_LINEAR_EXT}, the implementation may need to
+allocate memory and perform a copy as part of the map operation. The pointer
+returned to the application will always point to data in linear tiling
+laid out according to the returned _image_row_pitch_ and _image_slice_pitch_.
+endif::cl_ext_image_tiling_control[]
+
 // refError
 
 {clEnqueueMapImage} will return a pointer to the mapped region.
@@ -4344,8 +4385,27 @@ include::{generated}/api/version-notes/CL_IMAGE_D3D11_SUBRESOURCE_KHR.asciidoc[]
       specified when _image_ was created.
 endif::cl_khr_d3d11_sharing[]
 
+ifdef::cl_ext_image_tiling_control[]
+| {CL_IMAGE_TILING_EXT_anchor}
+
+include::{generated}/api/version-notes/CL_IMAGE_TILING_EXT.asciidoc[]
+  | {cl_image_tiling_ext_TYPE}
+    | Return the tiling passed using the {CL_MEM_IMAGE_TILING_EXT} property or
+      {CL_IMAGE_TILING_LINEAR_EXT} if none was passed at image creation time.
+endif::cl_ext_image_tiling_control[]
+
 |====
 
+ifdef::cl_ext_image_tiling_control[]
+If the image object is created with {CL_MEM_IMAGE_TILING_EXT} set to a value
+different from {CL_IMAGE_TILING_LINEAR_EXT}, the value returned for
+
+* {CL_IMAGE_ROW_PITCH} is the value that would be returned as _image_row_pitch_
+  by {clEnqueueMapImage} when mapping the entire image.
+* {CL_IMAGE_SLICE_PITCH} is the value that would be returned as _image_slice_pitch_
+  by {clEnqueueMapImage} when mapping the entire image.
+endif::cl_ext_image_tiling_control[]
+
 // refError
 
 {clGetImageInfo} returns  {CL_SUCCESS} if the function is executed

extensions/extensions.txt

@@ -41,8 +41,6 @@ include::cl_ext_image_from_buffer.asciidoc[]
 include::cl_ext_image_raw10_raw12.asciidoc[]
 <<<
 include::cl_ext_image_requirements_info.asciidoc[]
-<<<
-include::cl_ext_image_tiling_control.asciidoc[]
 
 // Vendor Extensions
 :leveloffset: 0