CH_Segment.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:    This is the class definition for a segment.
 *
*/

#ifndef __CH_Segment_h__
#define __CH_Segment_h__

#include "CH_API.h"
#include "CH_ExprLanguage.h"
#include "CH_Manager.h"
#include "CH_Support.h"
#include "CH_Types.h"

#include <CL/CL_SimpleChannel.h>
#include <UT/UT_Vector3.h>
#include <SYS/SYS_Math.h>   // for SYSsqrt() etc
#include <SYS/SYS_StaticAssert.h>
#include <SYS/SYS_Types.h>

#include <iosfwd>


#define CH_EXPRESSION_CONSTANT  "constant()"
#define CH_EXPRESSION_BEZIER    "bezier()"
#define CH_EXPRESSION_LINEAR    "linear()"
#define CH_EXPRESSION_CUBIC     "cubic()"
#define CH_EXPRESSION_EASE      "ease()"
#define CH_EXPRESSION_EASEIN    "easein()"
#define CH_EXPRESSION_EASEOUT   "easeout()"
#define CH_EXPRESSION_SPLINE    "spline()"
#define CH_EXPRESSION_QLINEAR   "qlinear()"
#define CH_EXPRESSION_QCUBIC    "qcubic()"
#define CH_EXPRESSION_QUINTIC   "quintic()"

#define CH_SEGMENT_MINIMUM_LENGTH 0.000001F

class CH_Channel;
class CH_Expression;
class CH_Manager;
class CH_Segment;
class CH_TimeGroup;
class OP_DopeBuffer;

class UT_StringHolder;

enum
{
    CH_STRETCH_IN = 0x01,
    CH_STRETCH_OUT = 0x02
};

class CH_API CH_SegmentFlags
{
public:
    CH_SegmentFlags()
    {
        setDefaults();
    }
    void        save(std::ostream &os, int binary) const;
    bool        load(UT_IStream &is);

    void        setDefaults();
    bool        isDefault() const;

    void        display();

    unsigned isConstant:1,
               isBezier:1,
               isLinear:1,
                isCubic:1,
                 isEase:1,
               isEaseIn:1,
              isEaseOut:1,
               isLocked:1,
               isSpline:1,
               modified:1,
            tieOutAccel:1,
             tieInAccel:1,
            tieOutSlope:1,
             tieInSlope:1,
            tieOutValue:1,
             tieInValue:1,
                lockEnd:1,
              lockStart:1,
             lockLength:1,
              isCooking:1,
              isQLinear:1,
               isQCubic:1,
            autoInSlope:1,
           autoOutSlope:1,
         modifyingAccel:1,
                 isChop:1,
              isQuintic:1;
};

#define CH_MAX_SLOPE            1e8
#define CH_MAX_ACCEL            1e8

class CH_API CH_Segment
{
public:

    // Minimal constructor with no expression
    CH_Segment(CH_Channel *mom);

    // Default constructor creates an expression with which returns the
    //  default value
    CH_Segment(fpreal def_val, CH_Channel *mom, fpreal len = 0);

    // Copy constructor.
    CH_Segment(const CH_Segment &from);
    CH_Segment(const CL_SimpleSegment &from, CH_Channel *mom,
               const char *expr, CH_ExprLanguage language);

    // Constructor for an expression segment.  By default, there is
    // no callback function and no raw array
    CH_Segment(const char *expr, CH_ExprLanguage language, CH_Channel *mom,
               fpreal len = 0);

    ~CH_Segment();

    int64        getMemoryUsage(bool inclusive) const;

    CH_Manager  *getManager() const;
    fpreal       getTolerance() const;

    void         save(std::ostream &os, int binary, bool compiled,
                      bool disabled) const;
    template <typename FPREAL_TYPE>
    bool         load(UT_IStream &is, bool disabled,
                      bool reload=false);

    // Now we define some operators so that we can use these objects
    // in the UT_Array of channels
    CH_Segment  &operator= (const CH_Segment &from);
    int          operator==(const CH_Segment &) { return 0; }

