CL_SimpleChannel.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        Channel Library (C++)
 *
 * COMMENTS:    Simplified version of a channel which can be used without
 *              requiring the full CH library 
 *
*/

#ifndef __CL_SimpleChannel_h__
#define __CL_SimpleChannel_h__

#include "CL_API.h"
#include "CL_Types.h"

#include <SYS/SYS_Types.h>
#include <UT/UT_Array.h>
#include <UT/UT_Interval.h>
#include <UT/UT_StringHolder.h>

class CL_SegmentValues;
class CL_SimpleSegment;
class CL_Cubic;

class UT_RLEBitArray;

class CL_API CL_Bezier
{
public:
    fpreal      x[4];
    fpreal      y[4];

    CL_Bezier() {}

    CL_Bezier(const CL_SegmentValues &sv);
    CL_Bezier(CL_SegmentValues sv, fpreal vscale, fpreal voff);
    // This constructor can be used to convert segment values to a bezier
    // without applying the clamp to the control points which is meant to fix
    // curves that back in on themselves. We want to prevent this clamping when
    // converting the end_segment. As it has has a length of 0, clamping will
    // cause us to lose its control points/acceleration handles.
    CL_Bezier(const CL_SegmentValues &sv, bool clamp_slopes);

    void        init(const CL_SegmentValues &sv);

    void        fromSegmentValues(const CL_SegmentValues &sv,
                                  bool clamp_slopes = true);

    void        getValues( CL_SegmentValues &v ) const;

    static void getCubicFromCVs( const fpreal x[4], CL_Cubic &c );
    static void getCubicFromCVs( const fpreal x[4], fpreal c[4] );

    static void splitInternal( fpreal t, const fpreal xin[4],
                                    fpreal xout1[4], fpreal xout2[4] );

    void        splitP( fpreal u, CL_Bezier &a, CL_Bezier &b ) const;

    void        split( fpreal t, CL_Bezier &a, CL_Bezier &b ) const;

    void        splitAndFindSlopeLengths( fpreal t,
                    fpreal &left_in, fpreal &left_out,
                    fpreal &right_in, fpreal &right_out ) const;

    // Calculates an acceleration ratio for a key to try and ease
    // the curve if it's at the corner of a steep gradient
    static fpreal getAdjustedAccelRatio(fpreal v0, fpreal v1, fpreal v2,
                                        fpreal t0, fpreal t1, fpreal t2,
                                        fpreal slope, bool is_in);

    fpreal      timeToParametric( fpreal t ) const;

    fpreal      evalP( fpreal u ) const;

    fpreal      eval( fpreal t ) const; // t is local

    void        display() const;
};

class CL_API CL_Cubic
{
public:
    fpreal      t0, t1;
    fpreal      x0, x1, x2, x3;

    CL_Cubic() {};
    CL_Cubic(const CL_SegmentValues &sv);
    CL_Cubic(fpreal iv, fpreal ov, fpreal im, fpreal om, fpreal it, fpreal ot);

    void        init(const CL_SegmentValues &sv);
    void        getValues(CL_SegmentValues &v) const;

    fpreal      timeToParametric( fpreal t ) const;     // t -> u

    static fpreal reverseEvalP( const fpreal x[4], fpreal y );  // y -> u
    static fpreal reverseEvalP( const CL_SimpleSegment &seg, fpreal y );        // y -> u
    fpreal      reverseEvalP( fpreal y ) const; // y -> u

    fpreal      evalP( fpreal u ) const         // u -> y
    {
        return x0 + u*(x1 + u*(x2 + u*x3));
    }

    fpreal      eval( fpreal t ) const;         // t -> y

    fpreal      calculateSlopeP( fpreal u ) const;

    fpreal      calculateAccelP( fpreal u ) const;

    // If lock_in = true, this computes the range of out slopes that produce
    // a monotonic curve assuming the in slope is fixed. false does the same
    // for the in slope assuming the out slope is fixed.
    // If no such interval exists, sets range to (-CL_MAX_SLOPE, CL_MAX_SLOPE)
    // and returns false. Returns true if there's a valid interval
    bool getMonotoneInterval(UT_IntervalR &range, bool lock_in);
    // Same as getMonotoneInterval, but if the interval doesn't exist then
    // it is recalculated with the locked slope being clamped to a range where
    // the interval must be non-empty.
    // This is useful to find slopes that get as close as possible to
    // monotonicity, which helps prevent snapping in some cases.
    void getWeakMonotoneInterval(UT_IntervalR &range, bool lock_in);


