From fac5fa8db321c9d1c069b9e087f27c62a48993ab Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Tue, 15 Oct 2024 07:59:05 -0700 Subject: [PATCH] document valid coordinate types when reading from or writing to images (#1242) --- env/common_properties.asciidoc | 4 +- env/image_addressing_and_filtering.asciidoc | 126 ++++++++++++++++++++ 2 files changed, 128 insertions(+), 2 deletions(-) diff --git a/env/common_properties.asciidoc b/env/common_properties.asciidoc index 027f2989..c40b633b 100644 --- a/env/common_properties.asciidoc +++ b/env/common_properties.asciidoc @@ -128,13 +128,13 @@ OpenCL environments: | `0` | A 2D depth image. -// image1d_array_t +// image2d_array_t | *2D* | `0` | `1` | A 2D image array. -// image1d_array_depth_t +// image2d_array_depth_t | *2D* | `1` | `1` diff --git a/env/image_addressing_and_filtering.asciidoc b/env/image_addressing_and_filtering.asciidoc index c6f4f1fd..84c66fca 100644 --- a/env/image_addressing_and_filtering.asciidoc +++ b/env/image_addressing_and_filtering.asciidoc @@ -956,6 +956,132 @@ layer = v (since v is already an integer) and the result is undefined if v is not one of the integers 0, 1, ... `h~t~` - 1. +=== Coordinate Format for Reading and Writing Images + +This section describes valid types for the _Coordinate_ operand used by image +read instructions (such as *OpImageRead*) or image write instructions (such as +*OpImageWrite*). +The valid operand types are determined by the *OpImageType* for the image and +whether the image is being read from or written to. + +The following table describes the valid types for the _Coordinate_ operand when +reading from the specified image type. +The integer types for the _Coordinate_ operand are only valid when the image is +read without a sampler (such as *OpImageRead*), or with a sampler using +non-normalized texel coordinates, *Nearest* filtering, and either the *None*, +*ClampToEdge*, or *Clamp* addressing mode. + +._Mapping Image Types to Coordinate Types for Reading_ +[cols="1,1,1,6",options="header"] +|==== +| _Dim_ | _Depth_ | _Arrayed_ +| *Supported Coordinate Type* + +// image1d_t +| *1D* | `0` | `0` +| *OpTypeInt* with _Width_ equal to 32 + + *OpTypeFloat* with _Width_ equal to 32 + +// image1d_array_t +| *1D* | `0` | `1` +| *OpTypeVector* with 2 components of *OpTypeInt* with _Width_ equal to 32 + + *OpTypeVector* with 2 components of *OpTypeFloat* with _Width_ equal to 32 + + The array index is provided by the second component of the _Coordinate_. + +// image2d_t +| *2D* | `0` | `0` +| *OpTypeVector* with 2 components of *OpTypeInt* with _Width_ equal to 32 + + *OpTypeVector* with 2 components of *OpTypeFloat* with _Width_ equal to 32 + +// image2d_depth_t +| *2D* | `1` | `0` +| *OpTypeVector* with 2 components of *OpTypeInt* with _Width_ equal to 32 + + *OpTypeVector* with 2 components of *OpTypeFloat* with _Width_ equal to 32 + +// image2d_array_t +| *2D* | `0` | `1` +| *OpTypeVector* with 4 components of *OpTypeInt* with _Width_ equal to 32 + + *OpTypeVector* with 4 components of *OpTypeFloat* with _Width_ equal to 32 + + The array index is provided by the third component of the _Coordinate_. + The fourth component of the _Coordinate_ is ignored. + +// image2d_array_depth_t +| *2D* | `1` | `1` +| *OpTypeVector* with 4 components of *OpTypeInt* with _Width_ equal to 32 + + *OpTypeVector* with 4 components of *OpTypeFloat* with _Width_ equal to 32 + + The array index is provided by the third component of the _Coordinate_. + The fourth component of the _Coordinate_ is ignored. + +// image3d_t +| *3D* | `0` | `0` +| *OpTypeVector* with 4 components of *OpTypeInt* with _Width_ equal to 32 + + *OpTypeVector* with 4 components of *OpTypeFloat* with _Width_ equal to 32 + + The fourth component of the _Coordinate_ is ignored. + +// image1d_buffer_t +| *Buffer* | `0` | `0` +| *OpTypeInt* with _Width_ equal to 32 + + *OpTypeFloat* with _Width_ equal to 32 + +|==== + +The following table describes the valid types for the _Coordinate_ operand when +writing to the specified image type. + +._Mapping Image Types to Coordinate Types for Writing_ +[cols="1,1,1,6",options="header"] +|==== +| _Dim_ | _Depth_ | _Arrayed_ +| *Supported Coordinate Type* + +// image1d_t +| *1D* | `0` | `0` +| *OpTypeInt* with _Width_ equal to 32 + +// image1d_array_t +| *1D* | `0` | `1` +| *OpTypeVector* with 2 components of *OpTypeInt* with _Width_ equal to 32 + + The array index is provided by the second component of the _Coordinate_. + +// image2d_t +| *2D* | `0` | `0` +| *OpTypeVector* with 2 components of *OpTypeInt* with _Width_ equal to 32 + +// image2d_depth_t +| *2D* | `1` | `0` +| *OpTypeVector* with 2 components of *OpTypeInt* with _Width_ equal to 32 + +// image2d_array_t +| *2D* | `0` | `1` +| *OpTypeVector* with 4 components of *OpTypeInt* with _Width_ equal to 32 + + The array index is provided by the third component of the _Coordinate_. + The fourth component of the _Coordinate_ is ignored. + +// image2d_array_depth_t +| *2D* | `1` | `1` +| *OpTypeVector* with 4 components of *OpTypeInt* with _Width_ equal to 32 + + The array index is provided by the third component of the _Coordinate_. + The fourth component of the _Coordinate_ is ignored. + +// image3d_t +| *3D* | `0` | `0` +| *OpTypeVector* with 4 components of *OpTypeInt* with _Width_ equal to 32 + + The fourth component of the _Coordinate_ is ignored. + +// image1d_buffer_t +| *Buffer* | `0` | `0` +| *OpTypeInt* with _Width_ equal to 32 + +|==== + === Data Format for Reading and Writing Images This section describes how image element data is returned by an