Update the XR documentation

about/list_of_features.rst

@@ -488,8 +488,11 @@ XR support (AR and VR)
 ^^^^^^^^^^^^^^^^^^^^^^
 
 - Support for ARKit on iOS out of the box.
-- Support for the OpenXR and OpenVR APIs.
-- Popular VR headsets like the Oculus Quest and HTC Vive are supported thanks to plugins.
+- Support for the OpenXR APIs.
+  
+   - Includes support for popular headsets like the Meta Quest and the Valve Index.
+  
+- Support for the OpenVR APIs.
 
 GUI system
 ^^^^^^^^^^

tutorials/vr/index.rst

@@ -1,10 +1,11 @@
-VR
-==
+XR (AR/VR)
+==========
 
 .. toctree::
    :maxdepth: 1
    :name: toc-tutorials-vr
 
-   vr_primer
-   vr_starter_tutorial/index
-   developing_for_oculus_quest
+   xr_primer
+   openxr/index
+   oculus_mobile/index
+   openvr/index

tutorials/vr/developing_for_oculus_quest.rst → tutorials/vr/oculus_mobile/developing_for_oculus_quest.rst

@@ -7,7 +7,7 @@ Introduction
 ------------
 
 This tutorial goes over how to get started developing for the
-*Oculus Quest* with an official Godot plugin.
+*Meta Quest* with the Godot Oculus Mobile plugin.
 
 Before starting, there are two things you need to do:
 
@@ -97,28 +97,13 @@ Now save and close the export window.
 Setting Up Your Quest
 ---------------------
 
-Finally take out your phone, when you got your Quest you needed to
-install an Oculus app on it and link it up to your Quest. Start the
-Oculus app. Press the settings cogwheel on the bottom right hand side.
-Select your Quest:
+Follow `these instructions <https://developer.oculus.com/documentation/native/android/mobile-device-setup/>`__ to 
+setup your device for development. 
 
-.. image:: img/quest_phone_settings.png
-
-Select "More Settings", and select "Developer Mode":
-
-.. image:: img/quest_phone_settings_2.png
-
-Now turn developer mode on:
-
-.. image:: img/quest_developer_mode.png
-
-This allows you to deploy your games to the Quest.
-
-Connect the Quest to your PC with the provided USB cable. Put the Quest
-on, it may give a few dialogs to give the PC permission to deploy apps.
-Now hit the little Android button that should be visible in the top right
-hand side of your Godot window. It should build your game and export it
-to the Quest.
+Once your device is set up and connected, click the **Android logo** that should be visible in the top-right corner of the Godot editor.
+When clicked, it exports your project and runs it on the connected device.
+If you do not see this Android logo, make sure you have create an Android export preset
+and that the preset is marked as **Runnable** in the Export dialog.
 
 The above does the bare minimum to get your project running on the Quest,
 it's not very exciting. Holger Dammertz has made a great toolkit for the

tutorials/vr/oculus_mobile/index.rst

@@ -0,0 +1,8 @@
+Oculus mobile plugin (deprecated)
+=================================
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-tutorials-vr-oculus_mobile
+
+   developing_for_oculus_quest

tutorials/vr/openvr/index.rst

@@ -0,0 +1,8 @@
+OpenVR plugin
+=============
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-tutorials-vr-openvr
+
+   vr_starter_tutorial/index

tutorials/vr/openxr/deploy_on_quest.rst

@@ -0,0 +1,38 @@
+.. _doc_deploy_on_quest:
+
+Deploying on Quest
+==================
+
+The OpenXR plugin makes developing for Android seamless with developing desktop XR experiences. 
+Note that many Android based devices are very constrained performance-wise. Therefore,
+**we highly recommend using the GLES2 renderer.**
+
+.. note::
+
+    Currently, the only Android-based device supported is the Meta Quest. 
+    As Khronos is finalizing the official Android support for OpenXR, we will be able to offer further support soon.
+
+.. seealso::
+
+    As with any other Android device, please follow 
+    `the instructions in the official Godot documentation for deploying to Android <https://docs.godotengine.org/en/stable/getting_started/workflow/export/exporting_for_android.html#doc-exporting-for-android>`__.
+
+Enable developer mode on the Quest
+----------------------------------
+
+You can only deploy games to the Meta Quest if developer mode is enabled.
+You can do this from the Oculus support application installed on your phone.
+Please `follow the instructions on the Oculus developer site <https://developer.oculus.com/documentation/native/android/mobile-device-setup/>`__.
+
+Setting up the export template
+------------------------------
+
+The instruction in the official Godot documentation already has you configuring an export template in Godot. However, a few extra settings are needed for XR deployment.
+
+Open the export settings again by opening the **Project > Export...** menu and select the Android export template you created. 
+If you haven't created it yet, do so now by pressing **Add...** and selecting **Android**.
+
+Scroll down to the **Xr Features** section. Here, the important setting is the **Xr Mode** which should be set to **OpenXR**.
+Note that the other options shown here should be set according to your project's needs.
+
+.. image:: img/android_xr_features.png

