Add a section about coordinate spaces to spatial.rst

Author: tetrapod00

tutorials/shaders/shader_reference/spatial_shader.rst

@@ -83,6 +83,51 @@ Render modes
 | **fog_disabled**              | Disable receiving depth-based or volumetric fog. Useful for blend_add materials like particles.      |
 +-------------------------------+------------------------------------------------------------------------------------------------------+
 
+Coordinate spaces
+^^^^^^^^^^^^^^^^^
+
+Spatial shaders do their work across multiple coordinate spaces. Some built-in variables with the same name are in different
+coordinate spaces in different processor functions.
+
++-------------------------------+----------------------------------------------------------------------------------------+
+| Coordinate space              | Description                                                                            |
++===============================+========================================================================================+
+| Model space                   | Also called "local space" or "local coordinates".                                      |
+|                               | Same as local coordinates of Transform3D.                                              |
++-------------------------------+----------------------------------------------------------------------------------------+
+| World space                   | Same as global coordinates of Transform3D.                                             |
+|                               |                                                                                        |
++-------------------------------+----------------------------------------------------------------------------------------+
+| View space                    |                                                                                        |
++-------------------------------+----------------------------------------------------------------------------------------+
+| Clip space                    |                                                                                        |
++-------------------------------+----------------------------------------------------------------------------------------+
+| Screen space                  |                                                                                        |
++-------------------------------+----------------------------------------------------------------------------------------+
+| Normalized device coordinates |                                                                                        |
++-------------------------------+----------------------------------------------------------------------------------------+
+
+You can convert between different coordinate spaces by using the built-in transform matrices. For example, in the fragment shader,
+both ``VERTEX`` and ``NORMAL`` are in view space by default. You can convert them to world space by multiplying them by
+``INV_VIEW_MATRIX``. When transforming a *position* vector, the `z` value should be `1.0`. When transforming a direction
+vector, the `z` value should be `0.0`.
+
+.. code-block:: glsl
+
+    void fragment() {
+        vec3 position_world = (INV_VIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
+        vec3 normal_world = (INV_VIEW_MATRIX * vec4(NORMAL, 0.0)).xyz;
+    }
+
+TODO add a sentence about screen space and NDC.
+
+.. code-block:: glsl
+
+    void convert_to_screenspace() {
+        TODO add the to and from NDC snippets here
+    }    
+
+
 Built-ins
 ^^^^^^^^^