Imath
<navlinks>
<page>

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

  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 const Frustum &operator=(const Frustum&) noexcept

    Component-wise assignment.

  Comparison

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

    Equality.

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

    Inequality.

  Query

  inline bool orthographic() const noexcept

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

  inline T nearPlane() const noexcept

    Return the near clipping plane.

  inline T hither() const noexcept

    Return the near clipping plane.

  inline T farPlane() const noexcept

    Return the far clipping plane.

  inline T yon() const noexcept

    Return the far clipping plane.

  inline T left() const noexcept

    Return the left of the frustum.

  inline T right() const noexcept

    Return the right of the frustum.

  inline T bottom() const noexcept

    Return the bottom of the frustum.

  inline T top() const noexcept

    Return the top of the frustum.

  inline T fovx() const noexcept

    Return the field of view in X.

  inline T fovy() const noexcept

    Return the field of view in Y.

  inline T aspect() const noexcept

    Return the aspect ratio.

  inline T aspectExc() const

    Return the aspect ratio.

    Throw an exception if the aspect ratio is undefined.

  inline Matrix44<T> projectionMatrix() const noexcept

    Return the project matrix that the frustum defines.

  inline Matrix44<T> projectionMatrixExc() const

    Return the project matrix that the frustum defines.

    Throw an exception if the frustum is degenerate.

  inline 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 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 Line3<T> projectScreenToRay(const Vec2<T>&) const noexcept

    Project a point in screen spaced to 3d ray.

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

    Project a 3D point into screen coordinates.

  Vec2<T> projectPointToScreenExc(const Vec3<T>&) const

    Project a 3D point into screen coordinates.

    Throw an exception if the point cannot be projected.

  T ZToDepth(long zval, long min, long max) const noexcept

    Map a z value to its depth in the frustum.

  T ZToDepthExc(long zval, long min, long max) const

    Map a z value to its depth in the frustum.

  T normalizedZToDepth(T zval) const noexcept

    Map a normalized z value to its depth in the frustum.

  T normalizedZToDepthExc(T zval) const

    Map a normalized z value to its depth in the frustum.

    Throw an exception on error.

  long DepthToZ(T depth, long zmin, long zmax) const noexcept

    Map depth to z value.

  long DepthToZExc(T depth, long zmin, long zmax) const

    Map depth to z value. Throw an exception on error.

  T worldRadius(const Vec3<T> &p, T radius) const noexcept

    Compute worldRadius.

  T worldRadiusExc(const Vec3<T> &p, T radius) const

    Compute worldRadius. Throw an exception on error.

  T screenRadius(const Vec3<T> &p, T radius) const noexcept

    Compute screen radius.

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

    Compute screen radius. Throw an exception on error.

</page>