MaterialMap.h

Go to the documentation of this file.

//! @file MaterialMap.h
//! CMaterialMap class is the implementation for a texture map associated to a C3DMaterial.
//
//////////////////////////////////////////////////////////////////////
 
#if !defined(AFX_MATERIALMAP_H__57174DE1_C363_11D3_AC9D_F94D2C3E2938__INCLUDED_)
#define AFX_MATERIALMAP_H__57174DE1_C363_11D3_AC9D_F94D2C3E2938__INCLUDED_
 
#ifdef _MSC_VER
#pragma once
#endif // _MSC_VER
 
#include "3DAnimatable.h"
#include "4x4Matrix.h"
#include "3DVector.h"
 
#ifndef MOOTOOLS_NO_BITMAP
#include "Bmapmgr.h"
#endif
 
BEGIN_MOOTOOLS_NAMESPACE
 
//! @enum MapType
//! @brief This enum allows to know the kind of texture map.
typedef enum MapType XEnumType(unsigned int)
{
    MAPTYPE_UNDEFINED = 0,
    MAPTYPE_FIRST = 1,
    MAPTYPE_DIFFUSE = 1,        // BASE_COLOR in PBR
    //MAPTYPE_BASE_COLOR = 1,
    MAPTYPE_AMBIENT,
    MAPTYPE_SPECULAR,
    MAPTYPE_TRANSPARENCY,
    MAPTYPE_BUMP,
    MAPTYPE_NORMALMAP,
    MAPTYPE_EMISSIVE,               // Added for PBR
    MAPTYPE_OCCLUSION,              // Added for PBR
//  MAPTYPE_SPECULAR_GLOSSINESS,    // -> RGB + A (for glossiness) ???
    MAPTYPE_SPECULAR_COLOR,         // -> RGB
    MAPTYPE_SPECULAR_ALPHA,         // -> A
//  MAPTYPE_METALLIC_ROUGHNESS,     // Added for PBR -> R=metallic G=Roughness  (gltf specs)
    MAPTYPE_ROUGHNESS,              // Added for PBR -> ? (3DS, Maya specs)
    MAPTYPE_METALLIC,               // Added for PBR -> ? (3DS, Maya specs)
    MAPTYPE_GLOSS,
    MAPTYPE_LAST,
 
    MAPTYPE_MIXED = MAPTYPE_LAST+10, // This type is not a standard material map type found in a 3dmaterial. Is is a compound type return by MapMixer only 
} MapType;
 
//! @enum MapProjection
//! @brief Projection type of the texture map. 
typedef enum XEnumType(unsigned int)
{
    MAPPROJ_UNDEFINED = 0,
    MAPPROJ_UVW, //!< A CUVWChannel is required for the map
    MAPPROJ_PLANAR, //!< The following projection means that the mapping mode requires UVW to be generated as it is a mapping projection
    MAPPROJ_CYLINDRICAL,
    MAPPROJ_SPHERICAL,
    MAPPROJ_CUBIC, //!< Lightwave cubic mode (front/top/right normal - back/bottom/left inverted projection)
    MAPPROJ_CUBIC2, //!< C4D cubic mode (no inverted projection)
    MAPPROJ_FRONT,
} MapProjection;
 
//! @enum MapAxis
//! @brief Axis direction of the mapping projection
typedef enum XEnumType(unsigned int)
{
    MAPAXIS_X = 0,
    MAPAXIS_Y,
    MAPAXIS_Z,
} MapAxis;
 
//! @enum MAP_PROPERTIES
//! @brief Different flags for the map
typedef enum MAP_PROPERTIES XEnumType(unsigned int)
{
    MAPPROP_UNKNOWN = 0,
    MAPPROP_NO_REPEAT_ON_U = 0x01,
    MAPPROP_NO_REPEAT_ON_V = 0x02,
    MAPPROP_DISABLE_ALPHA = 0x04, //!< Don't use alpha channel if there is any.
 
    // Invalidation flags
    MAPPROP_INVALIDATE = 0x01000000, //!< Something changed for the map. Try to load again the bitmap
} MAP_PROPERTIES;
 
#define KEYFRAME_MAP_TILE KEYFRAMEID(C3DKeyframe::KEYFRAME_TYPE_VECTOR, MAKE_CUSTOM_ID('M', 'P', 'T', 'L'))
#define KEYFRAME_MAP_SWAPMATRIX KEYFRAMEID(C3DKeyframe::KEYFRAME_TYPE_MATRIX, MAKE_CUSTOM_ID('M', 'P', 'S', 'W'))
 