tutorials/vr/openxr/enable_plugin.rst

@@ -0,0 +1,13 @@
+.. _doc_enable_plugin:
+
+Enabling the OpenXR plugin
+==========================
+
+Due to the design of Godot's XR system, the plugin will always automatically load the OpenXR interface.
+However, additional editor features will not be available unless the OpenXR plugin is enabled.
+
+For this, go to **Project > Project Settings** and select the **Plugins** tab:
+
+.. image:: img/enable_plugin.png
+
+Make sure the **Enable** checkbox is checked.

tutorials/vr/openxr/index.rst

@@ -0,0 +1,71 @@
+.. _doc_openxr_introduction:
+
+OpenXR plugin
+=============
+
+Welcome to the Godot OpenXR documentation!
+
+Introduction
+------------
+
+This is the documentation for the `Godot OpenXR plugin <https://github.com/GodotVR/godot_openxr>`__.
+
+The plugin is supported on Godot 3.4 and later. However, it does **not** support the upcoming Godot 4.0 release.
+
+Getting started
+---------------
+
+To start a new project that supports OpenXR, start by opening up the Godot editor and creating a new project.
+
+Copy the plugin into this new project in the subfolder ``addons/godot_openxr/`` using your operating system's file manager.
+It is important that the plugin is placed in this **exact** location in your project folder.
+
+Back in Godot, create a new 3D scene and press the **Instance Child Scene** button
+(represented by a chain link icon) in the scene tree dock.
+Select the ``addons/godot_openxr/scenes/first_person_controller_vr.tscn`` subscene
+and add it to your scene.
+Right-click the added node and select **Editable Children** to gain access
+to some of the nodes in this subscene:
+
+.. image:: img/editable_children.png
+
+This is the bare minimum you need. However, for good measure, we suggest adding
+a DirectionalLight node and a few MeshInstance nodes so you have something to see.
+If you add those to the hand nodes, you can visualize where your controllers
+are tracking.
+
+Your scene should now look something like this:
+
+.. image:: img/default_scene.png
+
+Now you can press the **Run** button in the top-right corner of the editor
+to start your project and you should be able to look around.
+
+Next steps
+----------
+
+To turn this simple scene into a proper game, the sky is the limit.
+Below, there are a few more topics specific to this plugin.
+However, the following resources are a good place to continue:
+
+- `VR starter tutorial <https://docs.godotengine.org/en/stable/tutorials/vr/vr_starter_tutorial/vr_starter_tutorial_part_one.html>`__
+  in the official documentation may focus on OpenVR, but almost everything
+  there applies to OpenXR as well.
+- `Godot XR tools <https://github.com/GodotVR/godot-xr-tools>`__ is a plugin
+  that contains a set of handy sub scene to quickly
+  implement locomotion, object interaction and UI elements in your XR experience.
+
+Please check the `Godot Engine community page <https://godotengine.org/community>`__ to find help from other Godot developers.
+The ``#xr`` channel on the Godot Discord has become a vibrant Godot XR community.
+
+Plugin features
+---------------
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-tutorials-vr-openxr
+
+   enable_plugin
+   runtime_selection
+   passthrough
+   deploy_on_quest

tutorials/vr/openxr/passthrough.rst

@@ -0,0 +1,61 @@
+.. _doc_passthrough:
+
+Passthrough
+===========
+
+.. note::
+
+    Only available in versions **1.1.1 and later** of the OpenXR plugin.
+
+Passthrough is a new feature introduced on the Meta Quest and added to the OpenXR spec as a Meta extension. 
+It is likely this implementation will be implemented by other vendors where the hardware supports a passthrough mode
+and promoted to core at some point.
+
+Keep in mind that this feature is not guaranteed to be available.
+Passthrough allows for the camera input on the headset to be used within the headset so the user can see the real world. 
+This allows us to implement an AR-like experience in a VR headset.
+
+If you are using the ``first person controller`` scene, you can simply
+enable passthrough by checking the **Start Passthrough** option
+on the controller node:
+
+.. image:: img/start_passthrough.png
+
+If you rather do this through code, you will first need to create an instance
+of the ``OpenXRConfig`` object. 
+You can do this the same way the ``first person controller`` does
+and assign the ``OpenXRConfig.gdns`` as the script to a node,
+or you can instance it in code as shown below:
+
+.. code::
+
+    var openxr_config = null
+
+
+    func _ready():
+        var config_gdns = load("res://addons/godot_ovrmobile/OvrInitConfig.gdns")
+        if config_gdns:
+            openxr_config = config_gdns.new()
+
+
+    func start_passthrough():
+        if openxr_config:
+            return openxr_config.start_passthrough()
+        else:
+            return false
+
+
+    func stop_passthrough():
+        if openxr_config:
+            openxr_config.stop_passthrough()
+
+.. note::
+
+        The Viewport's **Transparent Bg** property must be enabled prior to starting passthrough.
+        The plugin will log a warning message if it detects an incorrect configuration. 
+
+.. seealso::
+
+    A fix for a bug related to turning transparent background on/off
+    is scheduled for the Godot 3.4.3 release. If you wish to toggle passthrough
+    in your game, you will need to be on that version or newer.

