Update shader reference pages for canvas_item shaders and particle shaders for 4.2

tutorials/shaders/shader_reference/canvas_item_shader.rst

@@ -32,7 +32,9 @@ Render modes
 +---------------------------------+----------------------------------------------------------------------+
 | **light_only**                  | Only draw on light pass.                                             |
 +---------------------------------+----------------------------------------------------------------------+
-| **skip_vertex_transform**       | VERTEX/NORMAL/etc need to be transformed manually in vertex function.|
+| **skip_vertex_transform**       | VERTEX needs to be transformed manually in vertex function.          |
++---------------------------------+----------------------------------------------------------------------+
+| **world_vertex_coords**         | VERTEX is modified in world coordinates instead of local.            |
 +---------------------------------+----------------------------------------------------------------------+
 
 Built-ins
@@ -117,7 +119,7 @@ is usually:
 +--------------------------------+----------------------------------------------------+
 | in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture.       |
 |                                | For a Sprite2D with a texture of size 64x32px,     |
-|                                | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)`  |
+|                                | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)``      |
 +--------------------------------+----------------------------------------------------+
 | inout vec2 **VERTEX**          | Vertex, in local space.                            |
 +--------------------------------+----------------------------------------------------+
@@ -134,16 +136,17 @@ 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 does not provide the texture color in the ``COLOR`` built-in variable; to read
-the texture color for such nodes, use:
+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:
 
 .. code-block:: glsl
 
   COLOR = texture(TEXTURE, UV);
 
-This differs from the behavior of the built-in normal map. If a normal map is attached, Godot uses
+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``.
@@ -167,7 +170,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** = :code:`vec2(1/64, 1/32)`             |
+|                                             | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)``                 |
 +---------------------------------------------+---------------------------------------------------------------+
 | in bool **AT_LIGHT_PASS**                   | Always ``false``.                                             |
 +---------------------------------------------+---------------------------------------------------------------+
@@ -198,8 +201,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 and output fragment color. If      |
-|                                             | unused, will be set to **TEXTURE** color.                     |
+| inout vec4 **COLOR**                        | Color from vertex function multiplied by the **TEXTURE**      |
+|                                             | color. Also output color value.                               |
 +---------------------------------------------+---------------------------------------------------------------+
 
 Light built-ins
@@ -212,7 +215,10 @@ 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
 lighting on an object; this can be useful when you only want the object visible
-where it is covered by light.
+where it is covered by light. 
+
+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:
 
@@ -232,22 +238,21 @@ Below is an example of a light shader that takes a CanvasItem's normal map into
 +----------------------------------+------------------------------------------------------------------------------+
 | in vec3 **NORMAL**               | Input Normal.                                                                |
 +----------------------------------+------------------------------------------------------------------------------+
-| in vec4 **COLOR**                | Input Color.                                                                 |
-|                                  | This is the output of the fragment function with final modulation applied.   |
+| 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.      |
 +----------------------------------+------------------------------------------------------------------------------+
 | sampler2D **TEXTURE**            | Current texture in use for CanvasItem.                                       |
 +----------------------------------+------------------------------------------------------------------------------+
-| in vec2 **TEXTURE_PIXEL_SIZE**   | Normalized pixel size of default 2D texture.                                 |
-|                                  | For a Sprite2D with a texture of size 64x32px,                               |
-|                                  | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)`                            |
+| in vec2 **TEXTURE_PIXEL_SIZE**   | Normalized pixel size of **TEXTURE**.                                        |
+|                                  | For a Sprite2D with a **TEXTURE** of size 64x32px,                           |
+|                                  | **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.                                                              |
+| in vec4 **LIGHT_COLOR**          | Color of Light multiplied by Light's texture.                                |
 +----------------------------------+------------------------------------------------------------------------------+
 | in float **LIGHT_ENERGY**        | Energy multiplier of Light.                                                  |
 +----------------------------------+------------------------------------------------------------------------------+
