regressionPreventer.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_REGRESSION_PREVENTER_H
#define PXR_BASE_TS_REGRESSION_PREVENTER_H
 
#include "pxr/pxr.h"
#include "pxr/base/ts/api.h"
#include "pxr/base/ts/types.h"
#include "pxr/base/ts/knot.h"
#include "pxr/base/ts/knotData.h"
#include "pxr/base/ts/segment.h"
 
#include <optional>
#include <string>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class TsSpline;
 
 
class TsRegressionPreventer
{
public:
    enum TS_API InteractiveMode
    {
        ModeLimitActive = 100,
 
        ModeLimitOpposite
    };
 
    class SetResult
    {
    public:
        bool adjusted = false;
 
        bool havePreSegment = false;
        bool preActiveAdjusted = false;
        TsTime preActiveAdjustedWidth = 0;
        bool preOppositeAdjusted = false;
        TsTime preOppositeAdjustedWidth = 0;
 
        bool havePostSegment = false;
        bool postActiveAdjusted = false;
        TsTime postActiveAdjustedWidth = 0;
        bool postOppositeAdjusted = false;
        TsTime postOppositeAdjustedWidth = 0;
 
    public:
        TS_API
        std::string GetDebugDescription(int precision = 6) const;
    };
 
public:
    TS_API
    TsRegressionPreventer(
        TsSpline *spline,
        TsTime activeKnotTime,
        bool limit = true);
 
    TS_API
    TsRegressionPreventer(
        TsSpline *spline,
        TsTime activeKnotTime,
        InteractiveMode mode,
        bool limit = true);
 
    TS_API
    bool Set(
        const TsKnot &proposedActiveKnot,
        SetResult *resultOut = nullptr);
 
private:
    friend struct Ts_RegressionPreventerBatchAccess;
 
    // Unified enum for both interactive and batch use.
    enum _Mode
    {
        _ModeNone = TsAntiRegressionNone,
        _ModeContain = TsAntiRegressionContain,
        _ModeKeepRatio = TsAntiRegressionKeepRatio,
        _ModeKeepStart = TsAntiRegressionKeepStart,
        _ModeLimitActive = ModeLimitActive,
        _ModeLimitOpposite = ModeLimitOpposite
    };
 
    // Private constructor to which the public constructors delegate.
    TsRegressionPreventer(
        TsSpline *spline,
        TsTime activeKnotTime,
        _Mode mode,
        bool limit);
 
    // PERFORMANCE NOTE: this class would probably be faster if it dealt
    // directly with Ts_SplineData and Ts_KnotData, rather than going through
    // TsSpline and TsKnot.
 
    // Knot state stored for the lifetime of an interactive Preventer.  Tracks
    // the original knot from construction time, and the current time parameters
    // in the spline.
    struct _KnotState
    {
    public:
        // Uses the original value for both 'original' and 'current'.
        _KnotState(
            TsSpline *spline,
            const TsKnot &originalKnot);
 
        // Write the original back to the spline, undoing any prior writes.
        void RestoreOriginal();
 
        // Remove the knot from the spline.  This is needed when knot time is
        // changing.
        void RemoveCurrent();
 
        // Write a new version of the knot, and record it as 'current'.
        void Write(
            const TsKnot &newKnot);
 
    public:
        // The spline, so we can write into it.
        TsSpline* const spline;
 
        // Original knot.
        const TsKnot originalKnot;
 
        // Current time parameters, possibly modified from original.
        Ts_KnotData currentParams;
    };
 
    // Knot state used for the duration of a single Preventer iteration (Set or
    // _ProcessSegment).  Tracks the proposed new knot, and a potentially
    // adjusted working version of the time parameters.
    struct _WorkingKnotState
    {
    public:
        // Uses the proposed value for 'proposed' and 'working'.  This is for
        // interactive use with active knots, for which a proposed new value is
        // given as input.
        _WorkingKnotState(
            _KnotState *parentState,
            const TsKnot &proposedKnot);
 
        // Uses the parent's original for 'proposed' and 'working'.  This is for
        // interactive use with opposite knots, which always start out proposed
        // as the original knots.
        _WorkingKnotState(
            _KnotState *parentState);
 
        // For batch use.  Stores only the original time parameters, which are
        // used as the proposed parameters.  Has no parent state, and cannot be
        // used to write to the spline.  The only output is 'working'.
        _WorkingKnotState(
            const Ts_KnotData &originalParams);
 
