TIL/TIL_ImageSource.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 Alexander
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        TIL_ImageSource.h (TIL library, C++)
 *
 * COMMENTS:
 *      This is the base class for an image source (ie, COP for Houdini,
 *      or disk files for a standalone viewer). 
 */

#ifndef TIL_IMAGESOURCE_H
#define TIL_IMAGESOURCE_H

#include "TIL_API.h"
#include <stdlib.h>

#define TIL_GLOBAL_TIME         1.23456e18F

class UT_String;
class UT_TokenString;
class UT_WorkBuffer;
class IMG_TileOptions;

class TIL_Plane;
class TIL_Raster;
class TIL_Sequence;
class TIL_ColorCurves;

class TIL_API TIL_ImageSource
{
public:
                                 TIL_ImageSource();

    void                         bumpRefCount(int i);

    void                         invalidate()    { myValidFlag = false; }
    bool                         isValid() const { return myValidFlag; }

    // global stuff... (not source specific).
    virtual float                getGlobalTime() =0;
    virtual float                getSampleRate() =0;
    virtual float                getStartTime() =0;
    virtual float                getEndTime() =0;

    // returns the image index (0 to length-1) or the frame (start to end)
    // based on the current time.
    int                          getImageIndexFromTime(float t);
    int                          getFrameFromTime(float t);

    virtual int                  doesImageExist(int /*frame*/,
                                                bool /*adjust*/ = true)
                                                { return 1; }
    
    virtual int                  getActualFrame(int frame) { return frame; }
    virtual void                 removeFrame(int /*frame*/) { }
    virtual void                 addFrame(int /*frame*/) { }
    virtual void                 removeSequence() {}
    virtual bool                 canAddFrame() { return false; }

    virtual bool                 isNetwork() { return false; }

    // allows time mapping (mostly for disk files).
    virtual float                getFrameTime(float t,
                                              bool /*shift_only*/ = false,
                                              const TIL_Sequence * /*ref*/ = 0)
                                 { return t; }
    virtual int                  getFrameShift(int fr,
                                               bool /*shift_only*/ = false,
                                               const TIL_Sequence * /*ref*/ =0)
                                 { return fr; }

    // Allows you to remap a frame for information purposes (like the Houdini
    // frame number when rendered to mplay).
    virtual int                 getApparentFrame(int fr) { return fr; }
    
     // name of the source (cop name, disk file).
    virtual const char          *getName() = 0;
    virtual void                 getFullName(UT_String &name) = 0;
    virtual void                 getFrameName(int frame, UT_String &name);

    // ah, well.. whaddayathink
    virtual int                  equals(const TIL_ImageSource *) = 0;

    // Called to open the source (return 0 on failure). if reset is set, all
    // errors will be cleared.
    virtual int                  open(short & /*key*/, 
                                      int /*reset*/ = 0,
                                      float /*t*/ = TIL_GLOBAL_TIME)
                                 { return 0; }

    // called to close the source.
    virtual void                close(short /*key*/) { ; }

    // returns true if the res & data type are constant for the sequence.
    virtual bool                 isConstantSequence() const { return false; }

    // return a completed TIL_Sequence structure.
    virtual const TIL_Sequence  *getSequence(float t) = 0;

    // return an identifier that can be used to identify a single frame
    // out of the source, unique across multiple sources. 
    virtual UT_TokenString      *getID(float t, int xres, int yres,
                                       const TIL_Plane &plane,
                                       int array_index) = 0;

    virtual void                 getImageBounds(const TIL_Plane &plane,
                                                int array_index,
                                                float t, int xres, int yres,
                                                int &x1, int &y1,
                                                int &x2, int &y2);

    // return an int that uniquely identifies the source. 
    virtual int                  getID() const = 0;

    // fill the TIL_Raster with the appropriate image (ie, cook it).
    // return 0 on failure.
    virtual int                 getImage(TIL_Raster *image,
                                         float t, int xres, int yres,
                                         const TIL_Plane &plane,
                                         int array_index,
                                         int xstart, int ystart,
                                         int xend, int yend, float gamma,
                                         bool include_alpha = false,
                                         bool is_interactive = false,
                                         int fxres = 0, int fyres = 0) = 0;

