types.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_TYPES_H
#define PXR_BASE_TS_TYPES_H
 
#include "pxr/pxr.h"
#include "pxr/base/ts/api.h"
 
#include "pxr/base/gf/duration.h"
#include "pxr/base/gf/interval.h"
#include "pxr/base/gf/timeCode.h"
#include "pxr/base/gf/vec2d.h"
#include "pxr/base/tf/preprocessorUtilsLite.h"
 
#include <cstdint>
#include <optional>
#include <vector>
 
PXR_NAMESPACE_OPEN_SCOPE
 
#define TS_SPLINE_SUPPORTED_VALUE_TYPES         \
    ((Double,   double))                        \
    ((Float,    float))                         \
    ((Half,     GfHalf))                        \
    ((TimeCode, GfTimeCode))                    \
    ((Duration, GfDuration))
 
#define TS_SPLINE_STORAGE_VALUE_TYPES           \
    ((Double,   double))                        \
    ((Float,    float))                         \
    ((Half,     GfHalf))
 
#define TS_SPLINE_SAMPLE_VERTEX_TYPES \
    ((Vec2d,    GfVec2d))                       \
    ((Vec2f,    GfVec2f))                       \
    ((Vec2h,    GfVec2h))
 
#define TS_SPLINE_VALUE_TYPE_NAME(x) TF_PP_TUPLE_ELEM(0, x)
#define TS_SPLINE_VALUE_CPP_TYPE(x) TF_PP_TUPLE_ELEM(1, x)
 
template <class T>
inline constexpr bool
TsSplineIsValidDataType = false;
 
#define _TS_SUPPORT_DATA_TYPE(unused, tuple)                            \
    template <>                                                         \
    inline constexpr bool                                               \
    TsSplineIsValidDataType< TS_SPLINE_VALUE_CPP_TYPE(tuple) > = true;
TF_PP_SEQ_FOR_EACH(_TS_SUPPORT_DATA_TYPE,
                   ~,
                   TS_SPLINE_SUPPORTED_VALUE_TYPES)
#undef _TS_SUPPORT_DATA_TYPE
 
template <class T>
inline constexpr bool
TsSplineIsValidSampleType = false;
 
#define _TS_SUPPORT_SAMPLE_TYPE(unused, tuple)                          \
    template <>                                                         \
    inline constexpr bool                                               \
    TsSplineIsValidSampleType< TS_SPLINE_VALUE_CPP_TYPE(tuple) > = true;
TF_PP_SEQ_FOR_EACH(_TS_SUPPORT_SAMPLE_TYPE,
                   ~,
                   TS_SPLINE_SAMPLE_VERTEX_TYPES)
#undef _TS_SUPPORT_SAMPLE_TYPE
 
// Times are encoded as double.
using TsTime = double;
 
// ** NOTE TO MAINTAINERS **
//
// The following enum values are used in the binary crate format.
// Do not change them; only add.
 
enum TsInterpMode
{
    TsInterpValueBlock  = 0,  //< No value in this segment.
    TsInterpHeld        = 1,  //< Constant value in this segment.
    TsInterpLinear      = 2,  //< Linear interpolation.
    TsInterpCurve       = 3   //< Bezier or Hermite, depends on curve type.
};
 
enum TsCurveType
{
    TsCurveTypeBezier  = 0,  //< Bezier curve, free tangent widths.
    TsCurveTypeHermite = 1   //< Hermite curve, like Bezier but fixed tan width.
};
 
enum TsExtrapMode
{
    TsExtrapValueBlock    = 0, //< No value in this region.
    TsExtrapHeld          = 1, //< Constant value in this region.
    TsExtrapLinear        = 2, //< Linear interpolation based on edge knots.
    TsExtrapSloped        = 3, //< Linear interpolation with specified slope.
    TsExtrapLoopRepeat    = 4, //< Knot curve repeated, offset so ends meet.
    TsExtrapLoopReset     = 5, //< Curve repeated exactly, discontinuous joins.
    TsExtrapLoopOscillate = 6  //< Like Reset, but every other copy reversed.
};
 
