CL/CL_Track.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:
 *      Rob Bairos,,
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        CL_Track.h ( Clip Library, C++)
 *
 * COMMENTS:
 *              A set of raw data
 *
 */


#ifndef __CL_Track__
#define __CL_Track__

#include "CL_API.h"
#include <UT/UT_PtrArray.h>
#include <UT/UT_FloatArray.h>
#include <UT/UT_String.h>

class   UT_IStream;
class   CL_Clip;
class   CL_Track;
class   CL_SubRange;

typedef UT_PtrArray<CL_Track *>         CL_TrackList;
typedef UT_PtrArray<const CL_Track *>   CL_TrackListC;

//
// how to evaluate the track outside its defined range
//

typedef enum {
    CL_TRACK_HOLD,      // Track is start/end value before/after
    CL_TRACK_SLOPE,     // Track extends at start/end slope
    CL_TRACK_CYCLE,     // Track wraps to defined range (repeat)
    CL_TRACK_MIRROR,    // Track wraps+reflects to defined range
    CL_TRACK_DEFAULT,   // Track is default value beyond defined range
    CL_TRACK_CYCLE_STEP // Track is cycled and advanced
} CL_TrackOutside;

enum CL_TrackLimitMethod
{
    CL_TRACK_LIMIT_OFF,
    CL_TRACK_LIMIT_CLAMP,
    CL_TRACK_LIMIT_LOOP,
    CL_TRACK_LIMIT_ZIGZAG
};

enum CL_QuantizeValueMethod
{
    CL_QUANTIZE_VALUE_OFF,
    CL_QUANTIZE_VALUE_CEILING,
    CL_QUANTIZE_VALUE_FLOOR, 
    CL_QUANTIZE_VALUE_ROUND
};

enum CL_TrackResampleMethod
{
    CL_TRACK_INTERP_NONE,
    CL_TRACK_INTERP_LINEAR,
    CL_TRACK_INTERP_CUBIC,
    CL_TRACK_INTERP_EDGE_PRESERVE
};


class CL_API CL_Track {

public:

     CL_Track(CL_Clip &dad, const CL_Track &from);
     CL_Track(CL_Clip &dad, const char *name);
    ~CL_Track();


    CL_Track            &operator= (const CL_Track &from);

    void                 init(CL_Clip &dad, const char *name);

    float               *getData()
                         { return myData.array(); }

    const float         *getData() const
                         { return myData.getRawArray(); }

    int                  getTrackLength() const
                         { return myData.entries(); }

    const UT_String     &getName() const
                         { return myName; }


    //
    // Warning this method must be used with extreme caution
    void                 setName(const char *);

    // These methods increase the parent clip add methods dramatically
    // Of course, the *right* thing to do would be fore the parent
    // clip to keep a UT_SymbolTable of all channel names.  But
    // it is so much more fun to try and accellerate O(n^2)
    // algorithms than actually make them not O(n^2)

    unsigned short       getNameHash() const
                         { 
                            return myNameHash; 
                         }

    unsigned short       getNameBaseLength() const
                         { return myNameBaseLength; }

    unsigned short       getNameBaseHash() const
                         { return myNameBaseHash; }

    int                  getNameNumber() const
                         { 
                             if (myNameNumberDirty)
                                 ((CL_Track *)this)->calcNameNumber();
                             return myNameNumber; 
                         }

    static void          getNameComposition(const char *name,
                                            unsigned short &base_length,
                                            unsigned short &base_hash);


    const char          *info(float t, const char *prefix = 0,
                              const char *suffix = 0) const;

    int                  isTimeDependent() const;

    int                  isWithinRange(float low,float hi,int completely=1) const;

    // these methods define the evaluation of the array outside
    // its defined interval

    void                setLeft(CL_TrackOutside type);
    void                setRight(CL_TrackOutside type);
    void                setDefault(float value);

    CL_Clip             *getClip(void)
                         { return myParent; }

    const CL_Clip       *getClip(void) const
                         { return myParent; }


    const char          *getLeft(void) const;
    const char          *getRight(void) const;

    int64                getMemoryUsage(void) const;

    void                 getExtendCond(CL_TrackOutside &left, 
                                       CL_TrackOutside &right) const;
    float                getDefault() const
                         { return myDefault; }

    void                 dupAttributes(const CL_Track *,
                                       int data_too=0, int name_too=0);

    // data methods

    void                 reverse();
    void                 constant(float value=0);
    void                 cycle(int howmany);

    int                  convolve(const CL_Track &t1, const CL_Track &t2,
                                  int add = 0);

    int                  convolveCenter(float *data2, int n2, int passes = 1);
    int                  convolveCenterDirect(float *data2, int n2, int passes);
    int                  convolveCenterFFT(float *data2,int n2,int passes);

    int                  copyStamp(const CL_Track &t1, float toffset, int clr);

    int                  getThresholdTimes(float thresh, 
                                           UT_FloatArray &toffsets,
                                           UT_FloatArray &values) const;

    void                 despike(float tol, float effect=1.0f, int maxwidth=1);

    void                 blend(float start, const float *values, int len,
                               float base, const CL_SubRange *effect,
                               float cycle);

    void                 blend(float start, const float *values, int len,
                               float base, const CL_Track *effect_track,
                               float cycle);

    void                 limitValues(float max, float min, 
                                     CL_TrackLimitMethod method, 
                                     int start, int end);

    static float         limitValue(float max, float min,
                                    CL_TrackLimitMethod method, float v);

    // Resample from the given source into ourselves

    int                  resample(const float *values, int num, 
                                  CL_TrackResampleMethod method, 
                                  int constant_area, int iscycle = 0, 
                                  float cycle = 0);

    // Resample from ourselves into the given destination

    int                  resample(float *data, int size, int start, int end,
                                  CL_TrackResampleMethod method,
                                  int constant_area,
                                  int iscycle = 0,
                                  float cycle = 0) const;

    void                 quantizeValue(float max, float min,
                                       CL_QuantizeValueMethod method,
                                       float step, float offset,
                                       int clamp, int start, int end);

    void                 normalize();
    void                 absolute();
    void                 smoothRotate(float delta = 180.0f);


    // Filter size must be a power of 2, and the filter itself should be
    // in the form of a DFT filter
    // the callback function takes parms 'node' 'size', 'freq step'
    //   'mag filter' 'phase filter'
    // 'index' and 'chunk' -- mag & phase filter are the arrays to be filted
    // by the callback function. Called before filtering each chunk, if
    // not null.
    void                 filterFrequency(int filter_size,
                                         float freqstep,
                                         float overlap,
                                         float discard,
                                         float *filter,
                                         float *phase_filter = 0,
                                         void (*filter_design)(void *,int,float,float *,float *,int,int)=0,
                                         void *node = 0,
                                         int    doblend = 1);

    
    void                 pitchShift(float shift,int chunk,
                                    const CL_Track *animate=0,
                                    float (*callback)(void *,int,int)=0,
                                    void *node=0);

    //  This actually is a DFT followed by a multipy, and an IDFT
    void                 fastConvolve(int chunk,float *data);


    // This method allows this track to assume the same data array as 'track'.
    // They will share the same buffer until unalias() is called. aliasTrack()
    // may be called multiple times before unalias() is called. Both tracks
    // must have the same number of samples.
    void                 aliasTrack(CL_Track &track);
    void                 unalias();
    bool                 isAliased() const { return myPrevDataAlias != 0; }

    // swaps data with 'track'.
    void                 swapData(CL_Track &track);

private:

    // should only be called by CL_Clip

    void                 evaluate(float start_index, float stop_index,
                                  float *data, int size) const;


    // this single version is much less efficient than the range methods
    float                evaluateSingle(float index) const;

    // optimizied evaluations which work on a range
    // entire range is evaluated with a particular extend condition

    void                 evaluatePortion(float i0, float i1, 
                                         float start_index, float
                                         stop_index, float *data, int size, 
                                         float *fix, int portion) const;

    void                 evaluateCenter(float start_index, float stop_index,
                                        float *data, int size) const;
                                                             
    void                 evaluateLeftSlope(float start_index, float stop_index,
                                           float *data, int size) const;
    void                 evaluateRightSlope(float start_index, float stop_index,
                                            float *data, int size) const;

    void                 evaluateLeftHold(float *data, int size) const;
    void                 evaluateRightHold(float *data, int size) const;

    void                 evaluateDefault(float *data, int size) const;
    void                 evaluateCycle(float start_index, float stop_index,
                                       float *data, int size) const;
    void                 evaluateMirror(float start_index, float stop_index,
                                        float *data, int size) const;
    void                 evaluateCycleStep(float start_index, float stop_index,
                                           float *data, int size) const;

    void                 updateName();

    
    //
    // I/O methods
    //
    class CL_API BinaryIO
    {
        public:
            BinaryIO() : myTaintVersion(0), myOffset(0), myDoubleFlag(false) {}

            int                  myTaintVersion;
            int                  myOffset;
            bool                 myDoubleFlag;
    };

    int                  save(ostream &os, bool binary,
                              BinaryIO *binary_options) const;
    bool                 load(UT_IStream &is, BinaryIO *binary_options,
                              const char *path = 0);

    void                 setDefaults();
    void                 calcNameNumber();

    UT_String            myName;
    UT_FloatArray        myData;
    CL_Clip             *myParent;

    unsigned short       myNameBaseLength;
    unsigned short       myNameNumber;
    unsigned short       myNameBaseHash;

    unsigned short       myNameHash;
    char                 myNameNumberDirty;


    CL_TrackOutside      myLeft;        // eval method outside range
    CL_TrackOutside      myRight;       // eval method outside range
    float                myDefault;     // used in CL_TRACK_DEFAULT
    float               *myPrevDataAlias; // used by alias/unalias.

    friend               class CL_Clip;
    friend               class CL_AsciiClipReader;
    friend               class CL_AsciiClipWriter;
    friend               class CL_BinaryClipReader;
    friend               class CL_BinaryClipWriter;
};


#endif

---