Allow spaces and layers to be positioned in vsg coordinate space

Author: geefr

examples/composition_layer_quad/game.cpp

@@ -79,12 +79,19 @@ void Game::initVR()
 
     // A quad positioned in the world (scene reference space)
     // auto quadLayer = vsgvr::CompositionLayerQuad::create(_vr->getInstance(), _vr->getTraits(), _vr->getSession()->getSpace(), 1920, 1080);
-    // quadLayer->pose.position = { 0.0, 1.0, -4.0 };
+    // quadLayer->setPose(
+      // {0.0, 4.0, 1.0},
+      // vsg::dquat(vsg::radians(25.0), {1.0, 0.0, 0.0})
+    // );
 
     // A quad positioned in front of the user's face
-     auto faceLockedSpace = vsgvr::ReferenceSpace::create(_vr->getSession()->getSession(), XrReferenceSpaceType::XR_REFERENCE_SPACE_TYPE_VIEW);
-     auto quadLayer = vsgvr::CompositionLayerQuad::create(_vr->getInstance(), _vr->getTraits(), faceLockedSpace, 1920, 1080);
-     quadLayer->pose.position = { 0.0, 0.0, -4.0 };
+    auto faceLockedSpace = vsgvr::ReferenceSpace::create(_vr->getSession()->getSession(), XrReferenceSpaceType::XR_REFERENCE_SPACE_TYPE_VIEW);
+
+    auto quadLayer = vsgvr::CompositionLayerQuad::create(_vr->getInstance(), _vr->getTraits(), faceLockedSpace, 1920, 1080);
+    quadLayer->setPose(
+      {0.0, 4.0, 0.0},
+      {0.0, 0.0, 0.0, 1.0}
+    );
 
     /*auto rot = vsg::quat({0.0f, 5.0f, 2.5f}, {0.0f, 0.0f, 2.5f});
     quadLayer->pose.orientation = {

examples/composition_layer_quad/game.h

@@ -8,6 +8,9 @@
 #include <vsgvr/actions/ActionPoseBinding.h>
 #include <vsgvr/actions/SpaceBinding.h>
 
+#include <vsgvr/app/CompositionLayerProjection.h>
+#include <vsgvr/app/CompositionLayerQuad.h>
+
 #include "interaction.h"
 
 #include <memory>

readme.md

@@ -54,6 +54,22 @@ In addition the Vulkan runtime must satisfy the requirements of OpenXR. These re
 
 As features are implemented vsgvr will use more extensions if available, to support common features such as additional composition layers. If specific extensions are not present, or not requested by the application these features will be inoperable.
 
+### Coordinate Spaces
+
+In OpenXR various coordinate spaces are available, and follow a Y-up convention: x-right, y-up, z-out (backwards from user's perspective).
+
+While it may be modified, VulkanSceneGraph by default follows a Z-up convention: x-right, y-forward, z-up.
+
+vsgvr exposes both of these in some way, but by default follows the vsg Z-up convention:
+* Any API exposing vsg::mat4, vsg::vec3, vsg::quat, etc - Z-up
+* Any API exposing OpenXR types such as XrPosef - Y-up
+
+Most classes use OpenXR types internally, but expose both vsg and OpenXR types in their interfaces. Where possible the vsg types should be used within applications.
+
+This results in a logical mapping to the scene graph for world-based coordinate spaces (STAGE, LOCAL, VIEW).
+
+Action spaces are mapped using an `ActionPoseBinding`, which presents a vsg matrix for its transform - Any action related spaces are positioned within the OpenXR Session's space, which results in the transform being mapped to the overall 'world' space of the scenne graph automatically. Advanced users may query the action space directly and re-locate against a different XrSpace if desired.
+
 ## Setup
 
 If you don't have a VR headset there's a couple of options.

vsgvr/CMakeLists.txt

@@ -25,6 +25,7 @@ set( HEADERS_XR
   include/vsgvr/xr/Swapchain.h
   include/vsgvr/xr/Traits.h
   include/vsgvr/xr/ViewMatrix.h
+  include/vsgvr/xr/Pose.h
 )
 
 set( SOURCES
@@ -46,6 +47,7 @@ set( SOURCES
   src/vsgvr/xr/Session.cpp
   src/vsgvr/xr/Swapchain.cpp
   src/vsgvr/xr/Traits.cpp
+  src/vsgvr/xr/Pose.cpp
 )
 
 if( ANDROID )

vsgvr/include/vsgvr/app/CompositionLayerQuad.h

@@ -35,6 +35,7 @@ namespace vsgvr {
       CompositionLayerQuad() = delete;
       CompositionLayerQuad(vsg::ref_ptr<vsgvr::Instance> instance, vsg::ref_ptr<vsgvr::Traits> xrTraits, vsg::ref_ptr<vsgvr::ReferenceSpace> referenceSpace);
       CompositionLayerQuad(vsg::ref_ptr<vsgvr::Instance> instance, vsg::ref_ptr<vsgvr::Traits> xrTraits, vsg::ref_ptr<vsgvr::ReferenceSpace> referenceSpace, uint32_t inWidthPixels, uint32_t inHeightPixels);
+      CompositionLayerQuad(vsg::ref_ptr<vsgvr::Instance> instance, vsg::ref_ptr<vsgvr::Traits> xrTraits, vsg::ref_ptr<vsgvr::ReferenceSpace> referenceSpace, uint32_t inWidthPixels, uint32_t inHeightPixels, uint32_t inNumSamples, vsg::dvec3 position, vsg::dquat orientation, XrExtent2Df inSizeMeters, XrCompositionLayerFlags inFlags, XrEyeVisibility inEyeVisibility);
       CompositionLayerQuad(vsg::ref_ptr<vsgvr::Instance> instance, vsg::ref_ptr<vsgvr::Traits> xrTraits, vsg::ref_ptr<vsgvr::ReferenceSpace> referenceSpace, uint32_t inWidthPixels, uint32_t inHeightPixels, uint32_t inNumSamples, XrPosef inPose, XrExtent2Df inSizeMeters, XrCompositionLayerFlags inFlags, XrEyeVisibility inEyeVisibility);
       virtual ~CompositionLayerQuad();
       XrCompositionLayerBaseHeader* getCompositionLayerBaseHeaderPtr() override { return reinterpret_cast<XrCompositionLayerBaseHeader*>(&_compositionLayer); }
@@ -43,6 +44,8 @@ namespace vsgvr {
       std::vector<SwapchainImageRequirements> getSwapchainImageRequirements() override;
       void render(vsg::ref_ptr<vsgvr::Session> session, XrFrameState frameState, vsg::ref_ptr<vsg::FrameStamp> frameStamp) override;
 
+      void setPose(vsg::dvec3 position, vsg::dquat orientation);
+
       /// Image properties for the rendered quad
       uint32_t widthPixels = 1920;
       uint32_t heightPixels = 1080;

vsgvr/include/vsgvr/xr/Pose.h

@@ -0,0 +1,49 @@
+/*
+Copyright(c) 2022 Gareth Francis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+
+#pragma once
+
+#include <vsgvr/xr/Common.h>
+#include <vsg/core/Inherit.h>
+
+namespace vsgvr {
+  class VSGVR_DECLSPEC Pose : public vsg::Inherit<vsg::Object, Pose>
+  {
+    public:
+      Pose(XrPosef pose);
+      Pose(vsg::dvec3 position, vsg::dquat orientation);
+      Pose(vsg::vec3 position, vsg::quat orientation);
+      virtual ~Pose();
+
+      void setPose(XrPosef pose);
+      void setPose(vsg::dvec3 position, vsg::dquat orientation);
+      void setPose(vsg::vec3 position, vsg::quat orientation);
+
+      XrPosef getPose() const { return _pose; }
+
+      // TODO
+      // vsg::dmat4 getTransform() const;
+      // vsg::dvec3 getPosition() const;
+      // vsg::dquat getOrientation() const;
+    private:
+      XrPosef _pose;
+  };
+}

vsgvr/include/vsgvr/xr/ReferenceSpace.h

@@ -35,6 +35,8 @@ namespace vsgvr {
   public:
     ReferenceSpace() = delete;
     ReferenceSpace(XrSession session, XrReferenceSpaceType referenceSpaceType);
+    ReferenceSpace(XrSession session, XrReferenceSpaceType referenceSpaceType, vsg::dvec3 position, vsg::dquat orientation);
+
     /// Note: XrPosef is in the OpenXR coordinate system - X-right, Y-up, Z-back
     ReferenceSpace(XrSession session, XrReferenceSpaceType referenceSpaceType, XrPosef poseInReferenceSpace);
     virtual ~ReferenceSpace();

vsgvr/src/vsgvr/actions/ActionPoseBinding.cpp

@@ -74,27 +74,16 @@ namespace vsgvr
       {
         _transformValid = true;
 
-        // In the same way as ViewMatrix, poses need some conversion for the VSG space
-        // OpenXR space: x-right, y-up, z-back
-        // VSG/Vulkan space: x-right, y-forward, z-up
-        // * Invert y -> To flip the handedness (x-right, y-back, z-up)
-        // * Rotate clockwise around x -> To move into vsg space (x-right, y-up, z-back)
-        // After this, models are built for vsg space, and default concepts in the api map across
-        //
-        // TODO: Need to double check this, but here the action spaces needed to be un-rotated,
-        //       to compensate for the rotation in ViewMatrix. Not entirely sure why..
-        auto worldRotateMat = vsg::rotate(vsg::PI / 2.0, 1.0, 0.0, 0.0);
-
+        vsg::dmat4 xrToVsg;
+        vsg::transform(vsg::CoordinateConvention::Y_UP, vsg::CoordinateConvention::Z_UP, xrToVsg);
         auto q = vsg::dquat(
           location.pose.orientation.x,
           location.pose.orientation.y,
           location.pose.orientation.z,
           location.pose.orientation.w
         );
-        auto rotateMat = vsg::rotate(q);
         auto p = vsg::dvec3(location.pose.position.x, location.pose.position.y, location.pose.position.z);
-        auto translateMat = vsg::translate(p);
-        auto transform = worldRotateMat * translateMat * rotateMat;
+        auto transform = xrToVsg * vsg::translate(p) * vsg::rotate(q);
 
         _transform = transform;
       }

vsgvr/src/vsgvr/actions/SpaceBinding.cpp

@@ -48,27 +48,16 @@ namespace vsgvr
     {
       _transformValid = true;
 
-      // In the same way as ViewMatrix, poses need some conversion for the VSG space
-      // OpenXR space: x-right, y-up, z-back
-      // VSG/Vulkan space: x-right, y-forward, z-up
-      // * Invert y -> To flip the handedness (x-right, y-back, z-up)
-      // * Rotate clockwise around x -> To move into vsg space (x-right, y-up, z-back)
-      // After this, models are built for vsg space, and default concepts in the api map across
-      //
-      // TODO: Need to double check this, but here the action spaces needed to be un-rotated,
-      //       to compensate for the rotation in ViewMatrix. Not entirely sure why..
-      auto worldRotateMat = vsg::rotate(vsg::PI / 2.0, 1.0, 0.0, 0.0);
-
+      vsg::dmat4 xrToVsg;
+      vsg::transform(vsg::CoordinateConvention::Y_UP, vsg::CoordinateConvention::Z_UP, xrToVsg);
       auto q = vsg::dquat(
         location.pose.orientation.x,
         location.pose.orientation.y,
         location.pose.orientation.z,
         location.pose.orientation.w
       );
-      auto rotateMat = vsg::rotate(q);
       auto p = vsg::dvec3(location.pose.position.x, location.pose.position.y, location.pose.position.z);
-      auto translateMat = vsg::translate(p);
-      auto transform = worldRotateMat * translateMat * rotateMat;
+      auto transform = xrToVsg * vsg::translate(p) * vsg::rotate(q);
 
       _transform = transform;
     }

vsgvr/src/vsgvr/app/CompositionLayerQuad.cpp

@@ -23,6 +23,7 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #include <vsgvr/xr/Swapchain.h>
 #include <vsgvr/xr/Session.h>
+#include <vsgvr/xr/Pose.h>
 
 #include <vsg/core/Exception.h>
 #include "../xr/Macros.cpp"
@@ -39,6 +40,17 @@ namespace vsgvr {
     , widthPixels(inWidthPixels)
     , heightPixels(inHeightPixels)
   {}
+  CompositionLayerQuad::CompositionLayerQuad(vsg::ref_ptr<vsgvr::Instance> instance, vsg::ref_ptr<vsgvr::Traits> xrTraits, vsg::ref_ptr<vsgvr::ReferenceSpace> referenceSpace, uint32_t inWidthPixels, uint32_t inHeightPixels, uint32_t inNumSamples, vsg::dvec3 position, vsg::dquat orientation, XrExtent2Df inSizeMeters, XrCompositionLayerFlags inFlags, XrEyeVisibility inEyeVisibility)
+    : Inherit(instance, xrTraits, referenceSpace)
+    , widthPixels(inWidthPixels)
+    , heightPixels(inHeightPixels)
+    , numSamples(inNumSamples)
+    , sizeMeters(inSizeMeters)
+    , flags(inFlags)
+    , eyeVisibility(inEyeVisibility)
+  {
+    setPose(position, orientation);
+  }
   CompositionLayerQuad::CompositionLayerQuad(vsg::ref_ptr<vsgvr::Instance> instance, vsg::ref_ptr<vsgvr::Traits> xrTraits, vsg::ref_ptr<vsgvr::ReferenceSpace> referenceSpace, uint32_t inWidthPixels, uint32_t inHeightPixels, uint32_t inNumSamples, XrPosef inPose, XrExtent2Df inSizeMeters, XrCompositionLayerFlags inFlags, XrEyeVisibility inEyeVisibility)
     : Inherit(instance, xrTraits, referenceSpace)
     , widthPixels(inWidthPixels)
@@ -118,4 +130,9 @@ namespace vsgvr {
     };
     _compositionLayer.subImage.imageArrayIndex = 0;
   }
+
+  void CompositionLayerQuad::setPose(vsg::dvec3 position, vsg::dquat orientation)
+  {
+    pose = Pose(position, orientation).getPose();
+  }
 }