@@ -260,8 +265,7 @@ Below is an example of a light shader that takes a CanvasItem's normal map into
 +----------------------------------+------------------------------------------------------------------------------+
 | in vec3 **LIGHT_VERTEX**         | Pixel position, in screen space as modified in the fragment function.        |
 +----------------------------------+------------------------------------------------------------------------------+
-| inout vec4 **LIGHT**             | Value from the Light texture and output color. Can be modified. If not used, |
-|                                  | the light function is ignored.                                               |
+| inout vec4 **LIGHT**             | Output color for this Light.                                                 |
 +----------------------------------+------------------------------------------------------------------------------+
 | in vec4 **SPECULAR_SHININESS**   | Specular shininess, as set in the object's texture.                          |
 +----------------------------------+------------------------------------------------------------------------------+
@@ -280,14 +284,14 @@ present in the scene with the **SDF Collision** property enabled (which is the
 default). See the :ref:`2D lights and shadows <doc_2d_lights_and_shadows_setting_up_shadows>`
 documentation for more information.
 
-+-----------------------------------------------+----------------------------------------+
-| Function                                      | Description                            |
-+===============================================+========================================+
-| float **texture_sdf** (vec2 sdf_pos)          | Performs an SDF texture lookup.        |
-+-----------------------------------------------+----------------------------------------+
-| vec2 **texture_sdf_normal** (vec2 sdf_pos)    | Performs an SDF normal texture lookup. |
-+-----------------------------------------------+----------------------------------------+
-| vec2 **sdf_to_screen_uv** (vec2 sdf_pos)      | Converts a SDF to screen UV.           |
-+-----------------------------------------------+----------------------------------------+
-| vec2 **screen_uv_to_sdf** (vec2 uv)           | Converts screen UV to a SDF.           |
-+-----------------------------------------------+----------------------------------------+
++-----------------------------------------------+-------------------------------------------+
+| Function                                      | Description                               |
++===============================================+===========================================+
+| float **texture_sdf** (vec2 sdf_pos)          | Performs an SDF texture lookup.           |
++-----------------------------------------------+-------------------------------------------+
+| vec2 **texture_sdf_normal** (vec2 sdf_pos)    | Calculates a normal from the SDF texture. |
++-----------------------------------------------+-------------------------------------------+
+| vec2 **sdf_to_screen_uv** (vec2 sdf_pos)      | Converts a SDF to screen UV.              |
++-----------------------------------------------+-------------------------------------------+
+| vec2 **screen_uv_to_sdf** (vec2 uv)           | Converts screen UV to a SDF.              |
++-----------------------------------------------+-------------------------------------------+

tutorials/shaders/shader_reference/particle_shader.rst

@@ -9,8 +9,8 @@ position, and rotation. They are drawn with any regular material for CanvasItem
 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 the
-CanvasItem of Spatial shader. They contain two processor functions: ``start()``
+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()``.
 
 Unlike other shader types, particle shaders keep the data that was output the
@@ -30,15 +30,17 @@ take place over multiple frames.
 Render modes
 ^^^^^^^^^^^^
 
-+-----------------------+----------------------------------------+
-| Render mode           | Description                            |
-+=======================+========================================+
-| **keep_data**         | Do not clear previous data on restart. |
-+-----------------------+----------------------------------------+
-| **disable_force**     | Disable attractor force.               |
-+-----------------------+----------------------------------------+
-| **disable_velocity**  | Ignore **VELOCITY** value.             |
-+-----------------------+----------------------------------------+
++--------------------------+-------------------------------------------+
+| Render mode              | Description                               |
++==========================+===========================================+
+| **keep_data**            | Do not clear previous data on restart.    |
++--------------------------+-------------------------------------------+
+| **disable_force**        | Disable attractor force.                  |
++--------------------------+-------------------------------------------+
+| **disable_velocity**     | Ignore **VELOCITY** value.                |
++--------------------------+-------------------------------------------+
+| **collision_use_scale**  | Scale the particle's size for collisions. |
++--------------------------+-------------------------------------------+
 
 Built-ins
 ^^^^^^^^^
