TIL_TextureMap.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:        UT library (C++)
 *
 * COMMENTS:    There are two classes defined here.  If you're using one,
 *              you'll use the other:
 *                 TIL_TextureMap   - a texture map.  It knows how to lookup
 *                                      it's raster for you.
 *                 TIL_TextureCache - The cache control specifies parameters
 *                                      used in the internal cache for
 *                                      texture maps
 *                                   This class is simply a verb class which
 *                                      accesses an internal class.
 *
 *              The only way to get at the texture cache is through a
 *              TIL_TextureMap.  This allows the cache to keep a good
 *              record of references.  The rasters are loaded on demand
 *              which means that unless you look up a color, you don't
 *              load the raster.
 *
 */

#ifndef _TIL_TextureMap_h_
#define _TIL_TextureMap_h_

#include "TIL_API.h"
#include <IMG/IMG_FileTypes.h>
#include <IMG/IMG_TextureFilter.h>
#include <UT/UT_Array.h>
#include <UT/UT_FilterType.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_Rect.h>
#include <UT/UT_Set.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_String.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_Vector2.h>
#include <UT/UT_Vector3.h>
#include <UT/UT_Vector4.h>

class TIL_Raster;
class TIL_TextureMap;
class TIL_Cdf2D;
class IMG_TTFilterInfo;
class IMG_File;
class IMG_FileTTMap;
class UT_Options;
class til_Map;                  // Internal structure
class til_Lookup;               // Internal structure
class TIL_TextureRaster;        // Not exposed through HDK
class UT_Filter;
class UT_OpCaller;

//
//  An enum for bump map computation type
//

enum TIL_BUMP_COMPUTE_TYPE
{
        TIL_BUMP_PRECOMPUTE,
        TIL_BUMP_COMPUTE_R,
        TIL_BUMP_COMPUTE_G,
        TIL_BUMP_COMPUTE_B,
        TIL_BUMP_COMPUTE_A,
        TIL_BUMP_COMPUTE_LUM
};

enum TIL_PtexOrient
{
    TIL_PTEX_COMPLEMENT_S       = 0x01, // Complement the S coordinate
    TIL_PTEX_COMPLEMENT_T       = 0x02, // Complement the T coordinate
    TIL_PTEX_SWAP_ST            = 0x04, // Swap S/T coordinates

    // Orientation matching http://ptex.us
    TIL_PTEX_NATIVE             = 0,

    // The following are based on experimental evidence and may not be correct
    // Mudbox has the t coordinate flipped and the ST coordinats swapped
    TIL_PTEX_MUDBOX             = TIL_PTEX_SWAP_ST | TIL_PTEX_COMPLEMENT_T,
};

class TIL_API TIL_MissingTexture
{
public:
    /// Callback for missing texture
    TIL_MissingTexture() {}
    virtual ~TIL_MissingTexture();
    UT_NON_COPYABLE(TIL_MissingTexture)

    /// Callback invoked when a texture can't be found.  It's possible @c
    /// filename may be a @c nullptr.
    virtual void        missingTexture(const char *filename) const {};

    /// Callback invoked when a texture is converted internally to a .rat
    virtual void        convertToRat(const char *filename, bool ies) const {};
};

class TIL_API TIL_TextureMapStat {
public:
    const char          *myFilename;            // Filename for the raster
    int                  myXres, myYres;        // Resolution
    int                  myRampNodes;
    int                  myImageCount;          // Image count...
    int64                myMemory;
    int                  myOwnership;           // If it's a COP, this will be 0
};

class TIL_API TIL_TextureOptions {
public:
    TIL_TextureOptions()
        : myOptions(NULL)
        , myShared()
    { }
    TIL_TextureOptions(const UT_Options *options)
        : myOptions(options)
        , myShared()
    { }
    TIL_TextureOptions(const UT_Options *options,
                       UT_SharedPtr<UT_Options> shared)
        : myOptions(options)
        , myShared(shared)
    { }
    TIL_TextureOptions(const TIL_TextureOptions &opts)
        : myOptions(opts.myOptions)
        , myShared(opts.myShared)
    { }
    ~TIL_TextureOptions();

