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.
 *
 * 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 <SYS/SYS_Types.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_ValArray.h>
#include <UT/UT_Color.h>
#include <UT/UT_Options.h>
#include <PXL/PXL_Common.h>
#include <stdlib.h>
#include <limits>

#define TIL_GLOBAL_TIME         (std::numeric_limits<fpreal>::infinity())

class UT_Options;
class UT_String;
class UT_StringHolder;
class UT_TokenString;
class UT_WorkBuffer;
class IMG_TileOptions;
class IMG_Metadata;

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

class STY_StyleSheet;
class OP_Node;

struct TIL_API TIL_CookRegion
{
    int         myID;

    int         myX0, myX1;
    int         myY0, myY1;

    UT_Color    myColor;
    fpreal      myAlpha;
};

typedef UT_Array<TIL_CookRegion> TIL_CookRegionList;

/// Interface that allows another class to override the behaviour of a
/// TIL_ImageSource. The purpose is to allow postprocessing effects such as
/// slap compositing to be applied to any TIL_ImageSource.
class TIL_API TIL_ImageSourcePostprocessor : public UT_NonCopyable
{
public:
    /// The lifetime of the postprocessor must not exceed that of the reference
    /// image source that postprocessing will be applied to.
    TIL_ImageSourcePostprocessor(TIL_ImageSource &source) : mySource(source) {}

    virtual ~TIL_ImageSourcePostprocessor() {}

    virtual void                getImageBounds(const TIL_Plane &plane,
                                               int array_index,
                                               fpreal t, int xres, int yres,
                                               const UT_Options& options,
                                               int &x1, int &y1,
                                               int &x2, int &y2) = 0;

    virtual int                 getImage(TIL_Raster *image,
                                         fpreal t, int xres, int yres,
                                         const TIL_Plane &plane,
                                         int array_index,
                                         int xstart, int ystart,
                                         int xend, int yend, float gamma,
                                         const UT_Options &options,
                                         bool include_alpha,
                                         bool is_interactive,
                                         int fxres, int fyres) = 0;

    virtual const TIL_Sequence *getSequence(fpreal t,
                                            const UT_Options &options) = 0;

    /// If false, the postprocessor will be ignored.
    virtual bool                isEnabled() const = 0;

    /// The version is incremented whenever the postprocessor changes its
    /// behaviour, to indicate that any cached results are outdated.
    virtual int                 getVersion() const { return 0; }

protected:
    /// Get the source which this postprocessor is postprocessing.
    TIL_ImageSource            &getSource() { return mySource; }

private:
    TIL_ImageSource            &mySource;
};

class TIL_API TIL_ImageSource
{
public:
    // Specify how color space transformation should be done
    enum ColorSpaceMode
    {
        CS_HOUDINI,             // Use Houdini and possibly override gamma/LUT
        CS_OCIO_SPACE,          // Use OCIO transform
        CS_OCIO_DISPLAY_VIEW,   // Bake OCIO display/view
    };
    struct TIL_API ColorSpace
    {
        ColorSpace();
        void    setAutomatic() { setAutomatic(1); }
        void    setAutomaticManual(bool convert_space,
                                float gamma,
                                const UT_StringHolder &lut)
        {
            if (convert_space)
                setAutomatic(gamma, lut);
            else
                setManual(gamma, lut);
        }
        void    setManual(float gamma,
                          const UT_StringHolder &lut=UT_StringHolder())
        {
            myMode = CS_HOUDINI;
            myHoudiniAdjust = false;
            myGamma = gamma;
            myLUTFile = lut;
        }
        void    setAutomatic(float gamma,
                             const UT_StringHolder &lut=UT_StringHolder())
        {
            myMode = CS_HOUDINI;
            myHoudiniAdjust = true;
            myGamma = gamma;
            myLUTFile = lut;
        }
        void    setOCIOAutomatic()
        {
            myMode = CS_OCIO_SPACE;
            myOCIODest.clear();
            myOCIOLook.clear();
        }
        void    setOCIO(const UT_StringHolder &dest,
                        const UT_StringHolder &look = UT_StringHolder())
        {
            myMode = CS_OCIO_SPACE;
            myOCIODest = dest;
            myOCIOLook = look;
        }
        void    setOCIODisplayView(const UT_StringHolder &display,
                        const UT_StringHolder &view,
                        bool forward = true)
        {
            myMode = CS_OCIO_DISPLAY_VIEW;
            myOCIODisplay = display;
            myOCIOView = view;
            myOCIOForward = forward;
        }
        bool    ocioAutomatic() const { return myOCIODest.empty(); }
        bool    adjustColorSpace() const { return myHoudiniAdjust; }