    static bool     isMonotone(fpreal iv, fpreal ov, fpreal im, fpreal om, fpreal dt);
    static void     clampSlopesToMonotone(fpreal &in, fpreal &out,
                                          fpreal in_val, fpreal out_val, fpreal dt);
    /// Second derivative discontinuity minimizing method suggested by
    /// Wolberg. Given the slopes at the surrounding knots, picks a
    /// slope that gets as close to C2 continuity as possible while
    /// preserving monotonicity. To be used on keys whose neighbours have
    /// pre-determined slopes, like local extrema or non-auto slopes
    static fpreal   getMonotoneSlopeSDDE(fpreal v0, fpreal v1, fpreal v2,
                                         fpreal t0, fpreal t1, fpreal t2,
                                         fpreal m0, fpreal m2);
    // An extension of getMonotoneSlopeSDDE that operates on a group of
    // 2 keys sandwiched between knots with fixed slopes. Picks slopes for
    // to approach C2 continuity at both knots simultaneously while
    // preserving monotonicity
    static void     getMonotoneSlopeSDDE2(fpreal v0, fpreal v1,  fpreal v2,  fpreal v3,
                                          fpreal t0, fpreal t1,  fpreal t2,  fpreal t3,
                                          fpreal m0, fpreal &m1, fpreal &m2, fpreal m3);

    // An unstable extension of getMonotoneSlopeSDDE2 that uses conic intersections
    // to resolve cases where the segments are non monotonic.
    #if 0
    static void     getMonotoneSlopeSDDE2ViaConic
                                         (fpreal v0, fpreal v1,  fpreal v2,  fpreal v3,
                                          fpreal t0, fpreal t1,  fpreal t2,  fpreal t3,
                                          fpreal m0, fpreal &m1, fpreal &m2, fpreal m3);
    #endif


    void        display() const;
};

// Supported SimpleSegment Types.
enum CL_SimpleSegmentType
{
    CL_SIMPLESEGMENT_INVALID,
    CL_SIMPLESEGMENT_CONSTANT,
    CL_SIMPLESEGMENT_LINEAR,
    CL_SIMPLESEGMENT_CUBIC,
    CL_SIMPLESEGMENT_BEZIER,
    CL_SIMPLESEGMENT_EASE,
    CL_SIMPLESEGMENT_EASEIN,
    CL_SIMPLESEGMENT_EASEOUT,
    CL_SIMPLESEGMENT_QUINTIC,
    // Custom means an expression that is unsupported by
    // the simple channel. The custom expression will be stored
    // on the simpleSegment for purposes of preserving it when
    // round-tripping back to a CH_Segment, but it will be
    // evaluated as a Bezier instead of the actual type.
    CL_SIMPLESEGMENT_CUSTOM,
};

class CL_SimpleChannel;

enum class CL_KeyHalf
{
    In,
    Out,
    InOut,
};

class CL_API CL_SegmentValues
{
public:
    fpreal      t0, t1;
    fpreal      iv, ov, im, om, isl, osl;
    
    CL_SegmentValues() {}

    void        display();
};

// It is designed for fast evaluation of the supported segment types.
// with focus on the bezier segments.
class CL_API CL_SimpleSegment
{
public:
    fpreal getStart() const { return myBezierX[0]; }
    fpreal getEnd() const { return myBezierX[3]; }
    fpreal getStartValue() const { return myBezierY[0]; }
    fpreal getEndValue() const { return myBezierY[3]; }
    fpreal getLength() const { return myBezierX[3] - myBezierX[0]; }

    void setType(CL_SimpleSegmentType type) { myType = type; }
    CL_SimpleSegmentType getType() const { return myType; }

    void setExtraData(int index, fpreal data) { myExtra[index] = data; }
    fpreal *getExtraData() { return myExtra; }

private:

    //x[0] is the start time
    //x[3] is the end time
    //y[0] is the start value
    //y[3] is the end value
    fpreal myBezierX[4]; // x[] data member of CL_Bezier
    fpreal myBezierY[4]; // y[] data member of CL_Bezier

    CL_SimpleSegmentType myType; // Simple Segment Type

    // Extra data for Bezier/Cubic/Quintic
    // Bezier stores UT_BezierRootFinder precomputed coefficients
    // Cubic stores InSlope and OutSlope
    // Quintic stores InSlope, OutSlope, InAccel and OutAcce
    fpreal myExtra[16];

    friend class CL_SimpleChannel;
    friend class CL_Cubic;
};

