0024001: Stereographic rendering support
[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//
7// This library is free software; you can redistribute it and / or modify it
8// under the terms of the GNU Lesser General Public version 2.1 as published
9// by the Free Software Foundation, with special exception defined in the file
10// OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
11// distribution for complete text of the license and disclaimer of any warranty.
12//
13// Alternatively, this file may be used under the terms of Open CASCADE
14// commercial license or contractual agreement.
15
16#ifndef _Graphic3d_Camera_HeaderFile
17#define _Graphic3d_Camera_HeaderFile
18
19#include <Graphic3d_Mat4.hxx>
20#include <Graphic3d_Vec3.hxx>
21
22#include <gp_Dir.hxx>
23#include <gp_Pnt.hxx>
24
25#include <Standard_Macro.hxx>
26#include <Standard_TypeDef.hxx>
27
28DEFINE_STANDARD_HANDLE (Graphic3d_Camera, Standard_Transient)
29
30//! Camera class provides object-oriented approach to setting up projection
31//! and orientation properties of 3D view.
32class Graphic3d_Camera : public Standard_Transient
33{
34
35public:
36
37 //! Enumerates supported monographic projections.
38 //! - Projection_Orthographic : orthographic projection.
39 //! - Projection_Perspective : perspective projection.
40 //! - Projection_Stere : stereographic projection.
41 //! - Projection_MonoLeftEye : mono projection for stereo left eye.
42 //! - Projection_MonoRightEye : mono projection for stereo right eye.
43 enum Projection
44 {
45 Projection_Orthographic,
46 Projection_Perspective,
47 Projection_Stereo,
48 Projection_MonoLeftEye,
49 Projection_MonoRightEye
50 };
51
52 //! Enumerates approaches to define stereographic focus.
53 //! - FocusType_Absolute : focus is specified as absolute value.
54 //! - FocusType_Relative : focus is specified relative to
55 //! (as coefficient of) camera focal length.
56 enum FocusType
57 {
58 FocusType_Absolute,
59 FocusType_Relative
60 };
61
62 //! Enumerates approaches to define Intraocular distance.
63 //! - IODType_Absolute : Intraocular distance is defined as absolute value.
64 //! - IODType_Relative : Intraocular distance is defined relative to
65 //! (as coefficient of) camera focal length.
66 enum IODType
67 {
68 IODType_Absolute,
69 IODType_Relative
70 };
71
72public:
73
74 //! Default constructor.
75 //! Initializes camera with the following properties:
76 //! Eye (0, 0, -2); Center (0, 0, 0); Up (0, 1, 0);
77 //! Type (Orthographic); FOVy (45); Scale (1000); IsStereo(false);
78 //! ZNear (0.1); ZFar (100); Aspect(1);
79 //! ZFocus(1.0); ZFocusType(Relative); IOD(0.05); IODType(Relative)
80 Standard_EXPORT Graphic3d_Camera();
81
82 //! Copy constructor.
83 //! @param theOther [in] the camera to copy from.
84 Standard_EXPORT Graphic3d_Camera (const Handle(Graphic3d_Camera)& theOther);
85
86 //! Initialize mapping related parameters from other camera handle.
87 Standard_EXPORT void CopyMappingData (const Handle(Graphic3d_Camera)& theOtherCamera);
88
89 //! Initialize orientation related parameters from other camera handle.
90 Standard_EXPORT void CopyOrientationData (const Handle(Graphic3d_Camera)& theOtherCamera);
91
92 //! Copy properties of another camera.
93 //! @param theOther [in] the camera to copy from.
94 Standard_EXPORT void Copy (const Handle(Graphic3d_Camera)& theOther);
95
96 //! Returns modification state of camera projection matrix
97 Standard_Size ProjectionState() const
98 {
99 return myProjectionState;
100 }
101
102 //! Returns modification state of camera model-view matrix
103 Standard_Size ModelViewState() const
104 {
105 return myOrientationState;
106 }
107
108 //! Sets camera Eye position.
109 //! @param theEye [in] the location of camera's Eye.
110 Standard_EXPORT void SetEye (const gp_Pnt& theEye);
111
112 //! Get camera Eye position.
113 //! @return camera eye location.
114 const gp_Pnt& Eye() const
115 {
116 return myEye;
117 }
118
119 //! Sets Center of the camera.
120 //! @param theCenter [in] the point where the camera looks at.
121 Standard_EXPORT void SetCenter (const gp_Pnt& theCenter);
122
123 //! Get Center of the camera.
124 //! @return the point where the camera looks at.
125 const gp_Pnt& Center() const
126 {
127 return myCenter;
128 }
129
130 //! Sets camera Up direction vector.
131 //! @param theUp [in] the Up direction vector.
132 Standard_EXPORT void SetUp (const gp_Dir& theUp);
133
134 //! Get camera Up direction vector.
135 //! @return Camera's Up direction vector.
136 const gp_Dir& Up() const
137 {
138 return myUp;
139 }
140
141 //! Set camera projection shift vector.<br>
142 //! Used for compatibility with older view mechanics. Applied after
143 //! view transform and before projection step (P * Shift * V).
144 //! @param theProjShift [in] the projection shift vector.
145 Standard_EXPORT void SetProjectionShift (const gp_Pnt& theProjShift);
146
147 //! Get camera projection shift vector.
148 //! @return Camera's projection shift vector.
149 const gp_Pnt& ProjectionShift() const
150 {
151 return myProjectionShift;
152 }
153
154 //! Set camera axial scale.<br>
155 //! @param theAxialScale [in] the axial scale vector.
156 Standard_EXPORT void SetAxialScale (const gp_Pnt& theAxialScale);
157
158 //! Get camera axial scale.
159 //! @return Camera's axial scale.
160 const gp_Pnt& AxialScale() const
161 {
162 return myAxialScale;
163 }
164
165 //! Set distance of Eye from camera Center.
166 //! @param theDistance [in] the distance.
167 Standard_EXPORT void SetDistance (const Standard_Real theDistance);
168
169 //! Get distance of Eye from camera Center.
170 //! @return the distance.
171 Standard_EXPORT Standard_Real Distance() const;
172
173 //! Sets camera look direction.
174 //! @param theDir [in] the direction.
175 Standard_EXPORT void SetDirection (const gp_Dir& theDir);
176
177 //! Get camera look direction.
178 //! @return camera look direction.
179 Standard_EXPORT gp_Dir Direction() const;
180
181 //! Sets camera scale. For orthographic projection the scale factor
182 //! corresponds to parallel scale of view mapping (i.e. size
183 //! of viewport). For perspective camera scale is converted to
184 //! distance.
185 //! @param theScale [in] the scale factor.
186 Standard_EXPORT void SetScale (const Standard_Real theScale);
187
188 //! Get camera scale.
189 //! @return camera scale factor.
190 Standard_EXPORT Standard_Real Scale() const;
191
192 //! Change camera projection type.
193 //! While switching between perspective and ortho projection types
194 //! ZNear and ZFar value conversion is performed due to different
195 //! coordinate systems (made for compatibility, to be improved..)
196 //! @param theProjectionType [in] the camera projection type.
197 Standard_EXPORT void SetProjectionType (const Projection theProjection);
198
199 //! @return camera projection type.
200 Projection ProjectionType() const
201 {
202 return myProjType;
203 }
204
205 //! Check that the camera projection is orthographic.
206 //! @return boolean flag that indicates whether the camera's projection is
207 //! orthographic or not.
208 Standard_Boolean IsOrthographic() const
209 {
210 return (myProjType == Projection_Orthographic);
211 }
212
213 //! Check whether the camera projection is stereo.
214 //! Please note that stereo rendering is now implemented with support of
215 //! Quad buffering.
216 //! @return boolean flag indicating whether the stereographic L/R projection
217 //! is chosen.
218 Standard_Boolean IsStereo() const
219 {
220 return (myProjType == Projection_Stereo);
221 }
222
223 //! Set Field Of View (FOV) in y axis for perspective projection.
224 //! @param theFOVy [in] the FOV in degrees.
225 Standard_EXPORT void SetFOVy (const Standard_Real theFOVy);
226
227 //! Get Field Of View (FOV) in y axis.
228 //! @return the FOV value in degrees.
229 Standard_Real FOVy() const
230 {
231 return myFOVy;
232 }
233
234 //! Change the Near Z-clipping plane position.
235 //! @param theZNear [in] the distance of the plane from the Eye.
236 Standard_EXPORT void SetZNear (const Standard_Real theZNear);
237
238 //! Get the Near Z-clipping plane position.
239 //! @return the distance of the plane from the Eye.
240 Standard_Real ZNear() const
241 {
242 return myZNear;
243 }
244
245 //! Change the Far Z-clipping plane position.
246 //! @param theZFar [in] the distance of the plane from the Eye.
247 Standard_EXPORT void SetZFar (const Standard_Real theZFar);
248
249 //! Get the Far Z-clipping plane position.
250 //! @return the distance of the plane from the Eye.
251 Standard_Real ZFar() const
252 {
253 return myZFar;
254 }
255
256 //! Change display ratio.
257 //! @param theAspect [in] the display ratio.
258 Standard_EXPORT void SetAspect (const Standard_Real theAspect);
259
260 //! Get camera display ratio.
261 //! @return display ratio.
262 Standard_Real Aspect() const
263 {
264 return myAspect;
265 }
266
267 //! Sets stereographic focus distance.
268 //! @param theType [in] the focus definition type. Focus can be defined
269 //! as absolute value or relatively to (as coefficient of) coefficient of
270 //! camera focal length.
271 //! @param theZFocus [in] the focus absolute value or coefficient depending
272 //! on the passed definition type.
273 Standard_EXPORT void SetZFocus (const FocusType theType, const Standard_Real theZFocus);
274
275 //! Get stereographic focus value.
276 //! @return absolute or relative stereographic focus value
277 //! depending on its definition type.
278 Standard_Real ZFocus() const
279 {
280 return myZFocus;
281 }
282
283 //! Get stereographic focus definition type.
284 //! @return definition type used for stereographic focus.
285 FocusType ZFocusType() const
286 {
287 return myZFocusType;
288 }
289
290 //! Sets Intraocular distance.
291 //! @param theType [in] the IOD definition type. IOD can be defined as
292 //! absolute value or relatively to (as coefficient of) camera focal length.
293 //! @param theIOD [in] the Intraocular distance.
294 Standard_EXPORT void SetIOD (const IODType theType, const Standard_Real theIOD);
295
296 //! Get Intraocular distance value.
297 //! @return absolute or relative IOD value depending on its definition type.
298 Standard_Real IOD() const
299 {
300 return myIOD;
301 }
302
303 //! Get Intraocular distance definition type.
304 //! @return definition type used for Intraocular distance.
305 IODType GetIODType() const
306 {
307 return myIODType;
308 }
309
310 //! Get orientation matrix.
311 //! @return camera orientation matrix.
312 const Graphic3d_Mat4& OrientationMatrix() const
313 {
314 return myOrientation;
315 }
316
317 //! Get monographic or middle point projection matrix used for monographic
318 //! rendering and for point projection / unprojection.
319 //! @return monographic projection matrix.
320 const Graphic3d_Mat4& ProjectionMatrix() const
321 {
322 return myMProjection;
323 }
324
325 //! @return stereographic matrix computed for left eye. Please note
326 //! that this method is used for rendering for <i>Projection_Stereo</i>.
327 const Graphic3d_Mat4& ProjectionStereoLeft() const
328 {
329 return myLProjection;
330 }
331
332 //! @return stereographic matrix computed for right eye. Please note
333 //! that this method is used for rendering for <i>Projection_Stereo</i>.
334 const Graphic3d_Mat4& ProjectionStereoRight() const
335 {
336 return myRProjection;
337 }
338
339public:
340
341 //! Orthogonalize up direction vector.
342 Standard_EXPORT void OrthogonalizeUp();
343
344 //! Suspend internal data recalculation when changing set of camera
345 //! properties. This method is optional and can be used for pieces
346 //! of code which are critical to performance. Note that the method
347 //! supports stacked calls (carried out by internal counter).
348 Standard_EXPORT void BeginUpdate();
349
350 //! Unset lock set by <i>BeginUpdate</i> and invoke data recalculation when
351 //! there are no more locks left. This method is optional and can be used
352 //! for pieces of code which are critical to performance.
353 Standard_EXPORT void EndUpdate();
354
355 // Basic camera operations
356public:
357
358 //! Transform orientation components of the camera:
359 //! Eye, Up and Center points.
360 //! @param theTrsf [in] the transformation to apply.
361 Standard_EXPORT void Transform (const gp_Trsf& theTrsf);
362
363 //! Calculate view plane size at center (target) point
364 //! and distance between ZFar and ZNear planes.
365 //! @return values in form of gp_Pnt (Width, Height, Depth).
366 Standard_EXPORT gp_Pnt ViewDimensions () const;
367
368 //! Calculate view plane dimensions with projection shift applied.
369 //! Analog to old ViewMapping.WindowLimit() function.
370 //! @param theUMin [out] the u component of min corner of the rect.
371 //! @param theVMin [out] the v component of min corner of the rect.
372 //! @param theUMax [out] the u component of max corner of the rect.
373 //! @param theVMax [out] the v component of max corner of the rect.
374 Standard_EXPORT void WindowLimit (Standard_Real& theUMin,
375 Standard_Real& theVMin,
376 Standard_Real& theUMax,
377 Standard_Real& theVMax) const;
378
379 // Projection methods
380public:
381
382 //! Project point from world coordinate space to
383 //! normalized device coordinates (mapping).
384 //! @param thePnt [in] the 3D point in WCS.
385 //! @return mapped point in NDC.
386 Standard_EXPORT gp_Pnt Project (const gp_Pnt& thePnt) const;
387
388 //! Unproject point from normalized device coordinates
389 //! to world coordinate space.
390 //! @param thePnt [in] the NDC point.
391 //! @return 3D point in WCS.
392 Standard_EXPORT gp_Pnt UnProject (const gp_Pnt& thePnt) const;
393
394 //! Convert point from view coordinate space to
395 //! projection coordinate space.
396 //! @param thePnt [in] the point in VCS.
397 //! @return point in NDC.
398 Standard_EXPORT gp_Pnt ConvertView2Proj (const gp_Pnt& thePnt) const;
399
400 //! Convert point from projection coordinate space
401 //! to view coordinate space.
402 //! @param thePnt [in] the point in NDC.
403 //! @return point in VCS.
404 Standard_EXPORT gp_Pnt ConvertProj2View (const gp_Pnt& thePnt) const;
405
406 //! Convert point from world coordinate space to
407 //! view coordinate space.
408 //! @param thePnt [in] the 3D point in WCS.
409 //! @return point in VCS.
410 Standard_EXPORT gp_Pnt ConvertWorld2View (const gp_Pnt& thePnt) const;
411
412 //! Convert point from view coordinate space to
413 //! world coordinates.
414 //! @param thePnt [in] the 3D point in VCS.
415 //! @return point in WCS.
416 Standard_EXPORT gp_Pnt ConvertView2World (const gp_Pnt& thePnt) const;
417
418 // managing projection and orientation cache:
419public:
420
421 //! Compute and cache projection matrices.
422 void UpdateProjection();
423
424 //! Compute and cache orientation matrix.
425 void UpdateOrientation();
426
427private:
428
429 //! Compose orthographic projection matrix for
430 //! the passed camera volume mapping.
431 //! @param theLeft [in] the left mapping (clipping) coordinate.
432 //! @param theRight [in] the right mapping (clipping) coordinate.
433 //! @param theBottom [in] the bottom mapping (clipping) coordinate.
434 //! @param theTop [in] the top mapping (clipping) coordinate.
435 //! @param theNear [in] the near mapping (clipping) coordinate.
436 //! @param theFar [in] the far mapping (clipping) coordinate.
437 //! @param theShiftX [in] the shift x coordinate.
438 //! @param theShiftY [in] the shift y coordinate.
439 //! @param theOutMx [out] the projection matrix.
440 static void
441 OrthoProj (const Standard_ShortReal theLeft,
442 const Standard_ShortReal theRight,
443 const Standard_ShortReal theBottom,
444 const Standard_ShortReal theTop,
445 const Standard_ShortReal theNear,
446 const Standard_ShortReal theFar,
447 const Standard_ShortReal theShiftX,
448 const Standard_ShortReal theShiftY,
449 Graphic3d_Mat4& theOutMx);
450
451 //! Compose perspective projection matrix for
452 //! the passed camera volume mapping.
453 //! @param theLeft [in] the left mapping (clipping) coordinate.
454 //! @param theRight [in] the right mapping (clipping) coordinate.
455 //! @param theBottom [in] the bottom mapping (clipping) coordinate.
456 //! @param theTop [in] the top mapping (clipping) coordinate.
457 //! @param theNear [in] the near mapping (clipping) coordinate.
458 //! @param theFar [in] the far mapping (clipping) coordinate.
459 //! @param theShiftX [in] the shift x coordinate.
460 //! @param theShiftY [in] the shift y coordinate.
461 //! @param theOutMx [out] the projection matrix.
462 static void
463 PerspectiveProj (const Standard_ShortReal theLeft,
464 const Standard_ShortReal theRight,
465 const Standard_ShortReal theBottom,
466 const Standard_ShortReal theTop,
467 const Standard_ShortReal theNear,
468 const Standard_ShortReal theFar,
469 const Standard_ShortReal theShiftX,
470 const Standard_ShortReal theShiftY,
471 Graphic3d_Mat4& theOutMx);
472
473 //! Compose projection matrix for L/R stereo eyes.
474 //! @param theLeft [in] the left mapping (clipping) coordinate.
475 //! @param theRight [in] the right mapping (clipping) coordinate.
476 //! @param theBottom [in] the bottom mapping (clipping) coordinate.
477 //! @param theTop [in] the top mapping (clipping) coordinate.
478 //! @param theNear [in] the near mapping (clipping) coordinate.
479 //! @param theFar [in] the far mapping (clipping) coordinate.
480 //! @param theIOD [in] the Intraocular distance.
481 //! @param theZFocus [in] the z coordinate of off-axis
482 //! projection plane with zero parallax.
483 //! @param theShiftX [in] the shift x coordinate.
484 //! @param theShiftY [in] the shift y coordinate.
485 //! @param theIsLeft [in] boolean flag to choose between L/R eyes.
486 //! @param theOutMx [out] the projection matrix.
487 static void
488 StereoEyeProj (const Standard_ShortReal theLeft,
489 const Standard_ShortReal theRight,
490 const Standard_ShortReal theBottom,
491 const Standard_ShortReal theTop,
492 const Standard_ShortReal theNear,
493 const Standard_ShortReal theFar,
494 const Standard_ShortReal theIOD,
495 const Standard_ShortReal theZFocus,
496 const Standard_ShortReal theShiftX,
497 const Standard_ShortReal theShiftY,
498 const Standard_Boolean theIsLeft,
499 Graphic3d_Mat4& theOutMx);
500
501 //! Construct "look at" orientation transformation.
502 //! Reference point differs for perspective and ortho modes
503 //! (made for compatibility, to be improved..).
504 //! @param theEye [in] the eye coordinates in 3D space.
505 //! @param theLookAt [in] the point the camera looks at.
506 //! @param theUpDir [in] the up direction vector.
507 //! @param theAxialScale [in] the axial scale vector.
508 //! @param theOutMx [in/out] the orientation matrix.
509 static void
510 LookOrientation (const Graphic3d_Vec3& theEye,
511 const Graphic3d_Vec3& theLookAt,
512 Graphic3d_Vec3& theUpDir,
513 const Graphic3d_Vec3& theAxialScale,
514 Graphic3d_Mat4& theOutMx);
515
516private:
517
518 gp_Dir myUp; //!< Camera up direction vector.
519 gp_Pnt myEye; //!< Camera eye position.
520 gp_Pnt myCenter; //!< Camera center.
521
522 gp_Pnt myProjectionShift; //!< Camera projection shift for compatibility.
523 gp_Pnt myAxialScale; //!< Camera axial scale.
524
525 Projection myProjType; //!< Projection type used for rendering.
526 Standard_Real myFOVy; //!< Field Of View in y axis.
527 Standard_Real myZNear; //!< Distance to near clipping plane.
528 Standard_Real myZFar; //!< Distance to far clipping plane.
529 Standard_Real myAspect; //!< Width to height display ratio.
530
531 Standard_Real myScale; //!< Specifies parallel scale for orthographic projection.
532 Standard_Real myZFocus; //!< Stereographic focus value.
533 FocusType myZFocusType; //!< Stereographic focus definition type.
534
535 Standard_Real myIOD; //!< Intraocular distance value.
536 IODType myIODType; //!< Intraocular distance definition type.
537
538 //! Number of locks set up on internal data recalculation by
539 //! <i>(BeginUpdate, EndUpdate)</i> pairs. The counter provides effective
540 //! use of the mentioned methods when camera properties are modified
541 //! in stacked functions.
542 Standard_Integer myNbUpdateLocks;
543
544 Graphic3d_Mat4 myOrientation; //!< Camera orientation matrix.
545 Graphic3d_Mat4 myMProjection; //!< Monographic projection matrix.
546 Graphic3d_Mat4 myLProjection; //!< Projection matrix for left eye.
547 Graphic3d_Mat4 myRProjection; //!< Projection matrix for right eye.
548
549 Standard_Size myProjectionState;
550 Standard_Size myOrientationState;
551
552public:
553
554 DEFINE_STANDARD_RTTI(Graphic3d_Camera);
555
556};
557
558#endif