Cafu Engine
MapComposition.hpp
1 /*
2 Cafu Engine, http://www.cafu.de/
3 Copyright (c) Carsten Fuchs and other contributors.
4 This project is licensed under the terms of the MIT license.
5 */
6 
7 #ifndef CAFU_MATSYS_MAP_COMPOSITION_HPP_INCLUDED
8 #define CAFU_MATSYS_MAP_COMPOSITION_HPP_INCLUDED
9 
10 #include "TextParser/TextParser.hpp"
11 
12 
13 struct BitmapT;
14 
15 
16 /// A MapCompositionT is a description of how a SINGLE texture map image is composited from several source images on disk.
17 /// (Each material stage has an own MatCompositionT. Each frame of an animated sequence, too. Don't know yet about videos.)
19 {
20  public:
21 
22  /// This enum describes the filter mode of this map composition, kept in the root MapCompositionT (the children just keep the default values).
23  enum MinMagFiltersT { Nearest, Linear, Nearest_MipMap_Nearest, Nearest_MipMap_Linear, Linear_MipMap_Nearest, Linear_MipMap_Linear };
24 
25  /// This enum describes the wrap mode of this map composition, kept in the root MapCompositionT (the children just keep the default values).
26  enum WrapModesT { Repeat, Clamp, ClampToEdge };
27 
28  /// This enum describes the type of the map composition.
29  /// Note that there is no scaling operation - scaling is automatic.
30  /// TODO: Operations for the alpha-channel: e.g. taking it from the red channel of another image...
31  enum TypeT { Empty, Map, Add, Mul, CombineNormals, HeightMapToNormalMap, FlipNormalMapYAxis, ReNormalize, BlueToAlpha }; // VideoStream
32 
33 
34  /// Constructor for creating an "empty" map composition.
35  MapCompositionT(MinMagFiltersT MinFilter_=Linear_MipMap_Linear, MinMagFiltersT MagFilter_=Linear, WrapModesT WrapS_=Repeat, WrapModesT WrapT_=Repeat, bool NoScaleDown_=false, bool NoCompression_=false);
36 
37  /// Constructor for creating a MapCompositionT from a string description.
38  MapCompositionT(const std::string& s, const std::string& BaseDir_) /*throw (TextParserT::ParseError)*/;
39 
40  /// Constructor for creating a MapCompositionT from TextParserT input.
41  MapCompositionT(TextParserT& TP, const std::string& BaseDir_, bool NoCompression_=false, const unsigned long RecursionCount=0) /*throw (TextParserT::ParseError)*/;
42 
43  /// Copy Constructor (Law of the Big Three).
44  MapCompositionT(const MapCompositionT& Source);
45 
46  /// Destructor (Law of the Big Three).
48 
49  /// Assignment Operator (Law of the Big Three).
51 
52  /// Equal Operator. Treats Add, Mul and CombineNormals as commutative (a+b==b+a),
53  /// but never takes the associative or distributive law into account.
54  bool operator == (const MapCompositionT& rhs) const;
55 
56  /// Returns true iff this MapComposition is empty.
57  bool IsEmpty() const { return Type==Empty; };
58 
59  /// Returns one of the children of this MapCompositionT.
60  /// Use this method together with GetType().
61  const MapCompositionT* GetChild(int Num) const { return Num==0 ? Child1 : Child2; }
62 
63  MinMagFiltersT GetMinFilter() const { return MinFilter; } ///< Returns the filter for minification.
64  MinMagFiltersT GetMagFilter() const { return MagFilter; } ///< Returns the filter for magnification.
65  WrapModesT GetWrapModeS() const { return WrapS; } ///< Returns the wrapping mode in s-direction.
66  WrapModesT GetWrapModeT() const { return WrapT; } ///< Returns the wrapping mode in t-direction.
67  bool GetNoScaleDown() const { return NoScaleDown; } ///< Returns whether the texture should not be scaled down (e.g. for optimizing performance).
68  bool GetNoCompression() const { return NoCompression; } ///< Returns whether the texture should not be compressed (e.g. for optimizing performance/memory).
69  TypeT GetType() const { return Type; } ///< Returns the type of this map composition.
70 
71  /// This function loads all image source files from disk (at *BaseDir+FileName), and combines them (according to this MapCompositionT)
72  /// into a single resulting BitmapT. On any error with the participating bitmaps (ie. file not found, file unreadable, ...),
73  /// a default texture is substituted for the missing participant, and a warning is printed out. Thus, the function never fails.
74  /// The caller becomes the owner of the returned pointer (i.e. its the callers responsibility to delete it.)
75  BitmapT* GetBitmap() const;
76 
77  /// Returns a string description of this MapCompositionT (quasi the counter-piece to the constructor).
78  std::string GetString() const;
79 
80  /// Like GetString(), which is kept for backwards-compatibility, but includes the list of options as well.
81  std::string GetStringWithOptions(bool NoCompressionDefault=false) const;
82 
83  /// Returns the base dir of this MapCompositionT. Can be the empty string for empty map compositions.
84  std::string GetBaseDir() const;
85 
86 
87  private:
88 
89  /// As each MapCompositionT needs a base directory, this is the cache for the base directories.
90  /// MapCompositionTs store pointers to cache objects rather than array indices, in order to be able to
91  /// later copy MapCompositionTs even across exe/dll-boundaries, if need be. May later reconsider this, though...
92  /// Currently, the cache is not intended to be cleared during program run-time, the OS does the clean-up after program termination.
93  static ArrayT<std::string*> BaseDirCache;
94 
95  /// An auxiliary method for the constructors.
96  void Init(TextParserT& TP, const unsigned long RecursionCount) /*throw (TextParserT::ParseError)*/;
97 
98 
99  TypeT Type; ///< The type of this MapCompositionT.
100  MinMagFiltersT MinFilter; ///< The minification filter (valid only for the root MapCompositionT).
101  MinMagFiltersT MagFilter; ///< The magnification filter (valid only for the root MapCompositionT).
102  WrapModesT WrapS; ///< The s-coordinate wrap mode (valid only for the root MapCompositionT).
103  WrapModesT WrapT; ///< The t-coordinate wrap mode (valid only for the root MapCompositionT).
104  bool NoScaleDown; ///< The "user wishes no scale down" flag (valid only for the root MapCompositionT). Prevents the bitmap image from being scaled down by the Renderer when the user optimizes the game graphics. (That is, this is for overriding e.g. performance optimizations.) Useful for fonts, HUD, lightmaps, and everything else that must not get mixed up.
105  bool NoCompression; ///< The "no texture compression" flag (valid only for the root MapCompositionT). Prevents the Renderer from applying texture compression to this bitmap image when the user optimizes the game graphics. (That is, this is for overriding e.g. performance optimizations.) Useful e.g. for normal-maps, where the memory gains are outweighed by the compression artifacts.
106  std::string FileName; ///< The map filename (valid only for Type==Map).
107  std::string* BaseDir; ///< The base dir corresponding to the file name (valid only for Type==Map).
108  float HeightScale; ///< The scale for the heightmap (valid only for Type==HeightMapToNormalMap).
109  MapCompositionT* Child1; ///< The first child for most types except Empty and Map.
110  MapCompositionT* Child2; ///< The second child for most types except Empty and Map.
111 };
112 
113 #endif
MapCompositionT(MinMagFiltersT MinFilter_=Linear_MipMap_Linear, MinMagFiltersT MagFilter_=Linear, WrapModesT WrapS_=Repeat, WrapModesT WrapT_=Repeat, bool NoScaleDown_=false, bool NoCompression_=false)
Constructor for creating an "empty" map composition.
Definition: MapComposition.cpp:30
MinMagFiltersT GetMinFilter() const
Returns the filter for minification.
Definition: MapComposition.hpp:63
WrapModesT GetWrapModeT() const
Returns the wrapping mode in t-direction.
Definition: MapComposition.hpp:66
MapCompositionT & operator=(const MapCompositionT &Source)
Assignment Operator (Law of the Big Three).
Definition: MapComposition.cpp:266
This class represents a RGBA bitmap.
Definition: Bitmap.hpp:20
std::string GetBaseDir() const
Returns the base dir of this MapCompositionT. Can be the empty string for empty map compositions...
Definition: MapComposition.cpp:777
bool GetNoScaleDown() const
Returns whether the texture should not be scaled down (e.g. for optimizing performance).
Definition: MapComposition.hpp:67
BitmapT * GetBitmap() const
This function loads all image source files from disk (at *BaseDir+FileName), and combines them (accor...
Definition: MapComposition.cpp:334
WrapModesT
This enum describes the wrap mode of this map composition, kept in the root MapCompositionT (the chil...
Definition: MapComposition.hpp:26
~MapCompositionT()
Destructor (Law of the Big Three).
Definition: MapComposition.cpp:258
MinMagFiltersT GetMagFilter() const
Returns the filter for magnification.
Definition: MapComposition.hpp:64
TypeT GetType() const
Returns the type of this map composition.
Definition: MapComposition.hpp:69
bool GetNoCompression() const
Returns whether the texture should not be compressed (e.g. for optimizing performance/memory).
Definition: MapComposition.hpp:68
const MapCompositionT * GetChild(int Num) const
Returns one of the children of this MapCompositionT.
Definition: MapComposition.hpp:61
WrapModesT GetWrapModeS() const
Returns the wrapping mode in s-direction.
Definition: MapComposition.hpp:65
std::string GetString() const
Returns a string description of this MapCompositionT (quasi the counter-piece to the constructor)...
Definition: MapComposition.cpp:659
A MapCompositionT is a description of how a SINGLE texture map image is composited from several sourc...
Definition: MapComposition.hpp:18
TypeT
This enum describes the type of the map composition.
Definition: MapComposition.hpp:31
bool operator==(const MapCompositionT &rhs) const
Equal Operator.
Definition: MapComposition.cpp:292
bool IsEmpty() const
Returns true iff this MapComposition is empty.
Definition: MapComposition.hpp:57
std::string GetStringWithOptions(bool NoCompressionDefault=false) const
Like GetString(), which is kept for backwards-compatibility, but includes the list of options as well...
Definition: MapComposition.cpp:696
MinMagFiltersT
This enum describes the filter mode of this map composition, kept in the root MapCompositionT (the ch...
Definition: MapComposition.hpp:23
This is a class for parsing text.
Definition: TextParser.hpp:21