//! @class CMaterialMap
//! @brief CMaterialMap handles material texture map.
//! @details CMaterialMap refers to a bitmap file and optionnaly an alpha bitmap file.
//! This material map has a type given by CMaterialMap::GetType and can be relative to the material diffuse, normap map, transparency...\n
//! The material map defines also a projection type, get by CMaterialMap::GetProjection. MAPPROJ_UVW requires a CUVWChannel whereas the other value means that map is projected and the UV values are computed depending on the corresponding projection.
class DLL_3DFUNCTION CMaterialMap : public CXObject, public C3DKeyframable
{
    friend class C3DMaterial;
    friend class CMaterialMapCache;
 
public:
    typedef enum MaterialMapSize
    {
        MATERIALMAP_ANY_SIZE = -1,  //!< the first bitmap found in the cache whatever the size
        MATERIALMAP_DEFAULT_SIZE = 0,  //!< the bitmap file size
    } MaterialMapSize;
 
    typedef enum MapChannelFlags XEnumType(unsigned int)
    {
        MAPCHANNEL_UNSPECIFIED = (unsigned int) - 1, //!< This means that existing flags are kept and not replaced by the new one
        MAPCHANNEL_NONE = 0,
        MAPCHANNEL_FIRST_CHANNEL_FOUND = 0x01, //!< Setting this value implies that the first channel found will be returned if the designated channel is not found
    } MapChannelFlags;
 
private:
    unsigned int flags;
    C3DScene* refScene; // Internal. cf. note in constructor
    C3DMaterial* material;
    CXString filename, alphafilename;
    CCustomData data;
    ChannelID frontChannelID, backChannelID;
    unsigned int frontChannelFlags, backChannelFlags;
    MapType type;
    MapProjection projection;
    MapAxis axis;
 
    typedef struct MapPathPair
    {
    public:
        CXString mainPath; // full path name of the file found
        CXString alphaPath; // full path for the alpha file found
 
        MapPathPair() {};
        MapPathPair(const CXString& path, const CXString& alphaPath)
        {
            this->mainPath = path;
            this->alphaPath = alphaPath;
            this->mainPath.MakeLower();
            this->alphaPath.MakeLower();
        }
    } MapPathPair;
 
    friend CHashMethods<CMaterialMap::MapPathPair>;
 
#ifndef MOOTOOLS_NO_BITMAP
    unsigned char rgbaMapping[4];
 
    typedef struct MapBitmap
    {
        MapPathPair paths;
 
        enum MapFileStatus
        {
            MAPSTATUS_NOT_READED = 0,  // the file hasn't be readed for the moment...
            MAPSTATUS_READY,        // Map is ready
            MAPSTATUS_INVALID,       // Map file is invalid
            MAPSTATUS_CANT_FIND_FILE,  // Cant find map file
        } status;
 
        CXSize fileBitmapSize; // The loaded file bitmap size
        unsigned int requestedSize; // the size of the requested bitmap
        Bitmap* bmap; // rgb or rgba bitmap
        bool inCache; // true by default
 
        MapBitmap();
        virtual ~MapBitmap();
 
        static bool CheckFileChange(const Bitmap* bmap, const MapPathPair& paths);
        bool CheckFileChange(bool invalidate);
        void DeleteBitmap(bool resetInvalidStatus = false);
        bool ReadBitmap(const CXString& filename, const CXString& alphafilename, const unsigned char* rgbaMapping = NULL, unsigned int width = MATERIALMAP_DEFAULT_SIZE);
        CLayerBitmap* ReadBitmapLayer(const CXString& fullpath, unsigned int width = MATERIALMAP_DEFAULT_SIZE);
    } MapBitmap;
 
    MapBitmap bmapinfo;
    bool ReadBitmap(const CXString& filename, const CXString& alphafilename, unsigned int width = MATERIALMAP_DEFAULT_SIZE);
#else
    typedef struct MapBitmap
    {
        MapPathPair paths;
    } MapBitmap;
 
    MapBitmap bmapinfo;
#endif
 
    void SetMaterial(C3DMaterial* material);
    bool FindBitmap(const CXString& tryname, CXString& findname, bool fullPath) const;
 
protected: // Access for C3DMaterial
    static CMaterialMap *Create(C3DMaterial *material, const CXString& filename, ChannelID frontChannelID, MapType type, MapProjection proj, unsigned int frontChannelFlags = MAPCHANNEL_NONE); //!< Create a material map. Use C3DMaterial::AddMaterialMap to create and add it to a C3DMaterial
    CMaterialMap(C3DMaterial* material); //!< Use only by C3DMaterials
 
public:
    virtual ~CMaterialMap();
    virtual void Serialize( CXArchive& ar );
 
    C3DMaterial* GetMaterial() const; //!< Return the material to which the map is attached
    C3DScene* GetScene() const; //!< Return scene to which the map belong to (from C3DMaterials)
 
    static CXString GetMapName(MapType type);
 
