From 9773552257df0bea21748ee7c87c6215e9756d39 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Thu, 26 Oct 2023 02:25:20 +0200 Subject: [PATCH] Emphasize the importance of mipmaps for `textureLod()` in Screen-reading shaders This also mentions that reading the normal/roughness buffer is only currently supported in Forward+. --- tutorials/shaders/custom_postprocessing.rst | 7 +++++-- tutorials/shaders/screen-reading_shaders.rst | 11 +++++++++++ .../shaders/shader_reference/shading_language.rst | 10 +++++----- tutorials/shaders/shaders_style_guide.rst | 5 ++--- 4 files changed, 23 insertions(+), 10 deletions(-) diff --git a/tutorials/shaders/custom_postprocessing.rst b/tutorials/shaders/custom_postprocessing.rst index f66992546af..937cd3a717c 100644 --- a/tutorials/shaders/custom_postprocessing.rst +++ b/tutorials/shaders/custom_postprocessing.rst @@ -40,8 +40,9 @@ Your scene tree will look something like this: As of the time of writing, Godot does not support rendering to multiple buffers at the same time. Your post-processing shader will not have access - to normals or other render passes. You only have access to the rendered - frame. + to other render passes and buffers not exposed by Godot (such as depth or + normal/roughness). You only have access to the rendered frame and buffers + exposed by Godot as samplers. For this demo, we will use this :ref:`Sprite ` of a sheep. @@ -60,6 +61,8 @@ shader by `arlez80 `_, shader_type canvas_item; uniform vec2 size = vec2(32.0, 28.0); + // If you intend to read from mipmaps with `textureLod()` LOD values greater than `0.0`, + // use `filter_nearest_mipmap` instead. This shader doesn't require it. uniform sampler2D screen_texture : hint_screen_texture, repeat_disable, filter_nearest; void fragment() { diff --git a/tutorials/shaders/screen-reading_shaders.rst b/tutorials/shaders/screen-reading_shaders.rst index 6e784564272..ec39a60a52f 100644 --- a/tutorials/shaders/screen-reading_shaders.rst +++ b/tutorials/shaders/screen-reading_shaders.rst @@ -44,6 +44,12 @@ the third argument to ``textureLod`` and change the hint ``filter_nearest`` to filter with mipmaps, Godot will automatically calculate the blurred texture for you. +.. warning:: + + If the filter mode is not changed to a filter mode that contains ``mipmap`` in its name, + ``textureLod`` with a LOD parameter greater than ``0.0`` will have the same appearance + as with the ``0.0`` LOD parameter. + Screen texture example ~~~~~~~~~~~~~~~~~~~~~~ @@ -163,6 +169,11 @@ The following code retrieves the 3D position below the pixel being drawn: Normal-roughness texture ~~~~~~~~~~~~~~~~~~~~~~~~ +.. note:: + + Normal-roughness texture is only supported in the Forward+ rendering method, + not Mobile or Compatibility. + Similarly, the normal-roughness texture can be used to read the normals and roughness of objects rendered in the depth prepass. The normal is stored in the ``.xyz`` channels (mapped to the 0-1 range) while the roughness is stored in the diff --git a/tutorials/shaders/shader_reference/shading_language.rst b/tutorials/shaders/shader_reference/shading_language.rst index 40afc2af081..2f7db8f1f87 100644 --- a/tutorials/shaders/shader_reference/shading_language.rst +++ b/tutorials/shaders/shader_reference/shading_language.rst @@ -797,7 +797,7 @@ Full list of hints below: +----------------------+--------------------------------------------------+-----------------------------------------------------------------------------+ | **sampler2D** | hint_depth_texture | Texture is the depth texture. | +----------------------+--------------------------------------------------+-----------------------------------------------------------------------------+ -| **sampler2D** | hint_normal_roughness_texture | Texture is the normal roughness texture. | +| **sampler2D** | hint_normal_roughness_texture | Texture is the normal roughness texture (only supported in Forward+). | +----------------------+--------------------------------------------------+-----------------------------------------------------------------------------+ GDScript uses different variable types than GLSL does, so when passing variables @@ -1285,8 +1285,8 @@ is used, it can be scalar or vector. | gvec4_type **textureLod** (gsampler2D s, vec2 p, float lod) | Perform a texture read at custom mipmap. | | | | | gvec4_type **textureLod** (gsampler2DArray s, vec3 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | -| | will use the full resolution texture. | -| gvec4_type **textureLod** (gsampler3D s, vec3 p, float lod) | | +| | will use the full resolution texture. If the texture lacks mipmaps, | +| gvec4_type **textureLod** (gsampler3D s, vec3 p, float lod) | all LOD values will act like ``0.0``. | | | | | vec4 **textureLod** (samplerCube s, vec3 p, float lod) | | | | | @@ -1295,8 +1295,8 @@ is used, it can be scalar or vector. | gvec4_type **textureProjLod** (gsampler2D s, vec3 p, float lod) | Performs a texture read with projection/LOD. | | | | | gvec4_type **textureProjLod** (gsampler2D s, vec4 p, float lod) | The LOD defines which mipmap level is used. An LOD value of ``0.0`` | -| | will use the full resolution texture. | -| gvec4_type **textureProjLod** (gsampler3D s, vec4 p, float lod) | | +| | will use the full resolution texture. If the texture lacks mipmaps, | +| gvec4_type **textureProjLod** (gsampler3D s, vec4 p, float lod) | all LOD values will act like ``0.0``. | +-----------------------------------------------------------------------------+---------------------------------------------------------------------+ | gvec4_type **textureGrad** (gsampler2D s, vec2 p, vec2 dPdx, | Performs a texture read with explicit gradients. | | vec2 dPdy) | | diff --git a/tutorials/shaders/shaders_style_guide.rst b/tutorials/shaders/shaders_style_guide.rst index 107de14f703..9416d791978 100644 --- a/tutorials/shaders/shaders_style_guide.rst +++ b/tutorials/shaders/shaders_style_guide.rst @@ -30,14 +30,13 @@ Here is a complete shader example based on these guidelines: shader_type canvas_item; // Screen-space shader to adjust a 2D scene's brightness, contrast // and saturation. Taken from - // https://github.com/godotengine/godot-demo-projects/blob/master/2d/screen_space_shaders/shaders/BCS.shader + // https://github.com/godotengine/godot-demo-projects/blob/master/2d/screen_space_shaders/shaders/BCS.gdshader + uniform sampler2D screen_texture : hint_screen_texture, filter_linear_mipmap; uniform float brightness = 0.8; uniform float contrast = 1.5; uniform float saturation = 1.8; - uniform sampler2D screen_texture : hint_screen_texture, repeat_disable, filter_nearest; - void fragment() { vec3 c = textureLod(screen_texture, SCREEN_UV, 0.0).rgb;