        // Write the proposed value to the spline, without adjustment.  Update
        // the parent state's 'current'.
        void WriteProposed();
 
        // Write the possibly adjusted value to the spline.  Update the parent
        // state's 'current'.
        void WriteWorking();
 
    public:
        // Link to whole-operation state.
        _KnotState* const parentState;
 
        // The proposed knot, if one was provided.
        const TsKnot proposedKnot;
 
        // The proposed time parameters.
        const Ts_KnotData proposedParams;
 
        // Copy of time parameters that we are modifying.
        Ts_KnotData workingParams;
    };
 
    // Encapsulates the core math, and the details specific to whether we're
    // operating on a pre-segment (the one before the active knot) or a
    // post-segment (the one after).
    class _SegmentSolver
    {
    public:
        enum WhichSegment
        {
            PreSegment,
            PostSegment
        };
 
        _SegmentSolver(
            WhichSegment whichSegment,
            _Mode mode,
            _WorkingKnotState* activeKnotState,
            _WorkingKnotState* oppositeKnotState,
            SetResult* result);
 
        _SegmentSolver(
            _Mode mode,
            Ts_Segment* segment,
            SetResult* result);
 
        // If adjustments are needed, update activeKnotState->working,
        // oppositeKnotState->working, and *result.  Does not immediately write
        // to the spline.  Returns true on success, false on failure.
        bool Adjust();
 
    private:
        // Mode kernels.
        bool _AdjustWithContain();
        bool _AdjustWithKeepRatio();
        bool _AdjustWithKeepStart();
        bool _AdjustWithLimitActive();
        bool _AdjustWithLimitOpposite();
 
        // Accessors and mutators for the active and opposite tangent widths.
        // The widths passed and returned here are always normalized to the
        // [0, 1] segment time interval.
        TsTime _GetProposedActiveWidth() const;
        TsTime _GetProposedOppositeWidth() const;
        void _SetActiveWidth(TsTime width);
        void _SetOppositeWidth(TsTime width);
 
        // Like the above, but for asymmetrical algorithms that differentiate
        // between start and end knots rather than active and opposite.
        TsTime _GetProposedStartWidth() const;
        TsTime _GetProposedEndWidth() const;
        void _SetStartWidth(TsTime width);
        void _SetEndWidth(TsTime width);
 
        // Plumbing helpers.
        TsTime _GetSegmentWidth() const;
 
    private:
        const WhichSegment _whichSegment;
        const _Mode _mode;
        Ts_Segment* const _segment;
        _WorkingKnotState* const _activeKnotState;
        _WorkingKnotState* const _oppositeKnotState;
        SetResult* const _result;
    };
 
private:
    // Set() helpers.
    void _InitSetResult(
        const TsKnot &proposedActiveKnot,
        SetResult *resultOut) const;
    void _HandleInitialAdjustment(
        const TsKnot &proposedActiveKnot,
        SetResult* resultOut);
    void _HandleTimeChange(TsTime proposedActiveTime);
    void _DoSet(
        const TsKnot &proposedActiveKnot,
        _Mode mode,
        SetResult* resultOut);
 
private:
    TsSpline* const _spline;
    const _Mode _mode;
    const bool _limit;
 
    bool _valid;
    bool _initialAdjustmentDone;
 
    std::optional<_KnotState> _activeKnotState;
    std::optional<_KnotState> _preKnotState;
    std::optional<_KnotState> _postKnotState;
    std::optional<_KnotState> _overwrittenKnotState;
};
 
struct Ts_RegressionPreventerBatchAccess
{
    // Batch operation for one segment of a spline.  In Contain mode, this
    // method returns true for "bold" tangents that are non-regressive but
    // exceed the segment interval.
    TS_API
    static bool IsSegmentRegressive(
        const Ts_KnotData *startKnot,
        const Ts_KnotData *endKnot,
        TsAntiRegressionMode mode);
 
    // Overload of the above function that operates on a Ts_Segment
    TS_API
    static bool IsSegmentRegressive(
        const Ts_Segment* segment,
        TsAntiRegressionMode mode);
 
    // Batch operation for one segment of a spline.  Returns whether anything
    // was changed.
    TS_API
    static bool ProcessSegment(
        Ts_KnotData *startKnot,
        Ts_KnotData *endKnot,
        TsAntiRegressionMode mode);
 
    // Overload of the above function that operates on a Ts_Segment
    TS_API
    static bool ProcessSegment(
        Ts_Segment* segment,
        TsAntiRegressionMode mode);
};
 
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#endif