Merge pull request #9746 from tetrapod00/spatial-style-pass

Style consistency pass on Spatial, Fog, CanvasItem, Sky, Particle shader pages

tutorials/shaders/shader_reference/canvas_item_shader.rst

@@ -6,9 +6,9 @@ CanvasItem shaders
 CanvasItem shaders are used to draw all 2D elements in Godot. These include
 all nodes that inherit from CanvasItems, and all GUI elements.
 
-CanvasItem shaders contain less built-in variables and functionality than Spatial
-shaders, but they maintain the same basic structure with vertex, fragment, and
-light processor functions.
+CanvasItem shaders contain fewer built-in variables and functionality than 
+:ref:`Spatial shaders<doc_spatial_shader>`, but they maintain the same basic structure 
+with vertex, fragment, and light processor functions.
 
 Render modes
 ^^^^^^^^^^^^
@@ -32,18 +32,18 @@ Render modes
 +---------------------------------+----------------------------------------------------------------------+
 | **light_only**                  | Only draw on light pass.                                             |
 +---------------------------------+----------------------------------------------------------------------+
-| **skip_vertex_transform**       | VERTEX needs to be transformed manually in vertex function.          |
+| **skip_vertex_transform**       | ``VERTEX`` needs to be transformed manually in the ``vertex()``      |
+|                                 | function.                                                            |
 +---------------------------------+----------------------------------------------------------------------+
-| **world_vertex_coords**         | VERTEX is modified in world coordinates instead of local.            |
+| **world_vertex_coords**         | ``VERTEX`` is modified in world coordinates instead of local.        |
 +---------------------------------+----------------------------------------------------------------------+
 
 Built-ins
 ^^^^^^^^^
 
-Values marked as "in" are read-only. Values marked as "out" are for optional writing and will
-not necessarily contain sensible values. Values marked as "inout" provide a sensible default
-value, and can optionally be written to. Samplers are not subjects of writing and they are
-not marked.
+Values marked as ``in`` are read-only. Values marked as ``out`` can optionally be written to and will
+not necessarily contain sensible values. Values marked as ``inout`` provide a sensible default
+value, and can optionally be written to. Samplers cannot be written to so they are not marked.
 
 Global built-ins
 ^^^^^^^^^^^^^^^^
@@ -53,7 +53,7 @@ Global built-ins are available everywhere, including custom functions.
 +-------------------+-----------------------------------------------------------------------------------------+
 | Built-in          | Description                                                                             |
 +===================+=========================================================================================+
-| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every 3,600      |
+| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every ``3,600``  |
 |                   | seconds (which can  be changed with the                                                 |
 |                   | :ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>`|
 |                   | setting). It's not affected by :ref:`time_scale<class_Engine_property_time_scale>` or   |
@@ -62,7 +62,7 @@ Global built-ins are available everywhere, including custom functions.
 |                   | frame.                                                                                  |      
 +-------------------+-----------------------------------------------------------------------------------------+
 | in float **PI**   | A ``PI`` constant (``3.141592``).                                                       |
-|                   | A ration of circle's circumference to its diameter and amount of radians in half turn.  |
+|                   | A ratio of a circle's circumference to its diameter and amount of radians in half turn. |
 +-------------------+-----------------------------------------------------------------------------------------+
 | in float **TAU**  | A ``TAU`` constant (``6.283185``).                                                      |
 |                   | An equivalent of ``PI * 2`` and amount of radians in full turn.                         |
@@ -90,13 +90,13 @@ happen later) and do it manually with the following code:
         VERTEX = (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0)).xy;
     }
 
-Other built-ins, such as UV and COLOR, are also passed through to the fragment function if not modified.
+Other built-ins, such as ``UV`` and ``COLOR``, are also passed through to the ``fragment()`` function if not modified.
 
-For instancing, the INSTANCE_CUSTOM variable contains the instance custom data. When using particles, this information
+For instancing, the ``INSTANCE_CUSTOM`` variable contains the instance custom data. When using particles, this information
 is usually:
 
 * **x**: Rotation angle in radians.
-* **y**: Phase during lifetime (0 to 1).
+* **y**: Phase during lifetime (``0.0`` to ``1.0``).
 * **z**: Animation frame.
 
 +--------------------------------+----------------------------------------------------+
@@ -107,11 +107,12 @@ is usually:
 +--------------------------------+----------------------------------------------------+
 | in mat4 **CANVAS_MATRIX**      | World space to canvas space transform. In canvas   |
 |                                | space the origin is the upper-left corner of the   |
-|                                | screen and coordinates ranging from (0, 0) to      |
-|                                | viewport size.                                     |
+|                                | screen and coordinates ranging from ``(0.0, 0.0)`` |
+|                                | to viewport size.                                  |
 +--------------------------------+----------------------------------------------------+
 | in mat4 **SCREEN_MATRIX**      | Canvas space to clip space. In clip space          |
-|                                | coordinates ranging from (-1, -1) to (1, 1).       |
+|                                | coordinates ranging from ``(-1.0, -1.0)`` to       |
+|                                | ``(1.0, 1.0).``                                    |
 +--------------------------------+----------------------------------------------------+
 | in int  **INSTANCE_ID**        | Instance ID for instancing.                        |
 +--------------------------------+----------------------------------------------------+
@@ -123,12 +124,13 @@ is usually:
 |                                | For a Sprite2D with a texture of size 64x32px,     |
 |                                | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)``      |
 +--------------------------------+----------------------------------------------------+
-| inout vec2 **VERTEX**          | Vertex, in local space.                            |
+| inout vec2 **VERTEX**          | Vertex position, in local space.                   |
 +--------------------------------+----------------------------------------------------+
 | in int **VERTEX_ID**           | The index of the current vertex in the vertex      |
 |                                | buffer.                                            |
 +--------------------------------+----------------------------------------------------+
-| inout vec2 **UV**              | Normalized texture coordinates. Range from 0 to 1. |
+| inout vec2 **UV**              | Normalized texture coordinates. Range from ``0.0`` |
+|                                | to ``1.0``.                                        |
 +--------------------------------+----------------------------------------------------+
 | inout vec4 **COLOR**           | Color from vertex primitive.                       |
 +--------------------------------+----------------------------------------------------+
@@ -143,7 +145,7 @@ Fragment built-ins
 ^^^^^^^^^^^^^^^^^^
 
 Certain Nodes (for example, :ref:`Sprite2Ds <class_Sprite2D>`) display a texture
-by default. However, when a custom fragment function is attached to these nodes,
+by default. However, when a custom ``fragment()`` function is attached to these nodes,
 the texture lookup needs to be done manually. Godot provides the texture color
 in the ``COLOR`` built-in variable multiplied by the node's color. To read the
 texture color by itself, you can use:
@@ -155,17 +157,18 @@ texture color by itself, you can use:
 Similarly, if a normal map is used in the :ref:`CanvasTexture <class_CanvasTexture>`, Godot uses
 it by default and assigns its value to the built-in ``NORMAL`` variable. If you are using a normal
 map meant for use in 3D, it will appear inverted. In order to use it in your shader, you must assign
-it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D and overwriting ``NORMAL``.
+it to the ``NORMAL_MAP`` property. Godot will handle converting it for use in 2D and overwriting ``NORMAL``.
 
 .. code-block:: glsl
 
-  NORMALMAP = texture(NORMAL_TEXTURE, UV).rgb;
+  NORMAL_MAP = texture(NORMAL_TEXTURE, UV).rgb;
 
 +---------------------------------------------+---------------------------------------------------------------+
 | Built-in                                    | Description                                                   |
 +=============================================+===============================================================+
 | in vec4 **FRAGCOORD**                       | Coordinate of pixel center. In screen space. ``xy`` specifies |
-|                                             | position in window. Origin is upper-left.                     |
+|                                             | position in viewport. Upper-left of the viewport is the       |
+|                                             | origin, ``(0.0, 0.0)``.                                       |
 +---------------------------------------------+---------------------------------------------------------------+
 | in vec2 **SCREEN_PIXEL_SIZE**               | Size of individual pixels. Equal to inverse of resolution.    |
 +---------------------------------------------+---------------------------------------------------------------+
@@ -183,21 +186,21 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D
 +---------------------------------------------+---------------------------------------------------------------+
 | in vec4 **SPECULAR_SHININESS**              | Specular shininess color, as sampled from the texture.        |
 +---------------------------------------------+---------------------------------------------------------------+
-| in vec2 **UV**                              | UV from vertex function.                                      |
+| in vec2 **UV**                              | UV from the ``vertex()`` function.                            |
 +---------------------------------------------+---------------------------------------------------------------+
 | in vec2 **SCREEN_UV**                       | Screen UV coordinate for current pixel.                       |
 +---------------------------------------------+---------------------------------------------------------------+
 | sampler2D **SCREEN_TEXTURE**                | Removed in Godot 4. Use a ``sampler2D`` with                  |
 |                                             | ``hint_screen_texture`` instead.                              |
 +---------------------------------------------+---------------------------------------------------------------+
-| inout vec3 **NORMAL**                       | Normal read from **NORMAL_TEXTURE**. Writable.                |
+| inout vec3 **NORMAL**                       | Normal read from ``NORMAL_TEXTURE``. Writable.                |
 +---------------------------------------------+---------------------------------------------------------------+
 | sampler2D **NORMAL_TEXTURE**                | Default 2D normal texture.                                    |
 +---------------------------------------------+---------------------------------------------------------------+
 | out vec3 **NORMAL_MAP**                     | Configures normal maps meant for 3D for use in 2D. If used,   |
-|                                             | overrides **NORMAL**.                                         |
+|                                             | overrides ``NORMAL``.                                         |
 +---------------------------------------------+---------------------------------------------------------------+
-| out float **NORMAL_MAP_DEPTH**              | Normalmap depth for scaling.                                  |
+| out float **NORMAL_MAP_DEPTH**              | Normal map depth for scaling.                                 |
 +---------------------------------------------+---------------------------------------------------------------+
 | inout vec2 **VERTEX**                       | Pixel position in screen space.                               |
 +---------------------------------------------+---------------------------------------------------------------+
@@ -206,8 +209,8 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D
 | inout vec3 **LIGHT_VERTEX**                 | Same as ``VERTEX`` but can be written to alter lighting.      |
 |                                             | Z component represents height.                                |
 +---------------------------------------------+---------------------------------------------------------------+
-| inout vec4 **COLOR**                        | Color from vertex function multiplied by the **TEXTURE**      |
-|                                             | color. Also output color value.                               |
+| inout vec4 **COLOR**                        | Color from the ``vertex()`` function multiplied by the        |
+|                                             | ``TEXTURE`` color. Also output color value.                   |
 +---------------------------------------------+---------------------------------------------------------------+
 
 Light built-ins
@@ -217,12 +220,12 @@ Light processor functions work differently in Godot 4.x than they did in Godot
 3.x. In Godot 4.x all lighting is done during the regular draw pass. In other
 words, Godot no longer draws the object again for each light.
 
-Use render_mode ``unshaded`` if you do not want the light processor function to
-run. Use render_mode ``light_only`` if you only want to see the impact of
+Use the ``unshaded`` render mode if you do not want the ``light()`` function to
+run. Use the ``light_only`` render mode if you only want to see the impact of
 lighting on an object; this can be useful when you only want the object visible
 where it is covered by light.
 
-If you define a light function it will replace the built in light function,
+If you define a ``light()`` function it will replace the built in light function,
 even if your light function is empty.
 
 Below is an example of a light shader that takes a CanvasItem's normal map into account:
@@ -238,38 +241,43 @@ Below is an example of a light shader that takes a CanvasItem's normal map into
 | Built-in                         | Description                                                                  |
 +==================================+==============================================================================+
 | in vec4 **FRAGCOORD**            | Coordinate of pixel center. In screen space. ``xy`` specifies                |
-|                                  | position in window. Origin is lower-left.                                    |
+|                                  | position in viewport. Upper-left of the viewport is the origin,              |
+|                                  | ``(0.0, 0.0)``.                                                              |
 +----------------------------------+------------------------------------------------------------------------------+
-| in vec3 **NORMAL**               | Input Normal.                                                                |
+| in vec3 **NORMAL**               | Input normal.                                                                |
 +----------------------------------+------------------------------------------------------------------------------+
-| in vec4 **COLOR**                | Input Color. This is the output of the fragment function.                    |
+| in vec4 **COLOR**                | Input color. This is the output of the ``fragment()`` function.              |
 +----------------------------------+------------------------------------------------------------------------------+
-| in vec2 **UV**                   | UV from vertex function, equivalent to the UV in the fragment function.      |
+| in vec2 **UV**                   | UV from the ``vertex()`` function, equivalent to the UV in the               |
+|                                  | ``fragment()`` function.                                                     |
 +----------------------------------+------------------------------------------------------------------------------+
 | sampler2D **TEXTURE**            | Current texture in use for CanvasItem.                                       |
 +----------------------------------+------------------------------------------------------------------------------+
-| in vec2 **TEXTURE_PIXEL_SIZE**   | Normalized pixel size of **TEXTURE**.                                        |
-|                                  | For a Sprite2D with a **TEXTURE** of size 64x32px,                           |
+| in vec2 **TEXTURE_PIXEL_SIZE**   | Normalized pixel size of ``TEXTURE``.                                        |
+|                                  | For a Sprite2D with a ``TEXTURE`` of size ``64x32`` pixels,                  |
 |                                  | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)``                                |
 +----------------------------------+------------------------------------------------------------------------------+
 | in vec2 **SCREEN_UV**            | Screen UV coordinate for current pixel.                                      |
 +----------------------------------+------------------------------------------------------------------------------+
 | in vec2 **POINT_COORD**          | UV for Point Sprite.                                                         |
 +----------------------------------+------------------------------------------------------------------------------+
-| in vec4 **LIGHT_COLOR**          | Color of Light multiplied by Light's texture.                                |
+| in vec4 **LIGHT_COLOR**          | :ref:`Color<class_Light2D_property_color>` of the :ref:`class_Light2D`.      |
+|                                  | If the light is a :ref:`class_PointLight2D`, multiplied by the light's       |
+|                                  | :ref:`texture<class_PointLight2D_property_texture>`.                         |
 +----------------------------------+------------------------------------------------------------------------------+
-| in float **LIGHT_ENERGY**        | Energy multiplier of Light.                                                  |
+| in float **LIGHT_ENERGY**        | :ref:`Energy multiplier<class_Light2D_property_energy>` of the               |
+|                                  | :ref:`class_Light2D`.                                                        |
 +----------------------------------+------------------------------------------------------------------------------+
-| in vec3 **LIGHT_POSITION**       | Position of Light in screen space. If using a ``DirectionalLight2D``         |
-|                                  | this is always ``vec3(0,0,0)``.                                              |
+| in vec3 **LIGHT_POSITION**       | Position of the :ref:`class_Light2D` in screen space. If using a             |
+|                                  | :ref:`class_DirectionalLight2D` this is always ``(0.0, 0.0, 0.0)``.          |
 +----------------------------------+------------------------------------------------------------------------------+
-| in vec3 **LIGHT_DIRECTION**      | Direction of Light in screen space.                                          |
+| in vec3 **LIGHT_DIRECTION**      | Direction of the :ref:`class_Light2D` in screen space.                       |
 +----------------------------------+------------------------------------------------------------------------------+
-| in bool **LIGHT_IS_DIRECTIONAL** | ``true`` if this pass is a ``DirectionalLight2D``.                           |
+| in bool **LIGHT_IS_DIRECTIONAL** | ``true`` if this pass is a :ref:`class_DirectionalLight2D`.                  |
 +----------------------------------+------------------------------------------------------------------------------+
-| in vec3 **LIGHT_VERTEX**         | Pixel position, in screen space as modified in the fragment function.        |
+| in vec3 **LIGHT_VERTEX**         | Pixel position, in screen space as modified in the ``fragment()`` function.  |
 +----------------------------------+------------------------------------------------------------------------------+
-| inout vec4 **LIGHT**             | Output color for this Light.                                                 |
+| inout vec4 **LIGHT**             | Output color for this :ref:`class_Light2D`.                                  |
 +----------------------------------+------------------------------------------------------------------------------+
 | in vec4 **SPECULAR_SHININESS**   | Specular shininess, as set in the object's texture.                          |
 +----------------------------------+------------------------------------------------------------------------------+
@@ -280,8 +288,8 @@ SDF functions
 ^^^^^^^^^^^^^
 
 There are a few additional functions implemented to sample an automatically
-generated Signed Distance Field texture. These functions available for Fragment
-and Light functions of CanvasItem shaders.
+generated Signed Distance Field texture. These functions available for the ``fragment()``
+and ``light()`` functions of CanvasItem shaders.
 
 The signed distance field is generated from :ref:`class_LightOccluder2D` nodes
 present in the scene with the **SDF Collision** property enabled (which is the

tutorials/shaders/shader_reference/fog_shader.rst

@@ -21,10 +21,9 @@ touch a given :ref:`FogVolume <class_FogVolume>` will still be used.
 Built-ins
 ^^^^^^^^^
 
-Values marked as "in" are read-only. Values marked as "out" are for optional
-writing and will not necessarily contain sensible values. Samplers cannot be
-written to so they are not marked.
-
+Values marked as ``in`` are read-only. Values marked as ``out`` can optionally 
+be written to and will not necessarily contain sensible values. Samplers cannot 
+be written to so they are not marked.
 
 Global built-ins
 ^^^^^^^^^^^^^^^^
@@ -35,7 +34,7 @@ Global built-ins are available everywhere, including in custom functions.
 +---------------------------------+-----------------------------------------------------------------------------------------+
 | Built-in                        | Description                                                                             |
 +=================================+=========================================================================================+
-| in float **TIME**               | Global time since the engine has started, in seconds. It repeats after every 3,600      |
+| in float **TIME**               | Global time since the engine has started, in seconds. It repeats after every ``3,600``  |
 |                                 | seconds (which can  be changed with the                                                 |
 |                                 | :ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>`|
 |                                 | setting). It's not affected by :ref:`time_scale<class_Engine_property_time_scale>` or   |
