From f911b1310a3e85300bab851473acea47ae9305f9 Mon Sep 17 00:00:00 2001 From: tetrapod00 <145553014+tetrapod00@users.noreply.github.com> Date: Sun, 27 Oct 2024 15:52:59 -0700 Subject: [PATCH 1/3] Add note about uniform buffer size limit to Shading Language --- .../shaders/shader_reference/shading_language.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index bb3200be739..10c2db72d99 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -793,6 +793,19 @@ GDScript: in the shader. It must match *exactly* to the name of the uniform in the shader or else it will not be recognized. +.. note:: There is a limit to the total size of shader uniforms that you can use + in a single shader. On most desktop platforms, this limit is ``65536`` + bytes, or 4096 ``vec4`` uniforms. On mobile platforms, the limit is + typically ``16384`` bytes, or 1024 ``vec4`` uniforms. Vector uniforms + smaller than a ``vec4``, such as ``vec2`` or ``vec3``, are padded to + the size of a ``vec4``. Scalar uniforms such as ``int`` or ``float`` + are not padded, and ``bool`` is padded to the size of an ``int``. + + Arrays count as the total size of their contents. If you need a uniform + array that is larger than this limit, consider packing the data into a + texture instead, since the *contents* of a texture do not count towards + this limit, only the size of the sampler uniform. + Any GLSL type except for *void* can be a uniform. Additionally, Godot provides optional shader hints to make the compiler understand for what the uniform is used, and how the editor should allow users to modify it. From c2d020610b8c2fae6fd679587874afa3379c923d Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Tue, 29 Oct 2024 15:15:43 +0100 Subject: [PATCH 2/3] Tweak constant example in Shading language to avoid referring to reserved `PI` --- tutorials/shaders/shader_reference/shading_language.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 10c2db72d99..539666feab9 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -383,7 +383,7 @@ accessible outside of the shader. shader_type spatial; - const float PI = 3.14159265358979323846; + const float GOLDEN_RATIO = 1.618033988749894; Constants of the ``float`` type must be initialized using ``.`` notation after the decimal part or by using the scientific notation. The optional ``f`` post-suffix is @@ -800,7 +800,7 @@ GDScript: smaller than a ``vec4``, such as ``vec2`` or ``vec3``, are padded to the size of a ``vec4``. Scalar uniforms such as ``int`` or ``float`` are not padded, and ``bool`` is padded to the size of an ``int``. - + Arrays count as the total size of their contents. If you need a uniform array that is larger than this limit, consider packing the data into a texture instead, since the *contents* of a texture do not count towards From 4fd1d2377fe808fc63ba5d694740c7a9ef28a0fc Mon Sep 17 00:00:00 2001 From: tetrapod00 <145553014+tetrapod00@users.noreply.github.com> Date: Thu, 17 Oct 2024 23:00:16 -0700 Subject: [PATCH 3/3] Clarify COLOR and TEXTURE in CanvasItem shaders --- .../shader_reference/canvas_item_shader.rst | 59 ++++++++++++++++--- 1 file changed, 50 insertions(+), 9 deletions(-) diff --git a/tutorials/shaders/shader_reference/canvas_item_shader.rst b/tutorials/shaders/shader_reference/canvas_item_shader.rst index 8a9f081e9fe..dd85b3588e9 100644 --- a/tutorials/shaders/shader_reference/canvas_item_shader.rst +++ b/tutorials/shaders/shader_reference/canvas_item_shader.rst @@ -142,15 +142,56 @@ is usually: Fragment built-ins ^^^^^^^^^^^^^^^^^^ -Certain Nodes (for example, :ref:`Sprite2Ds `) display a texture -by default. However, when a custom fragment function is attached to these nodes, -the texture lookup needs to be done manually. Godot provides the texture color -in the ``COLOR`` built-in variable multiplied by the node's color. To read the -texture color by itself, you can use: +COLOR and TEXTURE +~~~~~~~~~~~~~~~~~ + +The built-in variable ``COLOR`` is used for a few things: + + - In the ``vertex()`` function, ``COLOR`` contains the color from the vertex + primitive multiplied by the CanvasItem's + :ref:`modulate` multiplied by the + CanvasItem's :ref:`self_modulate`. + - In the ``fragment()`` function, the input value ``COLOR`` is that same value + multiplied by the color from the default ``TEXTURE`` (if present). + - In the ``fragment()`` function, ``COLOR`` is also the final output. + +Certain nodes (for example, :ref:`Sprite2D `) display a texture +by default, for example :ref:`texture `. When +using a custom ``fragment()`` function, you have a few options on how to sample +this texture. + +To read only the contents of the default texture, ignoring the vertex ``COLOR``: + +.. code-block:: glsl + + void fragment() { + COLOR = texture(TEXTURE, UV); + } + +To read the contents of the default texture multiplied by vertex ``COLOR``: .. code-block:: glsl - COLOR = texture(TEXTURE, UV); + void fragment() { + // Equivalent to an empty fragment() function, since COLOR is also the output variable. + COLOR = COLOR; + } + +To read only the vertex ``COLOR`` in ``fragment()``, ignoring the main texture, +you must pass ``COLOR`` as a varying, then read it in ``fragment()``: + +.. code-block:: glsl + + varying vec4 vertex_color; + void vertex() { + vertex_color = COLOR; + } + void fragment() { + COLOR = vertex_color; + } + +NORMAL +~~~~~~ Similarly, if a normal map is used in the :ref:`CanvasTexture `, Godot uses it by default and assigns its value to the built-in ``NORMAL`` variable. If you are using a normal @@ -175,7 +216,7 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D +---------------------------------------------+---------------------------------------------------------------+ | in vec2 **TEXTURE_PIXEL_SIZE** | Normalized pixel size of default 2D texture. | | | For a Sprite2D with a texture of size 64x32px, | -| | **TEXTURE_PIXEL_SIZE** = ``vec2(1/64, 1/32)`` | +| | ``TEXTURE_PIXEL_SIZE`` = ``vec2(1/64, 1/32)`` | +---------------------------------------------+---------------------------------------------------------------+ | in bool **AT_LIGHT_PASS** | Always ``false``. | +---------------------------------------------+---------------------------------------------------------------+ @@ -206,8 +247,8 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D | inout vec3 **LIGHT_VERTEX** | Same as ``VERTEX`` but can be written to alter lighting. | | | Z component represents height. | +---------------------------------------------+---------------------------------------------------------------+ -| inout vec4 **COLOR** | Color from vertex function multiplied by the **TEXTURE** | -| | color. Also output color value. | +| inout vec4 **COLOR** | ``COLOR`` from the ``vertex()`` function multiplied by the | +| | ``TEXTURE`` color. Also output color value. | +---------------------------------------------+---------------------------------------------------------------+ Light built-ins