frustum.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_BASE_GF_FRUSTUM_H
#define PXR_BASE_GF_FRUSTUM_H
 
 
#include "pxr/pxr.h"
#include "pxr/base/gf/bbox3d.h"
#include "pxr/base/gf/matrix4d.h"
#include "pxr/base/gf/plane.h"
#include "pxr/base/gf/ray.h"
#include "pxr/base/gf/range1d.h"
#include "pxr/base/gf/range2d.h"
#include "pxr/base/gf/rotation.h"
#include "pxr/base/gf/vec2d.h"
#include "pxr/base/gf/vec3d.h"
#include "pxr/base/gf/api.h"
#include "pxr/base/tf/hash.h"
 
#include <array>
#include <atomic>
#include <iosfwd>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class GfFrustum {
  public:
    enum ProjectionType {
        Orthographic,                   
        Perspective,                    
    };
 
    using FrustumPlanes = std::array<GfPlane, 6>;
 
    GF_API GfFrustum();
 
    GfFrustum(GfFrustum const &o)
        : _position(o._position)
        , _rotation(o._rotation)
        , _window(o._window)
        , _nearFar(o._nearFar)
        , _viewDistance(o._viewDistance)
        , _projectionType(o._projectionType)
        , _planes(nullptr) {
        if (auto *planes = o._planes.load()) {
            _planes = new FrustumPlanes(*planes);
        }
    }
 
    GfFrustum(GfFrustum &&o) noexcept
        : _position(o._position)
        , _rotation(o._rotation)
        , _window(o._window)
        , _nearFar(o._nearFar)
        , _viewDistance(o._viewDistance)
        , _projectionType(o._projectionType)
        , _planes(nullptr) {
        if (auto *planes =
            o._planes.exchange(nullptr, std::memory_order_relaxed)) {
            _planes = planes;
        }
    }
 
    GF_API GfFrustum(const GfVec3d &position, const GfRotation &rotation,
              const GfRange2d &window, const GfRange1d &nearFar,
              GfFrustum::ProjectionType projectionType,
              double viewDistance = 5.0);
 
    GF_API GfFrustum(const GfMatrix4d &camToWorldXf,
              const GfRange2d &window, const GfRange1d &nearFar,
              GfFrustum::ProjectionType projectionType,
              double viewDistance = 5.0);
 
    GfFrustum &operator=(GfFrustum const &o) noexcept {
        if (this == &o) {
            return *this;
        }
        _position = o._position;
        _rotation = o._rotation;
        _window = o._window;
        _nearFar = o._nearFar;
        _viewDistance = o._viewDistance;
        _projectionType = o._projectionType;
        delete _planes.load(std::memory_order_relaxed);
        if (auto *planes = o._planes.load(std::memory_order_relaxed)) {
            _planes.store(new FrustumPlanes(*planes),
                          std::memory_order_relaxed);
        }
        else {
            _planes.store(nullptr, std::memory_order_relaxed);
        }
        return *this;
    }
 
    GfFrustum &operator=(GfFrustum &&o) noexcept {
        if (this == &o) {
            return *this;
        }
        _position = o._position;
        _rotation = o._rotation;
        _window = o._window;
        _nearFar = o._nearFar;
        _viewDistance = o._viewDistance;
        _projectionType = o._projectionType;
        delete _planes.load(std::memory_order_relaxed);
        _planes.store(o._planes.load(std::memory_order_relaxed),
                      std::memory_order_relaxed);
        o._planes.store(nullptr, std::memory_order_relaxed);
        return *this;
    }        
 
    friend inline size_t hash_value(const GfFrustum &f) {
        return TfHash::Combine(
            f._position,
            f._rotation,
            f._window,
            f._nearFar,
            f._viewDistance,
            f._projectionType
        );
    }
 
    // Equality operator. true iff all parts match.
    bool operator ==(const GfFrustum& f) const {
        if (_position       != f._position)        return false;
        if (_rotation       != f._rotation)        return false;
        if (_window         != f._window)          return false;
        if (_nearFar        != f._nearFar)         return false;
        if (_viewDistance   != f._viewDistance)    return false;
        if (_projectionType != f._projectionType)  return false;
 
        return true;
    }
 
    // Inequality operator. true iff not equality.
    bool operator !=(const GfFrustum& f) const {
        return !(*this == f);
    }
 
    GF_API ~GfFrustum();
 
 
    void                SetPosition(const GfVec3d &position) {
        _position = position;
        _DirtyFrustumPlanes();
    }
 
    const GfVec3d &     GetPosition() const {
        return _position;
    }
 
    void                SetRotation(const GfRotation &rotation) {
        _rotation = rotation;
        _DirtyFrustumPlanes();
    }
 
    const GfRotation &  GetRotation() const {
        return _rotation;
    }
 
    GF_API void SetPositionAndRotationFromMatrix(const GfMatrix4d &camToWorldXf);
 
    void                SetWindow(const GfRange2d &window)  {
        _window = window;
        _DirtyFrustumPlanes();
    }
 
    const GfRange2d &   GetWindow() const {
        return _window;
    }
 
    static double GetReferencePlaneDepth() {
        return 1.0;
    }
 
    void                SetNearFar(const GfRange1d &nearFar) {
        _nearFar = nearFar;
        _DirtyFrustumPlanes();
    }
 
    const GfRange1d &   GetNearFar() const {
        return _nearFar;
    }
 
    void                SetViewDistance(double viewDistance) {
        _viewDistance = viewDistance;
    }
 
    double              GetViewDistance() const {
        return _viewDistance;
    }
 
    void        SetProjectionType(GfFrustum::ProjectionType projectionType) {
        _projectionType = projectionType;
        _DirtyFrustumPlanes();
    }
 
    GfFrustum::ProjectionType   GetProjectionType() const {
        return _projectionType;
    }
 
 
 
    GF_API void         SetPerspective(double fieldOfViewHeight,
                                       double aspectRatio,
                                       double nearDistance, double farDistance);
 
    GF_API void         SetPerspective(double fieldOfView,
                                       bool   isFovVertical,
                                       double aspectRatio,
                                       double nearDistance, double farDistance);
 
    GF_API bool         GetPerspective(double *fieldOfViewHeight,
                                       double *aspectRatio,
                                       double *nearDistance,
                                       double *farDistance) const;
 
    GF_API bool         GetPerspective(bool   isFovVertical,
                                       double *fieldOfView,
                                       double *aspectRatio,
                                       double *nearDistance,
                                       double *farDistance) const;
 
    GF_API double       GetFOV(bool isFovVertical = false) const;
 
    GF_API
    void                SetOrthographic(double left, double right,
                                        double bottom, double top,
                                        double nearPlane, double farPlane);
 
    GF_API bool         GetOrthographic(double *left, double *right,
                                        double *bottom, double *top,
                                        double *nearPlane, double *farPlane)
                                        const;
 
    GF_API void         FitToSphere(const GfVec3d &center, 
                                    double radius,
                                    double slack = 0.0);
 
    GF_API GfFrustum&   Transform(const GfMatrix4d &matrix);
 
    GF_API GfVec3d      ComputeViewDirection() const;
 
    GF_API GfVec3d      ComputeUpVector() const;
 
    GF_API void         ComputeViewFrame(GfVec3d *side, 
                                         GfVec3d *up, 
                                         GfVec3d *view) const;
 
    GF_API GfVec3d      ComputeLookAtPoint() const;
 
    GF_API GfMatrix4d   ComputeViewMatrix() const;
 
    GF_API GfMatrix4d   ComputeViewInverse() const;
 
    GF_API GfMatrix4d   ComputeProjectionMatrix() const;
 
    GF_API double       ComputeAspectRatio() const;
 
    GF_API
    std::vector<GfVec3d> ComputeCorners() const;
 
    GF_API
    std::vector<GfVec3d> ComputeCornersAtDistance(double d) const;
 
    GF_API
    FrustumPlanes ComputePlanes() const;
 
    GF_API GfFrustum    ComputeNarrowedFrustum(const GfVec2d &windowPos,
                                               const GfVec2d &size) const;
 
    GF_API GfFrustum    ComputeNarrowedFrustum(const GfVec3d &worldPoint,
                                               const GfVec2d &size) const;
 
    GF_API GfRay        ComputeRay(const GfVec2d &windowPos) const;
 
    GF_API GfRay        ComputeRay(const GfVec3d &worldSpacePos) const;
 
    GF_API GfRay        ComputePickRay(const GfVec2d &windowPos) const;
 
    GF_API GfRay       ComputePickRay(const GfVec3d &worldSpacePos) const;
 
 
 
    GF_API bool         Intersects(const GfBBox3d &bbox) const;
 
    GF_API bool         Intersects(const GfVec3d &point) const;
 
    GF_API bool         Intersects(const GfVec3d &p0,
                                   const GfVec3d &p1) const;
 
    GF_API bool         Intersects(const GfVec3d &p0,
                                   const GfVec3d &p1,
                                   const GfVec3d &p2) const;
 
    GF_API static bool  IntersectsViewVolume(const GfBBox3d &bbox,
                                             const GfMatrix4d &vpMat);
 
 
  private:
    // Dirty the result of _CalculateFrustumPlanes.
    GF_API void _DirtyFrustumPlanes();
 
    // Calculates cached frustum planes used for intersection tests.
    GF_API void       _CalculateFrustumPlanes() const;
 
    // Builds and returns a \c GfRay that can be used for picking. Given an
    // eye position and direction in camera space, offsets the ray to emanate
    // from the near plane, then transforms into worldspace
    GF_API GfRay      _ComputePickRayOffsetToNearPlane(
                                    const GfVec3d &camSpaceFrom, 
                                    const GfVec3d &camSpaceDir) const;
 
    // Returns a frustum that is a narrowed-down version of this frustum. The
    // new frustum has the same near and far planes, but the other planes are
    // adjusted to be centered on \p windowPoint with the new width and height
    // obtained from the existing width and height by multiplying by \p size[0]
    // and \p size[1], respectively.  Finally, the new frustum is clipped
    // against this frustum so that it is completely contained in the existing
    // frustum.
    //
    // \p windowPoint is given in window coordinates.
    // \p size is given as a scalar (0 to 1 in both dimensions).
    //
    // If the \p size given is outside this range, it may result in returning
    // a collapsed frustum.
    //
    // This method is useful for computing a volume to use for interactive
    // picking.
    GfFrustum           _ComputeNarrowedFrustumSub(const GfVec2d windowPoint, 
                                    const GfVec2d &size) const;
 
    bool _SegmentIntersects(GfVec3d const &p0, uint32_t p0Mask,
                            GfVec3d const &p1, uint32_t p1Mask) const;
 
    // Position of the frustum in world space.
    GfVec3d                     _position;
 
    // Orientation of the frustum in world space as a rotation to apply to the
    // -z axis.
    GfRotation                  _rotation;
 
    // Window rectangle in the image plane.
    GfRange2d                   _window;
 
    // Near/far interval.
    GfRange1d                   _nearFar;
 
    // View distance.
    double                      _viewDistance;
 
    // Projection type.
    ProjectionType              _projectionType;
 
    // Cached planes.
    // If null, the planes have not been calculated.
    mutable std::atomic<FrustumPlanes *> _planes;
};
 
GF_API std::ostream& operator<<(std::ostream& out, const GfFrustum& f);
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif // PXR_BASE_GF_FRUSTUM_H