engines/engine.h

   1 /* ScummVM - Graphic Adventure Engine
   2  *
   3  * ScummVM is the legal property of its developers, whose names
   4  * are too numerous to list here. Please refer to the COPYRIGHT
   5  * file distributed with this source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation; either version 2
  10  * of the License, or (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  20  *
  21  * $URL$
  22  * $Id$
  23  */
  24
  25 #ifndef ENGINES_ENGINE_H
  26 #define ENGINES_ENGINE_H
  27
  28 #include "common/scummsys.h"
  29 #include "common/error.h"
  30 #include "common/fs.h"
  31 #include "common/str.h"
  32
  33 class OSystem;
  34
  35 namespace Audio {
  36         class Mixer;
  37 }
  38 namespace Common {
  39         class EventManager;
  40         class SaveFileManager;
  41         class TimerManager;
  42 }
  43 namespace GUI {
  44         class Debugger;
  45         class Dialog;
  46 }
  47
  48 /**
  49  * Setup the backend's graphics mode.
  50  */
  51 void initCommonGFX(bool defaultTo1XScaler);
  52
  53 /**
  54  * Setup the backend's screen size and graphics mode.
  55  *
  56  * Shows an various warnings on certain backend graphics
  57  * transaction failures (aspect switch, fullscreen switch, etc.).
  58  *
  59  * Errors out when backend is not able to switch to the specified
  60  * mode.
  61  */
  62 void initGraphics(int width, int height, bool defaultTo1xScaler);
  63
  64 /**
  65  * Initializes graphics and shows error message.
  66  */
  67 void GUIErrorMessage(const Common::String msg);
  68
  69
  70 class Engine {
  71 public:
  72         OSystem *_system;
  73         Audio::Mixer *_mixer;
  74
  75 protected:
  76         Common::TimerManager *_timer;
  77         Common::EventManager *_eventMan;
  78         Common::SaveFileManager *_saveFileMan;
  79
  80         GUI::Dialog *_mainMenuDialog;
  81         virtual int runDialog(GUI::Dialog &dialog);
  82
  83         const Common::String _targetName; // target name for saves
  84
  85         const Common::FSNode _gameDataDir;      // FIXME: Get rid of this
  86
  87 private:
  88         /**
  89          * The pause level, 0 means 'running', a positive value indicates
  90          * how often the engine has been paused (and hence how often it has
  91          * to be un-paused before it resumes running). This makes it possible
  92          * to nest code which pauses the engine.
  93          */
  94         int _pauseLevel;
  95
  96 public:
  97
  98
  99         /**
 100          * A feature in this context means an ability of the engine which can be
 101          * either available or not.
 102          * @see Engine::hasFeature()
 103          */
 104         enum EngineFeature {
 105                 /**
 106                  * Enables the subtitle speed and toggle items in the Options section
 107                  * of the global main menu.
 108                  */
 109                 kSupportsSubtitleOptions,
 110
 111                 /**
 112                  * 'Return to launcher' feature is supported, i.e., EVENT_RTL is handled
 113                  * either directly, or indirectly (that is, the engine calls and honors
 114                  * the result of the Engine::shouldQuit() method appropriately).
 115                  */
 116                 kSupportsRTL,
 117
 118                 /**
 119                  * Loading savestates during runtime is supported, that is, this engine
 120                  * implements loadGameState() and canLoadGameStateCurrently().
 121                  * If this feature is supported, then the corresponding MetaEngine *must*
 122                  * support the kSupportsListSaves feature.
 123                  */
 124                 kSupportsLoadingDuringRuntime,
 125
 126                 /**
 127                  * Loading savestates during runtime is supported, that is, this engine
 128                  * implements saveGameState() and canSaveGameStateCurrently().
 129                  * If this feature is supported, then the corresponding MetaEngine *must*
 130                  * support the kSupportsListSaves feature.
 131                  */
 132                 kSupportsSavingDuringRuntime
 133         };
 134
 135
 136
 137         /** @name Overloadable methods
 138          *
 139          *  All Engine subclasses should consider overloading some or all of the following methods.
 140          */
 141         //@{
 142
 143         Engine(OSystem *syst);
 144         virtual ~Engine();
 145
 146         /**
 147          * Init the engine and start its main loop.
 148          * @return returns kNoError on success, else an error code.
 149          */
 150         virtual Common::Error run() = 0;
 151
 152         /**
 153          * Prepare an error string, which is printed by the error() function.
 154          */
 155         virtual void errorString(const char *buf_input, char *buf_output, int buf_output_size);
 156
 157         /**
 158          * Return the engine's debugger instance, if any. Used by error() to
 159          * invoke the debugger when a severe error is reported.
 160          */
 161         virtual GUI::Debugger *getDebugger() { return 0; }
 162
 163         /**
 164          * Determine whether the engine supports the specified feature.
 165          */
 166         virtual bool hasFeature(EngineFeature f) const { return false; }
 167
 168 //      virtual EnginePlugin *getMetaEnginePlugin() const;
 169
 170         /**
 171          * Notify the engine that the sound settings in the config manager may have
 172          * changed and that it hence should adjust any internal volume etc. values
 173          * accordingly.
 174          * @todo find a better name for this
 175          */
 176         virtual void syncSoundSettings();
 177
 178         /**
 179          * Flip mute all sound option.
 180          */
 181         virtual void flipMute();
 182
 183         /**
 184          * Load a game state.
 185          * @param slot  the slot from which a savestate should be loaded
 186          * @return returns kNoError on success, else an error code.
 187          */
 188         virtual Common::Error loadGameState(int slot);
 189
 190         /**
 191          * Indicates whether a game state can be loaded.
 192          */
 193         virtual bool canLoadGameStateCurrently();
 194
 195         /**
 196          * Save a game state.
 197          * @param slot  the slot into which the savestate should be stored
 198          * @param desc  a description for the savestate, entered by the user
 199          * @return returns kNoError on success, else an error code.
 200          */
 201         virtual Common::Error saveGameState(int slot, const char *desc);
 202
 203         /**
 204          * Indicates whether a game state can be saved.
 205          */
 206         virtual bool canSaveGameStateCurrently();
 207
 208 protected:
 209
 210         /**
 211          * Actual implementation of pauseEngine by subclasses. See there
 212          * for details.
 213          */
 214         virtual void pauseEngineIntern(bool pause);
 215
 216         //@}
 217
 218
 219 public:
 220
 221         /**
 222          * Request the engine to quit. Sends a EVENT_QUIT event to the Event
 223          * Manager.
 224          */
 225         static void quitGame();
 226
 227         /**
 228          * Return whether the ENGINE should quit respectively should return to the
 229          * launcher.
 230          */
 231         static bool shouldQuit();
 232
 233         /**
 234          * Pause or resume the engine. This should stop/resume any audio playback
 235          * and other stuff. Called right before the system runs a global dialog
 236          * (like a global pause, main menu, options or 'confirm exit' dialog).
 237          *
 238          * This is a convenience tracker which automatically keeps track on how
 239          * often the engine has been paused, ensuring that after pausing an engine
 240          * e.g. twice, it has to be unpaused twice before actuallying resuming.
 241          *
 242          * @param pause         true to pause the engine, false to resume it
 243          */
 244         void pauseEngine(bool pause);
 245
 246         /**
 247          * Return whether the engine is currently paused or not.
 248          */
 249         bool isPaused() const { return _pauseLevel != 0; }
 250
 251         /**
 252          * Run the Global Main Menu Dialog
 253          */
 254         void openMainMenuDialog();
 255
 256         inline Common::TimerManager *getTimerManager() { return _timer; }
 257         inline Common::EventManager *getEventManager() { return _eventMan; }
 258         inline Common::SaveFileManager *getSaveFileManager() { return _saveFileMan; }
 259
 260 public:
 261
 262         /** On some systems, check if the game appears to be run from CD. */
 263         void checkCD();
 264
 265 protected:
 266
 267         /**
 268          * Indicate whether an autosave should be performed.
 269          */
 270         bool shouldPerformAutoSave(int lastSaveTime);
 271
 272 };
 273
 274 extern Engine *g_engine;
 275
 276 #endif