Clarify COLOR and TEXTURE in CanvasItem shaders

tutorials/shaders/shader_reference/canvas_item_shader.rst

@@ -142,15 +142,56 @@ is usually:
 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,
-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:
+COLOR and TEXTURE
+~~~~~~~~~~~~~~~~~
+
+The built-in variable ``COLOR`` is used for a few things:
+
+  - In the ``vertex()`` function, ``COLOR`` contains the color from the vertex
+    primitive multiplied by the CanvasItem's
+    :ref:`modulate<class_CanvasItem_property_modulate>` multiplied by the
+    CanvasItem's :ref:`self_modulate<class_CanvasItem_property_self_modulate>`.
+  - In the ``fragment()`` function, the input value ``COLOR`` is that same value
+    multiplied by the color from the default ``TEXTURE`` (if present).
+  - In the ``fragment()`` function, ``COLOR`` is also the final output.
+
+Certain nodes (for example, :ref:`Sprite2D <class_Sprite2D>`) display a texture
+by default, for example :ref:`texture <class_Sprite2D_property_texture>`. When
+using a custom ``fragment()`` function, you have a few options on how to sample
+this texture.
+
+To read only the contents of the default texture, ignoring the vertex ``COLOR``:
+
+.. code-block:: glsl
+
+  void fragment() {
+    COLOR = texture(TEXTURE, UV);
+  }
+
+To read the contents of the default texture multiplied by vertex ``COLOR``:
 
 .. code-block:: glsl
 
-  COLOR = texture(TEXTURE, UV);
+  void fragment() {
+    // Equivalent to an empty fragment() function, since COLOR is also the output variable.
+    COLOR = COLOR;
+  }
+
+To read only the vertex ``COLOR`` in ``fragment()``, ignoring the main texture,
+you must pass ``COLOR`` as a varying, then read it in ``fragment()``:
+
+.. code-block:: glsl
+
+  varying vec4 vertex_color;
+  void vertex() {
+    vertex_color = COLOR;
+  }
+  void fragment() {
+    COLOR = vertex_color;
+  }
+
+NORMAL
+~~~~~~
 
 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
@@ -175,7 +216,7 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D
 +---------------------------------------------+---------------------------------------------------------------+
 | in vec2 **TEXTURE_PIXEL_SIZE**              | Normalized pixel size of default 2D texture.                  |
 |                                             | For a Sprite2D with a texture of size 64x32px,                |
-|                                             | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)``                 |
+|                                             | ``TEXTURE_PIXEL_SIZE`` = ``vec2(1/64, 1/32)``                 |
 +---------------------------------------------+---------------------------------------------------------------+
 | in bool **AT_LIGHT_PASS**                   | Always ``false``.                                             |
 +---------------------------------------------+---------------------------------------------------------------+
@@ -206,8 +247,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