spline.h

//
// Copyright 2024 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
 
#ifndef PXR_BASE_TS_SPLINE_H
#define PXR_BASE_TS_SPLINE_H
 
#include "pxr/pxr.h"
#include "pxr/base/ts/api.h"
#include "pxr/base/ts/splineData.h"
#include "pxr/base/ts/knotMap.h"
#include "pxr/base/ts/knot.h"
#include "pxr/base/ts/types.h"
#include "pxr/base/ts/typeHelpers.h"
#include "pxr/base/ts/eval.h"
#include "pxr/base/vt/traits.h"
#include "pxr/base/vt/value.h"
#include "pxr/base/gf/interval.h"
#include "pxr/base/tf/type.h"
 
#include <string>
#include <memory>
#include <iosfwd>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class VtDictionary;
 
 
class TsSpline
{
public:
 
    TS_API
    TsSpline();
 
    TS_API
    TsSpline(TfType valueType);
 
    TS_API
    TsSpline(const TsSpline &other);
 
    TS_API
    TsSpline& operator=(const TsSpline &other);
 
    TS_API
    bool operator==(const TsSpline &other) const;
 
    TS_API
    bool operator!=(const TsSpline &other) const;
 
 
    TS_API
    static bool IsSupportedValueType(TfType valueType);
 
    TS_API
    TfType GetValueType() const;
 
    template <typename T>
    bool IsHolding() const;
 
    TS_API
    void SetTimeValued(bool timeValued);
 
    TS_API
    bool IsTimeValued() const;
 
 
    TS_API
    void SetCurveType(TsCurveType curveType);
 
    TS_API
    TsCurveType GetCurveType() const;
 
 
    TS_API
    void SetPreExtrapolation(
        const TsExtrapolation &extrap);
 
    TS_API
    TsExtrapolation GetPreExtrapolation() const;
 
    TS_API
    void SetPostExtrapolation(
        const TsExtrapolation &extrap);
 
    TS_API
    TsExtrapolation GetPostExtrapolation() const;
 
    // Returns whether pre extrapolation is valid.
    //
    // Pre extrapolation is invalid if it is looping and loopBoundaryTime
    // is set to a value for which the spline does not have an associated
    // knot time.
    //
    // Invalid extrapolation regions evaluate to value-block.
    TS_API
    bool IsPreExtrapolationValid() const;
 
    // Returns whether post extrapolation is valid.
    //
    // Post extrapolation is invalid if it is looping and loopBoundaryTime
    // is set to a value for which the spline does not have an associated
    // knot time.
    //
    // Invalid extrapolation regions evaluate to value-block.
    TS_API
    bool IsPostExtrapolationValid() const;
 
 
    TS_API
    void SetInnerLoopParams(
        const TsLoopParams &params);
 
    TS_API
    TsLoopParams GetInnerLoopParams() const;
 
 
    TS_API
    void SetKnots(
        const TsKnotMap &knots);
 
    TS_API
    bool CanSetKnot(
        const TsKnot &knot,
        std::string *reasonOut = nullptr) const;
 
    TS_API
    bool SetKnot(
        const TsKnot &knot,
        GfInterval *affectedIntervalOut = nullptr);
 
    TS_API
    TsKnotMap GetKnots() const;
 
    TS_API
    TsKnotMap GetKnots(const GfInterval& timeInterval) const;
 
    TS_API
    bool GetKnot(
        TsTime time,
        TsKnot *knotOut) const;
 
 
    TS_API
    void ClearKnots();
 
    TS_API
    void RemoveKnot(
        TsTime time,
        GfInterval *affectedIntervalOut = nullptr);
 
    TS_API
    bool ClearRedundantKnots(
        VtValue defaultValue = VtValue(),
        const GfInterval &interval = GfInterval::GetFullInterval());
 
 
    TS_API
    bool BakeInnerLoops();
 
    TS_API
    TsKnotMap GetKnotsWithInnerLoopsBaked() const;
 
 
    TS_API
    TsKnotMap GetKnotsWithLoopsBaked(
        const GfInterval &interval) const;
 
 
    TS_API
    bool Breakdown(
        TsTime time,
        GfInterval *affectedIntervalOut = nullptr);
 
    TS_API
    bool CanBreakdown(
        TsTime time,
        std::string* reason = nullptr);
 
 
    TS_API
    static TsAntiRegressionMode GetAntiRegressionAuthoringMode();
 