@@ -70,63 +72,37 @@ Global built-ins are available everywhere, including custom functions.
 Start and Process built-ins
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-+---------------------------------+--------------------------------------------------------------------------------+
-| Function                        | Description                                                                    |
-+=================================+================================================================================+
-| in float **LIFETIME**           | Particle lifetime.                                                             |
-+---------------------------------+--------------------------------------------------------------------------------+
-| in float **DELTA**              | Delta process time.                                                            |
-+---------------------------------+--------------------------------------------------------------------------------+
-| in uint **NUMBER**              | Unique number since emission start.                                            |
-+---------------------------------+--------------------------------------------------------------------------------+
-| in uint **INDEX**               | Particle index (from total particles).                                         |
-+---------------------------------+--------------------------------------------------------------------------------+
-| in mat4 **EMISSION_TRANSFORM**  | Emitter transform (used for non-local systems).                                |
-+---------------------------------+--------------------------------------------------------------------------------+
-| in uint **RANDOM_SEED**         | Random seed used as base for random.                                           |
-+---------------------------------+--------------------------------------------------------------------------------+
-| inout bool **ACTIVE**           | ``true`` when the particle is active, can be set ``false``.                    |
-+---------------------------------+--------------------------------------------------------------------------------+
-| inout vec4 **COLOR**            | Particle color, can be written to and accessed in mesh's vertex function.      |
-+---------------------------------+--------------------------------------------------------------------------------+
-| inout vec3 **VELOCITY**         | Particle velocity, can be modified.                                            |
-+---------------------------------+--------------------------------------------------------------------------------+
-| inout mat4 **TRANSFORM**        | Particle transform.                                                            |
-+---------------------------------+--------------------------------------------------------------------------------+
-| 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. |
-+---------------------------------+--------------------------------------------------------------------------------+
-
-.. note:: In order to use the ``COLOR`` variable in a StandardMaterial3D, set ``vertex_color_use_as_albedo``
-          to ``true``. In a ShaderMaterial, access it with the ``COLOR`` variable.
-
-Start built-ins
-^^^^^^^^^^^^^^^
-
-+---------------------------------+-------------+
-| Built-in                        | Description |
-+=================================+=============+
-| in bool **RESTART_POSITION**    |             |
-+---------------------------------+-------------+
-| in bool **RESTART_ROT_SCALE**   |             |
-+---------------------------------+-------------+
-| in bool **RESTART_VELOCITY**    |             |
-+---------------------------------+-------------+
-| in bool **RESTART_COLOR**       |             |
-+---------------------------------+-------------+
-| in bool **RESTART_CUSTOM**      |             |
-+---------------------------------+-------------+
-| in bool **RESTART_VELOCITY**    |             |
-+---------------------------------+-------------+
-
-Process built-ins
-^^^^^^^^^^^^^^^^^
+These properties can be accessed from both the ``start()`` and ``process()`` functions. 
 
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| Built-in                           | Description                                                                                                                             |
+| Function                           | Description                                                                                                                             |
 +====================================+=========================================================================================================================================+
