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   //! Identifies which style of tracking origin the application wants to use for the poses it is
0040   //! 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
0045                                      //! by the user
0046   };
0047
0048 public:
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
0081   //! be fetched instead
0082   virtual bool HasProjectionFrustums() const = 0;
0083
0084   //! Receive XR events.
0085   virtual void ProcessEvents() = 0;
0086
0087   //! Submit texture eye to XR Composer.
0088   //! @param[in] theTexture      texture handle
0089   //! @param[in] theGraphicsLib  graphics library in which texture handle is defined
0090   //! @param[in] theColorSpace   texture color space;
0091   //!                            sRGB means no color conversion by composer;
0092   //!                            Linear means to sRGB color conversion by composer
0093   //! @param[in] theEye  eye to display
0094   //! @return FALSE on error
0095   virtual bool SubmitEye(void*                  theTexture,
0096                          Aspect_GraphicsLibrary theGraphicsLib,
0097                          Aspect_ColorSpace      theColorSpace,
0098                          Aspect_Eye             theEye) = 0;
0099
0100   //! Return unit scale factor defined as scale factor for m (meters); 1.0 by default.
0101   Standard_Real UnitFactor() const { return myUnitFactor; }
0102
0103   //! Set unit scale factor.
0104   void SetUnitFactor(Standard_Real theFactor) { myUnitFactor = theFactor; }
0105
0106   //! Return aspect ratio.
0107   Standard_Real Aspect() const { return myAspect; }
0108
0109   //! Return field of view.
0110   Standard_Real FieldOfView() const { return myFieldOfView; }
0111
0112   //! Return Intra-ocular Distance (IOD); also known as Interpupillary Distance (IPD).
0113   //! Defined in meters by default (@sa UnitFactor()).
0114   Standard_Real IOD() const { return myIod; }
0115
0116   //! Return display frequency or 0 if unknown.
0117   Standard_ShortReal DisplayFrequency() const { return myDispFreq; }
0118
0119   //! Return projection frustum.
0120   //! @sa HasProjectionFrustums().
0121   const Aspect_FrustumLRBT<double>& ProjectionFrustum(Aspect_Eye theEye) const
0122   {
0123     return theEye == Aspect_Eye_Right ? myFrustumR : myFrustumL;
0124   }
0125
0126   //! Return head orientation in right-handed system:
0127   //! +y is up
0128   //! +x is to the right
0129   //! -z is forward
0130   //! Distance unit is meters by default (@sa UnitFactor()).
0131   const gp_Trsf& HeadPose() const { return myHeadPose; }
0132
0133   //! Return left hand orientation.
0134   gp_Trsf LeftHandPose() const
0135   {
0136     const Standard_Integer aDevice = NamedTrackedDevice(Aspect_XRTrackedDeviceRole_LeftHand);
0137     return aDevice != -1 ? myTrackedPoses[aDevice].Orientation : gp_Trsf();
0138   }
0139
0140   //! Return right hand orientation.
0141   gp_Trsf RightHandPose() const
0142   {
0143     const Standard_Integer aDevice = NamedTrackedDevice(Aspect_XRTrackedDeviceRole_RightHand);
0144     return aDevice != -1 ? myTrackedPoses[aDevice].Orientation : gp_Trsf();
0145   }
0146
0147   //! Return number of tracked poses array.
0148   const Aspect_TrackedDevicePoseArray& TrackedPoses() const { return myTrackedPoses; }
0149
0150   //! Return TRUE if device orientation is defined.
0151   bool HasTrackedPose(Standard_Integer theDevice) const
0152   {
0153     return myTrackedPoses[theDevice].IsValidPose;
0154   }
0155
0156   //! Return index of tracked device of known role, or -1 if undefined.
0157   virtual Standard_Integer NamedTrackedDevice(Aspect_XRTrackedDeviceRole theDevice) const = 0;
0158
0159   //! Load model for displaying device.
0160   //! @param[in] theDevice   device index
0161   //! @param[out] theTexture  texture source
0162   //! @return model triangulation or NULL if not found
0163   Handle(Graphic3d_ArrayOfTriangles) LoadRenderModel(Standard_Integer       theDevice,
0164                                                      Handle(Image_Texture)& theTexture)
0165   {
0166     return loadRenderModel(theDevice, true, theTexture);
0167   }
0168
0169   //! Load model for displaying device.
0170   //! @param[in] theDevice   device index
0171   //! @param[in] theToApplyUnitFactor  flag to apply unit scale factor
0172   //! @param[out] theTexture  texture source
0173   //! @return model triangulation or NULL if not found
0174   Handle(Graphic3d_ArrayOfTriangles) LoadRenderModel(Standard_Integer       theDevice,
0175                                                      Standard_Boolean       theToApplyUnitFactor,
0176                                                      Handle(Image_Texture)& theTexture)
0177   {
0178     return loadRenderModel(theDevice, theToApplyUnitFactor, theTexture);
0179   }
0180
0181   //! Fetch data for digital input action (like button).
0182   //! @param[in] theAction  action of Aspect_XRActionType_InputDigital type
0183   virtual Aspect_XRDigitalActionData GetDigitalActionData(
0184     const Handle(Aspect_XRAction)& theAction) const = 0;
0185
0186   //! Fetch data for digital input action (like axis).
0187   //! @param[in] theAction  action of Aspect_XRActionType_InputAnalog type
0188   virtual Aspect_XRAnalogActionData GetAnalogActionData(
0189     const Handle(Aspect_XRAction)& theAction) const = 0;
0190
0191   //! Fetch data for pose input action (like fingertip position).
0192   //! The returned values will match the values returned by the last call to WaitPoses().
0193   //! @param[in] theAction  action of Aspect_XRActionType_InputPose type
0194   virtual Aspect_XRPoseActionData GetPoseActionDataForNextFrame(
0195     const Handle(Aspect_XRAction)& theAction) const = 0;
0196
0197   //! Trigger vibration.
0198   Standard_EXPORT void TriggerHapticVibrationAction(const Handle(Aspect_XRAction)&   theAction,
0199                                                     const Aspect_XRHapticActionData& theParams);
0200
0201   //! Abort vibration.
0202   Standard_EXPORT void AbortHapticVibrationAction(const Handle(Aspect_XRAction)& theAction);
0203
0204   //! Return tracking origin.
0205   TrackingUniverseOrigin TrackingOrigin() const { return myTrackOrigin; }
0206
0207   //! Set tracking origin.
0208   virtual void SetTrackingOrigin(TrackingUniverseOrigin theOrigin) { myTrackOrigin = theOrigin; }
0209
0210   //! Return generic action for specific hand or NULL if undefined.
0211   const Handle(Aspect_XRAction)& GenericAction(Aspect_XRTrackedDeviceRole theDevice,
0212                                                Aspect_XRGenericAction     theAction) const
0213   {
0214     const NCollection_Array1<Handle(Aspect_XRAction)>& anActions = myRoleActions[theDevice];
0215     return anActions[theAction];
0216   }
0217
0218 public:
0219   //! Info string enumeration.
0220   enum InfoString
0221   {
0222     InfoString_Vendor,
0223     InfoString_Device,
0224     InfoString_Tracker,
0225     InfoString_SerialNumber,
0226   };
0227
0228   //! Query information.
0229   virtual TCollection_AsciiString GetString(InfoString theInfo) const = 0;
0230
0231 protected:
0232   //! Empty constructor.
0233   Standard_EXPORT Aspect_XRSession();
0234
0235   //! Load model for displaying device.
0236   //! @param[in] theDevice   device index
0237   //! @param[in] theToApplyUnitFactor  flag to apply unit scale factor
0238   //! @param[out] theTexture  texture source
0239   //! @return model triangulation or NULL if not found
0240   virtual Handle(Graphic3d_ArrayOfTriangles) loadRenderModel(Standard_Integer theDevice,
0241                                                              Standard_Boolean theToApplyUnitFactor,
0242                                                              Handle(Image_Texture)& theTexture) = 0;
0243
0244   //! Trigger vibration.
0245   virtual void triggerHapticVibrationAction(const Handle(Aspect_XRAction)&   theAction,
0246                                             const Aspect_XRHapticActionData& theParams) = 0;
0247
0248 protected:
0249   NCollection_Array1<Handle(Aspect_XRAction)>
0250     // clang-format off
0251                                   myRoleActions[Aspect_XRTrackedDeviceRole_NB]; //!< generic actions
0252   Aspect_XRActionSetMap           myActionSets;   //!< actions sets
0253   TrackingUniverseOrigin          myTrackOrigin;  //!< tracking origin
0254   Aspect_TrackedDevicePoseArray   myTrackedPoses; //!< array of tracked poses
0255   gp_Trsf                         myHeadPose;     //!< head orientation
0256   NCollection_Vec2<int>           myRendSize;     //!< viewport Width x Height for rendering into VR
0257   Aspect_FrustumLRBT<double>      myFrustumL;     //!< left  eye projection frustum
0258   Aspect_FrustumLRBT<double>      myFrustumR;     //!< right eye projection frustum
0259   Standard_Real                   myUnitFactor;   //!< unit scale factor defined as scale factor for m (meters)
0260   // clang-format on
0261   Standard_Real      myAspect;      //!< aspect ratio
0262   Standard_Real      myFieldOfView; //!< field of view
0263   Standard_Real      myIod;         //!< intra-ocular distance in meters
0264   Standard_ShortReal myDispFreq;    //!< display frequency
0265 };
0266
0267 #endif // _Aspect_XRSession_HeaderFile