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 <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>
32 #include <Standard_Macro.hxx>
33 #include <Standard_TypeDef.hxx>
35 #include <Bnd_Box.hxx>
37 //! Forward declaration
38 class Graphic3d_WorldViewProjState;
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
46 //! Template container for cached matrices or Real/ShortReal types.
47 template<typename Elem_t>
48 struct TransformMatrices
51 //! Default constructor.
52 TransformMatrices() : myIsOrientationValid (Standard_False), myIsProjectionValid (Standard_False) {}
54 //! Initialize orientation.
55 void InitOrientation()
57 myIsOrientationValid = Standard_True;
58 Orientation.InitIdentity();
61 //! Initialize projection.
64 myIsProjectionValid = Standard_True;
65 MProjection.InitIdentity();
66 LProjection.InitIdentity();
67 RProjection.InitIdentity();
70 //! Invalidate orientation.
71 void ResetOrientation() { myIsOrientationValid = Standard_False; }
73 //! Invalidate projection.
74 void ResetProjection() { myIsProjectionValid = Standard_False; }
76 //! Return true if Orientation was not invalidated.
77 Standard_Boolean IsOrientationValid() const { return myIsOrientationValid; }
79 //! Return true if Projection was not invalidated.
80 Standard_Boolean IsProjectionValid() const { return myIsProjectionValid; }
82 //! Dumps the content of me into the stream
83 void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const
85 if (IsOrientationValid())
87 OCCT_DUMP_FIELD_VALUES_DUMPED (theOStream, theDepth, &Orientation)
89 if (IsProjectionValid())
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)
95 OCCT_DUMP_FIELD_VALUE_NUMERICAL (theOStream, myIsOrientationValid)
96 OCCT_DUMP_FIELD_VALUE_NUMERICAL (theOStream, myIsProjectionValid)
101 NCollection_Mat4<Elem_t> Orientation;
102 NCollection_Mat4<Elem_t> MProjection;
103 NCollection_Mat4<Elem_t> LProjection;
104 NCollection_Mat4<Elem_t> RProjection;
108 Standard_Boolean myIsOrientationValid;
109 Standard_Boolean myIsProjectionValid;
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.
123 Projection_Orthographic,
124 Projection_Perspective,
126 Projection_MonoLeftEye,
127 Projection_MonoRightEye
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.
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.
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
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).
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.
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.
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,
177 Handle(Graphic3d_Camera)& theCamera);
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();
189 //! Copy constructor.
190 //! @param theOther [in] the camera to copy from.
191 Standard_EXPORT Graphic3d_Camera (const Handle(Graphic3d_Camera)& theOther);
193 //! Initialize mapping related parameters from other camera handle.
194 Standard_EXPORT void CopyMappingData (const Handle(Graphic3d_Camera)& theOtherCamera);
196 //! Initialize orientation related parameters from other camera handle.
197 Standard_EXPORT void CopyOrientationData (const Handle(Graphic3d_Camera)& theOtherCamera);
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);
203 //! @name Public camera properties
206 //! Get camera look direction.
207 //! @return camera look direction.
208 const gp_Dir& Direction() const { return myDirection; }
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);
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);
220 //! Get camera Up direction vector.
221 //! @return Camera's Up direction vector.
222 const gp_Dir& Up() const { return myUp; }
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);
230 //! Orthogonalize up direction vector.
231 Standard_EXPORT void OrthogonalizeUp();
233 //! Return a copy of orthogonalized up direction vector.
234 Standard_EXPORT gp_Dir OrthogonalizedUp() const;
236 //! Right side direction.
237 gp_Dir SideRight() const
239 return -(gp_Vec (Direction()) ^ gp_Vec (OrthogonalizedUp()));
242 //! Get camera Eye position.
243 //! @return camera eye location.
244 const gp_Pnt& Eye() const { return myEye; }
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.
250 Standard_EXPORT void MoveEyeTo (const gp_Pnt& theEye);
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);
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);
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
270 return myEye.XYZ() + myDirection.XYZ() * myDistance;
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);
279 //! Get distance of Eye from camera Center.
280 //! @return the distance.
281 Standard_Real Distance() const { return myDistance; }
283 //! Set distance of Eye from camera Center.
284 //! @param theDistance [in] the distance.
285 Standard_EXPORT void SetDistance (const Standard_Real theDistance);
287 //! Get camera scale.
288 //! @return camera scale factor.
289 Standard_EXPORT Standard_Real Scale() const;
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
298 //! @param theScale [in] the scale factor.
299 Standard_EXPORT void SetScale (const Standard_Real theScale);
301 //! Get camera axial scale.
302 //! @return Camera's axial scale.
303 const gp_XYZ& AxialScale() const { return myAxialScale; }
305 //! Set camera axial scale.
306 //! @param theAxialScale [in] the axial scale vector.
307 Standard_EXPORT void SetAxialScale (const gp_XYZ& theAxialScale);
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);
316 //! @return camera projection type.
317 Projection ProjectionType() const
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
327 return (myProjType == Projection_Orthographic);
330 //! Check whether the camera projection is stereo.
331 //! Please note that stereo rendering is now implemented with support of
333 //! @return boolean flag indicating whether the stereographic L/R projection
335 Standard_Boolean IsStereo() const
337 return (myProjType == Projection_Stereo);
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);
345 //! Get Field Of View (FOV) in y axis.
346 //! @return the FOV value in degrees.
347 Standard_Real FOVy() const { return myFOVy; }
349 //! Get Field Of View (FOV) in x axis.
350 //! @return the FOV value in degrees.
351 Standard_Real FOVx() const { return myFOVx; }
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; }
359 //! Set Field Of View (FOV) restriction for 2D on-screen elements.
360 Standard_EXPORT void SetFOV2d (Standard_Real theFOV);
362 //! Adjust camera to fit in specified AABB.
363 Standard_EXPORT bool FitMinMax (const Bnd_Box& theBox,
364 const Standard_Real theResolution,
365 const bool theToEnlargeIfLine);
367 //! Estimate Z-min and Z-max planes of projection volume to match the
368 //! displayed objects. The methods ensures that view volume will
369 //! be close by depth range to the displayed objects. Fitting assumes that
370 //! for orthogonal projection the view volume contains the displayed objects
371 //! completely. For zoomed perspective view, the view volume is adjusted such
372 //! that it contains the objects or their parts, located in front of the camera.
373 //! @param theScaleFactor [in] the scale factor for Z-range.
374 //! The range between Z-min, Z-max projection volume planes
375 //! evaluated by z fitting method will be scaled using this coefficient.
376 //! Program error exception is thrown if negative or zero value is passed.
377 //! @param theMinMax [in] applicative min max boundaries.
378 //! @param theScaleFactor [in] real graphical boundaries (not accounting infinite flag).
379 Standard_EXPORT bool ZFitAll (const Standard_Real theScaleFactor,
380 const Bnd_Box& theMinMax,
381 const Bnd_Box& theGraphicBB,
382 Standard_Real& theZNear,
383 Standard_Real& theZFar) const;
385 //! Change Z-min and Z-max planes of projection volume to match the displayed objects.
386 void ZFitAll (const Standard_Real theScaleFactor, const Bnd_Box& theMinMax, const Bnd_Box& theGraphicBB)
388 Standard_Real aZNear = 0.0, aZFar = 1.0;
389 ZFitAll (theScaleFactor, theMinMax, theGraphicBB, aZNear, aZFar);
390 SetZRange (aZNear, aZFar);
393 //! Change the Near and Far Z-clipping plane positions.
394 //! For orthographic projection, theZNear, theZFar can be negative or positive.
395 //! For perspective projection, only positive values are allowed.
396 //! Program error exception is raised if non-positive values are
397 //! specified for perspective projection or theZNear >= theZFar.
398 //! @param theZNear [in] the distance of the plane from the Eye.
399 //! @param theZFar [in] the distance of the plane from the Eye.
400 Standard_EXPORT void SetZRange (const Standard_Real theZNear, const Standard_Real theZFar);
402 //! Get the Near Z-clipping plane position.
403 //! @return the distance of the plane from the Eye.
404 Standard_Real ZNear() const
409 //! Get the Far Z-clipping plane position.
410 //! @return the distance of the plane from the Eye.
411 Standard_Real ZFar() const
416 //! Return TRUE if camera should calculate projection matrix for [0, 1] depth range or for [-1, 1] range.
417 //! FALSE by default.
418 Standard_Boolean IsZeroToOneDepth() const { return myIsZeroToOneDepth; }
420 //! Set using [0, 1] depth range or [-1, 1] range.
421 void SetZeroToOneDepth (Standard_Boolean theIsZeroToOne)
423 if (myIsZeroToOneDepth != theIsZeroToOne)
425 myIsZeroToOneDepth = theIsZeroToOne;
426 InvalidateProjection();
430 //! Changes width / height display ratio.
431 //! @param theAspect [in] the display ratio.
432 Standard_EXPORT void SetAspect (const Standard_Real theAspect);
434 //! Get camera display ratio.
435 //! @return display ratio.
436 Standard_Real Aspect() const
441 //! Sets stereographic focus distance.
442 //! @param theType [in] the focus definition type. Focus can be defined
443 //! as absolute value or relatively to (as coefficient of) coefficient of
444 //! camera focal length.
445 //! @param theZFocus [in] the focus absolute value or coefficient depending
446 //! on the passed definition type.
447 Standard_EXPORT void SetZFocus (const FocusType theType, const Standard_Real theZFocus);
449 //! Get stereographic focus value.
450 //! @return absolute or relative stereographic focus value
451 //! depending on its definition type.
452 Standard_Real ZFocus() const
457 //! Get stereographic focus definition type.
458 //! @return definition type used for stereographic focus.
459 FocusType ZFocusType() const
464 //! Sets Intraocular distance.
465 //! @param theType [in] the IOD definition type. IOD can be defined as
466 //! absolute value or relatively to (as coefficient of) camera focal length.
467 //! @param theIOD [in] the Intraocular distance.
468 Standard_EXPORT void SetIOD (const IODType theType, const Standard_Real theIOD);
470 //! Get Intraocular distance value.
471 //! @return absolute or relative IOD value depending on its definition type.
472 Standard_Real IOD() const
477 //! Get Intraocular distance definition type.
478 //! @return definition type used for Intraocular distance.
479 IODType GetIODType() const
484 //! Get current tile.
485 const Graphic3d_CameraTile& Tile() const { return myTile; }
487 //! Sets the Tile defining the drawing sub-area within View.
488 //! Note that tile defining a region outside the view boundaries is also valid - use method Graphic3d_CameraTile::Cropped() to assign a cropped copy.
489 //! @param theTile tile definition
490 Standard_EXPORT void SetTile (const Graphic3d_CameraTile& theTile);
492 //! @name Basic camera operations
495 //! Transform orientation components of the camera:
496 //! Eye, Up and Center points.
497 //! @param theTrsf [in] the transformation to apply.
498 Standard_EXPORT void Transform (const gp_Trsf& theTrsf);
500 //! Calculate view plane size at center (target) point
501 //! and distance between ZFar and ZNear planes.
502 //! @return values in form of gp_Pnt (Width, Height, Depth).
503 gp_XYZ ViewDimensions() const
505 return ViewDimensions (Distance());
508 //! Calculate view plane size at center point with specified Z offset
509 //! and distance between ZFar and ZNear planes.
510 //! @param theZValue [in] the distance from the eye in eye-to-center direction
511 //! @return values in form of gp_Pnt (Width, Height, Depth).
512 Standard_EXPORT gp_XYZ ViewDimensions (const Standard_Real theZValue) const;
514 //! Return offset to the view corner in NDC space within dimension X for 2d on-screen elements, which is normally 0.5.
515 //! Can be clamped when FOVx exceeds FOV2d.
516 Standard_Real NDC2dOffsetX() const
518 return myFOV2d >= myFOVx
520 : 0.5 * myFOV2d / myFOVx;
523 //! Return offset to the view corner in NDC space within dimension X for 2d on-screen elements, which is normally 0.5.
524 //! Can be clamped when FOVy exceeds FOV2d.
525 Standard_Real NDC2dOffsetY() const
527 return myFOV2d >= myFOVy
529 : 0.5 * myFOV2d / myFOVy;
532 //! Calculate WCS frustum planes for the camera projection volume.
533 //! Frustum is a convex volume determined by six planes directing
535 //! The frustum planes are usually used as inputs for camera algorithms.
536 //! Thus, if any changes to projection matrix calculation are necessary,
537 //! the frustum planes calculation should be also touched.
538 //! @param theLeft [out] the frustum plane for left side of view.
539 //! @param theRight [out] the frustum plane for right side of view.
540 //! @param theBottom [out] the frustum plane for bottom side of view.
541 //! @param theTop [out] the frustum plane for top side of view.
542 //! @param theNear [out] the frustum plane for near side of view.
543 //! @param theFar [out] the frustum plane for far side of view.
544 Standard_EXPORT void Frustum (gp_Pln& theLeft,
549 gp_Pln& theFar) const;
551 //! @name Projection methods
554 //! Project point from world coordinate space to
555 //! normalized device coordinates (mapping).
556 //! @param thePnt [in] the 3D point in WCS.
557 //! @return mapped point in NDC.
558 Standard_EXPORT gp_Pnt Project (const gp_Pnt& thePnt) const;
560 //! Unproject point from normalized device coordinates
561 //! to world coordinate space.
562 //! @param thePnt [in] the NDC point.
563 //! @return 3D point in WCS.
564 Standard_EXPORT gp_Pnt UnProject (const gp_Pnt& thePnt) const;
566 //! Convert point from view coordinate space to
567 //! projection coordinate space.
568 //! @param thePnt [in] the point in VCS.
569 //! @return point in NDC.
570 Standard_EXPORT gp_Pnt ConvertView2Proj (const gp_Pnt& thePnt) const;
572 //! Convert point from projection coordinate space
573 //! to view coordinate space.
574 //! @param thePnt [in] the point in NDC.
575 //! @return point in VCS.
576 Standard_EXPORT gp_Pnt ConvertProj2View (const gp_Pnt& thePnt) const;
578 //! Convert point from world coordinate space to
579 //! view coordinate space.
580 //! @param thePnt [in] the 3D point in WCS.
581 //! @return point in VCS.
582 Standard_EXPORT gp_Pnt ConvertWorld2View (const gp_Pnt& thePnt) const;
584 //! Convert point from view coordinate space to
585 //! world coordinates.
586 //! @param thePnt [in] the 3D point in VCS.
587 //! @return point in WCS.
588 Standard_EXPORT gp_Pnt ConvertView2World (const gp_Pnt& thePnt) const;
590 //! @name Camera modification state
593 //! @return projection modification state of the camera.
594 const Graphic3d_WorldViewProjState& WorldViewProjState() const
596 return myWorldViewProjState;
600 //! Returns modification state of camera projection matrix
601 Standard_Size ProjectionState() const
603 return myWorldViewProjState.ProjectionState();
606 //! Returns modification state of camera world view transformation matrix.
607 Standard_Size WorldViewState() const
609 return myWorldViewProjState.WorldViewState();
612 //! @name Lazily-computed orientation and projection matrices derived from camera parameters
615 //! Get orientation matrix.
616 //! @return camera orientation matrix.
617 Standard_EXPORT const Graphic3d_Mat4d& OrientationMatrix() const;
619 //! Get orientation matrix of Standard_ShortReal precision.
620 //! @return camera orientation matrix.
621 Standard_EXPORT const Graphic3d_Mat4& OrientationMatrixF() const;
623 //! Get monographic or middle point projection matrix used for monographic
624 //! rendering and for point projection / unprojection.
625 //! @return monographic projection matrix.
626 Standard_EXPORT const Graphic3d_Mat4d& ProjectionMatrix() const;
628 //! Get monographic or middle point projection matrix of Standard_ShortReal precision used for monographic
629 //! rendering and for point projection / unprojection.
630 //! @return monographic projection matrix.
631 Standard_EXPORT const Graphic3d_Mat4& ProjectionMatrixF() const;
633 //! @return stereographic matrix computed for left eye. Please note
634 //! that this method is used for rendering for <i>Projection_Stereo</i>.
635 Standard_EXPORT const Graphic3d_Mat4d& ProjectionStereoLeft() const;
637 //! @return stereographic matrix of Standard_ShortReal precision computed for left eye.
638 //! Please note that this method is used for rendering for <i>Projection_Stereo</i>.
639 Standard_EXPORT const Graphic3d_Mat4& ProjectionStereoLeftF() const;
641 //! @return stereographic matrix computed for right eye. Please note
642 //! that this method is used for rendering for <i>Projection_Stereo</i>.
643 Standard_EXPORT const Graphic3d_Mat4d& ProjectionStereoRight() const;
645 //! @return stereographic matrix of Standard_ShortReal precision computed for right eye.
646 //! Please note that this method is used for rendering for <i>Projection_Stereo</i>.
647 Standard_EXPORT const Graphic3d_Mat4& ProjectionStereoRightF() const;
649 //! Invalidate state of projection matrix.
650 //! The matrix will be updated on request.
651 Standard_EXPORT void InvalidateProjection();
653 //! Invalidate orientation matrix.
654 //! The matrix will be updated on request.
655 Standard_EXPORT void InvalidateOrientation();
659 //! Get stereo projection matrices.
660 //! @param theProjL [out] left eye projection matrix
661 //! @param theHeadToEyeL [out] left head to eye translation matrix
662 //! @param theProjR [out] right eye projection matrix
663 //! @param theHeadToEyeR [out] right head to eye translation matrix
664 Standard_EXPORT void StereoProjection (Graphic3d_Mat4d& theProjL,
665 Graphic3d_Mat4d& theHeadToEyeL,
666 Graphic3d_Mat4d& theProjR,
667 Graphic3d_Mat4d& theHeadToEyeR) const;
669 //! Get stereo projection matrices.
670 //! @param theProjL [out] left eye projection matrix
671 //! @param theHeadToEyeL [out] left head to eye translation matrix
672 //! @param theProjR [out] right eye projection matrix
673 //! @param theHeadToEyeR [out] right head to eye translation matrix
674 Standard_EXPORT void StereoProjectionF (Graphic3d_Mat4& theProjL,
675 Graphic3d_Mat4& theHeadToEyeL,
676 Graphic3d_Mat4& theProjR,
677 Graphic3d_Mat4& theHeadToEyeR) const;
679 //! Unset all custom frustums and projection matrices.
680 Standard_EXPORT void ResetCustomProjection();
682 //! Return TRUE if custom stereo frustums are set.
683 bool IsCustomStereoFrustum() const { return myIsCustomFrustomLR; }
685 //! Set custom stereo frustums.
686 //! These can be retrieved from APIs like OpenVR.
687 Standard_EXPORT void SetCustomStereoFrustums (const Aspect_FrustumLRBT<Standard_Real>& theFrustumL,
688 const Aspect_FrustumLRBT<Standard_Real>& theFrustumR);
690 //! Return TRUE if custom stereo projection matrices are set.
691 bool IsCustomStereoProjection() const { return myIsCustomProjMatLR; }
693 //! Set custom stereo projection matrices.
694 //! @param theProjL [in] left eye projection matrix
695 //! @param theHeadToEyeL [in] left head to eye translation matrix
696 //! @param theProjR [in] right eye projection matrix
697 //! @param theHeadToEyeR [in] right head to eye translation matrix
698 Standard_EXPORT void SetCustomStereoProjection (const Graphic3d_Mat4d& theProjL,
699 const Graphic3d_Mat4d& theHeadToEyeL,
700 const Graphic3d_Mat4d& theProjR,
701 const Graphic3d_Mat4d& theHeadToEyeR);
703 //! Return TRUE if custom projection matrix is set.
704 bool IsCustomMonoProjection() const { return myIsCustomProjMatM; }
706 //! Set custom projection matrix.
707 Standard_EXPORT void SetCustomMonoProjection (const Graphic3d_Mat4d& theProj);
709 //! Dumps the content of me into the stream
710 Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
712 //! @name Managing projection and orientation cache
715 //! Get stereo projection matrices.
716 //! @param theProjL [out] left eye projection matrix
717 //! @param theHeadToEyeL [out] left head to eye translation matrix
718 //! @param theProjR [out] right eye projection matrix
719 //! @param theHeadToEyeR [out] right head to eye translation matrix
720 template <typename Elem_t>
721 Standard_EXPORT void stereoProjection (NCollection_Mat4<Elem_t>& theProjL,
722 NCollection_Mat4<Elem_t>& theHeadToEyeL,
723 NCollection_Mat4<Elem_t>& theProjR,
724 NCollection_Mat4<Elem_t>& theHeadToEyeR) const;
726 //! Compute projection matrices.
727 //! @param theProjM [out] mono projection matrix
728 //! @param theProjL [out] left eye projection matrix
729 //! @param theProjR [out] right eye projection matrix
730 //! @param theToAddHeadToEye [in] flag to pre-multiply head-to-eye translation
731 template <typename Elem_t>
732 Standard_EXPORT void computeProjection (NCollection_Mat4<Elem_t>& theProjM,
733 NCollection_Mat4<Elem_t>& theProjL,
734 NCollection_Mat4<Elem_t>& theProjR,
735 bool theToAddHeadToEye) const;
737 //! Compute projection matrices.
738 //! @param theMatrices [in] the matrices data container.
739 template <typename Elem_t>
740 TransformMatrices<Elem_t>& UpdateProjection (TransformMatrices<Elem_t>& theMatrices) const
742 if (!theMatrices.IsProjectionValid())
744 theMatrices.InitProjection();
745 computeProjection (theMatrices.MProjection, theMatrices.LProjection, theMatrices.RProjection, true);
750 //! Compute orientation matrix.
751 //! @param theMatrices [in] the matrices data container.
752 template <typename Elem_t>
754 TransformMatrices<Elem_t>& UpdateOrientation (TransformMatrices<Elem_t>& theMatrices) const;
758 //! Compose orthographic projection matrix for the passed camera volume mapping.
759 //! @param theOutMx [out] the projection matrix
760 //! @param theLRBT [in] the left/right/bottom/top mapping (clipping) coordinates
761 //! @param theNear [in] the near mapping (clipping) coordinate
762 //! @param theFar [in] the far mapping (clipping) coordinate
763 template <typename Elem_t>
764 void orthoProj (NCollection_Mat4<Elem_t>& theOutMx,
765 const Aspect_FrustumLRBT<Elem_t>& theLRBT,
766 const Elem_t theNear,
767 const Elem_t theFar) const;
769 //! Compose perspective projection matrix for the passed camera volume mapping.
770 //! @param theOutMx [out] the projection matrix
771 //! @param theLRBT [in] the left/right/bottom/top mapping (clipping) coordinates
772 //! @param theNear [in] the near mapping (clipping) coordinate
773 //! @param theFar [in] the far mapping (clipping) coordinate
774 template <typename Elem_t>
775 void perspectiveProj (NCollection_Mat4<Elem_t>& theOutMx,
776 const Aspect_FrustumLRBT<Elem_t>& theLRBT,
777 const Elem_t theNear,
778 const Elem_t theFar) const;
780 //! Compose projection matrix for L/R stereo eyes.
781 //! @param theOutMx [out] the projection matrix
782 //! @param theLRBT [in] the left/right/bottom/top mapping (clipping) coordinates
783 //! @param theNear [in] the near mapping (clipping) coordinate
784 //! @param theFar [in] the far mapping (clipping) coordinate
785 //! @param theIOD [in] the Intraocular distance
786 //! @param theZFocus [in] the z coordinate of off-axis projection plane with zero parallax
787 //! @param theEyeIndex [in] choose between L/R eyes
788 template <typename Elem_t>
789 void stereoEyeProj (NCollection_Mat4<Elem_t>& theOutMx,
790 const Aspect_FrustumLRBT<Elem_t>& theLRBT,
791 const Elem_t theNear,
794 const Elem_t theZFocus,
795 const Aspect_Eye theEyeIndex) const;
797 //! Construct "look at" orientation transformation.
798 //! Reference point differs for perspective and ortho modes
799 //! (made for compatibility, to be improved..).
800 //! @param theEye [in] the eye coordinates in 3D space.
801 //! @param theFwdDir [in] view direction
802 //! @param theUpDir [in] the up direction vector.
803 //! @param theAxialScale [in] the axial scale vector.
804 //! @param theOutMx [in/out] the orientation matrix.
805 template <typename Elem_t>
807 LookOrientation (const NCollection_Vec3<Elem_t>& theEye,
808 const NCollection_Vec3<Elem_t>& theFwdDir,
809 const NCollection_Vec3<Elem_t>& theUpDir,
810 const NCollection_Vec3<Elem_t>& theAxialScale,
811 NCollection_Mat4<Elem_t>& theOutMx);
815 //! Enumerates vertices of view volume.
818 FrustumVert_LeftBottomNear,
819 FrustumVert_LeftBottomFar,
820 FrustumVert_LeftTopNear,
821 FrustumVert_LeftTopFar,
822 FrustumVert_RightBottomNear,
823 FrustumVert_RightBottomFar,
824 FrustumVert_RightTopNear,
825 FrustumVert_RightTopFar,
829 //! Fill array of current view frustum corners.
830 //! The size of this array is equal to FrustumVerticesNB.
831 //! The order of vertices is as defined in FrustumVert_* enumeration.
832 Standard_EXPORT void FrustumPoints (NCollection_Array1<Graphic3d_Vec3d>& thePoints,
833 const Graphic3d_Mat4d& theModelWorld = Graphic3d_Mat4d()) const;
837 gp_Dir myUp; //!< Camera up direction vector
838 gp_Dir myDirection;//!< Camera view direction (from eye)
839 gp_Pnt myEye; //!< Camera eye position
840 Standard_Real myDistance; //!< distance from Eye to Center
842 gp_XYZ myAxialScale; //!< World axial scale.
844 Projection myProjType; //!< Projection type used for rendering.
845 Standard_Real myFOVy; //!< Field Of View in y axis.
846 Standard_Real myFOVx; //!< Field Of View in x axis.
847 Standard_Real myFOV2d; //!< Field Of View limit for 2d on-screen elements
848 Standard_Real myFOVyTan; //!< Field Of View as Tan(DTR_HALF * myFOVy)
849 Standard_Real myZNear; //!< Distance to near clipping plane.
850 Standard_Real myZFar; //!< Distance to far clipping plane.
851 Standard_Real myAspect; //!< Width to height display ratio.
852 Standard_Boolean myIsZeroToOneDepth; //!< use [0, 1] depth range or [-1, 1]
854 Standard_Real myScale; //!< Specifies parallel scale for orthographic projection.
855 Standard_Real myZFocus; //!< Stereographic focus value.
856 FocusType myZFocusType; //!< Stereographic focus definition type.
858 Standard_Real myIOD; //!< Intraocular distance value.
859 IODType myIODType; //!< Intraocular distance definition type.
861 Graphic3d_CameraTile myTile;//!< Tile defining sub-area for drawing
863 Graphic3d_Mat4d myCustomProjMatM;
864 Graphic3d_Mat4d myCustomProjMatL;
865 Graphic3d_Mat4d myCustomProjMatR;
866 Graphic3d_Mat4d myCustomHeadToEyeMatL;
867 Graphic3d_Mat4d myCustomHeadToEyeMatR;
868 Aspect_FrustumLRBT<Standard_Real> myCustomFrustumL; //!< left custom frustum
869 Aspect_FrustumLRBT<Standard_Real> myCustomFrustumR; //!< right custom frustum
870 Standard_Boolean myIsCustomProjMatM; //!< flag indicating usage of custom projection matrix
871 Standard_Boolean myIsCustomProjMatLR; //!< flag indicating usage of custom stereo projection matrices
872 Standard_Boolean myIsCustomFrustomLR; //!< flag indicating usage of custom stereo frustums
874 mutable TransformMatrices<Standard_Real> myMatricesD;
875 mutable TransformMatrices<Standard_ShortReal> myMatricesF;
877 mutable Graphic3d_WorldViewProjState myWorldViewProjState;
881 DEFINE_STANDARD_RTTIEXT(Graphic3d_Camera,Standard_Transient)
884 DEFINE_STANDARD_HANDLE (Graphic3d_Camera, Standard_Transient)
886 //! Linear interpolation tool for camera orientation and position.
887 //! This tool interpolates camera parameters scale, eye, center, rotation (up and direction vectors) independently.
888 //! @sa Graphic3d_Camera::Interpolate()
890 inline void NCollection_Lerp<Handle(Graphic3d_Camera)>::Interpolate (const double theT,
891 Handle(Graphic3d_Camera)& theResult) const
893 Graphic3d_Camera::Interpolate (myStart, myEnd, theT, theResult);
896 //! Linear interpolation tool for camera orientation and position.
897 //! This tool interpolates camera parameters scale, eye, center, rotation (up and direction vectors) independently.
898 //! @sa Graphic3d_Camera::Interpolate()
899 typedef NCollection_Lerp<Handle(Graphic3d_Camera)> Graphic3d_CameraLerp;