Merge pull request godotengine#8285 from Calinou/environment-glow-2d

Document glow in 2D in Environment and post-processing

Author: mhilbrunner

about/list_of_features.rst

@@ -142,6 +142,8 @@ Rendering
 - GPU-based :ref:`particles <doc_particle_systems_2d>` with support for
   :ref:`custom particle shaders <doc_particle_shader>`.
 - CPU-based particles.
+- Optional :ref:`2D HDR rendering <doc_environment_and_post_processing_using_glow_in_2d>`
+  for better glow capabilities.
 
 2D tools
 --------
@@ -340,6 +342,7 @@ Rendering
 - Glow/bloom with optional bicubic upscaling and several blend modes available:
   Screen, Soft Light, Add, Replace, Mix.
 - Glow can have a colored dirt map texture, acting as a lens dirt effect.
+- Glow can be :ref:`used as a screen-space blur effect <doc_environment_and_post_processing_using_glow_to_blur_the_screen>`.
 - Color correction using a one-dimensional ramp or a 3D LUT texture.
 - Roughness limiter to reduce the impact of specular aliasing.
 - Brightness, contrast and saturation adjustments.

tutorials/3d/environment_and_post_processing.rst

@@ -88,9 +88,9 @@ Camera attributes
     adjusting those properties independently of other Environment settings more
     easily.
 
-The :ref:`class_CameraAttributes` resource stores exposure and depth of field information. It
-also allows enabling automatic exposure adjustments depending on scene
-brightness.
+The :ref:`class_CameraAttributes` resource stores exposure and depth of field
+information. It also allows enabling automatic exposure adjustments depending on
+scene brightness.
 
 There are two kinds of CameraAttribute resources available:
 
@@ -152,7 +152,9 @@ There are several background modes available:
 - **Sky** lets you define a background sky material (see below). By default,
   objects in the scene will reflect this sky material and absorb ambient light
   from it.
-- **Canvas** displays the 2D scene as a background to the 3D scene.
+- **Canvas** displays the 2D scene as a background to the 3D scene. This can be used
+  to make environment effects visible on 2D rendering, such as
+  :ref:`glow in 2D <doc_environment_and_post_processing_using_glow_in_2d>`.
 - **Keep** does not draw any sky, keeping what was present on previous frames
   instead. This improves performance in purely indoor scenes, but creates a
   "hall of mirrors" visual glitch if the sky is visible at any time.
@@ -544,6 +546,9 @@ illumination for off-screen elements (unlike :abbr:`SSIL (Screen-Space Indirect
 Glow
 ^^^^
 
+*This feature is only available when using the Forward+ and Mobile backends, not
+Compatibility.*
+
 In photography and film, when light amount exceeds the maximum *luminance*
 (brightness) supported by the media, it generally bleeds outwards to darker
 regions of the image. This is simulated in Godot with the **Glow** effect.
@@ -586,8 +591,9 @@ The **Blend Mode** of the effect can also be changed:
   an all around.
 - **Softlight** is the default and weakest one, producing only a subtle color
   disturbance around the objects. This mode works best on dark scenes.
-- **Replace** can be used to blur the whole screen or debug the effect. It only
-  shows the glow effect without the image below.
+- **Replace** can be used to
+  :ref:`blur the whole screen <doc_environment_and_post_processing_using_glow_to_blur_the_screen>`
+  or debug the effect. It only shows the glow effect without the image below.
 - **Mix** mixes the glow effect with the main image. This can be used for
   greater artistic control. The mix factor is controlled by the **Mix** property
   which appears above the blend mode (only when the blend mode is set to Mix).
@@ -619,11 +625,68 @@ There are 2 main use cases for a glow map texture:
 
 .. image:: img/environment_glow_map.webp
 
-.. note::
+.. _doc_environment_and_post_processing_using_glow_in_2d:
+
+Using glow in 2D
+^^^^^^^^^^^^^^^^
+
+There are 2 ways to use glow in 2D:
+
+- Since Godot 4.2, you can enable HDR for 2D rendering when using the Forward+
+  and Mobile rendering methods. This has a performance cost, but it allows for a
+  greater dynamic range. This also allows you to control which objects glow
+  using their individual **Modulate** or **Self Modulate** properties (use the
+  RAW mode in the color picker). Enabling HDR can also reduce banding in the 2D
+  rendering output.
+
+  - To enable HDR in 2D, open the Project Settings, enable
+    **Rendering > Viewport > HDR 2D** then restart the editor.
+
+- If you want to maximize performance, you can leave HDR disabled for 2D
+  rendering. However, you will have less control on which objects glow.
+
+  - Enable glow, set the environment background mode to **Canvas** then decrease
+    **Glow HDR Threshold** so that pixels that are not overbright will still
+    glow. To prevent UI elements from glowing, make them children of a
+    :ref:`class_CanvasLayer` node. You can control which layers are affected by
+    glow using the **Background > Canvas Max Layer** property of the Environment
+    resource.
+
+.. figure:: img/environment_and_post_processing_glow_in_2d.webp
+   :align: center
+   :alt: Example of using glow in a 2D scene
 
-    Glow can be used in 2D as well. To do so, set the environment background
-    mode to **Canvas** then enable glow as usual. You may have to decrease
-    **Glow HDR Threshold** to see a difference.
+   Example of using glow in a 2D scene. HDR 2D is enabled, while coins and the
+   bullet have their **Modulate** property increased to overbright values using the
+   RAW mode in the color picker.
+
+.. _doc_environment_and_post_processing_using_glow_to_blur_the_screen:
+
+Using glow to blur the screen
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Glow can be used to blur the whole viewport, which is useful for background blur
+when a menu is open. Only 3D rendering will be affected unless the environment's
+background mode is set to **Canvas**. To prevent UI elements from being blurred
+when using the Canvas background mode, make them children of a :ref:`class_CanvasLayer`
+node. You can control which layers are affected by this blurring effect using the
+**Background > Canvas Max Layer** property of the Environment resource.
+
+To use glow as a blurring solution:
+
+- Enable **Normalized** and adjust levels according to preference. Increasing
+  higher level indices will result in a more blurred image. It's recommended to
+  leave a single glow level at ``1.0`` and leave all other glow levels at
+  ``0.0``, but this is not required. Note that the final appearance will vary
+  depending on viewport resolution.
+- Set **Intensity** to ``1.0`` and **Bloom** to ``1.0``.
+- Set the blend mode to **Replace** and **HDR Luminance Cap** to ``1.0``.
+
+.. figure:: img/environment_and_post_processing_glow_blur.webp
+   :align: center
+   :alt: Example of using glow to blur the 2D rendering in the menu's background
+
+   Example of using glow to blur the 2D rendering in the menu's background
 
 Adjustments
 ^^^^^^^^^^^
@@ -717,7 +780,8 @@ a given range. It has an initial **Distance** with a **Transition** region
 .. image:: img/environment_dof_far.webp
 
 The **Amount** parameter controls the amount of blur. For larger blurs, tweaking
-the **Quality** may be needed in order to avoid artifacts.
+the depth of field quality in the advanced project settings may be needed to
+avoid artifacts.
 
 Depth of Field / Near Blur
 ^^^^^^^^^^^^^^^^^^^^^^^^^^