/// A specialized channel for fast evaluation.
/// Should be created from an existing CH_Channel using 
/// CH_Channel->asSimpleChannel().
/// Can be copied using the copy constructor.
/// Doesn't store the in/out value/slope/accel directly.
/// It stores precomputed bezier coefficient to avoid doing the conversion at
/// each evaluation.
/// Also uses UT_BezierRootFinder with precomputed coefficients to speed up
/// CL_Cubic::reverseEvalP.
class CL_API CL_SimpleChannel
{
public:
    // Create an empty channel
    CL_SimpleChannel();

    CL_SimpleChannel(
            fpreal start,
            int num_segments,
            fpreal length,
            CL_ChannelBehavior left_type,
            CL_ChannelBehavior right_type,
            fpreal default_value,
            fpreal default_slope);

    // Deprecated, use the variant without tolerance instead
    SYS_DEPRECATED(20.0)
    CL_SimpleChannel(
            fpreal start,
            int num_segments,
            fpreal length,
            CL_ChannelBehavior left_type,
            CL_ChannelBehavior right_type,
            fpreal default_value,
            fpreal default_slope,
            fpreal tolerance);

    ~CL_SimpleChannel() = default;

    CL_SimpleChannel(const CL_SimpleChannel &other) = default;
    CL_SimpleChannel(CL_SimpleChannel &&other) = default;

    CL_SimpleChannel &operator=(const CL_SimpleChannel &other) = default;
    CL_SimpleChannel &operator=(CL_SimpleChannel &&other) = default;

    // Evaluate the channel at global time.
    fpreal eval(fpreal gtime) const;

    // Evaluate the channel at global time using a segment hint.
    // Start with an hint of -1 if you don't have a previous evaluation.
    fpreal eval(fpreal gtime, int &segment_idx_hint) const;

    // Evaluate the segment at local time using a segment hint.
    fpreal eval(const CL_SimpleSegment &seg, fpreal ltime) const;

    // Evaluate the slope at local time using a segment hint.
    fpreal evalSlope(const CL_SimpleSegment &seg, fpreal ltime) const;

    bool isAtHardKey(fpreal gtime) const;

    int getSegmentIdx(fpreal ltime) const;
    CL_SimpleSegment &getSegment(int index) { return mySegments[index]; }
    const CL_SimpleSegment &getSegment(int index) const { return mySegments[index]; }
    const UT_Array<CL_SimpleSegment> &getSegments() const { return mySegments; }

    UT_StringHolder getSegmentExpression(int index) const { return mySegmentExpressions[index]; }
    const UT_Array<UT_StringHolder> &getSegmentExpressions() const { return mySegmentExpressions; }
    void setSegmentExpression(int index, const UT_StringHolder &expr)
            { mySegmentExpressions[index] = expr; }

    int getSegmentInSlopeAuto(int index) const
            { return mySegmentInSlopesAuto[index]; }
    int getSegmentOutSlopeAuto(int index) const
            { return mySegmentOutSlopesAuto[index]; }

    void setSegmentInSlopeAuto(int index, bool value)
            { mySegmentInSlopesAuto[index] = value; }
    void setSegmentOutSlopeAuto(int index, bool value)
            { mySegmentOutSlopesAuto[index] = value; }

    void setSegmentInSlope(int index, fpreal slope);
    void setSegmentOutSlope(int index, fpreal slope);
    void setSegmentInAccel(int index, fpreal accel, bool ratio = false);
    void setSegmentOutAccel(int index, fpreal accel, bool ratio = false);

    /// Set the type of the segment
    /// Note that this differs from the setSegmentExpression, which is used
    /// only for custom expressions.
    /// @param index The index of the segment to modify
    /// @param type The type to change the segment to.
    void setSegmentType(int index, CL_SimpleSegmentType type);

    CL_SimpleSegmentType getSegmentType(int index) const;

    /// Insert a key frame at the given global time.
    /// Returns true if a key frame was added, or false if it failed, or if
    /// there was already a key frame at the given time.
    bool insertKeyFrame(fpreal global_time, bool auto_slope = true);
    /// Destroy the key frame at the given global time
    /// Returns true if a key was deleted, or false if there was no key at this
    /// time
    bool destroyKeyFrame(fpreal global_time);

    /// Set the value of the key at the given time
    /// @param gtime Global time of the key to change
    /// @param value New value to set for the key
    /// @param half Which half of the key to set. Defaults to both (tied)
    /// @returns true if successful, or false if there is no key at the given time
    bool setKeyValue(fpreal gtime, fpreal value,
                     CL_KeyHalf half=CL_KeyHalf::InOut);

    /// Set the slope of the key at the given time
    /// @param gtime Global time of the key to change
    /// @param slope New slope to set for the key
    /// @param half Which half of the key to set. Defaults to both (tied)
    /// @returns true if successful, or false if there is no key at the given time
    bool setKeySlope(fpreal gtime, fpreal slope,
                     CL_KeyHalf half=CL_KeyHalf::InOut);

