Frustum¶
The Frustum
class template represents a 3D viewing frustum, with
predefined typedefs of type float
and double
.
Example:
#include <Imath/ImathFrustum.h>
#include <cassert>
void
frustum_example()
{
float near = 1.7f;
float far = 567.0f;
float left = -3.5f;
float right = 2.0f;
float top = 0.9f;
float bottom = -1.3f;
Imath::Frustumf frustum (near, far, left, right, top, bottom, false);
Imath::M44f m = frustum.projectionMatrix();
Imath::V3f p (1.0f, 1.0f, 1.0f);
Imath::V2f s = frustum.projectPointToScreen (p);
assert (s.equalWithAbsError (Imath::V2f (-0.345455f, -1.36364f), 0.0001f));
}
-
template<class
T
>
classFrustum
¶ Template class
Frustum<T>
The frustum is always located with the eye point at the origin facing down -Z. This makes the Frustum class compatable with OpenGL (or anything that assumes a camera looks down -Z, hence with a right-handed coordinate system) but not with RenderMan which assumes the camera looks down +Z. Additional functions are provided for conversion from and from various camera coordinate spaces.
nearPlane/farPlane: near/far are keywords used by Microsoft’s compiler, so we use nearPlane/farPlane instead to avoid issues.
Constructors and Assignment
-
constexpr
Frustum
()¶ Initialize with default values: near=0.1, far=1000.0, left=-1.0, right=1.0, top=1.0, bottom=-1.0, ortho=false.
-
constexpr
Frustum
(T nearPlane, T farPlane, T left, T right, T top, T bottom, bool ortho = false)¶ Initialize to specific values.
-
constexpr
Frustum
(T nearPlane, T farPlane, T fovx, T fovy, T aspect)¶ Initialize with fov and aspect.
-
~Frustum
()¶ Destructor.
-
constexpr const Frustum<T> &
operator=
(const Frustum &f)¶ Component-wise assignment.
Comparison
-
constexpr bool
operator==
(const Frustum<T> &src) const¶ Equality.
-
constexpr bool
operator!=
(const Frustum<T> &src) const¶ Inequality.
Query
-
constexpr bool
orthographic
() const¶ Return true if the frustum is orthographic, false if perspective.
-
constexpr T
nearPlane
() const¶ Return the near clipping plane.
-
constexpr T
hither
() const¶ Return the near clipping plane.
-
constexpr T
farPlane
() const¶ Return the far clipping plane.
-
constexpr T
yon
() const¶ Return the far clipping plane.
-
constexpr T
left
() const¶ Return the left of the frustum.
-
constexpr T
right
() const¶ Return the right of the frustum.
-
constexpr T
bottom
() const¶ Return the bottom of the frustum.
-
constexpr T
top
() const¶ Return the top of the frustum.
-
constexpr T
fovx
() const¶ Return the field of view in X.
-
constexpr T
fovy
() const¶ Return the field of view in Y.
-
constexpr T
aspect
() const¶ Return the aspect ratio.
-
constexpr T
aspectExc
() const¶ Return the aspect ratio.
Throw an exception if the aspect ratio is undefined.
-
constexpr Matrix44<T>
projectionMatrix
() const¶ Return the project matrix that the frustum defines.
-
constexpr Matrix44<T>
projectionMatrixExc
() const¶ Return the project matrix that the frustum defines.
Throw an exception if the frustum is degenerate.
-
constexpr bool
degenerate
() const¶ Return true if the frustum is degenerate.
Set Value
-
void
set
(T nearPlane, T farPlane, T left, T right, T top, T bottom, bool ortho = false)¶ Set functions change the entire state of the Frustum.
-
void
set
(T nearPlane, T farPlane, T fovx, T fovy, T aspect)¶ Set functions change the entire state of the Frustum using field of view and aspect ratio.
-
void
setExc
(T nearPlane, T farPlane, T fovx, T fovy, T aspect)¶ Set functions change the entire state of the Frustum using field of view and aspect ratio.
Throw an exception if
fovx
and/orfovy
are invalid.
-
void
modifyNearAndFar
(T nearPlane, T farPlane)¶ Set the near and far clipping planes.
-
void
setOrthographic
(bool ortho)¶ Set the ortographic state.
-
void
planes
(Plane3<T> p[6]) const¶ Set the planes in p to be the six bounding planes of the frustum, in the following order: top, right, bottom, left, near, far.
Note that the planes have normals that point out of the frustum.
-
void
planes
(Plane3<T> p[6], const Matrix44<T> &M) const¶ Set the planes in p to be the six bounding planes of the frustum, in the following order: top, right, bottom, left, near, far.
Note that the planes have normals that point out of the frustum. Apply the given matrix to transform the frustum before setting the planes.
Utility Methods
-
constexpr Line3<T>
projectScreenToRay
(const Vec2<T> &p) const¶ Project a point in screen spaced to 3d ray.
-
constexpr Vec2<T>
projectPointToScreen
(const Vec3<T> &point) const¶ Project a 3D point into screen coordinates.
-
constexpr Vec2<T>
projectPointToScreenExc
(const Vec3<T> &point) const¶ Project a 3D point into screen coordinates.
Throw an exception if the point cannot be projected.
-
constexpr T
ZToDepth
(long zval, long min, long max) const¶ Map a z value to its depth in the frustum.
-
constexpr T
ZToDepthExc
(long zval, long min, long max) const¶ Map a z value to its depth in the frustum.
-
constexpr T
normalizedZToDepth
(T zval) const¶ Map a normalized z value to its depth in the frustum.
-
constexpr T
normalizedZToDepthExc
(T zval) const¶ Map a normalized z value to its depth in the frustum.
Throw an exception on error.
-
constexpr long
DepthToZ
(T depth, long zmin, long zmax) const¶ Map depth to z value.
-
constexpr long
DepthToZExc
(T depth, long zmin, long zmax) const¶ Map depth to z value. Throw an exception on error.
-
constexpr T
worldRadius
(const Vec3<T> &p, T radius) const¶ Compute worldRadius.
-
constexpr T
worldRadiusExc
(const Vec3<T> &p, T radius) const¶ Compute worldRadius. Throw an exception on error.
-
constexpr T
screenRadius
(const Vec3<T> &p, T radius) const¶ Compute screen radius.
-
constexpr T
screenRadiusExc
(const Vec3<T> &p, T radius) const¶ Compute screen radius. Throw an exception on error.
-
constexpr