From 1e375578c172e97329b0a248b5168c3bf48cedf4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= <rverschelde@gmail.com>
Date: Tue, 29 Jun 2021 17:40:56 +0200
Subject: [PATCH] Exporting for Web: Update info about WebGL

---
 tutorials/export/exporting_for_web.rst | 38 ++++++++++++++++----------
 1 file changed, 23 insertions(+), 15 deletions(-)

diff --git a/tutorials/export/exporting_for_web.rst b/tutorials/export/exporting_for_web.rst
index ae066a6c8..5460acd5c 100644
--- a/tutorials/export/exporting_for_web.rst
+++ b/tutorials/export/exporting_for_web.rst
@@ -12,7 +12,8 @@ in the user's browser.
                with :kbd:`F12`, to view **debug information** like JavaScript,
                engine, and WebGL errors.
 
-.. attention:: `There are significant bugs when running HTML5 projects on iOS <https://github.com/godotengine/godot/issues?q=is:issue+is:open+label:platform:html5+ios>`__
+.. attention:: `There are significant bugs when running HTML5 projects on iOS
+               <https://github.com/godotengine/godot/issues?q=is:issue+is:open+label:platform:html5+ios>`__
                (regardless of the browser). We recommend using
                :ref:`iOS' native export functionality <doc_exporting_for_ios>`
                instead, as it will also result in better performance.
@@ -24,21 +25,23 @@ in the user's browser.
     it's recommended to play the exported project using a Chromium-based browser
     instead of Firefox.
 
-WebGL 2
--------
+WebGL version
+-------------
 
-Until the *OpenGL ES 3* renderer is removed from Godot in favor of *Vulkan*,
-HTML5 export uses *WebGL 2* when the *GLES3* option is selected.
+Depending on your choice of renderer, Godot can target WebGL 1.0 (*GLES2*) or
+WebGL 2.0 (*GLES3*).
 
-.. warning:: Using WebGL 2 is not recommended due to its expected removal
-             from Godot without replacement.
+WebGL 1.0 is the recommended option if you want your project to be supported
+on all browsers with the best performance.
 
-WebGL 2 is not supported in all browsers. **Firefox** and
-**Chromium** (Chrome, Opera) are the most popular supported browsers,
-**Safari** and **Edge** do not work. On **iOS**, all browsers are based on
-WebKit (i.e. Safari), so they will also not work.
+Godot's GLES3 renderer targets high end devices, and the performance using
+WebGL 2.0 can be subpar. Some features are also not supported in WebGL 2.0
+specifically.
 
-Godot's WebGL 2 renderer has issues with 3D and is no longer maintained.
+Additionally, while most browsers support WebGL 2.0, this is not yet the case
+for **Safari**. WebGL 2.0 support is coming in Safari 15 for macOS, and is not
+available yet for any **iOS** browser (all WebKit-based like Safari).
+See `Can I use WebGL 2.0 <https://caniuse.com/webgl2>`__ for details.
 
 .. _doc_javascript_export_options:
 
@@ -51,9 +54,14 @@ game in the default browser for testing.
 
 You can choose the **Export Type** to select which features will be available:
 
-- *Regular*: is the most compatible across browsers, will not support threads, nor GDNative.
-- *Threads*: will require the browser to support `SharedArrayBuffer <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer>`__
-- *GDNative*: enables GDNative support but makes the binary bigger and slower to load.
+- *Regular*: is the most compatible across browsers, will not support threads,
+  nor GDNative.
+- *Threads*: will require the browser to support `SharedArrayBuffer
+  <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer>`__.
+  See `Can I use SharedArrayBuffer <https://caniuse.com/sharedarraybuffer>`__
+  for details.
+- *GDNative*: enables GDNative support but makes the binary bigger and slower
+  to load.
 
 If you plan to use :ref:`VRAM compression <doc_import_images>` make sure that
 **Vram Texture Compression** is enabled for the targeted platforms (enabling