    // Evaluate this segment using the current global time in CH_EvalContext
    fpreal               evaluate(int thread);
    void                 evaluateString(UT_StringHolder &result, int thread);

    // Clears and reparses the expression:
    void                 unresolveLocalVars(int thread);

    CH_Channel          *getChannel() const { return myParent; }
    void                 setChannel(CH_Channel *chp) { myParent = chp; }

    void                 setExprLanguage(CH_ExprLanguage language);
    CH_ExprLanguage      getExprLanguage() const;

    // If we were to ask for the value of the segment as a string, this
    // function returns what the meaning of that string would be (either a
    // literal or expression in some language).
    CH_StringMeaning     getStringMeaning();

    int                  isMatchFunction() const;
    int                  isLockedSegment() const    { return myFlags.isLocked; }
    int                  isChopSegment() const    { return myFlags.isChop; }

    CH_SegmentFlags        getFlags() const { return myFlags; }
    void                 lockLength(int onoff) {  myFlags.lockLength = onoff; }
    void                  lockStart(int onoff) {  myFlags.lockStart  = onoff; }
    void                    lockEnd(int onoff) {  myFlags.lockEnd    = onoff; }
    void                 tieInValue(int onoff, bool dotie = true);
    void                tieOutValue(int onoff, bool dotie = true);
    void                 tieInSlope(int onoff, bool dotie = true,
                                        fpreal ar = 0.0 );
    void                tieOutSlope(int onoff, bool dotie = true,
                                        fpreal ar = 0.0 );
    void                 tieInAccel(int onoff, bool dotie = true);
    void                tieOutAccel(int onoff, bool dotie = true);

    void                autoInSlope(int onoff);
    void               autoOutSlope(int onoff);

    // Turn cooking on and set the sample array size or turn cooking off...
    void                cook(int state, int unused = 0);

    int                      isCooking() const { return myFlags.isCooking; }
    int                 isLengthLocked() const { return myFlags.lockLength; }
    int                  isStartLocked() const { return myFlags.lockStart; }
    int                    isEndLocked() const { return myFlags.lockEnd; }
    int                  isInValueTied() const { return myFlags.tieInValue; }
    int                 isOutValueTied() const { return myFlags.tieOutValue; }
    int                  isInSlopeTied() const { return myFlags.tieInSlope; }
    int                 isOutSlopeTied() const { return myFlags.tieOutSlope; }
    int                  isInAccelTied() const { return myFlags.tieInAccel; }
    int                 isOutAccelTied() const { return myFlags.tieOutAccel; }
    int                     isConstant() const { return myFlags.isConstant; }
    int                        isCubic() const { return myFlags.isCubic; }
    int                      isQuintic() const { return myFlags.isQuintic; }
    int                       isBezier() const { return myFlags.isBezier; }
    int                       isLinear() const { return myFlags.isLinear; }
    int                      isQLinear() const { return myFlags.isQLinear; }
    int                       isQCubic() const { return myFlags.isQCubic; }
    int                         isEase() const { return myFlags.isEase; }
    int                       isEaseIn() const { return myFlags.isEaseIn; }
    int                      isEaseOut() const { return myFlags.isEaseOut; }

    int                   isQuaternion() const
                                        { return isQLinear() || isQCubic(); }
    bool                    isStandard() const
                                        { return myFlags.isBezier ||
                                                 myFlags.isLinear || myFlags.isQLinear ||
                                                 myFlags.isConstant ||
                                                 myFlags.isCubic || myFlags.isQCubic ||
                                                 myFlags.isEase ||
                                                 myFlags.isEaseIn ||
                                                 myFlags.isEaseOut; } 
    // when drawing past channel ends, should "extend" be treated
    // the same as "hold"?
    bool             treatExtendAsHold() const
                                        { return isStandard() || myFlags.isQuintic; }

    bool             hasFakeSlopeHandles() const
                                        { return myFlags.isLinear ||
                                                 myFlags.isEase ||
                                                 myFlags.isEaseIn ||
                                                 myFlags.isEaseOut; }

