TIL_CopResolver.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_CopResolver.h ( TIL Library, C++)
 *
 * COMMENTS:
 *      Class to get a pointer to a COPs raster.  This class is used by the
 *      texture mapping code to resolve names of the form:
 *
 *              op:/comp/cop2net/cop{C,A}[frame]
 *              file:filename{xres,yres}
 *
 *      The frame is optional.  Sub-classes don't need to worry about parsing
 *      out the [frame], this is all handled by the static methods.
 */

#ifndef __TIL_CopResolver__
#define __TIL_CopResolver__

#include "TIL_API.h"
#include "TIL_Defines.h"
#include <IMG/IMG_FileTypes.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_ValArray.h>
#include <UT/UT_WorkBuffer.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_NonCopyable.h>
#include <stddef.h>


#define TIL_DEFAULT_COLOR_PLANE "(Default Color)"
#define TIL_DEFAULT_ALPHA_PLANE "(Default Alpha)"
#define TIL_NO_PLANE            "(None)"

class TIL_Raster;
class TIL_Sequence;
class TIL_ImageSource;
class UT_String;
class IMX_Layer;

class TIL_API TIL_CopResolver
{
public:
    TIL_CopResolver();
    virtual ~TIL_CopResolver();

    UT_NON_COPYABLE(TIL_CopResolver)

    /// Class to push/pop the enable state
    class TIL_API autoEnableCache
        : UT_NonCopyable
    {
    public:
        autoEnableCache(bool enable)
        {
            myOldEnabled = TIL_CopResolver::enableThreadResolverCache(enable);
        }
        ~autoEnableCache()
        {
            TIL_CopResolver::enableThreadResolverCache(myOldEnabled);
        }
    private:
        bool    myOldEnabled;
    };

    /// Class to push/pop the evaluate time
    class TIL_API autoEvaluateTime
        : UT_NonCopyable
    {
    public:
        autoEvaluateTime(fpreal time)
        {
            if (getResolver())
            {
                myOldSeconds = getResolver()->getGlobalTime();
                getResolver()->setGlobalTime(time);
            }
        }
        ~autoEvaluateTime()
        {
            if (getResolver())
            {
                getResolver()->setGlobalTime(myOldSeconds);
            }
        }

    private:
        fpreal          myOldSeconds;
    };

    static void                  setResolver(TIL_CopResolver *resolver);
    static TIL_CopResolver      *getResolver();

    /// Turns on resolver cache for THIS thread.  This allows in process
    /// renders to only hit op: once per render.
    /// Returns old value.
    static bool                  enableThreadResolverCache(bool enable);

    /// Returns true if this thread has the resolver enabled
    static bool                  threadResolverCacheEnabled();

    /// Provides a watermark for the resolver cache, bumped on every
    /// clear.  So if you acquired with a similar water mark you don't
    /// need to check for dirty.
    static exint                 threadResolverCacheWatermark();

    /// Clears any out of date resolver cache, ie, where cop version
    /// doesn't match the stashed version. The force_full_clear flag can be
    /// set to true to clear everything out of the cache. This is necessary
    /// if a time change happens and a time dependent COP texture is in the
    /// cache. The "version" will be unchanged, but we need to clear anyway.
    static void                  clearResolverCache(bool force_full_clear);

    /// Gets node ids of any COPs with textures in the resolver cache.
    static void                  getResolverCacheNodeIds(UT_IntArray &ids);

    // Get an TIL_Raster associated with the COP in the path specified
    // YOU MUST CALL doneWithRaster or returnRaster when done!
    // Do not free it, and do not dangle it.
    static TIL_Raster           *getRaster(const char *fullpath,
                                            int &opid,
                                            int udim_tile = 0,
                                            bool *specific_frame = nullptr);
    static fpreal                getRasterTime(int opid);
    static size_t                getRasterVersion(int opid);

    static fpreal                getTimeFromFrame(fpreal frame);

    /// Tell the resolver we're done with the raster.
    /// Some resolvers will delete rasters, others will hold onto them.  If the
    /// raster actually dirties/deletes the raster, @c doneWithRaster() will
    /// return true.
    static bool                  doneWithRaster(const TIL_Raster *r);