-| in bool **RESTART**                | ``true`` if the current process frame is first for the particle.                                                                        |
+| in float **LIFETIME**              | Particle lifetime.                                                                                                                      |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| in float **DELTA**                 | Delta process time.                                                                                                                     |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| in uint **NUMBER**                 | Unique number since emission start.                                                                                                     |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| in uint **INDEX**                  | Particle index (from total particles).                                                                                                  |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| in mat4 **EMISSION_TRANSFORM**     | Emitter transform (used for non-local systems).                                                                                         |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| in uint **RANDOM_SEED**            | Random seed used as base for random.                                                                                                    |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| inout bool **ACTIVE**              | ``true`` when the particle is active, can be set ``false``.                                                                             |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| inout vec4 **COLOR**               | Particle color, can be written to and accessed in mesh's vertex function.                                                               |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| inout vec3 **VELOCITY**            | Particle velocity, can be modified.                                                                                                     |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| inout mat4 **TRANSFORM**           | Particle transform.                                                                                                                     |
++------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| 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.                                             |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | 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.              |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
@@ -138,23 +114,68 @@ Process built-ins
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | 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 bool **COLLIDED**               | ``true`` when the particle has collided with a particle collider.                                                                       |
+| in vec3 **EMITTER_VELOCITY**       | Velocity of the Particles node.                                                                                                         |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| 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 **INTERPOLATE_TO_END**    | Value of ``interp_to_end`` property of Particles node.                                                                                  |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| 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.                                                                      |
-+------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-| 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.                                             |
+| in uint **AMOUNT_RATIO**           | Value of ``amount_ratio`` property of Particles node.                                                                                   |
 +------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 
+.. note:: In order to use the ``COLOR`` variable in a StandardMaterial3D, set ``vertex_color_use_as_albedo``
+          to ``true``. In a ShaderMaterial, access it with the ``COLOR`` variable.
+
+Start built-ins
+^^^^^^^^^^^^^^^
+
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Built-in                        | Description                                                                                                                                                                           |
++=================================+=======================================================================================================================================================================================+
+| in bool **RESTART_POSITION**    | ``true`` if particle is restarted, or emitted without a custom position (i.e. this particle was created by ``emit_subparticle()`` without the ``FLAG_EMIT_POSITION`` flag).           |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| in bool **RESTART_ROT_SCALE**   | ``true`` if particle is restarted, or emitted without a custom rotation or scale (i.e. this particle was created by ``emit_subparticle()`` without the ``FLAG_EMIT_ROT_SCALE`` flag). |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| in bool **RESTART_VELOCITY**    | ``true`` if particle is restarted, or emitted without a custom velocity (i.e. this particle was created by ``emit_subparticle()`` without the ``FLAG_EMIT_VELOCITY`` flag).           |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| in bool **RESTART_COLOR**       | ``true`` if particle is restarted, or emitted without a custom color (i.e. this particle was created by ``emit_subparticle()`` without the ``FLAG_EMIT_COLOR`` flag).                 |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| in bool **RESTART_CUSTOM**      | ``true`` if particle is restarted, or emitted without a custom property (i.e. this particle was created by ``emit_subparticle()`` without the ``FLAG_EMIT_CUSTOM`` flag).             |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+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.                                  |
++------------------------------------+-----------------------------------------------------------------------------------------------------+
+
 Process functions
 ^^^^^^^^^^^^^^^^^
 
-+--------------------------------------------------------------------------------------------+-----------------------------------------------+
-| Function                                                                                   | Description                                   |
-+============================================================================================+===============================================+
-| bool **emit_subparticle** (mat4 xform, vec3 velocity, vec4 color, vec4 custom, uint flags) | Forces to emit a particle from a sub-emitter. |
-+--------------------------------------------------------------------------------------------+-----------------------------------------------+
+``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
+following code will emit a particle with a specified position, velocity, and
+color, but unspecified rotation, scale, and custom value:
+
+.. code-block:: glsl
+
+    mat4 custom_transform = mat4(1.0);
+    custom_transform[3].xyz = vec3(10.5, 0.0, 4.0);
+    emit_subparticle(custom_transform, vec3(1.0, 0.5, 1.0), vec4(1.0, 0.0, 0.0, 1.0), vec4(1.0), FLAG_EMIT_POSITION | FLAG_EMIT_VELOCITY | FLAG_EMIT_COLOR);
+
++--------------------------------------------------------------------------------------------+--------------------------------------+
+| Function                                                                                   | Description                          |
++============================================================================================+======================================+
+| bool **emit_subparticle** (mat4 xform, vec3 velocity, vec4 color, vec4 custom, uint flags) | Emits a particle from a sub-emitter. |
++--------------------------------------------------------------------------------------------+--------------------------------------+