frustum.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache 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,                    
    };

    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 std::array<GfPlane, 6>(*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 std::array<GfPlane, 6>(*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);

    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 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<std::array<GfPlane, 6> *> _planes;
};

GF_API std::ostream& operator<<(std::ostream& out, const GfFrustum& f);

PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_BASE_GF_FRUSTUM_H