tutorials/vr/openxr/runtime_selection.rst

@@ -0,0 +1,33 @@
+.. _doc_runtime_selection:
+
+Switching runtimes
+==================
+
+In OpenXR, it is standard for each runtime to implement a mechanism to make it
+the current runtime.  In Steam, the Oculus application or Windows MR portal,
+there will be an option to switch to their runtime as the current OpenXR runtime.
+
+Generally speaking, end users will have a preferred runtime due to not having a reason
+to switch runtimes when playing games that support OpenXR. However, developers may wish to
+test multiple runtimes to see if their game behaves.
+
+To make this easy, Godot provides a dropdown in the top-right corner which can
+switch the runtime Godot will use when testing:
+
+.. image:: img/switch_runtime.png
+
+.. note::
+
+    Selecting a runtime in this dropdown only applies to your local session. 
+    It does **not** change the runtime used by other applications. 
+    Also, if you are deploying to an external device, this setting has no effect.
+
+As OpenXR doesn't have a mechanism for registering runtimes that we can query,
+Godot will check common locations for runtime configuration files.
+The locations that are checked are stored in the ``addons/godot_openxr/runtimes.json`` file.
+If you've installed a runtime in a nonstandard location or a runtime not currently present in this file, you can add it manually using a text editor.
+
+.. seealso::
+
+    If the dropdown isn't shown in your editor, make sure the plugin is enabled. 
+    See :ref:`doc_enable_plugin`.

tutorials/vr/vr_primer.rst → tutorials/vr/xr_primer.rst

@@ -1,4 +1,4 @@
-.. _doc_vr_primer:
+.. _doc_xr_primer:
 
 AR/VR primer
 ============
@@ -119,17 +119,29 @@ As mentioned earlier, Godot does not support the various VR and AR SDKs out of t
 need a plugin for the specific SDK you want to use. There are several official plugins available
 in the `GodotVR Repository <https://github.com/GodotVR>`__.
 
-* `Godot Oculus Mobile <https://github.com/GodotVR/godot_oculus_mobile>`__ provides support for
-  the Oculus Go and Oculus Quest. The Quest will require additional setup documented in
-  :ref:`doc_developing_for_oculus_quest`.
-* `Godot OpenVR <https://github.com/GodotVR/godot_openvr>`__ (not to be confused with OpenXR)
+* `Godot OpenXR <https://github.com/GodotVR/godot_openxr>`_: This is the **official XR plugin**
+  starting with Godot **3.4**. It supports OpenXR, an open standard for designing and building
+  cross-platform VR and AR software.
+  Tested with SteamVR, Monada and Oculus OpenXR (desktop and mobile) runtimes.
+
+    * See :ref:`doc_openxr_introduction`.
+
+* `Godot Oculus Mobile <https://github.com/GodotVR/godot_oculus_mobile>`_ provides :ref:`support for
+  the Meta Quest <doc_developing_for_oculus_quest>`.
+
+    * **Note**: This plugin has been deprecated starting with Godot 3.4.
+      We recommend migrating to the `Godot OpenXR <https://github.com/GodotVR/godot_openxr>`_ plugin instead.
+
+* `Godot OpenVR <https://github.com/GodotVR/godot_openvr>`_ (not to be confused with OpenXR)
   supports the OpenVR SDK used by Steam.
 * `Godot Oculus <https://github.com/GodotVR/godot_oculus>`__ supports the Oculus SDK
   (desktop headsets only).
-* `Godot OpenHMD <https://github.com/GodotVR/godot_openhmd>`__ supports OpenHMD, an open source
+
+    * **Note**: This plugin has been deprecated starting with Godot 3.4.
+      We recommend migrating to the `Godot OpenXR <https://github.com/GodotVR/godot_openxr>`_ plugin instead.
+
+* `Godot OpenHMD <https://github.com/GodotVR/godot_openhmd>`_ supports OpenHMD, an open source
   API and drivers for headsets.
-* `Godot OpenXR <https://github.com/GodotVR/godot_openxr>`__ supports OpenXR, an open standard
-  for VR and AR software. Tested with SteamVR, Monada and Oculus OpenXR runtimes.
 
 These plugins can be downloaded from GitHub or the Godot Asset Library.
 
@@ -139,7 +151,7 @@ In addition to the plugins, there are several official demos.
 * `Godot OpenVR FPS <https://github.com/GodotVR/godot_openvr_fps>`__ (the tutorial for this project
   is :ref:`doc_vr_starter_tutorial_part_one`).
 * `Godot XR tools <https://github.com/GodotVR/godot-xr-tools>`__, which shows implementations for VR
-  features such as movement and picking up objects. 
+  features such as movement and picking up objects.
 
 Other things to consider
 ------------------------