IMG_FileTTMap.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:        IMG_FileTTMap.h ( IMG Library, C++)
 *
 * COMMENTS:    Tiled Texture Maps
 */

#ifndef __IMG_FileTTMap__
#define __IMG_FileTTMap__

#include "IMG_API.h"
#include "IMG_File.h"
#include "IMG_TextureFilter.h"
#include <UT/UT_Array.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_UniquePtr.h>
#include <SYS/SYS_Inline.h>

class UT_Filter;
class UT_FilterWindow;
class UT_Options;
class IMG_TTMipSampler;
class IMG_Raster;

/// An IMG_TTChannel is used to retrieve pixel data from the image.
/// Each image owns an array of IMG_TTChannel objects that could
/// represent environment map rasters or mipmap levels.
class IMG_API IMG_TTChannel
{
public:
             IMG_TTChannel();
    virtual ~IMG_TTChannel();

             UT_NON_COPYABLE(IMG_TTChannel)

    virtual void         getRes(int &xres, int &yres,
                                int &tile_xres, int &tile_yres) const = 0;

    virtual int64        getMemoryUsage(bool inclusive) const = 0;

    virtual void         filterPixels(float *rgba, int nchan,
                                      int first_x, int first_y,
                                      const IMG_TextureFilter &filter,
                                      const float *xweights,
                                      const float *yweights,
                                      int usize, int vsize) = 0;

    virtual void         getPixel(float *rgba, int nchan, int iu, int iv,
                                  const IMG_TextureFilter &filter) = 0;

    /// This method returns the raw pixel data.
    virtual void         getPixel(void *pixel, int iu, int iv) = 0;
    /// Return raw scanline data
    virtual void         getScanline(void *scanline,
                                     int y, int xres, size_t bpp);

    /// Return raw tile data
    virtual void         getTile(const UT_DimRect &region,
                                void *data,
                                int bytes_per_pixel,
                                int bytes_per_scanline);

    /// This method is called when the channel is destroyed
    virtual void         closeChannel() {};

    // Check color statistics
    virtual bool        getMinMaxColor(UT_Vector4 &min_color,
                                       UT_Vector4 &max_color,
                                       IMG_ColorSpace cs = IMG_COLORSPACE_AUTO) const;
    virtual const UT_StringHolder       &getChecksum() const;
};

/// A IMG_TTMap represents a tiled texture format that can be
/// sampled for texture mapping or for environment mapping.  This class 
/// supports methods for sampling and filtering the texture data.  
/// This class is pure virtual and so derived classes must override the 
/// image file and format operations.
class IMG_API IMG_FileTTMap : public IMG_File
{
public:
             IMG_FileTTMap();
            ~IMG_FileTTMap() override;

             UT_NON_COPYABLE(IMG_FileTTMap)

    const char          *className() const override { return "IMG_FileTTMap"; }

    /// Return true if texture evaluation of this format is enabled
    virtual bool        textureEnabled() const;

    int          getOGLRaster(void *data, int xres, int yres,
                              IMG_ColorModel cm, IMG_DataType dt,
                              int raster_number=0);

    /// Lookup information about the raster specified by the IMG_TextureFilter
    /// This returns the resolution for each MIP map as well as the data format
    /// and the number of image channels.
    bool        getMipInfo(int aov_channel,
                            UT_Array<UT_Vector2i> &res,
                            IMG_DataType &data_type,
                            int &nchannels) const;

    /// Read pixels for a given MIP level
    bool        getMipData(int aov_channel, int mip_level,
                            const UT_DimRect &region,
                            void *data) const;

    // Perform unfiltered evaluation at a specified uv.  This operation
    // will not even perform filtering on pixels, so the caller is
    // responsible for all filtering and antialiasing.
    void        unfilteredSample(
                        float *result, int tuple_size, float u, float v,
                        const IMG_TextureFilter &info,
                        int channel, int raster);

    // Sample with filtering at the specified uv.
    void        sample(float *result, int tuple_size, float u, float v,
                        const IMG_TextureFilter &info,
                        int channel, int raster)
                {
                    float       ua[4] = {u,u,u,u};
                    float       va[4] = {v,v,v,v};

                    sample(result, tuple_size,
                            ua, va, 1, info, channel, raster);
                }


    //  Sample the map within a quadrilateral in texture space.  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
    void        sample(float *result, float &visible, int tuple_size,
                        const float u[4], const float v[4],
                        float quality,
                        const IMG_TextureFilter &info,
                        int channel, int raster);
    void        sample(float *result, int tuple_size,
                        const float u[4], const float v[4],
                        float quality,
                        const IMG_TextureFilter &info,
                        int channel, int raster)
                {
                    float       visible;
                    sample(result, visible,
                            tuple_size, u, v, quality,
                            info, channel, raster);
                }

    // Only call the envLookup functions if this RAT is really a cubic
    // environment map.
    void                 envLookup(float *result, int tuple_size,
                                   const UT_Vector3 &r, float angle,
                                   const IMG_TextureFilter &info, int channel);

    void                 envLookup(float *result, int tuple_size,
                                   const UT_Vector3 &r00, const UT_Vector3 &r01,
                                   const UT_Vector3 &r11, const UT_Vector3 &r10,
                                   const IMG_TextureFilter &info,
                                   int channel);

    fpreal               getUPixelSize() const  { return myDx; }
    fpreal               getVPixelSize() const  { return myDy; }

    int64                getMemoryUsage(bool inclusive) const override;
    virtual int          getRasterCount() const { return 0; }
    int                  getChannelTupleSize(int ch) const;
    virtual int          getNumChannels() const { return getStat().getNumPlanes(); }
    const UT_StringHolder       &ocioColorSpace(int channel) const;

    const UT_StringHolder       &swrapMode() const { return mySWrapMode; }
    const UT_StringHolder       &twrapMode() const { return myTWrapMode; }

    // Return the channel index to use for lookups that haven't specified a
    // particular channel.
    virtual int          getDefaultChannelIndex() const
                         { return 0; }
    int                  findChannelIndex(const char *name) const;

    // TODO: Remove this method and replace with calls to IMG_Stat::getImageType
    //       Add IMG_TYPE_ENVMAP to the IMG_ImageType enum.
    virtual int          isReflMap() const { return 0; }

    const IMG_TTChannel *getChannel(exint i) const
                            { return myTTChannels(i).get(); }

protected:
    void         initialize(int mipcount,
                            UT_Array<UT_UniquePtr<IMG_TTChannel>> &channels);

    int          closeFile() override;

    SYS_FORCE_INLINE
    exint                numTTChannels() const { return myTTChannels.size(); }
    SYS_FORCE_INLINE
    IMG_TTChannel       *getTTChannel(exint i) { return myTTChannels(i).get(); }

protected:
    // Mipmap level to start reading from the file.
    int                   myMipRead;

private:
    void                  initScaleAndSize();

    //
    // Data used in lookup of pixel values.  These members MUST be 
    // initialized by derived classes before this class is used for 
    // sampling, by calling the initialize() method above.
    //
    void                  clearMips();

    // We have MIPs for each channel and raster
    int                   getMipOffset(int aov, int image, int mip=0) const
                          {
                              // Each image AOV has myMipCount mip levels, so
                              // there are myMipCount IMG_TTChannel's for every
                              // AOV.
                              //
                              // Textures can contain multiple images (6-pack
                              // environment maps for example).  To the texture
                              // library, each of these images is considered as
                              // an AOV (it shows up as a separate AOV in the
                              // IMG_Stat).  Right now, there's no way for
                              // sub-images to contain multiple AOVs.
                              //
                              // These are flattened to a linear array:
                              //   image0.aov0.mip0  [4x4]
                              //   image0.aov0.mip1  [2x2]
                              //   image0.aov0.mip2  [1x1]
                              //   image1.aov0.mip0  [4x4]
                              //   image1.aov0.mip1
                              //   image1.aov0.mip2
                              //   image2.aov0.mip0
                              //   image2.aov0.mip1
                              //   image2.aov0.mip2
                              //   image0.aov1.mip0
                              //   image0.aov1.mip1
                              //   ...
                              return (aov+image)*myMipCount + mip;
                          }

    float                 myDx, myDy;   // Inverse pixel sizes

    UT_Array<int>       myColorSize;
    UT_StringArray      myOCIOColorSpace;
    UT_StringHolder     mySWrapMode;
    UT_StringHolder     myTWrapMode;

    // Mipmap samplers are stored as an array of pointers, with each
    // entry representing one mipmap level.  If this class is an 
    // environment map, multiple sets of mipmaps may be stored sequentially
    // in this array.
    UT_Array<UT_UniquePtr<IMG_TTMipSampler>>    myMips; // Mip Maps
    UT_Array<UT_UniquePtr<IMG_TTChannel>>       myTTChannels;
    int                                         myMipCount;
    int                                         myDSMComponentCount;
    int                                         myDepthComplexityPlane;
    bool                                        myFixMipFilterWidth;
};

#endif