Add a section about coordinate spaces to spatial.rst

Author: tetrapod00

tutorials/shaders/shader_reference/spatial_shader.rst

@@ -507,3 +507,89 @@ If you want the lights to add together, add the light contribution to ``DIFFUSE_
     materials from appearing in screen-space reflections or refraction.
     :ref:`SDFGI <doc_using_sdfgi>` sharp reflections are not visible on transparent
     materials (only rough reflections are visible on transparent materials).
+
+
+
+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". Called "object space" in             |
+|                               | other renderers. Equivalent to the local coordinates used by Transform3D.              |
++-------------------------------+----------------------------------------------------------------------------------------+
+| World space                   | Equivalent to the global coordinates used by Transform3D.                              |
+|                               |                                                                                        |
++-------------------------------+----------------------------------------------------------------------------------------+
+| View space                    | Coordinate space relative to the camera.                                               | 
+|                               | Called "camera space" or "eye space" in other renderers.                               |
++-------------------------------+----------------------------------------------------------------------------------------+
+| Clip space                    | TODO                                                                                   |
++-------------------------------+----------------------------------------------------------------------------------------+
+| Screen space                  | TODO                                                                                   |
++-------------------------------+----------------------------------------------------------------------------------------+
+| Normalized device coordinates | Final coordinates expected by the renderer. Usually not used directly. Values          |
+|                               | range from                                                                             |
+|                               | ``-1.0`` to ``1.0``, with ``(-1.0,-1.0)`` being the upper-left corner of the screen,   |
+|                               | and ``(1.0,1.0)`` the lower right.                                                     |
++-------------------------------+----------------------------------------------------------------------------------------+
+
+.. note::
+
+    Godot 4.3 introduced a change to clip space. If you are using a shader that uses clips space directly and was 
+    originally written for an earlier version, see `<https://godotengine.org/article/introducing-reverse-z/>`.
+    
+
+
+You don't need to know much matrix math in order to use coordinate spaces. You can convert vectors between different coordinate spaces by using the built-in transform matrices. 
+
+To transform a *position* vector ``VERTEX`` from view space to world space, multiply it by 
+the view-to-world matrix ``INV_VIEW_MATRIX``:
+
+.. code-block:: glsl
+
+    void fragment() {
+        vec3 position_world = (INV_VIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
+    }
+
+To transform a *direction* vector, such as ``NORMAL``, change the ``z`` field of the vec4 to ``0.0`` : 
+
+.. code-block:: glsl
+
+    void fragment() {
+        vec3 normal_world = (INV_VIEW_MATRIX * vec4(NORMAL, 0.0)).xyz;
+    }
+
+You can also compose multiple transformations together. To transform ``VERTEX`` from model space to view space, first 
+transform it to world space, then to view space. Note the order of the matrices:
+
+.. code-block:: glsl
+
+    void vertex() {
+        vec3 position_view = (VIEW_MATRIX * MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
+    }
+
+You can transform to one coordinate space, do some operations, and transform back. This snippet scales ``VERTEX`` in model space, 
+translates it in world space, then transforms back into model space, so it can be passed to ``fragment()``.
+
+.. code-block:: glsl
+
+ void vertex() {
+        VERTEX *= 2.0;
+        vec3 position_world = (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
+        position_world += vec3(1.0);
+        VERTEX = (inverse(MODEL_MATRIX) * vec4(position_world, 1.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
+    }    
+