Merge pull request #6267 from Calinou/add-antialiasing-docs

Add documentation pages on 2D and 3D antialiasing

about/list_of_features.rst

@@ -156,12 +156,6 @@ Vulkan 1.0, with Vulkan 1.1 and 1.2 features optionally used.
 - Perspective, orthographic and frustum-offset cameras.
 - When using the Vulkan Clustered backend (default on desktop), a depth prepass
   is used to improve performance in complex scenes by reducing the cost of overdraw.
-- Support for rendering 3D at a lower resolution while keeping 2D rendering at
-  the original scale. This can be used to improve performance on low-end systems
-  or improve visuals on high-end systems.
-
-  - 3D rendering can be scaled with bilinear filtering or
-    `AMD FidelityFX Super Resolution 1.0 <https://www.amd.com/en/technologies/fidelityfx-super-resolution>`__.
 
 - `OpenGL support planned for a future Godot 4.x release <https://godotengine.org/article/about-godot4-vulkan-gles3-and-gles2>`__.
 
@@ -331,12 +325,23 @@ Vulkan 1.0, with Vulkan 1.1 and 1.2 features optionally used.
 
 **Anti-aliasing:**
 
+- Temporal antialiasing (TAA).
+- Multi-sample antialiasing (MSAA), for both :ref:`doc_2d_antialiasing` and :ref:`doc_3d_antialiasing`.
 - Fast approximate antialiasing (FXAA).
-- Multi-sample antialiasing (MSAA).
 - Super-sample antialiasing (SSAA) using bilinear 3D scaling and a 3D resolution scale above 1.0.
-- Alpha antialiasing, alpha to coverage and alpha hashing on a per-material basis.
+- Alpha antialiasing, MSAA alpha to coverage and alpha hashing on a per-material basis.
+
+**Resolution scaling:**
+
+- Support for rendering 3D at a lower resolution while keeping 2D rendering at
+  the original scale. This can be used to improve performance on low-end systems
+  or improve visuals on high-end systems.
+- Resolution scaling uses bilinear filtering or AMD FidelityFX Super Resolution
+  1.0 (FSR).
+- Texture mipmap LOD bias is adjusted automatically to improve quality at lower
+  resolution scales. It can also be modified with a manual offset.
 
-Most of these effects can be adjusted for better performance or to further
+Most effects listed above can be adjusted for better performance or to further
 improve quality. This can be helpful when using Godot for offline rendering.
 
 3D tools

tutorials/2d/2d_antialiasing.rst

