Libs/MaterialSystem/MaterialManager.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 /**********************************/
   8 /*** Material Manager Interface ***/
   9 /**********************************/
  10
  11 #ifndef CAFU_MATSYS_MATERIAL_MANAGER_INTERFACE_HPP_INCLUDED
  12 #define CAFU_MATSYS_MATERIAL_MANAGER_INTERFACE_HPP_INCLUDED
  13
  14 #include "Templates/Array.hpp"
  15
  16 #include <map>
  17 #include <string>
  18
  19
  20 class MaterialT;
  21
  22
  23 /// This is an interface to the material manager.
  24 /// A material manager keeps a set of materials and their related script state, and finds materials by name.
  25 ///
  26 /// The interface is specified as ABC in order to be able to share the material manager across exe/dll boundaries.
  27 /// (Note that sharing across exe/dll boundaries is probably not needed: The MaterialManagerI is just a helper
  28 ///  for getting MaterialTs from script files. Thus we could also share (pointers to) arrays of MaterialTs directly.
  29 ///  (MODs should not register their own materials, as the engine registeres anything in the *Materials* dir. anyway.)
  30 ///  It is just the GetMaterial() "search" function that makes sharing the MatMan interesting.)
  31 class MaterialManagerI
  32 {
  33     public:
  34
  35     // ************************************************************************************************
  36     // TODO: Should use   const MaterialT*   rather than just   MaterialT*   throughout this interface!
  37     // ************************************************************************************************
  38
  39     /// Registers a material script file.
  40     /// The GetMaterial() function will look into the files registered here when looking for a material.
  41     /// @returns an array of pointers to all the new materials found in the cmat file FileName.
  42     ///          Note that only "new", not previously registered materials are considered here!
  43     virtual ArrayT<MaterialT*> RegisterMaterialScript(const std::string& FileName, const std::string& BaseDir)=0;
  44
  45     /// Registers all ".cmat" files in a directory as material script files.
  46     /// @returns an array of pointers to all the new materials found in cmat files in DirName.
  47     ///          Note that only "new", not previously registered materials are considered here!
  48     virtual ArrayT<MaterialT*> RegisterMaterialScriptsInDir(const std::string& DirName, const std::string& BaseDir, const bool Recurse=true)=0;
  49
  50     /// Returns all the materials registered so far.
  51     virtual const std::map<std::string, MaterialT*>& GetAllMaterials() const=0;
  52
  53     /// Returns whether the material with the given name is registered with the material manager,
  54     /// i.e.\ if a call to <code>GetMaterial(MaterialName)</code> will return successfully.
  55     /// Use this to avoid warning messages to the console if the material is not registered.
  56     virtual bool HasMaterial(const std::string& MaterialName) const=0;
  57
  58     /// Returns a material by its name.
  59     /// If the material is not found in the previously registered scripts, NULL is returned.
  60     virtual MaterialT* GetMaterial(const std::string& MaterialName) const=0;
  61
  62     // This method no longer exists - materials that have been registered once cannot be unregistered again without quitting the program.
  63     // This is to guarantee that the user code will never be left with stale MaterialT* pointers at any time.
  64     // /// Removes all materials from this material manager.
  65     // virtual void ClearAllMaterials()=0;
  66
  67     /// Virtual destructor, so that nothing can go wrong and even g++ is happy.
  68     virtual ~MaterialManagerI() { }
  69 };
  70
  71
  72 /// A global pointer to an implementation of the MaterialManagerI interface.
  73 ///
  74 /// Each module (exe or dll) that uses this pointer must somewhere provide exactly one definition for it (none is provided by the MatSys).
  75 /// That is, typically the main.cpp or similar file of each exe and dll must contain a line like
  76 ///     MaterialManagerI* MaterialManager=NULL;
  77 /// or else the module will not link successfully due to an undefined symbol.
  78 ///
  79 /// Exe files will then want to reset this pointer to an instance of a MaterialManagerImplT during their initialization
  80 /// e.g. by code like:   MaterialManager=new MaterialManagerImplT;
  81 /// Note that the MaterialManagerImplT ctor may require that other interfaces (e.g. the Console) have been inited first.
  82 ///
  83 /// Dlls typically get one of their init functions called immediately after they have been loaded.
  84 /// By doing so, the exe passes a pointer to its above instance to the dll, which in turn copies it to its MaterialManager variable.
  85 extern MaterialManagerI* MaterialManager;
  86
  87 #endif