    TS_API
    bool HasRegressiveTangents() const;
 
    TS_API
    bool AdjustRegressiveTangents();
 
 
    template <typename T>
    bool Eval(
        TsTime time,
        T *valueOut) const;
 
    template <typename T>
    bool EvalPreValue(
        TsTime time,
        T *valueOut) const;
 
    template <typename T>
    bool EvalDerivative(
        TsTime time,
        T *valueOut) const;
 
    template <typename T>
    bool EvalPreDerivative(
        TsTime time,
        T *valueOut) const;
 
    template <typename T>
    bool EvalHeld(
        TsTime time,
        T *valueOut) const;
 
    template <typename T>
    bool EvalPreValueHeld(
        TsTime time,
        T *valueOut) const;
 
    TS_API
    bool DoSidesDiffer(
        TsTime time) const;
 
    template <typename Vertex>
    bool
    Sample(
        const GfInterval& timeInterval,
        double timeScale,
        double valueScale,
        double tolerance,
        TsSplineSamples<Vertex>* splineSamples) const
    {
        return _Sample(timeInterval, timeScale, valueScale, tolerance,
                       splineSamples);
    }
 
    template <typename Vertex>
    bool
    Sample(
        const GfInterval& timeInterval,
        double timeScale,
        double valueScale,
        double tolerance,
        TsSplineSamplesWithSources<Vertex>* splineSamples) const
    {
        return _Sample(timeInterval, timeScale, valueScale, tolerance,
                       splineSamples);
    }
 
 
 
    TS_API
    TsSpline GetTruncated(
        const GfInterval& interval,
        TsExtrapolation preFallback = TsExtrapolation(TsExtrapValueBlock),
        TsExtrapolation postFallback = TsExtrapolation(TsExtrapValueBlock)
    ) const;
 
 
 
 
    TS_API
    GfInterval Diff(const TsSpline& other) const;
 
    TS_API
    GfInterval Diff(const TsSpline& other,
                    const GfInterval& compareInterval) const;
 
 
    TS_API
    bool IsEmpty() const;
 
    TS_API
    bool HasValueBlocks() const;
 
    TS_API
    bool IsVarying() const;
 
    TS_API
    bool HasLoops() const;
 
    TS_API
    bool HasInnerLoops() const;
 
    TS_API
    bool HasExtrapolatingLoops() const;
 
    TS_API
    bool IsLinear() const;
 
    TS_API
    bool IsC0Continuous() const;
 
    TS_API
    bool IsG1Continuous() const;
 
    TS_API
    bool IsC1Continuous() const;
 
    TS_API
    bool GetValueRange(
        const GfInterval &timeSpan,
        std::pair<VtValue, VtValue> *rangeOut) const;
 
    template <typename T>
    bool GetValueRange(
        const GfInterval &timeSpan,
        std::pair<T, T> *rangeOut) const;
 
 
    TS_API
    bool HasValueBlockAtTime(
        TsTime time) const;
 
    TS_API
    bool IsSegmentFlat(
        TsTime startTime) const;
 
    TS_API
    bool IsSegmentMonotonic(
        TsTime startTime) const;
 
    TS_API
    bool IsKnotRedundant(
        TsTime time,
        VtValue defaultValue = VtValue()) const;
 
 
public:
    // Hash function.  For now this is cheap, and only hashes by data pointer.
    // If there are two identical but independent splines, they will hash
    // unequal.
    template <typename HashState>
    friend void TfHashAppend(
        HashState &h,
        const TsSpline &spline)
    {
        h.Append(spline._data.get());
    }
 
private:
    friend class TsRegressionPreventer;
 
    // Direct access method used by TsRegressionPreventer.
    void _SetKnotUnchecked(const TsKnot & knot);
 
    template <typename SampleHolder>
    bool _Sample(
        const GfInterval& timeInterval,
        double timeScale,
        double valueScale,
        double tolerance,
        SampleHolder* splineSamples) const;
 
    // External helpers provide direct data access for Ts implementation.
    friend Ts_SplineData* Ts_GetSplineData(TsSpline &spline);
    friend const Ts_SplineData* Ts_GetSplineData(const TsSpline &spline);
 
    friend struct Ts_BinaryDataAccess;
    friend struct Ts_SplineOffsetAccess;
 
private:
    // TsSpline takes ownership of `data`. The caller should not retain or
    // delete `data` after this constructor is called.
    TS_API
    TsSpline(Ts_SplineData* data);
 
