Frustum¶

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

Previous topic

Next topic

This Page

Frustum¶