neo/framework/DeclManager.h

   1 /*
   2 ===========================================================================
   3
   4 Doom 3 GPL Source Code
   5 Copyright (C) 1999-2011 id Software LLC, a ZeniMax Media company.
   6
   7 This file is part of the Doom 3 GPL Source Code (?Doom 3 Source Code?).
   8
   9 Doom 3 Source Code is free software: you can redistribute it and/or modify
  10 it under the terms of the GNU General Public License as published by
  11 the Free Software Foundation, either version 3 of the License, or
  12 (at your option) any later version.
  13
  14 Doom 3 Source Code is distributed in the hope that it will be useful,
  15 but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 GNU General Public License for more details.
  18
  19 You should have received a copy of the GNU General Public License
  20 along with Doom 3 Source Code.  If not, see <http://www.gnu.org/licenses/>.
  21
  22 In addition, the Doom 3 Source Code is also subject to certain additional terms. You should have received a copy of these additional terms immediately following the terms and conditions of the GNU General Public License which accompanied the Doom 3 Source Code.  If not, please request a copy in writing from id Software at the address below.
  23
  24 If you have questions concerning this license or the applicable additional terms, you may contact in writing id Software LLC, c/o ZeniMax Media Inc., Suite 120, Rockville, Maryland 20850 USA.
  25
  26 ===========================================================================
  27 */
  28
  29 #ifndef __DECLMANAGER_H__
  30 #define __DECLMANAGER_H__
  31
  32 /*
  33 ===============================================================================
  34
  35         Declaration Manager
  36
  37         All "small text" data types, like materials, sound shaders, fx files,
  38         entity defs, etc. are managed uniformly, allowing reloading, purging,
  39         listing, printing, etc. All "large text" data types that never have more
  40         than one declaration in a given file, like maps, models, AAS files, etc.
  41         are not handled here.
  42
  43         A decl will never, ever go away once it is created. The manager is
  44         garranteed to always return the same decl pointer for a decl type/name
  45         combination. The index of a decl in the per type list also stays the
  46         same throughout the lifetime of the engine. Although the pointer to
  47         a decl always stays the same, one should never maintain pointers to
  48         data inside decls. The data stored in a decl is not garranteed to stay
  49         the same for more than one engine frame.
  50
  51         The decl indexes of explicitely defined decls are garrenteed to be
  52         consistent based on the parsed decl files. However, the indexes of
  53         implicit decls may be different based on the order in which levels
  54         are loaded.
  55
  56         The decl namespaces are separate for each type. Comments for decls go
  57         above the text definition to keep them associated with the proper decl.
  58
  59         During decl parsing, errors should never be issued, only warnings
  60         followed by a call to MakeDefault().
  61
  62 ===============================================================================
  63 */
  64
  65 typedef enum {
  66         DECL_TABLE                              = 0,
  67         DECL_MATERIAL,
  68         DECL_SKIN,
  69         DECL_SOUND,
  70         DECL_ENTITYDEF,
  71         DECL_MODELDEF,
  72         DECL_FX,
  73         DECL_PARTICLE,
  74         DECL_AF,
  75         DECL_PDA,
  76         DECL_VIDEO,
  77         DECL_AUDIO,
  78         DECL_EMAIL,
  79         DECL_MODELEXPORT,
  80         DECL_MAPDEF,
  81
  82         // new decl types can be added here
  83
  84         DECL_MAX_TYPES                  = 32
  85 } declType_t;
  86
  87 typedef enum {
  88         DS_UNPARSED,
  89         DS_DEFAULTED,                   // set if a parse failed due to an error, or the lack of any source
  90         DS_PARSED
  91 } declState_t;
  92
  93 const int DECL_LEXER_FLAGS      =       LEXFL_NOSTRINGCONCAT |                          // multiple strings seperated by whitespaces are not concatenated
  94                                                                 LEXFL_NOSTRINGESCAPECHARS |                     // no escape characters inside strings
  95                                                                 LEXFL_ALLOWPATHNAMES |                          // allow path seperators in names
  96                                                                 LEXFL_ALLOWMULTICHARLITERALS |          // allow multi character literals
  97                                                                 LEXFL_ALLOWBACKSLASHSTRINGCONCAT |      // allow multiple strings seperated by '\' to be concatenated
  98                                                                 LEXFL_NOFATALERRORS;                            // just set a flag instead of fatal erroring
  99
 100
 101 class idDeclBase {
 102 public:
 103         virtual                                 ~idDeclBase() {};
 104         virtual const char *    GetName( void ) const = 0;
 105         virtual declType_t              GetType( void ) const = 0;
 106         virtual declState_t             GetState( void ) const = 0;
 107         virtual bool                    IsImplicit( void ) const = 0;
 108         virtual bool                    IsValid( void ) const = 0;
 109         virtual void                    Invalidate( void ) = 0;
 110         virtual void                    Reload( void ) = 0;
 111         virtual void                    EnsureNotPurged( void ) = 0;
 112         virtual int                             Index( void ) const = 0;
 113         virtual int                             GetLineNum( void ) const = 0;
 114         virtual const char *    GetFileName( void ) const = 0;
 115         virtual void                    GetText( char *text ) const = 0;
 116         virtual int                             GetTextLength( void ) const = 0;
 117         virtual void                    SetText( const char *text ) = 0;
 118         virtual bool                    ReplaceSourceFileText( void ) = 0;
 119         virtual bool                    SourceFileChanged( void ) const = 0;
 120         virtual void                    MakeDefault( void ) = 0;
 121         virtual bool                    EverReferenced( void ) const = 0;
 122         virtual bool                    SetDefaultText( void ) = 0;
 123         virtual const char *    DefaultDefinition( void ) const = 0;
 124         virtual bool                    Parse( const char *text, const int textLength ) = 0;
 125         virtual void                    FreeData( void ) = 0;
 126         virtual size_t                  Size( void ) const = 0;
 127         virtual void                    List( void ) const = 0;
 128         virtual void                    Print( void ) const = 0;
 129 };
 130
 131
 132 class idDecl {
 133 public:
 134                                                         // The constructor should initialize variables such that
 135                                                         // an immediate call to FreeData() does no harm.
 136                                                         idDecl( void ) { base = NULL; }
 137         virtual                                 ~idDecl( void ) {};
 138
 139                                                         // Returns the name of the decl.
 140         const char *                    GetName( void ) const { return base->GetName(); }
 141
 142                                                         // Returns the decl type.
 143         declType_t                              GetType( void ) const { return base->GetType(); }
 144
 145                                                         // Returns the decl state which is usefull for finding out if a decl defaulted.
 146         declState_t                             GetState( void ) const { return base->GetState(); }
 147
 148                                                         // Returns true if the decl was defaulted or the text was created with a call to SetDefaultText.
 149         bool                                    IsImplicit( void ) const { return base->IsImplicit(); }
 150
 151                                                         // The only way non-manager code can have an invalid decl is if the *ByIndex()
 152                                                         // call was used with forceParse = false to walk the lists to look at names
 153                                                         // without touching the media.
 154         bool                                    IsValid( void ) const { return base->IsValid(); }
 155
 156                                                         // Sets state back to unparsed.
 157                                                         // Used by decl editors to undo any changes to the decl.
 158         void                                    Invalidate( void ) { base->Invalidate(); }
 159
 160                                                         // if a pointer might possible be stale from a previous level,
 161                                                         // call this to have it re-parsed
 162         void                                    EnsureNotPurged( void ) { base->EnsureNotPurged(); }
 163
 164                                                         // Returns the index in the per-type list.
 165         int                                             Index( void ) const { return base->Index(); }
 166
 167                                                         // Returns the line number the decl starts.
 168         int                                             GetLineNum( void ) const { return base->GetLineNum(); }
 169
 170                                                         // Returns the name of the file in which the decl is defined.
 171         const char *                    GetFileName( void ) const { return base->GetFileName(); }
 172
 173                                                         // Returns the decl text.
 174         void                                    GetText( char *text ) const { base->GetText( text ); }
 175
 176                                                         // Returns the length of the decl text.
 177         int                                             GetTextLength( void ) const { return base->GetTextLength(); }
 178
 179                                                         // Sets new decl text.
 180         void                                    SetText( const char *text ) { base->SetText( text ); }
 181
 182                                                         // Saves out new text for the decl.
 183                                                         // Used by decl editors to replace the decl text in the source file.
 184         bool                                    ReplaceSourceFileText( void ) { return base->ReplaceSourceFileText(); }
 185
 186                                                         // Returns true if the source file changed since it was loaded and parsed.
 187         bool                                    SourceFileChanged( void ) const { return base->SourceFileChanged(); }
 188
 189                                                         // Frees data and makes the decl a default.
 190         void                                    MakeDefault( void ) { base->MakeDefault(); }
 191
 192                                                         // Returns true if the decl was ever referenced.
 193         bool                                    EverReferenced( void ) const { return base->EverReferenced(); }
 194
 195 public:
 196                                                         // Sets textSource to a default text if necessary.
 197                                                         // This may be overridden to provide a default definition based on the
 198                                                         // decl name. For instance materials may default to an implicit definition
 199                                                         // using a texture with the same name as the decl.
 200         virtual bool                    SetDefaultText( void ) { return base->SetDefaultText(); }
 201
 202                                                         // Each declaration type must have a default string that it is guaranteed
 203                                                         // to parse acceptably. When a decl is not explicitly found, is purged, or
 204                                                         // has an error while parsing, MakeDefault() will do a FreeData(), then a
 205                                                         // Parse() with DefaultDefinition(). The defaultDefintion should start with
 206                                                         // an open brace and end with a close brace.
 207         virtual const char *    DefaultDefinition( void ) const { return base->DefaultDefinition(); }
 208
 209                                                         // The manager will have already parsed past the type, name and opening brace.
 210                                                         // All necessary media will be touched before return.
 211                                                         // The manager will have called FreeData() before issuing a Parse().
 212                                                         // The subclass can call MakeDefault() internally at any point if
 213                                                         // there are parse errors.
 214         virtual bool                    Parse( const char *text, const int textLength ) { return base->Parse( text, textLength ); }
 215
 216                                                         // Frees any pointers held by the subclass. This may be called before
 217                                                         // any Parse(), so the constructor must have set sane values. The decl will be
 218                                                         // invalid after issuing this call, but it will always be immediately followed
 219                                                         // by a Parse()
 220         virtual void                    FreeData( void ) { base->FreeData(); }
 221
 222                                                         // Returns the size of the decl in memory.
 223         virtual size_t                  Size( void ) const { return base->Size(); }
 224
 225                                                         // If this isn't overridden, it will just print the decl name.
 226                                                         // The manager will have printed 7 characters on the line already,
 227                                                         // containing the reference state and index number.
 228         virtual void                    List( void ) const { base->List(); }
 229
 230                                                         // The print function will already have dumped the text source
 231                                                         // and common data, subclasses can override this to dump more
 232                                                         // explicit data.
 233         virtual void                    Print( void ) const { base->Print(); }
 234
 235 public:
 236         idDeclBase *                    base;
 237 };
 238
 239
 240 template< class type >
 241 ID_INLINE idDecl *idDeclAllocator( void ) {
 242         return new type;
 243 }
 244
 245
 246 class idMaterial;
 247 class idDeclSkin;
 248 class idSoundShader;
 249
 250 class idDeclManager {
 251 public:
 252         virtual                                 ~idDeclManager( void ) {}
 253
 254         virtual void                    Init( void ) = 0;
 255         virtual void                    Shutdown( void ) = 0;
 256         virtual void                    Reload( bool force ) = 0;
 257
 258         virtual void                    BeginLevelLoad() = 0;
 259         virtual void                    EndLevelLoad() = 0;
 260
 261                                                         // Registers a new decl type.
 262         virtual void                    RegisterDeclType( const char *typeName, declType_t type, idDecl *(*allocator)( void ) ) = 0;
 263
 264                                                         // Registers a new folder with decl files.
 265         virtual void                    RegisterDeclFolder( const char *folder, const char *extension, declType_t defaultType ) = 0;
 266
 267                                                         // Returns a checksum for all loaded decl text.
 268         virtual int                             GetChecksum( void ) const = 0;
 269
 270                                                         // Returns the number of decl types.
 271         virtual int                             GetNumDeclTypes( void ) const = 0;
 272
 273                                                         // Returns the type name for a decl type.
 274         virtual const char *    GetDeclNameFromType( declType_t type ) const = 0;
 275
 276                                                         // Returns the decl type for a type name.
 277         virtual declType_t              GetDeclTypeFromName( const char *typeName ) const = 0;
 278
 279                                                         // If makeDefault is true, a default decl of appropriate type will be created
 280                                                         // if an explicit one isn't found. If makeDefault is false, NULL will be returned
 281                                                         // if the decl wasn't explcitly defined.
 282         virtual const idDecl *  FindType( declType_t type, const char *name, bool makeDefault = true ) = 0;
 283
 284         virtual const idDecl*   FindDeclWithoutParsing( declType_t type, const char *name, bool makeDefault = true ) = 0;
 285
 286         virtual void                    ReloadFile( const char* filename, bool force ) = 0;
 287
 288                                                         // Returns the number of decls of the given type.
 289         virtual int                             GetNumDecls( declType_t type ) = 0;
 290
 291                                                         // The complete lists of decls can be walked to populate editor browsers.
 292                                                         // If forceParse is set false, you can get the decl to check name / filename / etc.
 293                                                         // without causing it to parse the source and load media.
 294         virtual const idDecl *  DeclByIndex( declType_t type, int index, bool forceParse = true ) = 0;
 295
 296                                                         // List and print decls.
 297         virtual void                    ListType( const idCmdArgs &args, declType_t type ) = 0;
 298         virtual void                    PrintType( const idCmdArgs &args, declType_t type ) = 0;
 299
 300                                                         // Creates a new default decl of the given type with the given name in
 301                                                         // the given file used by editors to create a new decls.
 302         virtual idDecl *                CreateNewDecl( declType_t type, const char *name, const char *fileName ) = 0;
 303
 304                                                         // BSM - Added for the material editors rename capabilities
 305         virtual bool                    RenameDecl( declType_t type, const char* oldName, const char* newName ) = 0;
 306
 307                                                         // When media files are loaded, a reference line can be printed at a
 308                                                         // proper indentation if decl_show is set
 309         virtual void                    MediaPrint( const char *fmt, ... ) id_attribute((format(printf,2,3))) = 0;
 310
 311         virtual void                    WritePrecacheCommands( idFile *f ) = 0;
 312
 313                                                                         // Convenience functions for specific types.
 314         virtual const idMaterial *              FindMaterial( const char *name, bool makeDefault = true ) = 0;
 315         virtual const idDeclSkin *              FindSkin( const char *name, bool makeDefault = true ) = 0;
 316         virtual const idSoundShader *   FindSound( const char *name, bool makeDefault = true ) = 0;
 317
 318         virtual const idMaterial *              MaterialByIndex( int index, bool forceParse = true ) = 0;
 319         virtual const idDeclSkin *              SkinByIndex( int index, bool forceParse = true ) = 0;
 320         virtual const idSoundShader *   SoundByIndex( int index, bool forceParse = true ) = 0;
 321 };
 322
 323 extern idDeclManager *          declManager;
 324
 325
 326 template< declType_t type >
 327 ID_INLINE void idListDecls_f( const idCmdArgs &args ) {
 328         declManager->ListType( args, type );
 329 }
 330
 331 template< declType_t type >
 332 ID_INLINE void idPrintDecls_f( const idCmdArgs &args ) {
 333         declManager->PrintType( args, type );
 334 }
 335
 336 #endif /* !__DECLMANAGER_H__ */