godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2025-12-31 17:49:03 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #11359 from AThousandShips/fix_shaders

Browse Source 
Shader reference proofreading
This commit is contained in:
Max Hilbrunner
2025-10-09 13:19:09 +02:00
committed by GitHub
parent 6ebd201367 2c9ada62c4
commit fab7266307
5 changed files with 157 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -30,7 +30,7 @@ Render modes
+---------------------------------+----------------------------------------------------------------------+
| **unshaded** | Result is just albedo. No lighting/shading happens in material. |
+---------------------------------+----------------------------------------------------------------------+
| **light_only** | Only draw on light pass. |
| **light_only** | Only draw in the light pass. |
+---------------------------------+----------------------------------------------------------------------+
| **skip_vertex_transform** | ``VERTEX`` needs to be transformed manually in the ``vertex()`` |
| | function. |
@@ -54,27 +54,27 @@ Global built-ins
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`` |
| | seconds (which can be changed with the |
| | :ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>` |
| | setting). It's affected by |
| | :ref:`time_scale<class_Engine_property_time_scale>` but not by pausing. If you need a |
| | ``TIME`` variable that is not affected by time scale, add your own |
| | :ref:`global shader uniform<doc_shading_language_global_uniforms>` and update it each |
| | frame. |
+-------------------+------------------------------------------------------------------------------------------+
| in float **PI** | A ``PI`` constant (``3.141592``). |
| | 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. |
+-------------------+------------------------------------------------------------------------------------------+
| in float **E** | An ``E`` constant (``2.718281``). |
| | Euler's number and a base of the natural logarithm. |
+-------------------+------------------------------------------------------------------------------------------+
+-------------------+-------------------------------------------------------------------------------------------------+
| Built-in | Description |
+===================+=================================================================================================+
| 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 affected by |
| | :ref:`time_scale<class_Engine_property_time_scale>` but not by pausing. If you need a |
| | ``TIME`` variable that is not affected by time scale, add your own |
| | :ref:`global shader uniform<doc_shading_language_global_uniforms>` and update it each |
| | frame. |
+-------------------+-------------------------------------------------------------------------------------------------+
| in float **PI** | A ``PI`` constant (``3.141592``). |
| | The ratio of a circle's circumference to its diameter and the number of radians in a half turn. |
+-------------------+-------------------------------------------------------------------------------------------------+
| in float **TAU** | A ``TAU`` constant (``6.283185``). |
| | Equivalent to ``PI * 2`` and the number of radians in a full turn. |
+-------------------+-------------------------------------------------------------------------------------------------+
| in float **E** | An ``E`` constant (``2.718281``). |
| | Euler's number, the base of the natural logarithm. |
+-------------------+-------------------------------------------------------------------------------------------------+
Vertex built-ins
----------------
@@ -112,11 +112,11 @@ 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, 0.0)`` |
| | screen and coordinates range from ``(0.0, 0.0)`` |
| | to viewport size. |
+--------------------------------+----------------------------------------------------------------+
| in mat4 **SCREEN_MATRIX** | Canvas space to clip space. In clip space |
| | coordinates ranging from ``(-1.0, -1.0)`` to |
| in mat4 **SCREEN_MATRIX** | Canvas space to clip space transform. In clip space |
| | coordinates range from ``(-1.0, -1.0)`` to |
| | ``(1.0, 1.0).`` |
+--------------------------------+----------------------------------------------------------------+
| in int **INSTANCE_ID** | Instance ID for instancing. |
@@ -125,7 +125,7 @@ is usually:
+--------------------------------+----------------------------------------------------------------+
| in bool **AT_LIGHT_PASS** | Always ``false``. |
+--------------------------------+----------------------------------------------------------------+
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. |
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of the default 2D texture. |
| | For a Sprite2D with a texture of size 64x32px, |
| | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)`` |
+--------------------------------+----------------------------------------------------------------+
@@ -137,7 +137,7 @@ is usually:
| inout vec2 **UV** | Normalized texture coordinates. Range from ``0.0`` |
| | to ``1.0``. |
+--------------------------------+----------------------------------------------------------------+
| inout vec4 **COLOR** | Color from vertex primitive multiplied by CanvasItem's |
| inout vec4 **COLOR** | Color from vertex primitive multiplied by the CanvasItem's |
| | :ref:`modulate<class_CanvasItem_property_modulate>` |
| | multiplied by CanvasItem's |
| | :ref:`self_modulate<class_CanvasItem_property_self_modulate>`. |
@@ -221,7 +221,7 @@ it to the ``NORMAL_MAP`` property. Godot will handle converting it for use in 2D
| | 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. |
| in vec2 **SCREEN_PIXEL_SIZE** | Size of individual pixels. Equal to the inverse of resolution.|
+---------------------------------------------+---------------------------------------------------------------+
| in vec4 **REGION_RECT** | Visible area of the sprite region in format |
| | ``(x, y, width, height)``. Varies according to |
@@ -231,7 +231,7 @@ it to the ``NORMAL_MAP`` property. Godot will handle converting it for use in 2D
+---------------------------------------------+---------------------------------------------------------------+
| sampler2D **TEXTURE** | Default 2D texture. |
+---------------------------------------------+---------------------------------------------------------------+
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. |
| in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of the default 2D texture. |
| | For a Sprite2D with a texture of size 64x32px, |
| | ``TEXTURE_PIXEL_SIZE`` = ``vec2(1/64, 1/32)`` |
+---------------------------------------------+---------------------------------------------------------------+
@@ -242,11 +242,11 @@ it to the ``NORMAL_MAP`` 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 the ``vertex()`` function. |
| | For Sprite2D with region enabled, this will sample the entire |
| | texture. Use ``REGION_RECT`` instead to sample only the |
| | region defined in the Sprite2D's properties. |
| | For a Sprite2D with region enabled, this will sample the |
| | entire texture. Use ``REGION_RECT`` instead to sample only |
| | the region defined in the Sprite2D's properties. |
+---------------------------------------------+---------------------------------------------------------------+
| in vec2 **SCREEN_UV** | Screen UV coordinate for current pixel. |
| in vec2 **SCREEN_UV** | Screen UV coordinate for the current pixel. |
+---------------------------------------------+---------------------------------------------------------------+
| sampler2D **SCREEN_TEXTURE** | Removed in Godot 4. Use a ``sampler2D`` with |
| | ``hint_screen_texture`` instead. |
@@ -309,13 +309,13 @@ Below is an example of a light shader that takes a CanvasItem's normal map into
| in vec2 **UV** | UV from the ``vertex()`` function, equivalent to the UV in the |
| | ``fragment()`` function. |
+----------------------------------+------------------------------------------------------------------------------+
| sampler2D **TEXTURE** | Current texture in use for CanvasItem. |
| sampler2D **TEXTURE** | Current texture in use for the CanvasItem. |
+----------------------------------+------------------------------------------------------------------------------+
| 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 **SCREEN_UV** | Screen UV coordinate for the current pixel. |
+----------------------------------+------------------------------------------------------------------------------+
| in vec2 **POINT_COORD** | UV for Point Sprite. |
+----------------------------------+------------------------------------------------------------------------------+
@@ -346,9 +346,9 @@ SDF functions
-------------
There are a few additional functions implemented to sample an automatically
generated Signed Distance Field texture. These functions available for the ``fragment()``
generated Signed Distance Field texture. These functions are available in the ``fragment()``
and ``light()`` functions of CanvasItem shaders. Custom functions may also use them as long
as they called from supported functions.
as they are called from supported functions.
The signed distance field is generated from :ref:`class_LightOccluder2D` nodes
present in the scene with the **SDF Collision** property enabled (which is the

47
tutorials/shaders/shader_reference/fog_shader.rst
View File

@@ -3,7 +3,7 @@
Fog shaders
===========
Fog shaders are used to define how fog is added (or subtracted) from a scene in
Fog shaders are used to define how fog is added to (or subtracted from) a scene in
a given area. Fog shaders are always used together with
:ref:`FogVolumes <class_FogVolume>` and volumetric fog. Fog shaders only have
one processing function, the ``fog()`` function.
@@ -14,7 +14,7 @@ can add depends on how close the :ref:`FogVolume <class_FogVolume>` is to the
camera.
Fog shaders are a special form of compute shader that is called once for
every froxel that is touched by an axis aligned bounding box of the associated
every froxel that is touched by an axis-aligned bounding box of the associated
:ref:`FogVolume <class_FogVolume>`. This means that froxels that just barely
touch a given :ref:`FogVolume <class_FogVolume>` will still be used.
@@ -30,28 +30,27 @@ Global built-ins
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`` |
| | seconds (which can be changed with the |
| | :ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>` |
| | setting). It's affected by |
| | :ref:`time_scale<class_Engine_property_time_scale>` but not by pausing. If you need a |
| | ``TIME`` variable that is not affected by time scale, add your own |
| | :ref:`global shader uniform<doc_shading_language_global_uniforms>` and update it each |
| | frame. |
+-----------------------------------+------------------------------------------------------------------------------------------+
| in float **PI** | A ``PI`` constant (``3.141592``). |
| | 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. |
+-----------------------------------+------------------------------------------------------------------------------------------+
| in float **E** | An ``E`` constant (``2.718281``). |
| | Euler's number and a base of the natural logarithm. |
+-----------------------------------+------------------------------------------------------------------------------------------+
+-----------------------------------+-------------------------------------------------------------------------------------------------+
| Built-in | Description |
+===================================+=================================================================================================+
| 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 affected by |
| | :ref:`time_scale<class_Engine_property_time_scale>` but not by pausing. If you need a |
| | ``TIME`` variable that is not affected by time scale, add your own |
| | :ref:`global shader uniform<doc_shading_language_global_uniforms>` and update it each |
| | frame. |
+-----------------------------------+-------------------------------------------------------------------------------------------------+
| in float **PI** | A ``PI`` constant (``3.141592``). |
| | The ratio of a circle's circumference to its diameter and the number of radians in a half turn. |
+-----------------------------------+-------------------------------------------------------------------------------------------------+
| in float **TAU** | A ``TAU`` constant (``6.283185``). |
| | Equivalent to ``PI * 2`` and the number of radians in a full turn. |
+-----------------------------------+-------------------------------------------------------------------------------------------------+
| in float **E** | An ``E`` constant (``2.718281``). |
| | Euler's number, the base of the natural logarithm. |
+-----------------------------------+-------------------------------------------------------------------------------------------------+
Fog built-ins
-------------

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

