VR: Initial Virtual Reality support - Milestone 1, Scene Inspection

NOTE: While most of the milestone 1 goals are there, a few smaller features and
improvements are still to be done.

Big picture of this milestone: Initial, OpenXR-based virtual reality support
for users and foundation for advanced use cases.
Maniphest Task: https://developer.blender.org/T71347
The tasks contains more information about this milestone.

To be clear: This is not a feature rich VR implementation, it's focused on the
initial scene inspection use case. We intentionally focused on that, further
features like controller support are part of the next milestone.

- How to use?
Instructions on how to use this are here:
https://wiki.blender.org/wiki/User:Severin/GSoC-2019/How_to_Test
These will be updated and moved to a more official place (likely the manual) soon.

Currently Windows Mixed Reality and Oculus devices are usable. Valve/HTC
headsets don't support the OpenXR standard yet and hence, do not work with this
implementation.

---------------

This is the C-side implementation of the features added for initial VR
support as per milestone 1. A "VR Scene Inspection" Add-on will be
committed separately, to expose the VR functionality in the UI. It also
adds some further features for milestone 1, namely a landmarking system
(stored view locations in the VR space)

Main additions/features:
* Support for rendering viewports to an HMD, with good performance.
* Option to sync the VR view perspective with a fully interactive,
  regular 3D View (VR-Mirror).
* Option to disable positional tracking. Keeps the current position (calculated
  based on the VR eye center pose) when enabled while a VR session is running.
* Some regular viewport settings for the VR view
* RNA/Python-API to query and set VR session state information.
* WM-XR: Layer tying Ghost-XR to the Blender specific APIs/data
* wmSurface API: drawable, non-window container (manages Ghost-OpenGL and GPU
  context)
* DNA/RNA for management of VR session settings
* `--debug-xr` and `--debug-xr-time` commandline options
* Utility batch & config file for using the Oculus runtime on Windows.
* Most VR data is runtime only. The exception is user settings which are saved
  to files (`XrSessionSettings`).
* VR support can be disabled through the `WITH_XR_OPENXR` compiler flag.

For architecture and code documentation, see
https://wiki.blender.org/wiki/Source/Interface/XR.

---------------

A few thank you's:
* A huge shoutout to Ray Molenkamp for his help during the project - it would
  have not been that successful without him!
* Sebastian Koenig and Simeon Conzendorf for testing and feedback!
* The reviewers, especially Brecht Van Lommel!
* Dalai Felinto for pushing and managing me to get this done ;)
* The OpenXR working group for providing an open standard. I think we're the
  first bigger application to adopt OpenXR. Congratulations to them and
  ourselves :)

This project started as a Google Summer of Code 2019 project - "Core Support of
Virtual Reality Headsets through OpenXR" (see
https://wiki.blender.org/wiki/User:Severin/GSoC-2019/).
Some further information, including ideas for further improvements can be found
in the final GSoC report:
https://wiki.blender.org/wiki/User:Severin/GSoC-2019/Final_Report

Differential Revisions: D6193, D7098

Reviewed by: Brecht Van Lommel, Jeroen Bakker

1 files changed, 229 insertions, 0 deletions