    CXString GetBitmapPath(bool alpha, bool fullPath = false) const; //!< fullPath = true ensure that we have no relative path, otherwise the path might be relative to the scene filepath. Alpha = true, means that we return the alpha filename
    CXString AdjustPath(CXString filename, const CXString& newTargetPath = CXString(), bool allowRelative = true) const; //!< Adjust a single filename and make it relative to newTargetPath if provided or the scene path otherwise.
    void AdjustPaths(const CXString& targetPath, bool relativePathAllowed); //!< Make all internal filenames used by materials relative to provided path
 
    bool BitmapFileExists(bool alpha = false); //!< Check if the bitmap file exists
    fileuint GetFileSize(bool alpha = false); //!< The file size of the source bitmap which might differ from the size of the requested bitmap
    bool HasAlpha(); //!< Check if the map bitmap file has an alpha channel (if MAPPROP_DISABLE_ALPHA not set)
 
#ifndef MOOTOOLS_NO_BITMAP
    const Bitmap *GetBitmap(unsigned int maxSize = MATERIALMAP_DEFAULT_SIZE, bool keepAlreadyLoadedIfBigger = false); //!< Bitmap is assumed to have G8_BITMAP, GA_BITMAP, RGB_BITMAP or RGBA_BITMAP type. The bitmap is automatically released by the CMaterialMap
    bool HasBitmap() const;
 
    CXSize GetFileBitmapSize(bool alpha = false) const; //!< The size of the source bitmap which might differ from the size of the requested bitmap
    BitmapType GetFileBitmapType(bool alpha = false); //!< The source bitmap type (no MappingMode applied)
    BitmapType GetBitmapType() const; //!< The type of the map bitmap (depending on MappingMaskMode, and alpha filename)
 
    //! @brief Defines an array of 4 char that define how to process rgba pixels
    //! @details unsigned char mask[4] = { MAPRGBA_INV_G, MAPRGBA_R, MAPRGBA_A, MAPRGBA_INV_B} will read the bitmap then provided rgba bitmap with pixels of type {-green, red, alpha, -blue}
    //! unsigned char mask[4] = { MAPRGBA_INV_G, MAPRGBA_OFF, MAPRGBA_OFF, MAPRGBA_OFF} will read the bitmap then provided g8 bitmap with pixels of type {-green }\n
    //! unsigned char mask[4] = { MAPRGBA_R, MAPRGBA_G, MAPRGBA_B, MAPRGBA_A} will read the bitmap then provided rgbaBitmap { red, green, blu, alpha }. This is the default pixel mapping. In that case only, if no alpha is available in the input bitmap, it only returns an rgbBitmap\n
    void SetMappingMask(const unsigned char rgbaMappingMask[4]);
    bool GetMappingMask(unsigned char rgbaMappingMask[4]) const; //!< Return true if default mapping
    bool IsSameMappingMask(const unsigned char rgbaMappingMask[4]) const; //!< Compare both mapping mask. That allow to know that we read a map with a given format, and want to save to the same format
 
    //! @brief MapMixer allows to compound the bitmaps issued from different map.
    //! @details You can specify up to 4 maps through the variable arguments which must be terminated by NULL
    //! CMaterialMap* map1, const unsigned char rgbaMapping1[4], CMaterialMap* map2, const unsigned char rgbaMapping2[4], ..., NULL)\n
    //! the resulting map is issued from the combination of rgbaMapping1 and rgbaMapping2\n
    //! unsigned char rgbaMapping1[4] = { MAPRGBA_INV_G, MAPRGBA_OFF, MAPRGBA_OFF, MAPRGBA_OFF}\n
    //! unsigned char rgbaMapping2[4] = { MAPRGBA_OFF, MAPRGBA_R, MAPRGBA_OFF, MAPRGBA_OFF}\n
    //! will generate an RGB_BITMAP bitmap with {-g1, r2, 0} where g1 is green of map1 and r2 is red of map2\n
    //!
    //! unsigned char rgbaMapping1[4] = { MAPRGBA_INV_G, MAPRGBA_OFF, MAPRGBA_OFF, MAPRGBA_OFF}\n
    //! unsigned char rgbaMapping2[4] = { MAPRGBA_OFF, MAPRGBA_R, MAPRGBA_OFF, MAPRGBA_INV_A}\n
    //! will generate an RGBA_BITMAP bitmap with {-g1, r2, 0, -a2}\n
    //!
    //! unsigned char rgbaMapping1[4] = { MAPRGBA_INV_G, MAPRGBA_OFF, MAPRGBA_OFF, MAPRGBA_OFF}\n
    //! will generate a G8_BITMAP from the input bitmap with {-g1 } pixels\n
    //!
    //! unsigned char rgbaMapping1[4] = { MAPRGBA_INV_G, MAPRGBA_OFF, MAPRGBA_OFF, MAPRGBA_OFF}\n
    //! unsigned char rgbaMapping2[4] = { MAPRGBA_OFF, MAPRGBA_OFF, MAPRGBA_OFF, MAPRGBA_INV_A}\n
    //! will generate a GA_BITMAP from the input bitmap with {-g1, -a2}\n
 