@@ -0,0 +1,94 @@
+.. _doc_2d_antialiasing:
+
+2D antialiasing
+===============
+
+.. Images on this page were generated using the project below
+.. (except for `antialiasing_none_scaled.webp`):
+.. https://github.com/Calinou/godot-antialiasing-comparison
+
+.. seealso::
+
+    Godot also supports antialiasing in 3D rendering. This is covered on the
+    :ref:`doc_3d_antialiasing` page.
+
+Introduction
+------------
+
+Due to their limited resolution, scenes rendered in 2D can exhibit aliasing
+artifacts. These artifacts usually manifest in the form of a "staircase" effect on
+geometry edges, and are most noticeable when using nodes such as :ref:`class_Line2D`,
+:ref:`class_Polygon2D` or :ref:`class_TextureProgressBar`. :ref:`doc_custom_drawing_in_2d`
+can also have aliasing artifacts for methods that don't support antialiasing.
+
+In the example below, you can notice how
+edges have a blocky appearance:
+
+.. figure:: img/antialiasing_none_scaled.webp
+   :alt: Image is scaled by 2× with nearest-neighbor filtering to make aliasing more noticeable.
+   :align: center
+
+   Image is scaled by 2× with nearest-neighbor filtering to make aliasing more noticeable.
+
+To combat this, Godot supports several methods of enabling antialiasing on 2D rendering.
+
+Antialiasing property in Line2D and custom drawing
+--------------------------------------------------
+
+This is the recommended method, as it has a lower performance impact in most cases.
+
+Line2D has an **Antialiased** property which you can enable in the inspector.
+Also, several methods for :ref:`doc_custom_drawing_in_2d` support an optional
+``antialiased`` parameter, which can be set to ``true`` when calling the
+function.
+
+These methods do not require MSAA to be enabled, which makes their *baseline*
+performance cost low. In other words, there is no permanent added cost if you're
+not drawing any antialiased geometry at some point.
+
+The downside of these antialiasing methods is that they work by generating
+additional geometry. If you're generating complex 2D geometry that's updated
+every frame, this may be a bottleneck. Also, Polygon2D, TextureProgressBar, and
+several custom drawing methods don't feature an antialiased property. For these
+nodes, you can use 2D multisample antialiasing instead.
+
+Multisample antialiasing (MSAA)
+-------------------------------
+
+Before enabling MSAA in 2D, it's important to understand what MSAA will operate
+on. MSAA in 2D follows similar restrictions as in 3D. While it does not
+introduce any blurriness, its scope of application is limited. The main
+applications of 2D MSAA are:
+
+- Geometry edges, such as line and polygon drawing.
+- Sprite edges *only for pixels touching one of the texture's edges*. This works
+  for both linear and nearest-neighbor filtering. Sprite edges created using
+  transparency on the image are not affected by MSAA.
+
+The downside of MSAA is that it only operates on edges. This is because MSAA
+increases the number of *coverage* samples, but not the number of *color*
+samples. However, since the number of color samples did not increase, fragment
+shaders are still run for each pixel only once. As a result, MSAA will **not
+affect** the following kinds of aliasing in any way:
+
+- Aliasing *within* nearest-neighbor filtered textures (pixel art).
+- Aliasing caused by custom 2D shaders.
+- Specular aliasing when using Light2D.
+- Aliasing in font rendering.
+
+MSAA can be enabled in the Project Settings by changing the value of the
+**Rendering > Anti Aliasing > Quality > MSAA 2D** setting. It's important to change
+the value of the **MSAA 2D** setting and not **MSAA 3D**, as these are entirely
+separate settings.
+
+Comparison between no antialiasing (left) and various MSAA levels (right). The
+top-left corner contains a Line2D node, the top-right corner contains 2
+TextureProgressBar nodes. The bottom contains 8 pixel art sprites, with 4 of
+them touching the edges (green background) and 4 of them not touching the edges
+(Godot logo):
+
+.. image:: img/antialiasing_msaa_2x.webp
+
+.. image:: img/antialiasing_msaa_4x.webp
+
+.. image:: img/antialiasing_msaa_8x.webp

tutorials/2d/custom_drawing_in_2d.rst

@@ -450,15 +450,13 @@ Antialiased drawing
 ^^^^^^^^^^^^^^^^^^^
 
 Godot offers method parameters in :ref:`draw_line<class_CanvasItem_method_draw_line>`
-to enable antialiasing, but it doesn't work reliably in all situations
-(for instance, on mobile/web platforms, or when HDR is enabled).
-There is also no ``antialiased`` parameter available in
-:ref:`draw_polygon<class_CanvasItem_method_draw_polygon>`.
-
-As a workaround, install and use the
-`Antialiased Line2D add-on <https://github.com/godot-extended-libraries/godot-antialiased-line2d>`__
-(which also supports antialiased Polygon2D drawing). Note that this add-on relies
-on high-level nodes, rather than low-level ``_draw()`` functions.
+to enable antialiasing, but not all custom drawing methods offer this ``antialiased``
+parameter.
+
+For custom drawing methods that don't provide an ``antialiased`` parameter,
+you can enable 2D MSAA instead, which affects rendering in the entire viewport.
+This provides high-quality antialiasing, but a higher performance cost and only
+on specific elements. See :ref:`doc_2d_antialiasing` for more information.
 
 Tools
 -----

tutorials/2d/index.rst

@@ -14,3 +14,4 @@
    2d_meshes
    custom_drawing_in_2d
    2d_sprite_animation
+   2d_antialiasing

tutorials/3d/3d_antialiasing.rst

