stan220/godot-docs
1
0
Fork 0
mirror of https://github.com/stan220/godot-docs.git synced 2026-09-08 19:29:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Clean up canvas item shader reference and add new light shader built ins

Browse Source
This commit is contained in:
clayjohn
2022-09-28 12:27:33 -07:00
parent 9bedf39056
commit 39e0f7cf15
1 changed files with 96 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tutorials/shaders/shader_reference/canvas_item_shader.rst
+96 -96
View File
@@ -70,11 +70,11 @@ Global built-ins are available everywhere, including custom functions.
Vertex built-ins
^^^^^^^^^^^^^^^^
Vertex data (``VERTEX``) is presented in local space (pixel coordinates, relative to the camera).
Vertex data (``VERTEX``) is presented in local space (pixel coordinates, relative to the Node2D's origin).
If not written to, these values will not be modified and be passed through as they came.
The user can disable the built-in modelview transform (projection will still happen later) and do
it manually with the following code:
The user can disable the built-in model to world transform (world to screen and projection will still
happen later) and do it manually with the following code:
.. code-block:: glsl
@@ -83,32 +83,9 @@ it manually with the following code:
void vertex() {
VERTEX = (EXTRA_MATRIX * (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0))).xy;
VERTEX = (MODEL_MATRIX * vec4(VERTEX, 0.0, 1.0)).xy;
}
.. note:: ``MODEL_MATRIX`` is known as a modelview matrix. It takes input in local space and transforms it
into view space.
In order to get the world space coordinates of a vertex, you have to pass in a custom uniform like so:
::
material.set_shader_param("global_transform", get_global_transform())
Then, in your vertex shader:
.. code-block:: glsl
uniform mat4 global_transform;
varying vec2 world_position;
void vertex(){
world_position = (global_transform * vec4(VERTEX, 0.0, 1.0)).xy;
}
``world_position`` can then be used in either the vertex or fragment functions.
Other built-ins, such as UV and COLOR, are also passed through to the fragment function if not modified.
For instancing, the INSTANCE_CUSTOM variable contains the instance custom data. When using particles, this information
@@ -118,31 +95,36 @@ is usually:
* **y**: Phase during lifetime (0 to 1).
* **z**: Animation frame.
+--------------------------------+---------------------------------------------------+
| Built-in | Description |
+================================+===================================================+
| in mat4 **MODEL_MATRIX** | Image space to view space transform. |
+--------------------------------+---------------------------------------------------+
| in mat4 **CANVAS_MATRIX** | |
+--------------------------------+---------------------------------------------------+
| in mat4 **SCREEN_MATRIX** | |
+--------------------------------+---------------------------------------------------+
| in vec4 **INSTANCE_CUSTOM** | Instance custom data. |
+--------------------------------+---------------------------------------------------+
| in bool **AT_LIGHT_PASS** | ``true`` if this is a light pass. |
+--------------------------------+---------------------------------------------------+
| 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)` |
+--------------------------------+---------------------------------------------------+
| inout vec2 **VERTEX** | Vertex, in image space. |
+--------------------------------+---------------------------------------------------+
| inout vec2 **UV** | Texture coordinates. |
+--------------------------------+---------------------------------------------------+
| inout vec4 **COLOR** | Color from vertex primitive. |
+--------------------------------+---------------------------------------------------+
| inout float **POINT_SIZE** | Point size for point drawing. |
+--------------------------------+---------------------------------------------------+
+--------------------------------+----------------------------------------------------+
| Built-in | Description |
+================================+====================================================+
| in mat4 **MODEL_MATRIX** | Local space to world space transform. World space |
| | is the coordinates you normally use in the editor. |
+--------------------------------+----------------------------------------------------+
| in mat4 **CANVAS_MATRIX** | World space to canvas space transform. In canvas |
| | space the origin is the upper-left corner of the |
| | screen and coordinates ranging from (0, 0) to |
| | viewport size. |
+--------------------------------+----------------------------------------------------+
| in mat4 **SCREEN_MATRIX** | Canvas space to clip space. In clip space |
| | coordinates ranging from (-1, -1) to (1, 1). |
+--------------------------------+----------------------------------------------------+
| in vec4 **INSTANCE_CUSTOM** | Instance custom data. |
+--------------------------------+----------------------------------------------------+
| in bool **AT_LIGHT_PASS** | ``true`` if this is a light pass. |
+--------------------------------+----------------------------------------------------+
| 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)` |
+--------------------------------+----------------------------------------------------+
| inout vec2 **VERTEX** | Vertex, in image space. |
+--------------------------------+----------------------------------------------------+
| inout vec2 **UV** | Normalized texture coordinates. Range from 0 to 1. |
+--------------------------------+----------------------------------------------------+
| inout vec4 **COLOR** | Color from vertex primitive. |
+--------------------------------+----------------------------------------------------+
| inout float **POINT_SIZE** | Point size for point drawing. |
+--------------------------------+----------------------------------------------------+
Fragment built-ins
^^^^^^^^^^^^^^^^^^
@@ -182,7 +164,8 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D
| | For a Sprite2D with a texture of size 64x32px, |
| | **TEXTURE_PIXEL_SIZE** = :code`vec2(1/64, 1/32)` |
+---------------------------------------------+---------------------------------------------------------------+
| in bool **AT_LIGHT_PASS** | ``true`` if this is a light pass. |
| in bool **AT_LIGHT_PASS** | If using the compatibility render, ``true`` if this is a |
| | light pass. Otherwise ``false``. |
+---------------------------------------------+---------------------------------------------------------------+
| sampler2D **SPECULAR_SHININESS_TEXTURE** | |
+---------------------------------------------+---------------------------------------------------------------+
@@ -203,11 +186,11 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D
+---------------------------------------------+---------------------------------------------------------------+
| out float **NORMAL_MAP_DEPTH** | Normalmap depth for scaling. |
+---------------------------------------------+---------------------------------------------------------------+
| inout vec2 **VERTEX** | |
| inout vec2 **VERTEX** | Pixel position in screen space. |
+---------------------------------------------+---------------------------------------------------------------+
| inout vec2 **SHADOW_VERTEX** | |
| inout vec2 **SHADOW_VERTEX** | Same as ``VERTEX`` but can be written to alter shadows. |
+---------------------------------------------+---------------------------------------------------------------+
| inout vec3 **LIGHT_VERTEX** | |
| inout vec3 **LIGHT_VERTEX** | Same as ``VERTEX`` but can be written to alter lighting. |
+---------------------------------------------+---------------------------------------------------------------+
| inout vec4 **COLOR** | Color from vertex function and output fragment color. If |
| | unused, will be set to **TEXTURE** color. |
@@ -216,52 +199,69 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D
Light built-ins
^^^^^^^^^^^^^^^
Light processor functions work differently in 2D than they do in 3D. In CanvasItem shaders, the
Light processor functions work differently when using the compatibility renderer then they do when
using the rendering device based renderers. when using the compatibility renderer, the
shader is called once for the object being drawn, and then once for each light touching that
object in the scene. Use render_mode ``unshaded`` if you do not want any light passes to occur
for that object. Use render_mode ``light_only`` if you only want light passes to occur for
that object; this can be useful when you only want the object visible where it is covered by light.
When the shader is on a light pass, the ``AT_LIGHT_PASS`` variable will be ``true``.
When using the compatibility renderer and the shader is on a light pass, the ``AT_LIGHT_PASS``
variable will be ``true``. When using one of the other renderers ``AT_LIGHT_PASS`` will always be false.
+--------------------------------+------------------------------------------------------------------------------+
| Built-in | Description |
+================================+==============================================================================+
| in vec4 **FRAGCOORD** | Coordinate of pixel center. In screen space. ``xy`` specifies |
| | position in window, ``z`` specifies fragment depth if |
| | ``DEPTH`` is not used. Origin is lower-left. |
+--------------------------------+------------------------------------------------------------------------------+
| in vec3 **NORMAL** | Input Normal. Although this value is passed in, |
| | **normal calculation still happens outside of this function**. |
+--------------------------------+------------------------------------------------------------------------------+
| in vec4 **COLOR** | Input Color. |
| | This is the output of the fragment function with final modulation applied. |
+--------------------------------+------------------------------------------------------------------------------+
| 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 **SCREEN_UV** | **SCREEN_TEXTURE** Coordinate (for using with screen texture). |
+--------------------------------+------------------------------------------------------------------------------+
| in vec2 **POINT_COORD** | UV for Point Sprite. |
+--------------------------------+------------------------------------------------------------------------------+
| in vec4 **LIGHT_COLOR** | Color of Light. |
+--------------------------------+------------------------------------------------------------------------------+
| in vec3 **LIGHT_POSITION** | Position of Light. |
+--------------------------------+------------------------------------------------------------------------------+
| in vec3 **LIGHT_VERTEX** | |
+--------------------------------+------------------------------------------------------------------------------+
| inout vec4 **LIGHT** | Value from the Light texture and output color. Can be modified. If not used, |
| | the light function is ignored. |
+--------------------------------+------------------------------------------------------------------------------+
| in vec4 **SPECULAR_SHININESS** | |
+--------------------------------+------------------------------------------------------------------------------+
| out vec4 **SHADOW_MODULATE** | |
+--------------------------------+------------------------------------------------------------------------------+
Below is an example of a light shader that takes a CanvasItem's normal map into account:
.. code-block:: glsl
void light() {
float cNdotL = max(0.0, dot(NORMAL, LIGHT_DIRECTION));
LIGHT = vec4(LIGHT_COLOR.rgb * COLOR.rgb * LIGHT_ENERGY * cNdotL, LIGHT_COLOR.a);
}
+----------------------------------+------------------------------------------------------------------------------+
| Built-in | Description |
+==================================+==============================================================================+
| in vec4 **FRAGCOORD** | Coordinate of pixel center. In screen space. ``xy`` specifies |
| | position in window, ``z`` specifies fragment depth if |
| | ``DEPTH`` is not used. Origin is lower-left. |
+----------------------------------+------------------------------------------------------------------------------+
| in vec3 **NORMAL** | Input Normal. |
+----------------------------------+------------------------------------------------------------------------------+
| in vec4 **COLOR** | Input Color. |
| | This is the output of the fragment function with final modulation applied. |
+----------------------------------+------------------------------------------------------------------------------+
| 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 **SCREEN_UV** | **SCREEN_TEXTURE** Coordinate (for using with screen texture). |
+----------------------------------+------------------------------------------------------------------------------+
| in vec2 **POINT_COORD** | UV for Point Sprite. |
+----------------------------------+------------------------------------------------------------------------------+
| in vec4 **LIGHT_COLOR** | Color of Light. |
+----------------------------------+------------------------------------------------------------------------------+
| in vec3 **LIGHT_ENERGY** | Energy multiplier of Light. |
+----------------------------------+------------------------------------------------------------------------------+
| in vec3 **LIGHT_POSITION** | Position of Light in screen space. If using a ``DirectionalLight2D`` |
| | this is always ``vec3(0,0,0)``. |
+----------------------------------+------------------------------------------------------------------------------+
| in vec3 **LIGHT_DIRECTION** | Direction of Light in screen space. |
+----------------------------------+------------------------------------------------------------------------------+
| in vec3 **LIGHT_IS_DIRECTIONAL** | ``true`` if this pass is a ``DirectionalLight2D``. |
+----------------------------------+------------------------------------------------------------------------------+
| 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. |
+----------------------------------+------------------------------------------------------------------------------+
| in vec4 **SPECULAR_SHININESS** | |
+----------------------------------+------------------------------------------------------------------------------+
| out vec4 **SHADOW_MODULATE** | |
+----------------------------------+------------------------------------------------------------------------------+
SDF functions
^^^^^^^^^^^^^