src/Graphic3d/Graphic3d_Camera.hxx

   1 // Created on: 2013-05-29
   2 // Created by: Anton POLETAEV
   3 // Copyright (c) 1999-2014 OPEN CASCADE SAS
   4 //
   5 // This file is part of Open CASCADE Technology software library.
   6 //
   7 // This library is free software; you can redistribute it and/or modify it under
   8 // the terms of the GNU Lesser General Public License version 2.1 as published
   9 // by the Free Software Foundation, with special exception defined in the file
  10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
  11 // distribution for complete text of the license and disclaimer of any warranty.
  12 //
  13 // Alternatively, this file may be used under the terms of Open CASCADE
  14 // commercial license or contractual agreement.
  15
  16 #ifndef _Graphic3d_Camera_HeaderFile
  17 #define _Graphic3d_Camera_HeaderFile
  18
  19 #include <Aspect_Eye.hxx>
  20 #include <Aspect_FrustumLRBT.hxx>
  21 #include <Graphic3d_CameraTile.hxx>
  22 #include <Graphic3d_Mat4d.hxx>
  23 #include <Graphic3d_Mat4.hxx>
  24 #include <Graphic3d_Vec3.hxx>
  25 #include <Graphic3d_WorldViewProjState.hxx>
  26 #include <NCollection_Lerp.hxx>
  27 #include <NCollection_Array1.hxx>
  28
  29 #include <gp_Dir.hxx>
  30 #include <gp_Pnt.hxx>
  31
  32 #include <Standard_Macro.hxx>
  33 #include <Standard_TypeDef.hxx>
  34
  35 #include <Bnd_Box.hxx>
  36
  37 //! Forward declaration
  38 class Graphic3d_WorldViewProjState;
  39
  40 //! Camera class provides object-oriented approach to setting up projection
  41 //! and orientation properties of 3D view.
  42 class Graphic3d_Camera : public Standard_Transient
  43 {
  44 private:
  45
  46   //! Template container for cached matrices or Real/ShortReal types.
  47   template<typename Elem_t>
  48   struct TransformMatrices
  49   {
  50
  51     //! Default constructor.
  52     TransformMatrices() : myIsOrientationValid (Standard_False), myIsProjectionValid (Standard_False) {}
  53
  54     //! Initialize orientation.
  55     void InitOrientation()
  56     {
  57       myIsOrientationValid = Standard_True;
  58       Orientation.InitIdentity();
  59     }
  60
  61     //! Initialize projection.
  62     void InitProjection()
  63     {
  64       myIsProjectionValid = Standard_True;
  65       MProjection.InitIdentity();
  66       LProjection.InitIdentity();
  67       RProjection.InitIdentity();
  68     }
  69
  70     //! Invalidate orientation.
  71     void ResetOrientation() { myIsOrientationValid = Standard_False; }
  72
  73     //! Invalidate projection.
  74     void ResetProjection()  { myIsProjectionValid  = Standard_False; }
  75
  76     //! Return true if Orientation was not invalidated.
  77     Standard_Boolean IsOrientationValid() const { return myIsOrientationValid; }
  78
  79     //! Return true if Projection was not invalidated.
  80     Standard_Boolean IsProjectionValid()  const { return myIsProjectionValid;  }
  81
  82     //! Dumps the content of me into the stream
  83     void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const
  84     {
  85       if (IsOrientationValid())
  86       {
  87         OCCT_DUMP_FIELD_VALUES_DUMPED (theOStream, theDepth, &Orientation)
  88       }
  89       if (IsProjectionValid())
  90       {
  91         OCCT_DUMP_FIELD_VALUES_DUMPED (theOStream, theDepth, &MProjection)
  92         OCCT_DUMP_FIELD_VALUES_DUMPED (theOStream, theDepth, &LProjection)
  93         OCCT_DUMP_FIELD_VALUES_DUMPED (theOStream, theDepth, &RProjection)
  94       }
  95       OCCT_DUMP_FIELD_VALUE_NUMERICAL (theOStream, myIsOrientationValid)
  96       OCCT_DUMP_FIELD_VALUE_NUMERICAL (theOStream, myIsProjectionValid)
  97     }
  98
  99   public:
 100
 101     NCollection_Mat4<Elem_t> Orientation;
 102     NCollection_Mat4<Elem_t> MProjection;
 103     NCollection_Mat4<Elem_t> LProjection;
 104     NCollection_Mat4<Elem_t> RProjection;
 105
 106   private:
 107
 108     Standard_Boolean myIsOrientationValid;
 109     Standard_Boolean myIsProjectionValid;
 110
 111   };
 112
 113 public:
 114
 115   //! Enumerates supported monographic projections.
 116   //! - Projection_Orthographic : orthographic projection.
 117   //! - Projection_Perspective  : perspective projection.
 118   //! - Projection_Stereo       : stereographic projection.
 119   //! - Projection_MonoLeftEye  : mono projection for stereo left eye.
 120   //! - Projection_MonoRightEye : mono projection for stereo right eye.
 121   enum Projection
 122   {
 123     Projection_Orthographic,
 124     Projection_Perspective,
 125     Projection_Stereo,
 126     Projection_MonoLeftEye,
 127     Projection_MonoRightEye
 128   };
 129
 130   //! Enumerates approaches to define stereographic focus.
 131   //! - FocusType_Absolute : focus is specified as absolute value.
 132   //! - FocusType_Relative : focus is specified relative to
 133   //! (as coefficient of) camera focal length.
 134   enum FocusType
 135   {
 136     FocusType_Absolute,
 137     FocusType_Relative
 138   };
 139
 140   //! Enumerates approaches to define Intraocular distance.
 141   //! - IODType_Absolute : Intraocular distance is defined as absolute value.
 142   //! - IODType_Relative : Intraocular distance is defined relative to
 143   //! (as coefficient of) camera focal length.
 144   enum IODType
 145   {
 146     IODType_Absolute,
 147     IODType_Relative
 148   };
 149
 150 public:
 151
 152   //! Linear interpolation tool for camera orientation and position.
 153   //! This tool interpolates camera parameters scale, eye, center, rotation (up and direction vectors) independently.
 154   //! @sa Graphic3d_CameraLerp
 155   //!
 156   //! Eye/Center interpolation is performed through defining an anchor point in-between Center and Eye.
 157   //! The anchor position is defined as point near to the camera point which has smaller translation part.
 158   //! The main idea is to keep the distance between Center and Eye
 159   //! (which will change if Center and Eye translation will be interpolated independently).
 160   //! E.g.:
 161   //!  - When both Center and Eye are moved at the same vector -> both will be just translated by straight line;
 162   //!  - When Center is not moved -> camera Eye    will move around Center through arc;
 163   //!  - When Eye    is not moved -> camera Center will move around Eye    through arc;
 164   //!  - When both Center and Eye are move by different vectors -> transformation will be something in between,
 165   //!    and will try interpolate linearly the distance between Center and Eye.
 166   //!
 167   //! This transformation might be not in line with user expectations.
 168   //! In this case, application might define intermediate camera positions for interpolation or implement own interpolation logic.
 169   //!
 170   //! @param theStart  [in] initial camera position
 171   //! @param theEnd    [in] final   camera position
 172   //! @param theT      [in] step between initial and final positions within [0,1] range
 173   //! @param theCamera [out] interpolation result
 174   Standard_EXPORT static void Interpolate (const Handle(Graphic3d_Camera)& theStart,
 175                                            const Handle(Graphic3d_Camera)& theEnd,
 176                                            const double theT,
 177                                            Handle(Graphic3d_Camera)& theCamera);
 178
 179 public:
 180
 181   //! Default constructor.
 182   //! Initializes camera with the following properties:
 183   //! Eye (0, 0, -2); Center (0, 0, 0); Up (0, 1, 0);
 184   //! Type (Orthographic); FOVy (45); Scale (1000); IsStereo(false);
 185   //! ZNear (0.001); ZFar (3000.0); Aspect(1);
 186   //! ZFocus(1.0); ZFocusType(Relative); IOD(0.05); IODType(Relative)
 187   Standard_EXPORT Graphic3d_Camera();
 188
 189   //! Copy constructor.
 190   //! @param theOther [in] the camera to copy from.
 191   Standard_EXPORT Graphic3d_Camera (const Handle(Graphic3d_Camera)& theOther);
 192
 193   //! Initialize mapping related parameters from other camera handle.
 194   Standard_EXPORT void CopyMappingData (const Handle(Graphic3d_Camera)& theOtherCamera);
 195
 196   //! Initialize orientation related parameters from other camera handle.
 197   Standard_EXPORT void CopyOrientationData (const Handle(Graphic3d_Camera)& theOtherCamera);
 198
 199   //! Copy properties of another camera.
 200   //! @param theOther [in] the camera to copy from.
 201   Standard_EXPORT void Copy (const Handle(Graphic3d_Camera)& theOther);
 202
 203 //! @name Public camera properties
 204 public:
 205
 206   //! Get camera look direction.
 207   //! @return camera look direction.
 208   const gp_Dir& Direction() const { return myDirection; }
 209
 210   //! Sets camera look direction preserving the current Eye() position.
 211   //! WARNING! This method does NOT verify that the current Up() vector is orthogonal to the new Direction.
 212   //! @param theDir [in] the direction.
 213   Standard_EXPORT void SetDirectionFromEye (const gp_Dir& theDir);
 214
 215   //! Sets camera look direction and computes the new Eye position relative to current Center.
 216   //! WARNING! This method does NOT verify that the current Up() vector is orthogonal to the new Direction.
 217   //! @param theDir [in] the direction.
 218   Standard_EXPORT void SetDirection (const gp_Dir& theDir);
 219
 220   //! Get camera Up direction vector.
 221   //! @return Camera's Up direction vector.
 222   const gp_Dir& Up() const { return myUp; }
 223
 224   //! Sets camera Up direction vector, orthogonal to camera direction.
 225   //! WARNING! This method does NOT verify that the new Up vector is orthogonal to the current Direction().
 226   //! @param theUp [in] the Up direction vector.
 227   //! @sa OrthogonalizeUp().
 228   Standard_EXPORT void SetUp (const gp_Dir& theUp);
 229
 230   //! Orthogonalize up direction vector.
 231   Standard_EXPORT void OrthogonalizeUp();
 232
 233   //! Return a copy of orthogonalized up direction vector.
 234   Standard_EXPORT gp_Dir OrthogonalizedUp() const;
 235
 236   //! Right side direction.
 237   gp_Dir SideRight() const
 238   {
 239     return -(gp_Vec (Direction()) ^ gp_Vec (OrthogonalizedUp()));
 240   }
 241
 242   //! Get camera Eye position.
 243   //! @return camera eye location.
 244   const gp_Pnt& Eye() const { return myEye; }
 245
 246   //! Sets camera Eye position.
 247   //! Unlike SetEye(), this method only changes Eye point and preserves camera direction.
 248   //! @param theEye [in] the location of camera's Eye.
 249   //! @sa SetEye()
 250   Standard_EXPORT void MoveEyeTo (const gp_Pnt& theEye);
 251
 252   //! Sets camera Eye and Center positions.
 253   //! @param theEye    [in] the location of camera's Eye
 254   //! @param theCenter [in] the location of camera's Center
 255   Standard_EXPORT void SetEyeAndCenter (const gp_Pnt& theEye,
 256                                         const gp_Pnt& theCenter);
 257
 258   //! Sets camera Eye position.
 259   //! WARNING! For backward compatibility reasons, this method also changes view direction,
 260   //! so that the new direction is computed from new Eye position to old Center position.
 261   //! @param theEye [in] the location of camera's Eye.
 262   //! @sa MoveEyeTo(), SetEyeAndCenter()
 263   Standard_EXPORT void SetEye (const gp_Pnt& theEye);
 264
 265   //! Get Center of the camera, e.g. the point where camera looks at.
 266   //! This point is computed as Eye() translated along Direction() at Distance().
 267   //! @return the point where the camera looks at.
 268   gp_Pnt Center() const
 269   {
 270     return myEye.XYZ() + myDirection.XYZ() * myDistance;
 271   }
 272
 273   //! Sets Center of the camera, e.g. the point where camera looks at.
 274   //! This methods changes camera direction, so that the new direction is computed
 275   //! from current Eye position to specified Center position.
 276   //! @param theCenter [in] the point where the camera looks at.
 277   Standard_EXPORT void SetCenter (const gp_Pnt& theCenter);
 278
 279   //! Get distance of Eye from camera Center.
 280   //! @return the distance.
 281   Standard_Real Distance() const { return myDistance; }
 282
 283   //! Set distance of Eye from camera Center.
 284   //! @param theDistance [in] the distance.
 285   Standard_EXPORT void SetDistance (const Standard_Real theDistance);
 286
 287   //! Get camera scale.
 288   //! @return camera scale factor.
 289   Standard_EXPORT Standard_Real Scale() const;
 290
 291   //! Sets camera scale. For orthographic projection the scale factor
 292   //! corresponds to parallel scale of view mapping  (i.e. size
 293   //! of viewport). For perspective camera scale is converted to
 294   //! distance. The scale specifies equal size of the view projection in
 295   //! both dimensions assuming that the aspect is 1.0. The projection height
 296   //! and width are specified with the scale and correspondingly multiplied
 297   //! by the aspect.
 298   //! @param theScale [in] the scale factor.
 299   Standard_EXPORT void SetScale (const Standard_Real theScale);
 300
 301   //! Get camera axial scale.
 302   //! @return Camera's axial scale.
 303   const gp_XYZ& AxialScale() const { return myAxialScale; }
 304
 305   //! Set camera axial scale.
 306   //! @param theAxialScale [in] the axial scale vector.
 307   Standard_EXPORT void SetAxialScale (const gp_XYZ& theAxialScale);
 308
 309   //! Change camera projection type.
 310   //! When switching to perspective projection from orthographic one,
 311   //! the ZNear and ZFar are reset to default values (0.001, 3000.0)
 312   //! if less than 0.0.
 313   //! @param theProjectionType [in] the camera projection type.
 314   Standard_EXPORT void SetProjectionType (const Projection theProjection);
 315
 316   //! @return camera projection type.
 317   Projection ProjectionType() const
 318   {
 319     return myProjType;
 320   }
 321
 322   //! Check that the camera projection is orthographic.
 323   //! @return boolean flag that indicates whether the camera's projection is
 324   //! orthographic or not.
 325   Standard_Boolean IsOrthographic() const
 326   {
 327     return (myProjType == Projection_Orthographic);
 328   }
 329
 330   //! Check whether the camera projection is stereo.
 331   //! Please note that stereo rendering is now implemented with support of
 332   //! Quad buffering.
 333   //! @return boolean flag indicating whether the stereographic L/R projection
 334   //! is chosen.
 335   Standard_Boolean IsStereo() const
 336   {
 337     return (myProjType == Projection_Stereo);
 338   }
 339
 340   //! Set Field Of View (FOV) in y axis for perspective projection.
 341   //! Field of View in x axis is automatically scaled from view aspect ratio.
 342   //! @param theFOVy [in] the FOV in degrees.
 343   Standard_EXPORT void SetFOVy (const Standard_Real theFOVy);
 344
 345   //! Get Field Of View (FOV) in y axis.
 346   //! @return the FOV value in degrees.
 347   Standard_Real FOVy() const { return myFOVy; }
 348
 349   //! Get Field Of View (FOV) in x axis.
 350   //! @return the FOV value in degrees.
 351   Standard_Real FOVx() const { return myFOVx; }
 352
 353   //! Get Field Of View (FOV) restriction for 2D on-screen elements; 180 degrees by default.
 354   //! When 2D FOV is smaller than FOVy or FOVx, 2D elements defined within offset from view corner
 355   //! will be extended to fit into specified 2D FOV.
 356   //! This can be useful to make 2D elements sharply visible, like in case of HMD normally having extra large FOVy.
 357   Standard_Real FOV2d() const { return myFOV2d; }
 358
 359   //! Set Field Of View (FOV) restriction for 2D on-screen elements.
 360   Standard_EXPORT void SetFOV2d (Standard_Real theFOV);
 361
 362   //! Adjust camera to fit in specified AABB.
 363   Standard_EXPORT bool FitMinMax (const Bnd_Box& theBox,
 364                                   const Standard_Real theResolution,
 365                                   const bool theToEnlargeIfLine);
 366
 367   //! Estimate Z-min and Z-max planes of projection volume to match the
 368   //! displayed objects. The methods ensures that view volume will
 369   //! be close by depth range to the displayed objects. Fitting assumes that
 370   //! for orthogonal projection the view volume contains the displayed objects
 371   //! completely. For zoomed perspective view, the view volume is adjusted such
 372   //! that it contains the objects or their parts, located in front of the camera.
 373   //! @param theScaleFactor [in] the scale factor for Z-range.
 374   //!   The range between Z-min, Z-max projection volume planes
 375   //!   evaluated by z fitting method will be scaled using this coefficient.
 376   //!   Program error exception is thrown if negative or zero value is passed.
 377   //! @param theMinMax [in] applicative min max boundaries.
 378   //! @param theScaleFactor [in] real graphical boundaries (not accounting infinite flag).
 379   Standard_EXPORT bool ZFitAll (const Standard_Real theScaleFactor,
 380                                 const Bnd_Box&      theMinMax,
 381                                 const Bnd_Box&      theGraphicBB,
 382                                 Standard_Real&      theZNear,
 383                                 Standard_Real&      theZFar) const;
 384
 385   //! Change Z-min and Z-max planes of projection volume to match the displayed objects.
 386   void ZFitAll (const Standard_Real theScaleFactor, const Bnd_Box& theMinMax, const Bnd_Box& theGraphicBB)
 387   {
 388     Standard_Real aZNear = 0.0, aZFar = 1.0;
 389     ZFitAll (theScaleFactor, theMinMax, theGraphicBB, aZNear, aZFar);
 390     SetZRange (aZNear, aZFar);
 391   }
 392
 393   //! Change the Near and Far Z-clipping plane positions.
 394   //! For orthographic projection, theZNear, theZFar can be negative or positive.
 395   //! For perspective projection, only positive values are allowed.
 396   //! Program error exception is raised if non-positive values are
 397   //! specified for perspective projection or theZNear >= theZFar.
 398   //! @param theZNear [in] the distance of the plane from the Eye.
 399   //! @param theZFar [in] the distance of the plane from the Eye.
 400   Standard_EXPORT void SetZRange (const Standard_Real theZNear, const Standard_Real theZFar);
 401
 402   //! Get the Near Z-clipping plane position.
 403   //! @return the distance of the plane from the Eye.
 404   Standard_Real ZNear() const
 405   {
 406     return myZNear;
 407   }
 408
 409   //! Get the Far Z-clipping plane position.
 410   //! @return the distance of the plane from the Eye.
 411   Standard_Real ZFar() const
 412   {
 413     return myZFar;
 414   }
 415
 416   //! Return TRUE if camera should calculate projection matrix for [0, 1] depth range or for [-1, 1] range.
 417   //! FALSE by default.
 418   Standard_Boolean IsZeroToOneDepth() const { return myIsZeroToOneDepth; }
 419
 420   //! Set using [0, 1] depth range or [-1, 1] range.
 421   void SetZeroToOneDepth (Standard_Boolean theIsZeroToOne)
 422   {
 423     if (myIsZeroToOneDepth != theIsZeroToOne)
 424     {
 425       myIsZeroToOneDepth = theIsZeroToOne;
 426       InvalidateProjection();
 427     }
 428   }
 429
 430   //! Changes width / height display ratio.
 431   //! @param theAspect [in] the display ratio.
 432   Standard_EXPORT void SetAspect (const Standard_Real theAspect);
 433
 434   //! Get camera display ratio.
 435   //! @return display ratio.
 436   Standard_Real Aspect() const
 437   {
 438     return myAspect;
 439   }
 440
 441   //! Sets stereographic focus distance.
 442   //! @param theType [in] the focus definition type. Focus can be defined
 443   //! as absolute value or relatively to (as coefficient of) coefficient of
 444   //! camera focal length.
 445   //! @param theZFocus [in] the focus absolute value or coefficient depending
 446   //! on the passed definition type.
 447   Standard_EXPORT void SetZFocus (const FocusType theType, const Standard_Real theZFocus);
 448
 449   //! Get stereographic focus value.
 450   //! @return absolute or relative stereographic focus value
 451   //! depending on its definition type.
 452   Standard_Real ZFocus() const
 453   {
 454     return myZFocus;
 455   }
 456
 457   //! Get stereographic focus definition type.
 458   //! @return definition type used for stereographic focus.
 459   FocusType ZFocusType() const
 460   {
 461     return myZFocusType;
 462   }
 463
 464   //! Sets Intraocular distance.
 465   //! @param theType [in] the IOD definition type. IOD can be defined as
 466   //! absolute value or relatively to (as coefficient of) camera focal length.
 467   //! @param theIOD [in] the Intraocular distance.
 468   Standard_EXPORT void SetIOD (const IODType theType, const Standard_Real theIOD);
 469
 470   //! Get Intraocular distance value.
 471   //! @return absolute or relative IOD value depending on its definition type.
 472   Standard_Real IOD() const
 473   {
 474     return myIOD;
 475   }
 476
 477   //! Get Intraocular distance definition type.
 478   //! @return definition type used for Intraocular distance.
 479   IODType GetIODType() const
 480   {
 481     return myIODType;
 482   }
 483
 484   //! Get current tile.
 485   const Graphic3d_CameraTile& Tile() const { return myTile; }
 486
 487   //! Sets the Tile defining the drawing sub-area within View.
 488   //! Note that tile defining a region outside the view boundaries is also valid - use method Graphic3d_CameraTile::Cropped() to assign a cropped copy.
 489   //! @param theTile tile definition
 490   Standard_EXPORT void SetTile (const Graphic3d_CameraTile& theTile);
 491
 492   //! Sets camera parameters to make current orientation matrix identity one.
 493   Standard_EXPORT void SetIdentityOrientation();
 494
 495 //! @name Basic camera operations
 496 public:
 497
 498   //! Transform orientation components of the camera:
 499   //! Eye, Up and Center points.
 500   //! @param theTrsf [in] the transformation to apply.
 501   Standard_EXPORT void Transform (const gp_Trsf& theTrsf);
 502
 503   //! Calculate view plane size at center (target) point
 504   //! and distance between ZFar and ZNear planes.
 505   //! @return values in form of gp_Pnt (Width, Height, Depth).
 506   gp_XYZ ViewDimensions() const
 507   {
 508     return ViewDimensions (Distance());
 509   }
 510
 511   //! Calculate view plane size at center point with specified Z offset
 512   //! and distance between ZFar and ZNear planes.
 513   //! @param theZValue [in] the distance from the eye in eye-to-center direction
 514   //! @return values in form of gp_Pnt (Width, Height, Depth).
 515   Standard_EXPORT gp_XYZ ViewDimensions (const Standard_Real theZValue) const;
 516
 517   //! Return offset to the view corner in NDC space within dimension X for 2d on-screen elements, which is normally 0.5.
 518   //! Can be clamped when FOVx exceeds FOV2d.
 519   Standard_Real NDC2dOffsetX() const
 520   {
 521     return myFOV2d >= myFOVx
 522          ? 0.5
 523          : 0.5 * myFOV2d / myFOVx;
 524   }
 525
 526   //! Return offset to the view corner in NDC space within dimension X for 2d on-screen elements, which is normally 0.5.
 527   //! Can be clamped when FOVy exceeds FOV2d.
 528   Standard_Real NDC2dOffsetY() const
 529   {
 530     return myFOV2d >= myFOVy
 531          ? 0.5
 532          : 0.5 * myFOV2d / myFOVy;
 533   }
 534
 535   //! Calculate WCS frustum planes for the camera projection volume.
 536   //! Frustum is a convex volume determined by six planes directing
 537   //! inwards.
 538   //! The frustum planes are usually used as inputs for camera algorithms.
 539   //! Thus, if any changes to projection matrix calculation are necessary,
 540   //! the frustum planes calculation should be also touched.
 541   //! @param theLeft [out] the frustum plane for left side of view.
 542   //! @param theRight [out] the frustum plane for right side of view.
 543   //! @param theBottom [out] the frustum plane for bottom side of view.
 544   //! @param theTop [out] the frustum plane for top side of view.
 545   //! @param theNear [out] the frustum plane for near side of view.
 546   //! @param theFar [out] the frustum plane for far side of view.
 547   Standard_EXPORT void Frustum (gp_Pln& theLeft,
 548                                 gp_Pln& theRight,
 549                                 gp_Pln& theBottom,
 550                                 gp_Pln& theTop,
 551                                 gp_Pln& theNear,
 552                                 gp_Pln& theFar) const;
 553
 554 //! @name Projection methods
 555 public:
 556
 557   //! Project point from world coordinate space to
 558   //! normalized device coordinates (mapping).
 559   //! @param thePnt [in] the 3D point in WCS.
 560   //! @return mapped point in NDC.
 561   Standard_EXPORT gp_Pnt Project (const gp_Pnt& thePnt) const;
 562
 563   //! Unproject point from normalized device coordinates
 564   //! to world coordinate space.
 565   //! @param thePnt [in] the NDC point.
 566   //! @return 3D point in WCS.
 567   Standard_EXPORT gp_Pnt UnProject (const gp_Pnt& thePnt) const;
 568
 569   //! Convert point from view coordinate space to
 570   //! projection coordinate space.
 571   //! @param thePnt [in] the point in VCS.
 572   //! @return point in NDC.
 573   Standard_EXPORT gp_Pnt ConvertView2Proj (const gp_Pnt& thePnt) const;
 574
 575   //! Convert point from projection coordinate space
 576   //! to view coordinate space.
 577   //! @param thePnt [in] the point in NDC.
 578   //! @return point in VCS.
 579   Standard_EXPORT gp_Pnt ConvertProj2View (const gp_Pnt& thePnt) const;
 580
 581   //! Convert point from world coordinate space to
 582   //! view coordinate space.
 583   //! @param thePnt [in] the 3D point in WCS.
 584   //! @return point in VCS.
 585   Standard_EXPORT gp_Pnt ConvertWorld2View (const gp_Pnt& thePnt) const;
 586
 587   //! Convert point from view coordinate space to
 588   //! world coordinates.
 589   //! @param thePnt [in] the 3D point in VCS.
 590   //! @return point in WCS.
 591   Standard_EXPORT gp_Pnt ConvertView2World (const gp_Pnt& thePnt) const;
 592
 593 //! @name Camera modification state
 594 public:
 595
 596   //! @return projection modification state of the camera.
 597   const Graphic3d_WorldViewProjState& WorldViewProjState() const
 598   {
 599     return myWorldViewProjState;
 600   }
 601
 602
 603   //! Returns modification state of camera projection matrix
 604   Standard_Size ProjectionState() const
 605   {
 606     return myWorldViewProjState.ProjectionState();
 607   }
 608
 609   //! Returns modification state of camera world view transformation matrix.
 610   Standard_Size WorldViewState() const
 611   {
 612     return myWorldViewProjState.WorldViewState();
 613   }
 614
 615 //! @name Lazily-computed orientation and projection matrices derived from camera parameters
 616 public:
 617
 618   //! Get orientation matrix.
 619   //! @return camera orientation matrix.
 620   Standard_EXPORT const Graphic3d_Mat4d& OrientationMatrix() const;
 621
 622   //! Get orientation matrix of Standard_ShortReal precision.
 623   //! @return camera orientation matrix.
 624   Standard_EXPORT const Graphic3d_Mat4& OrientationMatrixF() const;
 625
 626   //! Get monographic or middle point projection matrix used for monographic
 627   //! rendering and for point projection / unprojection.
 628   //! @return monographic projection matrix.
 629   Standard_EXPORT const Graphic3d_Mat4d& ProjectionMatrix() const;
 630
 631   //! Get monographic or middle point projection matrix of Standard_ShortReal precision used for monographic
 632   //! rendering and for point projection / unprojection.
 633   //! @return monographic projection matrix.
 634   Standard_EXPORT const Graphic3d_Mat4& ProjectionMatrixF() const;
 635
 636   //! @return stereographic matrix computed for left eye. Please note
 637   //! that this method is used for rendering for <i>Projection_Stereo</i>.
 638   Standard_EXPORT const Graphic3d_Mat4d& ProjectionStereoLeft() const;
 639
 640   //! @return stereographic matrix of Standard_ShortReal precision computed for left eye.
 641   //! Please note that this method is used for rendering for <i>Projection_Stereo</i>.
 642   Standard_EXPORT const Graphic3d_Mat4& ProjectionStereoLeftF() const;
 643
 644   //! @return stereographic matrix computed for right eye. Please note
 645   //! that this method is used for rendering for <i>Projection_Stereo</i>.
 646   Standard_EXPORT const Graphic3d_Mat4d& ProjectionStereoRight() const;
 647
 648   //! @return stereographic matrix of Standard_ShortReal precision computed for right eye.
 649   //! Please note that this method is used for rendering for <i>Projection_Stereo</i>.
 650   Standard_EXPORT const Graphic3d_Mat4& ProjectionStereoRightF() const;
 651
 652   //! Invalidate state of projection matrix.
 653   //! The matrix will be updated on request.
 654   Standard_EXPORT void InvalidateProjection();
 655
 656   //! Invalidate orientation matrix.
 657   //! The matrix will be updated on request.
 658   Standard_EXPORT void InvalidateOrientation();
 659
 660 public:
 661
 662   //! Get stereo projection matrices.
 663   //! @param theProjL      [out] left  eye projection matrix
 664   //! @param theHeadToEyeL [out] left  head to eye translation matrix
 665   //! @param theProjR      [out] right eye projection matrix
 666   //! @param theHeadToEyeR [out] right head to eye translation matrix
 667   Standard_EXPORT void StereoProjection (Graphic3d_Mat4d& theProjL,
 668                                          Graphic3d_Mat4d& theHeadToEyeL,
 669                                          Graphic3d_Mat4d& theProjR,
 670                                          Graphic3d_Mat4d& theHeadToEyeR) const;
 671
 672   //! Get stereo projection matrices.
 673   //! @param theProjL      [out] left  eye projection matrix
 674   //! @param theHeadToEyeL [out] left  head to eye translation matrix
 675   //! @param theProjR      [out] right eye projection matrix
 676   //! @param theHeadToEyeR [out] right head to eye translation matrix
 677   Standard_EXPORT void StereoProjectionF (Graphic3d_Mat4& theProjL,
 678                                           Graphic3d_Mat4& theHeadToEyeL,
 679                                           Graphic3d_Mat4& theProjR,
 680                                           Graphic3d_Mat4& theHeadToEyeR) const;
 681
 682   //! Unset all custom frustums and projection matrices.
 683   Standard_EXPORT void ResetCustomProjection();
 684
 685   //! Return TRUE if custom stereo frustums are set.
 686   bool IsCustomStereoFrustum() const { return myIsCustomFrustomLR; }
 687
 688   //! Set custom stereo frustums.
 689   //! These can be retrieved from APIs like OpenVR.
 690   Standard_EXPORT void SetCustomStereoFrustums (const Aspect_FrustumLRBT<Standard_Real>& theFrustumL,
 691                                                 const Aspect_FrustumLRBT<Standard_Real>& theFrustumR);
 692
 693   //! Return TRUE if custom stereo projection matrices are set.
 694   bool IsCustomStereoProjection() const { return myIsCustomProjMatLR; }
 695
 696   //! Set custom stereo projection matrices.
 697   //! @param theProjL      [in] left  eye projection matrix
 698   //! @param theHeadToEyeL [in] left  head to eye translation matrix
 699   //! @param theProjR      [in] right eye projection matrix
 700   //! @param theHeadToEyeR [in] right head to eye translation matrix
 701   Standard_EXPORT void SetCustomStereoProjection (const Graphic3d_Mat4d& theProjL,
 702                                                   const Graphic3d_Mat4d& theHeadToEyeL,
 703                                                   const Graphic3d_Mat4d& theProjR,
 704                                                   const Graphic3d_Mat4d& theHeadToEyeR);
 705
 706   //! Return TRUE if custom projection matrix is set.
 707   bool IsCustomMonoProjection() const { return myIsCustomProjMatM; }
 708
 709   //! Set custom projection matrix.
 710   Standard_EXPORT void SetCustomMonoProjection (const Graphic3d_Mat4d& theProj);
 711
 712   //! Dumps the content of me into the stream
 713   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
 714
 715 //! @name Managing projection and orientation cache
 716 private:
 717
 718   //! Get stereo projection matrices.
 719   //! @param theProjL      [out] left  eye projection matrix
 720   //! @param theHeadToEyeL [out] left  head to eye translation matrix
 721   //! @param theProjR      [out] right eye projection matrix
 722   //! @param theHeadToEyeR [out] right head to eye translation matrix
 723   template <typename Elem_t>
 724   Standard_EXPORT void stereoProjection (NCollection_Mat4<Elem_t>& theProjL,
 725                                          NCollection_Mat4<Elem_t>& theHeadToEyeL,
 726                                          NCollection_Mat4<Elem_t>& theProjR,
 727                                          NCollection_Mat4<Elem_t>& theHeadToEyeR) const;
 728
 729   //! Compute projection matrices.
 730   //! @param theProjM [out] mono projection matrix
 731   //! @param theProjL [out] left  eye projection matrix
 732   //! @param theProjR [out] right eye projection matrix
 733   //! @param theToAddHeadToEye [in] flag to pre-multiply head-to-eye translation
 734   template <typename Elem_t>
 735   Standard_EXPORT void computeProjection (NCollection_Mat4<Elem_t>& theProjM,
 736                                           NCollection_Mat4<Elem_t>& theProjL,
 737                                           NCollection_Mat4<Elem_t>& theProjR,
 738                                           bool theToAddHeadToEye) const;
 739
 740   //! Compute projection matrices.
 741   //! @param theMatrices [in] the matrices data container.
 742   template <typename Elem_t>
 743   TransformMatrices<Elem_t>& UpdateProjection (TransformMatrices<Elem_t>& theMatrices) const
 744   {
 745     if (!theMatrices.IsProjectionValid())
 746     {
 747       theMatrices.InitProjection();
 748       computeProjection (theMatrices.MProjection, theMatrices.LProjection, theMatrices.RProjection, true);
 749     }
 750     return theMatrices;
 751   }
 752
 753   //! Compute orientation matrix.
 754   //! @param theMatrices [in] the matrices data container.
 755   template <typename Elem_t>
 756   Standard_EXPORT
 757     TransformMatrices<Elem_t>& UpdateOrientation (TransformMatrices<Elem_t>& theMatrices) const;
 758
 759 private:
 760
 761   //! Compose orthographic projection matrix for the passed camera volume mapping.
 762   //! @param theOutMx [out] the projection matrix
 763   //! @param theLRBT [in] the left/right/bottom/top mapping (clipping) coordinates
 764   //! @param theNear [in] the near mapping (clipping) coordinate
 765   //! @param theFar [in] the far mapping (clipping) coordinate
 766   template <typename Elem_t>
 767   void orthoProj (NCollection_Mat4<Elem_t>& theOutMx,
 768                   const Aspect_FrustumLRBT<Elem_t>& theLRBT,
 769                   const Elem_t theNear,
 770                   const Elem_t theFar) const;
 771
 772   //! Compose perspective projection matrix for the passed camera volume mapping.
 773   //! @param theOutMx [out] the projection matrix
 774   //! @param theLRBT [in] the left/right/bottom/top mapping (clipping) coordinates
 775   //! @param theNear [in] the near mapping (clipping) coordinate
 776   //! @param theFar [in] the far mapping (clipping) coordinate
 777   template <typename Elem_t>
 778   void perspectiveProj (NCollection_Mat4<Elem_t>& theOutMx,
 779                         const Aspect_FrustumLRBT<Elem_t>& theLRBT,
 780                         const Elem_t theNear,
 781                         const Elem_t theFar) const;
 782
 783   //! Compose projection matrix for L/R stereo eyes.
 784   //! @param theOutMx [out] the projection matrix
 785   //! @param theLRBT [in] the left/right/bottom/top mapping (clipping) coordinates
 786   //! @param theNear [in] the near mapping (clipping) coordinate
 787   //! @param theFar [in] the far mapping (clipping) coordinate
 788   //! @param theIOD [in] the Intraocular distance
 789   //! @param theZFocus [in] the z coordinate of off-axis projection plane with zero parallax
 790   //! @param theEyeIndex [in] choose between L/R eyes
 791   template <typename Elem_t>
 792   void stereoEyeProj (NCollection_Mat4<Elem_t>& theOutMx,
 793                       const Aspect_FrustumLRBT<Elem_t>& theLRBT,
 794                       const Elem_t theNear,
 795                       const Elem_t theFar,
 796                       const Elem_t theIOD,
 797                       const Elem_t theZFocus,
 798                       const Aspect_Eye theEyeIndex) const;
 799
 800   //! Construct "look at" orientation transformation.
 801   //! Reference point differs for perspective and ortho modes
 802   //! (made for compatibility, to be improved..).
 803   //! @param theEye [in] the eye coordinates in 3D space.
 804   //! @param theFwdDir [in] view direction
 805   //! @param theUpDir [in] the up direction vector.
 806   //! @param theAxialScale [in] the axial scale vector.
 807   //! @param theOutMx [in/out] the orientation matrix.
 808   template <typename Elem_t>
 809   static void
 810     LookOrientation (const NCollection_Vec3<Elem_t>& theEye,
 811                      const NCollection_Vec3<Elem_t>& theFwdDir,
 812                      const NCollection_Vec3<Elem_t>& theUpDir,
 813                      const NCollection_Vec3<Elem_t>& theAxialScale,
 814                      NCollection_Mat4<Elem_t>&       theOutMx);
 815
 816 public:
 817
 818   //! Enumerates vertices of view volume.
 819   enum
 820   {
 821     FrustumVert_LeftBottomNear,
 822     FrustumVert_LeftBottomFar,
 823     FrustumVert_LeftTopNear,
 824     FrustumVert_LeftTopFar,
 825     FrustumVert_RightBottomNear,
 826     FrustumVert_RightBottomFar,
 827     FrustumVert_RightTopNear,
 828     FrustumVert_RightTopFar,
 829     FrustumVerticesNB
 830   };
 831
 832   //! Fill array of current view frustum corners.
 833   //! The size of this array is equal to FrustumVerticesNB.
 834   //! The order of vertices is as defined in FrustumVert_* enumeration.
 835   Standard_EXPORT void FrustumPoints (NCollection_Array1<Graphic3d_Vec3d>& thePoints,
 836                                       const Graphic3d_Mat4d& theModelWorld = Graphic3d_Mat4d()) const;
 837
 838 private:
 839
 840   gp_Dir        myUp;       //!< Camera up direction vector
 841   gp_Dir        myDirection;//!< Camera view direction (from eye)
 842   gp_Pnt        myEye;      //!< Camera eye position
 843   Standard_Real myDistance; //!< distance from Eye to Center
 844
 845   gp_XYZ myAxialScale; //!< World axial scale.
 846
 847   Projection    myProjType; //!< Projection type used for rendering.
 848   Standard_Real myFOVy;     //!< Field Of View in y axis.
 849   Standard_Real myFOVx;     //!< Field Of View in x axis.
 850   Standard_Real myFOV2d;    //!< Field Of View limit for 2d on-screen elements
 851   Standard_Real myFOVyTan;  //!< Field Of View as Tan(DTR_HALF * myFOVy)
 852   Standard_Real myZNear;    //!< Distance to near clipping plane.
 853   Standard_Real myZFar;     //!< Distance to far clipping plane.
 854   Standard_Real myAspect;   //!< Width to height display ratio.
 855   Standard_Boolean myIsZeroToOneDepth; //!< use [0, 1] depth range or [-1, 1]
 856
 857   Standard_Real myScale;      //!< Specifies parallel scale for orthographic projection.
 858   Standard_Real myZFocus;     //!< Stereographic focus value.
 859   FocusType     myZFocusType; //!< Stereographic focus definition type.
 860
 861   Standard_Real myIOD;     //!< Intraocular distance value.
 862   IODType       myIODType; //!< Intraocular distance definition type.
 863
 864   Graphic3d_CameraTile myTile;//!< Tile defining sub-area for drawing
 865
 866   Graphic3d_Mat4d  myCustomProjMatM;
 867   Graphic3d_Mat4d  myCustomProjMatL;
 868   Graphic3d_Mat4d  myCustomProjMatR;
 869   Graphic3d_Mat4d  myCustomHeadToEyeMatL;
 870   Graphic3d_Mat4d  myCustomHeadToEyeMatR;
 871   Aspect_FrustumLRBT<Standard_Real> myCustomFrustumL; //!< left  custom frustum
 872   Aspect_FrustumLRBT<Standard_Real> myCustomFrustumR; //!< right custom frustum
 873   Standard_Boolean myIsCustomProjMatM;  //!< flag indicating usage of custom projection matrix
 874   Standard_Boolean myIsCustomProjMatLR; //!< flag indicating usage of custom stereo projection matrices
 875   Standard_Boolean myIsCustomFrustomLR; //!< flag indicating usage of custom stereo frustums
 876
 877   mutable TransformMatrices<Standard_Real>      myMatricesD;
 878   mutable TransformMatrices<Standard_ShortReal> myMatricesF;
 879
 880   mutable Graphic3d_WorldViewProjState myWorldViewProjState;
 881
 882 public:
 883
 884   DEFINE_STANDARD_RTTIEXT(Graphic3d_Camera,Standard_Transient)
 885 };
 886
 887 DEFINE_STANDARD_HANDLE (Graphic3d_Camera, Standard_Transient)
 888
 889 //! Linear interpolation tool for camera orientation and position.
 890 //! This tool interpolates camera parameters scale, eye, center, rotation (up and direction vectors) independently.
 891 //! @sa Graphic3d_Camera::Interpolate()
 892 template<>
 893 inline void NCollection_Lerp<Handle(Graphic3d_Camera)>::Interpolate (const double theT,
 894                                                                      Handle(Graphic3d_Camera)& theResult) const
 895 {
 896   Graphic3d_Camera::Interpolate (myStart, myEnd, theT, theResult);
 897 }
 898
 899 //! Linear interpolation tool for camera orientation and position.
 900 //! This tool interpolates camera parameters scale, eye, center, rotation (up and direction vectors) independently.
 901 //! @sa Graphic3d_Camera::Interpolate()
 902 typedef NCollection_Lerp<Handle(Graphic3d_Camera)> Graphic3d_CameraLerp;
 903
 904 #endif