@@ -0,0 +1,231 @@
+.. _doc_3d_antialiasing:
+
+3D antialiasing
+===============
+
+.. Images on this page were generated using the project below
+.. (except for `antialiasing_none_scaled.webp`):
+.. https://github.com/Calinou/godot-antialiasing-comparison
+
+.. seealso::
+
+    Godot also supports antialiasing in 2D rendering. This is covered on the
+    :ref:`doc_2d_antialiasing` page.
+
+Introduction
+------------
+
+Due to their limited resolution, scenes rendered in 3D can exhibit aliasing
+artifacts. These artifacts commonly manifest as a "staircase" effect on surface
+edges (edge aliasing) and as flickering and/or sparkles on reflective surfaces
+(specular aliasing).
+
+In the example below, you can notice how
+edges have a blocky appearance. The vegetation is also flickering in and out,
+and thin lines on top of the box have almost disappeared:
+
+.. figure:: img/antialiasing_none_scaled.webp
+   :alt: Image is scaled by 2× with nearest-neighbor filtering to make aliasing more noticeable.
+   :align: center
+
+   Image is scaled by 2× with nearest-neighbor filtering to make aliasing more noticeable.
+
+To combat this, various antialiasing techniques can be used in Godot. These are
+detailed below.
+
+Multisample antialiasing (MSAA)
+-------------------------------
+
+This technique is the "historical" way of dealing with aliasing. MSAA is very
+effective on geometry edges (especially at higher levels). MSAA does not
+introduce any blurriness whatsoever.
+
+MSAA is available in 3 levels: 2×, 4×, 8×. Higher levels are more effective at
+antialiasing edges, but are significantly more demanding. In games with modern
+visuals, sticking to 2× or 4× MSAA is highly recommended as 8× MSAA is usually
+too demanding.
+
+The downside of MSAA is that it only operates on edges. This is because MSAA
+increases the number of *coverage* samples, but not the number of *color*
+samples. However, since the number of color samples did not increase, fragment
+shaders are still run for each pixel only once. Therefore, MSAA does not reduce
+transparency aliasing for materials using the **Alpha Scissor** transparency
+mode (1-bit transparency). MSAA is also ineffective on specular aliasing.
+
+To mitigate aliasing on alpha scissor materials, alpha antialiasing (also called
+*alpha to coverage*) can be enabled on specific materials in the
+StandardMaterial3D or ORMMaterial3D properties. This only has an effect when
+MSAA is used (with any level). Alpha to coverage has a moderate performance
+cost, but it's very effective at reducing aliasing on transparent materials
+without introducing any blurriness.
+
+MSAA can be enabled in the Project Settings by changing the value of the
+**Rendering > Anti Aliasing > Quality > MSAA 3D** setting. It's important to change
+the value of the **MSAA 3D** setting and not **MSAA 2D**, as these are entirely
+separate settings.
+
+Comparison between no antialiasing (left) and various MSAA levels (right).
+Note that alpha antialiasing is not used here:
+
+.. image:: img/antialiasing_msaa_2x.webp
+
+.. image:: img/antialiasing_msaa_4x.webp
+
+.. image:: img/antialiasing_msaa_8x.webp
+
+Temporal antialiasing (TAA)
+---------------------------
+
+*This is only available in the Clustered Forward backend, not the Forward Mobile
+or Compatibility backends.*
+
+Temporal antialiasing works by *converging* the result of previously rendered
+frames into a single, high-quality frame. This is a continuous process that
+works by jittering the position of all vertices in the scene every frame. This
+jittering is done to capture sub-pixel detail and should be unnoticeable except
+in extreme situations.
+
+This technique is commonly used in modern games, as it provides the most
+effective form of antialiasing against specular aliasing and other
+shader-induced artifacts. TAA also provides full support for transparency
+antialiasing.
+
+TAA introduces a small amount of blur when enabled in still scenes, but this
+blurring effect becomes more pronounced when the camera is moving. Another
+downside of TAA is that it can exhibit *ghosting* artifacts behind moving
+objects. Rendering at a higher framerate will allow TAA to converge faster,
+therefore making those ghosting artifacts less visible.
+
+Temporal antialiasing can be enabled in the Project Settings by changing the
+value of the **Rendering > Anti Aliasing > Quality > Use Taa** setting.
+
+Comparison between no antialiasing (left) and TAA (right):
+
+.. image:: img/antialiasing_taa.webp
+
+Fast approximate antialiasing (FXAA)
+------------------------------------
+
+*This is only available in the Clustered Forward and Forward Mobile backends,
+not the Compatibility backend.*
+
+Fast approximate antialiasing is a post-processing antialiasing solution. It is
+faster to run than any other antialiasing technique and also supports
+antialiasing transparency. However, since it lacks temporal information, it will
+not do much against specular aliasing.
+
+This technique is still sometimes used in mobile games. However, on desktop
+platforms, FXAA generally fell out of fashion in favor of temporal antialiasing,
+which is much more effective against specular aliasing. Nonetheless, exposing FXAA
+as an in-game option may still be worthwhile for players with low-end GPUs.
+
+FXAA introduces a moderate amount of blur when enabled (more than TAA when
+still, but less than TAA when the camera is moving).
+
+FXAA can be enabled in the Project Settings by changing the
+value of the **Rendering > Anti Aliasing > Quality > Screen Space AA** setting to
+**FXAA**.
+
+Comparison between no antialiasing (left) and FXAA (right):
+
+.. image:: img/antialiasing_fxaa.webp
+
+Supersample antialiasing (SSAA)
+-------------------------------
+
+*This is only available in the Clustered Forward and Forward Mobile backends,
+not the Compatibility backend.*
+
+Supersampling provides the highest quality of antialiasing possible, but it's
+also the most expensive. It works by shading every pixel in the scene multiple
+times. This allows SSAA to antialias edges, transparency *and* specular aliasing
+at the same time, without introducing potential ghosting artifacts.
+
+The downside of SSAA is its *extremely* high cost. This cost generally makes
+SSAA difficult to use for game purposes, but you may still find supersampling
+useful for :ref:`offline rendering <doc_creating_movies>`.
+
+Supersample antialiasing is performed by increasing the **Rendering > Scaling 3D
+> Scale** advanced project setting above ``1.0`` while ensuring
+**Rendering > Scaling 3D > Mode** is set to **Bilinear** (the default).
+Since the scale factor is defined per-axis, a scale factor of ``1.5`` will result
+in 2.25× SSAA while a scale factor of ``2.0`` will result in 4× SSAA.
+
+Comparison between no antialiasing (left) and various SSAA levels (right):
+
+.. image:: img/antialiasing_ssaa_2.25x.webp
+
+.. image:: img/antialiasing_ssaa_4x.webp
+
+.. warning::
+
+    Supersampling also has high video RAM requirements, since it needs to render
+    in the target resolution then *downscale* to the window size. For example,
+    displaying a project in 3840×2160 (4K resolution) with 4× SSAA will require
+    rendering the scene in 7680×4320 (8K resolution), which is 4 times more
+    pixels.
+
+    If you are using a high window size such as 4K, you may find that increasing
+    the resolution scale past a certain value will cause a heavy slowdown (or
+    even a crash) due to running out of VRAM.
+
+Screen-space roughness limiter
+------------------------------
+
+*This is only available in the Clustered Forward and Forward Mobile backends,
+not the Compatibility backend.*
+
+This is not an edge antialiasing method, but it is a way of reducing specular
+aliasing in 3D.
+
+The screen-space roughness limiter works best on detailed geometry. While it has
+an effect on roughness map rendering itself, its impact is limited there.
+
+The screen-space roughness limiter is enabled by default; it doesn't require
+any manual setup. It has a small performance impact, so consider disabling it
+if your project isn't affected by specular aliasing much.
+
+Texture roughness limiter on import
+-----------------------------------
+
+Like the screen-space roughness limiter, this is not an edge antialiasing
+method, but it is a way of reducing specular aliasing in 3D.
+
+Roughness limiting on import works by specifying a normal map to use as a guide
+for limiting roughness. This is done by selecting the roughness map in the
+FileSystem dock, then going to the Import dock and setting **Roughness > Mode**
+to the color channel the roughness map is stored in (typically **Green**), then
+setting the path to the material's normal map. Remember to click **Reimport**
+at the bottom of the Import dock after setting the path to the normal map.
+
+Since this processing occurs purely on import, it has no performance cost
+whatsoever. However, its visual impact is limited. Limiting roughness on import
+only helps reduce specular aliasing within textures, not the aliasing that
+occurs on geometry edges on detailed meshes.
+
+Which antialiasing technique should I use?
+------------------------------------------
+
+**There is no "one size fits all" antialiasing technique.** Since antialiasing is
+often demanding on the GPU or can introduce unwanted blurriness, you'll want to
+add a setting to allow players to disable antialiasing.
+
+For projects with a photorealistic art direction, TAA is generally the most
+suitable option. While TAA can introduce ghosting artifacts, there is no other
+technique that combats specular aliasing as well as TAA does. The screen-space
+roughness limiter helps a little, but is far less effective against specular
+aliasing overall.
+
+For projects with a low amount of reflective surfaces (such as a cartoon
+artstyle), MSAA can work well. MSAA is also a good option if avoiding blurriness
+and temporal artifacts is important, such as in competitive games.
+
+When targeting low-end platforms such as mobile or integrated graphics, FXAA is
+usually the only viable option. 2× MSAA may be usable in some circumstances,
+but higher MSAA levels are unlikely to run smoothly on mobile GPUs.
+
+Godot allows using multiple antialiasing techniques at the same time. This is
+usually unnecessary, but it can provide better visuals on high-end GPUs or for
+:ref:`non-real-time rendering <doc_creating_movies>`. For example, to make
+moving edges look better when TAA is enabled, you can also enable MSAA at the
+same time.