@@ -5,7 +5,7 @@ Particle shaders
Particle shaders are a special type of shader that runs before the object is
drawn. They are used for calculating material properties such as color,
position, and rotation. They are drawn with any regular material for CanvasItem
position, and rotation. They can be 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;
@@ -54,26 +54,26 @@ Global built-ins
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`` |
| | seconds (which can be changed with the |
| | :ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>` |
| | setting). It's affected by |
| | :ref:`time_scale<class_Engine_property_time_scale>` but not by pausing. If you need a |
| | ``TIME`` variable that is not affected by time scale, add your own |
| | :ref:`global shader uniform<doc_shading_language_global_uniforms>` and update it each |
| | frame. |
+-------------------+------------------------------------------------------------------------------------------+
| in float **PI** | A ``PI`` constant (``3.141592``). |
| | 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. |
+-------------------+------------------------------------------------------------------------------------------+
| in float **E** | An ``E`` constant (``2.718281``). Euler's number and a base of the natural logarithm. |
+-------------------+------------------------------------------------------------------------------------------+
+-------------------+-------------------------------------------------------------------------------------------------+
| Built-in | Description |
+===================+=================================================================================================+
| 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 affected by |
| | :ref:`time_scale<class_Engine_property_time_scale>` but not by pausing. If you need a |
| | ``TIME`` variable that is not affected by time scale, add your own |
| | :ref:`global shader uniform<doc_shading_language_global_uniforms>` and update it each |
| | frame. |
+-------------------+-------------------------------------------------------------------------------------------------+
| in float **PI** | A ``PI`` constant (``3.141592``). |
| | The ratio of a circle's circumference to its diameter and the number of radians in a half turn. |
+-------------------+-------------------------------------------------------------------------------------------------+
| in float **TAU** | A ``TAU`` constant (``6.283185``). |
| | Equivalent to ``PI * 2`` and the number of radians in a full turn. |
+-------------------+-------------------------------------------------------------------------------------------------+
| in float **E** | An ``E`` constant (``2.718281``). Euler's number, the base of the natural logarithm. |
+-------------------+-------------------------------------------------------------------------------------------------+
Start and Process built-ins
---------------------------
@@ -95,38 +95,38 @@ These properties can be accessed from both the ``start()`` and ``process()`` fun
+------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
| 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 bool **ACTIVE** | ``true`` when the particle is active, can be set to ``false``. |
+------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
| inout vec4 **COLOR** | Particle color, can be written to and accessed in mesh's vertex function. |
| inout vec4 **COLOR** | Particle color, can be written to and accessed in the 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 vec4 **CUSTOM** | Custom particle data. Accessible from the mesh's shader as ``INSTANCE_CUSTOM``. |
+------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
| inout float **MASS** | Particle mass, intended to be used with attractors. Equals ``1.0`` by default. |
| inout float **MASS** | Particle mass, intended to be used with attractors. ``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, 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 the last argument of the ``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 the last argument of the ``emit_subparticle()`` function to assign a 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 the last argument of the ``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 the last argument of the ``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 the last argument of the ``emit_subparticle()`` function to assign a custom data vector to a new particle. |
+------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
| in vec3 **EMITTER_VELOCITY** | Velocity of the :ref:`Particles2D<class_GPUParticles2D>` (:ref:`3D<class_GPUParticles3D>`) 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 float **INTERPOLATE_TO_END** | Value of the :ref:`interp_to_end<class_GPUParticles2D_property_interp_to_end>` |
| | (:ref:`3D<class_GPUParticles3D_property_interp_to_end>`) property of the 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. |
| in uint **AMOUNT_RATIO** | Value of the :ref:`amount_ratio<class_GPUParticles2D_property_amount_ratio>` |
| | (:ref:`3D<class_GPUParticles3D_property_amount_ratio>`) property of the Particles node. |
+------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
.. note:: In order to use the ``COLOR`` variable in a StandardMaterial3D, set ``vertex_color_use_as_albedo``
@@ -152,25 +152,25 @@ 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 ``(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. |
+------------------------------------+-------------------------------------------------------------------------------------------------------+
+------------------------------------+---------------------------------------------------------------------------------------------------------+
| Built-in | Description |
+====================================+=========================================================================================================+
| in bool **RESTART** | ``true`` if the current process frame is the 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 the 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
particles shaders. It allows users to add a new particle with specified
particle 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

54
tutorials/shaders/shader_reference/sky_shader.rst
View File

@@ -155,7 +155,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`` |
| | seconds (which can be changed with the |
| | seconds (which can be changed with the |
| | :ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>` |
| | setting). It's affected by :ref:`time_scale<class_Engine_property_time_scale>` but not by pausing. If you need a |
| | ``TIME`` variable that is not affected by time scale, add your own |
@@ -164,13 +164,13 @@ There are 4 ``LIGHTX`` lights, accessed as ``LIGHT0``, ``LIGHT1``, ``LIGHT2``, a
+---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| 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. |
| samplerCube **RADIANCE** | Radiance cubemap. Can only be read from during the background pass. Check ``!AT_CUBEMAP_PASS`` before using. |
+---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| in bool **AT_HALF_RES_PASS** | ``true`` when rendering to half resolution pass. |
| in bool **AT_HALF_RES_PASS** | ``true`` when rendering to the half resolution pass. |
+---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| in bool **AT_QUARTER_RES_PASS** | ``true`` when rendering to quarter resolution pass. |
| in bool **AT_QUARTER_RES_PASS** | ``true`` when rendering to the quarter resolution pass. |
+---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| in bool **AT_CUBEMAP_PASS** | ``true`` when rendering to radiance cubemap. |
| in bool **AT_CUBEMAP_PASS** | ``true`` when rendering to the radiance cubemap. |
+---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| in bool **LIGHTX_ENABLED** | ``true`` if ``LIGHTX`` is visible and in the scene. If ``false``, other light properties may be garbage. |
+---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
@@ -184,34 +184,34 @@ There are 4 ``LIGHTX`` lights, accessed as ``LIGHT0``, ``LIGHT1``, ``LIGHT2``, a
| | (0.5 degrees). |
+---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| in float **PI** | A ``PI`` constant (``3.141592``). |
| | A ratio of a circle's circumference to its diameter and amount of radians in half turn. |
| | The ratio of a circle's circumference to its diameter and the number of radians in a half turn. |
+---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| in float **TAU** | A ``TAU`` constant (``6.283185``). |
| | An equivalent of ``PI * 2`` and amount of radians in full turn. |
| | Equivalent to ``PI * 2`` and the number of radians in a full turn. |
+---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
| in float **E** | An ``E`` constant (``2.718281``). |
| | Euler's number and a base of the natural logarithm. |
| | Euler's number, the base of the natural logarithm. |
+---------------------------------+--------------------------------------------------------------------------------------------------------------------------+
Sky built-ins
-------------
+-------------------------------+-------------------------------------------------------------------------------------------------+
| Built-in | Description |
+===============================+=================================================================================================+
| in vec3 **EYEDIR** | Normalized direction of current pixel. Use this as your basic direction for procedural effects. |
+-------------------------------+-------------------------------------------------------------------------------------------------+
| in vec2 **SCREEN_UV** | Screen UV coordinate for current pixel. Used to map a texture to the full screen. |
+-------------------------------+-------------------------------------------------------------------------------------------------+
| in vec2 **SKY_COORDS** | Sphere UV. Used to map a panorama texture to the sky. |
+-------------------------------+-------------------------------------------------------------------------------------------------+
| in vec4 **HALF_RES_COLOR** | Color value of corresponding pixel from half resolution pass. Uses linear filter. |
+-------------------------------+-------------------------------------------------------------------------------------------------+
| in vec4 **QUARTER_RES_COLOR** | Color value of corresponding pixel from quarter resolution pass. Uses linear filter. |
+-------------------------------+-------------------------------------------------------------------------------------------------+
| out vec3 **COLOR** | Output color. |
+-------------------------------+-------------------------------------------------------------------------------------------------+
| out float **ALPHA** | Output alpha value, can only be used in subpasses. |
+-------------------------------+-------------------------------------------------------------------------------------------------+
| out vec4 **FOG** | |
+-------------------------------+-------------------------------------------------------------------------------------------------+
+-------------------------------+-----------------------------------------------------------------------------------------------------+
| Built-in | Description |
+===============================+=====================================================================================================+
| in vec3 **EYEDIR** | Normalized direction of the current pixel. Use this as your basic direction for procedural effects. |
+-------------------------------+-----------------------------------------------------------------------------------------------------+
| in vec2 **SCREEN_UV** | Screen UV coordinate for the current pixel. Used to map a texture to the full screen. |
+-------------------------------+-----------------------------------------------------------------------------------------------------+
| in vec2 **SKY_COORDS** | Sphere UV. Used to map a panorama texture to the sky. |
+-------------------------------+-----------------------------------------------------------------------------------------------------+
| in vec4 **HALF_RES_COLOR** | Color value of the corresponding pixel from the half resolution pass. Uses linear filter. |
+-------------------------------+-----------------------------------------------------------------------------------------------------+
| in vec4 **QUARTER_RES_COLOR** | Color value of the corresponding pixel from the quarter resolution pass. Uses linear filter. |
+-------------------------------+-----------------------------------------------------------------------------------------------------+
| out vec3 **COLOR** | Output color. |
+-------------------------------+-----------------------------------------------------------------------------------------------------+
| out float **ALPHA** | Output alpha value, can only be used in subpasses. |
+-------------------------------+-----------------------------------------------------------------------------------------------------+
| out vec4 **FOG** | |
+-------------------------------+-----------------------------------------------------------------------------------------------------+

