Initial commit of Amber for open source

Amber is a multi-API shader test framework.

Amber lets you capture and communicate shader bugs with the fluidity and ease of a scripting flow:

* No graphics API programming is required.
  * WIP: Supports Vulkan and [Dawn][Dawn] graphics APIs.
* A single text string (or file) maps to a single graphics API pipeline test case.  The text includes:
  * Input data, including buffers and images.
  * Shaders.
  * Expectations for the result of running the pipeline.
* Shaders can be expressed in binary form (as hex), in SPIR-V assembly, or in a higher level shader language.
* After executing the pipeline, result buffers and images can be saved to output files.

This is not an officially supported Google product.

3 files changed, 1084 insertions, 0 deletions

diff --git a/docs/amber_script.md b/docs/amber_script.md
new file mode 100644
index 0000000..b998377
--- /dev/null
+++ b/docs/amber_script.md
@@ -0,0 +1,409 @@
+# AmberScript
+ * DRAFT
+
+This document defines the script input language for the Amber system. The format
+is based on the Talvos format, VkRunner format, and VkScript proposed format.
+
+## Specification
+All amber scripts must start with `#!amber` as the first line. Comments are
+specified by a # character and continue to the end of the line. Keywords are
+case sensitive. All names are made up of ASCII characters, and delimited by
+whitespace.
+
+TODO(dneto): What characters are valid in a name?
+
+### Number literals
+
+Literal numbers are normally presented in decimal form.  They are interpreted
+as integers or floating point depending on context: a command parameter is predefined
+as either integral or floating point, or the data type is user-specified (such
+as for buffer data).
+
+Hex values: Whenever an integer is expected, you may use a hexadecimal number, which
+is the characters `0x` followed by hexadecimal digits.
+
+### Shaders
+
+#### Shader Type
+ * vertex
+ * fragment
+ * geometry
+ * tessellation\_evaluation
+ * tessellation\_control
+ * compute
+
+The compute pipeline can only contain compute shaders. The graphics pipeline
+can not contain compute shaders, and must contain a vertex shader and a fragment
+shader.
+
+#### Shader Format
+ * GLSL  (with glslang)
+ * HLSL  (with dxc or glslang if dxc disabled)  -- future
+ * SPIRV-ASM (with spirv-as)
+ * SPIRV-HEX (decoded straight to spv)
+ * OPENCL-C (with clspv)  --- potentially?  -- future
+
+```
+SHADER vertex <shader_name> PASSTHROUGH
+
+SHADER <shader_type> <shader_name> <shader_format>
+...
+END
+```
+
+### Buffers
+
+#### Data Types
+ * int8
+ * int16
+ * int32
+ * int64
+ * uint8
+ * uint16
+ * uint32
+ * uint64
+ * float
+ * double
+ * vec[2,3,4]\<type>
+ * mat[2,3,4]\<type>    -- useful?
+
+TODO(dneto): Support half-precision floating point.
+
+Sized arrays and structures are not currently representable.
+
+#### Buffer Types
+ * uniform
+ * storage
+ * vertex
+ * index
+ * sampled
+ * storage
+ * color
+ * depth
+
+```
+// Filling the buffer with a given set of data. The values must provide
+// <size_in_bytes> of <type> data. The data can be provided as the type or
+// as a hex value.
+
+BUFFER <buffer_type> <name> DATA_TYPE <type> DATA
+<value>+
+END
+
+BUFFER <buffer_type> <name> DATA_TYPE <type> SIZE <size_in_bytes> <initializer>
+
+BUFFER framebuffer <name> DIMS <width_in_pixels> <height_in_pixels>
+```
+
+#### Buffer Initializers
+Fill the buffer with a single value.
+
+```
+FILL <value>
+```
+
+Fill the buffer with an increasing value from \<start> increasing by \<inc>.
+Floating point data uses floating point addition to generate increasting values.
+Likewise, integer data uses integer addition to generate increasing values.
+
+```
+SERIES <start> <inc>
+```
+
+### Pipelines
+
+#### Pipeline type
+ * compute
+ * graphics
+
+The PIPELINE command creates a pipeline. This can be either compute or graphics.
+Shaders are attached to the pipeline at pipeline creation time.
+
+```
+PIPELINE <pipeline_type> <pipeline_name>
+...
+END
+```
+
+### Pipeline Content
+
+The following commands are all specified within the `PIPELINE` command. If you
+have multiple entry points for a given shader, you'd create multiple pipelines
+each with a different `ENTRY_POINT`.
+
+Bind the entry point to use for a given shader. The default entry point is main.
+
+```
+  ENTRY_POINT <shader_name> <entry_point_name>
+```
+
+Shaders can be added into pipelines with the `ATTACH` call. Shaders may be
+attached to multiple pipelines at the same time.
+
+```
+  ATTACH <name_of_vertex_shader>
+  ATTACH <name_of_fragment_shader>
+```
+
+Set the SPIRV-Tools optimization passes to use for a given shader. The default
+is to run no optimization passes.
+```
+  SHADER_OPTIMIZATION <shader_name>
+    <optimization_name>+
+  END
+```
+
+#### Bindings
+
+##### Topologies
+ * point\_list
+ * line\_list
+ * line\_list\_with\_adjacency
+ * line\_strip
+ * line\_strip\_with\_adjacency
+ * triangle\_list
+ * triangle\_list\_with\_adjacency
+ * triangle\_strip
+ * triangle\_strip\_with\_adjacency
+ * triangle\_fan
+ * patch\_list
+
+Bind a provided framebuffer.
+
+```
+  FRAMEBUFFER <buffer_of_type_framebuffer_name>
+```
+
+Descriptor sets can be bound as:
+
+```
+  DESCRIPTOR_SET <id> BINDING <id> IDX <0> TO <buffer_name>
+```
+
+### Run a pipeline.
+
+```
+RUN <pipeline_name> <x> <y> <z>
+
+RUN <pipeline_name> \
+  DRAW_RECT POS <x_in_pixels> <y_in_pixels> \
+  SIZE <width_in_pixels> <height_in_pixels>
+
+RUN <pipeline_name> \
+  DRAW_ARRAY <indices_buffer> IN <data_buffer> \
+  AS <topology> START_IDX <value> COUNT <value>
+```
+
+### Commands
+```
+CLEAR_COLOR <pipeline> <r (0 - 255)> <g (0 - 255)> <b (0 - 255)>
+
+CLEAR <pipeline>
+```
+
+### Expectations
+
+#### Comparators
+ * EQ
+ * NE
+ * LT
+ * LE
+ * GT
+ * GE
+ * EQ\_RGB
+ * EQ\_RGBA
+
+```
+EXPECT <buffer_name> IDX <x> <y> <comparator> <value>+
+
+EXPECT <framebuffer_name> IDX <x_in_pixels> <y_in_pixels> \
+  SIZE <width_in_pixels> <height_in_pixels> \
+  EQ_RGB <r (0 - 255)> <g (0 - 255)> <b (0 - 255)>
+```
+
+## Examples
+
+### Compute Shader
+```
+#!amber
+# Simple amber compute shader.
+
+SHADER compute kComputeShader GLSL
+#version 450
+
+layout(binding = 3) buffer block {
+  vec2 values[];
+};
+
+void main() {
+  values[gl_WorkGroupID.x + gl_WorkGroupID.y * gl_NumWorkGroups.x] =
+                gl_WorkGroupID.xy;
+}
+END  # shader
+
+BUFFER storage kComputeBuffer TYPE vec2<int32> SIZE 524288 FILL 0
+
+PIPELINE compute kComputePipeline
+  ATTACH kComputeShader
+  DESCRIPTOR_SET 0 BINDING 3 IDX 0 TO kComputeBuffer
+END  # pipeline
+
+RUN kComputePipeline 256 256 1
+
+# Four corners
+EXPECT kComputeBuffer IDX 0 EQ 0 0
+EXPECT kComputeBuffer IDX 2040 EQ 255 0
+EXPECT kComputeBuffer IDX 522240 EQ 0 255
+EXPECT kComputeBuffer IDX 524280 EQ 255 255
+
+# Center
+EXPECT kComputeBuffer IDX 263168 EQ 128 128
+```
+
+### Entry Points
+```
+#!amber
+
+SHADER vertex kVertexShader PASSTHROUGH
+
+SHADER fragment kFragmentShader SPIRV-ASM
+              OpCapability Shader
+          %1 = OpExtInstImport "GLSL.std.450"
+               OpMemoryModel Logical GLSL450
+
+; two entrypoints
+               OpEntryPoint Fragment %red "red" %color
+               OpEntryPoint Fragment %green "green" %color
+
+               OpExecutionMode %red OriginUpperLeft
+               OpExecutionMode %green OriginUpperLeft
+               OpSource GLSL 430
+               OpName %red "red"
+               OpDecorate %color Location 0
+       %void = OpTypeVoid
+          %3 = OpTypeFunction %void
+      %float = OpTypeFloat 32
+    %v4float = OpTypeVector %float 4
+%_ptr_Output_v4float = OpTypePointer Output %v4float
+      %color = OpVariable %_ptr_Output_v4float Output
+    %float_1 = OpConstant %float 1
+    %float_0 = OpConstant %float 0
+  %red_color = OpConstantComposite %v4float %float_1 %float_0 %float_0 %float_1
+%green_color = OpConstantComposite %v4float %float_0 %float_1 %float_0 %float_1
+
+; this entrypoint outputs a red color
+        %red = OpFunction %void None %3
+          %5 = OpLabel
+               OpStore %color %red_color
+               OpReturn
+               OpFunctionEnd
+
+; this entrypoint outputs a green color
+      %green = OpFunction %void None %3
+          %6 = OpLabel
+               OpStore %color %green_color
+               OpReturn
+               OpFunctionEnd
+END  # shader
+
+BUFFER framebuffer kFrameBuffer DIMS 256 256
+
+PIPELINE graphics kRedPipeline
+  ATTACH kVertexShader
+  SHADER_OPTIMIZATION kVertexShader
+    eliminate-dead-branches
+    merge-return
+    eliminate-dead-code-aggressive
+  END
+
+  ATTACH kFragmentShader
+
+  FRAMEBUFFER kFrameBuffer
+  ENTRY_POINT kFragmentShader red
+END  # pipeline
+
+PIPELINE graphics kGreenPipeline
+  ATTACH kVertexShader
+  ATTACH kFragmentShader
+
+  FRAMEBUFFER kFrameBuffer
+  ENTRY_POINT kFragmentShader green
+END  # pipeline
+
+RUN kRedPipeline DRAW_RECT POS 0 0  SIZE 256 256
+RUN kGreenPipeline DRAW_RECT POS 128 128 SIZE 256 256
+
+EXPECT kFrameBuffer IDX 0 0 SIZE 127 127 EQ_RGB 255 0 0
+EXPECT kFrameBuffer IDX 128 128 SIZE 128 128 EQ_RGB 0 255 0
+```
+
+### Buffers
+```
+#!amber
+
+SHADER vertex kVertexShader GLSL
+  #version 430
+
+  layout(location = 0) in vec4 position;
+  layout(location = 1) in vec4 color_in;
+  layout(location = 0) out vec4 color_out;
+
+  void main() {
+    gl_Position = position;
+    color_out = color_in;
+  }
+END  # shader
+
+SHADER fragment kFragmentShader GLSL
+  #version 430
+
+  layout(location = 0) in vec4 color_in;
+  layout(location = 0) out vec4 color_out;
+
+  void main() {
+    color_out = color_in;
+  }
+END  # shader
+
+PIPELINE graphics kGraphicsPipeline
+  ATTACH kVertexShader
+  ATTACH kFragmentShader
+END  # pipeline
+
+BUFFER vertex kData TYPE vec3<int32> DATA
+# Top-left red
+-1 -1  0xff0000ff
+ 0 -1  0xff0000ff
+-1  0  0xff0000ff
+ 0  0  0xff0000ff
+# Top-right green
+ 0 -1  0xff00ff00
+ 1 -1  0xff00ff00
+ 0  0  0xff00ff00
+ 1  0  0xff00ff00
+# Bottom-left blue
+-1  0  0xffff0000
+ 0  0  0xffff0000
+-1  1  0xffff0000
+ 0  1  0xffff0000
+# Bottom-right purple
+ 0  0  0xff800080
+ 1  0  0xff800080
+ 0  1  0xff800080
+ 1  1  0xff800080
+END
+
+BUFFER index kIndices TYPE int32 DATA
+0  1  2    2  1  3
+4  5  6    6  5  7
+8  9  10   10 9  11
+12 13 14   14 13 15
+END
+
+CLEAR_COLOR kGraphicsPipeline 255 0 0 255
+CLEAR kGraphicsPipeline
+
+RUN kGraphicsPipeline \
+  DRAW_ARRAY kIndices IN kBuffer AS triangle_list \
+  START_IDX 0 COUNT 24
+ ```
diff --git a/docs/vk_script.md b/docs/vk_script.md
new file mode 100644
index 0000000..9448b56
--- /dev/null
+++ b/docs/vk_script.md
@@ -0,0 +1,609 @@
+# VkScript
+
+The VkScript format is a clone of the format used by VkRunner as described in
+[1].
+
+# General
+## Comments
+The # symbol can be used to start a comment which extends to the end of the
+line.
+
+## Continuations
+The \ can be used at the end of a line to signal a continuation, the
+new line will be skipped and parsing will treat the following line as a
+continuation of the current line.
+
+## Descriptor Sets and Bindings
+Any command below which accepts a binding will accept either a single integer
+value which will have a descriptor set of 0 and a binding of the value give or
+a string can be provided of the form <set integer>:<binding integer> in which
+case the descriptor set value will be `set` and the binding value will be
+`binding`.
+
+# Sections
+
+The format is broken down into five main sections:
+ * require
+ * shaders
+ * indices
+ * vertex data
+ * test
+
+## Require
+The `require` section lists all of the requirements for the testing environment.
+There are four types of information that can be encoded in the require section.
+
+The _feature_ list contains a list of features that are required in
+order for the test to execute. If a feature is missing an error will be reported
+and the test will fail. The _features_ are listed below in the
+*Available Require Features* section.
+
+The _framebuffer_ and _depthstencil_ commands allow setting the format for the
+given buffer. The valid values are listed below in the *Image Formats*
+section.
+
+The last option is _extensions_. Any string which isn't a _feature_,
+_framebuffer_ or _depthstencil_ is assumed to be an _extension_. The extensions
+must be of the format [a-zA-Z0-9_]+. If the device extension is not available
+we will report it is not available and the test will continue.
+
+#### Require Examples
+```
+[require]
+independentBlend
+VK_KHR_storage_buffer_storage_class
+```
+
+## Shaders
+The shader section allows you to specify the content of the shaders under test.
+This can be done as GLSL, SPIRV-ASM or SPIRV-Hex depending on how the shader is
+formatted. There is also a special *passthrough* vertex shader which can be
+used which just passes the vec4 input location 0 through to the `gl_Position`.
+The shader format is specified in the header after the word `shader`. The
+default is `GLSL`, SPIRV-ASM is specified as `spirv` and SPIRV-Hex as
+`spirv hex`.
+
+The shaders accepted are:
+ * compute
+ * fragment
+ * geometry
+ * tessellation control
+ * tessellation evaulation
+ * vertex
+
+#### Shader examples
+```
+[fragment shader]
+#version 430
+
+layout(location = 0) out vec4 color_out;
+
+void main() {
+  color_out = vec4(1, 2, 3, 4);
+}
+
+```
+
+Other example shader header lines are:
+ * `[fragment shader spirv hex]` -- a hex encoded SPIRV binary fragment shader
+ * `[tessellation evaluation shader spirv]` -- a spirv-asm tessellation evaluation shader
+ * `[vertex shader passthrough]`
+
+## Vertex Data
+The `vertex data` section provides vertex attributes and data for `draw array`
+commands. The data is formated with a header row followed by data rows.
+
+The headers can be provided in one of two forms. The first,
+`attribute_location/format` where `attribute_location` is the location of the
+attribute to be bound. The format is one of the *Image Formats* listed below.
+The second, `attribute_location/gl_type/glsl_type`. The `gl_type` is one of
+the types listed in the *GL Types* section below. The `glsl_type` is one listed
+in the *GLSL Types* section below.
+
+#### Vertex Data example
+```
+[vertex data]
+0/R32G32B32_SFLOAT  1/R8G8B8_UNORM
+-1    -1 0.25       255 0 0  # ending comment
+# Another Row
+0.25  -1 0.25       255 0 255
+```
+
+## Indices
+The `indices` section contains the list of indices to use along with the
+provided `vertex data`. The `indices` are used if the `indexed` option is
+provided to the `draw arrays` command. The indices themselves are a list of
+integer indexes to use.
+
+#### Indices Example
+```
+[indices]
+# comment line
+1 2 3   4 5 6
+# another comment
+7 8 9  10 11 12
+```
+
+## Test
+The test section contains a list of commands which can be executed to perform
+the actual testing. The commands range from setting up pipeline parameters,
+executing compute shaders and probing buffers to verify results.
+
+
+### Draw Rect
+ * `draw rect [ortho] [patch] _x_ _y_ _width_ _height_`
+
+The `draw rect` command draws a rectangle at the given coordinates. The vertices
+are uploaded at location 0 as a `vec3`. The `ortho` modifier scales the
+coordinates to be in the range of [-1,1] instead of [0,window size]. The `patch`
+modifier sets the draw call to use a given topology. Accepted possible
+topology value are listed in *Topologies*. The patch size will be set to 4.
+
+
+### Draw Arrays
+ * `draw arrays [indexed] [instanced] _topology_ _first_vertex_ _vertex_count_ [instance_count]`
+
+The `draw arrays` command uses data from the `vertex data` section when executing
+the draw command. The `topology` is from the *Topologies* list. If the `indexed`
+modifier is provided then the `indices` section data will be used as well.
+
+
+### Compute
+ * `compute _x_ _y_ _z_`
+
+Executes the compute shader with the given `x`, `y`, and `z` parameters.
+
+
+### Shader Entry Point
+ * `_stage_ entrypoint _name_`
+
+Sets the `stage` shader to use the entry point of `name` for subsequent
+executions.
+
+
+### Probe all
+ * `probe all (rgb|rgba) _r_ _g_ _b_ [_a_]
+
+Probes the entire window to verify all pixels are of color r,g,b and optionally
+a. If `rgba` is specified then the `a` parameter is required. If `rgb` is
+specified then the `a` parameter is dis-allowed.
+
+
+### Probe
+ * `[relative] probe [rect] (rgb|rgba) (_x_, _y_[, _width_, _height_]) (_r_, _g_, _b_[, _a_])`
+
+Probes a portion of the window to verify the pixes are of color r,g,b and
+optionally a. If `rgba` is specifed then the `a` parameter is required. If
+`rgb` is specified then the `a` parameter is dis-allowed. If `rect` is specified
+then `width` and `height` are required. If `rect` is not specified then `width`
+and `height` are dis-allowed and a value of 1 will be used for each parameter.
+If the `relative` parameter is provided the coordinates are normalized to
+be in the range [0.0, 1.0].
+
+
+### Probe SSBO
+* `probe ssbo _type_ _binding_ _offset_ _comparison_ _values_+`
+
+Probes the value in the storage buffer at `binding` and `offset` within that
+binding. The `type` is the data type to be probed as seen in the *Data Types*
+section below.
+
+The comparison operators are:
+ * `==`   (equal)
+ * `!=`   (not equal)
+ * `<`    (less than)
+ * '>'    (greater than)
+ * `<=`   (less or equal)
+ * `>=`   (greater or equal)
+ * `~=`   (fuzzy equal, for floating point comparisons using `tolerances`)
+
+The `values` provided must be a non-zero multiple of the `type`.
+
+
+### Uniform
+ * `uniform _type_ _offset _values_+`
+
+Sets the push constants at `offset`. The `type` is from the *Data Types*
+section below. The `values` must be a non-zero multiple of the requested
+`type`.
+
+
+### Unifom UBO
+ * `uniform ubo _binding_ _type_ _offset_ _values_+`
+
+Sets the values in the uniform buffer at `binding` and `offset`. The `type`
+is from the *Data Types* section below. The `values` must be a non-zero
+multiple of the requested `type`.
+
+
+### SSBO size
+ * `ssbo _binding_ _size_`
+
+Sets the size of the SSBO at `binding` to `size`.
+
+
+### SSBO subdata
+ * `ssbo _binding_ subdata _type_ _offset_ _values_+`
+
+Sets the value of the buffer at `binding` and `offset`. The `type` is from the
+*Data Types* section below. The `values` must be a non-zero multiple of the
+requested `type`.
+
+
+### Patch Parameters
+ * `patch parameter vertices _count_`
+
+Sets the number of control points for tessellation patches to `count`. Defaults
+to 3.
+
+
+### Tolerance
+ * `tolerance tolerance0 [tolerance1 tolerance2 tolerance3]
+
+The `tolerance` command sets the amount of fuzzyness used when using the `~=`
+comparator. If a single tolerance value is set it is used for every comparison.
+If all four values are set then each `vecN` command will use the first `N`
+tolerance values. Each column of a `matMxN` will also use the first `N`
+tolerances. A tolerance maybe either a number or a percentage `0.01%`.
+
+
+### Clear Color
+ * `clear color _r_ _g_ _b_ _a_`
+
+Sets the clear color. Defaults to (0, 0, 0, 0).
+
+
+### Clear Depth
+ * `clear depth _value_`
+
+Sets the depth clear value. Defaults to 1.0.
+
+
+### Clear Stencil
+ * `clear stencil _value_`
+
+Sets the stencil clear value. Defaults to 0.0.
+
+
+### Clear
+ * `clear`
+
+Clears the framebuffer.
+
+### Pipeline Configuration
+There are a number of pipeline flags which can be set to alter execution. Each
+draw call uses the pipeline configuration that was specified prior to the draw
+call.
+
+The pipeline commands with their accepted data are:
+ * `primitiveRestartEnable <bool>`
+ * `depthClampEnable <bool>`
+ * `rasterizerDiscardEnable <bool>`
+ * `depthBiasEnable <bool>`
+ * `logicOpEnable <bool>`
+ * `blendEnable <bool>`
+ * `depthTestEnable <bool>`
+ * `depthWriteEnable <bool>`
+ * `depthBoundsTestEnable <bool>`
+ * `stencilTestEnable <bool>`
+ * `topology <VkPrimitiveTopology>`
+ * `polygonMode <VkPolygonMode>`
+ * `logicOp <VkLogicOp>`
+ * `frontFace <VkFrontFace>`
+ * `cullMode <VkCullMode>`
+ * `depthBiasConstantFactor <float>`
+ * `depthBiasClamp <float>`
+ * `depthBiasSlopeFactor <float>`
+ * `lineWidth <float>`
+ * `minDepthBounds <float>`
+ * `maxDepthBounds <float>`
+ * `srcColorBlendFactor <VkBlendFactor>`
+ * `dstColorBlendFactor <VkBlendFactor>`
+ * `srcAlphaBlendFactor <VkBlendFactor>`
+ * `dstAlphaBlendFactor <VkBlendFactor>`
+ * `colorBlendOp <VkBlendOp>`
+ * `alphaBlendOp <VkBlendOp>`
+ * `depthCompareOp <VkCompareOp>`
+ * `front.compareOp <VkCompareOp>`
+ * `back.compareOp <VkCompareOp>`
+ * `front.failOp <VkStencilOp>`
+ * `front.passOp <VkStencilOp>`
+ * `front.depthFailOp <VkStencilOp>`
+ * `back.failOp <VkStencilOp>`
+ * `back.passOp <VkStencilOp>`
+ * `back.depthFailOp <VkStencilOp>`
+ * `front.reference <uint32_t>`
+ * `back.reference <uint32_t>`
+ * `colorWriteMask <VkColorComponent bitmask>`
+
+#### Test Example
+```
+[test]
+clear color 1 0.4 0.5 0.2
+clear
+relative probe rect rgba (0.0, 0.0, 1.0, 1.0) (1.0, 0.4, 0.5, 0.2)
+```
+
+### Data Types
+ * int
+ * uint
+ * int8_t
+ * uint8_t
+ * int16_t
+ * uint16_t
+ * int64_t
+ * uint64_t
+ * float
+ * double
+ * vec
+ * vec[234]
+ * dvec
+ * dvec[234]
+ * ivec
+ * ivec[234]
+ * uvec
+ * uvec[234]
+ * i8vec
+ * i8vec[234]
+ * u8vec
+ * u8vec[234]
+ * i16vec
+ * i16vec[234]
+ * u16vec
+ * u16vec[234]
+ * i64vec
+ * i64vec[234]
+ * u64vec
+ * u64vec[234]
+ * mat
+ * mat[234]x[234]
+ * dmat
+ * dmat[234]x[234]
+
+### Topologies
+ * PATCH_LIST
+ * POINT_LIST
+ * GL_LINE_STRIP_ADJACENCY
+ * GL_LINE_STRIP
+ * GL_LINES
+ * GL_LINES_ADJACENCY
+ * GL_PATCHES
+ * GL_POINTS
+ * GL_TRIANGLE_STRIP
+ * GL_TRIANGLE_FAN
+ * GL_TRIANGLES
+ * GL_TRIANGLES_ADJACENCY
+ * GL_TRIANGLE_STRIP_ADJACENCY
+ * LINE_LIST
+ * LINE_LIST_WITH_ADJACENCY
+ * LINE_STRIP
+ * LINE_STRIP_WITH_ADJACENCY
+ * TRIANGLE_FAN
+ * TRIANGLE_LIST
+ * TRIANGLE_LIST_WITH_ADJACENCY
+ * TRIANGLE_STRIP
+ * TRIANGLE_STRIP_WITH_ADJACENCY
+
+
+### GL Types
+ * byte
+ * ubyte
+ * short
+ * ushort
+ * int
+ * uint
+ * half
+ * float
+ * double
+
+### GLSL Types
+ * int
+ * uint
+ * float
+ * double
+ * vec
+ * vec2
+ * vec3
+ * vec4
+ * dvec
+ * dvec2
+ * dvec3
+ * dvec4
+ * uvec
+ * uvec2
+ * uvec3
+ * uvec4
+ * ivec
+ * ivec2
+ * ivec3
+ * ivec4
+
+### Available Require Features
+  * robustBufferAccess
+  * fullDrawIndexUint32
+  * imageCubeArray
+  * independentBlend
+  * geometryShader
+  * tessellationShader
+  * sampleRateShading
+  * dualSrcBlend
+  * logicOp
+  * multiDrawIndirect
+  * drawIndirectFirstInstance
+  * depthClamp
+  * depthBiasClamp
+  * fillModeNonSolid
+  * depthBounds
+  * wideLines
+  * largePoints
+  * alphaToOne
+  * multiViewport
+  * samplerAnisotropy
+  * textureCompressionETC2
+  * textureCompressionASTC_LDR
+  * textureCompressionBC
+  * occlusionQueryPrecise
+  * pipelineStatisticsQuery
+  * vertexPipelineStoresAndAtomics
+  * fragmentStoresAndAtomics
+  * shaderTessellationAndGeometryPointSize
+  * shaderImageGatherExtended
+  * shaderStorageImageExtendedFormats
+  * shaderStorageImageMultisample
+  * shaderStorageImageReadWithoutFormat
+  * shaderStorageImageWriteWithoutFormat
+  * shaderUniformBufferArrayDynamicIndexing
+  * shaderSampledImageArrayDynamicIndexing
+  * shaderStorageBufferArrayDynamicIndexing
+  * shaderStorageImageArrayDynamicIndexing
+  * shaderClipDistance
+  * shaderCullDistance
+  * shaderFloat64
+  * shaderInt64
+  * shaderInt16
+  * shaderResourceResidency
+  * shaderResourceMinLod
+  * sparseBinding
+  * sparseResidencyBuffer
+  * sparseResidencyImage2D
+  * sparseResidencyImage3D
+  * sparseResidency2Samples
+  * sparseResidency4Samples
+  * sparseResidency8Samples
+  * sparseResidency16Samples
+  * sparseResidencyAliased
+  * variableMultisampleRate
+  * inheritedQueries
+
+### Image Formats
+  * A1R5G5B5_UNORM_PACK16
+  * A2B10G10R10_SINT_PACK32
+  * A2B10G10R10_SNORM_PACK32
+  * A2B10G10R10_SSCALED_PACK32
+  * A2B10G10R10_UINT_PACK32
+  * A2B10G10R10_UNORM_PACK32
+  * A2B10G10R10_USCALED_PACK32
+  * A2R10G10B10_SINT_PACK32
+  * A2R10G10B10_SNORM_PACK32
+  * A2R10G10B10_SSCALED_PACK32
+  * A2R10G10B10_UINT_PACK32
+  * A2R10G10B10_UNORM_PACK32
+  * A2R10G10B10_USCALED_PACK32
+  * A8B8G8R8_SINT_PACK32
+  * A8B8G8R8_SNORM_PACK32
+  * A8B8G8R8_SRGB_PACK32
+  * A8B8G8R8_SSCALED_PACK32
+  * A8B8G8R8_UINT_PACK32
+  * A8B8G8R8_UNORM_PACK32
+  * A8B8G8R8_USCALED_PACK32
+  * B10G11R11_UFLOAT_PACK32
+  * B4G4R4A4_UNORM_PACK16
+  * B5G5R5A1_UNORM_PACK16
+  * B5G6R5_UNORM_PACK16
+  * B8G8R8A8_SINT
+  * B8G8R8A8_SNORM
+  * B8G8R8A8_SRGB
+  * B8G8R8A8_SSCALED
+  * B8G8R8A8_UINT
+  * B8G8R8A8_UNORM
+  * B8G8R8A8_USCALED
+  * B8G8R8_SINT
+  * B8G8R8_SNORM
+  * B8G8R8_SRGB
+  * B8G8R8_SSCALED
+  * B8G8R8_UINT
+  * B8G8R8_UNORM
+  * B8G8R8_USCALED
+  * D16_UNORM
+  * D16_UNORM_S8_UINT
+  * D24_UNORM_S8_UINT
+  * D32_SFLOAT
+  * D32_SFLOAT_S8_UINT
+  * R16G16B16A16_SFLOAT
+  * R16G16B16A16_SINT
+  * R16G16B16A16_SNORM
+  * R16G16B16A16_SSCALED
+  * R16G16B16A16_UINT
+  * R16G16B16A16_UNORM
+  * R16G16B16A16_USCALED
+  * R16G16B16_SFLOAT
+  * R16G16B16_SINT
+  * R16G16B16_SNORM
+  * R16G16B16_SSCALED
+  * R16G16B16_UINT
+  * R16G16B16_UNORM
+  * R16G16B16_USCALED
+  * R16G16_SFLOAT
+  * R16G16_SINT
+  * R16G16_SNORM
+  * R16G16_SSCALED
+  * R16G16_UINT
+  * R16G16_UNORM
+  * R16G16_USCALED
+  * R16_SFLOAT
+  * R16_SINT
+  * R16_SNORM
+  * R16_SSCALED
+  * R16_UINT
+  * R16_UNORM
+  * R16_USCALED
+  * R32G32B32A32_SFLOAT
+  * R32G32B32A32_SINT
+  * R32G32B32A32_UINT
+  * R32G32B32_SFLOAT
+  * R32G32B32_SINT
+  * R32G32B32_UINT
+  * R32G32_SFLOAT
+  * R32G32_SINT
+  * R32G32_UINT
+  * R32_SFLOAT
+  * R32_SINT
+  * R32_UINT
+  * R4G4B4A4_UNORM_PACK16
+  * R4G4_UNORM_PACK8
+  * R5G5B5A1_UNORM_PACK16
+  * R5G6B5_UNORM_PACK16
+  * R64G64B64A64_SFLOAT
+  * R64G64B64A64_SINT
+  * R64G64B64A64_UINT
+  * R64G64B64_SFLOAT
+  * R64G64B64_SINT
+  * R64G64B64_UINT
+  * R64G64_SFLOAT
+  * R64G64_SINT
+  * R64G64_UINT
+  * R64_SFLOAT
+  * R64_SINT
+  * R64_UINT
+  * R8G8B8A8_SINT
+  * R8G8B8A8_SNORM
+  * R8G8B8A8_SRGB
+  * R8G8B8A8_SSCALED
+  * R8G8B8A8_UINT
+  * R8G8B8A8_UNORM
+  * R8G8B8A8_USCALED
+  * R8G8B8_SINT
+  * R8G8B8_SNORM
+  * R8G8B8_SRGB
+  * R8G8B8_SSCALED
+  * R8G8B8_UINT
+  * R8G8B8_UNORM
+  * R8G8B8_USCALED
+  * R8G8_SINT
+  * R8G8_SNORM
+  * R8G8_SRGB
+  * R8G8_SSCALED
+  * R8G8_UINT
+  * R8G8_UNORM
+  * R8G8_USCALED
+  * R8_SINT
+  * R8_SNORM
+  * R8_SRGB
+  * R8_SSCALED
+  * R8_UINT
+  * R8_UNORM
+  * R8_USCALED
+  * S8_UINT
+  * X8_D24_UNORM_PACK32
+
+1- https://github.com/Igalia/vkrunner/blob/d817f8b186cccebed89471580a685dc80a330946/README.md
diff --git a/docs/vulkan_resource_and_descriptor.md b/docs/vulkan_resource_and_descriptor.md
new file mode 100644
index 0000000..a8439da
--- /dev/null
+++ b/docs/vulkan_resource_and_descriptor.md
@@ -0,0 +1,66 @@
+# Classes for Vulkan resources and descriptors
+ * DRAFT
+
+Vulkan has many resource and descriptor types.
+Since it is complicated to manage them e.g.,
+create/allocate/map/read/write/destory, we create several classes to
+provide an abstraction. This document briefly explains those classes.
+
+
+### Resource class
+Represents a main resource i.e., VkBuffer or VkImage (See
+[Resources in Vulkan spec](
+https://www.khronos.org/registry/vulkan/specs/1.1/html/vkspec.html#resources))
+in GPU device and an additional VkBuffer to allow read/write to the
+main resource from CPU.
+
+If the main resource is accessible from CPU, the additional
+VkBuffer is not needed and it will be `VK_NULL_HANDLE`.
+Otherwise, the additional VkBuffer has the same size with the main
+resource and we must copy the main resource to the VkBuffer or
+copy the VkBuffer to the main resource when reading from/write to
+the main resource.
+
+The Resource class has Buffer and Image sub-classes.
+
+#### Buffer class
+Abstracts VkBuffer and creates/allocates/maps/destorys
+VkBuffer and VkBufferView resources.
+
+#### Image class
+Abstracts VkImage and creates/allocates/maps/destorys
+VkImage and VkImageView resources.
+
+
+### Sampler class
+ * TODO: Not implementated yet
+ * Represent [VkSampler](
+   https://www.khronos.org/registry/vulkan/specs/1.1/html/vkspec.html#samplers)
+
+
+### Descriptor class
+Represents [Descriptor Types](
+https://www.khronos.org/registry/vulkan/specs/1.1/html/vkspec.html#descriptorsets-types).
+There are 11 Descriptor Types and they need different resources.
+For example, a Combined Image Sampler needs both Image and
+Sampler objects while Storage Buffer needs only a Buffer object.
+
+* TODO: Describe 11 sub-classes of Descriptor for those Descriptor Types.
+
+
+### FrameBuffer class
+Abstracts [VkFrameBuffer](
+https://www.khronos.org/registry/vulkan/specs/1.1/html/vkspec.html#_framebuffers)
+for attachments and an Image for the FrameBuffer.
+The usage of the Image is `VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT`.
+
+
+### VertexBuffer class
+Manages vertices data and a Buffer whose usage is
+`VK_BUFFER_USAGE_VERTEX_BUFFER_BIT`.
+
+
+### IndexBuffer class
+ * TODO: Not implementated yet
+ * Manages indices data and a Buffer whose usage is
+   `VK_BUFFER_USAGE_INDEX_BUFFER_BIT`.