    //!< The returned material map must be free by the caller using xDelete(map);
    static CMaterialMap* MapMixer(unsigned int dstMapSize = MATERIALMAP_DEFAULT_SIZE, ...);
 
    //! @brief Same feature as CMaterialMap::MapMixer except than the variable argument type differs.
    //! @details You can specify up to 4 maps through the variable arguments which must be terminated by NULL
    //! const Bitmap* bmap1, const char rgbaMapping1[4], const Bitmap* bmap2, const char rgbaMapping2[4], ..., NULL)
    static Bitmap* BitmapMixer(unsigned int dstMapSize = MATERIALMAP_DEFAULT_SIZE, ...);
 
    static const Bitmap* LoadBitmap(C3DScene* scene, const CXString& bmappath); //!< Load a bitmap at the specified path taking advantage of CMaterialMap loading mechanism
    static bool UnloadBitmap(const Bitmap *bmap); //!< Release the bitmap loaded with LoadBitmap
#endif
 
    // operator
    bool operator==(CMaterialMap &refMap) const;
    CMaterialMap& operator=(CMaterialMap& refmap);
 
    CCustomData& GetCustomData();
    const CCustomData& GetCustomData() const;
 
    void SetFlag(MAP_PROPERTIES flag, bool set);
    bool IsFlagSet(MAP_PROPERTIES flag) const;
 
    void SetType(MapType reftype);
    MapType GetType() const;
 
    void SetProjection(MapProjection reftype);
    MapProjection GetProjection() const;
    
    void SetAlphaFileName(const CXString& filename, const CXString& newReferencePath = CXString()); //!< operator If newReferencePath is provided, the filename will be make relative to that directory if possible
    void SetFileName(const CXString& filename); 
    void SetHPBRotation(unsigned int time, const C3DVector& hpbvector);
 
    void ResetTransformation();
    void SetScale(unsigned int time, const C3DVector& vect);
    void Scale(unsigned int time, const C3DVector& vect);
    void SetTranslation(unsigned int time, const C3DVector& vect);
    void Translate(unsigned int time, const C3DVector& vect);
    void SetRotation(unsigned int time, const CQuaternion& quat);
    void Rotate(unsigned int time, const CQuaternion& quat);
    void SetTile(unsigned int time, const C3DVector& vect);
    void SetMatrix(unsigned int time, const C4x4Matrix& matrix);
    void SetAxis(MapAxis axis);
 
    //! @brief Handle the channel id of the material map. The corresponding channel is an UVW_CHANNEL
    //! @details The material might define a back channel ID for double sided face that have both side the same material with different UVs
    //! If no back channel is define, then front / back side share the same UV and GetChannelID return frontChannelID for front / back side\n
    void SetChannelID(ChannelID uvwChannelID, bool front = true, unsigned int channelFlags = MAPCHANNEL_UNSPECIFIED);
    ChannelID GetChannelID(bool front = true, unsigned int *channelFlags = NULL) const; //!< Return the material map channel ID, as set in SetChannelID (the flag MAPPROP_USE_FRONT_CHANNEL_WHEN_BACK_MISSING is not taken into account). Can also return CHANNELID_FIRST_CHANNEL_FOUND. GetUVWChannelID should be used as an helper to get the final channel ID to use for a given object
 
    void ChangeChannelID(CHashMap<CChannelInfo, const CChannelInfo&, CChannelInfo>& channelMap); //!< Remap the materialmap channel ID to the new channelID provided by the map.
 
    void GetFileName(CXString& filename) const; //!< This returns the raw image filename as it is stored in the map, when reading a file. The path can be relative, absolute... Use GetBitmapPath resolves absolute / relative path and potentially fixe texture location changes.
    void GetAlphaFileName(CXString& filename) const; //!< Same as GetFileName, but for the alpha image
    void GetScale(unsigned int time, C3DVector& vect) const;
    void GetTranslation(unsigned int time, C3DVector& vect) const;
    void GetHPBRotation(unsigned int time, C3DVector& vect) const;
    void GetRotation(unsigned int time, CQuaternion& vect) const;
    void GetMatrix(unsigned int time, C4x4Matrix& vect) const;
    void GetTile(unsigned int time, C3DVector& vect) const;
    MapAxis GetAxis() const;
 
    void SwapCoordinates(unsigned int swapmode);
};
 
END_MOOTOOLS_NAMESPACE
 
#endif // !defined(AFX_MATERIALMAP_H__57174DE1_C363_11D3_AC9D_F94D2C3E2938__INCLUDED_)