    // currently, all segment functions that have fake slope handles can have fake accel handles as well
    bool             hasFakeAccelHandles() const
                                        { return hasFakeSlopeHandles() && getManager()->shouldShowFakeAccelHandles(); }

    int                  isInSlopeAuto() const { return myFlags.autoInSlope; }
    int                 isOutSlopeAuto() const { return myFlags.autoOutSlope; }
    // Setting force to true ignores whether the slope is auto or not
    bool                isInSlopeFixed(bool force) const;
    bool               isOutSlopeFixed(bool force) const;

    int                  isInValueUsed();       // These methods query the
    int                 isOutValueUsed();       //  expression to find out
    int                  isInSlopeUsed();
    int                 isOutSlopeUsed();
    int                  isInAccelUsed();
    int                 isOutAccelUsed();
    int                   isSplineUsed();

    // For simple functions that CH_SegmentFlags supports, return the
    // CH_Support.h user flags for whether the value/slope/accels are used
    // without needing to evaluate the expression. Returns false if all of the 
    // CH_SegmentFlags::isCubic, isBezier, etc. are false.
    bool                getFunctionKeyUserFlags(int thread, unsigned &flags);

    // Does a quick check to see if this segment is time dependent, using the
    // flags set from the last evaluation. Returns false if we're not a special
    // case function, or if result was computed as a special case, else false.
    bool                computeFastTimeDep(bool &is_special) const;

    // Does a quick check to see if this segment is time dependent, using the
    // flags set from the last evaluation. If it can't find out, then it will
    // conservatively return true.
    bool                isTimeDependent() const
                        {
                            bool is_special;
                            return computeFastTimeDep(is_special);
                        }

    // This function will return if the value is time dependent, and, if
    // it's not, the value argument will be set.  This way, you can compare
    // adjacent values between segments to quickly check for time dependencies.
    // This function will evaluate the expression if it's not already flagged
    // as time dependent.
    // This is a helper for CH_Channel::isTimeDependentSlowImpl().
    inline bool         isTimeDependentAndGetValue(
                                fpreal &value, int thread) const;
    inline bool         isTimeDependentAndGetValue(
                                UT_StringHolder &value, int thread) const;

    bool                hasNonIntegerKeys() const;
    unsigned            isDataDependent() const;

    //  The following methods are used to change the segment times
    //  (start, end, duration), and also for checking whether the
    //  segment can be changed.
    int                 canChange(fpreal start, fpreal end) const;
    void                changeLength(fpreal len,
                                     CH_SegmentScale how=CH_SCALE_ANY,
                                     bool accel_ratio = true);
    void                changeLength(fpreal len,
                                     CH_SegmentScale how,
                                     bool in_accel_ratio,
                                     bool out_accel_ratio);
    void                changeTimes(fpreal s, fpreal e);

    // This method should only be called by CH_Channel - hands off.
    void                stretch(fpreal scale, int adjust_slopes,
                                int adjust_accel);

    //  Some query methods
    const char          *getExpression() const;
    const CH_Expression *getCHExpr() const  { return myExpression; }
    CH_Expression       *getCHExpr()        { return myExpression; }

    bool                 isEndSegment() const
                         {
                            return myLength == CONST_FPREAL(0);
                         }
    fpreal               getInValue() const     { return myInValue; }
    fpreal               getOutValue() const    { return myOutValue; }
    fpreal               getInSlope() const     { return myInSlope; }
    fpreal               getOutSlope() const    { return myOutSlope; }
    fpreal               getInAccel() const     { return myInAccel; }
    fpreal               getOutAccel() const    { return myOutAccel; }
    fpreal               getInAccelRatio() const
                         {
                             return getAccelRatio(myInSlope, myInAccel,
                                                  myLength);
                         }
    fpreal               getOutAccelRatio() const
                         {
                             return getAccelRatio(myOutSlope, myOutAccel,
                                                  myLength);
                         }
    static fpreal        getAccelRatio(fpreal slope, fpreal accel,
                                       fpreal length);
    static fpreal        getAccelFromRatio(fpreal slope, fpreal ratio,
                                           fpreal length)
                         {
                             if( length==0.0 )
                                length = 1.0;
                            return length * ratio * SYSsqrt( slope*slope + 1 );
                         }
    static fpreal        getAccelX(fpreal slope, fpreal accel);

