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 <Graphic3d_CameraTile.hxx>
  20 #include <Graphic3d_Mat4d.hxx>
  21 #include <Graphic3d_Mat4.hxx>
  22 #include <Graphic3d_Vec3.hxx>
  23 #include <Graphic3d_WorldViewProjState.hxx>
  24 #include <NCollection_Lerp.hxx>
  25
  26 #include <gp_Dir.hxx>
  27 #include <gp_Pnt.hxx>
  28
  29 #include <Standard_Macro.hxx>
  30 #include <Standard_TypeDef.hxx>
  31
  32 #include <Bnd_Box.hxx>
  33
  34 //! Forward declaration
  35 class Graphic3d_WorldViewProjState;
  36
  37 //! Camera class provides object-oriented approach to setting up projection
  38 //! and orientation properties of 3D view.
  39 class Graphic3d_Camera : public Standard_Transient
  40 {
  41 private:
  42
  43   //! Template container for cached matrices or Real/ShortReal types.
  44   template<typename Elem_t>
  45   struct TransformMatrices
  46   {
  47
  48     //! Default constructor.
  49     TransformMatrices() : myIsOrientationValid (Standard_False), myIsProjectionValid (Standard_False) {}
  50
  51     //! Initialize orientation.
  52     void InitOrientation()
  53     {
  54       myIsOrientationValid = Standard_True;
  55       Orientation.InitIdentity();
  56     }
  57
  58     //! Initialize projection.
  59     void InitProjection()
  60     {
  61       myIsProjectionValid = Standard_True;
  62       MProjection.InitIdentity();
  63       LProjection.InitIdentity();
  64       RProjection.InitIdentity();
  65     }
  66
  67     //! Invalidate orientation.
  68     void ResetOrientation() { myIsOrientationValid = Standard_False; }
  69
  70     //! Invalidate projection.
  71     void ResetProjection()  { myIsProjectionValid  = Standard_False; }
  72
  73     //! Return true if Orientation was not invalidated.
  74     Standard_Boolean IsOrientationValid() const { return myIsOrientationValid; }
  75
  76     //! Return true if Projection was not invalidated.
  77     Standard_Boolean IsProjectionValid()  const { return myIsProjectionValid;  }
  78
  79   public:
  80
  81     NCollection_Mat4<Elem_t> Orientation;
  82     NCollection_Mat4<Elem_t> MProjection;
  83     NCollection_Mat4<Elem_t> LProjection;
  84     NCollection_Mat4<Elem_t> RProjection;
  85
  86   private:
  87
  88     Standard_Boolean myIsOrientationValid;
  89     Standard_Boolean myIsProjectionValid;
  90
  91   };
  92
  93 public:
  94
  95   //! Enumerates supported monographic projections.
  96   //! - Projection_Orthographic : orthographic projection.
  97   //! - Projection_Perspective  : perspective projection.
  98   //! - Projection_Stereo       : stereographic projection.
  99   //! - Projection_MonoLeftEye  : mono projection for stereo left eye.
 100   //! - Projection_MonoRightEye : mono projection for stereo right eye.
 101   enum Projection
 102   {
 103     Projection_Orthographic,
 104     Projection_Perspective,
 105     Projection_Stereo,
 106     Projection_MonoLeftEye,
 107     Projection_MonoRightEye
 108   };
 109
 110   //! Enumerates approaches to define stereographic focus.
 111   //! - FocusType_Absolute : focus is specified as absolute value.
 112   //! - FocusType_Relative : focus is specified relative to
 113   //! (as coefficient of) camera focal length.
 114   enum FocusType
 115   {
 116     FocusType_Absolute,
 117     FocusType_Relative
 118   };
 119
 120   //! Enumerates approaches to define Intraocular distance.
 121   //! - IODType_Absolute : Intraocular distance is defined as absolute value.
 122   //! - IODType_Relative : Intraocular distance is defined relative to
 123   //! (as coefficient of) camera focal length.
 124   enum IODType
 125   {
 126     IODType_Absolute,
 127     IODType_Relative
 128   };
 129
 130 public:
 131
 132   //! Default constructor.
 133   //! Initializes camera with the following properties:
 134   //! Eye (0, 0, -2); Center (0, 0, 0); Up (0, 1, 0);
 135   //! Type (Orthographic); FOVy (45); Scale (1000); IsStereo(false);
 136   //! ZNear (0.001); ZFar (3000.0); Aspect(1);
 137   //! ZFocus(1.0); ZFocusType(Relative); IOD(0.05); IODType(Relative)
 138   Standard_EXPORT Graphic3d_Camera();
 139
 140   //! Copy constructor.
 141   //! @param theOther [in] the camera to copy from.
 142   Standard_EXPORT Graphic3d_Camera (const Handle(Graphic3d_Camera)& theOther);
 143
 144   //! Initialize mapping related parameters from other camera handle.
 145   Standard_EXPORT void CopyMappingData (const Handle(Graphic3d_Camera)& theOtherCamera);
 146
 147   //! Initialize orientation related parameters from other camera handle.
 148   Standard_EXPORT void CopyOrientationData (const Handle(Graphic3d_Camera)& theOtherCamera);
 149
 150   //! Copy properties of another camera.
 151   //! @param theOther [in] the camera to copy from.
 152   Standard_EXPORT void Copy (const Handle(Graphic3d_Camera)& theOther);
 153
 154 //! @name Public camera properties
 155 public:
 156
 157   //! Sets camera Eye position.
 158   //! @param theEye [in] the location of camera's Eye.
 159   Standard_EXPORT void SetEye (const gp_Pnt& theEye);
 160
 161   //! Get camera Eye position.
 162   //! @return camera eye location.
 163   const gp_Pnt& Eye() const
 164   {
 165     return myEye;
 166   }
 167
 168   //! Sets Center of the camera.
 169   //! @param theCenter [in] the point where the camera looks at.
 170   Standard_EXPORT void SetCenter (const gp_Pnt& theCenter);
 171
 172   //! Get Center of the camera.
 173   //! @return the point where the camera looks at.
 174   const gp_Pnt& Center() const
 175   {
 176     return myCenter;
 177   }
 178
 179   //! Sets camera Up direction vector, orthogonal to camera direction.
 180   //! @param theUp [in] the Up direction vector.
 181   Standard_EXPORT void SetUp (const gp_Dir& theUp);
 182
 183   //! Orthogonalize up direction vector.
 184   Standard_EXPORT void OrthogonalizeUp();
 185
 186   //! Return a copy of orthogonalized up direction vector.
 187   Standard_EXPORT gp_Dir OrthogonalizedUp() const;
 188
 189   //! Get camera Up direction vector.
 190   //! @return Camera's Up direction vector.
 191   const gp_Dir& Up() const
 192   {
 193     return myUp;
 194   }
 195
 196   //! Set camera axial scale.
 197   //! @param theAxialScale [in] the axial scale vector.
 198   Standard_EXPORT void SetAxialScale (const gp_XYZ& theAxialScale);
 199
 200   //! Get camera axial scale.
 201   //! @return Camera's axial scale.
 202   const gp_XYZ& AxialScale() const
 203   {
 204     return myAxialScale;
 205   }
 206
 207   //! Set distance of Eye from camera Center.
 208   //! @param theDistance [in] the distance.
 209   Standard_EXPORT void SetDistance (const Standard_Real theDistance);
 210
 211   //! Get distance of Eye from camera Center.
 212   //! @return the distance.
 213   Standard_EXPORT Standard_Real Distance() const;
 214
 215   //! Sets camera look direction.
 216   //! @param theDir [in] the direction.
 217   Standard_EXPORT void SetDirection (const gp_Dir& theDir);
 218
 219   //! Get camera look direction.
 220   //! @return camera look direction.
 221   Standard_EXPORT gp_Dir Direction() const;
 222
 223   //! Sets camera scale. For orthographic projection the scale factor
 224   //! corresponds to parallel scale of view mapping  (i.e. size
 225   //! of viewport). For perspective camera scale is converted to
 226   //! distance. The scale specifies equal size of the view projection in
 227   //! both dimensions assuming that the aspect is 1.0. The projection height
 228   //! and width are specified with the scale and correspondingly multiplied
 229   //! by the aspect.
 230   //! @param theScale [in] the scale factor.
 231   Standard_EXPORT void SetScale (const Standard_Real theScale);
 232
 233   //! Get camera scale.
 234   //! @return camera scale factor.
 235   Standard_EXPORT Standard_Real Scale() const;
 236
 237   //! Change camera projection type.
 238   //! When switching to perspective projection from orthographic one,
 239   //! the ZNear and ZFar are reset to default values (0.001, 3000.0)
 240   //! if less than 0.0.
 241   //! @param theProjectionType [in] the camera projection type.
 242   Standard_EXPORT void SetProjectionType (const Projection theProjection);
 243
 244   //! @return camera projection type.
 245   Projection ProjectionType() const
 246   {
 247     return myProjType;
 248   }
 249
 250   //! Check that the camera projection is orthographic.
 251   //! @return boolean flag that indicates whether the camera's projection is
 252   //! orthographic or not.
 253   Standard_Boolean IsOrthographic() const
 254   {
 255     return (myProjType == Projection_Orthographic);
 256   }
 257
 258   //! Check whether the camera projection is stereo.
 259   //! Please note that stereo rendering is now implemented with support of
 260   //! Quad buffering.
 261   //! @return boolean flag indicating whether the stereographic L/R projection
 262   //! is chosen.
 263   Standard_Boolean IsStereo() const
 264   {
 265     return (myProjType == Projection_Stereo);
 266   }
 267
 268   //! Set Field Of View (FOV) in y axis for perspective projection.
 269   //! @param theFOVy [in] the FOV in degrees.
 270   Standard_EXPORT void SetFOVy (const Standard_Real theFOVy);
 271
 272   //! Get Field Of View (FOV) in y axis.
 273   //! @return the FOV value in degrees.
 274   Standard_Real FOVy() const
 275   {
 276     return myFOVy;
 277   }
 278
 279   //! Estimate Z-min and Z-max planes of projection volume to match the
 280   //! displayed objects. The methods ensures that view volume will
 281   //! be close by depth range to the displayed objects. Fitting assumes that
 282   //! for orthogonal projection the view volume contains the displayed objects
 283   //! completely. For zoomed perspective view, the view volume is adjusted such
 284   //! that it contains the objects or their parts, located in front of the camera.
 285   //! @param theScaleFactor [in] the scale factor for Z-range.
 286   //!   The range between Z-min, Z-max projection volume planes
 287   //!   evaluated by z fitting method will be scaled using this coefficient.
 288   //!   Program error exception is thrown if negative or zero value is passed.
 289   //! @param theMinMax [in] applicative min max boundaries.
 290   //! @param theScaleFactor [in] real graphical boundaries (not accounting infinite flag).
 291   Standard_EXPORT bool ZFitAll (const Standard_Real theScaleFactor,
 292                                 const Bnd_Box&      theMinMax,
 293                                 const Bnd_Box&      theGraphicBB,
 294                                 Standard_Real&      theZNear,
 295                                 Standard_Real&      theZFar) const;
 296
 297   //! Change Z-min and Z-max planes of projection volume to match the displayed objects.
 298   void ZFitAll (const Standard_Real theScaleFactor, const Bnd_Box& theMinMax, const Bnd_Box& theGraphicBB)
 299   {
 300     Standard_Real aZNear = 0.0, aZFar = 1.0;
 301     ZFitAll (theScaleFactor, theMinMax, theGraphicBB, aZNear, aZFar);
 302     SetZRange (aZNear, aZFar);
 303   }
 304
 305   //! Change the Near and Far Z-clipping plane positions.
 306   //! For orthographic projection, theZNear, theZFar can be negative or positive.
 307   //! For perspective projection, only positive values are allowed.
 308   //! Program error exception is raised if non-positive values are
 309   //! specified for perspective projection or theZNear >= theZFar.
 310   //! @param theZNear [in] the distance of the plane from the Eye.
 311   //! @param theZFar [in] the distance of the plane from the Eye.
 312   Standard_EXPORT void SetZRange (const Standard_Real theZNear, const Standard_Real theZFar);
 313
 314   //! Get the Near Z-clipping plane position.
 315   //! @return the distance of the plane from the Eye.
 316   Standard_Real ZNear() const
 317   {
 318     return myZNear;
 319   }
 320
 321   //! Get the Far Z-clipping plane position.
 322   //! @return the distance of the plane from the Eye.
 323   Standard_Real ZFar() const
 324   {
 325     return myZFar;
 326   }
 327
 328   //! Changes width / height display ratio.
 329   //! @param theAspect [in] the display ratio.
 330   Standard_EXPORT void SetAspect (const Standard_Real theAspect);
 331
 332   //! Get camera display ratio.
 333   //! @return display ratio.
 334   Standard_Real Aspect() const
 335   {
 336     return myAspect;
 337   }
 338
 339   //! Sets stereographic focus distance.
 340   //! @param theType [in] the focus definition type. Focus can be defined
 341   //! as absolute value or relatively to (as coefficient of) coefficient of
 342   //! camera focal length.
 343   //! @param theZFocus [in] the focus absolute value or coefficient depending
 344   //! on the passed definition type.
 345   Standard_EXPORT void SetZFocus (const FocusType theType, const Standard_Real theZFocus);
 346
 347   //! Get stereographic focus value.
 348   //! @return absolute or relative stereographic focus value
 349   //! depending on its definition type.
 350   Standard_Real ZFocus() const
 351   {
 352     return myZFocus;
 353   }
 354
 355   //! Get stereographic focus definition type.
 356   //! @return definition type used for stereographic focus.
 357   FocusType ZFocusType() const
 358   {
 359     return myZFocusType;
 360   }
 361
 362   //! Sets Intraocular distance.
 363   //! @param theType [in] the IOD definition type. IOD can be defined as
 364   //! absolute value or relatively to (as coefficient of) camera focal length.
 365   //! @param theIOD [in] the Intraocular distance.
 366   Standard_EXPORT void SetIOD (const IODType theType, const Standard_Real theIOD);
 367
 368   //! Get Intraocular distance value.
 369   //! @return absolute or relative IOD value depending on its definition type.
 370   Standard_Real IOD() const
 371   {
 372     return myIOD;
 373   }
 374
 375   //! Get Intraocular distance definition type.
 376   //! @return definition type used for Intraocular distance.
 377   IODType GetIODType() const
 378   {
 379     return myIODType;
 380   }
 381
 382   //! Get current tile.
 383   const Graphic3d_CameraTile& Tile() const { return myTile; }
 384
 385   //! Sets the Tile defining the drawing sub-area within View.
 386   //! Note that tile defining a region outside the view boundaries is also valid - use method Graphic3d_CameraTile::Cropped() to assign a cropped copy.
 387   //! @param theTile tile definition
 388   Standard_EXPORT void SetTile (const Graphic3d_CameraTile& theTile);
 389
 390 //! @name Basic camera operations
 391 public:
 392
 393   //! Transform orientation components of the camera:
 394   //! Eye, Up and Center points.
 395   //! @param theTrsf [in] the transformation to apply.
 396   Standard_EXPORT void Transform (const gp_Trsf& theTrsf);
 397
 398   //! Calculate view plane size at center (target) point
 399   //! and distance between ZFar and ZNear planes.
 400   //! @return values in form of gp_Pnt (Width, Height, Depth).
 401   gp_XYZ ViewDimensions() const
 402   {
 403     return ViewDimensions (Distance());
 404   }
 405
 406   //! Calculate view plane size at center point with specified Z offset
 407   //! and distance between ZFar and ZNear planes.
 408   //! @param theZValue [in] the distance from the eye in eye-to-center direction
 409   //! @return values in form of gp_Pnt (Width, Height, Depth).
 410   Standard_EXPORT gp_XYZ ViewDimensions (const Standard_Real theZValue) const;
 411
 412   //! Calculate WCS frustum planes for the camera projection volume.
 413   //! Frustum is a convex volume determined by six planes directing
 414   //! inwards.
 415   //! The frustum planes are usually used as inputs for camera algorithms.
 416   //! Thus, if any changes to projection matrix calculation are necessary,
 417   //! the frustum planes calculation should be also touched.
 418   //! @param theLeft [out] the frustum plane for left side of view.
 419   //! @param theRight [out] the frustum plane for right side of view.
 420   //! @param theBottom [out] the frustum plane for bottom side of view.
 421   //! @param theTop [out] the frustum plane for top side of view.
 422   //! @param theNear [out] the frustum plane for near side of view.
 423   //! @param theFar [out] the frustum plane for far side of view.
 424   Standard_EXPORT void Frustum (gp_Pln& theLeft,
 425                                 gp_Pln& theRight,
 426                                 gp_Pln& theBottom,
 427                                 gp_Pln& theTop,
 428                                 gp_Pln& theNear,
 429                                 gp_Pln& theFar) const;
 430
 431 //! @name Projection methods
 432 public:
 433
 434   //! Project point from world coordinate space to
 435   //! normalized device coordinates (mapping).
 436   //! @param thePnt [in] the 3D point in WCS.
 437   //! @return mapped point in NDC.
 438   Standard_EXPORT gp_Pnt Project (const gp_Pnt& thePnt) const;
 439
 440   //! Unproject point from normalized device coordinates
 441   //! to world coordinate space.
 442   //! @param thePnt [in] the NDC point.
 443   //! @return 3D point in WCS.
 444   Standard_EXPORT gp_Pnt UnProject (const gp_Pnt& thePnt) const;
 445
 446   //! Convert point from view coordinate space to
 447   //! projection coordinate space.
 448   //! @param thePnt [in] the point in VCS.
 449   //! @return point in NDC.
 450   Standard_EXPORT gp_Pnt ConvertView2Proj (const gp_Pnt& thePnt) const;
 451
 452   //! Convert point from projection coordinate space
 453   //! to view coordinate space.
 454   //! @param thePnt [in] the point in NDC.
 455   //! @return point in VCS.
 456   Standard_EXPORT gp_Pnt ConvertProj2View (const gp_Pnt& thePnt) const;
 457
 458   //! Convert point from world coordinate space to
 459   //! view coordinate space.
 460   //! @param thePnt [in] the 3D point in WCS.
 461   //! @return point in VCS.
 462   Standard_EXPORT gp_Pnt ConvertWorld2View (const gp_Pnt& thePnt) const;
 463
 464   //! Convert point from view coordinate space to
 465   //! world coordinates.
 466   //! @param thePnt [in] the 3D point in VCS.
 467   //! @return point in WCS.
 468   Standard_EXPORT gp_Pnt ConvertView2World (const gp_Pnt& thePnt) const;
 469
 470 //! @name Camera modification state
 471 public:
 472
 473   //! @return projection modification state of the camera.
 474   const Graphic3d_WorldViewProjState& WorldViewProjState() const
 475   {
 476     return myWorldViewProjState;
 477   }
 478
 479
 480   //! Returns modification state of camera projection matrix
 481   Standard_Size ProjectionState() const
 482   {
 483     return myWorldViewProjState.ProjectionState();
 484   }
 485
 486   //! Returns modification state of camera world view transformation matrix.
 487   Standard_Size WorldViewState() const
 488   {
 489     return myWorldViewProjState.WorldViewState();
 490   }
 491
 492 //! @name Lazily-computed orientation and projection matrices derived from camera parameters
 493 public:
 494
 495   //! Get orientation matrix.
 496   //! @return camera orientation matrix.
 497   Standard_EXPORT const Graphic3d_Mat4d& OrientationMatrix() const;
 498
 499   //! Get orientation matrix of Standard_ShortReal precision.
 500   //! @return camera orientation matrix.
 501   Standard_EXPORT const Graphic3d_Mat4& OrientationMatrixF() const;
 502
 503   //! Get monographic or middle point projection matrix used for monographic
 504   //! rendering and for point projection / unprojection.
 505   //! @return monographic projection matrix.
 506   Standard_EXPORT const Graphic3d_Mat4d& ProjectionMatrix() const;
 507
 508   //! Get monographic or middle point projection matrix of Standard_ShortReal precision used for monographic
 509   //! rendering and for point projection / unprojection.
 510   //! @return monographic projection matrix.
 511   Standard_EXPORT const Graphic3d_Mat4& ProjectionMatrixF() const;
 512
 513   //! @return stereographic matrix computed for left eye. Please note
 514   //! that this method is used for rendering for <i>Projection_Stereo</i>.
 515   Standard_EXPORT const Graphic3d_Mat4d& ProjectionStereoLeft() const;
 516
 517   //! @return stereographic matrix of Standard_ShortReal precision computed for left eye.
 518   //! Please note that this method is used for rendering for <i>Projection_Stereo</i>.
 519   Standard_EXPORT const Graphic3d_Mat4& ProjectionStereoLeftF() const;
 520
 521   //! @return stereographic matrix computed for right eye. Please note
 522   //! that this method is used for rendering for <i>Projection_Stereo</i>.
 523   Standard_EXPORT const Graphic3d_Mat4d& ProjectionStereoRight() const;
 524
 525   //! @return stereographic matrix of Standard_ShortReal precision computed for right eye.
 526   //! Please note that this method is used for rendering for <i>Projection_Stereo</i>.
 527   Standard_EXPORT const Graphic3d_Mat4& ProjectionStereoRightF() const;
 528
 529   //! Invalidate state of projection matrix.
 530   //! The matrix will be updated on request.
 531   Standard_EXPORT void InvalidateProjection();
 532
 533   //! Invalidate orientation matrix.
 534   //! The matrix will be updated on request.
 535   Standard_EXPORT void InvalidateOrientation();
 536
 537 //! @name Managing projection and orientation cache
 538 private:
 539
 540   //! Compute projection matrices.
 541   //! @param theMatrices [in] the matrices data container.
 542   template <typename Elem_t>
 543   Standard_EXPORT
 544     TransformMatrices<Elem_t>& UpdateProjection (TransformMatrices<Elem_t>& theMatrices) const;
 545
 546   //! Compute orientation matrix.
 547   //! @param theMatrices [in] the matrices data container.
 548   template <typename Elem_t>
 549   Standard_EXPORT
 550     TransformMatrices<Elem_t>& UpdateOrientation (TransformMatrices<Elem_t>& theMatrices) const;
 551
 552 private:
 553
 554   //! Compose orthographic projection matrix for
 555   //! the passed camera volume mapping.
 556   //! @param theLeft [in] the left mapping (clipping) coordinate.
 557   //! @param theRight [in] the right mapping (clipping) coordinate.
 558   //! @param theBottom [in] the bottom mapping (clipping) coordinate.
 559   //! @param theTop [in] the top mapping (clipping) coordinate.
 560   //! @param theNear [in] the near mapping (clipping) coordinate.
 561   //! @param theFar [in] the far mapping (clipping) coordinate.
 562   //! @param theOutMx [out] the projection matrix.
 563   template <typename Elem_t>
 564   static void
 565     OrthoProj (const Elem_t              theLeft,
 566                const Elem_t              theRight,
 567                const Elem_t              theBottom,
 568                const Elem_t              theTop,
 569                const Elem_t              theNear,
 570                const Elem_t              theFar,
 571                NCollection_Mat4<Elem_t>& theOutMx);
 572
 573   //! Compose perspective projection matrix for
 574   //! the passed camera volume mapping.
 575   //! @param theLeft [in] the left mapping (clipping) coordinate.
 576   //! @param theRight [in] the right mapping (clipping) coordinate.
 577   //! @param theBottom [in] the bottom mapping (clipping) coordinate.
 578   //! @param theTop [in] the top mapping (clipping) coordinate.
 579   //! @param theNear [in] the near mapping (clipping) coordinate.
 580   //! @param theFar [in] the far mapping (clipping) coordinate.
 581   //! @param theOutMx [out] the projection matrix.
 582   template <typename Elem_t>
 583   static void
 584     PerspectiveProj (const Elem_t              theLeft,
 585                      const Elem_t              theRight,
 586                      const Elem_t              theBottom,
 587                      const Elem_t              theTop,
 588                      const Elem_t              theNear,
 589                      const Elem_t              theFar,
 590                      NCollection_Mat4<Elem_t>& theOutMx);
 591
 592   //! Compose projection matrix for L/R stereo eyes.
 593   //! @param theLeft [in] the left mapping (clipping) coordinate.
 594   //! @param theRight [in] the right mapping (clipping) coordinate.
 595   //! @param theBottom [in] the bottom mapping (clipping) coordinate.
 596   //! @param theTop [in] the top mapping (clipping) coordinate.
 597   //! @param theNear [in] the near mapping (clipping) coordinate.
 598   //! @param theFar [in] the far mapping (clipping) coordinate.
 599   //! @param theIOD [in] the Intraocular distance.
 600   //! @param theZFocus [in] the z coordinate of off-axis
 601   //! projection plane with zero parallax.
 602   //! @param theIsLeft [in] boolean flag to choose between L/R eyes.
 603   //! @param theOutMx [out] the projection matrix.
 604   template <typename Elem_t>
 605   static void
 606     StereoEyeProj (const Elem_t              theLeft,
 607                    const Elem_t              theRight,
 608                    const Elem_t              theBottom,
 609                    const Elem_t              theTop,
 610                    const Elem_t              theNear,
 611                    const Elem_t              theFar,
 612                    const Elem_t              theIOD,
 613                    const Elem_t              theZFocus,
 614                    const Standard_Boolean    theIsLeft,
 615                    NCollection_Mat4<Elem_t>& theOutMx);
 616
 617   //! Construct "look at" orientation transformation.
 618   //! Reference point differs for perspective and ortho modes
 619   //! (made for compatibility, to be improved..).
 620   //! @param theEye [in] the eye coordinates in 3D space.
 621   //! @param theLookAt [in] the point the camera looks at.
 622   //! @param theUpDir [in] the up direction vector.
 623   //! @param theAxialScale [in] the axial scale vector.
 624   //! @param theOutMx [in/out] the orientation matrix.
 625   template <typename Elem_t>
 626   static void
 627     LookOrientation (const NCollection_Vec3<Elem_t>& theEye,
 628                      const NCollection_Vec3<Elem_t>& theLookAt,
 629                      const NCollection_Vec3<Elem_t>& theUpDir,
 630                      const NCollection_Vec3<Elem_t>& theAxialScale,
 631                      NCollection_Mat4<Elem_t>&       theOutMx);
 632
 633 private:
 634
 635   gp_Dir myUp;     //!< Camera up direction vector.
 636   gp_Pnt myEye;    //!< Camera eye position.
 637   gp_Pnt myCenter; //!< Camera center.
 638
 639   gp_XYZ myAxialScale; //!< World axial scale.
 640
 641   Projection    myProjType; //!< Projection type used for rendering.
 642   Standard_Real myFOVy;     //!< Field Of View in y axis.
 643   Standard_Real myFOVyTan;  //!< Field Of View as Tan(DTR_HALF * myFOVy)
 644   Standard_Real myZNear;    //!< Distance to near clipping plane.
 645   Standard_Real myZFar;     //!< Distance to far clipping plane.
 646   Standard_Real myAspect;   //!< Width to height display ratio.
 647
 648   Standard_Real myScale;      //!< Specifies parallel scale for orthographic projection.
 649   Standard_Real myZFocus;     //!< Stereographic focus value.
 650   FocusType     myZFocusType; //!< Stereographic focus definition type.
 651
 652   Standard_Real myIOD;     //!< Intraocular distance value.
 653   IODType       myIODType; //!< Intraocular distance definition type.
 654
 655   Graphic3d_CameraTile myTile;//!< Tile defining sub-area for drawing
 656
 657   mutable TransformMatrices<Standard_Real>      myMatricesD;
 658   mutable TransformMatrices<Standard_ShortReal> myMatricesF;
 659
 660   mutable Graphic3d_WorldViewProjState myWorldViewProjState;
 661
 662 public:
 663
 664   DEFINE_STANDARD_RTTIEXT(Graphic3d_Camera,Standard_Transient)
 665 };
 666
 667 DEFINE_STANDARD_HANDLE (Graphic3d_Camera, Standard_Transient)
 668
 669 //! Linear interpolation tool for camera orientation and position.
 670 //! This tool interpolates camera parameters scale, eye, center, rotation (up and direction vectors) independently.
 671 //!
 672 //! Eye/Center interpolation is performed through defining an anchor point in-between Center and Eye.
 673 //! The anchor position is defined as point near to the camera point which has smaller translation part.
 674 //! The main idea is to keep the distance between Center and Eye
 675 //! (which will change if Center and Eye translation will be interpolated independently).
 676 //! E.g.:
 677 //!  - When both Center and Eye are moved at the same vector -> both will be just translated by straight line
 678 //!  - When Center is not moved -> camera Eye    will move around Center through arc
 679 //!  - When Eye    is not moved -> camera Center will move around Eye    through arc
 680 //!  - When both Center and Eye are move by different vectors -> transformation will be something in between,
 681 //!    and will try interpolate linearly the distance between Center and Eye.
 682 //!
 683 //! This transformation might be not in line with user expectations.
 684 //! In this case, application might define intermediate camera positions for interpolation
 685 //! or implement own interpolation logic.
 686 template<>
 687 Standard_EXPORT void NCollection_Lerp<Handle(Graphic3d_Camera)>::Interpolate (const double theT,
 688                                                                               Handle(Graphic3d_Camera)& theResult) const;
 689 typedef NCollection_Lerp<Handle(Graphic3d_Camera)> Graphic3d_CameraLerp;
 690
 691 #endif