    /// Set the accel of the key at the given time
    /// @param gtime Global time of the key to change
    /// @param accel New value to set for the key
    /// @param half Which half of the key to set. Defaults to both (tied)
    /// @returns true if successful, or false if there is no key at the given time
    bool setKeyAccel(fpreal gtime, fpreal accel,
                     CL_KeyHalf half=CL_KeyHalf::InOut);

    /// Set the auto_slope property of the key at the given time
    /// @param gtime Global time of the key to change
    /// @param auto_slope New auto_slope to set for the key
    /// @param half Which half of the key to set. Defaults to both (tied)
    /// @returns true if successful, or false if there is no key at the given
    /// time
    bool setKeyAutoSlope(fpreal gtime, bool auto_slope,
                         CL_KeyHalf half=CL_KeyHalf::InOut);

    /// Sets data evenly spaced between from and to
    bool setRawValues(fpreal from,
                      fpreal to,
                      fpreal *data,
                      int num_samples,
                      bool auto_slope = true);
    /// Sets data at the specified times
    bool setRawValues(fpreal *times, fpreal *data, int num_samples);

    /// clears the channel, erasing all segments
    void clear();

    /// Set the default value. This is the value returned when evaluating
    /// an empty channel.
    void setDefaultValue(fpreal value) { myDefaultValue = value; }

    void setPreValue(fpreal value) { myPreValue = value; }
    void setPreSlope(fpreal slope) { myPreSlope = slope; }
    void setPreType(CL_ChannelBehavior type) { myPreType = type; }

    void setPostValue(fpreal value) { myPostValue = value; }
    void setPostSlope(fpreal slope) { myPostSlope = slope; }
    void setPostType(CL_ChannelBehavior type) { myPostType = type; }

    fpreal getDefaultValue() const { return myDefaultValue; }

    fpreal getPreValue() const { return myPreValue; }
    fpreal getPreSlope() const { return myPreSlope; }
    CL_ChannelBehavior getPreType() const { return myPreType; }

    fpreal getPostValue() const { return myPostValue; }
    fpreal getPostSlope() const { return myPostSlope; }
    CL_ChannelBehavior getPostType() const { return myPostType; }

    fpreal getTolerance() const
        { return CL_SimpleChannel::getChannelTolerance(); }

    SYS_DEPRECATED(20.0)
    void setTolerance(fpreal tolerance) { myTolerance = tolerance; }

    fpreal getStart() const { return myStart; }
    fpreal getEnd() const { return myStart + myLength; }
    fpreal getLength() const { return myLength; }

    void setStart(fpreal start) { myStart = start; }
    /// Returns the number of segments including the end segment
    int getNSegments() const { return mySegments.size(); }

    UT_Array<fpreal> getKeyTimes() const;
    UT_Array<fpreal> getKeyValues() const;

    bool getSurroundingSegs(fpreal gtime, CL_SimpleSegment *&left,
                            CL_SimpleSegment *&right);

    /// Shift the specified keys by the given time offsets.
    /// Time offsets must either match the size of indices, or be an array
    /// of 1 element to shift all keys by the same offset.
    bool moveKeysWithDeltas(const UT_IntArray &indices,
                            const UT_Array<fpreal> &time_offsets);

    void smoothAutoSlopesForSegments(
            UT_RLEBitArray &slope_flags,
            bool force = false,
            fpreal max_delta = -1);

    void smoothAutoSlopes(bool force = false);

    // The following four functions are called by the CH_Manager to ensure
    // simple channels share the same default animation preferences that
    // regular channels do.
    static void setChannelTolerance(fpreal tol) { theTolerance = tol; }
    /// Set the segment type used for the first key in a channel
    static void setDefaultSegmentType(CL_SimpleSegmentType type);
    /// Set the segment type used when splitting a segment if auto split is
    /// false
    static void setDefaultSegmentSplitType(CL_SimpleSegmentType type);
    /// Set the segment type behaviour when splitting a segment. If true,
    /// The type of the split segment will be applied to the new segment,
    /// otherwise, theDefaultSplitSegmentType will be used
    static void setAutoSplit(bool onoff);

    static fpreal getChannelTolerance() { return theTolerance; }

    static CL_SimpleSegmentType getDefaultSegmentType()
            { return theDefaultSegmentType; }

    static CL_SimpleSegmentType getDefaultSegmentSplitType()
            { return theDefaultSplitSegmentType; }

