Frustum

#include <Imath/ImathFrustum.h>

The Frustum class template represents a 3D viewing frustum, with predefined typedefs of type float and double.

Example:

#include <Imath/ImathFrustum.h>

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 Imath::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

inline constexpr Frustum() noexcept

Initialize with default values: near=0.1, far=1000.0, left=-1.0, right=1.0, top=1.0, bottom=-1.0, ortho=false.

inline constexpr Frustum(const Frustum&) noexcept

Copy constructor.

inline constexpr Frustum(T nearPlane, T farPlane, T left, T right, T top, T bottom, bool ortho = false) noexcept

Initialize to specific values.

inline constexpr Frustum(T nearPlane, T farPlane, T fovx, T fovy, T aspect) noexcept

Initialize with fov and aspect.

virtual ~Frustum() noexcept

Destructor.

inline constexpr const Frustum &operator=(const Frustum&) noexcept

Component-wise assignment.

Comparison

inline constexpr bool operator==(const Frustum<T> &src) const noexcept

Equality.

inline constexpr bool operator!=(const Frustum<T> &src) const noexcept

Inequality.

Query

inline constexpr bool orthographic() const noexcept

Return true if the frustum is orthographic, false if perspective.

inline constexpr T nearPlane() const noexcept

Return the near clipping plane.

inline constexpr T hither() const noexcept

Return the near clipping plane.

inline constexpr T farPlane() const noexcept

Return the far clipping plane.

inline constexpr T yon() const noexcept

Return the far clipping plane.

inline constexpr T left() const noexcept

Return the left of the frustum.

inline constexpr T right() const noexcept

Return the right of the frustum.

inline constexpr T bottom() const noexcept

Return the bottom of the frustum.

inline constexpr T top() const noexcept

Return the top of the frustum.

inline constexpr T fovx() const noexcept

Return the field of view in X.

inline constexpr T fovy() const noexcept

Return the field of view in Y.

inline constexpr T aspect() const noexcept

Return the aspect ratio.

inline constexpr T aspectExc() const

Return the aspect ratio.

Throw an exception if the aspect ratio is undefined.

inline constexpr Matrix44<T> projectionMatrix() const noexcept

Return the project matrix that the frustum defines.

inline constexpr Matrix44<T> projectionMatrixExc() const

Return the project matrix that the frustum defines.

Throw an exception if the frustum is degenerate.

inline constexpr bool degenerate() const noexcept

Return true if the frustum is degenerate.

Set Value

inline void set(T nearPlane, T farPlane, T left, T right, T top, T bottom, bool ortho = false) noexcept

Set functions change the entire state of the Frustum.

inline void set(T nearPlane, T farPlane, T fovx, T fovy, T aspect) noexcept

Set functions change the entire state of the Frustum using field of view and aspect ratio.

inline 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.

inline void modifyNearAndFar(T nearPlane, T farPlane) noexcept

Set the near and far clipping planes.

inline void setOrthographic(bool) noexcept

Set the ortographic state.

void planes(Plane3<T> p[6]) const noexcept

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 noexcept

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.

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

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

inline constexpr Line3<T> projectScreenToRay(const Vec2<T>&) const noexcept

Project a point in screen spaced to 3d ray.

constexpr Vec2<T> projectPointToScreen(const Vec3<T>&) const noexcept

Project a 3D point into screen coordinates.

constexpr Vec2<T> projectPointToScreenExc(const Vec3<T>&) 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 noexcept

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 noexcept

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 noexcept

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 noexcept

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 noexcept

Compute screen radius.

constexpr T screenRadiusExc(const Vec3<T> &p, T radius) const

Compute screen radius. Throw an exception on error.