43
tutorials/shaders/shader_reference/spatial_shader.rst
View File

@@ -5,11 +5,12 @@ Spatial shaders
Spatial shaders are used for shading 3D objects. They are the most complex type of shader Godot offers.
Spatial shaders are highly configurable with different render modes and different rendering options
(e.g. Subsurface Scattering, Transmission, Ambient Occlusion, Rim lighting etc). Users can optionally
(e.g. Subsurface Scattering, Transmission, Ambient Occlusion, Rim lighting, etc.). Users can optionally
write vertex, fragment, and light processor functions to affect how objects are drawn.
Render modes
------------
For visual examples of these render modes, see :ref:`Standard Material 3D and ORM Material 3D<doc_standard_material_3d>`.
+-------------------------------+------------------------------------------------------------------------------------------------------+
@@ -81,7 +82,7 @@ For visual examples of these render modes, see :ref:`Standard Material 3D and OR
+-------------------------------+------------------------------------------------------------------------------------------------------+
| **vertex_lighting** | Use vertex-based lighting instead of per-pixel lighting. |
+-------------------------------+------------------------------------------------------------------------------------------------------+
| **particle_trails** | Enables the trails when used on particles geometry. |
| **particle_trails** | Enables the trails when used on particle geometry. |
+-------------------------------+------------------------------------------------------------------------------------------------------+
| **alpha_to_coverage** | Alpha antialiasing mode, see `here <https://github.com/godotengine/godot/pull/40364>`_ for more. |
+-------------------------------+------------------------------------------------------------------------------------------------------+
@@ -110,7 +111,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`` |
| | seconds (which can be changed with the |
| | seconds (which can be changed with the |
| | :ref:`rollover<class_ProjectSettings_property_rendering/limits/time/time_rollover_secs>` |
| | setting). It's affected by :ref:`time_scale<class_Engine_property_time_scale>` but not by pausing. |
| | If you need a ``TIME`` variable that is not affected by time scale, add your own |
@@ -118,12 +119,12 @@ Global built-ins are available everywhere, including custom functions.
| | frame. |
+-----------------------------+-----------------------------------------------------------------------------------------------------+
| in float **PI** | A ``PI`` constant (``3.141592``). |
| | A ratio of a circle's circumference to its diameter and amount of radians in half turn. |
| | The ratio of a circle's circumference to its diameter and the number of radians in a half turn. |
+-----------------------------+-----------------------------------------------------------------------------------------------------+
| in float **TAU** | A ``TAU`` constant (``6.283185``). |
| | An equivalent of ``PI * 2`` and amount of radians in full turn. |
| | Equivalent to ``PI * 2`` and the number of radians in a full turn. |
+-----------------------------+-----------------------------------------------------------------------------------------------------+
| in float **E** | An ``E`` constant (``2.718281``). Euler's number and a base of the natural logarithm. |
| in float **E** | An ``E`` constant (``2.718281``). Euler's number, the base of the natural logarithm. |
+-----------------------------+-----------------------------------------------------------------------------------------------------+
| in bool **OUTPUT_IS_SRGB** | ``true`` when output is in sRGB color space (this is ``true`` in the Compatibility |
| | renderer, ``false`` in Forward+ and Mobile). |
@@ -171,7 +172,7 @@ is usually:
* **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
This allows you to easily adjust the shader to a particle system using default particle material. When writing a custom particle
shader, this value can be used as desired.
+----------------------------------------+--------------------------------------------------------+
@@ -183,8 +184,8 @@ shader, this value can be used as desired.
+----------------------------------------+--------------------------------------------------------+
| in mat4 **INV_VIEW_MATRIX** | View space to world space transform. |
+----------------------------------------+--------------------------------------------------------+
| in mat4 **MAIN_CAM_INV_VIEW_MATRIX** | View space to world space transform of camera used to |
| | draw the current viewport. |
| in mat4 **MAIN_CAM_INV_VIEW_MATRIX** | View space to world space transform of the camera used |
| | to draw the current viewport. |
+----------------------------------------+--------------------------------------------------------+
| in mat4 **INV_PROJECTION_MATRIX** | Clip space to view space transform. |
+----------------------------------------+--------------------------------------------------------+
@@ -351,12 +352,12 @@ these properties, and if you don't write to them, Godot will optimize away the c
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| sampler2D **SCREEN_TEXTURE** | Removed in Godot 4. Use a ``sampler2D`` with ``hint_screen_texture`` instead. |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| in vec2 **SCREEN_UV** | Screen UV coordinate for current pixel. |
| in vec2 **SCREEN_UV** | Screen UV coordinate for the current pixel. |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| sampler2D **DEPTH_TEXTURE** | Removed in Godot 4. Use a ``sampler2D`` with ``hint_depth_texture`` instead. |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| 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. |
| out float **DEPTH** | Custom depth value (range ``[0.0, 1.0]``). If ``DEPTH`` is written to in any shader branch, |
| | then you are responsible for setting ``DEPTH`` for **all** other branches. |
| | Otherwise, the graphics API will leave them uninitialized. |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| inout vec3 **NORMAL** | Normal that comes from the ``vertex()`` function, in view space. |
@@ -374,7 +375,7 @@ these properties, and if you don't write to them, Godot will optimize away the c
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| out vec3 **ALBEDO** | Albedo (default white). Base color. |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| out float **ALPHA** | Alpha (range of ``[0.0, 1.0]``). If read from or written to, the material will go to the |
| out float **ALPHA** | Alpha (range ``[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. |
@@ -394,16 +395,16 @@ these properties, and if you don't write to them, Godot will optimize away the c
| | This should be written to when using a *shaded* material with premultiplied alpha blending for |
| | interaction with lighting. This is not required for unshaded materials. |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| out float **METALLIC** | Metallic (range of ``[0.0, 1.0]``). |
| out float **METALLIC** | Metallic (range ``[0.0, 1.0]``). |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| out float **SPECULAR** | Specular (not physically accurate to change). Defaults to ``0.5``. ``0.0`` disables reflections. |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| out float **ROUGHNESS** | Roughness (range of ``[0.0, 1.0]``). |
| out float **ROUGHNESS** | Roughness (range ``[0.0, 1.0]``). |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| out float **RIM** | Rim (range of ``[0.0, 1.0]``). If used, Godot calculates rim lighting. |
| out float **RIM** | Rim (range ``[0.0, 1.0]``). If used, Godot calculates rim lighting. |
| | Rim size depends on ``ROUGHNESS``. |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| out float **RIM_TINT** | Rim Tint, range of ``0.0`` (white) to ``1.0`` (albedo). If used, Godot calculates rim lighting. |
| out float **RIM_TINT** | Rim Tint, range from ``0.0`` (white) to ``1.0`` (albedo). If used, Godot calculates rim lighting.|
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| out float **CLEARCOAT** | Small specular blob added on top of the existing one. If used, Godot calculates clearcoat. |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
@@ -430,7 +431,7 @@ 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 ambient occlusion affects direct light (range of ``[0.0, 1.0]``, default ``0.0``). |
| out float **AO_LIGHT_AFFECT** | How much ambient occlusion affects direct light (range ``[0.0, 1.0]``, default ``0.0``). |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
| out vec3 **EMISSION** | Emission color (can go over ``(1.0, 1.0, 1.0)`` for HDR). |
+----------------------------------------+--------------------------------------------------------------------------------------------------+
@@ -496,7 +497,7 @@ If you want the lights to add together, add the light contribution to ``DIFFUSE_
+-----------------------------------+------------------------------------------------------------------------+
| in vec3 **NORMAL** | Normal vector, in view space. |
+-----------------------------------+------------------------------------------------------------------------+
| in vec2 **SCREEN_UV** | Screen UV coordinate for current pixel. |
| in vec2 **SCREEN_UV** | Screen UV coordinate for the current pixel. |
+-----------------------------------+------------------------------------------------------------------------+
| in vec2 **UV** | UV that comes from the ``vertex()`` function. |
+-----------------------------------+------------------------------------------------------------------------+
@@ -532,8 +533,8 @@ If you want the lights to add together, add the light contribution to ``DIFFUSE_
+-----------------------------------+------------------------------------------------------------------------+
| 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. |
| out float **ALPHA** | Alpha (range ``[0.0, 1.0]``). If written to, the material will go to |
| | the transparent pipeline. |
+-----------------------------------+------------------------------------------------------------------------+
.. note::