enum TsSplineSampleSource
{
    TsSourcePreExtrap,          //< Extrapolation before the first knot
    TsSourcePreExtrapLoop,      //< Looped extrapolation before the first knot
    TsSourceInnerLoopPreEcho,   //< Echoed copy of an inner loop prototype
    TsSourceInnerLoopProto,     //< This is the inner loop prototype
    TsSourceInnerLoopPostEcho,  //< Echoed copy of an inner loop prototype
    TsSourceKnotInterp,         //< "Normal" knot interpolation
    TsSourcePostExtrap,         //< Extrapolation after the last knot
    TsSourcePostExtrapLoop,     //< Looped extrapolation after the last knot
};
 
enum TsTangentAlgorithm
{
    TsTangentAlgorithmNone,
    TsTangentAlgorithmCustom,
    TsTangentAlgorithmAutoEase
};
 
#if !defined(doxygen)
// TsLoopParams is deprecated. Declare an non-deprecated replacement
// we can use internally to avoid compiler warnings when building
// our own code.
class Ts_LoopParams;
using TsLoopParams [[deprecated("TsSpline inner looping is deprecated")]] =
    Ts_LoopParams;
#endif
 
#if defined(doxygen)
class TsLoopParams
#else
class Ts_LoopParams
#endif // doxygen
{
public:
    TsTime protoStart = 0.0;
    TsTime protoEnd = 0.0;
    int32_t numPreLoops = 0;
    int32_t numPostLoops = 0;
    double valueOffset = 0.0;
 
public:
    TS_API
    bool operator==(const Ts_LoopParams &other) const;
 
    TS_API
    bool operator!=(const Ts_LoopParams &other) const;
 
    TS_API
    GfInterval GetPrototypeInterval() const;
 
    TS_API
    GfInterval GetLoopedInterval() const;
};
 
class TsExtrapolation
{
public:
    TsExtrapMode mode = TsExtrapHeld;
 
    // Used only in TsExtrapSloped mode. Specifies slope of the extrapolated
    // segment.
    double slope = 0.0;
 
    // Used only in looping extrapolation modes to optionally specify a
    // subsection of the spline.
    //
    // This setting is incompatible with inner looping. Attempts to set
    // extrapolation with a non-null loopBoundaryTime on a spline with inner
    // looping, and vice versa, will cause a TF_CODING_ERROR to be issued.
    //
    // When this has no value, this extrapolation loops the full knot region.
    //
    // When this has a value that is exactly a knot time,
    // this extrapolation loops the knot subregion demarcated by
    // loopBoundaryTime and the knot subregion's start for post-extrapolation
    // or end for pre-extrapolation.
    // 
    // There are a few degenerate cases.
    // - This has a value that isn't exactly a knot time. The resulting
    //   extrapolation is value block.
    // - This has a value that is the start knot time for pre-extrapolation,
    //   or end knot time for post-extrapolation. The resulting extrapolation
    //   is held, and has the same behavior as TsExtrapHeld.
    std::optional<double> loopBoundaryTime;
 
public:
    TS_API
    TsExtrapolation();
 
    TS_API
    TsExtrapolation(TsExtrapMode mode);
 
    TS_API
    TsExtrapolation(TsExtrapMode mode, double slope);
 
    TS_API
    bool operator==(const TsExtrapolation &other) const;
 
    TS_API
    bool operator!=(const TsExtrapolation &other) const;
 
    TS_API
    bool IsLooping() const;
};
 
template <typename Vertex>
class TsSplineSamples
{
public:
    static_assert(TsSplineIsValidSampleType<Vertex>,
                  "The Vertex template parameter to TsSplineSamples must be one"
                  " of GfVec2d, GfVec2f, or GfVec2h.");
 
    using Polyline = std::vector<Vertex>;
 
    std::vector<Polyline> polylines;
};
 
template <typename Vertex>
class TsSplineSamplesWithSources
{
public:
    static_assert(TsSplineIsValidSampleType<Vertex>,
                  "The Vertex template parameter to TsSplineSamplesWithSources"
                  " must be one of GfVec2d, GfVec2f, or GfVec2h.");
 
    using Polyline = std::vector<Vertex>;
 
    std::vector<Polyline> polylines;
    std::vector<TsSplineSampleSource> sources;
};
 
enum TsAntiRegressionMode
{
    TsAntiRegressionNone,
 
    TsAntiRegressionContain,
 
    TsAntiRegressionKeepRatio,
 
    TsAntiRegressionKeepStart
};
 
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif