include/opencascade/Aspect_XRSession.hxx

0001 // Copyright (c) 2020 OPEN CASCADE SAS
0002 //
0003 // This file is part of Open CASCADE Technology software library.
0004 //
0005 // This library is free software; you can redistribute it and/or modify it under
0006 // the terms of the GNU Lesser General Public License version 2.1 as published
0007 // by the Free Software Foundation, with special exception defined in the file
0008 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
0009 // distribution for complete text of the license and disclaimer of any warranty.
0010 //
0011 // Alternatively, this file may be used under the terms of Open CASCADE
0012 // commercial license or contractual agreement.
0013
0014 #ifndef _Aspect_XRSession_HeaderFile
0015 #define _Aspect_XRSession_HeaderFile
0016
0017 #include <Aspect_ColorSpace.hxx>
0018 #include <Aspect_Eye.hxx>
0019 #include <Aspect_FrustumLRBT.hxx>
0020 #include <Aspect_GraphicsLibrary.hxx>
0021 #include <Aspect_XRActionSet.hxx>
0022 #include <Aspect_XRAnalogActionData.hxx>
0023 #include <Aspect_XRDigitalActionData.hxx>
0024 #include <Aspect_XRGenericAction.hxx>
0025 #include <Aspect_XRHapticActionData.hxx>
0026 #include <Aspect_XRPoseActionData.hxx>
0027 #include <Aspect_XRTrackedDeviceRole.hxx>
0028 #include <gp_Trsf.hxx>
0029 #include <NCollection_Array1.hxx>
0030
0031 class Graphic3d_ArrayOfTriangles;
0032 class Image_Texture;
0033
0034 //! Extended Reality (XR) Session interface.
0035 class Aspect_XRSession : public Standard_Transient
0036 {
0037   DEFINE_STANDARD_RTTIEXT(Aspect_XRSession, Standard_Transient)
0038 public:
0039
0040   //! Identifies which style of tracking origin the application wants to use for the poses it is requesting.
0041   enum TrackingUniverseOrigin
0042   {
0043     TrackingUniverseOrigin_Seated,   //! poses are provided relative to the seated zero pose
0044     TrackingUniverseOrigin_Standing, //! poses are provided relative to the safe bounds configured by the user
0045   };
0046
0047 public:
0048
0049   //! Return TRUE if session is opened.
0050   virtual bool IsOpen() const = 0;
0051
0052   //! Initialize session.
0053   virtual bool Open() = 0;
0054
0055   //! Release session.
0056   virtual void Close() = 0;
0057
0058   //! Fetch actual poses of tracked devices.
0059   virtual bool WaitPoses() = 0;
0060
0061   //! Return recommended viewport Width x Height for rendering into VR.
0062   virtual NCollection_Vec2<int> RecommendedViewport() const = 0;
0063
0064   //! Return transformation from eye to head.
0065   virtual NCollection_Mat4<double> EyeToHeadTransform (Aspect_Eye theEye) const = 0;
0066
0067   //! Return transformation from head to eye.
0068   NCollection_Mat4<double> HeadToEyeTransform (Aspect_Eye theEye) const
0069   {
0070     NCollection_Mat4<double> aMat;
0071     EyeToHeadTransform (theEye).Inverted (aMat);
0072     return aMat;
0073   }
0074
0075   //! Return projection matrix.
0076   virtual NCollection_Mat4<double> ProjectionMatrix (Aspect_Eye theEye,
0077                                                      double theZNear,
0078                                                      double theZFar) const = 0;
0079
0080   //! Return FALSE if projection frustums are unsupported and general 4x4 projection matrix should be fetched instead
0081   virtual bool HasProjectionFrustums() const = 0;
0082
0083   //! Receive XR events.
0084   virtual void ProcessEvents() = 0;
0085
0086   //! Submit texture eye to XR Composer.
0087   //! @param theTexture     [in] texture handle
0088   //! @param theGraphicsLib [in] graphics library in which texture handle is defined
0089   //! @param theColorSpace  [in] texture color space;
0090   //!                            sRGB means no color conversion by composer;
0091   //!                            Linear means to sRGB color conversion by composer
0092   //! @param theEye [in] eye to display
0093   //! @return FALSE on error
0094   virtual bool SubmitEye (void* theTexture,
0095                           Aspect_GraphicsLibrary theGraphicsLib,
0096                           Aspect_ColorSpace theColorSpace,
0097                           Aspect_Eye theEye) = 0;
0098
0099   //! Return unit scale factor defined as scale factor for m (meters); 1.0 by default.
0100   Standard_Real UnitFactor() const { return myUnitFactor; }
0101
0102   //! Set unit scale factor.
0103   void SetUnitFactor (Standard_Real theFactor) { myUnitFactor = theFactor; }
0104
0105   //! Return aspect ratio.
0106   Standard_Real Aspect() const { return myAspect; }
0107
0108   //! Return field of view.
0109   Standard_Real FieldOfView() const { return myFieldOfView; }
0110
0111   //! Return Intra-ocular Distance (IOD); also known as Interpupillary Distance (IPD).
0112   //! Defined in meters by default (@sa UnitFactor()).
0113   Standard_Real IOD() const { return myIod; }
0114
0115   //! Return display frequency or 0 if unknown.
0116   Standard_ShortReal DisplayFrequency() const { return myDispFreq; }
0117
0118   //! Return projection frustum.
0119   //! @sa HasProjectionFrustums().
0120   const Aspect_FrustumLRBT<double>& ProjectionFrustum (Aspect_Eye theEye) const
0121   {
0122     return theEye == Aspect_Eye_Right ? myFrustumR : myFrustumL;
0123   }
0124
0125   //! Return head orientation in right-handed system:
0126   //! +y is up
0127   //! +x is to the right
0128   //! -z is forward
0129   //! Distance unit is meters by default (@sa UnitFactor()).
0130   const gp_Trsf& HeadPose() const { return myHeadPose; }
0131
0132   //! Return left hand orientation.
0133   gp_Trsf LeftHandPose()  const
0134   {
0135     const Standard_Integer aDevice = NamedTrackedDevice (Aspect_XRTrackedDeviceRole_LeftHand);
0136     return aDevice != -1 ? myTrackedPoses[aDevice].Orientation : gp_Trsf();
0137   }
0138
0139   //! Return right hand orientation.
0140   gp_Trsf RightHandPose() const
0141   {
0142     const Standard_Integer aDevice = NamedTrackedDevice (Aspect_XRTrackedDeviceRole_RightHand);
0143     return aDevice != -1 ? myTrackedPoses[aDevice].Orientation : gp_Trsf();
0144   }
0145
0146   //! Return number of tracked poses array.
0147   const Aspect_TrackedDevicePoseArray& TrackedPoses() const { return myTrackedPoses; }
0148
0149   //! Return TRUE if device orientation is defined.
0150   bool HasTrackedPose (Standard_Integer theDevice) const { return myTrackedPoses[theDevice].IsValidPose; }
0151
0152   //! Return index of tracked device of known role, or -1 if undefined.
0153   virtual Standard_Integer NamedTrackedDevice (Aspect_XRTrackedDeviceRole theDevice) const = 0;
0154
0155   //! Load model for displaying device.
0156   //! @param theDevice  [in] device index
0157   //! @param theTexture [out] texture source
0158   //! @return model triangulation or NULL if not found
0159   Handle(Graphic3d_ArrayOfTriangles) LoadRenderModel (Standard_Integer theDevice,
0160                                                       Handle(Image_Texture)& theTexture)
0161   {
0162     return loadRenderModel (theDevice, true, theTexture);
0163   }
0164
0165   //! Load model for displaying device.
0166   //! @param theDevice  [in] device index
0167   //! @param theToApplyUnitFactor [in] flag to apply unit scale factor
0168   //! @param theTexture [out] texture source
0169   //! @return model triangulation or NULL if not found
0170   Handle(Graphic3d_ArrayOfTriangles) LoadRenderModel (Standard_Integer theDevice,
0171                                                       Standard_Boolean theToApplyUnitFactor,
0172                                                       Handle(Image_Texture)& theTexture)
0173   {
0174     return loadRenderModel (theDevice, theToApplyUnitFactor, theTexture);
0175   }
0176
0177   //! Fetch data for digital input action (like button).
0178   //! @param theAction [in] action of Aspect_XRActionType_InputDigital type
0179   virtual Aspect_XRDigitalActionData GetDigitalActionData (const Handle(Aspect_XRAction)& theAction) const = 0;
0180
0181   //! Fetch data for digital input action (like axis).
0182   //! @param theAction [in] action of Aspect_XRActionType_InputAnalog type
0183   virtual Aspect_XRAnalogActionData GetAnalogActionData (const Handle(Aspect_XRAction)& theAction) const = 0;
0184
0185   //! Fetch data for pose input action (like fingertip position).
0186   //! The returned values will match the values returned by the last call to WaitPoses().
0187   //! @param theAction [in] action of Aspect_XRActionType_InputPose type
0188   virtual Aspect_XRPoseActionData GetPoseActionDataForNextFrame (const Handle(Aspect_XRAction)& theAction) const = 0;
0189
0190   //! Trigger vibration.
0191   Standard_EXPORT void TriggerHapticVibrationAction (const Handle(Aspect_XRAction)& theAction,
0192                                                      const Aspect_XRHapticActionData& theParams);
0193
0194   //! Abort vibration.
0195   Standard_EXPORT void AbortHapticVibrationAction (const Handle(Aspect_XRAction)& theAction);
0196
0197   //! Return tracking origin.
0198   TrackingUniverseOrigin TrackingOrigin() const { return myTrackOrigin; }
0199
0200   //! Set tracking origin.
0201   virtual void SetTrackingOrigin (TrackingUniverseOrigin theOrigin) { myTrackOrigin = theOrigin; }
0202
0203   //! Return generic action for specific hand or NULL if undefined.
0204   const Handle(Aspect_XRAction)& GenericAction (Aspect_XRTrackedDeviceRole theDevice,
0205                                                 Aspect_XRGenericAction theAction) const
0206   {
0207     const NCollection_Array1<Handle(Aspect_XRAction)>& anActions = myRoleActions[theDevice];
0208     return anActions[theAction];
0209   }
0210
0211 public:
0212
0213   //! Info string enumeration.
0214   enum InfoString
0215   {
0216     InfoString_Vendor,
0217     InfoString_Device,
0218     InfoString_Tracker,
0219     InfoString_SerialNumber,
0220   };
0221
0222   //! Query information.
0223   virtual TCollection_AsciiString GetString (InfoString theInfo) const = 0;
0224
0225 protected:
0226
0227   //! Empty constructor.
0228   Standard_EXPORT Aspect_XRSession();
0229
0230   //! Load model for displaying device.
0231   //! @param theDevice  [in] device index
0232   //! @param theToApplyUnitFactor [in] flag to apply unit scale factor
0233   //! @param theTexture [out] texture source
0234   //! @return model triangulation or NULL if not found
0235   virtual Handle(Graphic3d_ArrayOfTriangles) loadRenderModel (Standard_Integer theDevice,
0236                                                               Standard_Boolean theToApplyUnitFactor,
0237                                                               Handle(Image_Texture)& theTexture) = 0;
0238
0239   //! Trigger vibration.
0240   virtual void triggerHapticVibrationAction (const Handle(Aspect_XRAction)& theAction,
0241                                              const Aspect_XRHapticActionData& theParams) = 0;
0242
0243 protected:
0244
0245   NCollection_Array1<Handle(Aspect_XRAction)>
0246                                   myRoleActions[Aspect_XRTrackedDeviceRole_NB]; //!< generic actions
0247   Aspect_XRActionSetMap           myActionSets;   //!< actions sets
0248   TrackingUniverseOrigin          myTrackOrigin;  //!< tracking origin
0249   Aspect_TrackedDevicePoseArray   myTrackedPoses; //!< array of tracked poses
0250   gp_Trsf                         myHeadPose;     //!< head orientation
0251   NCollection_Vec2<int>           myRendSize;     //!< viewport Width x Height for rendering into VR
0252   Aspect_FrustumLRBT<double>      myFrustumL;     //!< left  eye projection frustum
0253   Aspect_FrustumLRBT<double>      myFrustumR;     //!< right eye projection frustum
0254   Standard_Real                   myUnitFactor;   //!< unit scale factor defined as scale factor for m (meters)
0255   Standard_Real                   myAspect;       //!< aspect ratio
0256   Standard_Real                   myFieldOfView;  //!< field of view
0257   Standard_Real                   myIod;          //!< intra-ocular distance in meters
0258   Standard_ShortReal              myDispFreq;     //!< display frequency
0259
0260 };
0261
0262 #endif // _Aspect_XRSession_HeaderFile