CH/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.
//
//
// Produced by:
//      Mark Elendt
//      Side Effects Software Inc.
//      20 Maud St.
//      Toronto, Ontario,  M5V 2M5
//      Canada
//      416-366-4607
//
// 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 <iostream.h>
#include <deque>
#include <UT/UT_Vector3.h>
#include "CH_Channel.h"

#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()"

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

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

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

    unsigned    getFlag() const;
    void        parseFlag(unsigned flag);
    void        setDefaults();
    unsigned    isDefault() const;

    CH_SegmentFlags     &operator=(unsigned f) { parseFlag(f); return *this; }
    operator             unsigned() { return getFlag(); }

    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;
};

class CH_API CH_SegmentValues
{
public:
    float       t0, t1;
    float       iv, ov, im, om, isl, osl;
    
    CH_SegmentValues() {}

    CH_SegmentValues( CH_Segment const& seg );

    void        display();
};

#define CH_MAX_SLOPE            1e8
#define CH_MAX_ACCEL            1e8

class CH_API CH_Segment
{
public:
    // Default constructor creates an expression with which returns the
    //  default value
    CH_Segment(float defVal, CH_Channel *mom, float len = 0);

    // Copy constructor.
    CH_Segment(const CH_Segment &from);

    // 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,
               float len = 0);

    ~CH_Segment();

    CH_Manager  *getManager()   const { return myParent->getManager(); }
    float        getTolerance() const { return getManager()->getTolerance(); }

    void         save(ostream &os, int binary, bool compiled,
                      bool disabled) const;
    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_RefArray of channels
    CH_Segment  &operator= (const CH_Segment &from);
    int          operator==(const CH_Segment &) { return 0; }

    // The segment may be evaluated by using any of the following
    // evaluation methods.  The segment can be evaluated by relative
    // time, absolute time or both.
    // If extend is non-zero, the left(1) or right(2) value along the 
    // slope is calculated accordingly.
    float                evaluate(float ltime, bool extend /*=false*/,
                                  int thread);
    void                 evaluateString(UT_String &result,
                                        float ltime, bool extend /*=false*/,
                                        int thread);

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

    CH_Channel          *getChannel(void) 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(void) const;
    int                  isLockedSegment() const    { return myFlags.isLocked; }

    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,
                                        float ar = 0.0 );
    void                tieOutSlope(int onoff, bool dotie = true,
                                        float ar = 0.0 );
    void                 tieInAccel(int onoff, bool dotie = true);
    void                tieOutAccel(int onoff, bool dotie = true);

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

    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                       isBezier() const { return myFlags.isBezier; }
    int                      isQLinear() const { return myFlags.isQLinear; }
    int                       isQCubic() const { return myFlags.isQCubic; }
    int                   isQuaternion() const
                                        { return isQLinear() || isQCubic(); }

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

    // Does a quick check to see if this segment is time dependent, using the
    // flags set from the last evaluation.
    bool                isTimeDependent() const;
    // If evaluate_to_find_out is false, the expression's flags will just be
    // checked.  In that case, if the expression was never evaluated since
    // it last changed, this function may return that it's not time dependent
    // even if it is.
    bool                isTimeDependent(bool evaluate_to_find_out,
                                        int thread) const;

    // 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.
    bool                isTimeDependentAndGetFloat(float &value,
                                                   int thread) const;

    // This function is like isTimeDependentAndGetFloat(), except it will
    // evaluate the expression as a string.  Note that the char* may be
    // set to null if the segment is time dependent.  If it's not null, it
    // points to a strdup'd string that you must free().
    bool                isTimeDependentAndGetString(UT_String &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(float start, float end) const;
    void                changeLength(float len,
                                     CH_SegmentScale how=CH_SCALE_ANY,
                                     bool accel_ratio = true);
    void                changeTimes(float s, float e);

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

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

    const UT_Vector3    *getSplineKnots(void) const { return mySplineKnots; }
    const UT_Vector3    *getSplineKnot(int n) const { return &mySplineKnots[n];}
    int                  getNKnots(void)   const { return nKnots; }

    bool                 isEndSegment() const
                         {
                            return myLength == CONST_FPREAL(0);
                         }
    float                getInValue(void)      const { return inValue; }
    float                getOutValue(void)     const { return outValue; }
    float                getInSlope(void)      const { return inSlope; }
    float                getOutSlope(void)     const { return outSlope; }
    float                getInAccel(void)      const { return inAccel; }
    float                getOutAccel(void)     const { return outAccel; }
    fpreal               getInAccelRatio() const
                         {
                             return getAccelRatio( inSlope, inAccel, myLength );
                         }
    fpreal               getOutAccelRatio() const
                         {
                             return getAccelRatio( outSlope, outAccel,
                                                    myLength );
                         }
    static fpreal        getAccelRatio( float slope, float accel,
                                        float length );
    static fpreal        getAccelFromRatio( float slope, float ratio,
                                                float length )
                         {
                             if( length==0.0 )
                                length = 1.0;
                            return length * ratio * SYSsqrt( slope*slope + 1 );
                         }

    CH_Segment          *getNext()          { return myNext; }
    const CH_Segment    *getNext() const    { return myNext; }
    CH_Segment          *getPrev()          { return myPrev; }
    const CH_Segment    *getPrev() const    { return myPrev; }

    float                getLength (void) const { return myLength; }
    float                getILength(void) const { return myInverseLength; }

    float                getStart(void) const { return myStart; }
    float                getEnd  (void) const { return myEnd; }

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

    void                changeExpression(const char *expr,
                                CH_ExprLanguage language, bool convert_accels);
    void                changeExpression(const char *expr,
                                CH_ExprLanguage language);

    // 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();

    void                addSplineKnot(float x, float y);
    void                setSplineKnot(int n, float x, float y);

    // 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(float v, bool dotie = true);
    void                setOutValue(float v, bool dotie = true);
    void                 setInSlope(float v, bool dotie = true, float ar = 0.0);
    void                setOutSlope(float v, bool dotie = true, float ar = 0.0);
    void                 setInAccel(float v, bool dotie = true);
    void                setOutAccel(float v, bool dotie = true);
    void                 setInAccelRatio( float ratio, bool dotie = true )
                         {
                            fpreal  v = getAccelFromRatio( inSlope, ratio,
                                                            myLength );
                            setInAccel( v, dotie );
                         }
    void                 setOutAccelRatio( float ratio, bool dotie = true )
                         {
                            fpreal  v = getAccelFromRatio( outSlope, ratio,
                                                            myLength );
                            setOutAccel( v, dotie );
                         }
    void                clampInAccel();
    void                clampOutAccel();
    void                normalizeAccels();

    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);

    int                  wasModified() const { return myFlags.modified; }
    void                 setModified(int onOff);

    void                dirtyExprCache();

    float               getValue(bool left, CH_ValueTypes t) const;
    void                setValue(bool left, CH_ValueTypes t, float 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);

    void                display();

    CH_TimeGroup        *getTimeGroup(void)  const { return myTimeGroup; }

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

    void                 setExpression(const CH_Expression *newexpr);
    void                 checkExpression();
    void                 constructorInit(void); // Initialize all values
    void                 isCooking(int state)   // Toggle state during cook
                         { myFlags.isCooking = state; }
    void                 recook(float *values, int nsamples, int thread);
    void                 clearCache();
    void                 fillCache(int cache_start, int cache_end, int thread);
    void                 updateCacheToIncludeSample(int include_sample,
                                                    int thread);
    float                evaluateFromCache(float ltime, int thread);
    bool                 loadTimeGroups(UT_IStream &is);
    void                 saveTimeGroups(ostream &is, int binary) const;

    void                 holdLastKey(float v, bool dotie);

    void                 updateExprFlags();

    // 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;

    std::deque<float>    myCookedValues;        // Segment value cache
    int                  myCacheStart;          // Cache start sample (global)

    // (**) we should just use cubic splines, or at least this should just be a
    // pointer to a structure containing a UT_Vector3 refarray
    UT_Vector3          *mySplineKnots;         // Spline knots
    int                  nKnots;                // Number of knots

    float                inValue, outValue;
    float                inSlope, outSlope;
    float                inAccel, outAccel;

    CH_TimeGroup        *myTimeGroup;

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

    // (*) myEnd is redundant, and is not really that much more efficient
    float                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;
};

#endif

---