    const TIL_TextureOptions    &operator=(const TIL_TextureOptions &src)
                                {
                                    if (&src != this)
                                    {
                                        myShared = src.myShared;
                                        myOptions = src.myOptions;
                                    }
                                    return *this;
                                }

    const UT_Options    *get() const    { return myOptions; }

private:
     const UT_Options           *myOptions;
     UT_SharedPtr<UT_Options>    myShared;
};

//
//  The texture cache control class
//
class TIL_API TIL_TextureCache
{
public:
//
//  Limit the raster size of a texture map to the size specified
    static int          getMaxWidth();
    static int          getMaxHeight();
    static void         setMaxSize(int w=256, int h=256);

//
//  Limit the maximum number of maps in core at once
    static int          getCacheSize();
    static void         setCacheSize(int size=100);

//  Limit the maps to max amount of memory (in Mb)
    static int64        getCacheMemSize();
    static void         setCacheMemSize(int64 sizeinmb);

//
//  Query methods for the cache.
    static void         getImageStat(UT_Array<TIL_TextureMapStat> &stats);

    // Simple method to get memory usage
    static int64         getMemoryUsage();

    static void         getConversionStats(exint &num_conversions,
                                exint &current_memory,
                                exint &peak_memory);

    static void         storeTexture(const UT_StringHolder &name,
                                    UT_UniquePtr<TIL_TextureRaster> map);
    static void         eraseTexture(const UT_StringHolder &name);

    struct TIL_API OIIOStats
    {
        UT_StringHolder searchpath;

        int             max_open_files = 0;
        float           max_memory_MB = 0;
        int             autotile = 0;
        int             autoscanline = 0;
        int             automip = 0;
        int             forcefloat = 0;
        int             accept_untiled = 0;
        int             accept_unmipped = 0;
        int             deduplicate = 0;
        int             unassociatedalpha = 0;
        int             failure_retries = 0;
        int             max_errors_per_file = 0;
        int             trust_file_extensions = 0;
        int             max_mip_res = 0;

        // Read-only options
        int64           cache_memory_used = 0;
        int             tiles_created = 0;
        int             tiles_current = 0;
        int             tiles_peak = 0;
        int             open_files_created = 0;
        int             open_files_current = 0;
        int             open_files_peak = 0;

        int64           image_size = 0;        // total size
        int64           file_size = 0;         // total size on disk
        int64           bytes_read = 0;        // bytes read
        int             unique_files = 0;
        float           fileio_time = 0;
        float           fileopen_time = 0;
    };
    static bool                 getOIIOStats(OIIOStats &stats);

    static UT_StringHolder      getOIIOStats(int level=1);

    struct TIL_API PtexStats
    {
        int64   myMemUsed;
        int64   myPeakMemUsed;
        int64   myFilesOpen;
        int64   myPeakFilesOpen;
        int64   myFilesAccessed;
        int64   myFileReopens;
        int64   myBlockReads;
    };
    static void                 getPtexStats(PtexStats &stats);

    // List of all invalid textures since the cache was last cleared
    struct TIL_API ErrorFiles
        : public UT_NonCopyable
    {
        ErrorFiles();
        ~ErrorFiles();

        const UT_Set<UT_StringHolder>   *myFileList;
    };
    static ErrorFiles  getErrorFiles();

//
// The version of the cache updates everytime something in it changes
// or is removed.  This way we can clear display lists, etc.
    static int           getVersion();

    static void          bumpVersion();

    ///  Close all file descriptors, without flushing the cache
    static void         closeAllFiles();

//
//  Flush all maps out of core.
    static void clearCache(int only_out_of_date=0);

//
//  Flush a map  by name.
    static void clearCache(const UT_StringRef &mapname);

//
//  Set auto-flushing of the cache.  That is, as soon as the map is
//      dereferenced completely, flush it from the cache.  This can slow
//      some applications down.
    static int          getAutoFlush();
    static void         setAutoFlush(int onOff);

//
// Inform the cache of any deleted rasters that it may be referencing
    static void         rasterDied(TIL_Raster *raster);
    static void         imageDataDied(void *imagedata); // for COPs 1.

//
// If a texture map is not a .rat file, exit with an error on load.
    static void         setNonRATError(bool on);
    static bool         getNonRATError();
};

class til_PtexData;
class til_OIIOData;

class TIL_API TIL_TextureHandle
{
public:
     TIL_TextureHandle()
         : myLookup(0)
     {
     }

    const til_Lookup    *lookup() const         { return myLookup.get(); }

private:
    TIL_TextureHandle(const UT_SharedPtr<til_Lookup> &lookup);

    UT_SharedPtr<til_Lookup>     myLookup;
    friend class                 TIL_TextureMap;
};

class TIL_API TIL_TextureMap
{
public:
    // Information about a texture
    struct TextureInfo
    {
        void    dump() const;

        bool    isValid() const { return myMipMapRes.size() > 0; }
        bool    mipMapped() const { return myMipMapRes.size() > 1; }
        int     mipCount() const { return myMipMapRes.size(); }

        UT_Array<UT_Vector2i>   myMipMapRes;
        PXL_DataFormat          myDataFormat = PXL_INT8;
        int                     myChannelCount = 0;
        int                     myMipOffset = 0;
    };

    struct forceDiskCache
    {
        forceDiskCache(bool enable=true)
            : myEnable(enable)
        {
        }
        bool    myEnable;
    };

    TIL_TextureMap(const UT_StringHolder &mapname = UT_StringHolder(),
                    const char *relativeTo = nullptr,
                    TIL_Raster *rp = nullptr);

    TIL_TextureMap(const UT_StringHolder &mapname, const forceDiskCache &);

    virtual ~TIL_TextureMap();

    UT_NON_COPYABLE(TIL_TextureMap)

    /// Returns whether a filename has UDIM formatting characters
    static bool                 hasUDIM(const char *format);

    /// Expand a file containing %(UDIM)d, %(U)d or %(V)d formatting characters
    /// The @c iu and @c iv parameters passed in are the zero-based coordinates
    /// (i.e. UDIM == (1000 + iu+1+ 10*iv) and U == iu+1).
    ///
    /// For example:  expandUDIM("%s/%s_%(UDIM)%d_%(U)02d_%(V)d.rat", 3, 7)
    /// will return "%s/%s_1074_04_8.rat"
    static UT_StringHolder      expandUDIM(const char *format, int iu, int iv);

    /// Set the callback for missing textures.  This returns the previous
    /// callback.
    static const TIL_MissingTexture     *setMissingTexture(
                                                const TIL_MissingTexture *m);

    /// Access the missing texture callback without having to set it
    static const TIL_MissingTexture     *getMissingTexture();

    /// Check existence of a texture map.
    static bool         mapExists(const UT_StringRef &name);

    /// Check existence of a UDIM directory.  The path passed in should be the
    /// expanded UDIM texture path.  This allows you to check for paths where
    /// the <UDIM> token is in the directory name (rather than the filename).
    ///
    /// If the directory is missing, this will print a warning and notify the
    /// missing texture callback.
    static bool         validUDIMDirectory(const UT_StringRef &udim_name);

    void                 setOpCaller(UT_OpCaller *c)    { myCaller = c; }
    void                 setMap(const UT_StringHolder &name,
                                const char *relativeTo,
                                TIL_Raster *rp = nullptr,
                                bool always_resolve = true,
                                bool force_disk_cache = false);
    const UT_StringHolder       &getMap() const;

    void                 clearRaster();
    void                 forceReload();
    const TIL_Raster    *getOGLRaster();
    TIL_TextureOptions   getTextureOptions() const;
    void                 getResolution(int &x, int &y)
                         { getResolution(getLookupHandle(), x, y); }
    int                  getNChannels() const;

    // The color channel name may be NULL representing the default channel
    void                         setColorChannelName(const UT_StringHolder &n);
    const UT_StringHolder       &getColorChannelName() const;

    // Set the face index
    void                 setFaceIndex(int index);
    int                  getFaceIndex() const   { return myFaceIndex; }
    // Set the subimage for OIIO lookup
    void                setSubimage(int i) { mySubimage = i; }
    int                 getSubimage() const { return mySubimage; }
    // Set the channel offset (offset into the tuple data)
    void                 setPtexChannel(int index);
    int                  getPtexChannel() const { return myPtexChannel; }

    // ptexture orientation
    TIL_PtexOrient       ptexOrient() const     { return myPtexOrient; }
    void                 setPtexOrient(TIL_PtexOrient o) { myPtexOrient = o; }

    void                 setFilter(UT_FilterType filter, float xw, float yw);
    void                 setXFilter(UT_FilterType filter);
    void                 setYFilter(UT_FilterType filter);
    void                 setFilterWidths(float xwidth, float ywidth);
    void                 setFilterBlurs(float xblur, float yblur);
    void                 setMipInterpolate(int onoff);
    void                 setWrapMode(UT_FilterWrap uwrap, UT_FilterWrap vwrap,
                                        const UT_Vector4 &border);
    void                 setDeepInterp(IMG_DeepInterp interp);
    void                 setBeerLambert(bool beerlambert);
    void                 setSourceColorSpace(IMG_ColorSpace convert);
    void                 setFilterMode(IMG_TextureFilter::FilterMode m);
    void                 setZSkew(float zskew);
    // IES normalization-  0: none  1: max value (default)  2: preserve energy
    void                 setIESNormalization(int mode)
                         {
                             myIESNormalization = mode;
                         }
    int                  iesNormalization() const { return myIESNormalization; }
    void                 setIESAngleScale(float scale) { myIESAngleScale = scale; }
    float                iesAngleScale() const { return myIESAngleScale; }

    const UT_Filter *getXFilter() const { return myFilter.getXFilter(); };
    const UT_Filter *getYFilter() const { return myFilter.getYFilter(); };
    float       getXFilterWidth() const { return myFilter.getXWidth(); }
    float       getYFilterWidth() const { return myFilter.getYWidth(); }

//
//  Functions used to set the color lookup behaviour of the map
    void                setColorLookup(bool interp = true,
                                       bool needalpha = true)
                        {
                            myInterpRequired = interp;
                            myAlphaRequired = needalpha;
                        }
    void                setBumpLookup(bool interp = false,
                                TIL_BUMP_COMPUTE_TYPE type=TIL_BUMP_PRECOMPUTE)
                        {
                            myInterpRequired = interp;
                            myBumpType = type;
                        }

    UT_FilterWrap        getUWrap() const        { return myFilter.getXWrap(); }
    UT_FilterWrap        getVWrap() const        { return myFilter.getYWrap(); }
    const UT_Vector4    &getBorder() const       { return myFilter.getBorder(); }

    // If the texture failed to load, this method will tell us whether it
    // is using the default lookup functionality.
    bool                isDefault() const;
    int                 isTTMap() const;
    int                 isDSM() const;
    bool                isPtex() const;
    bool                isOIIO() const;
    int                 isIES() const;

//
//  Lookup a single sample of the image, interpreting the map as a color
//  When specifying four corners of the map, the order of the coordinates
//  is very important:
//
//      BAD                     GOOD                    GOOD
//      2--3                    3--2                    2--3
//       \/                     |  |                    |  |
//       /\                     |  |                    |  |
//      0--1                    0--1                    1--0

    /// When performing multiple texture evaluations, this allows the texture
    /// class to pre-compute some common values rather than performing the
    /// computation on every lookup.
    TIL_TextureHandle   getLookupHandle() const;

    /// @{
    /// Evaluate using an automatic lookup handle
    template <typename T>
    inline void         colorLookup(float u, float v, UT_Vector4T<T> &clr) const
                        {
                            TIL_TextureHandle   h = getLookupHandle();
                            colorLookup(h, u, v, clr);
                        }
    template <typename T>
    inline void         colorLookup(const float u[4], const float v[4],
                                    UT_Vector4T<T> &clr) const
                        {
                            TIL_TextureHandle   h = getLookupHandle();
                            colorLookup(h, u, v, clr);
                        }
    fpreal              depthLookup(float u, float v,
                                    float farvalue=1E6) const
                        {
                            TIL_TextureHandle   h = getLookupHandle();
                            return depthLookup(h, u, v, farvalue);
                        }
    template <typename T>
    void                bumpLookup(float u, float v,
                                   T &du, T &dv) const
                        {
                            TIL_TextureHandle   h = getLookupHandle();
                            bumpLookup(h, u, v, du, dv);
                        }

    template <typename T>
    inline void         envLookup(const UT_Vector3T<T> &R, fpreal angle,
                                  UT_Vector4T<T> &clr) const
                        {
                            TIL_TextureHandle   h = getLookupHandle();
                            envLookup(h, R, angle, clr);
                        }

    template <typename T>
    inline void         envLookup(const UT_Vector3T<T> &r00, const UT_Vector3T<T> &r10,
                                  const UT_Vector3T<T> &r11, const UT_Vector3T<T> &r01,
                                  UT_Vector4T<T> &clr) const
                        {
                            TIL_TextureHandle   h = getLookupHandle();
                            envLookup(h, r00, r10, r11, r01, clr);
                        }
    /// @}

    /// @{
    /// Get the min/max color values in a texture file
    void                getMinMax(UT_Vector4F &min, UT_Vector4F &max) const
                            { getMinMax(getLookupHandle(), min, max); }
    void                getMinMax(UT_Vector4D &min, UT_Vector4D &max) const
                            { getMinMax(getLookupHandle(), min, max); }
    void                getMinMax(const TIL_TextureHandle &h,
                                    UT_Vector4F &min, UT_Vector4F &max) const;
    void                getMinMax(const TIL_TextureHandle &h,
                                    UT_Vector4D &min, UT_Vector4D &max) const;

    /// Get a checksum for the texture.  If the texture is a MIP mapped texture
    /// and @c compute_for_mips is true, the checksum will be computed from the
    /// 128x128 MIP map.
    const UT_StringHolder &getTextureChecksum(const TIL_TextureHandle &h) const;
    const UT_StringHolder &getTextureChecksum() const
                               { return getTextureChecksum(getLookupHandle()); }
    /// @}

    /// @{
    /// Evaluate using a lookup handle
    void                colorLookup(TIL_TextureHandle &h,
                                    float u, float v, UT_Vector4F &clr) const;
    void                colorLookup(TIL_TextureHandle &h,
                                    float u, float v, UT_Vector4D &clr) const;
    void                colorLookup(TIL_TextureHandle &h,
                                    const float u[4], const float v[4],
                                    UT_Vector4F &clr) const;
    void                colorLookup(TIL_TextureHandle &h,
                                    const float u[4], const float v[4],
                                    UT_Vector4D &clr) const;
    float               depthLookup(TIL_TextureHandle &h,
                                    float u, float v,
                                    float farvalue=1E6) const;
    void                bumpLookup(TIL_TextureHandle &h,
                                   float u, float v,
                                   fpreal32 &du, fpreal32 &dv) const;
    void                bumpLookup(TIL_TextureHandle &h,
                                   float u, float v,
                                   fpreal64 &du, fpreal64 &dv) const;

    void                envLookup(TIL_TextureHandle &h,
                                  const UT_Vector3F &R, fpreal angle,
                                  UT_Vector4F &clr) const;
    void                envLookup(TIL_TextureHandle &h,
                                  const UT_Vector3D &R, fpreal angle,
                                  UT_Vector4D &clr) const;

    void                envLookup(TIL_TextureHandle &h,
                              const UT_Vector3F &r00, const UT_Vector3F &r10,
                              const UT_Vector3F &r11, const UT_Vector3F &r01,
                              UT_Vector4 &clr) const;
    void                envLookup(TIL_TextureHandle &h,
                              const UT_Vector3D &r00, const UT_Vector3D &r10,
                              const UT_Vector3D &r11, const UT_Vector3D &r01,
                              UT_Vector4D &clr) const;
    void                getResolution(const TIL_TextureHandle &h,
                                      int &x, int &y);
    /// @}

    /// @{
    /// Deep shadow lookup will fall back to regular depth map lookups
    /// if this map is not a deep shadow map.
    void                deepLookup(TIL_TextureHandle &h,
                                   UT_Vector3F &clr,
                                   const UT_Vector3F &p,
                                   const UT_Vector3F &du,
                                   const UT_Vector3F &dv,
                                   float quality, int maxsamples);
    void                deepLookup(TIL_TextureHandle &h,
                                   UT_Vector3D &clr,
                                   const UT_Vector3D &p,
                                   const UT_Vector3D &du,
                                   const UT_Vector3D &dv,
                                   float quality, int maxsamples);
    /// @}

    /// Query filter information
    const IMG_TextureFilter     &getFilter() const      { return myFilter; }
    IMG_TextureFilter           &getFilter()            { return myFilter; }

    // Adjust scales should only be called internally.
    TIL_BUMP_COMPUTE_TYPE        getBumpCompute() const
                                 {
                                     return myBumpType;
                                 }

    bool         getInterpRequired() const      { return myInterpRequired; }
    bool         getAlphaRequired() const       { return myAlphaRequired; }

    /// Get the OCIO color space associated with the file
    const UT_StringHolder       &ocioColorSpace() const;

    /// Lookup the wrap mode in metadata on the image.  Returns false if
    /// there's no metadata.
    void                wrapMode(UT_StringHolder &swrap,
                                 UT_StringHolder &twrap) const;

    /// Load information about texture and MIP levels
    bool                textureInfo(TextureInfo &info) const;

    /// Load the raster for a given MIP level, possibly converting the data
    bool                loadMipRaster(const TIL_TextureHandle &h,
                                    int mip_level,
                                    const TextureInfo &tinfo,
                                    const UT_DimRect &region,
                                    void *data) const;
    bool                loadMipRaster(int mip_level,
                                    const TextureInfo &tinfo,
                                    const UT_DimRect &region,
                                    void *data) const
                        {
                            return loadMipRaster(getLookupHandle(),
                                    mip_level, tinfo, region, data);
                        }

    // Returns true if the texture is volatile (ie, sourced from a COP). It
    // needs to be checked every time it's accessed to se if it's been updated.
    bool         isVolatileTexture() const;

    // Returns true if a volatile texture has changed, and optionally returns
    // the new raster in the newraster parm.
    bool         hasTextureChanged(const TIL_Raster **newraster = 0);

    // Return the IMG File used (for TT maps). This may contain filters.
    IMG_File            *getFile();

    // Returns the unfiltered TT map.
    IMG_FileTTMap       *getTTMap();

    /// Return a 2d CDF for sampling
    const TIL_Cdf2D     *getCDF(int maxres=512);

    // Look up the color channel index
    int                  getColorChannelIndex(IMG_FileTTMap *map) const;

private:
    void                resolveHandles();
    float               shadowLookup(const UT_Vector3 &p,
                                     const UT_Vector3 &du,
                                     const UT_Vector3 &dv,
                                     float quality, int maxsamples) const;

    // This version of the shadow lookup is used when there are no
    // derivatives available (for non-shading contexts)
    float               shadowLookup(const UT_Vector3 &Ps,
                                     float du, float dv,
                                     float quality, int maxsamples) const;

    void        updateHandles();

private:
    void                         updateFilter()
    {
        if (myOIIO || myPtex)
            doUpdateFilter();
    }
    void                         doUpdateFilter();

    til_Map                     *myMap;
    UT_SharedPtr<til_PtexData>   myPtex;
    UT_SharedPtr<til_OIIOData>   myOIIO;
    UT_SharedPtr<til_Lookup>     myMapLookup;
    UT_OpCaller                 *myCaller;
    IMG_TextureFilter            myFilter;
    UT_StringHolder              myColorChannel;

    int                          myFaceIndex;
    int                          mySubimage;
    int                          myPtexChannel;
    TIL_BUMP_COMPUTE_TYPE        myBumpType;
    TIL_PtexOrient               myPtexOrient;
    int                          myIESNormalization;
    float                        myIESAngleScale;
    bool                         myInterpRequired;
    bool                         myAlphaRequired;
};

#endif