    CH_Segment          *getNext()          { return myNext; }
    const CH_Segment    *getNext() const    { return myNext; }
    void                 setNext(CH_Segment *segp)
                                            { myNext = segp; }
    CH_Segment          *getPrev()          { return myPrev; }
    const CH_Segment    *getPrev() const    { return myPrev; }
    void                 setPrev(CH_Segment *segp)
                                            { myPrev = segp; }

    fpreal               getLength() const  { return myLength; }
    fpreal               getILength() const { return myInverseLength; }

    fpreal               getStart() const   { return myStart; }
    fpreal               getEnd() const     { return myEnd; }

    fpreal               relativeTime(fpreal t) const
                         {
                             return (t - myStart) * myInverseLength;
                         }

    void                changeExpression(const char *expr, CH_ExprLanguage language,
                                         bool convert_accels, bool post_process=true);
    void                changeExpression(const char *expr,
                                CH_ExprLanguage language);
    void                changeExpressionToBezierOrCubic();

    // Return whether or not an expression is a call to an animation function.
    // Note that such expressions are compatible between different languages.
    // The static method is for an arbitrary expression string and the
    // non-static is for this segment.
    static bool         expressionIsAnimationFunctionCall(
                            const char *expression);
    bool                expressionIsAnimationFunctionCall();

    // When an application calls the following methods to set in/out values,
    // they should leave the doTie as 1, it's only used internally.
    void                 setInValue(fpreal v, bool dotie = true);
    void                setOutValue(fpreal v, bool dotie = true);
    void                 setInSlope(fpreal v, bool dotie = true, fpreal ar = 0.0);
    void                 setInSlope(fpreal v, bool dotie, fpreal ar,
                                bool clamp_accel);
    void                setOutSlope(fpreal v, bool dotie = true, fpreal ar = 0.0);
    void                setOutSlope(fpreal v, bool dotie, fpreal ar,
                                bool clamp_accel);
    void                 setInAccel(fpreal v, bool dotie = true);
    void                setOutAccel(fpreal v, bool dotie = true);
    void                 setInAccelRatio(fpreal ratio, bool dotie = true)
                         {
                            fpreal v = getAccelFromRatio(myInSlope, ratio,
                                                         myLength);
                            setInAccel( v, dotie );
                         }
    void                 setOutAccelRatio(fpreal ratio, bool dotie = true )
                         {
                            fpreal v = getAccelFromRatio(myOutSlope, ratio,
                                                         myLength);
                            setOutAccel( v, dotie );
                         }
    void                clampInAccel();
    void                clampOutAccel();
    void                normalizeAccels();
    void                postProcessFakeSlopeAccelHandles();
    void                postProcessHybridSlopes();

    // Does nothing for segments that are not cubic or bezier
    void                makeMonotone(bool do_prev=false, bool do_next=false);
    // Returns false for segments that are not cubic or bezier
    bool                isMonotone() const;
    /// For segments that are not cubic or bezier, sets range to the entire
    /// slope interval, (-CH_MAX_SLOPE, CH_MAX_SLOPE), and returns false
    bool                getMonotoneInterval(UT_IntervalR &range, bool lock_in);

    void                setPrevNext(CH_Segment *p, CH_Segment *n)
                        {
                            myPrev = p;
                            myNext = n;
                        }

    // Sorry, you can only flag a segment as being changed, it's got it's
    // own internal mechanism for flagging this
    void                setChanged();

    // Only the CH_Channel class should call the following method(s)
    void                reverse();

    // Op dependencies
    void                buildOpDependencies(void *ref_id, int thread);
    int                 changeOpRef(const char *new_fullpath,
                                    const char *old_fullpath,
                                    const char *old_cwd,
                                    const char *chan_name,
                                    const char *old_chan_name,
                                    int thread);

    int                 findString(const char *str, bool fullword,
                                   bool usewildcards) const;
    int                 changeString(const char *from, const char *to,
                                     bool fullword, int thread);