    static bool getAutoSplit() { return theAutoSplit; }

private:
    static fpreal theTolerance;
    static constexpr fpreal theDefaultAccelRatio = 1.0 / 3.0;
    static CL_SimpleSegmentType theDefaultSegmentType;
    static CL_SimpleSegmentType theDefaultSplitSegmentType;
    static bool theAutoSplit;

    // should be kept in sync with CH_Segment::getAccelFromRatio
    static fpreal getAccelFromRatio(fpreal slope, fpreal ratio,
                                   fpreal length)
                {
                    if( length==0.0 )
                        length = 1.0;
                    return length * ratio * SYSsqrt( slope*slope + 1 );
                }

    // These methods are adapted from CH_Segment::clamp{In,Out}Accel. They
    // serve as an alternative to the clamp_slopes option in
    // CL_Bezier::fromSegmentValues, clamping the acceleration instead of the
    // slope.
    /// Clamp a SegmentValues' in acceleration to fix a curve that would
    /// back in on itself.
    static fpreal clampSegmentValuesInAccel(const CL_SegmentValues &sv,
                                            bool is_end_segment);
    /// Clamp a SegmentValues' out acceleration to fix a curve that would
    /// back in on itself.
    static fpreal clampSegmentValuesOutAccel(const CL_SegmentValues &sv,
                                             bool is_end_segment);

    bool extend(fpreal t, int &i, fpreal &ret) const;

    void splitSegment(fpreal gtime, bool auto_slope = true);
    /// Change a segment's length, preserving its start time and in/out slopes
    void changeSegmentLength(int index,
                             fpreal new_length,
                             bool scale_accels = true);

    // Methods for manipulating the segments array.
    // Note that the following 4 functions do not change the segment data,
    // But rather just ensure that the various arrays (segment, expression,
    // in/out slope) are kept in sync when segments are moved.
    // It is up to the caller to ensure that the segment values/times are
    // correct when calling these methods.
    void appendSegment(const CL_SimpleSegment &segment,
                       const UT_StringHolder &expr,
                       bool auto_slope);
    void insertSegment(int index,
                       const CL_SimpleSegment &segment,
                       const UT_StringHolder &expr,
                       bool auto_slope);
    void removeSegment(int index);

    CL_SegmentValues getValuesFromSegment(CL_SimpleSegment &segment);
    void setSegmentFromValues(CL_SimpleSegment &segment,
                              const CL_SegmentValues &sv,
                              bool clamp_slopes = true);

    /// Recompute the bezier coeffs for each segment, in the given range
    void recomputeBezierCoeffs(int start_index = 0, int end_index = -1);
    void recomputeBezierCoeffs(CL_SimpleSegment &segment);

    /// Sets the extra data for the segment, based on its type.
    void setSegmentExtraData(CL_SimpleSegment &segment);

    /// Moves a key/segment by the given time delta.
    /// Requires that the new time does NOT have a key at it already
    void shiftKey(int index, fpreal t, bool recompute_coeffs = true);

    /// Returns whether or not a segment is an end segment (ie, has length == 0)
    bool isEndSegment(const CL_SimpleSegment &segment) const;

    // Compact array of segments.
    // This data layout currently works well when evaluating a single channel
    // many times across its whole time range.
    // We might have to change the data layout to be more efficient
    // at evaluating many channels at the same global time.
    // This could involve a page system where segments from the same time range
    // are from the area in memory same pool.
    UT_Array<CL_SimpleSegment> mySegments;

    // Custom expressions for each segment with a type of CUSTOM.
    // Stored for purposes of round-tripping back to CH_Channel only - these
    // segments will still be evaluated as Beziers here.
    UT_Array<UT_StringHolder> mySegmentExpressions;

    // Whether the in/out slope for each segment is auto calculated or not
    // Stored for purposes of round-tripping back to a CH_Channel. These
    // are currently not used when setting the key value of a simple channel.
    // TODO(michaelf): Do we want to support auto-slope calculation when setting
    // keys of simplechannels?
    UT_Array<bool> mySegmentInSlopesAuto;
    UT_Array<bool> mySegmentOutSlopesAuto;

    fpreal myTolerance; // Global floating point tolerance.
    fpreal myLength; // Channel Length in time.
    fpreal myStart; // Channel Start global time.

    // Constant value to be used if the channel is empty.
    fpreal myDefaultValue;
    // Precomputed values for pre/post extend.
    fpreal myPreValue;
    fpreal myPostValue;

    // Precomputed slope (or extra) for pre/post extend.
    fpreal myPreSlope;
    fpreal myPostSlope;

    // Pre/right types, used by extend()
    CL_ChannelBehavior myPreType;
    CL_ChannelBehavior myPostType;
};

#endif