[doc] Add some documentation around translations.
This CL adds the start of a document listing how things translate into
various backends.
Change-Id: Iebeb4488450b4f299e83d0de7ee124b441795e98
Reviewed-on: https://dawn-review.googlesource.com/c/tint/+/31240
Reviewed-by: David Neto <dneto@google.com>
Commit-Queue: dan sinclair <dsinclair@chromium.org>
diff --git a/docs/translations.md b/docs/translations.md
new file mode 100644
index 0000000..05f917e
--- /dev/null
+++ b/docs/translations.md
@@ -0,0 +1,157 @@
+# Translations
+
+This document attempts to document how WGSL translates into the various backends
+for the cases where the translation is not a direct mapping.
+
+# Access Control
+
+## HLSL
+ * ReadOnly -> `ByteAddressBuffer`
+ * ReadWrite -> `RWByteAddressBuffer`
+
+## MSL
+ * ReadOnly -> `const`
+
+## SPIR-V
+There are two ways this can be achieved in SPIR-V. Either the variable can be
+decorated with `NonWritable` or each member of the struct can be decorated with
+`NonWritable`. We chose to go the struct member route.
+ * The read-only becomes part of the type in this case. Otherwise, you are
+ treating the readonly type information as part of the variable which is
+ confusing.
+ * Treating the readonly as part of the variable means we should be
+ deduplicating the types behind the access control, which causes confusing
+ with the type_names and various tracking systems within Tint.
+
+
+# Builtin Decorations
+Name | SPIR-V | MSL | HLSL
+=====|========|=====|=====
+position | SpvBuiltInPosition |position | SV_Position
+vertex_idx | SpvBuiltInVertexIndex |vertex_id | SV_VertexID
+instance_idx | SpvBuiltInInstanceIndex | instance_id| SV_InstanceID
+front_facing | SpvBuiltInFrontFacing | front_facing | SV_IsFrontFacing
+frag_coord | SpvBuiltInFragCoord | position | SV_Position
+frag_depth | SpvBuiltInFragDepth | depth(any) | SV_Depth
+local_invocation_id | SpvBuiltInLocalInvocationId | thread_position_in_threadgroup | SV_GroupThreadID
+local_invocation_idx | SpvBuiltInLocalInvocationIndex | thread_index_in_threadgroup | SV_GroupIndex
+global_invocation_id | SpvBuiltInGlobalInvocationId | thread_position_in_grid | SV_DispatchThreadID
+
+
+# Builtins Methods
+Name | SPIR-V | MSL | HLSL
+=====|========|=====|======
+abs | GLSLstd450FAbs or GLSLstd450SAbs| fabs or abs | abs
+acos | GLSLstd450Acos | acos | acos
+all | SpvOpAll | all | all
+any | SpvOpAny | any | any
+arrayLength | SpvOpArrayLength | |
+asin | GLSLstd450Asin | asin | asin
+atan | GLSLstd450Atan | atan | atan
+atan2 | GLSLstd450Atan2| atan2 | atan2
+ceil | GLSLstd450Ceil| ceil | ceil
+clamp | GLSLstd450NClamp or GLSLstd450UClamp or GLSLstd450SClamp| clamp | clamp
+cos | GLSLstd450Cos | cos | cos
+cosh | GLSLstd450Cosh | cosh | cosh
+countOneBits | SpvOpBitCount | popcount | countbits
+cross | GLSLstd450Cross | cross | cross
+determinant | GLSLstd450Determinant | determinant | determinant
+distance | GLSLstd450Distance | distance | distance
+dot | SpOpDot | dot | dot
+dpdx | SpvOpDPdx | dpdx | ddx
+dpdxCoarse | SpvOpDPdxCoarse | dpdx | ddx_coarse
+dpdxFine | SpvOpDPdxFine | dpdx | ddx_fine
+dpdy | SpvOpDPdy | dpdy | ddy
+dpdyCoarse | SpvOpDPdyCoarse | dpdy | ddy_coarse
+dpdyFine | SpvOpDPdyFine | dpdy | ddy_fine
+exp | GLSLstd450Exp | exp | exp
+exp2 | GLSLstd450Exp2 | exp2 | exp2
+faceForward | GLSLstd450FaceForward | faceforward | faceforward
+floor | GLSLstd450Floor | floor | floor
+fma | GLSLstd450Fma | fma | fma
+fract | GLSLstd450Fract | fract | frac
+frexp | GLSLstd450Frexp | |
+fwidth | SpvOpFwidth | fwidth | fwidth
+fwidthCoarse | SpvOpFwidthCoarse | fwidth | fwidth
+fwidthFine | SpvOpFwidthFine | fwidth | fwidth
+inverseSqrt | GLSLstd450InverseSqrt | rsqrt | rsqrt
+isFinite | | isfinite | isfinite
+isInf | SpvOpIsInf | isinf | isinf
+isNan | SpvOpIsNan | isnan | isnan
+isNormal | | isnormal |
+ldexp | GLSLstd450Ldexp | |
+length | GLSLstd450Length | length | length
+log | GLSLstd450Log | log | log
+log2 | GLSLstd450Log2 | log2 | log2
+max | GLSLstd450NMax or GLSLstd450SMax or GLSLstd450UMax | fmax or max | max
+min | GLSLstd450NMin or GLSLstd450SMin or GLSLstd450UMin | fmin or min | min
+mix | GLSLstd450FMix | mix | mix
+modf | GLSLstd450Modf | |
+normalize | GLSLstd450Normalize | normalize | normalize
+outerProduct | SpvOpOuterProduct | |
+pow | GLSLstd450Pow | pow | pow
+reflect | GLSLstd450Reflect | reflect | reflect
+reverseBits | SpvOpBitReverse | reverse_bits | reversebits
+round | GLSLstd450Round | round | round
+select | SpvOpSelect | select |
+sign | GLSLstd450FSign | sign | sign
+sin | GLSLstd450Sin | sin | sin
+sinh | GLSLstd450Sinh | sinh | sinh
+smoothStep | GLSLstd450SmoothStep | smoothstep | smoothstep
+sqrt | GLSLstd450Sqrt | sqrt | sqrt
+step | GLSLstd450Step | step | step
+tan | GLSLstd450Tan | tan | tan
+tanh | GLSLstd450Tanh | tanh | tanh
+trunc | GLSLstd450Trunc | trunc | trunc
+
+# Short-circuting
+## HLSL
+TODO(dsinclair): Nested if's
+
+## SPIR-V
+TODO(dsinclair): Nested if's
+
+# Storage classes
+TODO(dsinclair): do ...
+
+# Storage buffers
+## HLSL
+TODO(dsinclair): Rewriting of accessors to loads
+
+# Loop blocks
+## HLSL
+TODO(dsinclair): Rewrite with bools
+
+## MSL
+TODO(dsinclair): Rewrite with bools
+
+# Input / Output storage class
+## HLSL
+TODO(dsinclair): Structs and params
+
+## MSL
+TODO(dsinclair): Structs and params
+
+# Discard
+## HLSL
+ * `discard`
+
+## MSL
+ * `discard_fragment()`
+
+
+# Specialization constants
+## HLSL
+```
+#ifndef WGSL_SPEC_CONSTANT_<id>
+-- if default provided
+#define WGSL_SPEC_CONSTANT_<id> default value
+-- else
+#error spec constant required for constant id
+--
+#endif
+static const <type> <name> = WGSL_SPEC_CONSTANT_<id>
+```
+
+## MSL
+`[[function_constant(<id>)]]`