@@ -67,7 +66,7 @@ be drawn at once.
 +-------------------------------+-------------------------------------------------------------------------------------------------+
 | in vec3 **OBJECT_POSITION**   | Position of the center of the current :ref:`FogVolume <class_FogVolume>` in world space.        |
 +-------------------------------+-------------------------------------------------------------------------------------------------+
-| in vec3 **UVW**               | 3-dimensional uv, used to map a 3D texture to the current :ref:`FogVolume <class_FogVolume>`.   |
+| in vec3 **UVW**               | 3-dimensional UV, used to map a 3D texture to the current :ref:`FogVolume <class_FogVolume>`.   |
 +-------------------------------+-------------------------------------------------------------------------------------------------+
 | in vec3 **SIZE**              | Size of the current :ref:`FogVolume <class_FogVolume>` when its                                 |
 |                               | :ref:`shape<class_FogVolume_property_shape>` has a size.                                        |

tutorials/shaders/shader_reference/particle_shader.rst

@@ -10,8 +10,8 @@ or Spatial, depending on whether they are 2D or 3D.
 
 Particle shaders are unique because they are not used to draw the object itself;
 they are used to calculate particle properties, which are then used by a
-CanvasItem or Spatial shader. They contain two processor functions: ``start()``
-and ``process()``.
+:ref:`CanvasItem<doc_canvas_item_shader>` or :ref:`Spatial<doc_spatial_shader>` 
+shader. They contain two processor functions: ``start()`` and ``process()``.
 
 Unlike other shader types, particle shaders keep the data that was output the
 previous frame. Therefore, particle shaders can be used for complex effects that
@@ -37,7 +37,7 @@ Render modes
 +--------------------------+-------------------------------------------+
 | **disable_force**        | Disable attractor force.                  |
 +--------------------------+-------------------------------------------+
-| **disable_velocity**     | Ignore **VELOCITY** value.                |
+| **disable_velocity**     | Ignore ``VELOCITY`` value.                |
 +--------------------------+-------------------------------------------+
 | **collision_use_scale**  | Scale the particle's size for collisions. |
 +--------------------------+-------------------------------------------+
@@ -45,10 +45,9 @@ Render modes
 Built-ins
 ^^^^^^^^^
 
-Values marked as "in" are read-only. Values marked as "out" are for optional writing and will
-not necessarily contain sensible values. Values marked as "inout" provide a sensible default
-value, and can optionally be written to. Samplers are not subjects of writing and they are
-not marked.
+Values marked as ``in`` are read-only. Values marked as ``out`` can optionally be written to and will
+not necessarily contain sensible values. Values marked as ``inout`` provide a sensible default
+value, and can optionally be written to. Samplers cannot be written to so they are not marked.
 
 Global built-ins
 ^^^^^^^^^^^^^^^^
@@ -58,7 +57,7 @@ Global built-ins are available everywhere, including custom functions.
 +-------------------+-----------------------------------------------------------------------------------------+
 | Built-in          | Description                                                                             |
 +===================+=========================================================================================+
-| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every 3,600      |
+| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every ``3,600``  |
 |                   | seconds (which can  be changed with the                                                 |
 |                   | :ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>`|
 |                   | setting). It's not affected by :ref:`time_scale<class_Engine_property_time_scale>` or   |
@@ -67,7 +66,7 @@ Global built-ins are available everywhere, including custom functions.
 |                   | frame.                                                                                  | 
 +-------------------+-----------------------------------------------------------------------------------------+
 | in float **PI**   | A ``PI`` constant (``3.141592``).                                                       |
-|                   | A ration of circle's circumference to its diameter and amount of radians in half turn.  |
+|                   | A ratio of a circle's circumference to its diameter and amount of radians in half turn. |
 +-------------------+-----------------------------------------------------------------------------------------+
 | in float **TAU**  | A ``TAU`` constant (``6.283185``).                                                      |
 |                   | An equivalent of ``PI * 2`` and amount of radians in full turn.                         |
@@ -103,28 +102,30 @@ These properties can be accessed from both the ``start()`` and ``process()`` fun
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | inout mat4 **TRANSFORM**           | Particle transform.                                                                                                                     |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| inout vec4 **CUSTOM**              | Custom particle data. Accessible from shader of mesh as **INSTANCE_CUSTOM**.                                                            |
+| inout vec4 **CUSTOM**              | Custom particle data. Accessible from shader of mesh as ``INSTANCE_CUSTOM``.                                                            |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | inout float **MASS**               | Particle mass, intended to be used with attractors. Equals ``1.0`` by default.                                                          |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | in vec4 **USERDATAX**              | Vector that enables the integration of supplementary user-defined data into the particle process shader.                                |
-|                                    | ``USERDATAX`` are six built-ins identified by number, ``X`` can be numbers between 1 and 6.                                             |
+|                                    | ``USERDATAX`` are six built-ins identified by number, ``X`` can be numbers between 1 and 6, for example ``USERDATA3``.                  |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| in uint **FLAG_EMIT_POSITION**     | A flag for using on the last argument of ``emit_subparticle`` function to assign a position to a new particle's transform.              |
+| in uint **FLAG_EMIT_POSITION**     | A flag for using on the last argument of ``emit_subparticle()`` function to assign a position to a new particle's transform.            |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| in uint **FLAG_EMIT_ROT_SCALE**    | A flag for using on the last argument of ``emit_subparticle`` function to assign the rotation and scale to a new particle's transform.  |
+| in uint **FLAG_EMIT_ROT_SCALE**    | A flag for using on the last argument of ``emit_subparticle()`` function to assign the rotation and scale to a new particle's transform.|
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| in uint **FLAG_EMIT_VELOCITY**     | A flag for using on the last argument of ``emit_subparticle`` function to assign a velocity to a new particle.                          |
+| in uint **FLAG_EMIT_VELOCITY**     | A flag for using on the last argument of ``emit_subparticle()`` function to assign a velocity to a new particle.                        |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| in uint **FLAG_EMIT_COLOR**        | A flag for using on the last argument of ``emit_subparticle`` function to assign a color to a new particle.                             |
+| in uint **FLAG_EMIT_COLOR**        | A flag for using on the last argument of ``emit_subparticle()`` function to assign a color to a new particle.                           |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| in uint **FLAG_EMIT_CUSTOM**       | A flag for using on the last argument of ``emit_subparticle`` function to assign a custom data vector to a new particle.                |
+| in uint **FLAG_EMIT_CUSTOM**       | A flag for using on the last argument of ``emit_subparticle()`` function to assign a custom data vector to a new particle.              |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| in vec3 **EMITTER_VELOCITY**       | Velocity of the Particles node.                                                                                                         |
+| in vec3 **EMITTER_VELOCITY**       | Velocity of the :ref:`Particles2D<class_GPUParticles2D>` (:ref:`3D<class_GPUParticles3D>`) node.                                        |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| in float **INTERPOLATE_TO_END**    | Value of ``interp_to_end`` property of Particles node.                                                                                  |
+| in float **INTERPOLATE_TO_END**    | Value of :ref:`interp_to_end<class_GPUParticles2D_property_interp_to_end>`                                                              |
+|                                    | (:ref:`3D<class_GPUParticles3D_property_interp_to_end>`) property of Particles node.                                                    |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| in uint **AMOUNT_RATIO**           | Value of ``amount_ratio`` property of Particles node.                                                                                   |
+| in uint **AMOUNT_RATIO**           | Value of :ref:`amount_ratio<class_GPUParticles2D_property_amount_ratio>`                                                                |
+|                                    | (:ref:`3D<class_GPUParticles3D_property_amount_ratio>`) property of Particles node.                                                     |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 
 .. note:: In order to use the ``COLOR`` variable in a StandardMaterial3D, set ``vertex_color_use_as_albedo``
@@ -150,24 +151,24 @@ Start built-ins
 Process built-ins
 ^^^^^^^^^^^^^^^^^
 
-+------------------------------------+-----------------------------------------------------------------------------------------------------+
-| Built-in                           | Description                                                                                         |
-+====================================+=====================================================================================================+
-| in bool **RESTART**                | ``true`` if the current process frame is first for the particle.                                    |
-+------------------------------------+-----------------------------------------------------------------------------------------------------+
-| in bool **COLLIDED**               | ``true`` when the particle has collided with a particle collider.                                   |
-+------------------------------------+-----------------------------------------------------------------------------------------------------+
-| in vec3 **COLLISION_NORMAL**       | A normal of the last collision. If there is no collision detected it is equal to ``vec3(0.0)``.     |
-+------------------------------------+-----------------------------------------------------------------------------------------------------+
-| in float **COLLISION_DEPTH**       | A length of normal of the last collision. If there is no collision detected it is equal to ``0.0``. |
-+------------------------------------+-----------------------------------------------------------------------------------------------------+
-| in vec3 **ATTRACTOR_FORCE**        | A combined force of the attractors at the moment on that particle.                                  |
-+------------------------------------+-----------------------------------------------------------------------------------------------------+
++------------------------------------+-------------------------------------------------------------------------------------------------------+
+| Built-in                           | Description                                                                                           |
++====================================+=======================================================================================================+
+| in bool **RESTART**                | ``true`` if the current process frame is first for the particle.                                      |
++------------------------------------+-------------------------------------------------------------------------------------------------------+
+| in bool **COLLIDED**               | ``true`` when the particle has collided with a particle collider.                                     |
++------------------------------------+-------------------------------------------------------------------------------------------------------+
+| in vec3 **COLLISION_NORMAL**       | A normal of the last collision. If there is no collision detected it is equal to ``(0.0, 0.0, 0.0)``. |
++------------------------------------+-------------------------------------------------------------------------------------------------------+
+| in float **COLLISION_DEPTH**       | A length of normal of the last collision. If there is no collision detected it is equal to ``0.0``.   |
++------------------------------------+-------------------------------------------------------------------------------------------------------+
+| in vec3 **ATTRACTOR_FORCE**        | A combined force of the attractors at the moment on that particle.                                    |
++------------------------------------+-------------------------------------------------------------------------------------------------------+
 
 Process functions
 ^^^^^^^^^^^^^^^^^
 
-``emit_subparticle`` is currently the only custom function supported by
+``emit_subparticle()`` is currently the only custom function supported by
 particles shaders. It allows users to add a new particle with specified
 parameters from a sub-emitter. The newly created particle will only use the
 properties that match the ``flags`` parameter. For example, the

tutorials/shaders/shader_reference/sky_shader.rst

@@ -62,7 +62,7 @@ the radiance cubemap:
 Try to avoid updating the radiance cubemap needlessly. If you do need to
 update the radiance cubemap each frame, make sure your
 :ref:`Sky process mode <class_Sky_property_process_mode>` is set to
-:ref:`REALTIME <class_Sky_constant_PROCESS_MODE_REALTIME>`.
+:ref:`PROCESS_MODE_REALTIME <class_Sky_constant_PROCESS_MODE_REALTIME>`.
 
 Note that the :ref:`process mode <class_Sky_property_process_mode>` only
 affects the rendering of the radiance cubemap. The visible sky is always
@@ -139,9 +139,9 @@ a lower resolution than the rest of the sky:
 Built-ins
 ^^^^^^^^^
 
-Values marked as "in" are read-only. Values marked as "out" are for optional
-writing and will not necessarily contain sensible values. Samplers cannot be
-written to so they are not marked.
+Values marked as ``in`` are read-only. Values marked as ``out`` can optionally 
+be written to and will not necessarily contain sensible values. Samplers cannot 
+be written to so they are not marked.
 
 Global built-ins
 ^^^^^^^^^^^^^^^^
@@ -154,7 +154,7 @@ There are 4 ``LIGHTX`` lights, accessed as ``LIGHT0``, ``LIGHT1``, ``LIGHT2``, a
 +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
 | Built-in                        | Description                                                                                                              |
 +=================================+==========================================================================================================================+
-| in float **TIME**               | Global time since the engine has started, in seconds. It repeats after every 3,600                                       |
+| in float **TIME**               | Global time since the engine has started, in seconds. It repeats after every ``3,600``                                   |
 |                                 | seconds (which can  be changed with the                                                                                  |
 |                                 | :ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>`                                 |
 |                                 | setting). It's not affected by :ref:`time_scale<class_Engine_property_time_scale>` or                                    |
