godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #8506 from clayjohn/shaders-CI-particles

Browse Source 
Update shader reference pages for canvas_item shaders and particle shaders for 4.2
This commit is contained in:
Max Hilbrunner
2023-11-23 13:08:04 +01:00
committed by GitHub
parent bdd27bebb3 da93553be2
commit 37a5a9b4f7
2 changed files with 133 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
tutorials/shaders/shader_reference/canvas_item_shader.rst
View File

@@ -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. |
+-----------------------------------------------+-------------------------------------------+

177
tutorials/shaders/shader_reference/particle_shader.rst
View File

@@ -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. |
+--------------------------------------------------------------------------------------------+--------------------------------------+