Libs/SoundSystem/SoundShaderManager.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_SOUNDSYS_SOUND_SHADER_MANAGER_INTERFACE_HPP_INCLUDED
   8 #define CAFU_SOUNDSYS_SOUND_SHADER_MANAGER_INTERFACE_HPP_INCLUDED
   9
  10 #include "Templates/Array.hpp"
  11
  12 #include <string>
  13
  14
  15 class SoundShaderT;
  16
  17
  18 /// This is an interface to the sound shader manager.
  19 /// The interface is specified as ABC in order to be able to share the sound shader manager across exe/dll boundaries.
  20 /// (Note that sharing across exe/dll boundaries is probably not needed: The SoundShaderManagerI is just a helper
  21 ///  for getting SoundShaderTs from script files. Thus we could also share (pointers to) arrays of SoundShaderTs directly.
  22 ///  (MODs should not register their own sound shaders, as the engine registeres anything in the *SoundShader* dir. anyway.)
  23 ///  It is just the GetSoundShader() "search" function that makes sharing the SoundShaderManagerI interesting.)
  24 class SoundShaderManagerI
  25 {
  26     public:
  27
  28     /// Register a sound shader script file by parsing all sound shaders from the list and adding them to the manager.
  29     /// @param ScriptFile Path to the file that contains the sound shader definitions.
  30     /// @param ModDir The directory of the MOD the sound shader script is registered for relative to the executables directory.
  31     /// @return Array of new created sound shaders or empty array if a problem occured or no new sound shader definitions
  32     ///         were found in the script.
  33     virtual ArrayT<const SoundShaderT*> RegisterSoundShaderScript(const std::string& ScriptFile, const std::string& ModDir)=0;
  34
  35     /// Registers all ".caud" files inside a directory.
  36     /// @param Directory The path from which sound shader script files should be registered.
  37     /// @param ModDir The directory of the MOD for which the sound shader script in this directory are registered relative to the executables directory.
  38     /// @param Recurse Determines if subdirectories are searched for ".caud" files recusively.
  39     /// @return Array of new created sound shaders or empty array if a problem occured or no new sound shader definitions
  40     ///         were found in the script.
  41     virtual ArrayT<const SoundShaderT*> RegisterSoundShaderScriptsInDir(const std::string& Directory, const std::string& ModDir, bool Recurse=true)=0;
  42
  43     /// Searches for the shader specified by Name and returns it.
  44     /// @param Name The name of this sound shader as it is defined in the sound shader script.
  45     ///             If no sound shader by this name is found the manager tries to interpret the Name as a filename to
  46     ///             an audio file and automatically creates a default shader for it.
  47     /// @return Pointer to the found sound shader or NULL if no sound shader with this name is registered and no default
  48     ///         shader could be created.
  49     virtual const SoundShaderT* GetSoundShader(const std::string& Name)=0;
  50
  51     /// Virtual destructor, so that nothing can go wrong and even g++ is happy.
  52     virtual ~SoundShaderManagerI() { }
  53 };
  54
  55
  56 /// A global pointer to an implementation of the SoundShaderManagerI interface.
  57 ///
  58 /// Each module (exe or dll) that uses this pointer must somewhere provide exactly one definition for it (none is provided by the SoundSys).
  59 /// That is, typically the main.cpp or similar file of each exe and dll must contain a line like
  60 ///     SoundShaderManagerI* SoundShaderManager=NULL;
  61 /// or else the module will not link successfully due to an undefined symbol.
  62 ///
  63 /// Exe files will then want to reset this pointer to an instance of a SoundShaderManagerImplT during their initialization
  64 /// e.g. by code like:   SoundShaderManager=new SoundShaderManagerImplT;
  65 /// Note that the SoundShaderManagerImplT ctor may require that other interfaces (e.g. the Console) have been inited first.
  66 ///
  67 /// Dlls typically get one of their init functions called immediately after they have been loaded.
  68 /// By doing so, the exe passes a pointer to its above instance to the dll, which in turn copies it to its SoundShaderManager variable.
  69 extern SoundShaderManagerI* SoundShaderManager;
  70
  71 #endif