1 // Created on: 2013-05-29
2 // Created by: Anton POLETAEV
3 // Copyright (c) 1999-2014 OPEN CASCADE SAS
5 // This file is part of Open CASCADE Technology software library.
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.
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
16 #ifndef _Graphic3d_Camera_HeaderFile
17 #define _Graphic3d_Camera_HeaderFile
19 #include <Graphic3d_Mat4d.hxx>
20 #include <Graphic3d_Mat4.hxx>
21 #include <Graphic3d_Vec3.hxx>
23 #include <NCollection_Handle.hxx>
28 #include <Standard_Macro.hxx>
29 #include <Standard_TypeDef.hxx>
31 #include <Bnd_Box.hxx>
33 //! Forward declaration
34 class Handle(Graphic3d_Camera);
36 //! Camera class provides object-oriented approach to setting up projection
37 //! and orientation properties of 3D view.
38 class Graphic3d_Camera : public Standard_Transient
42 //! Template container for cached matrices or Real/ShortReal types.
43 template<typename Elem_t>
44 struct TransformMatrices
46 void InitOrientation()
48 Orientation = new NCollection_Mat4<Elem_t>();
53 MProjection = new NCollection_Mat4<Elem_t>();
54 LProjection = new NCollection_Mat4<Elem_t>();
55 RProjection = new NCollection_Mat4<Elem_t>();
58 void ResetOrientation()
60 Orientation.Nullify();
63 void ResetProjection()
65 MProjection.Nullify();
66 LProjection.Nullify();
67 RProjection.Nullify();
70 Standard_Boolean IsOrientationValid()
72 return !Orientation.IsNull();
75 Standard_Boolean IsProjectionValid()
77 return !MProjection.IsNull() &&
78 !LProjection.IsNull() &&
79 !RProjection.IsNull();
82 NCollection_Handle< NCollection_Mat4<Elem_t> > Orientation;
83 NCollection_Handle< NCollection_Mat4<Elem_t> > MProjection;
84 NCollection_Handle< NCollection_Mat4<Elem_t> > LProjection;
85 NCollection_Handle< NCollection_Mat4<Elem_t> > RProjection;
90 //! Enumerates supported monographic projections.
91 //! - Projection_Orthographic : orthographic projection.
92 //! - Projection_Perspective : perspective projection.
93 //! - Projection_Stereo : stereographic projection.
94 //! - Projection_MonoLeftEye : mono projection for stereo left eye.
95 //! - Projection_MonoRightEye : mono projection for stereo right eye.
98 Projection_Orthographic,
99 Projection_Perspective,
101 Projection_MonoLeftEye,
102 Projection_MonoRightEye
105 //! Enumerates approaches to define stereographic focus.
106 //! - FocusType_Absolute : focus is specified as absolute value.
107 //! - FocusType_Relative : focus is specified relative to
108 //! (as coefficient of) camera focal length.
115 //! Enumerates approaches to define Intraocular distance.
116 //! - IODType_Absolute : Intraocular distance is defined as absolute value.
117 //! - IODType_Relative : Intraocular distance is defined relative to
118 //! (as coefficient of) camera focal length.
127 //! Default constructor.
128 //! Initializes camera with the following properties:
129 //! Eye (0, 0, -2); Center (0, 0, 0); Up (0, 1, 0);
130 //! Type (Orthographic); FOVy (45); Scale (1000); IsStereo(false);
131 //! ZNear (0.001); ZFar (3000.0); Aspect(1);
132 //! ZFocus(1.0); ZFocusType(Relative); IOD(0.05); IODType(Relative)
133 Standard_EXPORT Graphic3d_Camera();
135 //! Copy constructor.
136 //! @param theOther [in] the camera to copy from.
137 Standard_EXPORT Graphic3d_Camera (const Handle(Graphic3d_Camera)& theOther);
139 //! Initialize mapping related parameters from other camera handle.
140 Standard_EXPORT void CopyMappingData (const Handle(Graphic3d_Camera)& theOtherCamera);
142 //! Initialize orientation related parameters from other camera handle.
143 Standard_EXPORT void CopyOrientationData (const Handle(Graphic3d_Camera)& theOtherCamera);
145 //! Copy properties of another camera.
146 //! @param theOther [in] the camera to copy from.
147 Standard_EXPORT void Copy (const Handle(Graphic3d_Camera)& theOther);
149 //! @name Public camera properties
152 //! Sets camera Eye position.
153 //! @param theEye [in] the location of camera's Eye.
154 Standard_EXPORT void SetEye (const gp_Pnt& theEye);
156 //! Get camera Eye position.
157 //! @return camera eye location.
158 const gp_Pnt& Eye() const
163 //! Sets Center of the camera.
164 //! @param theCenter [in] the point where the camera looks at.
165 Standard_EXPORT void SetCenter (const gp_Pnt& theCenter);
167 //! Get Center of the camera.
168 //! @return the point where the camera looks at.
169 const gp_Pnt& Center() const
174 //! Sets camera Up direction vector, orthogonal to camera direction.
175 //! @param theUp [in] the Up direction vector.
176 Standard_EXPORT void SetUp (const gp_Dir& theUp);
178 //! Orthogonalize up direction vector.
179 Standard_EXPORT void OrthogonalizeUp();
181 //! Return a copy of orthogonalized up direction vector.
182 Standard_EXPORT gp_Dir OrthogonalizedUp() const;
184 //! Get camera Up direction vector.
185 //! @return Camera's Up direction vector.
186 const gp_Dir& Up() const
191 //! Set camera axial scale.
192 //! @param theAxialScale [in] the axial scale vector.
193 Standard_EXPORT void SetAxialScale (const gp_XYZ& theAxialScale);
195 //! Get camera axial scale.
196 //! @return Camera's axial scale.
197 const gp_XYZ& AxialScale() const
202 //! Set distance of Eye from camera Center.
203 //! @param theDistance [in] the distance.
204 Standard_EXPORT void SetDistance (const Standard_Real theDistance);
206 //! Get distance of Eye from camera Center.
207 //! @return the distance.
208 Standard_EXPORT Standard_Real Distance() const;
210 //! Sets camera look direction.
211 //! @param theDir [in] the direction.
212 Standard_EXPORT void SetDirection (const gp_Dir& theDir);
214 //! Get camera look direction.
215 //! @return camera look direction.
216 Standard_EXPORT gp_Dir Direction() const;
218 //! Sets camera scale. For orthographic projection the scale factor
219 //! corresponds to parallel scale of view mapping (i.e. size
220 //! of viewport). For perspective camera scale is converted to
221 //! distance. The scale specifies equal size of the view projection in
222 //! both dimensions assuming that the aspect is 1.0. The projection height
223 //! and width are specified with the scale and correspondingly multiplied
225 //! @param theScale [in] the scale factor.
226 Standard_EXPORT void SetScale (const Standard_Real theScale);
228 //! Get camera scale.
229 //! @return camera scale factor.
230 Standard_EXPORT Standard_Real Scale() const;
232 //! Change camera projection type.
233 //! When switching to perspective projection from orthographic one,
234 //! the ZNear and ZFar are reset to default values (0.001, 3000.0)
235 //! if less than 0.0.
236 //! @param theProjectionType [in] the camera projection type.
237 Standard_EXPORT void SetProjectionType (const Projection theProjection);
239 //! @return camera projection type.
240 Projection ProjectionType() const
245 //! Check that the camera projection is orthographic.
246 //! @return boolean flag that indicates whether the camera's projection is
247 //! orthographic or not.
248 Standard_Boolean IsOrthographic() const
250 return (myProjType == Projection_Orthographic);
253 //! Check whether the camera projection is stereo.
254 //! Please note that stereo rendering is now implemented with support of
256 //! @return boolean flag indicating whether the stereographic L/R projection
258 Standard_Boolean IsStereo() const
260 return (myProjType == Projection_Stereo);
263 //! Set Field Of View (FOV) in y axis for perspective projection.
264 //! @param theFOVy [in] the FOV in degrees.
265 Standard_EXPORT void SetFOVy (const Standard_Real theFOVy);
267 //! Get Field Of View (FOV) in y axis.
268 //! @return the FOV value in degrees.
269 Standard_Real FOVy() const
274 //! Change Z-min and Z-max planes of projection volume to match the
275 //! displayed objects. The methods ensures that view volume will
276 //! be close by depth range to the displayed objects. Fitting assumes that
277 //! for orthogonal projection the view volume contains the displayed objects
278 //! completely. For zoomed perspective view, the view volume is adjusted such
279 //! that it contains the objects or their parts, located in front of the camera.
280 //! @param theScaleFactor [in] the scale factor for Z-range.
281 //! The range between Z-min, Z-max projection volume planes
282 //! evaluated by z fitting method will be scaled using this coefficient.
283 //! Program error exception is thrown if negative or zero value is passed.
284 //! @param theMinMax [in] applicative min max boundaries.
285 //! @param theScaleFactor [in] real graphical boundaries (not accounting infinite flag).
287 Standard_EXPORT void ZFitAll (const Standard_Real theScaleFactor, const Bnd_Box& theMinMax, const Bnd_Box& theGraphicBB);
289 //! Change the Near and Far Z-clipping plane positions.
290 //! For orthographic projection, theZNear, theZFar can be negative or positive.
291 //! For perspective projection, only positive values are allowed.
292 //! Program error exception is raised if non-positive values are
293 //! specified for perspective projection or theZNear >= theZFar.
294 //! @param theZNear [in] the distance of the plane from the Eye.
295 //! @param theZFar [in] the distance of the plane from the Eye.
296 Standard_EXPORT void SetZRange (const Standard_Real theZNear, const Standard_Real theZFar);
298 //! Get the Near Z-clipping plane position.
299 //! @return the distance of the plane from the Eye.
300 Standard_Real ZNear() const
305 //! Get the Far Z-clipping plane position.
306 //! @return the distance of the plane from the Eye.
307 Standard_Real ZFar() const
312 //! Changes width / height display ratio.
313 //! @param theAspect [in] the display ratio.
314 Standard_EXPORT void SetAspect (const Standard_Real theAspect);
316 //! Get camera display ratio.
317 //! @return display ratio.
318 Standard_Real Aspect() const
323 //! Sets stereographic focus distance.
324 //! @param theType [in] the focus definition type. Focus can be defined
325 //! as absolute value or relatively to (as coefficient of) coefficient of
326 //! camera focal length.
327 //! @param theZFocus [in] the focus absolute value or coefficient depending
328 //! on the passed definition type.
329 Standard_EXPORT void SetZFocus (const FocusType theType, const Standard_Real theZFocus);
331 //! Get stereographic focus value.
332 //! @return absolute or relative stereographic focus value
333 //! depending on its definition type.
334 Standard_Real ZFocus() const
339 //! Get stereographic focus definition type.
340 //! @return definition type used for stereographic focus.
341 FocusType ZFocusType() const
346 //! Sets Intraocular distance.
347 //! @param theType [in] the IOD definition type. IOD can be defined as
348 //! absolute value or relatively to (as coefficient of) camera focal length.
349 //! @param theIOD [in] the Intraocular distance.
350 Standard_EXPORT void SetIOD (const IODType theType, const Standard_Real theIOD);
352 //! Get Intraocular distance value.
353 //! @return absolute or relative IOD value depending on its definition type.
354 Standard_Real IOD() const
359 //! Get Intraocular distance definition type.
360 //! @return definition type used for Intraocular distance.
361 IODType GetIODType() const
366 //! @name Basic camera operations
369 //! Transform orientation components of the camera:
370 //! Eye, Up and Center points.
371 //! @param theTrsf [in] the transformation to apply.
372 Standard_EXPORT void Transform (const gp_Trsf& theTrsf);
374 //! Calculate view plane size at center (target) point
375 //! and distance between ZFar and ZNear planes.
376 //! @return values in form of gp_Pnt (Width, Height, Depth).
377 Standard_EXPORT gp_XYZ ViewDimensions() const;
379 //! Calculate WCS frustum planes for the camera projection volume.
380 //! Frustum is a convex volume determined by six planes directing
382 //! The frustum planes are usually used as inputs for camera algorithms.
383 //! Thus, if any changes to projection matrix calculation are necessary,
384 //! the frustum planes calculation should be also touched.
385 //! @param theLeft [out] the frustum plane for left side of view.
386 //! @param theRight [out] the frustum plane for right side of view.
387 //! @param theBottom [out] the frustum plane for bottom side of view.
388 //! @param theTop [out] the frustum plane for top side of view.
389 //! @param theNear [out] the frustum plane for near side of view.
390 //! @param theFar [out] the frustum plane for far side of view.
391 Standard_EXPORT void Frustum (gp_Pln& theLeft,
396 gp_Pln& theFar) const;
398 //! @name Projection methods
401 //! Project point from world coordinate space to
402 //! normalized device coordinates (mapping).
403 //! @param thePnt [in] the 3D point in WCS.
404 //! @return mapped point in NDC.
405 Standard_EXPORT gp_Pnt Project (const gp_Pnt& thePnt) const;
407 //! Unproject point from normalized device coordinates
408 //! to world coordinate space.
409 //! @param thePnt [in] the NDC point.
410 //! @return 3D point in WCS.
411 Standard_EXPORT gp_Pnt UnProject (const gp_Pnt& thePnt) const;
413 //! Convert point from view coordinate space to
414 //! projection coordinate space.
415 //! @param thePnt [in] the point in VCS.
416 //! @return point in NDC.
417 Standard_EXPORT gp_Pnt ConvertView2Proj (const gp_Pnt& thePnt) const;
419 //! Convert point from projection coordinate space
420 //! to view coordinate space.
421 //! @param thePnt [in] the point in NDC.
422 //! @return point in VCS.
423 Standard_EXPORT gp_Pnt ConvertProj2View (const gp_Pnt& thePnt) const;
425 //! Convert point from world coordinate space to
426 //! view coordinate space.
427 //! @param thePnt [in] the 3D point in WCS.
428 //! @return point in VCS.
429 Standard_EXPORT gp_Pnt ConvertWorld2View (const gp_Pnt& thePnt) const;
431 //! Convert point from view coordinate space to
432 //! world coordinates.
433 //! @param thePnt [in] the 3D point in VCS.
434 //! @return point in WCS.
435 Standard_EXPORT gp_Pnt ConvertView2World (const gp_Pnt& thePnt) const;
437 //! @name Camera modification state
440 //! Returns modification state of camera projection matrix
441 Standard_Size ProjectionState() const
443 return myProjectionState;
446 //! Returns modification state of camera model-view matrix
447 Standard_Size ModelViewState() const
449 return myOrientationState;
452 //! @name Lazily-computed orientation and projection matrices derived from camera parameters
455 //! Get orientation matrix.
456 //! @return camera orientation matrix.
457 Standard_EXPORT const Graphic3d_Mat4d& OrientationMatrix() const;
459 //! Get orientation matrix of Standard_ShortReal precision.
460 //! @return camera orientation matrix.
461 Standard_EXPORT const Graphic3d_Mat4& OrientationMatrixF() const;
463 //! Get monographic or middle point projection matrix used for monographic
464 //! rendering and for point projection / unprojection.
465 //! @return monographic projection matrix.
466 Standard_EXPORT const Graphic3d_Mat4d& ProjectionMatrix() const;
468 //! Get monographic or middle point projection matrix of Standard_ShortReal precision used for monographic
469 //! rendering and for point projection / unprojection.
470 //! @return monographic projection matrix.
471 Standard_EXPORT const Graphic3d_Mat4& ProjectionMatrixF() const;
473 //! @return stereographic matrix computed for left eye. Please note
474 //! that this method is used for rendering for <i>Projection_Stereo</i>.
475 Standard_EXPORT const Graphic3d_Mat4d& ProjectionStereoLeft() const;
477 //! @return stereographic matrix of Standard_ShortReal precision computed for left eye.
478 //! Please note that this method is used for rendering for <i>Projection_Stereo</i>.
479 Standard_EXPORT const Graphic3d_Mat4& ProjectionStereoLeftF() const;
481 //! @return stereographic matrix computed for right eye. Please note
482 //! that this method is used for rendering for <i>Projection_Stereo</i>.
483 Standard_EXPORT const Graphic3d_Mat4d& ProjectionStereoRight() const;
485 //! @return stereographic matrix of Standard_ShortReal precision computed for right eye.
486 //! Please note that this method is used for rendering for <i>Projection_Stereo</i>.
487 Standard_EXPORT const Graphic3d_Mat4& ProjectionStereoRightF() const;
489 //! Invalidate state of projection matrix.
490 //! The matrix will be updated on request.
491 Standard_EXPORT void InvalidateProjection();
493 //! Invalidate orientation matrix.
494 //! The matrix will be updated on request.
495 Standard_EXPORT void InvalidateOrientation();
497 //! @name Managing projection and orientation cache
500 //! Compute projection matrices.
501 //! @param theMatrices [in] the matrices data container.
502 template <typename Elem_t>
504 TransformMatrices<Elem_t>& UpdateProjection (TransformMatrices<Elem_t>& theMatrices) const;
506 //! Compute orientation matrix.
507 //! @param theMatrices [in] the matrices data container.
508 template <typename Elem_t>
510 TransformMatrices<Elem_t>& UpdateOrientation (TransformMatrices<Elem_t>& theMatrices) const;
514 //! Compose orthographic projection matrix for
515 //! the passed camera volume mapping.
516 //! @param theLeft [in] the left mapping (clipping) coordinate.
517 //! @param theRight [in] the right mapping (clipping) coordinate.
518 //! @param theBottom [in] the bottom mapping (clipping) coordinate.
519 //! @param theTop [in] the top mapping (clipping) coordinate.
520 //! @param theNear [in] the near mapping (clipping) coordinate.
521 //! @param theFar [in] the far mapping (clipping) coordinate.
522 //! @param theOutMx [out] the projection matrix.
523 template <typename Elem_t>
525 OrthoProj (const Elem_t theLeft,
526 const Elem_t theRight,
527 const Elem_t theBottom,
529 const Elem_t theNear,
531 NCollection_Mat4<Elem_t>& theOutMx);
533 //! Compose perspective projection matrix for
534 //! the passed camera volume mapping.
535 //! @param theLeft [in] the left mapping (clipping) coordinate.
536 //! @param theRight [in] the right mapping (clipping) coordinate.
537 //! @param theBottom [in] the bottom mapping (clipping) coordinate.
538 //! @param theTop [in] the top mapping (clipping) coordinate.
539 //! @param theNear [in] the near mapping (clipping) coordinate.
540 //! @param theFar [in] the far mapping (clipping) coordinate.
541 //! @param theOutMx [out] the projection matrix.
542 template <typename Elem_t>
544 PerspectiveProj (const Elem_t theLeft,
545 const Elem_t theRight,
546 const Elem_t theBottom,
548 const Elem_t theNear,
550 NCollection_Mat4<Elem_t>& theOutMx);
552 //! Compose projection matrix for L/R stereo eyes.
553 //! @param theLeft [in] the left mapping (clipping) coordinate.
554 //! @param theRight [in] the right mapping (clipping) coordinate.
555 //! @param theBottom [in] the bottom mapping (clipping) coordinate.
556 //! @param theTop [in] the top mapping (clipping) coordinate.
557 //! @param theNear [in] the near mapping (clipping) coordinate.
558 //! @param theFar [in] the far mapping (clipping) coordinate.
559 //! @param theIOD [in] the Intraocular distance.
560 //! @param theZFocus [in] the z coordinate of off-axis
561 //! projection plane with zero parallax.
562 //! @param theIsLeft [in] boolean flag to choose between L/R eyes.
563 //! @param theOutMx [out] the projection matrix.
564 template <typename Elem_t>
566 StereoEyeProj (const Elem_t theLeft,
567 const Elem_t theRight,
568 const Elem_t theBottom,
570 const Elem_t theNear,
573 const Elem_t theZFocus,
574 const Standard_Boolean theIsLeft,
575 NCollection_Mat4<Elem_t>& theOutMx);
577 //! Construct "look at" orientation transformation.
578 //! Reference point differs for perspective and ortho modes
579 //! (made for compatibility, to be improved..).
580 //! @param theEye [in] the eye coordinates in 3D space.
581 //! @param theLookAt [in] the point the camera looks at.
582 //! @param theUpDir [in] the up direction vector.
583 //! @param theAxialScale [in] the axial scale vector.
584 //! @param theOutMx [in/out] the orientation matrix.
585 template <typename Elem_t>
587 LookOrientation (const NCollection_Vec3<Elem_t>& theEye,
588 const NCollection_Vec3<Elem_t>& theLookAt,
589 const NCollection_Vec3<Elem_t>& theUpDir,
590 const NCollection_Vec3<Elem_t>& theAxialScale,
591 NCollection_Mat4<Elem_t>& theOutMx);
595 gp_Dir myUp; //!< Camera up direction vector.
596 gp_Pnt myEye; //!< Camera eye position.
597 gp_Pnt myCenter; //!< Camera center.
599 gp_XYZ myAxialScale; //!< World axial scale.
601 Projection myProjType; //!< Projection type used for rendering.
602 Standard_Real myFOVy; //!< Field Of View in y axis.
603 Standard_Real myZNear; //!< Distance to near clipping plane.
604 Standard_Real myZFar; //!< Distance to far clipping plane.
605 Standard_Real myAspect; //!< Width to height display ratio.
607 Standard_Real myScale; //!< Specifies parallel scale for orthographic projection.
608 Standard_Real myZFocus; //!< Stereographic focus value.
609 FocusType myZFocusType; //!< Stereographic focus definition type.
611 Standard_Real myIOD; //!< Intraocular distance value.
612 IODType myIODType; //!< Intraocular distance definition type.
614 mutable TransformMatrices<Standard_Real> myMatricesD;
615 mutable TransformMatrices<Standard_ShortReal> myMatricesF;
617 mutable Standard_Size myProjectionState;
618 mutable Standard_Size myOrientationState;
622 DEFINE_STANDARD_RTTI(Graphic3d_Camera, Standard_Transient);
626 DEFINE_STANDARD_HANDLE (Graphic3d_Camera, Standard_Transient)