[Scummvm-git-logs] scummvm master -> f04056519a2dadb5050683fb24774d5ea459be19
criezy
criezy at scummvm.org
Wed Dec 2 00:13:52 UTC 2020
This automated email contains information about 1 new commit which have been
pushed to the 'scummvm' repo located at https://github.com/scummvm/scummvm .
Summary:
f04056519a DOXYGEN: Review of high prio headers from engines
Commit: f04056519a2dadb5050683fb24774d5ea459be19
https://github.com/scummvm/scummvm/commit/f04056519a2dadb5050683fb24774d5ea459be19
Author: Bartosz Gentkowski (bartosz.gentkowski at nordicsemi.no)
Date: 2020-12-02T00:13:49Z
Commit Message:
DOXYGEN: Review of high prio headers from engines
This is a doxygen review for 4 header files that have been
identified as high priority for GSoD:
- advancedDetector.h
- metaengine.h
- engine.h
- util.h
It also adds doxy groups to other headers from this folder to
make them appear properly in the structure.
Changed paths:
doc/doxygen/groups.dox
engines/advancedDetector.h
engines/engine.h
engines/game.h
engines/metaengine.h
engines/obsolete.h
engines/savestate.h
engines/util.h
diff --git a/doc/doxygen/groups.dox b/doc/doxygen/groups.dox
index 4b037bfe41..de451ecf82 100644
--- a/doc/doxygen/groups.dox
+++ b/doc/doxygen/groups.dox
@@ -1,38 +1,37 @@
/**
@defgroup common Common API
- at brief Common functions and structures.
+ at brief Common classes, functions, and structures.
*/
/**
-
- at defgroup lua Lua API
+ at defgroup lua Lua
@ingroup common
@brief Functions for the Lua programming language. See @linkLua.
-
*/
/**
- at defgroup graphics Graphics API
- at brief API related to on-screen graphics - surfaces, pixels, cursors, fonts, palettes, and renderers.
+ at defgroup audio Audio API
+ at brief APIs for managing in-game audio.
*/
/**
- at defgroup image Image API
- at brief API of various image decoders used in engines.
+ at defgroup engines Engine API
+ at brief API related to engines.
*/
/**
- at defgroup audio Audio API
- at brief APIs for managing in-game audio.
+ at defgroup graphics Graphics API
+ at brief API related to on-screen graphics - surfaces, pixels, cursors, fonts, palettes, and renderers.
*/
+
/**
@defgroup image Image API
diff --git a/engines/advancedDetector.h b/engines/advancedDetector.h
index 971afa85e4..14744d557c 100644
--- a/engines/advancedDetector.h
+++ b/engines/advancedDetector.h
@@ -34,14 +34,22 @@ namespace Common {
class Error;
class FSList;
}
-
+/**
+ * @defgroup engines_advdetector Advanced Detector
+ * @ingroup engines
+ *
+ * @brief The Advanced Detector (AD) provides a standard framework for filename and MD5-based game detection.
+ *
+ * @{
+ */
+
/**
* A record describing a file to be matched for detecting a specific game
* variant. A list of such records is used inside every ADGameDescription to
* enable detection.
*/
struct ADGameFileDescription {
- const char *fileName; ///< Name of described file.
+ const char *fileName; ///< Name of the described file.
uint16 fileType; ///< Optional. Not used during detection, only by engines.
const char *md5; ///< MD5 of (the beginning of) the described file. Optional. Set to NULL to ignore.
int32 fileSize; ///< Size of the described file. Set to -1 to ignore.
@@ -67,70 +75,118 @@ struct ADGameFileDescription {
/**
* A shortcut to produce a list of ADGameFileDescription records with only two
- * records that contains just a filename with an MD5, plus a file size.
+ * records that contain just a filename with an MD5, plus a file size.
*/
#define AD_ENTRY2s(f1, x1, s1, f2, x2, s2) {{f1, 0, x1, s1}, {f2, 0, x2, s2}, AD_LISTEND}
+/**
+ * Flags used in the game description.
+ */
enum ADGameFlags {
- ADGF_NO_FLAGS = 0,
- ADGF_REMASTERED = (1 << 18), ///< add "-remastered' to gameid
- ADGF_AUTOGENTARGET = (1 << 19), ///< automatically generate gameid from extra
- ADGF_UNSTABLE = (1 << 20), ///< flag to designate not yet officially-supported games that are not fit for public testing
- ADGF_TESTING = (1 << 21), ///< flag to designate not yet officially-supported games that are fit for public testing
- ADGF_PIRATED = (1 << 22), ///< flag to designate well known pirated versions with cracks
- ADGF_UNSUPPORTED = (1 << 23), ///< flag to mark certain versions (like fan translations) not to be run for various reasons. A custom message can be provided in the ADGameDescription::extra field.
- ADGF_ADDENGLISH = (1 << 24), ///< always add English as language option
- ADGF_MACRESFORK = (1 << 25), ///< the md5 for this entry will be calculated from the resource fork
- ADGF_USEEXTRAASTITLE = (1 << 26), ///< Extra field value will be used as main game title, not gameid
- ADGF_DROPLANGUAGE = (1 << 27), ///< don't add language to gameid
- ADGF_DROPPLATFORM = (1 << 28), ///< don't add platform to gameid
- ADGF_CD = (1 << 29), ///< add "-cd" to gameid
- ADGF_DEMO = (1 << 30) ///< add "-demo" to gameid
+ ADGF_NO_FLAGS = 0, ///< No flags.
+ ADGF_REMASTERED = (1 << 18), ///< Add "-remastered' to gameid.
+ ADGF_AUTOGENTARGET = (1 << 19), ///< Automatically generate gameid from @ref ADGameDescription::extra.
+ ADGF_UNSTABLE = (1 << 20), ///< Flag to designate not yet officially supported games that are not fit for public testing.
+ ADGF_TESTING = (1 << 21), ///< Flag to designate not yet officially supported games that are fit for public testing.
+ ADGF_PIRATED = (1 << 22), ///< Flag to designate well-known pirated versions with cracks.
+ ADGF_UNSUPPORTED = (1 << 23), /*!< Flag to mark certain versions (like fan translations) not to be run for various reasons.
+ A custom message can be provided in the @ref ADGameDescription::extra field. */
+ ADGF_ADDENGLISH = (1 << 24), ///< Always add English as a language option.
+ ADGF_MACRESFORK = (1 << 25), ///< Calculate the MD5 for this entry from the resource fork.
+ ADGF_USEEXTRAASTITLE = (1 << 26), ///< Use @ref ADGameDescription::extra as the main game title, not gameid.
+ ADGF_DROPLANGUAGE = (1 << 27), ///< Do not add language to gameid.
+ ADGF_DROPPLATFORM = (1 << 28), ///< Do not add platform to gameid.
+ ADGF_CD = (1 << 29), ///< Add "-cd" to gameid.
+ ADGF_DEMO = (1 << 30) ///< Add "-demo" to gameid.
};
+/**
+ * Data table describing a game variant.
+ */
struct ADGameDescription {
+ /**
+ * The gameid that identifies the game.
+ *
+ * Mainly used for taking the game description from the @ref PlainGameDescriptor table.
+ */
const char *gameId;
+
+ /**
+ * Field that is used to distinguish between different variants of a game.
+ *
+ * The content of this field is inserted in the generated description for the config file game entry.
+ * If the @ref kADFlagUseExtraAsHint ADFlag is set, the contents of this field are stored
+ * in the config file, and are used to additionally distinguish between game variants.
+ * Also, if the ADGF_USEEXTRAASTITLE game flag is set, the contents of this field
+ * will be used as a description instead the one extracted from the @ref PlainGameDescriptor table.
+ */
const char *extra;
+
+ /**
+ * A list of individual file entries used for detection.
+ *
+ * 13 files (last is zero-terminated) is the maximum number of files currently used in ScummVM.
+ * A hardcoded number is used here due to a C++ limitation for defining const arrays.
+ */
ADGameFileDescription filesDescriptions[14];
+
+ /**
+ * Language of the game variant.
+ */
Common::Language language;
+
+ /**
+ * Platform of the game variant.
+ */
Common::Platform platform;
/**
- * A bitmask of extra flags. The top 16 bits are reserved for generic flags
- * defined in the ADGameFlags. This leaves 16 bits to be used by client
- * code.
+ * A bitmask of extra flags.
+ *
+ * The top 16 bits are reserved for generic flags defined in @ref ADGameFlags.
+ * This leaves 16 bits to be used by the client code.
*/
uint32 flags;
+ /**
+ * Game features that are user-controllable.
+ *
+ * This list reflects which features of the GUI should be turned on or off in order to minimize user confusion.
+ * For instance, there is no point in changing game language in single-language games
+ * or have MIDI controls in a game that only supports digital music.
+ */
const char *guiOptions;
};
/**
- * A game installation matching an AD game description
+ * A game installation matching an AD game description.
*/
struct ADDetectedGame {
- bool hasUnknownFiles;
- FilePropertiesMap matchedFiles;
- const ADGameDescription *desc;
+ bool hasUnknownFiles; /*!< Whether the game has unknown files. */
+ FilePropertiesMap matchedFiles; /*!< List of the files that were used to match the game. */
+ const ADGameDescription *desc; /*!< Human-readable game title. */
ADDetectedGame() : desc(nullptr), hasUnknownFiles(false) {}
+ /**
+ * Construct an ADDetectedGame object.
+ */
explicit ADDetectedGame(const ADGameDescription *d) : desc(d), hasUnknownFiles(false) {}
};
-/** A list of games detected by the AD */
+/** A list of games detected by the AD. */
typedef Common::Array<ADDetectedGame> ADDetectedGames;
/**
- * End marker for a table of ADGameDescription structs. Use this to
- * terminate a list to be passed to the AdvancedDetector API.
+ * End marker for a table of @ref ADGameDescription structures. Use this to
+ * terminate a list to be passed to the Advanced Detector API.
*/
#define AD_TABLE_END_MARKER \
{ NULL, NULL, { { NULL, 0, NULL, 0 } }, Common::UNK_LANG, Common::kPlatformUnknown, ADGF_NO_FLAGS, GUIO0() }
struct ADFileBasedFallback {
/**
- * Pointer to an ADGameDescription or subclass thereof which will get
- * returned if there's a detection match.
+ * Pointer to an @ref ADGameDescription or its subclass that will be
+ * returned if there is a detection match.
*/
const ADGameDescription *desc;
@@ -144,9 +200,11 @@ struct ADFileBasedFallback {
enum ADFlags {
/**
- * Store value of extra field in config file, and use it as a hint
- * on subsequent runs. Could be used when there is no way to autodetect
- * game (when more than one game sits in same directory), and user picks
+ * Store the value of the @ref ADGameDescription::extra field
+ * in the config file, and use it as a hint on subsequent runs.
+ *
+ * This can be used when there is no way to autodetect the game
+ * (when more than one game are located in same directory), and the user picks
* up a variant manually.
* In addition, this is useful if two variants of a game sharing the same
* gameid are contained in a single directory.
@@ -156,39 +214,34 @@ enum ADFlags {
/**
- * Map entry for mapping GUIO_GAMEOPTIONS* to their ExtraGuiOption
+ * Map entry for mapping GUIO_GAMEOPTIONS* to their @ref ExtraGuiOption
* description.
*/
struct ADExtraGuiOptionsMap {
- /**
- * GUIO_GAMEOPTION* string.
- */
- const char *guioFlag;
-
- /**
- * The associated option.
- */
- ExtraGuiOption option;
+ const char *guioFlag; /*!< GUIO_GAMEOPTION* string. */
+ ExtraGuiOption option; /*!< The associated option. */
};
#define AD_EXTRA_GUI_OPTIONS_TERMINATOR { 0, { 0, 0, 0, 0 } }
/**
- * A MetaEngineDetection implementation based around the advanced detector code.
+ * A @ref MetaEngineDetection implementation based on the Advanced Detector code.
*/
class AdvancedMetaEngineDetection : public MetaEngineDetection {
protected:
/**
* Pointer to an array of objects which are either ADGameDescription
- * or superset structures (i.e. start with an ADGameDescription member.
+ * or superset structures (i.e. start with an ADGameDescription member).
+ *
* The list is terminated by an entry with a gameid equal to 0
- * (see AD_TABLE_END_MARKER).
+ * (see @ref AD_TABLE_END_MARKER).
*/
const byte *_gameDescriptors;
/**
- * The size of a single entry of the above descs array. Always
- * must be >= sizeof(ADGameDescription).
+ * The size of a single entry of the above descriptions array.
+ *
+ * Always must be >= sizeof(ADGameDescription).
*/
const uint _descItemSize;
@@ -204,10 +257,11 @@ protected:
const ADExtraGuiOptionsMap * const _extraGuiOptions;
/**
- * The number of bytes to compute MD5 sum for. The AdvancedDetector
- * is primarily based on computing and matching MD5 checksums of files.
- * Since doing that for large files can be slow, it can be restricted
- * to a subset of all files.
+ * The number of bytes to compute the MD5 checksum for.
+ *
+ * The Advanced Detector is primarily based on computing and matching
+ * MD5 checksums of files. Since doing that for large files can be slow,
+ * it can be restricted to a subset of all files.
* Typically this will be set to something between 5 and 50 kilobytes,
* but arbitrary non-zero values are possible. The default is 5000.
*/
@@ -215,78 +269,112 @@ protected:
/**
* A bitmask of flags which can be used to configure the behavior
- * of the AdvancedDetector. Refer to ADFlags for a list of flags
- * that can be ORed together and passed here.
+ * of the Advanced Detector.
+ *
+ * See @ref ADFlags for a list of flags that can be ORed together and passed here.
*/
uint32 _flags;
/**
* A list of game GUI options which will be added to each
- * entry in addition to per-game options. Refer to GameGUIOption
- * enum for the list.
+ * entry in addition to per-game options.
+ *
+ * Refer to @ref GameGUIOption enum for the list.
*/
Common::String _guiOptions;
/**
* Maximum depth of directories to look up.
- * If set to 0, the depth is 1 level
+ *
+ * If set to 0, the depth is 1 level.
*/
uint32 _maxScanDepth;
/**
- * Case-insensitive list of directory globs which could be used for
+ * Case-insensitive list of directory globs that can be used for
* going deeper into the directory structure.
- * @see String::matchString() method for format description.
*
- * @note Last item must be 0
+ * See @ref String::matchString() method for format description.
+ *
+ * @note The last item must be 0.
*/
const char * const *_directoryGlobs;
/**
* If true, filenames will be matched against the entire path, relative to
- * the root detection directory (e.g. "foo/bar.000" for a file at
- * "<root>/foo/bar.000"). Otherwise, filenames only match the basename
- * (e.g. "bar.000" for the same file).
+ * the root detection directory.
+ *
+ * For example: "foo/bar.000" for a file at "<root>/foo/bar.000").
+ * Otherwise, filenames only match the base name (e.g. "bar.000" for the same file).
*
- * @note _maxScanDepth and _directoryGlobs must still be configured to allow
+ * @note @c _maxScanDepth and @c _directoryGlobs must still be configured to allow
* the detector to find files inside subdirectories.
*/
bool _matchFullPaths;
/**
- * If we use ADGF_AUTOGENTARGET, then this specifies the max length
- * of the autogenerated name. The default is 15
+ * If ADGF_AUTOGENTARGET is used, then this specifies the max length
+ * of the autogenerated name.
+ * The default is 15.
*/
int _maxAutogenLength;
public:
+ /**
+ * Initialize game detection using AdvancedMetaEngineDetection.
+ */
AdvancedMetaEngineDetection(const void *descs, uint descItemSize, const PlainGameDescriptor *gameIds, const ADExtraGuiOptionsMap *extraGuiOptions = 0);
/**
- * Returns list of targets supported by the engine.
- * Distinguishes engines with single ID
+ * Return a list of targets supported by the engine.
+ *
+ * Distinguishes engines with a single ID.
*/
PlainGameList getSupportedGames() const override;
+ /** Query the engine for a @ref PlainGameDescriptor for the specified gameid, if any. */
PlainGameDescriptor findGame(const char *gameId) const override;
+ /**
+ * Run the engine's game detector on the given list of files, and return a
+ * (possibly empty) list of games supported by the engine that were
+ * found among the given files.
+ */
DetectedGames detectGames(const Common::FSList &fslist) const override;
/**
* A generic createInstance.
+ *
* For instantiating engine objects, this method is called first,
* and then the subclass implemented createInstance is called from within.
*/
Common::Error createInstance(OSystem *syst, Engine **engine) const;
+ /**
+ * Return a list of extra GUI options for the specified target.
+ *
+ * If no target is specified, all of the available custom GUI options are
+ * returned for the plugin (used to set default values).
+ *
+ * Currently, this only supports options with checkboxes.
+ *
+ * The default implementation returns an empty list.
+ *
+ * @param target Name of a config manager target.
+ *
+ * @return A list of extra GUI options for an engine plugin and target.
+ */
virtual const ExtraGuiOptions getExtraGuiOptions(const Common::String &target) const override;
protected:
+ /**
+ * A hashmap of files and their MD5 checksums.
+ */
typedef Common::HashMap<Common::String, Common::FSNode, Common::IgnoreCase_Hash, Common::IgnoreCase_EqualTo> FileMap;
/**
- * An (optional) generic fallback detect function which is invoked
- * if the regular MD5 based detection failed to detect anything.
+ * An (optional) generic fallback detection function that is invoked
+ * if the regular MD5-based detection failed to detect anything.
*/
virtual ADDetectedGame fallbackDetect(const FileMap &allFiles, const Common::FSList &fslist) const {
return ADDetectedGame();
@@ -297,45 +385,48 @@ private:
protected:
/**
- * Detect games in specified directory.
- * Parameters language and platform are used to pass on values
+ * Detect games in the specified directory.
+ *
+ * Parameters @p language and @p platform are used to pass the values
* specified by the user. This is used to restrict search scope.
*
- * @param allFiles list of all present files, as computed by composeFileHashMap
- * @param language restrict results to specified language
- * @param platform restrict results to specified platform
- * @param extra restrict results to specified extra string (only if kADFlagUseExtraAsHint is set)
- * @return list of ADGameDescription pointers corresponding to matched games
+ * @param parent Parent node of this file node.
+ * @param allFiles List of all present files, as computed by the @ref composeFileHashMap.
+ * @param language Restrict results to the specified language.
+ * @param platform Restrict results to the specified platform.
+ * @param extra Restrict results to the specified @c extra string (only if @ref kADFlagUseExtraAsHint is set).
+ *
+ * @return A list of @ref ADGameDescription pointers corresponding to the matched games.
*/
virtual ADDetectedGames detectGame(const Common::FSNode &parent, const FileMap &allFiles, Common::Language language, Common::Platform platform, const Common::String &extra) const;
/**
- * Iterates over all ADFileBasedFallback records inside fileBasedFallback.
- * This then returns the record (or rather, the ADGameDescription
+ * Iterate over all @ref ADFileBasedFallback records inside @p fileBasedFallback
+ * and return the record (or rather, the ADGameDescription
* contained in it) for which all files described by it are present, and
* among those the one with the maximal number of matching files.
+ *
* In case of a tie, the entry coming first in the list is chosen.
*
- * @param allFiles a map describing all present files
- * @param fslist a list of nodes for all present files
- * @param fileBasedFallback a list of ADFileBasedFallback records, zero-terminated
- * @param filesProps if not 0, return a map of properties for all detected files here
+ * @param allFiles Map describing all present files
+ * @param fileBasedFallback List of ADFileBasedFallback records, zero-terminated.
*/
ADDetectedGame detectGameFilebased(const FileMap &allFiles, const ADFileBasedFallback *fileBasedFallback) const;
/**
- * Compose a hashmap of all files in fslist.
- * Includes nifty stuff like removing trailing dots and ignoring case.
+ * Compose a hashmap of all files in @p fslist.
+ *
+ * Removes trailing dots and ignores case in the process.
*/
void composeFileHashMap(FileMap &allFiles, const Common::FSList &fslist, int depth, const Common::String &parentName = Common::String()) const;
/** Get the properties (size and MD5) of this file. */
bool getFileProperties(const FileMap &allFiles, const ADGameDescription &game, const Common::String fname, FileProperties &fileProps) const;
- /** Convert an AD game description into the shared game description format */
+ /** Convert an AD game description into the shared game description format. */
virtual DetectedGame toDetectedGame(const ADDetectedGame &adGame) const;
- friend class FileMapArchive; // for FileMap
+ friend class FileMapArchive;
};
/**
@@ -344,41 +435,48 @@ protected:
class AdvancedMetaEngine : public MetaEngine {
public:
/**
- * Base createInstance for AMEC.
- * The AME provides a default createInstance which is called first, so we should invoke that
- * first.
- * By the point of time we call this, we assume that we only have one
+ * Base createInstance for AdvancedMetaEngine.
+ *
+ * The AdvancedMetaEngine provides a default createInstance that is called first,
+ * so this should be invoked first.
+ * By the time this is called, it is assumed that there is only one
* plugin engine loaded in memory.
*/
virtual Common::Error createInstance(OSystem *syst, Engine **engine) const override;
/**
- * To be implemented by subclasses, which is called after we call the base
- * createInstance function above.
+ * A createInstance implementation for subclasses. To be called after the base
+ * createInstance function above is called.
*/
virtual bool createInstance(OSystem *syst, Engine **engine, const ADGameDescription *desc) const = 0;
/**
- * Provide the engineID here, must match the one from MetaEngine.
+ * Return the name of the engine plugin based on the engineID.
+ *
+ * The the engineID must match the one from MetaEngine.
*
* @see MetaEngineConnect::getName().
*/
virtual const char *getName() const override = 0;
public:
+ /**
+ * A hashmap of files and their MD5 checksums.
+ */
typedef Common::HashMap<Common::String, Common::FSNode, Common::IgnoreCase_Hash, Common::IgnoreCase_EqualTo> FileMap;
/**
- * An (optional) generic fallback detect function which is invoked
- * if the regular MD5 based detection failed to detect anything.
- * NOTE: This is only meant to be used if fallback detection is heavily dependant on engine resources.
+ * An (optional) generic fallback detection function that is invoked
+ * if the regular MD5-based detection failed to detect anything.
+
+ * @note This is only meant to be used if fallback detection heavily depends on engine resources.
*
* To use this, implement the intended fallbackDetectExtern inside the relevant MetaEngineConnect class.
* Then, override the method "fallbackDetect" inside your MetaEngine class.
- * Finally, provide a "hook" to fetch the relevant MetaEngineConnect class and then use the orignal detection
+ * Finally, provide a "hook" to fetch the relevant MetaEngineConnect class and then use the original detection
* method.
*
- * An example for the way this is used can be found in the Wintermute Engine.
+ * An example of how this is implemented can be found in the Wintermute Engine.
*/
virtual ADDetectedGame fallbackDetectExtern(uint md5Bytes, const FileMap &allFiles, const Common::FSList &fslist) const {
return ADDetectedGame();
@@ -386,9 +484,10 @@ public:
/**
* Get the properties (size and MD5) of this file.
- * Based on MetaEngine::getFileProperties.
+ *
+ * Based on @ref MetaEngine::getFileProperties.
*/
bool getFilePropertiesExtern(uint md5Bytes, const FileMap &allFiles, const ADGameDescription &game, const Common::String fname, FileProperties &fileProps) const;
};
-
+/** @} */
#endif
diff --git a/engines/engine.h b/engines/engine.h
index 4dc63c1de6..e250e3082d 100644
--- a/engines/engine.h
+++ b/engines/engine.h
@@ -52,42 +52,74 @@ class Dialog;
}
/**
- * Initializes graphics and shows error message.
+ * @defgroup engines_engine Engine
+ * @ingroup engines
+ *
+ * @brief API for managing various functions of the engine.
+ *
+ * @{
+ */
+
+/**
+ * Initialize graphics and show an error message.
*/
void GUIErrorMessage(const Common::U32String &msg, const char *url = nullptr);
-void GUIErrorMessage(const Common::String &msg, const char *url = nullptr); // Redirect to GUIErrorMessage with U32Strings
+/**
+ * Initialize graphics and show an error message.
+ */
+void GUIErrorMessage(const Common::String &msg, const char *url = nullptr);
+/**
+ * Initialize graphics and show an error message.
+ */
void GUIErrorMessageWithURL(const Common::U32String &msg, const char *url);
-void GUIErrorMessageWithURL(const Common::String &msg, const char *url); // Redirect to GUIErrorMessageWithURL with U32Strings
+/**
+ * Initialize graphics and show an error message.
+ */
+void GUIErrorMessageWithURL(const Common::String &msg, const char *url);
+/**
+ * Initialize graphics and show an error message.
+ */
void GUIErrorMessageFormat(Common::U32String fmt, ...);
+/**
+ * Initialize graphics and show an error message.
+ */
void GUIErrorMessageFormat(const char *fmt, ...) GCC_PRINTF(1, 2);
-class Engine;
+class Engine;
/**
-* Manages pausing by Engine::pauseEngine handing out tokens that
-* each represent one requested level of pause.
+* Class for managing pausing by Engine::pauseEngine that hands out pause tokens.
+*
+* Each token represents one requested level of pause.
*/
class PauseToken {
public:
PauseToken();
+ /**
+ * Construct a pause token.
+ */
PauseToken(const PauseToken &);
#if __cplusplus >= 201103L
PauseToken(PauseToken &&);
#endif
~PauseToken();
-
+ /**
+ * Assign the pause token.
+ */
void operator=(const PauseToken &);
#if __cplusplus >= 201103L
void operator=(PauseToken &&);
#endif
- /** Manually releases the PauseToken. Only allowed if the token
- * currently represents a pause request.
+ /**
+ * Manually release the PauseToken.
+ *
+ * Only allowed if the token currently represents a pause request.
*/
void clear();
/**
- * Returns true if the PauseToken represents a pause level,
+ * Return true if the PauseToken represents a pause level,
* false if it is empty.
*/
bool isActive() const { return _engine != nullptr; }
@@ -96,31 +128,58 @@ private:
PauseToken(Engine *);
Engine *_engine;
-
+ /**
+ * @see Engine
+ */
friend class Engine;
};
class Engine {
public:
+ /**
+ * The OSystem instance used by the engine.
+ */
OSystem *_system;
+ /**
+ * The Mixer instance used by the engine.
+ */
Audio::Mixer *_mixer;
protected:
+ /**
+ * The TimerManager instance used by the engine.
+ */
Common::TimerManager *_timer;
+ /**
+ * The EventManager instance used by the engine.
+ */
Common::EventManager *_eventMan;
+ /**
+ * The SaveFileMAnager used by the engine.
+ */
Common::SaveFileManager *_saveFileMan;
+ /**
+ * The Dialog instance used by the engine.
+ */
GUI::Dialog *_mainMenuDialog;
+ /**
+ * Run a GUI dialog.
+ */
virtual int runDialog(GUI::Dialog &dialog);
- const Common::String _targetName; // target name for saves
+ /**
+ * Target name for saves.
+ */
+ const Common::String _targetName;
private:
/**
- * The pause level, 0 means 'running', a positive value indicates
- * how often the engine has been paused (and hence how often it has
- * to be un-paused before it resumes running). This makes it possible
- * to nest code which pauses the engine.
+ * The pause level.
+ *
+ * 0 means 'running'. A positive value indicates how often the engine
+ * has been paused and thus how many times it must be unpaused before
+ * it resumes running. This makes it possible to nest the code that pauses the engine.
*/
int _pauseLevel;
@@ -130,80 +189,91 @@ private:
uint32 _pauseStartTime;
/**
- * The time when the engine was started. This value is used to calculate
- * the current play time of the game running.
+ * The time when the engine was started.
+ *
+ * This value is used to calculate the current play time of the game running.
*/
int32 _engineStartTime;
/**
- * Autosave interval
+ * Autosave interval.
*/
const int _autosaveInterval;
/**
- * The last time an autosave was done
+ * The last time an autosave was done.
*/
int _lastAutosaveTime;
/**
- * Save slot selected via global main menu.
- * This slot will be loaded after main menu execution (not from inside
+ * Save slot selected via the global main menu.
+ *
+ * This slot will be loaded after the main menu execution (not from inside
* the menu loop, to avoid bugs like #2822778).
*/
int _saveSlotToLoad;
/**
- * Optional debugger for the engine
+ * Optional debugger for the engine.
*/
GUI::Debugger *_debugger;
public:
/**
- * A feature in this context means an ability of the engine which can be
- * either available or not.
+ * Engine features.
+ *
+ * A feature in this context means an ability of the engine
+ * that can be either available or not.
* @see Engine::hasFeature()
*/
enum EngineFeature {
/**
- * Enables the subtitle speed and toggle items in the Options section
+ * Enable the subtitle speed and toggle items in the Options section
* of the global main menu.
*/
kSupportsSubtitleOptions,
/**
- * 'Return to launcher' feature is supported, i.e., EVENT_RETURN_TO_LAUNCHER is handled
- * either directly, or indirectly (that is, the engine calls and honors
+ * The 'Return to launcher' feature is supported.
+ *
+ * This means that EVENT_RETURN_TO_LAUNCHER is handled
+ * either directly, or indirectly (the engine calls and honors
* the result of the Engine::shouldQuit() method appropriately).
*/
kSupportsReturnToLauncher,
/**
- * Loading savestates during runtime is supported, that is, this engine
- * implements loadGameState() and canLoadGameStateCurrently().
+ * Loading save states during runtime is supported.
+ *
+ * This means that the engine implements loadGameState() and canLoadGameStateCurrently().
* If this feature is supported, then the corresponding MetaEngine *must*
* support the kSupportsListSaves feature.
*/
kSupportsLoadingDuringRuntime,
/**
- * Loading savestates during runtime is supported, that is, this engine
- * implements saveGameState() and canSaveGameStateCurrently().
+ * Loading save states during runtime is supported.
+ *
+ * This means that the engine implements saveGameState() and canSaveGameStateCurrently().
* If this feature is supported, then the corresponding MetaEngine *must*
* support the kSupportsListSaves feature.
*/
kSupportsSavingDuringRuntime,
/**
- * Changing the game settings during runtime is supported. This enables
- * showing the engine options tab in the config dialog accessed through
- * the Global Main Menu.
+ * Changing the game settings during runtime is supported.
+ *
+ * This enables showing the Engine Options tab in the config dialog
+ * accessed through the global main menu.
*/
kSupportsChangingOptionsDuringRuntime,
/**
- * Arbitrary resolutions are supported, that is, this engine allows
- * the backend to override the resolution passed to OSystem::setupScreen.
+ * Arbitrary resolutions are supported.
+ *
+ * This means that the engine allows the backend to override the resolution
+ * passed to OSystem::setupScreen.
* The engine will need to read the actual resolution used by the
* backend using OSystem::getWidth and OSystem::getHeight.
*/
@@ -215,16 +285,22 @@ public:
/** @name Overloadable methods
*
* All Engine subclasses should consider overloading some or all of the following methods.
+ * @{
*/
- //@{
+ /**
+ * Create an instance of the engine.
+ */
Engine(OSystem *syst);
+ /**
+ * Destroy the engine instance.
+ */
virtual ~Engine();
/**
- * Init SearchMan according to the game path.
+ * Initialize SearchMan according to the game path.
*
- * By default it adds the directory in non-flat mode with a depth of 4 as
+ * By default, this adds the directory in non-flat mode with a depth of 4 as
* priority 0 to SearchMan.
*
* @param gamePath The base directory of the game data.
@@ -232,13 +308,14 @@ public:
virtual void initializePath(const Common::FSNode &gamePath);
/**
- * Init the engine and start its main loop.
- * @return returns kNoError on success, else an error code.
+ * Initialize the engine and start its main loop.
+ *
+ * @return kNoError on success, otherwise an error code.
*/
virtual Common::Error run() = 0;
/**
- * Prepare an error string, which is printed by the error() function.
+ * Prepare an error string that is printed by the error() function.
*/
virtual void errorString(const char *buf_input, char *buf_output, int buf_output_size);
@@ -248,8 +325,10 @@ public:
virtual GUI::Debugger *getDebugger() { return _debugger; }
/**
- * Sets the engine's debugger. Once set, the Engine class is responsible for managing
- * the debugger, and freeing it on exit
+ * Set the engine's debugger.
+ *
+ * Once set, the Engine class is responsible for managing
+ * the debugger, and freeing it on exit.
*/
void setDebugger(GUI::Debugger *debugger) {
assert(!_debugger);
@@ -258,6 +337,7 @@ public:
/**
* Return the engine's debugger instance, or create one if none is present.
+ *
* Used by error() to invoke the debugger when a severe error is reported.
*/
GUI::Debugger *getOrCreateDebugger();
@@ -268,15 +348,17 @@ public:
virtual bool hasFeature(EngineFeature f) const { return false; }
/**
- * Notify the engine that the sound settings in the config manager may have
- * changed and that it hence should adjust any internal volume etc. values
+ * Notify the engine that the sound settings in the config manager might have
+ * changed and that it should adjust any internal volume (and other) values
* accordingly.
+ *
* The default implementation sets the volume levels of all mixer sound
* types according to the config entries of the active domain.
* When overwriting, call the default implementation first, then adjust the
* volumes further (if required).
*
* @note When setting volume levels, respect the "mute" config entry.
+ *
* @note The volume for the plain sound type is reset to the maximum
* volume. If the engine can associate its own value for this
* type, it needs to overwrite this member and set it accordingly.
@@ -285,19 +367,19 @@ public:
virtual void syncSoundSettings();
/**
- * Notify the engine that the settings editable from the game tab in the
- * in-game options dialog may have changed and that they need to be applied
+ * Notify the engine that the settings editable from the Game tab in the
+ * in-game options dialog might have changed and that they need to be applied
* if necessary.
*/
virtual void applyGameSettings() {}
/**
- * Flip mute all sound option.
+ * Flip mute all sound options.
*/
virtual void flipMute();
/**
- * Generates the savegame filename
+ * Generate the savegame filename.
*/
virtual Common::String getSaveStateName(int slot) const {
return Common::String::format("%s.%03d", _targetName.c_str(), slot);
@@ -305,108 +387,133 @@ public:
/**
* Load a game state.
- * @param slot the slot from which a savestate should be loaded
- * @return returns kNoError on success, else an error code.
+ *
+ * @param slot The slot from which a save state should be loaded.
+ *
+ * @return kNoError on success, otherwise an error code.
*/
virtual Common::Error loadGameState(int slot);
/**
* Load a game state.
- * @param stream the stream to load the savestate from
- * @return returns kNoError on success, else an error code.
+ *
+ * @param stream The stream to load the save state from.
+ *
+ * @return kNoError on success, otherwise an error code.
*/
virtual Common::Error loadGameStream(Common::SeekableReadStream *stream);
/**
- * Sets the game slot for a savegame to be loaded after global
- * main menu execution. This is to avoid loading a savegame from
+ * Set the game slot for a savegame to be loaded after the global
+ * main menu execution.
+ *
+ * This is to avoid loading a savegame from
* inside the menu loop which causes bugs like #2822778.
*
- * @param slot the slot from which a savestate should be loaded.
+ * @param slot The slot from which a save state should be loaded.
*/
void setGameToLoadSlot(int slot);
/**
- * Indicates whether a game state can be loaded.
+ * Indicate whether a game state can be loaded.
*/
virtual bool canLoadGameStateCurrently();
/**
* Save a game state.
- * @param slot the slot into which the savestate should be stored
- * @param desc a description for the savestate, entered by the user
- * @param isAutosave Expected to be true if an autosave is being created
- * @return returns kNoError on success, else an error code.
+ *
+ * @param slot The slot into which the save state should be stored.
+ * @param desc Description for the save state, entered by the user.
+ * @param isAutosave Expected to be true if an autosave is being created.
+ *
+ * @return kNoError on success, otherwise an error code.
*/
virtual Common::Error saveGameState(int slot, const Common::String &desc, bool isAutosave = false);
/**
* Save a game state.
- * @param stream The write stream to save the savegame data to
- * @param isAutosave Expected to be true if an autosave is being created
- * @return returns kNoError on success, else an error code.
+ *
+ * @param stream The write stream to save the savegame data to.
+ * @param isAutosave Expected to be true if an autosave is being created.
+ *
+ * @return kNoError on success, otherwise an error code.
*/
virtual Common::Error saveGameStream(Common::WriteStream *stream, bool isAutosave = false);
/**
- * Indicates whether a game state can be saved.
+ * Indicate whether a game state can be saved.
*/
virtual bool canSaveGameStateCurrently();
/**
- * Shows the ScummVM save dialog, allowing users to save their game
+ * Show the ScummVM save dialog, allowing users to save their game.
*/
bool saveGameDialog();
/**
- * Shows the ScummVM Restore dialog, allowing users to load a game
+ * Show the ScummVM Restore dialog, allowing users to load a game.
*/
bool loadGameDialog();
protected:
/**
- * Actual implementation of pauseEngine by subclasses. See there
- * for details.
+ * Actual implementation of pauseEngine by subclasses.
+ *
+ * @see Engine::pauseEngine
*/
virtual void pauseEngineIntern(bool pause);
- //@}
+ /** @} */
public:
/**
- * Request the engine to quit. Sends a EVENT_QUIT event to the Event
- * Manager.
+ * Request the engine to quit.
+ *
+ * Sends an EVENT_QUIT event to the Event Manager.
*/
static void quitGame();
/**
- * Return whether the ENGINE should quit respectively should return to the
- * launcher.
+ * Return whether the engine should quit.
+ *
+ * This can mean either quitting ScummVM altogether, or returning to the launcher.
*/
static bool shouldQuit();
+ /**
+ * Return the MetaEngineDetection instance used by this engine.
+ */
static MetaEngineDetection &getMetaEngineDetection();
+
+ /**
+ * Return the MetaEngine instance used by this engine.
+ */
static MetaEngine &getMetaEngine();
/**
- * Pause the engine. This should stop any audio playback
- * and other stuff. Called right before the system runs a global dialog
- * (like a global pause, main menu, options or 'confirm exit' dialog).
+ * Pause the engine.
+ *
+ * This should stop any audio playback and other operations.
+ * Called right before the system runs a global dialog
+ * (like a global pause, main menu, options, or 'confirm exit' dialog).
*
- * Returns a PauseToken. Multiple pause tokens may exist. The engine will
+ * Returns a PauseToken. Multiple pause tokens can exist. The engine will
* be resumed when all associated pause tokens reach the end of their lives.
*/
PauseToken pauseEngine();
private:
- /** Resume the engine. This should resume any audio playback and other stuff.
- *
- * Only PauseToken is allowed to call this member function. Use the PauseToken
- * that you got from pauseEngine to resume the engine.
- */
+ /** Resume the engine.
+ *
+ * This should resume any audio playback and other operations.
+ * Only PauseToken is allowed to call this member function. Use the PauseToken
+ * that you got from pauseEngine to resume the engine.
+ */
void resumeEngine();
-
+ /**
+ * @see Engine::PauseToken
+ */
friend class PauseToken;
public:
@@ -417,22 +524,21 @@ public:
bool isPaused() const { return _pauseLevel != 0; }
/**
- * Run the Global Main Menu Dialog
+ * Run the global main menu dialog.
*/
void openMainMenuDialog();
/**
* Display a warning to the user that the game is not fully supported.
*
- * @return true if the user chose to start anyway, false otherwise
+ * @return True if the user chooses to start anyway, false otherwise.
*/
static bool warnUserAboutUnsupportedGame();
/**
* Display an error message to the user that the game is not supported.
*
- * @param extraMsg This will be appended to the default message.
- *
+ * @param extraMsg An extra message that will be appended to the default message.
*/
static void errorUnsupportedGame(Common::String extraMsg);
@@ -446,48 +552,67 @@ public:
/**
* Set the game time counter to the specified time.
*
- * This can be used to set the play time counter after loading a savegame
- * for example. Another use case is in case the engine wants to exclude
- * time from the counter the user spent in original engine dialogs.
+ * This can be used to set the play time counter after loading a savegame,
+ * for example. Another use case is when the engine wants to exclude from
+ * the counter the time that the user spent in original engine dialogs.
*
* @param time Play time to set up in ms.
*/
void setTotalPlayTime(uint32 time = 0);
+ /**
+ * Return the TimerManager instance used by this engine.
+ */
inline Common::TimerManager *getTimerManager() { return _timer; }
+ /**
+ * Return the EventManager instance used by this engine.
+ */
inline Common::EventManager *getEventManager() { return _eventMan; }
+ /**
+ * Return the SaveFileManager instance used by this engine.
+ */
inline Common::SaveFileManager *getSaveFileManager() { return _saveFileMan; }
public:
- /** On some systems, check if the game appears to be run from CD. */
+ /** On some systems, check whether the game appears to be run from CD. */
void checkCD();
/**
- * Checks for whether it's time to do an autosave, and if so, does it.
+ * Check whether it is time to autosave, and if so, do it.
*/
void handleAutoSave();
/**
- * Does an autosave immediately if autosaves are turned on
+ * Autosave immediately if autosaves are enabled.
*/
void saveAutosaveIfEnabled();
/**
- * Indicates whether an autosave can currently be saved.
+ * Indicate whether an autosave can currently be done.
*/
virtual bool canSaveAutosaveCurrently() {
return canSaveGameStateCurrently();
}
/**
- * Returns the slot that should be used for autosaves
- * @note This should match the meta engine getAutosaveSlot() method
+ * Return the slot that should be used for autosaves.
+ *
+ * @note This should match the meta engine getAutosaveSlot() method.
*/
virtual int getAutosaveSlot() const {
return 0;
}
-
+
+ /**
+ * Check whether it is time to autosave based on the
+ * provided @p lastSaveTime.
+ *
+ * This function is now deprecated as autosaves are handled directly by
+ * the Engine class and derived classes do not need to worry about it other than
+ * to implement canSaveAutosaveCurrently() and getAutosaveSlot()
+ * if the default implementations are not sufficient.
+ */
bool shouldPerformAutoSave(int lastSaveTime) {
// TODO: Remove deprecated method once all engines are refactored
// to no longer do autosaves directly themselves
@@ -495,12 +620,17 @@ public:
}
};
-// Chained games
+
+/** @name Chained games
+*
+* @{
+*/
/**
- * Singleton class which manages chained games. A chained game is one that
- * starts automatically, optionally loading a saved game, instead of returning
- * to the launcher.
+ * Singleton class which manages chained games.
+ *
+ * A chained game is one that starts automatically, optionally loading
+ * a saved game, instead of returning to the launcher.
*/
class ChainedGamesManager : public Common::Singleton<ChainedGamesManager> {
private:
@@ -513,15 +643,18 @@ private:
public:
ChainedGamesManager();
+ /** Clear the chained games manager of any games. */
void clear();
+ /** Load a game into a slot in the chained games manager. */
void push(const Common::String target, const int slot = -1);
+ /** Pop the last game loaded into the chained games manager. */
bool pop(Common::String &target, int &slot);
};
/** Convenience shortcut for accessing the chained games manager. */
#define ChainedGamesMan ChainedGamesManager::instance()
-
-// FIXME: HACK for MidiEmu & error()
+/** @} */
+/** Current workaround for MidiEmu & error(). */ //FIXME
extern Engine *g_engine;
-
+/** @} */
#endif
diff --git a/engines/game.h b/engines/game.h
index 17ff2cc76c..6bf9f04285 100644
--- a/engines/game.h
+++ b/engines/game.h
@@ -31,6 +31,15 @@
#include "common/language.h"
#include "common/platform.h"
+/**
+ * @defgroup engines_game Games
+ * @ingroup engines
+ *
+ * @brief API for managing games by engines.
+ *
+ * @{
+ */
+
/**
* A simple structure used to map gameids (like "monkey", "sword1", ...) to
* nice human readable and descriptive game titles (like "The Secret of Monkey Island").
@@ -253,5 +262,5 @@ private:
*/
Common::U32String generateUnknownGameReport(const DetectedGames &detectedGames, bool translate, bool fullPath, uint32 wordwrapAt = 0);
Common::U32String generateUnknownGameReport(const DetectedGame &detectedGame, bool translate, bool fullPath, uint32 wordwrapAt = 0);
-
+/** @} */
#endif
diff --git a/engines/metaengine.h b/engines/metaengine.h
index f669c13771..a32210b695 100644
--- a/engines/metaengine.h
+++ b/engines/metaengine.h
@@ -54,33 +54,51 @@ class GuiObject;
class OptionsContainerWidget;
}
+/**
+ * @defgroup engines_metaengine Meta engine
+ * @ingroup engines
+ *
+ * @brief API for managing various functions of the meta engine.
+ *
+ * @{
+ */
+
/**
* Per-game extra GUI options structure.
* Currently, this can only be used for options with checkboxes.
*/
struct ExtraGuiOption {
- const char *label; // option label, e.g. "Fullscreen mode"
- const char *tooltip; // option tooltip (when the mouse hovers above it)
- const char *configOption; // confMan key, e.g. "fullscreen"
- bool defaultState; // the detault state of the checkbox (checked or not)
+ const char *label; /*!< Option label, e.g. "Fullscreen mode". */
+ const char *tooltip; /*!< Option tooltip shown when the mouse cursor hovers over it. */
+ const char *configOption; /*!< confMan key, e.g. "fullscreen". */
+ bool defaultState; /*!< Default state of the checkbox (checked or not). */
};
+/**
+ * Array of ExtraGuiOption structures.
+ */
typedef Common::Array<ExtraGuiOption> ExtraGuiOptions;
+/**
+ * @todo Doc required
+ */
enum { kSavegameFilePattern = -99 };
#define EXTENDED_SAVE_VERSION 4
+/**
+ * Structure describing a savegame file.
+ */
struct ExtendedSavegameHeader {
- char id[6];
- uint8 version;
- Common::String saveName;
- Common::String description;
- uint32 date;
- uint16 time;
- uint32 playtime;
- Graphics::Surface *thumbnail;
- bool isAutosave;
+ char id[6]; /*!< ID of the savegame file. */
+ uint8 version; /*!< Version of the savegame header. */
+ Common::String saveName; /*!< Name of the savegame. */
+ Common::String description; /*!< Description of the savegame, as entered by the user. */
+ uint32 date; /*!< Date of the savegame. */
+ uint16 time; /*!< Time of the savegame. */
+ uint32 playtime; /*!< Total play time until this savegame. */
+ Graphics::Surface *thumbnail; /*!< Screen content shown as a thumbnail for this savegame. */
+ bool isAutosave; /*!< Whether this savegame is an autosave. */
ExtendedSavegameHeader() {
memset(id, 0, 6);
@@ -94,94 +112,99 @@ struct ExtendedSavegameHeader {
};
/**
- * A meta engine static is essentially a factory for Engine instances with the
+ * A meta engine factory for Engine instances with the
* added ability of listing and detecting supported games.
+ *
* Every engine "plugin" provides a hook to get an instance of a MetaEngineDetection
- * subclass for that "engine plugin". E.g. SCUMM povides ScummMetaEngineDetection.
+ * subclass for that "engine plugin". For example, SCUMM provides ScummMetaEngineDetection.
* This is then in turn used by the frontend code to detect games,
- * and other useful functionality. To instantiate actual Engine objects,
- * See the class MetaEngine below.
+ * and other useful functionality.
+ *
+ * To instantiate actual Engine objects, see the class @ref MetaEngine.
*/
class MetaEngineDetection : public PluginObject {
public:
virtual ~MetaEngineDetection() {}
- /** Get the engine ID */
+ /** Get the engine ID. */
virtual const char *getEngineId() const = 0;
- /** Returns some copyright information about the original engine. */
+ /** Return some copyright information about the original engine. */
virtual const char *getOriginalCopyright() const = 0;
- /** Returns a list of games supported by this engine. */
+ /** Return a list of games supported by this engine. */
virtual PlainGameList getSupportedGames() const = 0;
/** Query the engine for a PlainGameDescriptor for the specified gameid, if any. */
virtual PlainGameDescriptor findGame(const char *gameId) const = 0;
/**
- * Runs the engine's game detector on the given list of files, and returns a
- * (possibly empty) list of games supported by the engine which it was able
- * to detect amongst the given files.
+ * Run the engine's game detector on the given list of files, and return a
+ * (possibly empty) list of games supported by the engine that were
+ * found among the given files.
*/
virtual DetectedGames detectGames(const Common::FSList &fslist) const = 0;
/**
* Return a list of extra GUI options for the specified target.
+ *
* If no target is specified, all of the available custom GUI options are
- * Returned for the plugin (used to set default values).
+ * returned for the plugin (used to set default values).
*
* Currently, this only supports options with checkboxes.
*
* The default implementation returns an empty list.
*
- * @param target name of a config manager target
- * @return a list of extra GUI options for an engine plugin and
- * target
+ * @param target Name of a config manager target.
+ *
+ * @return A list of extra GUI options for an engine plugin and target.
*/
virtual const ExtraGuiOptions getExtraGuiOptions(const Common::String &target) const {
return ExtraGuiOptions();
}
/**
- * Register the default values for the settings the engine uses into the
+ * Register the default values for the settings that the engine uses into the
* configuration manager.
*
- * @param target name of a config manager target
+ * @param target Name of a config manager target.
*/
virtual void registerDefaultSettings(const Common::String &target) const;
/**
* Return a GUI widget container for configuring the specified target options.
*
- * The returned widget is shown in the Engine tab in the edit game dialog.
- * Engines can build custom options dialogs, but by default a simple widget
+ * The returned widget is shown in the Engine tab in the Edit Game dialog.
+ * Engines can build custom option dialogs, but by default a simple widget
* allowing to configure the extra GUI options is used.
*
- * Engines that don't want to have an Engine tab in the edit game dialog
+ * Engines that are not supposed to have an Engine tab in the Edit Game dialog
* can return nullptr.
*
- * @param boss the widget / dialog the returned widget is a child of
- * @param name the name the returned widget must use
- * @param target name of a config manager target
+ * @param boss The widget or dialog that the returned widget is a child of.
+ * @param name The name that the returned widget must use.
+ * @param target Name of a config manager target.
*/
virtual GUI::OptionsContainerWidget *buildEngineOptionsWidgetStatic(GUI::GuiObject *boss, const Common::String &name, const Common::String &target) const;
};
/**
* A MetaEngine is another factory for Engine instances, and is very
- * similiar to meta engines. This class, however, composes of bridged functionalities
- * that can be used to connect an actual Engine with a MetaEngine.
- * Every engine "plugin" provides a hook to get an instance of MetaEngine subclass
- * for that "engine plugin.". E.g. SCUMM provides a ScummMetaEngine.
+ * similar to meta engines.
+ *
+ * This class, however, is made of of bridged functionalities that can be used to connect
+ * an actual Engine with a MetaEngine. Every engine "plugin" provides a hook to get an instance
+ * of the MetaEngine subclass for that "engine plugin.". For example, SCUMM provides a ScummMetaEngine.
* This is then in turn used for things like instantiating engine objects, listing savefiles,
* querying save metadata, etc.
- * Since engine plugins can be used a external runtime libraries, these can live and build inside
+ *
+ * Since engine plugins can use external runtime libraries, these can live and build inside
* the engine, while a MetaEngine will always build into the executable to be able to detect code.
*/
class MetaEngine : public PluginObject {
private:
/**
- * Converts the current screen contents to a thumbnail, and saves it
+ * Convert the current screen contents to a thumbnail and save it.
*/
static void saveScreenThumbnail(Common::OutSaveFile *saveFile);
public:
@@ -189,23 +212,28 @@ public:
/**
* Name of the engine plugin.
- * Classes inheriting a MetaEngineConnect must provide a engineID here,
+ *
+ * Classes inheriting a MetaEngineConnect must provide an engineID here,
* which can then be used to match an Engine with MetaEngine.
- * E.g. ScummMetaEngine inherits MetaEngine & provides a engineID of "Scumm".
- * ScummMetaEngineConnect inherits MetaEngineConnect & provides the name "Scumm".
- * This way, we can easily match a Engine with a MetaEngine.
+ *
+ * For example, ScummMetaEngine inherits MetaEngine and provides a engineID of "Scumm".
+ * ScummMetaEngineConnect inherits MetaEngineConnect and provides the name "Scumm".
+ * This way, an Engine can be easily matched with a MetaEngine.
*/
virtual const char *getName() const = 0;
/**
- * Tries to instantiate an engine instance based on the settings of
- * the currently active ConfMan target. That is, the MetaEngine should
- * query the ConfMan singleton for the target, gameid, path etc. data.
- *
- * @param syst Pointer to the global OSystem object
- * @param engine Pointer to a pointer which the MetaEngine sets to
- * the newly create Engine, or 0 in case of an error
- * @return a Common::Error describing the error which occurred, or kNoError
+ * Instantiate an engine instance based on the settings of
+ * the currently active ConfMan target.
+ *
+ * The MetaEngine queries the ConfMan singleton for data like the target,
+ * gameid, path etc.
+ *
+ * @param syst Pointer to the global OSystem object.
+ * @param engine Pointer to a pointer that the MetaEngine sets to
+ * the newly created Engine, or 0 in case of an error.
+ *
+ * @return A Common::Error describing the error that occurred, or kNoError.
*/
virtual Common::Error createInstance(OSystem *syst, Engine **engine) const = 0;
@@ -215,49 +243,51 @@ public:
* The returned list is guaranteed to be sorted by slot numbers. That
* means smaller slot numbers are always stored before bigger slot numbers.
*
- * The caller has to ensure that this (Meta)Engine is responsible
- * for the specified target (by using findGame on it respectively
- * on the associated gameid from the relevant ConfMan entry, if present).
+ * The caller must ensure that this (Meta)Engine is responsible
+ * for the specified target. This is done by using findGame on it respectively
+ * on the associated gameid from the relevant ConfMan entry, if present.
*
* The default implementation returns an empty list.
*
* @note MetaEngines must indicate that this function has been implemented
* via the kSupportsListSaves feature flag.
*
- * @param target name of a config manager target
- * @return a list of save state descriptors
+ * @param target Name of a config manager target.
+ *
+ * @return A list of save state descriptors.
*/
virtual SaveStateList listSaves(const char *target) const;
/**
* Return a list of all save states associated with the given target.
*
- * This is a wrapper around the basic listSaves virtual method, but which
- * has some extra logic for autosave handling
+ * This is a wrapper around the basic listSaves virtual method, but it has
+ * some extra logic for autosave handling.
*
- * @param target name of a config manager target
- * @param saveMode If true, getting the list for a save dialog
- * @return a list of save state descriptors
+ * @param target Name of a config manager target.
+ * @param saveMode If true, get the list for a save dialog.
+ * @return A list of save state descriptors.
*/
SaveStateList listSaves(const char *target, bool saveMode) const;
/**
- * Returns the slot number being used for autosaves.
- * @note This should match the engine getAutosaveSlot() method
+ * Return the slot number that is used for autosaves.
+ *
+ * @note This should match the engine getAutosaveSlot() method.
*/
virtual int getAutosaveSlot() const {
return 0;
}
/**
- * Return the maximum save slot that the engine supports.
+ * Return the maximum number of save slots that the engine supports.
*
* @note MetaEngines must indicate that this function has been implemented
* via the kSupportsListSaves feature flag.
*
* The default implementation limits the save slots to zero (0).
*
- * @return maximum save slot number supported
+ * @return Maximum save slot number supported.
*/
virtual int getMaximumSaveSlot() const {
// For games using the new save format, assume 99 slots by default
@@ -267,42 +297,42 @@ public:
/**
* Remove the specified save state.
*
- * For most engines this just amounts to calling _saveFileMan->removeSaveFile().
- * Engines which keep an index file will also update it accordingly.
+ * For most engines, this just means calling _saveFileMan->removeSaveFile().
+ * Engines that keep an index file will also update it accordingly.
*
* @note MetaEngines must indicate that this function has been implemented
* via the kSupportsDeleteSave feature flag.
*
- * @param target name of a config manager target
- * @param slot slot number of the save state to be removed
+ * @param target Name of a config manager target.
+ * @param slot Slot number of the save state to be removed.
*/
virtual void removeSaveState(const char *target, int slot) const;
/**
- * Returns meta infos from the specified save state.
+ * Return meta information from the specified save state.
*
- * Depending on the MetaEngineFeatures set this can include
- * thumbnails, save date / time, play time.
+ * Depending on the MetaEngineFeatures set, this can include
+ * thumbnails, save date and time, play time.
*
- * @param target name of a config manager target
- * @param slot slot number of the save state
+ * @param target Name of a config manager target.
+ * @param slot Slot number of the save state.
*/
virtual SaveStateDescriptor querySaveMetaInfos(const char *target, int slot) const;
/**
- * Returns name of the save file for given slot and optional target,
- * or a pattern for matching filenames against
+ * Return the name of the save file for the given slot and optional target,
+ * or a pattern for matching filenames against.
*
- * @param saveGameIdx index of the save, or kSavegameFilePattern
- * for returning a filename pattern
- * @param target game target. If omitted, then the engine id is used
+ * @param saveGameIdx Index of the save, or kSavegameFilePattern
+ * for returning a filename pattern.
+ * @param target Game target. If omitted, then the engine ID is used.
*/
virtual Common::String getSavegameFile(int saveGameIdx, const char *target = nullptr) const;
/**
- * Returns pattern for save files.
+ * Return the pattern for save files.
*
- * @param target game target. If omitted, then the engine id is used
+ * @param target Game target. If omitted, then the engine ID is used.
*/
Common::String getSavegameFilePattern(const char *target = nullptr) const {
return getSavegameFile(kSavegameFilePattern, target);
@@ -313,6 +343,9 @@ public:
*/
virtual Common::Array<Common::Keymap *> initKeymaps(const char *target) const;
+ /**
+ * Return the extra GUI options used by the target.
+ */
virtual const ExtraGuiOptions getExtraGuiOptions(const Common::String &target) const {
return ExtraGuiOptions();
}
@@ -320,118 +353,128 @@ public:
/**
* Return a GUI widget container for configuring the specified target options.
*
- * Engines can build custom options dialogs from here, but by default a simple widget
+ * Engines can build custom option dialogs from here, but by default a simple widget
* allowing to configure the extra GUI options is used.
*
- * A engine that builds the "Engines" tab in "Edit Game" uses a MetaEngine.
- * A engine that specifies a custom dialog, when a game is running, uses a MetaEngineConnect.
+ * The engine that builds the Engines tab in the Edit Game dialog uses a MetaEngine.
+ * The engine that specifies a custom dialog when a game is running uses a MetaEngineConnect.
*
- * Engines that don't want to have an Engine tab in the edit game dialog
+ * Engines are not supposed to have an Engine tab in the Edit Game dialog
* can return nullptr.
*
- * @param boss the widget / dialog the returned widget is a child of
- * @param name the name the returned widget must use
- * @param target name of a config manager target
+ * @param boss The widget or dialog that the returned widget is a child of.
+ * @param name The name that the returned widget must use.
+ * @param target Name of a config manager target.
*/
virtual GUI::OptionsContainerWidget *buildEngineOptionsWidgetDynamic(GUI::GuiObject *boss, const Common::String &name, const Common::String &target) const;
- /** @name MetaEngineFeature flags */
- //@{
-
/**
- * A feature in this context means an ability of the engine which can be
+ * MetaEngine feature flags.
+ *
+ * A feature in this context means an ability of the engine that can be
* either available or not.
*/
enum MetaEngineFeature {
/**
- * Listing all Save States for a given target is supported, i.e.,
- * the listSaves() and getMaximumSaveSlot methods are implemented.
+ * List all save states for a given target that is supported.
+ *
+ * For the target to be supported, the listSaves() and
+ * getMaximumSaveSlot methods must be implemented.
* Used for --list-saves support, as well as the GMM load dialog.
*/
kSupportsListSaves,
/**
- * Loading from the Launcher / command line (-x)
+ * Load from the launcher or command line (-x).
*/
kSupportsLoadingDuringStartup,
/**
- * Deleting Saves from the Launcher (i.e. implements the
- * removeSaveState() method)
+ * Delete saves from the launcher.
+ *
+ * This means that the engine implements the removeSaveState() method.
*/
kSupportsDeleteSave,
/**
- * Features meta infos for savestates (i.e. implements the
- * querySaveMetaInfos method properly).
+ * Feature meta information for save states.
+ *
+ * This means that the engine implements the querySaveMetaInfos method properly.
*
- * Engines implementing meta infos always have to provide
+ * Engines implementing meta information always must provide
* the following entries in the save state descriptor queried
* by querySaveMetaInfos:
- * - 'is_deletable', which indicates if a given save is
- * safe for deletion
- * - 'is_write_protected', which indicates if a given save
- * can be overwritten by the user.
- * (note: of course you do not have to
- * set this, since it defaults to 'false')
+ * - is_deletable - indicates whether a given save is
+ * safe for deletion
+ * - is_write_protected - indicates whether a given save
+ * can be overwritten by the user.
+ * You do not need to set this, default value is 'false'.
*/
kSavesSupportMetaInfo,
/**
- * Features a thumbnail in savegames (i.e. includes a thumbnail
- * in savestates returned via querySaveMetaInfo).
- * This flag may only be set when 'kSavesSupportMetaInfo' is set.
+ * Feature a thumbnail in savegames.
+ *
+ * This means that the engine includes a thumbnail in save states
+ * returned via querySaveMetaInfo.
+ * This flag can only be set when kSavesSupportMetaInfo is set.
*/
kSavesSupportThumbnail,
/**
- * Features 'save_date' and 'save_time' entries in the
- * savestate returned by querySaveMetaInfo. Those values
- * indicate the date/time the savegame was created.
- * This flag may only be set when 'kSavesSupportMetaInfo' is set.
+ * Feature @c save_date and @c save_time entries in the
+ * save state returned by querySaveMetaInfo.
+ *
+ * These values indicate the date and time when the savegame was created.
+ * This flag can only be set when kSavesSupportMetaInfo is set.
*/
kSavesSupportCreationDate,
/**
- * Features 'play_time' entry in the savestate returned by
- * querySaveMetaInfo. It indicates how long the user played
- * the game till the save.
- * This flag may only be set when 'kSavesSupportMetaInfo' is set.
+ * Feature @c play_time entry in the save state returned by
+ * querySaveMetaInfo.
+ *
+ * This indicates how long the user played the game until the save.
+ * This flag can only be set when kSavesSupportMetaInfo is set.
*/
kSavesSupportPlayTime,
/**
- * Feature is available if engine's saves could be detected
- * with "<target>.###" pattern and "###" corresponds to slot
- * number.
+ * This feature is available if the engine's saves can be detected
+ * with:
+ * @code
+ * <target>.###
+ * @endcode
+ * where ### corresponds to slot number.
*
- * If that's not true or engine is using some unusual way
+ * If that is not true, or if the engine uses some unusual way
* of detecting saves and slot numbers, this should be
- * unavailable. In that case Save/Load dialog for engine's
+ * unavailable. In that case Save/Load dialog for the engine's
* games is locked during cloud saves sync.
*/
kSimpleSavesNames,
/**
- * Uses default implementation of save header and thumbnail
+ * Use the default implementation of save header and thumbnail
* appended to the save.
+ *
* This flag requires the following flags to be set:
- * kSavesSupportMetaInfo, kSavesSupportThumbnail, kSavesSupportCreationDate,
- * kSavesSupportPlayTime
+ * - kSavesSupportMetaInfo
+ * - kSavesSupportThumbnail
+ * - kSavesSupportCreationDate
+ * - kSavesSupportPlayTime
*/
kSavesUseExtendedFormat
};
- //@}
-
/**
* Return a list of achievement descriptions for the specified target.
*
* The default implementation returns an empty list.
*
- * @param target name of a config manager target
- * @return a list of achievement descriptions for an engine plugin
- * and target
+ * @param target Name of a config manager target.
+ *
+ * @return A list of achievement descriptions for an engine plugin and target.
*/
virtual const Common::AchievementsInfo getAchievementsInfo(const Common::String &target) const {
return Common::AchievementsInfo();
@@ -439,74 +482,89 @@ public:
/**
* Determine whether the engine supports the specified MetaEngine feature.
- * Used by e.g. the launcher to determine whether to enable the "Load" button.
+ *
+ * Used by e.g. the launcher to determine whether to enable the Load button.
*/
virtual bool hasFeature(MetaEngineFeature f) const;
+ /**
+ * Write the extended savegame header to the given savegame file.
+ */
static void appendExtendedSave(Common::OutSaveFile *saveFile, uint32 playtime, Common::String desc, bool isAutosave);
+ /**
+ * Parse the extended savegame header to retrieve the SaveStateDescriptor information.
+ */
static void parseSavegameHeader(ExtendedSavegameHeader *header, SaveStateDescriptor *desc);
+ /**
+ * Populate the given extended savegame header with dummy values.
+ *
+ * This is used when failing to read the header from a savegame file.
+ */
static void fillDummyHeader(ExtendedSavegameHeader *header);
+ /**
+ * Read the extended savegame header from the given savegame file.
+ */
static WARN_UNUSED_RESULT bool readSavegameHeader(Common::InSaveFile *in, ExtendedSavegameHeader *header, bool skipThumbnail = true);
};
/**
- * Singleton class which manages all Engine plugins.
+ * Singleton class that manages all engine plugins.
*/
class EngineManager : public Common::Singleton<EngineManager> {
public:
/**
- * Given a list of FSNodes in a given directory, detect a set of games contained within
+ * Given a list of FSNodes in a given directory, detect a set of games contained within.
*
* Returns an empty list if none are found.
*/
DetectionResults detectGames(const Common::FSList &fslist) const;
- /** Find a plugin by its engine ID */
+ /** Find a plugin by its engine ID. */
const Plugin *findPlugin(const Common::String &engineId) const;
/**
* Get the list of all plugins for the type specified.
+ *
* By default, it will get METAENGINES, for now.
- * If usage of actual engines never occurs, we can skip
- * the default arguments, and always have it return
- * PLUGIN_TYPE_ENGINE_DETECTION.
+ * If usage of actual engines never occurs, the default arguments can be skipped,
+ * and always have it return PLUGIN_TYPE_ENGINE_DETECTION.
*/
const PluginList &getPlugins(const PluginType fetchPluginType = PLUGIN_TYPE_ENGINE_DETECTION) const;
- /** Find a target */
+ /** Find a target. */
QualifiedGameDescriptor findTarget(const Common::String &target, const Plugin **plugin = NULL) const;
/**
- * List games matching the specified criteria
+ * List games matching the specified criteria.
*
- * If the engine id is not specified, this scans all the plugins,
- * loading them from disk if necessary. This is a slow operation on
+ * If the engine ID is not specified, this scans all the plugins,
+ * loading them from the disk if necessary. This is a slow operation on
* some platforms and should not be used for the happy path.
*/
QualifiedGameList findGamesMatching(const Common::String &engineId, const Common::String &gameId) const;
/**
- * Create a target from the supplied game descriptor
+ * Create a target from the supplied game descriptor.
*
- * Returns the created target name.
+ * @return The created target name.
*/
Common::String createTargetForGame(const DetectedGame &game);
- /** Upgrade a target to the current configuration format */
+ /** Upgrade a target to the current configuration format. */
void upgradeTargetIfNecessary(const Common::String &target) const;
private:
- /** Find a game across all loaded plugins */
+ /** Find a game across all loaded plugins. */
QualifiedGameList findGameInLoadedPlugins(const Common::String &gameId) const;
- /** Find a loaded plugin with the given engine ID */
+ /** Find a loaded plugin with the given engine ID. */
const Plugin *findLoadedPlugin(const Common::String &engineId) const;
- /** Use heuristics to complete a target lacking an engine ID */
+ /** Use heuristics to complete a target lacking an engine ID. */
void upgradeTargetForEngineId(const Common::String &target) const;
};
/** Convenience shortcut for accessing the engine manager. */
#define EngineMan EngineManager::instance()
-
+/** @} */
#endif
diff --git a/engines/obsolete.h b/engines/obsolete.h
index c1bbad6a8c..22b9cd012b 100644
--- a/engines/obsolete.h
+++ b/engines/obsolete.h
@@ -27,6 +27,15 @@
namespace Engines {
+/**
+ * @defgroup engines_obsolete Obsolete game IDs
+ * @ingroup engines
+ *
+ * @brief API for managing obsolete game IDs and updating the config file.
+ *
+ * @{
+ */
+
/**
* Structure for autoupgrading targets using an obsolete gameid
* to the correct new gameid.
@@ -71,7 +80,7 @@ PlainGameDescriptor findGameID(
const PlainGameDescriptor *gameids,
const ObsoleteGameID *obsoleteList = 0);
-
+/** @} */
} // End of namespace Engines
#endif
diff --git a/engines/savestate.h b/engines/savestate.h
index f43d190443..59532040e5 100644
--- a/engines/savestate.h
+++ b/engines/savestate.h
@@ -32,6 +32,15 @@ namespace Graphics {
struct Surface;
}
+/**
+ * @defgroup engines_savestate Save states
+ * @ingroup engines
+ *
+ * @brief API for managing save states.
+ *
+ * @{
+ */
+
/**
* Object describing a save state.
*
@@ -273,5 +282,5 @@ struct SaveStateDescriptorSlotComparator {
return x.getSaveSlot() < y.getSaveSlot();
}
};
-
+/** @} */
#endif
diff --git a/engines/util.h b/engines/util.h
index d70ceb1c02..1eb28f5b6f 100644
--- a/engines/util.h
+++ b/engines/util.h
@@ -30,36 +30,54 @@
#include "graphics/mode.h"
/**
- * Setup the backend's graphics mode.
+ * @defgroup engines_util Util
+ * @ingroup engines
+ *
+ * @brief Various utility functions related to engines.
+ *
+ * @{
+ */
+
+/**
+ * Set up the graphics mode of the backend.
*/
void initCommonGFX();
/**
- * Sends a list of graphics modes to the backend so it can make a decision
+ * Send a list of graphics modes to the backend so it can make a decision
* about the best way to set up the display hardware.
*
- * Engines that switch between different virtual screen sizes during a game
+ * Engines that switch between different virtual screen sizes during the game
* should call this function prior to any call to initGraphics. Engines that use
* only a single screen size do not need to call this function.
*/
void initGraphicsModes(const Graphics::ModeList &modes);
/**
- * Sets up the backend's screen size and graphics mode.
+ * Set up the screen size and graphics mode of the backend.
*
- * Shows an various warnings on certain backend graphics
+ * Shows various warnings on certain backend graphics
* transaction failures (aspect switch, fullscreen switch, etc.).
*
- * Errors out when backend is not able to switch to the specified
+ * Errors are returned when the backend is not able to switch to the specified
* mode.
*
- * Defaults to 256 color paletted mode if no graphics format is provided.
- * Uses the backend's preferred format if graphics format pointer is NULL.
+ * Defaults to 256 color palette mode if no graphics format is provided.
+ * Uses the preferred format of the backend if graphics format pointer is NULL.
* Finds the best compatible format if a list of graphics formats is provided.
*/
void initGraphics(int width, int height);
+/**
+ * @overload
+ */
void initGraphics(int width, int height, const Graphics::PixelFormat *format);
+/**
+ * @overload
+ */
void initGraphics(int width, int height, const Common::List<Graphics::PixelFormat> &formatList);
+/**
+ * @overload
+ */
void initGraphics3d(int width, int height);
-
+/** @} */
#endif
More information about the Scummvm-git-logs
mailing list