@@ -162,17 +162,17 @@ There are 4 ``LIGHTX`` lights, accessed as ``LIGHT0``, ``LIGHT1``, ``LIGHT2``, a
 |                                 | :ref:`global shader uniform<doc_shading_language_global_uniforms>` and update it each                                    |
 |                                 | frame.                                                                                                                   |                          
 +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
-| in vec3 **POSITION**            | Camera position in world space                                                                                           |
+| in vec3 **POSITION**            | Camera position, in world space.                                                                                         |
 +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
 | samplerCube **RADIANCE**        | Radiance cubemap. Can only be read from during background pass. Check ``!AT_CUBEMAP_PASS`` before using.                 |
 +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
-| in bool **AT_HALF_RES_PASS**    | Currently rendering to half resolution pass.                                                                             |
+| in bool **AT_HALF_RES_PASS**    | ``true`` when rendering to half resolution pass.                                                                         |
 +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
-| in bool **AT_QUARTER_RES_PASS** | Currently rendering to quarter resolution pass.                                                                          |
+| in bool **AT_QUARTER_RES_PASS** | ``true`` when rendering to quarter resolution pass.                                                                      |
 +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
-| in bool **AT_CUBEMAP_PASS**     | Currently rendering to radiance cubemap.                                                                                 |
+| in bool **AT_CUBEMAP_PASS**     | ``true`` when rendering to radiance cubemap.                                                                             |
 +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
-| in bool **LIGHTX_ENABLED**      | ``LightX`` is visible and in the scene. If ``false``, other light properties may be garbage.                             |
+| in bool **LIGHTX_ENABLED**      | ``true`` if ``LIGHTX`` is visible and in the scene. If ``false``, other light properties may be garbage.                 |
 +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
 | in float **LIGHTX_ENERGY**      | Energy multiplier for ``LIGHTX``.                                                                                        |
 +---------------------------------+--------------------------------------------------------------------------------------------------------------------------+

tutorials/shaders/shader_reference/spatial_shader.rst

@@ -10,6 +10,7 @@ write vertex, fragment, and light processor functions to affect how objects are
 
 Render modes
 ^^^^^^^^^^^^
+For visual examples of these render modes, see :ref:`Standard Material 3D and ORM Material 3D<doc_standard_material_3d>`.
 
 +-------------------------------+------------------------------------------------------------------------------------------------------+
 | Render mode                   | Description                                                                                          |
@@ -58,9 +59,9 @@ Render modes
 +-------------------------------+------------------------------------------------------------------------------------------------------+
 | **specular_disabled**         | Disable specular.                                                                                    |
 +-------------------------------+------------------------------------------------------------------------------------------------------+
-| **skip_vertex_transform**     | VERTEX/NORMAL/etc. need to be transformed manually in vertex function.                               |
+| **skip_vertex_transform**     | ``VERTEX``/``NORMAL``/etc. need to be transformed manually in the ``vertex()`` function.             |
 +-------------------------------+------------------------------------------------------------------------------------------------------+
-| **world_vertex_coords**       | VERTEX/NORMAL/etc. are modified in world coordinates instead of local.                               |
+| **world_vertex_coords**       | ``VERTEX``/``NORMAL``/etc. are modified in world space instead of model space.                       |
 +-------------------------------+------------------------------------------------------------------------------------------------------+
 | **ensure_correct_normals**    | Use when non-uniform scale is applied to mesh.                                                       |
 +-------------------------------+------------------------------------------------------------------------------------------------------+
@@ -86,10 +87,9 @@ Render modes
 Built-ins
 ^^^^^^^^^
 
-Values marked as "in" are read-only. Values marked as "out" are for optional writing and will
-not necessarily contain sensible values. Values marked as "inout" provide a sensible default
-value, and can optionally be written to. Samplers are not subjects of writing and they are
-not marked.
+Values marked as ``in`` are read-only. Values marked as ``out`` can optionally be written to and will
+not necessarily contain sensible values. Values marked as ``inout`` provide a sensible default
+value, and can optionally be written to. Samplers cannot be written to so they are not marked.
 
 Global built-ins
 ^^^^^^^^^^^^^^^^
@@ -99,7 +99,7 @@ Global built-ins are available everywhere, including custom functions.
 +-------------------+-----------------------------------------------------------------------------------------+
 | Built-in          | Description                                                                             |
 +===================+=========================================================================================+
-| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every 3,600      |
+| in float **TIME** | Global time since the engine has started, in seconds. It repeats after every ``3,600``  |
 |                   | seconds (which can  be changed with the                                                 |
 |                   | :ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>`|
 |                   | setting). It's not affected by :ref:`time_scale<class_Engine_property_time_scale>` or   |
@@ -108,7 +108,7 @@ Global built-ins are available everywhere, including custom functions.
 |                   | frame.                                                                                  | 
 +-------------------+-----------------------------------------------------------------------------------------+
 | in float **PI**   | A ``PI`` constant (``3.141592``).                                                       |
-|                   | A ration of circle's circumference to its diameter and amount of radians in half turn.  |
+|                   | A ratio of a circle's circumference to its diameter and amount of radians in half turn. |
 +-------------------+-----------------------------------------------------------------------------------------+
 | in float **TAU**  | A ``TAU`` constant (``6.283185``).                                                      |
 |                   | An equivalent of ``PI * 2`` and amount of radians in full turn.                         |
@@ -119,11 +119,11 @@ Global built-ins are available everywhere, including custom functions.
 Vertex built-ins
 ^^^^^^^^^^^^^^^^
 
-Vertex data (``VERTEX``, ``NORMAL``, ``TANGENT``, ``BITANGENT``) are presented in local
-model space. If not written to, these values will not be modified and be passed through
-as they came.
+Vertex data (``VERTEX``, ``NORMAL``, ``TANGENT``, ``BITANGENT``) are presented in model space
+(also called local space). If not written to, these values will not be modified and be 
+passed through as they came.
 
-They can optionally be presented in world space by using the *world_vertex_coords* render mode.
+They can optionally be presented in world space by using the ``world_vertex_coords`` render mode.
 
 Users can disable the built-in modelview transform (projection will still happen later) and do
 it manually with the following code:
@@ -140,18 +140,18 @@ it manually with the following code:
         TANGENT = normalize((MODELVIEW_MATRIX * vec4(TANGENT, 0.0)).xyz);
     }
 
-Other built-ins, such as UV, UV2 and COLOR, are also passed through to the fragment function if not modified.
+Other built-ins, such as ``UV``, ``UV2``, and ``COLOR``, are also passed through to the ``fragment()`` function if not modified.
 
 Users can override the modelview and projection transforms using the ``POSITION`` built-in. If ``POSITION`` is written
 to anywhere in the shader, it will always be used, so the user becomes responsible for ensuring that it always has
 an acceptable value. When ``POSITION`` is used, the value from ``VERTEX`` is ignored and projection does not happen.
 However, the value passed to the fragment shader still comes from ``VERTEX``.
 
-For instancing, the INSTANCE_CUSTOM variable contains the instance custom data. When using particles, this information
+For instancing, the ``INSTANCE_CUSTOM`` variable contains the instance custom data. When using particles, this information
 is usually:
 
 * **x**: Rotation angle in radians.
-* **y**: Phase during lifetime (0 to 1).
+* **y**: Phase during lifetime (``0.0`` to ``1.0``).
 * **z**: Animation frame.
 
 This allows you to easily adjust the shader to a particle system using default particles material. When writing a custom particle
@@ -171,13 +171,13 @@ shader, this value can be used as desired.
 +----------------------------------------+--------------------------------------------------------+
 | in mat4 **INV_PROJECTION_MATRIX**      | Clip space to view space transform.                    |
 +----------------------------------------+--------------------------------------------------------+
-| in vec3 **NODE_POSITION_WORLD**        | Node world space position.                             |
+| in vec3 **NODE_POSITION_WORLD**        | Node position, in world space.                         |
 +----------------------------------------+--------------------------------------------------------+
-| in vec3 **NODE_POSITION_VIEW**         | Node view space position.                              |
+| in vec3 **NODE_POSITION_VIEW**         | Node position, in view space.                          |
 +----------------------------------------+--------------------------------------------------------+
-| in vec3 **CAMERA_POSITION_WORLD**      | Camera world space position.                           |
+| in vec3 **CAMERA_POSITION_WORLD**      | Camera position, in world space.                       |
 +----------------------------------------+--------------------------------------------------------+
-| in vec3 **CAMERA_DIRECTION_WORLD**     | Camera world space direction.                          |
+| in vec3 **CAMERA_DIRECTION_WORLD**     | Camera direction, in world space.                      |
 +----------------------------------------+--------------------------------------------------------+
 | in uint **CAMERA_VISIBLE_LAYERS**      | Cull layers of the camera rendering the current pass.  |
 +----------------------------------------+--------------------------------------------------------+
@@ -200,15 +200,15 @@ shader, this value can be used as desired.
 | in vec3 **EYE_OFFSET**                 | Position offset for the eye being rendered.            |
 |                                        | Only applicable for multiview rendering.               |
 +----------------------------------------+--------------------------------------------------------+
-| inout vec3 **VERTEX**                  | Vertex in local coordinates.                           |
+| inout vec3 **VERTEX**                  | Vertex position in model space.                        |
 +----------------------------------------+--------------------------------------------------------+
 | in int **VERTEX_ID**                   | The index of the current vertex in the vertex buffer.  |
 +----------------------------------------+--------------------------------------------------------+
-| inout vec3 **NORMAL**                  | Normal in local coordinates.                           |
+| inout vec3 **NORMAL**                  | Normal in model space.                                 |
 +----------------------------------------+--------------------------------------------------------+
-| inout vec3 **TANGENT**                 | Tangent in local coordinates.                          |
+| inout vec3 **TANGENT**                 | Tangent in model space.                                |
 +----------------------------------------+--------------------------------------------------------+
-| inout vec3 **BINORMAL**                | Binormal in local coordinates.                         |
+| inout vec3 **BINORMAL**                | Binormal in model space.                               |
 +----------------------------------------+--------------------------------------------------------+
 | out vec4 **POSITION**                  | If written to, overrides final vertex position.        |
 +----------------------------------------+--------------------------------------------------------+
@@ -222,11 +222,12 @@ shader, this value can be used as desired.
 +----------------------------------------+--------------------------------------------------------+
 | inout float **POINT_SIZE**             | Point size for point rendering.                        |
 +----------------------------------------+--------------------------------------------------------+
-| inout mat4 **MODELVIEW_MATRIX**        | Model space to view space transform (use if possible). |
+| inout mat4 **MODELVIEW_MATRIX**        | Model/local space to view space transform              |
+|                                        | (use if possible).                                     |
 +----------------------------------------+--------------------------------------------------------+
 | inout mat3 **MODELVIEW_NORMAL_MATRIX** |                                                        |
 +----------------------------------------+--------------------------------------------------------+
-| in mat4 **MODEL_MATRIX**               | Model space to world space transform.                  |
+| in mat4 **MODEL_MATRIX**               | Model/local space to world space transform.            |
 +----------------------------------------+--------------------------------------------------------+
 | in mat3 **MODEL_NORMAL_MATRIX**        |                                                        |
 +----------------------------------------+--------------------------------------------------------+
@@ -254,7 +255,7 @@ shader, this value can be used as desired.
 
 .. note::
 
-    ``INV_VIEW_MATRIX`` is the matrix used for rendering the object in that pass, not like ``MAIN_CAM_INV_VIEW_MATRIX``, which is the matrix of the camera in the scene. In the shadow pass, ``INV_VIEW_MATRIX``'s view is based on the camera that is located at the position of the light.
+    ``INV_VIEW_MATRIX`` is the matrix used for rendering the object in that pass, unlike ``MAIN_CAM_INV_VIEW_MATRIX``, which is the matrix of the camera in the scene. In the shadow pass, ``INV_VIEW_MATRIX``'s view is based on the camera that is located at the position of the light.
 
 Fragment built-ins
 ^^^^^^^^^^^^^^^^^^
@@ -276,18 +277,18 @@ these properties, and if you don't write to them, Godot will optimize away the c
 | in vec3 **VIEW**                       | Normalized vector from fragment position to camera (in view space). This is the same for both    |
 |                                        | perspective and orthogonal cameras.                                                              |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| in vec2 **UV**                         | UV that comes from vertex function.                                                              |
+| in vec2 **UV**                         | UV that comes from the ``vertex()`` function.                                                    |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| in vec2 **UV2**                        | UV2 that comes from vertex function.                                                             |
+| in vec2 **UV2**                        | UV2 that comes from the ``vertex()`` function.                                                   |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| in vec4 **COLOR**                      | COLOR that comes from vertex function.                                                           |
+| in vec4 **COLOR**                      | COLOR that comes from the ``vertex()`` function.                                                 |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| in vec2 **POINT_COORD**                | Point Coordinate for drawing points with POINT_SIZE.                                             |
+| in vec2 **POINT_COORD**                | Point coordinate for drawing points with ``POINT_SIZE``.                                         |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
 | in bool **OUTPUT_IS_SRGB**             | ``true`` when output is in sRGB color space (this is ``true`` in the Compatibility renderer,     |
 |                                        | ``false`` in Forward+ and Forward Mobile).                                                       |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| in mat4 **MODEL_MATRIX**               | Model space to world space transform.                                                            |
+| in mat4 **MODEL_MATRIX**               | Model/local space to world space transform.                                                      |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
 | in mat3 **MODEL_NORMAL_MATRIX**        |                                                                                                  |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
@@ -309,7 +310,7 @@ these properties, and if you don't write to them, Godot will optimize away the c
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
 | in uint **CAMERA_VISIBLE_LAYERS**      | Cull layers of the camera rendering the current pass.                                            |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| in vec3 **VERTEX**                     | Vertex that comes from vertex function (default, in view space).                                 |
+| in vec3 **VERTEX**                     | Vertex position that comes from the ``vertex()`` function (default, in view space).              |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
 | inout vec3 **LIGHT_VERTEX**            | A writable version of ``VERTEX`` that can be used to alter light and shadows. Writing to this    |
 |                                        | will not change the position of the fragment.                                                    |
@@ -330,23 +331,24 @@ these properties, and if you don't write to them, Godot will optimize away the c
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
 | sampler2D **DEPTH_TEXTURE**            | Removed in Godot 4. Use a ``sampler2D`` with ``hint_depth_texture`` instead.                     |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out float **DEPTH**                    | Custom depth value (0..1). If ``DEPTH`` is being written to in any shader branch, then you are   |
-|                                        | responsible for setting the ``DEPTH`` for **all** other branches. Otherwise, the graphics API    |
-|                                        | will leave them uninitialized.                                                                   |
+| out float **DEPTH**                    | Custom depth value (range of ``[0.0, 1.0]``). If ``DEPTH`` is being written to in any shader     |
+|                                        | branch, then you are responsible for setting the ``DEPTH`` for **all** other branches.           |
+|                                        | Otherwise, the graphics API will leave them uninitialized.                                       |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| inout vec3 **NORMAL**                  | Normal that comes from vertex function (default, in view space).                                 |
+| inout vec3 **NORMAL**                  | Normal that comes from the ``vertex()`` function (default, in view space).                       |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| inout vec3 **TANGENT**                 | Tangent that comes from vertex function.                                                         |
+| inout vec3 **TANGENT**                 | Tangent that comes from the ``vertex()`` function (default, in view space).                      |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| inout vec3 **BINORMAL**                | Binormal that comes from vertex function.                                                        |
+| inout vec3 **BINORMAL**                | Binormal that comes from the ``vertex()`` function (default, in view space).                     |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out vec3 **NORMAL_MAP**                | Set normal here if reading normal from a texture instead of NORMAL.                              |
+| out vec3 **NORMAL_MAP**                | Set normal here if reading normal from a texture instead of ``NORMAL``.                          |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out float **NORMAL_MAP_DEPTH**         | Depth from variable above. Defaults to 1.0.                                                      |
+| out float **NORMAL_MAP_DEPTH**         | Depth from ``NORMAL_MAP``. Defaults to ``1.0``.                                                  |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out vec3 **ALBEDO**                    | Albedo (default white).                                                                          |
+| out vec3 **ALBEDO**                    | Albedo (default white). Base color.                                                              |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out float **ALPHA**                    | Alpha (0..1); if read from or written to, the material will go to the transparent pipeline.      |
+| out float **ALPHA**                    | Alpha (range of ``[0.0, 1.0]``). If read from or written to, the material will go to the         |
+|                                        | transparent pipeline.                                                                            |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
 | out float **ALPHA_SCISSOR_THRESHOLD**  | If written to, values below a certain amount of alpha are discarded.                             |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
@@ -356,15 +358,15 @@ these properties, and if you don't write to them, Godot will optimize away the c
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
 | out vec2 **ALPHA_TEXTURE_COORDINATE**  |                                                                                                  |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out float **METALLIC**                 | Metallic (0..1).                                                                                 |
+| out float **METALLIC**                 | Metallic (range of ``[0.0, 1.0]``).                                                              |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out float **SPECULAR**                 | Specular. Defaults to 0.5, best not to modify unless you want to change IOR.                     |
+| out float **SPECULAR**                 | Specular. Defaults to ``0.5``, best not to modify unless you want to change IOR.                 |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out float **ROUGHNESS**                | Roughness (0..1).                                                                                |
+| out float **ROUGHNESS**                | Roughness (range of ``[0.0, 1.0]``).                                                             |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out float **RIM**                      | Rim (0..1). If used, Godot calculates rim lighting.                                              |
+| out float **RIM**                      | Rim (range of ``[0.0, 1.0]``). If used, Godot calculates rim lighting.                           |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out float **RIM_TINT**                 | Rim Tint, goes from 0 (white) to 1 (albedo). If used, Godot calculates rim lighting.             |
+| out float **RIM_TINT**                 | Rim Tint, range of ``0.0`` (white) to ``1.0`` (albedo). If used, Godot calculates rim lighting.  |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
 | out float **CLEARCOAT**                | Small added specular blob. If used, Godot calculates Clearcoat.                                  |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
@@ -386,15 +388,16 @@ these properties, and if you don't write to them, Godot will optimize away the c
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
 | out float **AO**                       | Strength of Ambient Occlusion. For use with pre-baked AO.                                        |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out float **AO_LIGHT_AFFECT**          | How much AO affects lights (0..1; default 0).                                                    |
+| out float **AO_LIGHT_AFFECT**          | How much AO affects lights (range of ``[0.0, 1.0]``, default ``0.0``).                           |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out vec3 **EMISSION**                  | Emission color (can go over 1,1,1 for HDR).                                                      |
+| out vec3 **EMISSION**                  | Emission color (can go over ``(1.0, 1.0, 1.0)`` for HDR).                                        |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out vec4 **FOG**                       | If written to, blends final pixel color with FOG.rgb based on FOG.a.                             |
+| out vec4 **FOG**                       | If written to, blends final pixel color with ``FOG.rgb`` based on ``FOG.a``.                     |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out vec4 **RADIANCE**                  | If written to, blends environment map radiance with RADIANCE.rgb based on RADIANCE.a.            |
+| out vec4 **RADIANCE**                  | If written to, blends environment map radiance with ``RADIANCE.rgb`` based on ``RADIANCE.a``.    |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
-| out vec4 **IRRADIANCE**                | If written to, blends environment map IRRADIANCE with IRRADIANCE.rgb based on IRRADIANCE.a.      |
+| out vec4 **IRRADIANCE**                | If written to, blends environment map irradiance with ``IRRADIANCE.rgb`` based on                |
+|                                        | ``IRRADIANCE.a``.                                                                                |
 +----------------------------------------+--------------------------------------------------------------------------------------------------+
 
 .. note::
@@ -407,15 +410,13 @@ these properties, and if you don't write to them, Godot will optimize away the c
 Light built-ins
 ^^^^^^^^^^^^^^^
 
-Writing light processor functions is completely optional. You can skip the light function by setting
-render_mode to ``unshaded``. If no light function is written, Godot will use the material
-properties written to in the fragment function to calculate the lighting for you (subject to
-the render_mode).
+Writing light processor functions is completely optional. You can skip the ``light()`` function by using
+the ``unshaded`` render mode. If no light function is written, Godot will use the material properties 
+written to in the ``fragment()`` function to calculate the lighting for you (subject to the render mode).
 
-The light function is called for every light in every pixel. It is called within a loop for
-each light type.
+The ``light()`` function is called for every light in every pixel. It is called within a loop for each light type.
 
-Below is an example of a custom light function using a Lambertian lighting model:
+Below is an example of a custom ``light()`` function using a Lambertian lighting model:
 
 .. code-block:: glsl
 
@@ -427,73 +428,73 @@ If you want the lights to add together, add the light contribution to ``DIFFUSE_
 
 .. warning::
 
-    The ``light()`` function won't be run if the ``vertex_lighting`` render mode
-    is enabled, or if
-    **Rendering > Quality > Shading > Force Vertex Shading** is enabled in the
-    Project Settings. (It's enabled by default on mobile platforms.)
-
-+-----------------------------------+----------------------------------------------------+
-| Built-in                          | Description                                        |
-+===================================+====================================================+
-| in vec2 **VIEWPORT_SIZE**         | Size of viewport (in pixels).                      |
-+-----------------------------------+----------------------------------------------------+
-| in vec4 **FRAGCOORD**             | Coordinate of pixel center in screen space.        |
-|                                   | ``xy`` specifies position in window, ``z``         |
-|                                   | specifies fragment depth if ``DEPTH`` is not used. |
-|                                   | Origin is lower-left.                              |
-+-----------------------------------+----------------------------------------------------+
-| in mat4 **MODEL_MATRIX**          | Model space to world space transform.              |
-+-----------------------------------+----------------------------------------------------+
-| in mat4 **INV_VIEW_MATRIX**       | View space to world space transform.               |
-+-----------------------------------+----------------------------------------------------+
-| in mat4 **VIEW_MATRIX**           | World space to view space transform.               |
-+-----------------------------------+----------------------------------------------------+
-| in mat4 **PROJECTION_MATRIX**     | View space to clip space transform.                |
-+-----------------------------------+----------------------------------------------------+
-| in mat4 **INV_PROJECTION_MATRIX** | Clip space to view space transform.                |
-+-----------------------------------+----------------------------------------------------+
-| in vec3 **NORMAL**                | Normal vector, in view space.                      |
-+-----------------------------------+----------------------------------------------------+
-| in vec2 **UV**                    | UV that comes from vertex function.                |
-+-----------------------------------+----------------------------------------------------+
-| in vec2 **UV2**                   | UV2 that comes from vertex function.               |
-+-----------------------------------+----------------------------------------------------+
-| in vec3 **VIEW**                  | View vector, in view space.                        |
-+-----------------------------------+----------------------------------------------------+
-| in vec3 **LIGHT**                 | Light Vector, in view space.                       |
-+-----------------------------------+----------------------------------------------------+
-| in vec3 **LIGHT_COLOR**           | Color of light multiplied by ``energy * PI``.      |
-|                                   | The ``PI`` multiplication is present because       |
-|                                   | physically-based lighting models include a         |
-|                                   | division by ``PI``.                                |
-+-----------------------------------+----------------------------------------------------+
-| in float **SPECULAR_AMOUNT**      | 2.0 * ``light_specular`` property for              |
-|                                   | ``OmniLight3D`` and ``SpotLight3D``.               |
-|                                   | 1.0 for ``DirectionalLight3D``.                    |
-+-----------------------------------+----------------------------------------------------+
-| in bool **LIGHT_IS_DIRECTIONAL**  | ``true`` if this pass is a ``DirectionalLight3D``. |
-+-----------------------------------+----------------------------------------------------+
-| in float **ATTENUATION**          | Attenuation based on distance or shadow.           |
-+-----------------------------------+----------------------------------------------------+
-| in vec3 **ALBEDO**                | Base albedo.                                       |
-+-----------------------------------+----------------------------------------------------+
-| in vec3 **BACKLIGHT**             |                                                    |
-+-----------------------------------+----------------------------------------------------+
-| in float **METALLIC**             | Metallic.                                          |
-+-----------------------------------+----------------------------------------------------+
-| in float **ROUGHNESS**            | Roughness.                                         |
-+-----------------------------------+----------------------------------------------------+
-| in bool **OUTPUT_IS_SRGB**        | ``true`` when output is in sRGB color space        |
-|                                   | (this is ``true`` in the Compatibility renderer,   |
-|                                   | ``false`` in Forward+ and Forward Mobile).         |
-+-----------------------------------+----------------------------------------------------+
-| out vec3 **DIFFUSE_LIGHT**        | Diffuse light result.                              |
-+-----------------------------------+----------------------------------------------------+
-| out vec3 **SPECULAR_LIGHT**       | Specular light result.                             |
-+-----------------------------------+----------------------------------------------------+
-| out float **ALPHA**               | Alpha (0..1); if written to, the material will go  |
-|                                   | to the transparent pipeline.                       |
-+-----------------------------------+----------------------------------------------------+
+    The ``light()`` function won't be run if the ``vertex_lighting`` render mode is enabled, or if 
+    :ref:`Rendering > Quality > Shading > Force Vertex Shading<class_ProjectSettings_property_rendering/shading/overrides/force_vertex_shading>`
+    is enabled in the Project Settings. (It's enabled by default on mobile platforms.)
+
++-----------------------------------+------------------------------------------------------------------------+
+| Built-in                          | Description                                                            |
++===================================+========================================================================+
+| in vec2 **VIEWPORT_SIZE**         | Size of viewport (in pixels).                                          |
++-----------------------------------+------------------------------------------------------------------------+
+| in vec4 **FRAGCOORD**             | Coordinate of pixel center in screen space.                            |
+|                                   | ``xy`` specifies position in window, ``z``                             |
+|                                   | specifies fragment depth if ``DEPTH`` is not used.                     |
+|                                   | Origin is lower-left.                                                  |
++-----------------------------------+------------------------------------------------------------------------+
+| in mat4 **MODEL_MATRIX**          | Model/local space to world space transform.                            |
++-----------------------------------+------------------------------------------------------------------------+
+| in mat4 **INV_VIEW_MATRIX**       | View space to world space transform.                                   |
++-----------------------------------+------------------------------------------------------------------------+
+| in mat4 **VIEW_MATRIX**           | World space to view space transform.                                   |
++-----------------------------------+------------------------------------------------------------------------+
+| in mat4 **PROJECTION_MATRIX**     | View space to clip space transform.                                    |
++-----------------------------------+------------------------------------------------------------------------+
+| in mat4 **INV_PROJECTION_MATRIX** | Clip space to view space transform.                                    |
++-----------------------------------+------------------------------------------------------------------------+
+| in vec3 **NORMAL**                | Normal vector, in view space.                                          |
++-----------------------------------+------------------------------------------------------------------------+
+| in vec2 **UV**                    | UV that comes from the ``vertex()`` function.                          |
++-----------------------------------+------------------------------------------------------------------------+
+| in vec2 **UV2**                   | UV2 that comes from the ``vertex()`` function.                         |
++-----------------------------------+------------------------------------------------------------------------+
+| in vec3 **VIEW**                  | View vector, in view space.                                            |
++-----------------------------------+------------------------------------------------------------------------+
+| in vec3 **LIGHT**                 | Light vector, in view space.                                           |
++-----------------------------------+------------------------------------------------------------------------+
+| in vec3 **LIGHT_COLOR**           | :ref:`Light color<class_Light3D_property_light_color>` multiplied by   |
+|                                   | :ref:`light energy<class_Light3D_property_light_energy>` multiplied by |
+|                                   | ``PI``. The ``PI`` multiplication is present because                   |
+|                                   | physically-based lighting models include a division by ``PI``.         |
++-----------------------------------+------------------------------------------------------------------------+
+| in float **SPECULAR_AMOUNT**      | For :ref:`class_OmniLight3D` and :ref:`class_SpotLight3D`,             |
+|                                   | ``2.0`` multiplied by                                                  |
+|                                   | :ref:`light_specular<class_Light3D_property_light_specular>`.          |
+|                                   | For :ref:`class_DirectionalLight3D`, ``1.0``.                          |
++-----------------------------------+------------------------------------------------------------------------+
+| in bool **LIGHT_IS_DIRECTIONAL**  | ``true`` if this pass is a :ref:`class_DirectionalLight3D`.            |
++-----------------------------------+------------------------------------------------------------------------+
+| in float **ATTENUATION**          | Attenuation based on distance or shadow.                               |
++-----------------------------------+------------------------------------------------------------------------+
+| in vec3 **ALBEDO**                | Base albedo.                                                           |
++-----------------------------------+------------------------------------------------------------------------+
+| in vec3 **BACKLIGHT**             |                                                                        |
++-----------------------------------+------------------------------------------------------------------------+
+| in float **METALLIC**             | Metallic.                                                              |
++-----------------------------------+------------------------------------------------------------------------+
+| in float **ROUGHNESS**            | Roughness.                                                             |
++-----------------------------------+------------------------------------------------------------------------+
+| in bool **OUTPUT_IS_SRGB**        | ``true`` when output is in sRGB color space.                           |
+|                                   | This is ``true`` in the Compatibility renderer,                        |
+|                                   | ``false`` in Forward+ and Forward Mobile.                              |
++-----------------------------------+------------------------------------------------------------------------+
+| out vec3 **DIFFUSE_LIGHT**        | Diffuse light result.                                                  |
++-----------------------------------+------------------------------------------------------------------------+
+| out vec3 **SPECULAR_LIGHT**       | Specular light result.                                                 |
++-----------------------------------+------------------------------------------------------------------------+
+| out float **ALPHA**               | Alpha (range of ``[0.0, 1.0]``). If written to, the material will go   |
+|                                   | to the transparent pipeline.                                           |
++-----------------------------------+------------------------------------------------------------------------+
 
 .. note::