Image buffers (#757)

Contributes to #747

Add support for specifying buffers as images via a new command.
 * takes dimensionality and dimensions
 * Generalize image support to support 1D and 3D images.

Add some examples of the new functionality.

Simplify some Vulkan image calls.

1 files changed, 32 insertions, 4 deletions

diff --git a/docs/amber_script.md b/docs/amber_script.md
index 3a403a4..03a23b0 100644
--- a/docs/amber_script.md
+++ b/docs/amber_script.md
@@ -137,10 +137,11 @@ END
 BUFFER {name} DATA_TYPE {type} {STD140 | STD430} SIZE _size_in_items_ \
     {initializer}
 
+# Deprecated
 # Defines a buffer with width and height and filled by data as specified by the
 # `initializer`.
 BUFFER {name} DATA_TYPE {type} {STD140 | STD430} WIDTH {w} HEIGHT {h} \
-    {initializer}
+  {initializer}
 
 # Creates a buffer which will store the given `FORMAT` of data. These
 # buffers are used as image and depth buffers in the `PIPELINE` commands.
@@ -149,6 +150,31 @@ BUFFER {name} FORMAT {format_string} \
     [ MIP_LEVELS _mip_levels_ (default 1) ]
 ```
 
+#### Images
+
+An AmberScript image is a specialized buffer that specifies image-specific
+attributes.
+
+##### Dimensionality
+ * `DIM_1D` -- A 1-dimensional image
+ * `DIM_2D` -- A 2-dimensional image
+ * `DIM_3D` -- A 3-dimensional image
+
+```groovy
+# Specify an image buffer with a format. HEIGHT is necessary for DIM_2D and
+# DIM_3D. DEPTH is necessary for DIM_3D.
+IMAGE {name} FORMAT {format_string} [ MIP_LEVELS _mip_levels_ (default 1) ] \
+    {dimensionality} \
+    WIDTH {w} [ HEIGHT {h} [ DEPTH {d} ] ] \
+    {initializer}
+
+# Specify an image buffer with a data type. HEIGHT is necessary for DIM_2D and
+# DIM_3D. DEPTH is necessary for DIM_3D.
+IMAGE {name} DATA_TYPE {type} {dimensionality} \
+    WIDTH {w} [ HEIGHT {h} [ DEPTH {d} ] ] \
+    {intializer}
+```
+
 #### Buffer Initializers
 
 ```groovy
@@ -177,8 +203,6 @@ COPY {buffer_from} TO {buffer_to}
 Samplers are used for sampling buffers that are bound to a pipeline as
 sampled image or combined image sampler.
 
-The samplers use normalized coordinates in the range of [0..1].
-
 #### Filter types
  * `nearest`
  * `linear`
@@ -206,11 +230,15 @@ SAMPLER {name} \
     [ MIN_FILTER {filter_type} (default nearest) ] \
     [ ADDRESS_MODE_U {address_mode} (default repeat) ] \
     [ ADDRESS_MODE_V {address_mode} (default repeat) ] \
+    [ ADDRESS_MODE_W {address_mode} (default repeat) ] \
     [ BORDER_COLOR {border_color} (default float_transparent_black) ] \
     [ MIN_LOD _val_ (default 0.0) ] \
-    [ MAX_LOD _val_ (default 1.0) ]
+    [ MAX_LOD _val_ (default 1.0) ] \
+    [ NORMALIZED_COORDS | UNNORMALIZED_COORDS (default NORMALIZED_COORDS) ]
 ```
 
+Note: unnormalized coordinates will override MIN\_LOD and MAX\_LOD to 0.0.
+
 ### Pipelines
 
 #### Pipeline type