    /// Returns shared IMX_Layer with COW semantics.  Only works
    /// for copernicus, will need getRaster for Images or COP2.
    static UT_SharedPtr<const IMX_Layer> getLayer(
                                        const char *fullpath,
                                        int &opid,
                                        int udim_tile = 0,
                                        bool *specific_frame = nullptr);

    // Returns 1 if the frame is specified in the filename.  The id will be -1
    // if there is no such path.
    static int                   getIdFrame(const char *fullpath, int &id,
                                            fpreal &frame);
    static void                  splitFile(const char *fullpath,
                                           UT_String &name, 
                                           int &xres,int &yres,
                                           float &quality);

    // These split net/node methods are now out of style with networks
    // within networks.  Now you should specify full, absolute, paths.
    static int                   getNodeId(const char *net, const char *node);
    static void                  getNodeRes(const char *net, const char *node,
                                            int &xres, int &yres);
    
    static int                   getNodeId(const char *fullpath);
    static void                  getNodeRes(const char *fullpath, 
                                            int &xres, int &yres);
    
    static void                  getFileRes(const char *file,
                                            int &xres, int &yres);
    
    static int                   splitPath(const char *cpath, int &id,
                                           fpreal &frame,
                                           UT_WorkBuffer &color, int &cindex,
                                           UT_WorkBuffer &alpha, int &aindex,
                                           int &xres, int &yres);

    // builds menus for plane selection (COPs2 only).
    static void                  buildColorMenu(const char *net,
                                                const char *node,
                                                UT_ValArray<char *> &items);

    static void                  buildAlphaMenu(const char *net,
                                                const char *node,
                                                UT_ValArray<char *> &items);

    static bool                  canResolve(const char *fullpath);

    // These methods should really only be used inside the TIL_CopResolver
    // class.  They shouldn't be called directly.
    virtual int          resolveId(const char *fullpath) = 0;
    
    virtual TIL_Raster  *resolveRaster(int id) = 0;
    virtual TIL_Raster  *resolveRasterFrame(int id, fpreal frame,
                                            int xres=0, int yres=0) = 0;
    virtual TIL_Raster  *resolveRasterPlane(int id, fpreal frame,
                                            const char *color, int cindex,
                                            const char *alpha, int aindex,
                                            int xres=0, int yres = 0, 
                                            int udim_tile=0,
                                            TIL_DataFormat f =
                                                TILE_MAX_DATA_FORMAT) = 0;

    virtual UT_SharedPtr<const IMX_Layer> resolveLayer(int id) = 0;
    virtual UT_SharedPtr<const IMX_Layer> resolveLayerFrame(int id, fpreal frame) = 0;
    virtual UT_SharedPtr<const IMX_Layer> resolveLayerPlane(int id,
                                                            fpreal frame,
                                                            const char *color,
                                                            int udim_tile) = 0;
    // Returns whether or not the resolver knows how to handle this path.
    virtual bool         resolveIsPossible(const char *fullpath) = 0;

    /// You gain ownership of a FileRaster and must delete it:
    virtual TIL_Raster  *getFileRaster(const char *file,
                                       IMG_DataType type = IMG_DT_ANY,
                                       int xres = 0, int yres = 0);
    /// You do not gain ownershipo of a node raster, and must call
    /// returnRaster or doneWithRaster on it.
    /// @param fullpath The path to the COP node, eg "op:/path/to/cop"
    /// @param cmenu    The name of the color plane, eg "C" or 
    ///                 TIL_DEFAULT_COLOR_PLANE.
    /// @param amenu    The name of the alpha plane, eg "A" or
    ///                 TIL_DEFAULT_ALPHA_PLANE, or TIL_NO_PLANE.
    /// @param override_frame  If true, the current time frame is used
    ///                 for cooking the COP node to obtain the raster
    ///                 (ie, the following 'frame' parameter is ignored).
    /// @param frame    Frame at which to cook the COP node to obtain the raster
    /// @param f        Desired data format (bit precision) of the returned 
    ///                 raster.
    /// @param xres     Width that the raster will be scaled to. If set to 0,
    ///                 will use the node's default width.
    /// @param yres     Height that the raster will be scaled to. If set to 0,
    ///                 will use the node's default height.
    virtual TIL_Raster  *getNodeRaster(const char *fullpath,
                                       const char *cmenu, const char *amenu,
                                       bool override_frame = false,
                                       fpreal frame = 1.0,
                                       TIL_DataFormat f =
                                           TILE_MAX_DATA_FORMAT,
                                       int xres = 0, int yres = 0);

