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