document valid coordinate types when reading from or writing to images (

#1242)

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`

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