keyFrame.h

//
// Copyright 2023 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
 
#ifndef PXR_BASE_TS_KEY_FRAME_H
#define PXR_BASE_TS_KEY_FRAME_H
 
#include "pxr/pxr.h"
#include "pxr/base/ts/api.h"
#include "pxr/base/arch/demangle.h"
#include "pxr/base/ts/types.h"
#include "pxr/base/ts/data.h"
#include "pxr/base/vt/value.h"
#include "pxr/base/vt/traits.h"
#include "pxr/base/tf/diagnostic.h"
#include "pxr/base/tf/stringUtils.h"
 
#include <iosfwd>
#include <typeinfo>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class TsSpline;
 
class TsKeyFrame final
{
public: // methods
 
    TS_API
    TsKeyFrame();
 
    
    template <typename T>
    TsKeyFrame( const TsTime & time,
                  const T & val,
                  TsKnotType knotType = TsKnotLinear,
                  const T & leftTangentSlope = TsTraits<T>::zero,
                  const T & rightTangentSlope = TsTraits<T>::zero,
                  TsTime leftTangentLength = 0,
                  TsTime rightTangentLength = 0);
 
    TS_API
    TsKeyFrame( const TsTime & time,
                  const VtValue & val,
                  TsKnotType knotType = TsKnotLinear,
                  const VtValue & leftTangentSlope = VtValue(),
                  const VtValue & rightTangentSlope = VtValue(),
                  TsTime leftTangentLength = 0,
                  TsTime rightTangentLength = 0);
 
    template <typename T>
    TsKeyFrame( const TsTime & time,
                  const T & lhv,
                  const T & rhv,
                  TsKnotType knotType = TsKnotLinear,
                  const T & leftTangentSlope = TsTraits<T>::zero,
                  const T & rightTangentSlope = TsTraits<T>::zero,
                  TsTime leftTangentLength = 0,
                  TsTime rightTangentLength = 0);
 
    TS_API
    TsKeyFrame( const TsTime & time,
                  const VtValue & lhv,
                  const VtValue & rhv,
                  TsKnotType knotType = TsKnotLinear,
                  const VtValue & leftTangentSlope = VtValue(),
                  const VtValue & rightTangentSlope = VtValue(),
                  TsTime leftTangentLength = 0,
                  TsTime rightTangentLength = 0);
 
    TS_API
    TsKeyFrame( const TsKeyFrame & kf );
 
 
    TS_API
    ~TsKeyFrame();
 
 
    TS_API
    TsKeyFrame & operator=(const TsKeyFrame &rhs);
 
    TS_API
    bool operator==(const TsKeyFrame &) const;
 
    TS_API
    bool operator!=(const TsKeyFrame &) const;
 
    TS_API
    bool IsEquivalentAtSide(const TsKeyFrame &keyFrame, TsSide side) const;
 
    TS_API
    TsTime GetTime() const {
        return _holder.Get()->GetTime();
    }
 
    TS_API
    void SetTime( const TsTime & newTime ) {
        _holder.GetMutable()->SetTime(newTime);
    }
 
    TS_API
    VtValue GetValue() const;
 
    TS_API
    void SetValue( VtValue val );
 
    TS_API
    VtValue GetValue( TsSide side ) const;
 
    TS_API
    void SetValue( VtValue val, TsSide side );
 
    TS_API
    VtValue GetValueDerivative() const;
 
    TS_API
    VtValue GetZero() const;
 
    TS_API
    TsKnotType GetKnotType() const;
 
    TS_API
    void SetKnotType( TsKnotType knotType );
 
    TS_API
    bool CanSetKnotType( TsKnotType, std::string *reason=NULL ) const;
 
 
 
    TS_API
    bool GetIsDualValued() const;
 
    TS_API
    void SetIsDualValued( bool isDual );
 
    TS_API
    VtValue GetLeftValue() const;
 
    TS_API
    void SetLeftValue( VtValue val );
 
    TS_API
    VtValue GetLeftValueDerivative() const;
 
 
 
    TS_API
    bool IsInterpolatable() const;
 
    TS_API
    bool IsExtrapolatable() const;
 
    TS_API
    bool SupportsTangents() const;
 
    TS_API
    bool HasTangents() const;
 
    TS_API
    TsTime GetLeftTangentLength() const;
 
    TS_API
    VtValue GetLeftTangentSlope() const;
 
    TS_API
    TsTime GetRightTangentLength() const;
 
    TS_API
    VtValue GetRightTangentSlope() const;
 
    TS_API
    void SetLeftTangentLength( TsTime );
 
    TS_API
    void SetLeftTangentSlope( VtValue );
 
    TS_API
    void SetRightTangentLength( TsTime );
 
    TS_API
    void SetRightTangentSlope( VtValue newSlope);
 
    TS_API
    bool GetTangentSymmetryBroken() const;
 
    TS_API
    void SetTangentSymmetryBroken( bool broken );
 
    TS_API
    void ResetTangentSymmetryBroken();
 
private:
 
    // Give the rest of the library access to the Ts_Data object held
    // in this keyframe through the Ts_GetKeyFrameData function.
    friend Ts_Data* Ts_GetKeyFrameData(TsKeyFrame &kf);
    friend Ts_Data const* Ts_GetKeyFrameData(TsKeyFrame const& kf);
 
    // Shared initialization
    void _Initialize(
        const TsTime & time,
        TsKnotType knotType,
        const VtValue & leftTangentSlope,
        const VtValue & rightTangentSlope,
        TsTime leftTangentLength,
        TsTime rightTangentLength);
 
    // XXX: exported because called from inlined templated constructors
    TS_API
    void _InitializeKnotType(TsKnotType knotType);
    TS_API
    void _InitializeTangentLength(TsTime leftTangentLength,
        TsTime rightTangentLength);
 
    // Helper function which tests the setability of tangents for this knot,
    // and reports an error if tangents not supported
    bool _ValidateTangentSetting() const;
 
private:
 
    Ts_PolymorphicDataHolder _holder;
};
 
 
TS_API
std::ostream& operator<<(std::ostream &out, const TsKeyFrame &val);
 
template <typename T>
TsKeyFrame::TsKeyFrame( const TsTime & time,
                            const T & val,
                            TsKnotType knotType,
                            const T & leftTangentSlope,
                            const T & rightTangentSlope,
                            TsTime leftTangentLength,
                            TsTime rightTangentLength)
{
    static_assert( TsTraits<T>::isSupportedSplineValueType );
 
    _holder.New(time, false /*isDual*/,
        val, val, leftTangentSlope, rightTangentSlope);
 
    _InitializeKnotType(knotType);
    _InitializeTangentLength(leftTangentLength,rightTangentLength);
}
 
template <typename T>
TsKeyFrame::TsKeyFrame( const TsTime & time,
                            const T & lhv,
                            const T & rhv,
                            TsKnotType knotType,
                            const T & leftTangentSlope,
                            const T & rightTangentSlope,
                            TsTime leftTangentLength,
                            TsTime rightTangentLength)
{
    static_assert( TsTraits<T>::isSupportedSplineValueType );
 
    _holder.New(time, true /*isDual*/, lhv, rhv,
        leftTangentSlope, rightTangentSlope);
    
    _InitializeKnotType(knotType);
    _InitializeTangentLength(leftTangentLength,rightTangentLength);
}
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif