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));
}
typedef Frustum<float> Imath::Frustumf

Frustum of type float.

typedef Frustum<double> Imath::Frustumd

Frustum of type double.

template<class T>
class Frustum

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(const Frustum &f)

Copy constructor.

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/or fovy 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.

constexpr Frustum<T> window(T left, T right, T top, T bottom) const

Takes a rectangle in the screen space (i.e., -1 <= left <= right <= 1 and -1 <= bottom <= top <= 1) of this Frustum, and returns a new Frustum whose near clipping-plane window is that rectangle in local space.

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.