    void                transferGroup(CH_Segment &from);

    bool                wasModified() const { return (myFlags.modified != 0); }
    void                setModified(bool on_off);

    void                dirtyExprCache();

    fpreal              getValue(bool left, CH_ValueTypes t) const;
    void                setValue(bool left, CH_ValueTypes t, fpreal value);
    bool                getValueValid(bool left, CH_ValueTypes t);
    bool                getValueTied(bool left, CH_ValueTypes t) const;
    void                setValueTied(bool left, CH_ValueTypes t, bool on_off);
    bool                getValueAuto(bool left, CH_ValueTypes t) const;
    void                setValueAuto(bool left, CH_ValueTypes t, bool on_off);

    void                display();

    CH_TimeGroup        *getTimeGroup() const { return myTimeGroup; }

    CL_SimpleSegmentType getSimpleType() const;

    static const char   *getExpressionFromSimpleType(CL_SimpleSegmentType type);

    CL_SegmentValues     getSegmentValues() const;
private:
    void                 setTimeGroup(CH_TimeGroup *g, bool refresh=true);

    void                 setExpression(const CH_Expression *newexpr);
    void                 checkExpression();
    void                 constructorInit();     // Initialize all values
    void                 isCooking(int state)   // Toggle state during cook
                         { myFlags.isCooking = state; }
    bool                 loadTimeGroups(UT_IStream &is);
    void                 saveTimeGroups(std::ostream &is, int binary) const;

    void                 holdLastKey(fpreal v, bool dotie);

    void                 updateExprFlags();


    static constexpr unsigned
                         TIMEDEPFLAGS = (CH_EXPRTIME  | CH_EXPRCHAN  | 
                                         CH_EXPRVALUE | CH_EXPRSLOPE |
                                         CH_EXPRACCEL | CH_EXPRKNOTS);

    bool                 isExprTimeDep() const;

    // the member variables marked with (*) should be removed as they are
    // actually useless

    CH_SegmentFlags      myFlags;

    // Here is the local context information for the segment.  It is
    // be used for evaluation of the segment.
    //
    // All times and lengths of time are in the channel local time.
    CH_Expression       *myExpression;

    fpreal               myInValue, myOutValue;
    fpreal               myInSlope, myOutSlope;
    fpreal               myInAccel, myOutAccel;

    CH_TimeGroup        *myTimeGroup;

    // (*) we shouldn't store length, just use getNext()->myStart - myStart
    // storing inverse length is acceptable
    fpreal               myLength;
    fpreal               myInverseLength;       // Inverse stored for speed

    // (*) myEnd is redundant, and is not really that much more efficient
    fpreal               myStart, myEnd;        // Redundant; for efficiency

    CH_Channel          *myParent;              // Our channel.

    // (**) ideally we would store segments in a ref array, in which case
    // getNext could ideally be (this+1), ditto for prev, but there are some
    // boundary cases of course where this gets weird
    CH_Segment          *myPrev, *myNext;       // For easy reference

    friend class         CH_TimeGroup;
    friend class         OP_DopeBuffer;
};

inline bool
CH_Segment::computeFastTimeDep(bool &is_special) const
{
    // Constant segments are never time dependent
    if (myFlags.isConstant)
    {
        is_special = true;
        return false;
    }

    if (isEndSegment())
    {
        // For end segments, the out value/slopes are not used so all of these
        // expressions on them are NOT time dependent
        if (treatExtendAsHold())
        {
            is_special = true;
            return false;
        }
    }
    else
    {
        if (myFlags.isBezier || myFlags.isCubic || myFlags.isQuintic)
        {
            is_special = true;
            return (myInValue != myOutValue) || myInSlope || myOutSlope;
        }

        if (myFlags.isLinear || myFlags.isEase ||
            myFlags.isEaseIn || myFlags.isEaseOut)
        {
            is_special = true;
            return myInValue != myOutValue;
        }
    }

    // If the expression is already flagged as time-dependent, we don't
    // need to do any evaluation.
    is_special = false;
    return isExprTimeDep();
}



#endif