        void            dump() const;
        UT_StringHolder toString() const;

        ColorSpaceMode  myMode = CS_OCIO_SPACE;
        float           myGamma = 1.0f;
        UT_StringHolder myLUTFile;
        UT_StringHolder myOCIODest;
        UT_StringHolder myOCIOLook;
        UT_StringHolder myOCIODisplay;
        UT_StringHolder myOCIOView;
        bool            myOCIOForward = true;
        bool            myHoudiniAdjust = true;
    };

    TIL_ImageSource();

    void                         bumpRefCount(int i);

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

    virtual bool willProvideFetcher() const { return false; }

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

    virtual UT_StringHolder getBottomLeftCaption() const { return ""; };
    virtual UT_StringHolder getTopRightCaption() const { return ""; };

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

    virtual bool                 doesImageExist(int /*frame*/,
                                                bool /*adjust*/ = true)
                                                { return true; }

    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 fpreal               getFrameTime(fpreal 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 (cop2 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 bool                 equals(const TIL_ImageSource *) const = 0;

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

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

    virtual bool                 isArbitrarilyZoomable() const { return true; }

    /// Return a completed TIL_Sequence structure with postprocessing, if any.
    const TIL_Sequence *getSequence(fpreal t, const UT_Options &options,
                                    bool skip_postprocessor = false)
    {
        if (myPostprocessor && myPostprocessor->isEnabled() &&
            !skip_postprocessor)
            return myPostprocessor->getSequence(t, options);
        else
            return getSourceSequence(t, options);
    }

    /// Return a completed TIL_Sequence structure without postprocessing.
    virtual const TIL_Sequence  *getSourceSequence(
                                         fpreal t, 
                                         const UT_Options &options) = 0;

    virtual UT_Options getDefaultOptions() const
    {
        return UT_Options();
    }

    const TIL_Sequence  *getSequence(fpreal t, bool skip_postprocessor = false)
    {
        return getSequence(t, getDefaultOptions(), skip_postprocessor);
    }

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

    void                         getImageBounds(const TIL_Plane &plane,
                                                int array_index,
                                                fpreal t, int xres, int yres,
                                                const UT_Options& options,
                                                int &x1, int &y1,
                                                int &x2, int &y2,
                                                bool skip_postprocessor = false)
    {
        if (myPostprocessor && myPostprocessor->isEnabled() &&
            !skip_postprocessor)
            myPostprocessor->getImageBounds(
                plane, array_index, t, xres, yres, options, x1, y1, x2, y2);
        else
            getSourceImageBounds(
                plane, array_index, t, xres, yres, options, x1, y1, x2, y2);
    }

    virtual void                 getSourceImageBounds(const TIL_Plane &plane,
                                                      int array_index, fpreal t,
                                                      int xres, int yres,
                                                      const UT_Options& options,
                                                      int &x1, int &y1,
                                                      int &x2, int &y2);

    // Returns a list of regions currently being cooked
    virtual void                 getCookRegions(TIL_CookRegionList &region) = 0;

    /// Returns true iff there is currently a priority circle active.
    /// If there is, centrex, centrey, and radius are set to those of the circle.
    virtual bool                 getPriorityCircle(float &centrex, float &centrey, float &radius) const
    {
        return false;
    }

    // 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.
    int                          getImage(TIL_Raster *image,
                                         fpreal t, int xres, int yres,
                                         const TIL_Plane &plane,
                                         int array_index,
                                         int xstart, int ystart,
                                         int xend, int yend, float gamma,
                                         const UT_Options &options,
                                         bool include_alpha = false,
                                         bool is_interactive = false,
                                         int fxres = 0, int fyres = 0,
                                         bool skip_postprocessor = false)
    {
        if (myPostprocessor && myPostprocessor->isEnabled() && 
            !skip_postprocessor)
            return myPostprocessor->getImage(
                image, t, xres, yres, plane, array_index, xstart, ystart, xend,
                yend, gamma, options, include_alpha, is_interactive, fxres,
                fyres);
        else
            return getSourceImage(
                image, t, xres, yres, plane, array_index, xstart, ystart, xend,
                yend, gamma, options, include_alpha, is_interactive, fxres,
                fyres);
    }

    virtual int                 getSourceImage(TIL_Raster *image,
                                               fpreal t, int xres, int yres,
                                               const TIL_Plane &plane,
                                               int array_index,
                                               int xstart, int ystart,
                                               int xend, int yend, float gamma,
                                               const UT_Options &,
                                               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, fpreal t);
    virtual void                setComment(const UT_String &comment, fpreal 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,
                                           const ColorSpace &cspace,
                                           void (*info)(void*, const char*),
                                           void *data,
                                           bool suppress_summary_dialog,
                                           bool overwrite);

    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,
                                           const ColorSpace &cspace,
                                           void (*info)(void*, const char*),
                                           void *data,
                                           bool suppress_summary_dialog,
                                           bool overwrite);

    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 size_t              getVersion()                    { return 1; }
    virtual bool                isFrameLocked(fpreal /*t*/) const { return false; }
    virtual bool                isAnythingLocked() const        { return false; }
    virtual bool                isPlaneLocked(const TIL_Plane *,
                                              fpreal /*t*/) const { return false; }
    virtual const TIL_Plane     *getPreviewPlane(int /*index*/) { return nullptr; }

    virtual void                 setMouseLocation(int mx, int my,
                                                  float radius = 64.0f);

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

    virtual bool                 getColorCurves(const char *planename,
                                                int array, fpreal 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(int slot) const;
    virtual bool                 runPixelScript(int px, int py, int slot);

    // Returns true if the image source is stereoscopic, ie, it can provide
    // left / right images (as two separate planes).
    virtual bool                 isStereoscopicSource(fpreal t) const;
    virtual int                  getLeftPlaneIndex(fpreal t) const;
    virtual const char          *getLeftPlaneName(fpreal t) const;
    virtual int                  getRightPlaneIndex(fpreal t) const;
    virtual const char          *getRightPlaneName(fpreal t) const;

    // NOTE: This level has nothing to destruct.
    virtual int64                getMemoryUsage(bool inclusive) const = 0;

    // Return image metadata
    virtual const IMG_Metadata  *getMetadata(int frame) const = 0;
    // Return metadata for a given plane
    virtual const IMG_Metadata  *getPlaneMetadata(int frame,
                                            const UT_StringRef &planename) const;

    virtual fpreal getRenderTime(int frame) const
    { return -1.0; }

    virtual int64 getPeakMemUsage(int frame) const
    { return 0; }

    virtual OP_Node* getOp() const
    { return 0; }

    virtual bool  getPreferredViewingPlane(UT_WorkBuffer &buf) const
                                 { return false; }

    // Returns the style sheet json string at a given pixel.
    // By default, there is none
    virtual bool getStyleSheetJSON(int x, int y, UT_StringHolder& str)
                                 { return false; }

    // Returns the style sheet object at a given pixel.
    // By default there is none
    virtual STY_StyleSheet* getStyleSheet(int x, int y)
                                { return NULL; }

    // Returns the material node at a given pixel
    virtual OP_Node* getMaterialNode(int x, int y)
                                { return NULL; }

    // Indicates that an auto update is being performed
    virtual void onAutoUpdate() {}

    /// Set the postprocessor, which will be checked and called when applicable,
    /// providing an opportunity to override the behaviour of this image source.
    /// The constructor for the postprocessor type T must accept a reference to
    /// the owning TIL_ImageSource as the first argument.
    /// @returns The newly created postprocessor.
    /// @see TIL_ImageSourcePostprocessor
    template <typename T, typename... Args>
    T                           *setPostprocessor(Args &&...args)
    {
        SYS_STATIC_ASSERT_MSG(
            std::is_convertible_v<T*, TIL_ImageSourcePostprocessor*>,
            "T must inherit from the TIL_ImageSourcePostprocessor interface.");
        myPostprocessor = UTmakeUnique<T>(*this, std::forward<Args>(args)...);
        return static_cast<T*>(myPostprocessor.get());
    }

    /// Get the current postprocessor.
    /// @see setPostprocessor
    const TIL_ImageSourcePostprocessor*
                                 getPostprocessor() const
                                 { return myPostprocessor.get(); }

    TIL_ImageSourcePostprocessor*
                                 getPostprocessor()
                                 { return myPostprocessor.get(); }

protected:
    virtual                     ~TIL_ImageSource();
                                 UT_NON_COPYABLE(TIL_ImageSource)
private:
    int                          myRefCount;
    bool                         myValidFlag;

    UT_UniquePtr<TIL_ImageSourcePostprocessor> 
                                 myPostprocessor;
};

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

    UT_NON_COPYABLE(TIL_Access)

    bool        isOpen() const { return myOpen; }

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

#endif