tutorials/3d/3d_rendering_limitations.rst

@@ -95,15 +95,17 @@ this feature. There are still several ways to avoid this problem:
 
 - Only make materials transparent if you actually need it. If a material only
   has a small transparent part, consider splitting it into a separate material.
-  This will allow the opaque part to cast shadows and may also improve
-  performance.
+  This will allow the opaque part to cast shadows and will also improve performance.
 
 - If your texture mostly has fully opaque and fully transparent areas, you can
   use alpha testing instead of alpha blending. This transparency mode is faster
-  to render and doesn't suffer from transparency issues. Enable
-  **Transparency > Transparency** to **Alpha Scissor** in StandardMaterial3D,
-  and adjust **Transparency > Alpha Scissor Threshold** accordingly if needed.
-  Note that MSAA will not anti-alias the texture's edges, but FXAA will.
+  to render and doesn't suffer from transparency issues. Enable **Transparency >
+  Transparency** to **Alpha Scissor** in StandardMaterial3D, and adjust
+  **Transparency > Alpha Scissor Threshold** accordingly if needed. Note that
+  MSAA will not antialias the texture's edges unless alpha antialiasing is
+  enabled in the material's properties. However, FXAA, TAA and supersampling
+  will be able to antialias the texture's edges regardless of whether alpha
+  antialiasing is enabled on the material.
 
 - If you need to render semi-transparent areas of the texture, alpha scissor
   isn't suitable. Instead, setting the StandardMaterial3D's
