Document troubleshooting rendering issues on Android and iOS

tutorials/3d/3d_rendering_limitations.rst

@@ -3,6 +3,12 @@
 3D rendering limitations
 ========================
 
+.. seealso::
+
+    In addition to the limitations below, mobile platforms have even more
+    limitations on 3D rendering compared to desktop platforms.
+    See :ref:`doc_mobile_rendering_limitations` for more information.
+
 Introduction
 ------------
 

tutorials/export/exporting_for_android.rst

@@ -162,3 +162,12 @@ and ARMv8 is usually sufficient to cover most devices in use today.
 You can optimize the size further by compiling an Android export template with
 only the features you need. See :ref:`doc_optimizing_for_size` for more
 information.
+
+Troubleshooting rendering issues
+--------------------------------
+
+To improve out-of-the-box performance on mobile devices, Godot automatically
+uses low-end-friendly settings by default on both Android and iOS.
+
+This can cause rendering issues that do not occur when running the project on a
+desktop platform. See :ref:`doc_mobile_rendering_limitations` for more information.

tutorials/export/exporting_for_ios.rst

@@ -98,3 +98,12 @@ Plugins for iOS
 
 Special iOS plugins can be used in Godot. Check out the
 :ref:`doc_plugins_for_ios` page.
+
+Troubleshooting rendering issues
+--------------------------------
+
+To improve out-of-the-box performance on mobile devices, Godot automatically
+uses low-end-friendly settings by default on both Android and iOS.
+
+This can cause rendering issues that do not occur when running the project on a
+desktop platform. See :ref:`doc_mobile_rendering_limitations` for more information.

tutorials/platform/index.rst

@@ -9,3 +9,4 @@ Platform-specific
    ios/index
    platform_html5
    consoles
+   mobile_rendering_limitations

tutorials/platform/mobile_rendering_limitations.rst

@@ -0,0 +1,73 @@
+.. _doc_mobile_rendering_limitations:
+
+Mobile rendering limitations
+============================
+
+.. seealso::
+
+    The general :ref:`doc_3d_rendering_limitations` also apply to mobile platforms.
+
+To improve out-of-the-box performance on mobile devices, Godot automatically uses
+low-end-friendly settings by default on both Android and iOS. These are configured
+by project settings with a ``.mobile`` :ref:`feature tag <doc_feature_tags>` suffix.
+
+One of the most notable changes on mobile that will affect 3D projects is that
+lighting is done per-vertex instead of per-pixel. This improves performance a
+lot, but can break rendering in some scenes, especially if your meshes aren't
+sufficiently subdivided for per-vertex lighting to look good. This can be
+disabled in the Project Settings at a performance cost (see below).
+
+When using GLES2, some custom shaders may break when exporting to Android. This
+is caused by a lower shader precision being used by default to improve
+performance. You can force high precision on all shader computations by enabling
+``rendering/gles2/compatibility/enable_high_float.Android`` project setting, but
+this has a significant performance cost and won't work on all devices.
+
+The following project settings have mobile-specific overrides:
+
++---------------------------------------------------------------------------+-----------------+--------------------+
+| Setting                                                                   | Desktop default | Mobile default     |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| ``rendering/quality/directional_shadow/size``                             | 4096            | 2048               |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| ``rendering/quality/intended_usage/framebuffer_allocation``               | 3D              | 3D Without Effects |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| ``rendering/quality/lightmapping/use_bicubic_sampling``                   | ``true``        | ``false``          |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| ``rendering/quality/reflections/high_quality_ggx``                        | ``true``        | ``false``          |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| ``rendering/quality/shading/force_blinn_over_ggx``                        | ``false``       | ``true``           |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| ``rendering/quality/shading/force_lambert_over_burley``                   | ``false``       | ``true``           |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| ``rendering/quality/shading/force_vertex_shading``                        | ``false``       | ``true``           |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| ``rendering/quality/shadow_atlas/size``                                   | 4096            | 2048               |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| ``rendering/quality/shadows/filter_mode``                                 | PCF5            | Disabled           |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| *GLES3 only:* ``rendering/gles3/shaders/max_simultaneous_compiles``       | 2               | 1                  |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| *GLES3 only:* ``rendering/gles3/shaders/shader_cache_size_mb``            | 512             | 128                |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| *GLES3 only:* ``rendering/quality/depth/hdr``                             | ``true``        | ``false``          |
++---------------------------------------------------------------------------+-----------------+--------------------+
+| *GLES3 only:* ``rendering/quality/reflections/texture_array_reflections`` | ``true``        | ``false``          |
++---------------------------------------------------------------------------+-----------------+--------------------+
+
+See the :ref:`ProjectSettings class documentation <class_ProjectSettings>`
+for more information on those setting overrides.
+
+If you're only targeting mobile platforms in your project, consider changing the
+project settings' values to match the mobile overrides. This way, you'll get a
+preview that is closer to the mobile appearance when running the project on a
+desktop platform (as well as within the editor).
+
+.. warning::
+
+    Due to driver bugs, GLES3 support on Android and iOS can be poor, especially
+    on old or low-end devices. Therefore, it is recommended to use the GLES2
+    renderer when targeting mobile platforms (especially Android).
+
+    You can change the rendering backend in the Project Settings
+    (**Rendering > Quality > Driver > Driver Name**).