    // Get data to read from.  Will be either actual data or default data.
    TS_API
    const Ts_SplineData* _GetData() const;
 
    // Ensure we have our own independent data, in preparation for writing.  If
    // a value type is passed, and we don't yet have typed data, ensure we have
    // data of the specified type.
    void _PrepareForWrite(TfType valueType = TfType());
 
    template <typename T>
    bool _Eval(
        TsTime time,
        T *valueOut,
        Ts_EvalAspect aspect,
        Ts_EvalLocation location) const;
 
    // Update all the tangents based on the tangent algorithms in the knots and
    // follow that with a call to AdjustRegressiveTangents() to remove any
    // remaining regressive spline segments.  Return true if any changes were
    // made.
    TS_API
    bool _UpdateAllTangents();
 
    // Update the tangents of a single knot based on its tangent algorithms and
    // the regression prevention settings.
    TS_API
    bool _UpdateKnotTangents(const size_t knotIndex);
 
private:
    // Our parameter data.  Copy-on-write.  Null only if we are in the default
    // state, with no knots, and all overall parameters set to defaults.  To
    // deal with the possibility of null data, call _GetData for reading, and
    // _PrepareForWrite before writing.
    std::shared_ptr<Ts_SplineData> _data;
};
 
// TsSpline supports value transforms.
VT_VALUE_TYPE_CAN_TRANSFORM(TsSpline);
 
TS_API
std::ostream& operator<<(std::ostream& out, const TsSpline &spline);
 
// XXX: This should not be necessary.  All it does is call std::swap.  This is
// here as a workaround for a downstream library that tries to call swap on
// splines, with a "using namespace std" that doesn't appear to work when pxr
// namespaces are in use.
TS_API
void swap(TsSpline &lhs, TsSpline &rhs);
 
// For applying layer offsets.
struct Ts_SplineOffsetAccess
{
    TS_API
    static void ApplyOffsetAndScale(
        TsSpline *spline,
        const TsTime offset,
        const double scale);
};
 
 
// TEMPLATE IMPLEMENTATIONS
 
template <typename T>
bool TsSpline::IsHolding() const
{
    if constexpr (!Ts_IsSupportedValueType<T>::value)
    {
        return false;
    }
 
    return GetValueType() == Ts_GetType<T>();
}
 
template <typename T>
bool TsSpline::_Eval(
    const TsTime time,
    T* const valueOut,
    const Ts_EvalAspect aspect,
    const Ts_EvalLocation location) const
{
    const std::optional<double> result =
        Ts_Eval(_GetData(), time, aspect, location);
 
    if (!result)
    {
        return false;
    }
 
    *valueOut = T(*result);
    return true;
}
 
// Implement a special case that will ensure the contents of the VtValue output
// variable contain a value of the same type (double, float, or GfHalf) as the
// spline.
template <>
TS_API
bool TsSpline::_Eval(
    const TsTime time,
    VtValue* const valueOut,
    const Ts_EvalAspect aspect,
    const Ts_EvalLocation location) const;
 
template <typename T>
bool TsSpline::Eval(const TsTime time, T* const valueOut) const
{
    return _Eval(time, valueOut, Ts_EvalValue, Ts_EvalAtTime);
}
 
template <typename T>
bool TsSpline::EvalPreValue(const TsTime time, T* const valueOut) const
{
    return _Eval(time, valueOut, Ts_EvalValue, Ts_EvalPre);
}
 
template <typename T>
bool TsSpline::EvalDerivative(const TsTime time, T* const valueOut) const
{
    return _Eval(time, valueOut, Ts_EvalDerivative, Ts_EvalAtTime);
}
 
template <typename T>
bool TsSpline::EvalPreDerivative(const TsTime time, T* const valueOut) const
{
    return _Eval(time, valueOut, Ts_EvalDerivative, Ts_EvalPre);
}
 
template <typename T>
bool TsSpline::EvalHeld(const TsTime time, T* const valueOut) const
{
    return _Eval(time, valueOut, Ts_EvalHeldValue, Ts_EvalAtTime);
}
 
template <typename T>
bool TsSpline::EvalPreValueHeld(const TsTime time, T* const valueOut) const
{
    return _Eval(time, valueOut, Ts_EvalHeldValue, Ts_EvalPre);
}
 
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif