CL/CL_Clip.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_Clip.h ( Clip Library, C++)
 *
 * COMMENTS:
 *              A collection of raw data tracks
 */

#ifndef __CL_Clip__
#define __CL_Clip__

#include "CL_API.h"
#include <UT/UT_XformOrder.h>
#include <UT/UT_PtrArray.h>
#include <UT/UT_IntArray.h>
#include <UT/UT_String.h>
#include <UT/UT_Color.h>
#include <UT/UT_NameManager.h>
#include <SYS/SYS_Math.h>

#include "CL_Track.h"

class UT_IStream;

typedef void (*CL_InfoCallback)(UT_String &result, void *data, int idx);

class CL_API CL_Clip {

public:

     CL_Clip(int size);
     CL_Clip(const CL_Clip &from);
    ~CL_Clip();

    CL_Clip     &operator= (const CL_Clip &v);

    // a very efficient copy constructor which checks existing
    // data to minimize memory calls

    void         copyContents(const CL_Clip &v, int data, int slerps);


    // these methods when used with caution can increase efficiency
    // when adding tracks

    int                 getCheckDuplicateNames() const
                        { return myCheckDuplicateNames; }

    void                setCheckDuplicateNames(int val)
                        { myCheckDuplicateNames = val; }

    //
    // access/query methods
    //

    void                 clearAndDestroy();

    void                 setStart(float start)
                         { myStart = start; }

    float                getStart(void) const
                         { return myStart; }

    float                getEnd(void) const
                         { return myStart + myTrackLength - 1; }

    int                  getTrackLength(void) const
                         { return myTrackLength; }

    void                 setTrackLength(int length, int clear_extra=0);

    void                 setSampleRate(float rate)
                         { mySampleRate = SYSmax(rate, 1.0e-4); }

    float                getSampleRate(void) const
                         { return mySampleRate; }

    int                  getTrackNames(UT_PtrArray<const char *> &list) const;
    int                  getTracks(CL_TrackListC &list, 
                                   const char *pattern = 0) const;
    int                  getTracks(UT_IntArray &list, const char *pat) const;


    int                  isTimeDependent() const;

    //
    // quaternion (slerp) methods
    // each track can belong to at most 1 slerp triplet
    //

    int                  numSlerps() const;

    int                  copySlerpAttributes(const CL_Clip &v,
                                             int by_name = 0);

    int                  resetSlerps();

    int                  findSlerp(const CL_Track *track, int &idx) const;

    int                  getSlerp(int slerp_idx,
                                  int &x_idx,
                                  int &y_idx,
                                  int &z_idx) const;

    int                  getSlerp(const CL_Track *track,
                                  int &x_idx,
                                  int &y_idx,
                                  int &z_idx) const;

    int                  setSlerp(int x_idx, int y_idx, int z_idx);

    int                  slerpBlend(int slerp_idx,
                                    const float *xvalues,
                                    const float *yvalues,
                                    const float *zvalues,
                                    float start, int len, float base, 
                                    const CL_Track *effect_track);

    int                  slerpBlend(int slerp_idx,
                                    const float *xvalues,
                                    const float *yvalues,
                                    const float *zvalues,
                                    float start, int len, float base,
                                    const CL_SubRange *effect);

    int                  validateSlerps();

    void                        setSlerpOrder(UT_XformOrder::xyzOrder o)
                                { mySRotOrder = o; } 

    UT_XformOrder::xyzOrder     getSlerpOrder() const
                                { return mySRotOrder; }
    
    //
    // track access/creation
    // returns index if name was added, else already exists and returns -1
    //

    void                 removeTrack(int idx);

    CL_Track            *addTrack(const char *name);
    CL_Track            *dupTrackInfo(const CL_Track *,int data_too = 0,
                                      const char *name = 0);
    
    int                  getNumTracks(void) const
                         { return myTracks.entries(); }

    CL_Track            *getTrack(int index)
                         { return (index >= 0 && index < myTracks.entries()) ?
                              myTracks(index) : 0; }

    const CL_Track      *getTrack(int index) const
                         { return (index >= 0 && index < myTracks.entries()) ?
                              myTracks(index) : 0; }

    CL_Track            *getTrack(const char *name, int *index = 0);
    const CL_Track      *getTrack(const char *name, int *index = 0) const;


    //
    // track evaluation
    //


    // These three evaluat methods should only be used when appropriate,
    // it is much more efficient to use the range evaluations

    float        evaluateSingle(const CL_Track *track, float index) const
                 { return track->evaluateSingle(index - myStart); }

    float        evaluateSingleTime(const CL_Track *track, float t) const
                 { return evaluateSingle(track, getIndex(t)); }

    float        evaluateSingleFrame(const CL_Track *track, 
                                     float f, float fps) const
                 { return evaluateSingle(track, getIndexF(f, fps)); }



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

    int          evaluateSlerp(int slerp_idx,
                               float start_index, float stop_index,
                               float *xdata, float *ydata, float *zdata,
                               int size) const;

    void         evaluateTime(const CL_Track *track, 
                          float start_time, float stop_time,
                          float *data, int size) const
                 { evaluate(track, getIndex(start_time), 
                            getIndex(stop_time), data, size); }

    void         resampleTime(const CL_Track *track, 
                              float start_time, float stop_time,
                              float *data, int size) const;

    // Find the max/min height of the track. 
    // If track is nil, find the min max of every track

    void         getHeight(const CL_Track *track, 
                           float start_index, float stop_index,
                           int nsamples, float *imin, float *imax) const;

    // Find the min max of the graph over *each* step interval
    // data should be twice as long as size

    void         evaluateHeightRange(const CL_Track *track, 
                            float start_index, float stop_index,
                            float *data, int size) const;


    // This method extends the clip so that it contains a local index
    // at time t, and returns the index.  The clip may be extended
    // or cycled to accomodate the change.  If delta is given, it
    // returns the index delta of the clips start times.
    // Note all indices are truncated to ints

    int          extendTime(float t, int *delta);


    //
    // convenience methods
    //

    float                getStartTime() const
                         { return getTime(myStart); }

    float                getEndTime() const
                         { return getTime(myStart + myTrackLength - 1); }

    void                 dupAttributes(const CL_Clip &);
    
    //
    // unit conversion methods
    //

    float                getIndex(float time) const
                         { return time*mySampleRate; }

    float                getTime(float index) const
                         { return index / mySampleRate; }

    float                getFrame(float index, float fps) const
                         { return index*fps/mySampleRate + 1;}

    float                getIndexF(float frame, float fps) const
                         { return getTimeF(frame, fps)*mySampleRate; }

    static float         getTimeF(float frame, float fps)
                         { return (frame - 1) / fps; }

    static float         getFrameT(float time, float fps)
                         { return time*fps + 1; }


    //
    // Data operations
    //

    void                 trim(const CL_Clip *clip, float leftpos, 
                              float rightpos, int discard);

    // shorten the tracklength to newlen, if add is 1 then the
    // remaining samples are added to the beginning
    // Returns 1 if newlen is smaller than the beginning length

    int                  crop(int newlen, int add);


    //
    // I/O methods
    // Note: 0 is success, -ve is fail
    //

    int                  save(ostream &os, int binary) const;
    int                  save(const char *nm) const;

    // Returns true on success and false otherwise.
    bool                 load(UT_IStream &is, const char *path=0);

    int                  load(const char *nm);

    int64                getMemoryUsage(void) const;
    int                  info(ostream &os, float fps, float t,
                              int limit=1, CL_InfoCallback cb=0,
                              void *cbdata=0) const;

    static float         fixedDecimal(float num, int digits = 2);
    static void          printNum(ostream &os,float num);

    //
    // This method will reorder our tracks given a new list
    // Should be used with caution.

    void                 reorder(CL_TrackList &list);

    // Given 3 track indices compute the sets of rotations that will
    // eliminate any discontinuites introduced by static cracking.
    // Negative indices are considered constant 0 tracks.
    // Optionally supply a desired beginning rotation

    void                 crackSmooth(int xidx, int yidx, int zidz,
                                     UT_XformOrder order,
                                     int use_hint,
                                     float hx, float hy, float hz);

    // This method will return true if the clips lie over the same
    // range (ie, sample-to-sample correspondence

    int                  isSameRange(const CL_Clip &v) const;

    // These methods can be used to increase performance by reducing
    // memory management

    void                 stashAll();
    void                 destroyStashed();

    char                *newName(const char *oldname) const;

    void                 setDefaults(void);

    // Called by CL_Track to update the name hash table when loaded.
    void                 trackRenamed(CL_Track *track,
                                      const char *oldname);

private:
    float                        mySampleRate;
    float                        myStart;

    int                          myTrackLength;
    CL_TrackList                 myTracks;
    CL_TrackList                 myStashedTracks;

    UT_IntArray                  mySXTracks;    // Quaternion tracks
    UT_IntArray                  mySYTracks;
    UT_IntArray                  mySZTracks;

    UT_XformOrder::xyzOrder      mySRotOrder;

    bool                         myCheckDuplicateNames;

    UT_NameManager<CL_Track*>    myTrackNames;

    bool                         myDisableRemovingTrackNames;

};

typedef UT_PtrArray<CL_Clip *>          CL_ClipList;
typedef UT_PtrArray<const CL_Clip *>    CL_ClipListC;


#endif

---