    virtual void         getRes(int id, int &xres, int &yres);

    virtual TIL_Sequence *getSequence(int id);

    /// This cooks a bunch of planes simulataneously, and adds the created
    /// rasters to 'new_rasters'. You are responsible for deleting them.
    virtual bool        resolveRasters(int id,
                                       const UT_StringArray &plane_names,
                                       fpreal t,
                                       UT_ValArray<TIL_Raster *> &new_rasters,
                                       TIL_DataFormat format=TILE_MAX_DATA_FORMAT);
                                       

    virtual void        buildPlaneMenu(const char *net, const char *node,
                                       UT_ValArray<char *> &items);

    virtual TIL_ImageSource *resolveImageSource(int id);

    /// Caller is finished with the raster for now, so delete memory if
    /// possible.  Returns true if the raster is no longer valid, but false if
    /// the raster hasn't been touched (and is still valid).  This is
    /// implementation dependent.
    virtual bool        returnRaster(const TIL_Raster *raster);

    // If the id returned is really an OP_Node, then this will return 1.
    virtual int         isOpBased();

    virtual fpreal      getTimeForRaster(int id);
    virtual size_t      getVersionForRaster(int id);

    /// Apply the COP_Node unload prevention via the id.
    /// Must be paired.
    virtual void        addAutoUnloadPrevention(int id);
    virtual void        removeAutoUnloadPrevention(int id);

protected:
    // Returns 1 if the frame is defined, 0 otherwise.  It's possible that
    // the name returned may be a reference to the path.  Please harden if
    // you need to keep it around.
    int                 splitPath(const char *fullpath,
                                  UT_String &name, fpreal &frame);

    virtual fpreal      timeFromFrame(fpreal frame);
    virtual fpreal      getGlobalTime();
    virtual void        setGlobalTime(fpreal time);
};

class TIL_API TIL_CopHandle
{
public:
    TIL_CopHandle() = default;
    TIL_CopHandle(const char *filename)
        : myRaster(TIL_CopResolver::getRaster(filename, myOpId, 0, &mySpecificFrame))
    {
    }

    TIL_CopHandle(const TIL_CopHandle &) = delete;
    TIL_CopHandle       &operator=(const TIL_CopHandle &ch) = delete;

    TIL_CopHandle(TIL_CopHandle &&ch)
    {
        moveFrom(ch);
    }
    TIL_CopHandle       &operator=(TIL_CopHandle &&ch)
    {
        moveFrom(ch);
        return *this;
    }
    ~TIL_CopHandle()
    {
        clear();
    }

    bool                 isValid() const { return myRaster != nullptr; }
    explicit             operator bool() const { return isValid(); }
    int                  opid() const { return myOpId; }
    bool                 specificFrame() const { return mySpecificFrame; }
    const TIL_Raster    *raster() const { return myRaster; }
    const TIL_Raster    *operator->() const { return myRaster; }

    void        clear()
    {
        if (myRaster)
            TIL_CopResolver::getResolver()->returnRaster(myRaster);
    }

    bool        resolve(const char *filename)
    {
        clear();
        myRaster = TIL_CopResolver::getRaster(filename, myOpId, 0, &mySpecificFrame);
        return isValid();
    }

private:
    void        moveFrom(TIL_CopHandle &ch)
    {
        myRaster = ch.myRaster;
        myOpId = ch.myOpId;
        mySpecificFrame = ch.mySpecificFrame;
        ch.myRaster = nullptr;
    }

    const TIL_Raster    *myRaster = nullptr;
    int                  myOpId = -1;
    bool                 mySpecificFrame = false;
};

#endif