Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify use of source_color in Shading Language #10119

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 24 additions & 15 deletions tutorials/shaders/shader_reference/shading_language.rst
Original file line number Diff line number Diff line change
Expand Up @@ -780,7 +780,7 @@ Uniforms
Passing values to shaders is possible. These are global to the whole shader and
are called *uniforms*. When a shader is later assigned to a material, the
uniforms will appear as editable parameters in it. Uniforms can't be written
from within the shader.
from within the shader. Any GLSL type except for ``void`` can be a uniform.

.. code-block:: glsl
Expand All @@ -803,9 +803,12 @@ GDScript:
in the shader. It must match *exactly* to the name of the uniform in
the shader or else it will not be recognized.

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.

Uniform hints
~~~~~~~~~~~~~

Additionally, Godot provides optional uniform hints to make the compiler understand
what the uniform is used for, and how the editor should allow users to modify it.

.. code-block:: glsl
Expand All @@ -816,20 +819,26 @@ used, and how the editor should allow users to modify it.
uniform vec4 other_color : source_color = vec4(1.0); // Default values go after the hint.
uniform sampler2D image : source_color;
It's important to understand that textures *that are supplied as color* require
hints for proper sRGB -> linear conversion (i.e. ``source_color``), as Godot's
3D engine renders in linear color space. If this is not done, the texture will
appear washed out.
.. admonition:: Source Color
Copy link
Contributor Author

@tetrapod00 tetrapod00 Oct 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the first use of an admonition note with a custom title in the whole docs repo. I think it makes this more readable, but if this is against some style guide I can change this to use a subheader or standard note block instead.

It renders as something like this:
firefox_gk9XGAXHlj


.. note::
Any texture which contains *sRGB color data* requires a ``source_color`` hint
in order to be correctly sampled. This is because Godot renders in linear
color space, but some textures contain sRGB color data. If this hint is not
used, the texture will appear washed out.

Albedo and color textures should have a ``source_color`` hint. Normal,
roughness, metallic, and height textures typically do not need a ``source_color``
hint.

Using ``source_color`` hint is required in the Forward+ and Mobile renderers,
and in ``canvas_item`` shaders when :ref:`HDR 2D<class_ProjectSettings_property_rendering/viewport/hdr_2d>`
is enabled. The ``source_color`` hint is optional for the Compatibility renderer, and for ``canvas_item``
shaders if ``HDR 2D`` is disabled. However, it is recommended to always use
the ``source_color`` hint, because it works even if you change renderers or
disable ``HDR 2D``.

The 2D renderer also renders in linear color space if the
**Rendering > Viewport > HDR 2D** project setting is enabled, so
``source_color`` must also be used in ``canvas_item`` shaders. If 2D HDR is
disabled, ``source_color`` will keep working correctly in ``canvas_item``
shaders, so it's recommend to use it either way.

Full list of hints below:
Full list of uniform hints below:

+----------------------+--------------------------------------------------+-----------------------------------------------------------------------------+
| Type | Hint | Description |
Expand Down