All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
frustum.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef GF_FRUSTUM_H
25 #define GF_FRUSTUM_H
26 
29 
30 #include "pxr/pxr.h"
31 #include "pxr/base/gf/bbox3d.h"
32 #include "pxr/base/gf/matrix4d.h"
33 #include "pxr/base/gf/plane.h"
34 #include "pxr/base/gf/ray.h"
35 #include "pxr/base/gf/range1d.h"
36 #include "pxr/base/gf/range2d.h"
37 #include "pxr/base/gf/rotation.h"
38 #include "pxr/base/gf/vec2d.h"
39 #include "pxr/base/gf/vec3d.h"
40 #include "pxr/base/gf/api.h"
41 
42 #include <boost/functional/hash.hpp>
43 
44 #include <iosfwd>
45 #include <vector>
46 
47 PXR_NAMESPACE_OPEN_SCOPE
48 
87 class GfFrustum {
88  public:
94  };
95 
104  GF_API GfFrustum();
105 
108  GF_API GfFrustum(const GfVec3d &position, const GfRotation &rotation,
109  const GfRange2d &window, const GfRange1d &nearFar,
110  GfFrustum::ProjectionType projectionType,
111  double viewDistance = 5.0);
112 
116  GF_API GfFrustum(const GfMatrix4d &camToWorldXf,
117  const GfRange2d &window, const GfRange1d &nearFar,
118  GfFrustum::ProjectionType projectionType,
119  double viewDistance = 5.0);
120 
121  friend inline size_t hash_value(const GfFrustum &f) {
122  size_t h = 0;
123  boost::hash_combine(h, f._position);
124  boost::hash_combine(h, f._rotation);
125  boost::hash_combine(h, f._window);
126  boost::hash_combine(h, f._nearFar);
127  boost::hash_combine(h, f._viewDistance);
128  boost::hash_combine(h, f._projectionType);
129  return h;
130  }
131 
132  // Equality operator. true iff all parts match.
133  bool operator ==(const GfFrustum& f) const {
134  if (_position != f._position) return false;
135  if (_rotation != f._rotation) return false;
136  if (_window != f._window) return false;
137  if (_nearFar != f._nearFar) return false;
138  if (_viewDistance != f._viewDistance) return false;
139  if (_projectionType != f._projectionType) return false;
140 
141  return true;
142  }
143 
144  // Inequality operator. true iff not equality.
145  bool operator !=(const GfFrustum& f) const {
146  return !(*this == f);
147  }
148 
150  GF_API ~GfFrustum();
151 
156 
158  void SetPosition(const GfVec3d &position) {
159  _position = position;
160  _DirtyFrustumPlanes();
161  }
162 
164  const GfVec3d & GetPosition() const {
165  return _position;
166  }
167 
171  void SetRotation(const GfRotation &rotation) {
172  _rotation = rotation;
173  _DirtyFrustumPlanes();
174  }
175 
178  const GfRotation & GetRotation() const {
179  return _rotation;
180  }
181 
187  GF_API void SetPositionAndRotationFromMatrix(const GfMatrix4d &camToWorldXf);
188 
191  void SetWindow(const GfRange2d &window) {
192  _window = window;
193  _DirtyFrustumPlanes();
194  }
195 
197  const GfRange2d & GetWindow() const {
198  return _window;
199  }
200 
202  static double GetReferencePlaneDepth() {
203  return 1.0;
204  }
205 
207  void SetNearFar(const GfRange1d &nearFar) {
208  _nearFar = nearFar;
209  _DirtyFrustumPlanes();
210  }
211 
213  const GfRange1d & GetNearFar() const {
214  return _nearFar;
215  }
216 
218  void SetViewDistance(double viewDistance) {
219  _viewDistance = viewDistance;
220  }
221 
223  double GetViewDistance() const {
224  return _viewDistance;
225  }
226 
229  _projectionType = projectionType;
230  _DirtyFrustumPlanes();
231  }
232 
235  return _projectionType;
236  }
237 
239 
247 
265  GF_API void SetPerspective(double fieldOfViewHeight,
266  double aspectRatio,
267  double nearDistance, double farDistance);
268 
296  GF_API void SetPerspective(double fieldOfView,
297  bool isFovVertical,
298  double aspectRatio,
299  double nearDistance, double farDistance);
300 
304  GF_API bool GetPerspective(double *fieldOfViewHeight,
305  double *aspectRatio,
306  double *nearDistance,
307  double *farDistance) const;
308 
312  GF_API bool GetPerspective(bool isFovVertical,
313  double *fieldOfView,
314  double *aspectRatio,
315  double *nearDistance,
316  double *farDistance) const;
317 
329  GF_API double GetFOV(bool isFovVertical = false);
330 
335  GF_API
336  void SetOrthographic(double left, double right,
337  double bottom, double top,
338  double nearPlane, double farPlane);
339 
343  GF_API bool GetOrthographic(double *left, double *right,
344  double *bottom, double *top,
345  double *nearPlane, double *farPlane)
346  const;
347 
353  GF_API void FitToSphere(const GfVec3d &center,
354  double radius,
355  double slack = 0.0);
356 
370  GF_API GfFrustum& Transform(const GfMatrix4d &matrix);
371 
374  GF_API GfVec3d ComputeViewDirection() const;
375 
378  GF_API GfVec3d ComputeUpVector() const;
379 
393  GF_API void ComputeViewFrame(GfVec3d *side,
394  GfVec3d *up,
395  GfVec3d *view) const;
396 
399  GF_API GfVec3d ComputeLookAtPoint() const;
400 
404  GF_API GfMatrix4d ComputeViewMatrix() const;
405 
409  GF_API GfMatrix4d ComputeViewInverse() const;
410 
413  GF_API GfMatrix4d ComputeProjectionMatrix() const;
414 
418  GF_API double ComputeAspectRatio() const;
419 
430  GF_API
431  std::vector<GfVec3d> ComputeCorners() const;
432 
442  GF_API
443  std::vector<GfVec3d> ComputeCornersAtDistance(double d) const;
444 
458  GF_API GfFrustum ComputeNarrowedFrustum(const GfVec2d &point,
459  const GfVec2d &halfSize) const;
460 
474  GF_API GfFrustum ComputeNarrowedFrustum(const GfVec3d &worldPoint,
475  const GfVec2d &halfSize) const;
476 
484  GF_API GfRay ComputeRay(const GfVec2d &windowPos) const;
485 
492  GF_API GfRay ComputeRay(const GfVec3d &worldSpacePos) const;
493 
500  GF_API GfRay ComputePickRay(const GfVec2d &windowPos) const;
501 
504  GF_API GfRay ComputePickRay(const GfVec3d &worldSpacePos) const;
505 
507 
514 
518  GF_API bool Intersects(const GfBBox3d &bbox) const;
519 
522  GF_API bool Intersects(const GfVec3d &point) const;
523 
526  GF_API bool Intersects(const GfVec3d &p0,
527  const GfVec3d &p1) const;
528 
531  GF_API bool Intersects(const GfVec3d &p0,
532  const GfVec3d &p1,
533  const GfVec3d &p2) const;
534 
546  GF_API static bool IntersectsViewVolume(const GfBBox3d &bbox,
547  const GfMatrix4d &vpMat);
548 
550 
551  private:
552  // Dirty the result of _CalculateFrustumPlanes.
553  GF_API void _DirtyFrustumPlanes();
554 
555  // Calculates cached frustum planes used for intersection tests.
556  GF_API void _CalculateFrustumPlanes() const;
557 
558  // Builds and returns a \c GfRay that can be used for picking. Given an
559  // eye position and direction in camera space, offsets the ray to emanate
560  // from the near plane, then transforms into worldspace
561  GF_API GfRay _ComputePickRayOffsetToNearPlane(
562  const GfVec3d &camSpaceFrom,
563  const GfVec3d &camSpaceDir) const;
564 
565  // Returns a frustum that is a narrowed-down version of this frustum, such
566  // that the frustum rectangle on the near plane encloses \p point with at
567  // most \p halfSize[0] distance on the left and right and at most \p
568  // halfSize[1] distance on the top and bottom. (If \p point is closer than
569  // the half size to a side of the frustum, that side is left alone. The
570  // point and sizes are in normalized 2D coordinates; they range from (-1,
571  // -1) at the lower left corner of the near-plane window rectangle to
572  // (1,1) at the upper right corner.
573  //
574  // \p windowPoint is expressed in window coordinates
575  //
576  // This method is useful for computing a volume to use for interactive
577  // picking.
578  GfFrustum _ComputeNarrowedFrustumSub(const GfVec2d windowPoint,
579  const GfVec2d &halfSize) const;
580 
581  bool _SegmentIntersects(GfVec3d const &p0, uint32_t p0Mask,
582  GfVec3d const &p1, uint32_t p1Mask) const;
583 
584  // Position of the frustum in world space.
585  GfVec3d _position;
586 
587  // Orientation of the frustum in world space as a rotation to apply to the
588  // -z axis.
589  GfRotation _rotation;
590 
591  // Window rectangle in the image plane.
592  GfRange2d _window;
593 
594  // Near/far interval.
595  GfRange1d _nearFar;
596 
597  // View distance.
598  double _viewDistance;
599 
600  // Projection type.
601  ProjectionType _projectionType;
602 
603  // Cached planes.
604  // If empty, the planes have not been calculated.
605  mutable std::vector<GfPlane> _planes;
606 };
607 
615 GF_API std::ostream& operator<<(std::ostream& out, const GfFrustum& f);
616 
617 PXR_NAMESPACE_CLOSE_SCOPE
618 
619 #endif // GF_FRUSTUM_H
GF_API GfVec3d ComputeViewDirection() const
Returns the normalized world-space view direction vector, which is computed by rotating the -z axis b...
GF_API GfMatrix4d ComputeViewInverse() const
Returns a matrix that represents the inverse viewing transformation for this frustum.
GfFrustum::ProjectionType GetProjectionType() const
Returns the projection type.
Definition: frustum.h:234
double GetViewDistance() const
Returns the view distance.
Definition: frustum.h:223
GF_API GfVec3d ComputeLookAtPoint() const
Computes and returns the world-space look-at point from the eye point (position), view direction (rot...
void SetProjectionType(GfFrustum::ProjectionType projectionType)
Sets the projection type.
Definition: frustum.h:228
const GfVec3d & GetPosition() const
Returns the position of the frustum in world space.
Definition: frustum.h:164
Basic type: 1-dimensional floating point range.
Definition: range1d.h:62
GF_API void FitToSphere(const GfVec3d &center, double radius, double slack=0.0)
Modifies the frustum to tightly enclose a sphere with the given center and radius, using the current view direction.
const GfRotation & GetRotation() const
Returns the orientation of the frustum in world space as a rotation to apply to the -z axis...
Definition: frustum.h:178
GF_API GfFrustum & Transform(const GfMatrix4d &matrix)
Transforms the frustum by the given matrix.
GF_API bool GetPerspective(double *fieldOfViewHeight, double *aspectRatio, double *nearDistance, double *farDistance) const
Returns the current frustum in the format used by SetPerspective().
Basic type for a vector of 2 double components.
Definition: vec2d.h:63
GF_API std::vector< GfVec3d > ComputeCornersAtDistance(double d) const
Returns the world-space corners of the intersection of the frustum with a plane parallel to the near/...
GF_API void SetOrthographic(double left, double right, double bottom, double top, double nearPlane, double farPlane)
Sets up the frustum in a manner similar to glOrtho().
GF_API void SetPositionAndRotationFromMatrix(const GfMatrix4d &camToWorldXf)
Sets the position and rotation of the frustum from a camera matrix (always from a y-Up camera)...
static GF_API bool IntersectsViewVolume(const GfBBox3d &bbox, const GfMatrix4d &vpMat)
Returns true if the bbox volume intersects the view volume given by the view-projection matrix...
GF_API GfFrustum ComputeNarrowedFrustum(const GfVec2d &point, const GfVec2d &halfSize) const
Returns a frustum that is a narrowed-down version of this frustum, such that the frustum rectangle on...
GF_API double ComputeAspectRatio() const
Returns the aspect ratio of the frustum, defined as the width of the window divided by the height...
void SetWindow(const GfRange2d &window)
Sets the window rectangle in the reference plane that defines the left, right, top, and bottom planes of the frustum.
Definition: frustum.h:191
void SetViewDistance(double viewDistance)
Sets the view distance.
Definition: frustum.h:218
GF_API GfMatrix4d ComputeViewMatrix() const
Returns a matrix that represents the viewing transformation for this frustum.
Stores a 4x4 matrix of double elements.
Definition: matrix4d.h:88
GF_API double GetFOV(bool isFovVertical=false)
Returns the horizontal or vertical fov of the frustum.
Basic type: 2-dimensional floating point range.
Definition: range2d.h:64
Basic type: View frustum.
Definition: frustum.h:87
GF_API void SetPerspective(double fieldOfViewHeight, double aspectRatio, double nearDistance, double farDistance)
Sets up the frustum in a manner similar to gluPerspective().
GF_API GfRay ComputeRay(const GfVec2d &windowPos) const
Builds and returns a GfRay that starts at the viewpoint and extends through the given windowPos given...
Perspective projection.
Definition: frustum.h:93
GF_API void ComputeViewFrame(GfVec3d *side, GfVec3d *up, GfVec3d *view) const
Computes the view frame defined by this frustum.
GF_API bool Intersects(const GfBBox3d &bbox) const
Returns true if the given axis-aligned bbox is inside or intersecting the frustum.
void SetNearFar(const GfRange1d &nearFar)
Sets the near/far interval.
Definition: frustum.h:207
ProjectionType
This enum is used to determine the type of projection represented by a frustum.
Definition: frustum.h:91
GF_API std::ostream & operator<<(std::ostream &, const GfBBox3d &)
Output a GfBBox3d using the format [(range) matrix zeroArea].
GF_API ~GfFrustum()
Destructor.
GF_API GfFrustum()
This constructor creates an instance with default viewing parameters:
void SetPosition(const GfVec3d &position)
Sets the position of the frustum in world space.
Definition: frustum.h:158
Basic type for a vector of 3 double components.
Definition: vec3d.h:63
Basic type: Ray used for intersection testing.
Definition: ray.h:60
GF_API GfRay ComputePickRay(const GfVec2d &windowPos) const
Builds and returns a GfRay that can be used for picking at the given normalized (-1 to +1 in both dim...
static double GetReferencePlaneDepth()
Returns the depth of the reference plane.
Definition: frustum.h:202
const GfRange2d & GetWindow() const
Returns the window rectangle in the reference plane.
Definition: frustum.h:197
const GfRange1d & GetNearFar() const
Returns the near/far interval.
Definition: frustum.h:213
GF_API bool GetOrthographic(double *left, double *right, double *bottom, double *top, double *nearPlane, double *farPlane) const
Returns the current frustum in the format used by SetOrthographic().
Basic type: 3-space rotation specification.
Definition: rotation.h:55
GF_API GfVec3d ComputeUpVector() const
Returns the normalized world-space up vector, which is computed by rotating the y axis by the frustum...
Basic type: arbitrarily oriented 3D bounding box.
Definition: bbox3d.h:84
void SetRotation(const GfRotation &rotation)
Sets the orientation of the frustum in world space as a rotation to apply to the default frame: looki...
Definition: frustum.h:171
GF_API std::vector< GfVec3d > ComputeCorners() const
Returns the world-space corners of the frustum as a vector of 8 points, ordered as: ...
Orthographic projection.
Definition: frustum.h:92
GF_API GfMatrix4d ComputeProjectionMatrix() const
Returns a GL-style projection matrix corresponding to the frustum&#39;s projection.