diff --git a/source/blender/makesrna/intern/rna_xr.c b/source/blender/makesrna/intern/rna_xr.c
new file mode 100644
index 00000000000..76cbc99b397
--- /dev/null
+++ b/source/blender/makesrna/intern/rna_xr.c
@@ -0,0 +1,229 @@
+/*
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ */
+
+/** \file
+ * \ingroup RNA
+ */
+
+#include "DNA_view3d_types.h"
+#include "DNA_xr_types.h"
+
+#include "RNA_define.h"
+#include "RNA_enum_types.h"
+
+#include "WM_types.h"
+
+#include "rna_internal.h"
+
+#ifdef RNA_RUNTIME
+
+#  include "BLI_math.h"
+
+#  include "WM_api.h"
+
+static bool rna_XrSessionState_is_running(bContext *C)
+{
+#  ifdef WITH_XR_OPENXR
+  const wmWindowManager *wm = CTX_wm_manager(C);
+  return WM_xr_session_is_ready(&wm->xr);
+#  else
+  UNUSED_VARS(C);
+  return false;
+#  endif
+}
+
+#  ifdef WITH_XR_OPENXR
+static wmXrData *rna_XrSessionState_wm_xr_data_get(PointerRNA *ptr)
+{
+  /* Callers could also get XrSessionState pointer through ptr->data, but prefer if we just
+   * consistently pass wmXrData pointers to the WM_xr_xxx() API. */
+
+  BLI_assert(ptr->type == &RNA_XrSessionState);
+
+  wmWindowManager *wm = (wmWindowManager *)ptr->owner_id;
+  BLI_assert(wm && (GS(wm->id.name) == ID_WM));
+
+  return &wm->xr;
+}
+#  endif
+
+static void rna_XrSessionState_viewer_pose_location_get(PointerRNA *ptr, float *r_values)
+{
+#  ifdef WITH_XR_OPENXR
+  const wmXrData *xr = rna_XrSessionState_wm_xr_data_get(ptr);
+  WM_xr_session_state_viewer_pose_location_get(xr, r_values);
+#  else
+  UNUSED_VARS(ptr);
+  zero_v3(r_values);
+#  endif
+}
+
+static void rna_XrSessionState_viewer_pose_rotation_get(PointerRNA *ptr, float *r_values)
+{
+#  ifdef WITH_XR_OPENXR
+  const wmXrData *xr = rna_XrSessionState_wm_xr_data_get(ptr);
+  WM_xr_session_state_viewer_pose_rotation_get(xr, r_values);
+#  else
+  UNUSED_VARS(ptr);
+  unit_qt(r_values);
+#  endif
+}
+
+#else /* RNA_RUNTIME */
+
+static void rna_def_xr_session_settings(BlenderRNA *brna)
+{
+  StructRNA *srna;
+  PropertyRNA *prop;
+
+  static const EnumPropertyItem base_pose_types[] = {
+      {XR_BASE_POSE_SCENE_CAMERA,
+       "SCENE_CAMERA",
+       0,
+       "Scene Camera",
+       "Follow the active scene camera to define the VR view's base pose"},
+      {XR_BASE_POSE_OBJECT,
+       "OBJECT",
+       0,
+       "Object",
+       "Follow the transformation of an object to define the VR view's base pose"},
+      {XR_BASE_POSE_CUSTOM,
+       "CUSTOM",
+       0,
+       "Custom",
+       "Follow a custom transformation to define the VR view's base pose"},
+      {0, NULL, 0, NULL, NULL},
+  };
+
+  srna = RNA_def_struct(brna, "XrSessionSettings", NULL);
+  RNA_def_struct_ui_text(srna, "XR Session Settings", "");
+
+  prop = RNA_def_property(srna, "shading", PROP_POINTER, PROP_NONE);
+  RNA_def_property_flag(prop, PROP_NEVER_NULL);
+  RNA_def_property_ui_text(prop, "Shading Settings", "");
+  RNA_def_property_clear_flag(prop, PROP_EDITABLE);
+
+  prop = RNA_def_property(srna, "base_pose_type", PROP_ENUM, PROP_NONE);
+  RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
+  RNA_def_property_enum_items(prop, base_pose_types);
+  RNA_def_property_ui_text(
+      prop,
+      "Base Pose Type",
+      "Define where the location and rotation for the VR view come from, to which "
+      "translation and rotation deltas from the VR headset will be applied to");
+  RNA_def_property_update(prop, NC_WM | ND_XR_DATA_CHANGED, NULL);
+
+  prop = RNA_def_property(srna, "base_pose_object", PROP_POINTER, PROP_NONE);
+  RNA_def_property_flag(prop, PROP_EDITABLE);
+  RNA_def_property_ui_text(prop,
+                           "Base Pose Object",
+                           "Object to take the location and rotation to which translation and "
+                           "rotation deltas from the VR headset will be applied to");
+  RNA_def_property_update(prop, NC_WM | ND_XR_DATA_CHANGED, NULL);
+
+  prop = RNA_def_property(srna, "base_pose_location", PROP_FLOAT, PROP_TRANSLATION);
+  RNA_def_property_ui_text(prop,
+                           "Base Pose Location",
+                           "Coordinates to apply translation deltas from the VR headset to");
+  RNA_def_property_ui_range(prop, -FLT_MAX, FLT_MAX, 1, RNA_TRANSLATION_PREC_DEFAULT);
+  RNA_def_property_update(prop, NC_WM | ND_XR_DATA_CHANGED, NULL);
+
+  prop = RNA_def_property(srna, "base_pose_angle", PROP_FLOAT, PROP_AXISANGLE);
+  RNA_def_property_ui_text(
+      prop,
+      "Base Pose Angle",
+      "Rotation angle around the Z-Axis to apply the rotation deltas from the VR headset to");
+  RNA_def_property_update(prop, NC_WM | ND_XR_DATA_CHANGED, NULL);
+
+  prop = RNA_def_property(srna, "show_floor", PROP_BOOLEAN, PROP_NONE);
+  RNA_def_property_boolean_sdna(prop, NULL, "draw_flags", V3D_OFSDRAW_SHOW_GRIDFLOOR);
+  RNA_def_property_ui_text(prop, "Display Grid Floor", "Show the ground plane grid");
+  RNA_def_property_update(prop, NC_WM | ND_XR_DATA_CHANGED, NULL);
+
+  prop = RNA_def_property(srna, "show_annotation", PROP_BOOLEAN, PROP_NONE);
+  RNA_def_property_boolean_sdna(prop, NULL, "draw_flags", V3D_OFSDRAW_SHOW_ANNOTATION);
+  RNA_def_property_ui_text(prop, "Show Annotation", "Show annotations for this view");
+  RNA_def_property_update(prop, NC_WM | ND_XR_DATA_CHANGED, NULL);
+
+  prop = RNA_def_property(srna, "clip_start", PROP_FLOAT, PROP_DISTANCE);
+  RNA_def_property_range(prop, 1e-6f, FLT_MAX);
+  RNA_def_property_ui_range(prop, 0.001f, FLT_MAX, 10, 3);
+  RNA_def_property_ui_text(prop, "Clip Start", "VR viewport near clipping distance");
+  RNA_def_property_update(prop, NC_WM | ND_XR_DATA_CHANGED, NULL);
+
+  prop = RNA_def_property(srna, "clip_end", PROP_FLOAT, PROP_DISTANCE);
+  RNA_def_property_range(prop, 1e-6f, FLT_MAX);
+  RNA_def_property_ui_range(prop, 0.001f, FLT_MAX, 10, 3);
+  RNA_def_property_ui_text(prop, "Clip End", "VR viewport far clipping distance");
+  RNA_def_property_update(prop, NC_WM | ND_XR_DATA_CHANGED, NULL);
+
+  prop = RNA_def_property(srna, "use_positional_tracking", PROP_BOOLEAN, PROP_NONE);
+  RNA_def_property_boolean_sdna(prop, NULL, "flag", XR_SESSION_USE_POSITION_TRACKING);
+  RNA_def_property_ui_text(
+      prop,
+      "Positional Tracking",
+      "Allow VR headsets to affect the location in virtual space, in addition to the rotation");
+  RNA_def_property_update(prop, NC_WM | ND_XR_DATA_CHANGED, NULL);
+}
+
+static void rna_def_xr_session_state(BlenderRNA *brna)
+{
+  StructRNA *srna;
+  FunctionRNA *func;
+  PropertyRNA *parm, *prop;
+
+  srna = RNA_def_struct(brna, "XrSessionState", NULL);
+  RNA_def_struct_clear_flag(srna, STRUCT_UNDO);
+  RNA_def_struct_ui_text(srna, "Session State", "Runtime state information about the VR session");
+
+  func = RNA_def_function(srna, "is_running", "rna_XrSessionState_is_running");
+  RNA_def_function_ui_description(func, "Query if the VR session is currently running");
+  RNA_def_function_flag(func, FUNC_NO_SELF);
+  parm = RNA_def_pointer(func, "context", "Context", "", "");
+  RNA_def_parameter_flags(parm, PROP_NEVER_NULL, PARM_REQUIRED);
+  parm = RNA_def_boolean(func, "result", 0, "Result", "");
+  RNA_def_function_return(func, parm);
+
+  prop = RNA_def_property(srna, "viewer_pose_location", PROP_FLOAT, PROP_TRANSLATION);
+  RNA_def_property_array(prop, 3);
+  RNA_def_property_float_funcs(prop, "rna_XrSessionState_viewer_pose_location_get", NULL, NULL);
+  RNA_def_property_clear_flag(prop, PROP_EDITABLE);
+  RNA_def_property_ui_text(
+      prop,
+      "Viewer Pose Location",
+      "Last known location of the viewer pose (center between the eyes) in world space");
+
+  prop = RNA_def_property(srna, "viewer_pose_rotation", PROP_FLOAT, PROP_QUATERNION);
+  RNA_def_property_array(prop, 4);
+  RNA_def_property_float_funcs(prop, "rna_XrSessionState_viewer_pose_rotation_get", NULL, NULL);
+  RNA_def_property_clear_flag(prop, PROP_EDITABLE);
+  RNA_def_property_ui_text(
+      prop,
+      "Viewer Pose Rotation",
+      "Last known rotation of the viewer pose (center between the eyes) in world space");
+}
+
+void RNA_def_xr(BlenderRNA *brna)
+{
+  RNA_define_animate_sdna(false);
+
+  rna_def_xr_session_settings(brna);
+  rna_def_xr_session_state(brna);
+
+  RNA_define_animate_sdna(true);
+}
+
+#endif /* RNA_RUNTIME */