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