0031922: Configuration - unresolved external symbol NCollection_Lerp<Handle(Graphic3d...
[occt.git] / 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   //! Estimate Z-min and Z-max planes of projection volume to match the
363   //! displayed objects. The methods ensures that view volume will
364   //! be close by depth range to the displayed objects. Fitting assumes that
365   //! for orthogonal projection the view volume contains the displayed objects
366   //! completely. For zoomed perspective view, the view volume is adjusted such
367   //! that it contains the objects or their parts, located in front of the camera.
368   //! @param theScaleFactor [in] the scale factor for Z-range.
369   //!   The range between Z-min, Z-max projection volume planes
370   //!   evaluated by z fitting method will be scaled using this coefficient.
371   //!   Program error exception is thrown if negative or zero value is passed.
372   //! @param theMinMax [in] applicative min max boundaries.
373   //! @param theScaleFactor [in] real graphical boundaries (not accounting infinite flag).
374   Standard_EXPORT bool ZFitAll (const Standard_Real theScaleFactor,
375                                 const Bnd_Box&      theMinMax,
376                                 const Bnd_Box&      theGraphicBB,
377                                 Standard_Real&      theZNear,
378                                 Standard_Real&      theZFar) const;
379
380   //! Change Z-min and Z-max planes of projection volume to match the displayed objects.
381   void ZFitAll (const Standard_Real theScaleFactor, const Bnd_Box& theMinMax, const Bnd_Box& theGraphicBB)
382   {
383     Standard_Real aZNear = 0.0, aZFar = 1.0;
384     ZFitAll (theScaleFactor, theMinMax, theGraphicBB, aZNear, aZFar);
385     SetZRange (aZNear, aZFar);
386   }
387
388   //! Change the Near and Far Z-clipping plane positions.
389   //! For orthographic projection, theZNear, theZFar can be negative or positive.
390   //! For perspective projection, only positive values are allowed.
391   //! Program error exception is raised if non-positive values are
392   //! specified for perspective projection or theZNear >= theZFar.
393   //! @param theZNear [in] the distance of the plane from the Eye.
394   //! @param theZFar [in] the distance of the plane from the Eye.
395   Standard_EXPORT void SetZRange (const Standard_Real theZNear, const Standard_Real theZFar);
396
397   //! Get the Near Z-clipping plane position.
398   //! @return the distance of the plane from the Eye.
399   Standard_Real ZNear() const
400   {
401     return myZNear;
402   }
403
404   //! Get the Far Z-clipping plane position.
405   //! @return the distance of the plane from the Eye.
406   Standard_Real ZFar() const
407   {
408     return myZFar;
409   }
410
411   //! Changes width / height display ratio.
412   //! @param theAspect [in] the display ratio.
413   Standard_EXPORT void SetAspect (const Standard_Real theAspect);
414
415   //! Get camera display ratio.
416   //! @return display ratio.
417   Standard_Real Aspect() const
418   {
419     return myAspect;
420   }
421
422   //! Sets stereographic focus distance.
423   //! @param theType [in] the focus definition type. Focus can be defined
424   //! as absolute value or relatively to (as coefficient of) coefficient of
425   //! camera focal length.
426   //! @param theZFocus [in] the focus absolute value or coefficient depending
427   //! on the passed definition type.
428   Standard_EXPORT void SetZFocus (const FocusType theType, const Standard_Real theZFocus);
429
430   //! Get stereographic focus value.
431   //! @return absolute or relative stereographic focus value
432   //! depending on its definition type.
433   Standard_Real ZFocus() const
434   {
435     return myZFocus;
436   }
437
438   //! Get stereographic focus definition type.
439   //! @return definition type used for stereographic focus.
440   FocusType ZFocusType() const
441   {
442     return myZFocusType;
443   }
444
445   //! Sets Intraocular distance.
446   //! @param theType [in] the IOD definition type. IOD can be defined as
447   //! absolute value or relatively to (as coefficient of) camera focal length.
448   //! @param theIOD [in] the Intraocular distance.
449   Standard_EXPORT void SetIOD (const IODType theType, const Standard_Real theIOD);
450
451   //! Get Intraocular distance value.
452   //! @return absolute or relative IOD value depending on its definition type.
453   Standard_Real IOD() const
454   {
455     return myIOD;
456   }
457
458   //! Get Intraocular distance definition type.
459   //! @return definition type used for Intraocular distance.
460   IODType GetIODType() const
461   {
462     return myIODType;
463   }
464
465   //! Get current tile.
466   const Graphic3d_CameraTile& Tile() const { return myTile; }
467
468   //! Sets the Tile defining the drawing sub-area within View.
469   //! Note that tile defining a region outside the view boundaries is also valid - use method Graphic3d_CameraTile::Cropped() to assign a cropped copy.
470   //! @param theTile tile definition
471   Standard_EXPORT void SetTile (const Graphic3d_CameraTile& theTile);
472
473 //! @name Basic camera operations
474 public:
475
476   //! Transform orientation components of the camera:
477   //! Eye, Up and Center points.
478   //! @param theTrsf [in] the transformation to apply.
479   Standard_EXPORT void Transform (const gp_Trsf& theTrsf);
480
481   //! Calculate view plane size at center (target) point
482   //! and distance between ZFar and ZNear planes.
483   //! @return values in form of gp_Pnt (Width, Height, Depth).
484   gp_XYZ ViewDimensions() const
485   {
486     return ViewDimensions (Distance());
487   }
488
489   //! Calculate view plane size at center point with specified Z offset
490   //! and distance between ZFar and ZNear planes.
491   //! @param theZValue [in] the distance from the eye in eye-to-center direction
492   //! @return values in form of gp_Pnt (Width, Height, Depth).
493   Standard_EXPORT gp_XYZ ViewDimensions (const Standard_Real theZValue) const;
494
495   //! Return offset to the view corner in NDC space within dimension X for 2d on-screen elements, which is normally 0.5.
496   //! Can be clamped when FOVx exceeds FOV2d.
497   Standard_Real NDC2dOffsetX() const
498   {
499     return myFOV2d >= myFOVx
500          ? 0.5
501          : 0.5 * myFOV2d / myFOVx;
502   }
503
504   //! Return offset to the view corner in NDC space within dimension X for 2d on-screen elements, which is normally 0.5.
505   //! Can be clamped when FOVy exceeds FOV2d.
506   Standard_Real NDC2dOffsetY() const
507   {
508     return myFOV2d >= myFOVy
509          ? 0.5
510          : 0.5 * myFOV2d / myFOVy;
511   }
512
513   //! Calculate WCS frustum planes for the camera projection volume.
514   //! Frustum is a convex volume determined by six planes directing
515   //! inwards.
516   //! The frustum planes are usually used as inputs for camera algorithms.
517   //! Thus, if any changes to projection matrix calculation are necessary,
518   //! the frustum planes calculation should be also touched.
519   //! @param theLeft [out] the frustum plane for left side of view.
520   //! @param theRight [out] the frustum plane for right side of view.
521   //! @param theBottom [out] the frustum plane for bottom side of view.
522   //! @param theTop [out] the frustum plane for top side of view.
523   //! @param theNear [out] the frustum plane for near side of view.
524   //! @param theFar [out] the frustum plane for far side of view.
525   Standard_EXPORT void Frustum (gp_Pln& theLeft,
526                                 gp_Pln& theRight,
527                                 gp_Pln& theBottom,
528                                 gp_Pln& theTop,
529                                 gp_Pln& theNear,
530                                 gp_Pln& theFar) const;
531
532 //! @name Projection methods
533 public:
534
535   //! Project point from world coordinate space to
536   //! normalized device coordinates (mapping).
537   //! @param thePnt [in] the 3D point in WCS.
538   //! @return mapped point in NDC.
539   Standard_EXPORT gp_Pnt Project (const gp_Pnt& thePnt) const;
540
541   //! Unproject point from normalized device coordinates
542   //! to world coordinate space.
543   //! @param thePnt [in] the NDC point.
544   //! @return 3D point in WCS.
545   Standard_EXPORT gp_Pnt UnProject (const gp_Pnt& thePnt) const;
546
547   //! Convert point from view coordinate space to
548   //! projection coordinate space.
549   //! @param thePnt [in] the point in VCS.
550   //! @return point in NDC.
551   Standard_EXPORT gp_Pnt ConvertView2Proj (const gp_Pnt& thePnt) const;
552
553   //! Convert point from projection coordinate space
554   //! to view coordinate space.
555   //! @param thePnt [in] the point in NDC.
556   //! @return point in VCS.
557   Standard_EXPORT gp_Pnt ConvertProj2View (const gp_Pnt& thePnt) const;
558
559   //! Convert point from world coordinate space to
560   //! view coordinate space.
561   //! @param thePnt [in] the 3D point in WCS.
562   //! @return point in VCS.
563   Standard_EXPORT gp_Pnt ConvertWorld2View (const gp_Pnt& thePnt) const;
564
565   //! Convert point from view coordinate space to
566   //! world coordinates.
567   //! @param thePnt [in] the 3D point in VCS.
568   //! @return point in WCS.
569   Standard_EXPORT gp_Pnt ConvertView2World (const gp_Pnt& thePnt) const;
570
571 //! @name Camera modification state
572 public:
573
574   //! @return projection modification state of the camera.
575   const Graphic3d_WorldViewProjState& WorldViewProjState() const
576   {
577     return myWorldViewProjState;
578   }
579
580
581   //! Returns modification state of camera projection matrix
582   Standard_Size ProjectionState() const
583   {
584     return myWorldViewProjState.ProjectionState();
585   }
586
587   //! Returns modification state of camera world view transformation matrix.
588   Standard_Size WorldViewState() const
589   {
590     return myWorldViewProjState.WorldViewState();
591   }
592
593 //! @name Lazily-computed orientation and projection matrices derived from camera parameters
594 public:
595
596   //! Get orientation matrix.
597   //! @return camera orientation matrix.
598   Standard_EXPORT const Graphic3d_Mat4d& OrientationMatrix() const;
599
600   //! Get orientation matrix of Standard_ShortReal precision.
601   //! @return camera orientation matrix.
602   Standard_EXPORT const Graphic3d_Mat4& OrientationMatrixF() const;
603
604   //! Get monographic or middle point projection matrix used for monographic
605   //! rendering and for point projection / unprojection.
606   //! @return monographic projection matrix.
607   Standard_EXPORT const Graphic3d_Mat4d& ProjectionMatrix() const;
608
609   //! Get monographic or middle point projection matrix of Standard_ShortReal precision used for monographic
610   //! rendering and for point projection / unprojection.
611   //! @return monographic projection matrix.
612   Standard_EXPORT const Graphic3d_Mat4& ProjectionMatrixF() const;
613
614   //! @return stereographic matrix computed for left eye. Please note
615   //! that this method is used for rendering for <i>Projection_Stereo</i>.
616   Standard_EXPORT const Graphic3d_Mat4d& ProjectionStereoLeft() const;
617
618   //! @return stereographic matrix of Standard_ShortReal precision computed for left eye.
619   //! Please note that this method is used for rendering for <i>Projection_Stereo</i>.
620   Standard_EXPORT const Graphic3d_Mat4& ProjectionStereoLeftF() const;
621
622   //! @return stereographic matrix computed for right eye. Please note
623   //! that this method is used for rendering for <i>Projection_Stereo</i>.
624   Standard_EXPORT const Graphic3d_Mat4d& ProjectionStereoRight() const;
625
626   //! @return stereographic matrix of Standard_ShortReal precision computed for right eye.
627   //! Please note that this method is used for rendering for <i>Projection_Stereo</i>.
628   Standard_EXPORT const Graphic3d_Mat4& ProjectionStereoRightF() const;
629
630   //! Invalidate state of projection matrix.
631   //! The matrix will be updated on request.
632   Standard_EXPORT void InvalidateProjection();
633
634   //! Invalidate orientation matrix.
635   //! The matrix will be updated on request.
636   Standard_EXPORT void InvalidateOrientation();
637
638 public:
639
640   //! Get stereo projection matrices.
641   //! @param theProjL      [out] left  eye projection matrix
642   //! @param theHeadToEyeL [out] left  head to eye translation matrix
643   //! @param theProjR      [out] right eye projection matrix
644   //! @param theHeadToEyeR [out] right head to eye translation matrix
645   Standard_EXPORT void StereoProjection (Graphic3d_Mat4d& theProjL,
646                                          Graphic3d_Mat4d& theHeadToEyeL,
647                                          Graphic3d_Mat4d& theProjR,
648                                          Graphic3d_Mat4d& theHeadToEyeR) const;
649
650   //! Get stereo projection matrices.
651   //! @param theProjL      [out] left  eye projection matrix
652   //! @param theHeadToEyeL [out] left  head to eye translation matrix
653   //! @param theProjR      [out] right eye projection matrix
654   //! @param theHeadToEyeR [out] right head to eye translation matrix
655   Standard_EXPORT void StereoProjectionF (Graphic3d_Mat4& theProjL,
656                                           Graphic3d_Mat4& theHeadToEyeL,
657                                           Graphic3d_Mat4& theProjR,
658                                           Graphic3d_Mat4& theHeadToEyeR) const;
659
660   //! Unset all custom frustums and projection matrices.
661   Standard_EXPORT void ResetCustomProjection();
662
663   //! Return TRUE if custom stereo frustums are set.
664   bool IsCustomStereoFrustum() const { return myIsCustomFrustomLR; }
665
666   //! Set custom stereo frustums.
667   //! These can be retrieved from APIs like OpenVR.
668   Standard_EXPORT void SetCustomStereoFrustums (const Aspect_FrustumLRBT<Standard_Real>& theFrustumL,
669                                                 const Aspect_FrustumLRBT<Standard_Real>& theFrustumR);
670
671   //! Return TRUE if custom stereo projection matrices are set.
672   bool IsCustomStereoProjection() const { return myIsCustomProjMatLR; }
673
674   //! Set custom stereo projection matrices.
675   //! @param theProjL      [in] left  eye projection matrix
676   //! @param theHeadToEyeL [in] left  head to eye translation matrix
677   //! @param theProjR      [in] right eye projection matrix
678   //! @param theHeadToEyeR [in] right head to eye translation matrix
679   Standard_EXPORT void SetCustomStereoProjection (const Graphic3d_Mat4d& theProjL,
680                                                   const Graphic3d_Mat4d& theHeadToEyeL,
681                                                   const Graphic3d_Mat4d& theProjR,
682                                                   const Graphic3d_Mat4d& theHeadToEyeR);
683
684   //! Return TRUE if custom projection matrix is set.
685   bool IsCustomMonoProjection() const { return myIsCustomProjMatM; }
686
687   //! Set custom projection matrix.
688   Standard_EXPORT void SetCustomMonoProjection (const Graphic3d_Mat4d& theProj);
689
690   //! Dumps the content of me into the stream
691   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
692
693 //! @name Managing projection and orientation cache
694 private:
695
696   //! Get stereo projection matrices.
697   //! @param theProjL      [out] left  eye projection matrix
698   //! @param theHeadToEyeL [out] left  head to eye translation matrix
699   //! @param theProjR      [out] right eye projection matrix
700   //! @param theHeadToEyeR [out] right head to eye translation matrix
701   template <typename Elem_t>
702   Standard_EXPORT void stereoProjection (NCollection_Mat4<Elem_t>& theProjL,
703                                          NCollection_Mat4<Elem_t>& theHeadToEyeL,
704                                          NCollection_Mat4<Elem_t>& theProjR,
705                                          NCollection_Mat4<Elem_t>& theHeadToEyeR) const;
706
707   //! Compute projection matrices.
708   //! @param theProjM [out] mono projection matrix
709   //! @param theProjL [out] left  eye projection matrix
710   //! @param theProjR [out] right eye projection matrix
711   //! @param theToAddHeadToEye [in] flag to pre-multiply head-to-eye translation
712   template <typename Elem_t>
713   Standard_EXPORT void computeProjection (NCollection_Mat4<Elem_t>& theProjM,
714                                           NCollection_Mat4<Elem_t>& theProjL,
715                                           NCollection_Mat4<Elem_t>& theProjR,
716                                           bool theToAddHeadToEye) const;
717
718   //! Compute projection matrices.
719   //! @param theMatrices [in] the matrices data container.
720   template <typename Elem_t>
721   TransformMatrices<Elem_t>& UpdateProjection (TransformMatrices<Elem_t>& theMatrices) const
722   {
723     if (!theMatrices.IsProjectionValid())
724     {
725       theMatrices.InitProjection();
726       computeProjection (theMatrices.MProjection, theMatrices.LProjection, theMatrices.RProjection, true);
727     }
728     return theMatrices;
729   }
730
731   //! Compute orientation matrix.
732   //! @param theMatrices [in] the matrices data container.
733   template <typename Elem_t>
734   Standard_EXPORT
735     TransformMatrices<Elem_t>& UpdateOrientation (TransformMatrices<Elem_t>& theMatrices) const;
736
737 private:
738
739   //! Compose orthographic projection matrix for the passed camera volume mapping.
740   //! @param theOutMx [out] the projection matrix
741   //! @param theLRBT [in] the left/right/bottom/top mapping (clipping) coordinates
742   //! @param theNear [in] the near mapping (clipping) coordinate
743   //! @param theFar [in] the far mapping (clipping) coordinate
744   template <typename Elem_t>
745   static void orthoProj (NCollection_Mat4<Elem_t>& theOutMx,
746                          const Aspect_FrustumLRBT<Elem_t>& theLRBT,
747                          const Elem_t theNear,
748                          const Elem_t theFar);
749
750   //! Compose perspective projection matrix for the passed camera volume mapping.
751   //! @param theOutMx [out] the projection matrix
752   //! @param theLRBT [in] the left/right/bottom/top mapping (clipping) coordinates
753   //! @param theNear [in] the near mapping (clipping) coordinate
754   //! @param theFar [in] the far mapping (clipping) coordinate
755   template <typename Elem_t>
756   static void perspectiveProj (NCollection_Mat4<Elem_t>& theOutMx,
757                                const Aspect_FrustumLRBT<Elem_t>& theLRBT,
758                                const Elem_t theNear,
759                                const Elem_t theFar);
760
761   //! Compose projection matrix for L/R stereo eyes.
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   //! @param theIOD [in] the Intraocular distance
767   //! @param theZFocus [in] the z coordinate of off-axis projection plane with zero parallax
768   //! @param theEyeIndex [in] choose between L/R eyes
769   template <typename Elem_t>
770   static void stereoEyeProj (NCollection_Mat4<Elem_t>& theOutMx,
771                              const Aspect_FrustumLRBT<Elem_t>& theLRBT,
772                              const Elem_t theNear,
773                              const Elem_t theFar,
774                              const Elem_t theIOD,
775                              const Elem_t theZFocus,
776                              const Aspect_Eye theEyeIndex);
777
778   //! Construct "look at" orientation transformation.
779   //! Reference point differs for perspective and ortho modes 
780   //! (made for compatibility, to be improved..).
781   //! @param theEye [in] the eye coordinates in 3D space.
782   //! @param theFwdDir [in] view direction
783   //! @param theUpDir [in] the up direction vector.
784   //! @param theAxialScale [in] the axial scale vector.
785   //! @param theOutMx [in/out] the orientation matrix.
786   template <typename Elem_t>
787   static void
788     LookOrientation (const NCollection_Vec3<Elem_t>& theEye,
789                      const NCollection_Vec3<Elem_t>& theFwdDir,
790                      const NCollection_Vec3<Elem_t>& theUpDir,
791                      const NCollection_Vec3<Elem_t>& theAxialScale,
792                      NCollection_Mat4<Elem_t>&       theOutMx);
793
794 public:
795
796   //! Enumerates vertices of view volume.
797   enum
798   {
799     FrustumVert_LeftBottomNear,
800     FrustumVert_LeftBottomFar,
801     FrustumVert_LeftTopNear,
802     FrustumVert_LeftTopFar,
803     FrustumVert_RightBottomNear,
804     FrustumVert_RightBottomFar,
805     FrustumVert_RightTopNear,
806     FrustumVert_RightTopFar,
807     FrustumVerticesNB
808   };
809
810   //! Fill array of current view frustum corners.
811   //! The size of this array is equal to FrustumVerticesNB.
812   //! The order of vertices is as defined in FrustumVert_* enumeration.
813   Standard_EXPORT void FrustumPoints (NCollection_Array1<Graphic3d_Vec3d>& thePoints,
814                                       const Graphic3d_Mat4d& theModelWorld = Graphic3d_Mat4d()) const;
815
816 private:
817
818   gp_Dir        myUp;       //!< Camera up direction vector
819   gp_Dir        myDirection;//!< Camera view direction (from eye)
820   gp_Pnt        myEye;      //!< Camera eye position
821   Standard_Real myDistance; //!< distance from Eye to Center
822
823   gp_XYZ myAxialScale; //!< World axial scale.
824
825   Projection    myProjType; //!< Projection type used for rendering.
826   Standard_Real myFOVy;     //!< Field Of View in y axis.
827   Standard_Real myFOVx;     //!< Field Of View in x axis.
828   Standard_Real myFOV2d;    //!< Field Of View limit for 2d on-screen elements
829   Standard_Real myFOVyTan;  //!< Field Of View as Tan(DTR_HALF * myFOVy)
830   Standard_Real myZNear;    //!< Distance to near clipping plane.
831   Standard_Real myZFar;     //!< Distance to far clipping plane.
832   Standard_Real myAspect;   //!< Width to height display ratio.
833
834   Standard_Real myScale;      //!< Specifies parallel scale for orthographic projection.
835   Standard_Real myZFocus;     //!< Stereographic focus value.
836   FocusType     myZFocusType; //!< Stereographic focus definition type.
837
838   Standard_Real myIOD;     //!< Intraocular distance value.
839   IODType       myIODType; //!< Intraocular distance definition type.
840
841   Graphic3d_CameraTile myTile;//!< Tile defining sub-area for drawing
842
843   Graphic3d_Mat4d  myCustomProjMatM;
844   Graphic3d_Mat4d  myCustomProjMatL;
845   Graphic3d_Mat4d  myCustomProjMatR;
846   Graphic3d_Mat4d  myCustomHeadToEyeMatL;
847   Graphic3d_Mat4d  myCustomHeadToEyeMatR;
848   Aspect_FrustumLRBT<Standard_Real> myCustomFrustumL; //!< left  custom frustum
849   Aspect_FrustumLRBT<Standard_Real> myCustomFrustumR; //!< right custom frustum
850   Standard_Boolean myIsCustomProjMatM;  //!< flag indicating usage of custom projection matrix
851   Standard_Boolean myIsCustomProjMatLR; //!< flag indicating usage of custom stereo projection matrices
852   Standard_Boolean myIsCustomFrustomLR; //!< flag indicating usage of custom stereo frustums
853
854   mutable TransformMatrices<Standard_Real>      myMatricesD;
855   mutable TransformMatrices<Standard_ShortReal> myMatricesF;
856
857   mutable Graphic3d_WorldViewProjState myWorldViewProjState;
858
859 public:
860
861   DEFINE_STANDARD_RTTIEXT(Graphic3d_Camera,Standard_Transient)
862 };
863
864 DEFINE_STANDARD_HANDLE (Graphic3d_Camera, Standard_Transient)
865
866 //! Linear interpolation tool for camera orientation and position.
867 //! This tool interpolates camera parameters scale, eye, center, rotation (up and direction vectors) independently.
868 //! @sa Graphic3d_Camera::Interpolate()
869 template<>
870 inline void NCollection_Lerp<Handle(Graphic3d_Camera)>::Interpolate (const double theT,
871                                                                      Handle(Graphic3d_Camera)& theResult) const
872 {
873   Graphic3d_Camera::Interpolate (myStart, myEnd, theT, theResult);
874 }
875
876 //! Linear interpolation tool for camera orientation and position.
877 //! This tool interpolates camera parameters scale, eye, center, rotation (up and direction vectors) independently.
878 //! @sa Graphic3d_Camera::Interpolate()
879 typedef NCollection_Lerp<Handle(Graphic3d_Camera)> Graphic3d_CameraLerp;
880
881 #endif