@@ -112,12 +114,15 @@ this feature. There are still several ways to avoid this problem:
 
 - If you want a material to fade with distance, use the StandardMaterial3D
   distance fade mode **Pixel Dither** or **Object Dither** instead of
-  **PixelAlpha**. This will make the material opaque. This way, it can also
-  cast shadows.
+  **PixelAlpha**. This will make the material opaque, which also speeds up rendering.
 
 Multi-sample antialiasing
 -------------------------
 
+.. seealso::
+
+    Antialiasing is explained in detail on the :ref:`doc_3d_antialiasing` page.
+
 Multi-sample antialiasing (MSAA) takes multiple *coverage* samples at the edges
 of polygons when rendering objects. It does not increase the number of *color*
 samples used to render a scene. Here's what this means in practice:
@@ -130,14 +135,24 @@ There are several ways to work around this limitation depending on your performa
 
 - To make specular aliasing less noticeable, open the Project Settings and enable
   **Rendering > Quality > Screen Space Filters > Screen Space Roughness Limiter**.
-  This filter has a moderate cost on performance. It should be enabled only if
+  This filter has a moderate cost on performance, so it should only be enabled if
   you actually need it.
 
-- Enable FXAA in addition to (or instead of) MSAA. Since FXAA is a screen-space
-  antialiasing method, it will smooth out anything. As a downside, it will also
-  make the scene appear blurrier, especially at resolutions below 1440p.
-
-- Render the scene at a higher resolution, then display it in a ViewportTexture
-  that matches the window size. Make sure to enable **Filter** on the
-  ViewportTexture flags. This technique is called *supersampling* and is very
-  slow. Its use is generally only recommended for offline rendering.
+- Enable fast approximate antialiasing (FXAA) in addition to (or instead of)
+  MSAA. Since FXAA is a screen-space antialiasing method, it will smooth out
+  anything. As a downside, FXAA also makes the scene appear blurrier, especially
+  at resolutions below 1440p. FXAA also lacks temporal information, which means
+  its impact on specular aliasing is limited.
+
+- Enable temporal antialiasing (TAA) in addition to (or instead of) MSAA. Since
+  TAA is a screen-space antialiasing method, it will smooth out anything. As a
+  downside, TAA also makes the scene appear blurrier, especially at resolutions
+  below 1440p. TAA provides superior quality compared to FXAA and can
+  effectively combat specular aliasing. However, TAA has a greater performance
+  cost compared to FXAA, and TAA can introduce ghosting artifacts with fast
+  movement.
+
+- Render the scene at a higher resolution by increasing the **Scaling 3D >
+  Scale** project setting above ``1.0``. This technique is called supersample
+  antialiasing (SSAA) and is very slow. Its use is generally only recommended
+  for offline rendering.

tutorials/3d/index.rst

@@ -14,6 +14,7 @@
    gi_probes
    baked_lightmaps
    environment_and_post_processing
+   3d_antialiasing
    volumetric_fog
    high_dynamic_range
    using_gridmaps