    virtual void                getInfo(UT_WorkBuffer &infotext);
    virtual void                getComment(UT_String &comment, float t);
    virtual void                setComment(const UT_String &comment, float t);

    // There's duplicate information in the IMG_TileOptions class, we only use
    // the Format and FormatOptions in the writing process.
    virtual int                 writeImage(const char *filename,
                                           const IMG_TileOptions *finfo,
                                           const TIL_Sequence *, int step =1,
                                           const char *uselut = 0,
                                           float gamma = 1.0F,
                                           void (*info)(void*, const char*)=0,
                                           void *data=0,
                                           bool suppress_summary_dialog=false);

    virtual int                 writeImage(const char *filename,
                                           const IMG_TileOptions *finfo,
                                           int xres, int yres,
                                           const char *color,
                                           const char *alpha,
                                           int start, int end, int step =1,
                                           const char *uselut = 0,
                                           float gamma = 1.0F,
                                           void (*info)(void*, const char*)=0,
                                           void *data =0,
                                           bool suppress_summary_dialog=false);

    virtual void                writeImageComplete(int successcount,
                                               int failcount,
                                               const UT_String &failedfiles);

    // normally, once you're done with an image, it will stay cached if there's
    // room. The parm is the frame index. Return false to have it deallocated
    // immediately.
    virtual bool                isCachingNeeded(int  ) const { return true; }
    
    // only really needed for COPs. 
    virtual unsigned long       getVersion()                    { return 1; }
    virtual int                 isFrameLocked(float /*t*/)      { return 0; }
    virtual int                 isAnythingLocked()              { return 0; }
    virtual int                 isPlaneLocked(const TIL_Plane *,
                                              float /*t*/)      { return 0; }
    virtual const TIL_Plane     *getPreviewPlane(int /*index*/) { return 0; }

    virtual void                 setMouseLocation(int mx, int my);

    virtual void                 bumpVersion(bool ) { }
    virtual bool                 isSlowOperation() const    { return false; }

    virtual bool                 getColorCurves(const char *planename,
                                                int array, float t, 
                                                TIL_ColorCurves &curves,
                                                UT_String &first,
                                                bool allnodes, int comp=-1,
                                                bool natural_range = true,
                                                float start = 0.0f,
                                                float end   = 1.0f,
                                                int evalpoints = 0);
    
    virtual bool                 allowUserSelection() const { return false; }

    virtual TIL_ImageSource     *selectParentSource(int px, int py,
                                                    const char *planename,
                                                    int array_index);

    // Allow the source to have a callback invoked.  The function should return
    // true if a script is run
    virtual bool                 hasPixelScript() const;
    virtual bool                 runPixelScript(int px, int py);

    // Returns true if the image source is stereoscopic, ie, it can provide
    // left / right images (as two separate planes).
    virtual bool                 isStereoscopicSource(float t) const;
    virtual int                  getLeftPlaneIndex(float t) const;
    virtual const char          *getLeftPlaneName(float t) const;
    virtual int                  getRightPlaneIndex(float t) const;
    virtual const char          *getRightPlaneName(float t) const;
    
protected:    
    virtual                     ~TIL_ImageSource();
    
private:
    TIL_ImageSource &            operator=(const TIL_ImageSource &);

    int                          myRefCount;
    bool                         myValidFlag;
};


// Convenience class for opening and closing a source.
class TIL_API TIL_Access
{
public:
     TIL_Access(TIL_ImageSource &source, int reset=0,
                float t = TIL_GLOBAL_TIME);
    ~TIL_Access();

    bool        isOpen() const { return myOpen; }
    
private:
    TIL_Access &         operator=(const TIL_Access &);

    TIL_ImageSource     &mySource;
    short                myAccessKey;
    bool                 myOpen;
};

#endif

---