Merge pull request #2223 from clayjohn/gles2_3_update

Updates to GLES2 GLES3 Differences document

tutorials/misc/gles2_gles3_differences.rst

@@ -16,42 +16,39 @@ Particles
 
 GLES2 cannot use the :ref:`Particles <class_Particles>` or :ref:`Particles2D <class_Particles2D>` nodes
 as they require advanced GPU features. Instead, use :ref:`CPUParticles <class_CPUParticles>` or
-`:ref:`CPUParticles2D <class_CPUParticles2D>`, which provides a similar interface to a
+:ref:`CPUParticles2D <class_CPUParticles2D>`, which provides a similar interface to a
 :ref:`ParticlesMaterial <class_ParticlesMaterial>`.
 
 .. tip:: Particles and Particles2D can be converted to their CPU equivalent node with the "Convert to
          CPUParticles" option in the editor.
 
-SCREEN_TEXTURE mip-maps
------------------------
+``SCREEN_TEXTURE`` mip-maps
+---------------------------
 
 In GLES2, ``SCREEN_TEXTURE`` (accessed via a :ref:`ShaderMaterial <class_ShaderMaterial>`) does not have
 computed mip-maps. So when accessing at a different LOD, the texture will not appear blurry. 
 
-Color space
------------
-
-Shading in GLES3 takes place in linear color space while in GLES2 it takes place in sRGB space.
-While this is a very important distinction for graphics programmers, for everyone else it means
-that, in GLES3 shaders, you need to convert to sRGB before outputting your final color or else
-your colors will appear washed out and over-bright. 
+``DEPTH_TEXTURE``
+-----------------
 
-You do so with the following line of code at the end of the fragment shader:
+While GLES2 supports ``DEPTH_TEXTURE`` in shaders, it may not work on some old hardware (especially mobile).
 
-.. code-block:: glsl
-
-    ALBEDO = mix(pow((ALBEDO + vec3(0.055)) * (1.0 / (1.0 + 0.055)), vec3(2.4)), ALBEDO * (1.0 / 12.92), lessThan(ALBEDO, vec3(0.04045)));
+Color space
+-----------
 
-GLES2 does not need this. If your game is going to use both GLES2 and GLES3, wrap it in an ``if`` 
-statement checking to see if the output is in sRGB, using ``OUTPUT_IS_SRGB``. 
+GLES2 and GLES3 are in different color spaces. This means that colors will appear slightly
+different between them  especially when lighting is used. 
 
-.. code-block:: glsl
+If your game is going to use both GLES2 and GLES3, you can use an ``if`` 
+statement check and see if the output is in sRGB, using ``OUTPUT_IS_SRGB``. ``OUTPUT_IS_SRGB`` is 
+``true`` in GLES2 and ``false`` in GLES3.
 
-    if (!OUTPUT_IS_SRGB) {
-        ALBEDO = mix(pow((ALBEDO + vec3(0.055)) * (1.0 / (1.0 + 0.055)), vec3(2.4)), ALBEDO * (1.0 / 12.92), lessThan(ALBEDO, vec3(0.04045)));
-  }
+HDR
+---
 
-``OUTPUT_IS_SRGB`` is ``true`` in GLES2 and ``false`` in GLES3.
+GLES is not capable of using High Dynamic Range (HDR) rendering features. If HDR is set for your 
+project, or for a given viewport, Godot will still user Low Dynamic Range (LDR) which limits 
+viewport values to the ``0-1`` range.
 
 SpatialMaterial features
 ------------------------
@@ -64,8 +61,10 @@ In GLES2, the following advanced rendering features in the :ref:`SpatialMaterial
 - Clearcoat
 - Depth mapping
 
-The option to use them may appear in custom :ref:`ShaderMaterials <class_ShaderMaterial>`, however, they 
-will be non-functional. For example, you will still be able to set ``SSS`` (which normally adds 
+When using SpatialMaterials they will not even appear in the editor.
+
+In custom :ref:`ShaderMaterials <class_ShaderMaterial>`, you can set values for these features but they 
+will be non-functional. For example, you will still be able to set the ``SSS`` built-in (which normally adds 
 subsurface scattering) in your shader, but nothing will happen.
 
 Environment features
@@ -86,3 +85,33 @@ That means that in GLES2 environments you can only set:
 - Sky (including procedural sky)
 - Ambient light
 - Fog
+
+GIProbes
+--------
+
+:ref:`GIProbes <class_GIProbe>` do not work in GLES2. Instead use :ref:`Baked Lightmaps <class_BakedLightmap>`. 
+For a description of how baked lightmaps work see the :ref:`Baked Lightmaps tutorial <doc_baked_lightmaps>`.
+
+Contact shadows
+---------------
+
+The ``shadow_contact`` property of :ref:`Lights <class_Light>` is not supported in GLES2 and so does nothing.
+
+Light performance
+-----------------
+
+In GLES2, performance scales poorly with several lights, as each light is processed in a separate render 
+pass (in opposition to GLES3 which is all done in a single pass). Try to limit scenes to as few lights as 
+possible in order to achieve greatest performance. 
+
+Texture compression
+-------------------
+
+On mobile, GLES2 requires ETC texture compression, while GLES3 requires ETC2. ETC2 is enabled by default, 
+so if exporting to mobile using GLES2 make sure to set the project setting 
+``rendering/vram_compression/import_etc`` and then reimport textures.
+
+Blend shapes
+------------
+
+Blend shapes are not supported in GLES2.