Merge pull request #8329 from Calinou/screen-reading-shaders-screen-texture-mipmaps

Emphasize the importance of mipmaps for `textureLod()` in Screen-reading shaders

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 <class_Sprite2D>` of a sheep.
 
@@ -60,6 +61,8 @@ shader by `arlez80 <https://bitbucket.org/arlez80/hex-mosaic/src/master/>`_,
     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() {

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

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)                                                                  |                                                                     |

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;