thirdparty/scummvm
2
0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

DOXYGEN: Doxygen improvements part 3

Browse source 
Editing doxygen comments in files:

- debug.h
- dialogs.h
- encoding.h
- endian.h
- error.h
- events.h
- fft.h
- file.h
- frac.h
- fs.h
- gui_options.h
- hash-ptr.h
- hashmap.h
- huffman.h
- ini-file.h

Plus some small changes in the config file.
This commit is contained in:
Bartosz Gentkowski 2020-10-08 00:04:21 +02:00 • committed by Thierry Crozat
parent 61ee3a1ec5
commit 24e3b6096e
16 changed files with 493 additions and 401 deletions
Download patch file Download diff file Expand all files Collapse all files

21
common/debug.h
View file

@ -80,8 +80,11 @@ void debugN(int level, const char *s, ...) GCC_PRINTF(2, 3);
* if the specified special debug level is active.
* As a rule of thumb, the more important the message, the lower the level.
* Automatically appends a newline.
*
* @see enableDebugChannel
*
* @param level Debug level that must be active for the message to be printed.
* @param debugChannels Bitfield of channels to check against.
* @param s Message to print.
*/
void debugC(int level, uint32 debugChannels, const char *s, ...) GCC_PRINTF(3, 4);
@ -91,8 +94,12 @@ void debugC(int level, uint32 debugChannels, const char *s, ...) GCC_PRINTF(3, 4
* if the specified special debug level is active.
* As a rule of thumb, the more important the message, the lower the level.
* Does not append a newline automatically.
*
* @see enableDebugChannel
*
* @param level Debug level that must be active for the message to be printed.
* @param debugChannels Bitfield of channels to check against.
* @param s Message to print.
*
*/
void debugCN(int level, uint32 debugChannels, const char *s, ...) GCC_PRINTF(3, 4);
@ -100,8 +107,10 @@ void debugCN(int level, uint32 debugChannels, const char *s, ...) GCC_PRINTF(3,
* Print a debug message to the text console (stdout), but only if
* the specified special debug level is active.
* Automatically appends a newline.
*
* @see enableDebugChannel
*
* @param debugChannels Bitfield of channels to check against.
* @param s Message to print.
*/
void debugC(uint32 debugChannels, const char *s, ...) GCC_PRINTF(2, 3);
@ -109,8 +118,10 @@ void debugC(uint32 debugChannels, const char *s, ...) GCC_PRINTF(2, 3);
* Print a debug message to the text console (stdout), but only if
* the specified special debug level is active.
* Does not append a newline automatically.
*
* @see enableDebugChannel
*
* @param debugChannels Bitfield of channels to check against.
* @param s Message to print.
*/
void debugCN(uint32 debugChannels, const char *s, ...) GCC_PRINTF(2, 3);
@ -125,7 +136,7 @@ bool debugLevelSet(int level);
* Check whether the debug level and channel are active.
*
* @param level Debug level to check against. If set to -1, only channel check is active.
* @param debugChannels Debug channel to check against.
* @param debugChannels Bitfield of channels to check against.
* @see enableDebugChannel
*/
bool debugChannelSet(int level, uint32 debugChannels);

18
common/dialogs.h
View file

@ -48,24 +48,24 @@ namespace Common {
class DialogManager {
public:
/**
* Values representing the user response to a dialog
* Values representing the user response to a dialog.
*/
enum DialogResult {
kDialogError = -1, ///< Dialog couldn't be displayed
kDialogCancel = 0, ///< User cancelled the dialog (Cancel/No/Close buttons)
kDialogOk = 1 ///< User confirmed the dialog (OK/Yes buttons)
kDialogError = -1, ///< Dialog could not be displayed.
kDialogCancel = 0, ///< User cancelled the dialog (Cancel/No/Close buttons).
kDialogOk = 1 ///< User confirmed the dialog (OK/Yes buttons).
};
DialogManager() : _wasFullscreen(false) {}
virtual ~DialogManager() {}
/**
* Displays a dialog for selecting a file or folder in the filesystem.
* Display a dialog for selecting a file or folder in the file system.
*
* @param title The dialog title
* @param choice The path selected by the user
* @param isDirBrowser Restrict selection to directories
* @return The dialog result
* @param title Dialog title.
* @param choice Path selected by the user.
* @param isDirBrowser Restrict selection to directories.
* @return The dialog result.
*/
virtual DialogResult showFileBrowser(const Common::U32String &title, FSNode &choice, bool isDirBrowser = false) { return kDialogError; }

143
common/encoding.h
View file

@ -40,47 +40,48 @@ namespace Common {
*/
/**
* A class, that allows conversion between different text encoding,
* the encodings available depend on the current backend and if the
* A class that allows conversion between different text encoding.
* The encodings available depend on the current backend and whether
* ScummVM is compiled with or without iconv.
*/
class Encoding {
public:
/**
* Constructs everything needed for the conversion between 2 encodings
* Construct everything needed for the conversion between two encodings
* and saves the values for future use.
*
* @param to Name of the encoding the strings will be converted to
* @param from Name of the encoding the strings will be converted from
* @param to Name of the encoding the strings will be converted to.
* @param from Name of the encoding the strings will be converted from.
*/
Encoding(const String &to, const String &from);
~Encoding() {};
/**
* Converts string between encodings. The resulting string is ended by
* a character with value 0 (C-like ending for 1 byte per character
* encodings, 2 zero bytes for UTF-16, 4 zero bytes for UTF-32)
* Convert a string between encodings.
*
* The result has to be freed after use.
* The resulting string is ended by a character with value 0
* (C-like ending for 1 byte per character encodings, 2 zero bytes for UTF-16,
* 4 zero bytes for UTF-32).
* The result must be freed after usage using @c free(), not @c delete[].
*
* @param string String that should be converted.
* @param string String to be converted.
* @param length Length of the string to convert in bytes.
*
* @return Converted string (must be freed) or nullptr if the conversion failed
* @return Converted string (must be freed) or nullptr if the conversion failed.
*/
char *convert(const char *string, size_t length);
/**
* Static version of the method above.
* Converts string between encodings. The resulting string is ended by
* a character with value 0 (C-like ending for 1 byte per character
* encodings, 2 zero bytes for UTF-16, 4 zero bytes for UTF-32)
* Convert a string between encodings.
*
* The result has to be freed after use.
* This is a static version of the method above.
* The resulting string is ended by a character with value 0
* (C-like ending for 1 byte per character encodings, 2 zero bytes for UTF-16,
* 4 zero bytes for UTF-32). The result must be freed after usage.
*
* @param to Name of the encoding the strings will be converted to
* @param from Name of the encoding the strings will be converted from
* @param string String that should be converted.
* @param to Name of the encoding the strings will be converted to.
* @param from Name of the encoding the strings will be converted from.
* @param string String to be converted.
* @param length Length of the string to convert in bytes.
*
* @return Converted string (must be freed) or nullptr if the conversion failed
@ -96,42 +97,46 @@ class Encoding {
}
/**
* @return The encoding, which is currently being converted from
* @return The encoding that is currently being converted from.
*/
String getFrom() {return _from;};
/**
* @param from The encoding, to convert from
* @param from The encoding to convert from.
*/
void setFrom(const String &from) {_from = from;};
/**
* @return The encoding, which is currently being converted to
* @return The encoding that is currently being converted to.
*/
String getTo() {return _to;};
/**
* @param to The encoding, to convert to
* @param to The encoding to convert to.
*/
void setTo(const String &to) {_to = to;};
/**
* Switches the endianity of a string.
* Switch the endianness of a string.
*
* @param string Array containing the characters of a string.
* @param length Length of the string in bytes
* @param string Array containing the characters of a string.
* @param length Length of the string in bytes.
* @param bitCount Number of bits used for each character.
*
* @return Array of characters with the opposite endianity
* @return Array of characters with the opposite endianness.
*/
static char *switchEndian(const char *string, int length, int bitCount);
/**
* Computes length (in bytes) of a string in a given encoding.
* The string must be zero ended. Similar to strlen
* (could be used instead of strlen).
* Compute the length (in bytes) of a string in a given encoding.
*
* @param string String, which size should be computed.
* The string must be zero ended. Similar to @c strlen.
*
* @note This function must be used instead of @c strlen for some encodings
* (such as UTF-16 and UTF-32) because @c strlen does not support
* multi-byte encodings, with some exceptions (such as UTF-8).
*
* @param string The string whose size to compute.
* @param encoding Encoding of the string.
*
* @return Size of the string in bytes.
@ -139,91 +144,93 @@ class Encoding {
static size_t stringLength(const char *string, const String &encoding);
private:
/** The encoding, which is currently being converted to */
/** The encoding that is currently being converted to. */
String _to;
/** The encoding, which is currently being converted from */
/** The encoding that is currently being converted from. */
String _from;
/**
* Takes care of transliteration and calls conversion
* Take care of transliteration and call conversion.
*
* The result has to be freed after use.
* The result must be freed after usage.
*
* @param to Name of the encoding the strings will be converted to
* @param from Name of the encoding the strings will be converted from
* @param string String that should be converted.
* @param to Name of the encoding the strings will be converted to.
* @param from Name of the encoding the strings will be converted from.
* @param string The string to convert.
* @param length Length of the string to convert in bytes.
*
* @return Converted string (must be freed) or nullptr if the conversion failed
* @return Converted string (must be freed) or nullptr if the conversion failed.
*/
static char *convertWithTransliteration(const String &to, const String &from, const char *string, size_t length);
/**
* Calls as many conversion functions as possible or until the conversion
* succeeds. It first tries to use iconv, then it tries to use platform
* specific functions and after that it tries to use TransMan mapping.
* Call as many conversion functions as possible, or until the conversion
* succeeds.
*
* The result has to be freed after use.
* It first tries to use iconv, then it tries to use platform
* specific functions, and after that, it tries to use TransMan mapping.
*
* @param to Name of the encoding the strings will be converted to
* @param from Name of the encoding the strings will be converted from
* @param string String that should be converted.
* The result must be freed after usage.
*
* @param to Name of the encoding the strings will be converted to.
* @param from Name of the encoding the strings will be converted from.
* @param string The string to convert.
* @param length Length of the string to convert in bytes.
*
* @return Converted string (must be freed) or nullptr if the conversion failed
* @return Converted string (must be freed) or nullptr if the conversion failed.
*/
static char *conversion(const String &to, const String &from, const char *string, size_t length);
/**
* Tries to convert the string using iconv.
* Attempt to convert the string using iconv.
*
* The result has to be freed after use.
* The result must be freed after usage.
*
* @param to Name of the encoding the strings will be converted to
* @param from Name of the encoding the strings will be converted from
* @param string String that should be converted.
* @param to Name of the encoding the strings will be converted to.
* @param from Name of the encoding the strings will be converted from.
* @param string The string to convert.
* @param length Length of the string to convert in bytes.
*
* @return Converted string (must be freed) or nullptr if the conversion failed
* @return Converted string (must be freed) or nullptr if the conversion failed.
*/
static char *convertIconv(const char *to, const char *from, const char *string, size_t length);
/**
* Uses conversion table to convert the string to unicode and from that
* to the final encoding. Important encodings, that aren't supported by
* Use a conversion table to convert the string to unicode, and from that,
* to the final encoding. Important encodings, that are not supported by
* all backends should go here.
*
* The result has to be freed after use.
* The result must be freed after usage.
*
* @param to Name of the encoding the strings will be converted to
* @param from Name of the encoding the strings will be converted from
* @param string String that should be converted.
* @param to Name of the encoding the strings will be converted to.
* @param from Name of the encoding the strings will be converted from.
* @param string The string to be converted.
* @param length Length of the string to convert in bytes.
*
* @return Converted string (must be freed) or nullptr if the conversion failed
* @return Converted string (must be freed) or nullptr if the conversion failed.
*/
static char *convertConversionTable(const char *to, const char *from, const char *string, size_t length);
/**
* Transliterates cyrillic string in iso-8859-5 encoding and returns
* it's ASCII (latin) form.
* Transliterate a Cyrillic string in ISO-8859-5 encoding and return
* its ASCII (Latin) form.
*
* The result has to be freed after use.
* The result must be freed after usage.
*
* @param string String that should be converted
* @param string The string to convert.
*
* @return Transliterated string in ASCII (must be freed) or nullptr on fail.
*/
static char *transliterateCyrillic(const char *string);
/**
* Transliterates cyrillic in UTF-32 string.
* Transliterate a Cyrillic string into a UTF-32 string.
*
* The result has to be freed after use.
* The result must be freed after usage.
*
* @param string String that should be converted
* @param length Length of the string in bytes
* @param string The string to convert.
* @param length Length of the string in bytes.
*
* @return Transliterated string in UTF-32 (must be freed) or nullptr on fail.
*/

72
common/endian.h
View file

@ -30,22 +30,21 @@
* @defgroup common_endian Endian conversions
* @ingroup common
*
* @brief Endian conversion and byteswap conversion functions and macros.
* @brief Functions and macros for endian conversions and byteswap conversions.
*
* @details
* SWAP_BYTES_??(a) - inverse byte order
* SWAP_CONSTANT_??(a) - inverse byte order, implemented as macro.
* Use with compiletime-constants only, the result will be a compiletime-constant aswell.
* Unlike most other functions these can be used for eg. switch-case labels
*
* READ_UINT??(a) - read native value from pointer a
* READ_??_UINT??(a) - read LE/BE value from pointer a and convert it to native
* WRITE_??_UINT??(a, v) - write native value v to pointer a with LE/BE encoding
* TO_??_??(a) - convert native value v to LE/BE
* FROM_??_??(a) - convert LE/BE value v to native
* CONSTANT_??_??(a) - convert LE/BE value v to native, implemented as macro.
* Use with compiletime-constants only, the result will be a compiletime-constant aswell.
* Unlike most other functions these can be used for eg. switch-case labels
* - SWAP_BYTES_??(a) - Reverse byte order
* - SWAP_CONSTANT_??(a) - Reverse byte order, implemented as a macro.
* Use with compile-time constants only, the result will be a compile-time constant as well.
* Unlike most other functions, these can be used for e.g. switch-case labels.
* - READ_UINT??(a) - Read native value from pointer @p a.
* - READ_??_UINT??(a) - Read LE/BE value from pointer @p a and convert it to native.
* - WRITE_??_UINT??(a, v) - Write a native value @p v to pointer @p a with LE/BE encoding.
* - TO_??_??(a) - Convert native value @p v to LE/BE.
* - FROM_??_??(a) - Convert LE/BE value @p v to native.
* - CONSTANT_??_??(a) - Convert LE/BE value @p v to native, implemented as a macro.
* Use with compile-time constants only, the result will be a compile-time constant as well.
* Unlike most other functions these, can be used for e.g. switch-case labels.
*
* @{
*/
@ -55,6 +54,10 @@
# error No endianness defined
#endif
/**
* Swap the bytes in a 64-bit word in order to convert LE encoded data to BE
* and vice versa. Use with compile-time constants only.
*/
#define SWAP_CONSTANT_64(a) \
((uint64)((((a) >> 56) & 0x000000FF) | \
(((a) >> 40) & 0x0000FF00) | \
@ -65,12 +68,20 @@
(((a) & 0x0000FF00) << 40) | \
(((a) & 0x000000FF) << 56) ))
/**
* Swap the bytes in a 32-bit word in order to convert LE encoded data to BE
* and vice versa. Use with compile-time constants only.
*/
#define SWAP_CONSTANT_32(a) \
((uint32)((((a) >> 24) & 0x00FF) | \
(((a) >> 8) & 0xFF00) | \
(((a) & 0xFF00) << 8) | \
(((a) & 0x00FF) << 24) ))
/**
* Swap the bytes in a 16-bit word in order to convert LE encoded data to BE
* and vice versa. Use with compile-time constants only.
*/
#define SWAP_CONSTANT_16(a) \
((uint16)((((a) >> 8) & 0x00FF) | \
(((a) << 8) & 0xFF00) ))
@ -78,7 +89,7 @@
/**
* Swap the bytes in a 16 bit word in order to convert LE encoded data to BE
* Swap the bytes in a 16-bit word in order to convert LE encoded data to BE
* and vice versa.
*/
@ -106,7 +117,7 @@
/**
* Swap the bytes in a 32 bit word in order to convert LE encoded data to BE
* Swap the bytes in a 32-bit word in order to convert LE encoded data to BE
* and vice versa.
*/
@ -155,7 +166,7 @@
#endif
/**
* Swap the bytes in a 64 bit word in order to convert LE encoded data to BE
* Swap the bytes in a 64-bit word in order to convert LE encoded data to BE
* and vice versa.
*/
@ -211,8 +222,8 @@
* A wrapper macro used around four character constants, like 'DATA', to
* ensure portability. Typical usage: MKTAG('D','A','T','A').
*
* Why is this necessary? The C/C++ standard does not define the endianess to
* be used for character constants. Hence if one uses multi-byte character
* This is required because the C/C++ standard does not define the endianess to
* be used for character constants. Hence, if one uses multi-byte character
* constants, a potential portability problem opens up.
*/
#define MKTAG(a0,a1,a2,a3) ((uint32)((a3) | ((a2) << 8) | ((a1) << 16) | ((a0) << 24)))
@ -223,8 +234,11 @@
*/
#define MKTAG16(a0,a1) ((uint16)((a1) | ((a0) << 8)))
// Functions for reading/writing native integers.
// They also transparently handle the need for alignment.
/** @name Functions for reading and writing native integers
* @brief Functions for reading and writing native integer values.
* They also transparently handle the need for alignment.
* @{
*/
// Test for GCC >= 4.0. These implementations will automatically use
// CPU-specific instructions for unaligned data when they are available (eg.
@ -372,11 +386,14 @@
}
# endif
/** @} */
#endif
// Map Funtions for reading/writing BE/LE integers depending on native endianess
/** @name Map functions for reading/writing BE/LE integers depending on native endianess
* @{
*/
#if defined(SCUMM_LITTLE_ENDIAN)
#define READ_LE_UINT16(a) READ_UINT16(a)
@ -411,8 +428,13 @@
#define TO_BE_64(a) SWAP_BYTES_64(a)
#define CONSTANT_LE_64(a) ((uint64)(a))
#define CONSTANT_BE_64(a) SWAP_CONSTANT_64(a)
/** @} */
// if the unaligned load and the byteswap take alot instructions its better to directly read and invert
/** @name Functions for directly reading/writing and inverting
* @brief Use these in case the unaligned load and byteswap take
* a lot of instructions.
* @{
*/
# if defined(SCUMM_NEED_ALIGNMENT) && !defined(__mips__)
inline uint16 READ_BE_UINT16(const void *ptr) {
@ -637,7 +659,7 @@ inline int32 READ_BE_INT32(const void *ptr) {
inline void WRITE_BE_INT32(void *ptr, int32 value) {
WRITE_BE_UINT32(ptr, static_cast<uint32>(value));
}
/** @} */
/** @} */
#endif

52
common/error.h
View file

@ -37,43 +37,43 @@ namespace Common {
*/
/**
* Error codes which may be reported by plugins under various circumstances.
* Error codes that may be reported by plugins under various circumstances.
*
* @note Error names should follow the pattern k-NOUN/ACTION-CONDITION-Error.
* So kPathInvalidError would be correct, but these would not be:
* So kPathInvalidError is correct, but the following are not:
* kInvalidPath, kPathInvalid, kPathIsInvalid, kInvalidPathError.
*
* @todo Adjust all error codes to comply with these conventions.
*/
enum ErrorCode {
kNoError = 0, ///< No error occurred
kNoGameDataFoundError, ///< Engine initialization: No game data was found in the specified location
kUnsupportedGameidError, ///< Engine initialization: Gameid not supported by this (Meta)Engine
kUnsupportedColorMode, ///< Engine initialization: Engine does not support backend's color mode
kAudioDeviceInitFailed, ///< Engine initialization: Audio device initialization failed
kNoError = 0, ///< No error occurred.
kNoGameDataFoundError, ///< Engine initialization: No game data was found in the specified location.
kUnsupportedGameidError, ///< Engine initialization: Game ID not supported by this (Meta)Engine.
kUnsupportedColorMode, ///< Engine initialization: Engine does not support backend's color mode.
kAudioDeviceInitFailed, ///< Engine initialization: Audio device initialization failed.
kReadPermissionDenied, ///< Unable to read data due to missing read permission
kWritePermissionDenied, ///< Unable to write data due to missing write permission
kReadPermissionDenied, ///< Unable to read data due to missing read permission.
kWritePermissionDenied, ///< Unable to write data due to missing write permission.
kPathDoesNotExist, ///< The specified path does not exist
kPathNotDirectory, ///< The specified path does not point to a directory
kPathNotFile, ///< The specified path does not point to a file
kPathDoesNotExist, ///< The specified path does not exist.
kPathNotDirectory, ///< The specified path does not point to a directory.
kPathNotFile, ///< The specified path does not point to a file.
kCreatingFileFailed, ///< Failed creating a (savestate) file
kReadingFailed, ///< Failed to read a file (permission denied?)
kWritingFailed, ///< Failure to write data -- disk full?
kCreatingFileFailed, ///< Failed creating a (savestate) file.
kReadingFailed, ///< Failed to read a file (permission denied?).
kWritingFailed, ///< Failure to write data - disk full?
// The following are used by --list-saves
/** Failed to find a MetaEnginePlugin. This should never happen, because all MetaEngines must always
* be built into the executable, regardless if the engine plugins are present or not.
*/
kMetaEnginePluginNotFound,
// Failed to find a MetaEnginePlugin. This should never happen, because all MetaEngines must always
// be built into the executable, regardless if the engine plugins are present or not.
kMetaEnginePluginNotFound, ///< See comment above
kEnginePluginNotFound, ///< Failed to find an Engine plugin to handle target.
kEnginePluginNotSupportSaves, ///< The plugin does not support listing save states.
kEnginePluginNotFound, ///< Failed to find a Engine plugin to handle target
kEnginePluginNotSupportSaves, ///< Failed if plugin does not support listing save states
kUserCanceled, ///< User has canceled the launching of the game.
kUserCanceled, ///< User has canceled the launching of the game
kUnknownError ///< Catch-all error, used if no other error code matches
kUnknownError ///< Catch-all error, used if no other error code matches.
};
/**
@ -84,8 +84,8 @@ enum ErrorCode {
*/
class Error {
protected:
ErrorCode _code;
String _desc;
ErrorCode _code; /*!< Error code. */
String _desc; /*!< Error description. */
public:
/**
* Construct a new Error with the specified error code and the default

145
common/events.h
View file

@ -70,12 +70,13 @@ enum EventType {
EVENT_QUIT = 10,
EVENT_SCREEN_CHANGED = 11,
/** The input devices have changed, input related configuration needs to be re-applied */
/** The input devices have changed, input-related configuration must be reapplied. */
EVENT_INPUT_CHANGED = 35,
/**
* The backend requests the agi engine's predictive dialog to be shown.
* TODO: Fingolfin suggests that it would be of better value to expand
* The backend requests the AGI engine's predictive dialog to be shown.
*
* @todo Fingolfin suggests that it would be of better value to expand
* on this notion by generalizing its use. For example the backend could
* use events to ask for the save game dialog or to pause the engine.
* An associated enumerated type can accomplish this.
@ -107,14 +108,14 @@ enum EventType {
* Additional mouse events, details in Event::mouse.
*
* Note that X1 and X2 are usually back and forward, however
* this can't be guaranteed on all platforms.
* this cannot be guaranteed on all platforms.
*/
EVENT_X1BUTTONDOWN = 30,
EVENT_X1BUTTONUP = 31,
EVENT_X2BUTTONDOWN = 32,
EVENT_X2BUTTONUP = 33,
/** ScummVM has gained or lost focus */
/** ScummVM has gained or lost focus. */
EVENT_FOCUS_GAINED = 36,
EVENT_FOCUS_LOST = 37
};
@ -123,15 +124,15 @@ const int16 JOYAXIS_MIN = -32768;
const int16 JOYAXIS_MAX = 32767;
/**
* Data structure for joystick events
* Data structure for joystick events.
*/
struct JoystickState {
/** The axis for EVENT_JOYAXIS_MOTION events */
/** The axis for EVENT_JOYAXIS_MOTION events. */
byte axis;
/** The new axis position for EVENT_JOYAXIS_MOTION events */
/** The new axis position for EVENT_JOYAXIS_MOTION events. */
int16 position;
/**
* The button index for EVENT_JOYBUTTON_DOWN/UP events
* The button index for EVENT_JOYBUTTON_DOWN/UP events.
*
* Some of the button indices match well-known game controller
* buttons. See JoystickButton.
@ -142,7 +143,7 @@ struct JoystickState {
};
/**
* The list of named buttons available from a joystick
* The list of named buttons available from a joystick.
*/
enum JoystickButton {
JOYSTICK_BUTTON_A,
@ -163,7 +164,7 @@ enum JoystickButton {
};
/**
* The list of named axes available from a joystick
* The list of named axes available from a joystick.
*/
enum JoystickAxis {
JOYSTICK_AXIS_LEFT_STICK_X,
@ -175,7 +176,7 @@ enum JoystickAxis {
};
/**
* The list named buttons available from a mouse
* The list named buttons available from a mouse.
*/
enum MouseButton {
MOUSE_BUTTON_LEFT = 0,
@ -186,7 +187,7 @@ enum MouseButton {
MOUSE_BUTTON_X1 = 5,
MOUSE_BUTTON_X2 = 6
};
/** Used by @ref ArtificialEventSource. */
typedef uint32 CustomEventType;
/**
@ -199,7 +200,7 @@ struct Event {
EventType type;
/**
* True if this is a key down repeat event.
* True if this is a key-down repeat event.
*
* Only valid for EVENT_KEYDOWN events.
*/
@ -214,14 +215,15 @@ struct Event {
/**
* The mouse coordinates, in virtual screen coordinates. Only valid
* for mouse events.
* Virtual screen coordinates means: the coordinate system of the
* 'Virtual screen coordinates' refers to the coordinate system of the
* screen area as defined by the most recent call to initSize().
*/
Point mouse;
/** Refers to an event generated by @ref ArtificialEventSource. */
CustomEventType customType;
/* The path of the file or directory dragged to the ScummVM window */
/** The path of the file or directory dragged to the ScummVM window. */
Common::String path;
/**
@ -240,51 +242,52 @@ struct Event {
};
/**
* Determinates whether an event is a mouse event
* Determine whether an event is a mouse event.
*
* Mouse events have valid mouse coordinates
* Mouse events have valid mouse coordinates.
*/
bool isMouseEvent(const Event &event);
/**
* A source of Events.
*
* An example for this is OSystem, it provides events created by the system
* and or user.
* An example for this is OSystem, which provides events created by the system
* and/or user.
*/
class EventSource {
public:
virtual ~EventSource();
/**
* Queries a event from the source.
* Query an event from the source.
*
* @param event a reference to the event struct, where the event should be stored.
* @return true if an event was polled, false otherwise.
* @param event Reference to the event struct where the event should be stored.
* @retval true If an event was polled, false otherwise.
*/
virtual bool pollEvent(Event &event) = 0;
/**
* Checks whether events from this source are allowed to be mapped.
* Check whether events from this source are allowed to be mapped.
*
* Possible event sources not allowing mapping are: the event recorder/player and/or
* the EventManager, which allows user events to be pushed.
*
* By default we allow mapping for every event source.
* By default, mapping is allowed for every event source.
*/
virtual bool allowMapping() const { return true; }
};
/**
* An artificial event source. This is class is used as an event source, which is
* made up by client specific events.
* An artificial event source. This class is used as an event source, which is
* made up by client-specific events.
*
* Example usage cases for this are the Keymapper or the DefaultEventManager.
* Example use cases for this are the Keymapper or the DefaultEventManager.
*/
class ArtificialEventSource : public EventSource {
protected:
Queue<Event> _artificialEventQueue;
public:
/** Put the specified event into the queue. */
void addEvent(const Event &ev) {
_artificialEventQueue.push(ev);
}
@ -299,44 +302,44 @@ public:
}
/**
* By default an artificial event source prevents its events
* By default, an artificial event source prevents its events
* from being mapped.
*/
virtual bool allowMapping() const { return false; }
};
/**
* Object which catches and processes Events.
* Object that catches and processes Events.
*
* An example for this is the Engine object, it is catching events and processing them.
* An example for this is the Engine object - it catches events and processes them.
*/
class EventObserver {
public:
virtual ~EventObserver();
/**
* Notifies the observer of an incoming event.
* Notify the observer of an incoming event.
*
* An observer is supposed to eat the event, with returning true, when
* An observer is supposed to 'eat' the event, with returning true, when
* it wants to prevent other observers from receiving the event.
* A usage example here is the keymapper:
* If it processes an Event, it should 'eat' it and create a new
* event, which the EventDispatcher will then catch.
*
* @param event the event, which is incoming.
* @return true if the event should not be passed to other observers,
* @param event The event that is incoming.
* @retval true If the event should not be passed to other observers,
* false otherwise.
*/
virtual bool notifyEvent(const Event &event) = 0;
/**
* Notifies the observer of pollEvent() query.
* Notify the observer of pollEvent() query.
*/
virtual void notifyPoll() { }
};
/**
* A event mapper, which will map events to others.
* A event mapper that maps events to others.
*
* An example for this is the Keymapper.
*/
@ -345,20 +348,20 @@ public:
virtual ~EventMapper();
/**
* Map an incoming event to one or more action events
* Map an incoming event to one or more action events.
*/
virtual List<Event> mapEvent(const Event &ev) = 0;
};
/**
* Dispatches events from various sources to various observers.
* Dispatch events from various sources to various observers.
*
* EventDispatcher is using a priority based approach. Observers
* with higher priority will be notified before observers with
* lower priority. Because of the possibility that oberservers
* might 'eat' events, not all observers might be notified.
* EventDispatcher uses a priority-based approach. Observers
* with higher priority are notified before observers with
* lower priority. Note that observers might 'eat' events,
* and thus not all observers might be notified.
*
* Another speciality is the support for a event mapper, which
* Another speciality is the support for an event mapper that
* will catch events and create new events out of them. This
* mapper will be processed before an event is sent to the
* observers.
@ -369,7 +372,7 @@ public:
~EventDispatcher();
/**
* Tries to catch events from the registered event
* Attempt to catch events from the registered event
* sources and dispatch them to the observers.
*
* This dispatches *all* events the sources offer.
@ -383,32 +386,32 @@ public:
void clearEvents();
/**
* Registers an event mapper with the dispatcher.
* Register an event mapper with the dispatcher.
*/
void registerMapper(EventMapper *mapper);
/**
* Registers a new EventSource with the Dispatcher.
* Register a new EventSource with the Dispatcher.
*/
void registerSource(EventSource *source, bool autoFree);
/**
* Unregisters a EventSource.
* Unregister an EventSource.
*
* This takes the "autoFree" flag passed to registerSource into account.
*/
void unregisterSource(EventSource *source);
/**
* Registers a new EventObserver with the Dispatcher.
* Register a new EventObserver with the Dispatcher.
*
* @param listenPolls if set, then all pollEvent() calls are passed to observer
* currently it is used by keyMapper
* @param listenPolls If set, then all pollEvent() calls are passed to the observer.
* Currently, it is used by keyMapper.
*/
void registerObserver(EventObserver *obs, uint priority, bool autoFree, bool listenPolls = false);
/**
* Unregisters a EventObserver.
* Unregister an EventObserver.
*
* This takes the "autoFree" flag passed to registerObserver into account.
*/
@ -444,7 +447,7 @@ class Keymapper;
/**
* The EventManager provides user input events to the client code.
* In addition, it keeps track of the state of various input devices,
* like keys, mouse position and buttons.
* like keys, mouse position, and buttons.
*/
class EventManager : NonCopyable {
public:
@ -458,28 +461,28 @@ public:
/**
* Initialize the event manager.
* @note called after graphics system has been set up
* @note Called after graphics system has been set up.
*/
virtual void init() {}
/**
* Get the next event in the event queue.
* @param event point to an Event struct, which will be filled with the event data.
* @return true if an event was retrieved.
* @param event Point to an Event struct, which will be filled with the event data.
* @retval true If an event was retrieved.
*/
virtual bool pollEvent(Event &event) = 0;
/**
* Pushes a "fake" event into the event queue
* Push a "fake" event into the event queue.
*/
virtual void pushEvent(const Event &event) = 0;
/**
* Purges all unprocessed mouse events already in the event queue.
* Purge all unprocessed mouse events already in the event queue.
*/
virtual void purgeMouseEvents() = 0;
/** Return the current mouse position */
/** Return the current mouse position. */
virtual Point getMousePos() const = 0;
/**
@ -489,17 +492,16 @@ public:
*/
virtual int getButtonState() const = 0;
/** Get a bitmask with the current modifier state */
/** Get a bitmask with the current modifier state. */
virtual int getModifierState() const = 0;
/**
* Should the application terminate? Set to true if we
* received an EVENT_QUIT.
* Whether the application should terminate. Set to true if EVENT_QUIT was received.
*/
virtual int shouldQuit() const = 0;
/**
* Should we return to the launcher?
* Whether to return to the launcher.
*/
virtual int shouldReturnToLauncher() const = 0;
@ -518,30 +520,31 @@ public:
// TODO: Consider removing OSystem::getScreenChangeID and
// replacing it by a generic getScreenChangeID method here
/** Return the @ref Keymapper object. */
virtual Keymapper *getKeymapper() = 0;
/** Return the global @ref Keymap object. */
virtual Keymap *getGlobalKeymap() = 0;
enum {
/**
* Priority of the event manager, for now it's lowest since it eats
* *all* events, we might to change that in the future though.
* Priority of the event manager. For now, it is lowest since it eats
* *all* events. This might be changed in the future though.
*/
kEventManPriority = 0,
/**
* Priority of the event recorder. It has to go after event manager
* in order to record events generated by it
* Priority of the event recorder. It must go after the event manager
* in order to record events generated by it.
*/
kEventRecorderPriority = 1,
/**
* Priority of the remap dialog. It has to go first to capture all
* Priority of the remap dialog. It must go first to capture all
* the events before they are consumed by other observers.
*/
kEventRemapperPriority = 999
};
/**
* Returns the underlying EventDispatcher.
* Return the underlying EventDispatcher.
*/
EventDispatcher *getEventDispatcher() { return &_dispatcher; }
@ -550,7 +553,7 @@ protected:
};
/**
* Wrap an event source so the key down events are repeated while
* Wrap an event source so the key-down events are repeated while
* keys are held down.
*
* Does not take ownership of the wrapped EventSource.

8
common/fft.h
View file

@ -46,10 +46,10 @@ namespace Common {
class CosineTable;
/**
* (Inverse) Fast Fourier Transform
* (Inverse) Fast Fourier Transform.
*
* Used in engines:
* - scumm
* - SCUMM
*/
class FFT {
public:
@ -58,10 +58,10 @@ public:
const uint16 *getRevTab() const;
/** Do the permutation needed BEFORE calling calc(). */
/** Perform the permutation needed BEFORE calling calc(). */
void permute(Complex *z);
/** Do a complex FFT.
/** Perform a complex FFT.
*
* The input data must be permuted before.
* No 1.0/sqrt(n) normalization is done.

72
common/file.h
View file

@ -43,7 +43,7 @@ namespace Common {
class Archive;
/**
* TODO: vital to document this core class properly!!! For both users and implementors
* @todo vital to document this core class properly!!! For both users and implementors
*/
class File : public SeekableReadStream, public NonCopyable {
protected:
@ -58,52 +58,52 @@ public:
virtual ~File();
/**
* Checks if a given file exists in any of the current default paths,
* Check if a given file exists in any of the current default paths,
* as defined by SearchMan.
*
* @param filename the file to check for
* @return true if the file exists, false otherwise
* @param filename The file to check for.
* @return True if the file exists, false otherwise.
*/
static bool exists(const String &filename);
/**
* Try to open the file with the given filename, by searching SearchMan.
* @note Must not be called if this file already is open (i.e. if isOpen returns true).
* Try to open the file with the given file name, by searching SearchMan.
* @note Must not be called if this file is already open (i.e. if isOpen returns true).
*
* @param filename the name of the file to open
* @return true if file was opened successfully, false otherwise
* @param filename Name of the file to open.
* @return True if the file was opened successfully, false otherwise.
*/
virtual bool open(const String &filename);
/**
* Try to open the file with the given filename from within the given archive.
* @note Must not be called if this file already is open (i.e. if isOpen returns true).
* Try to open the file with the given file name from within the given archive.
* @note Must not be called if this file is already open (i.e. if isOpen returns true).
*
* @param filename the name of the file to open
* @param archive the archive in which to search for the file
* @return true if file was opened successfully, false otherwise
* @param filename Name of the file to open.
* @param archive Archive in which to search for the file.
* @return True if the file was opened successfully, false otherwise.
*/
virtual bool open(const String &filename, Archive &archive);
/**
* Try to open the file corresponding to the give node. Will check whether the
* Try to open the file corresponding to the given node. Will check whether the
* node actually refers to an existing file (and not a directory), and handle
* those cases gracefully.
* @note Must not be called if this file already is open (i.e. if isOpen returns true).
*
* @param node the node to consider.
* @return true if file was opened successfully, false otherwise
* @param node The node to consider.
* @return True if the file was opened successfully, false otherwise.
*/
virtual bool open(const FSNode &node);
/**
* Try to 'open' the given stream. That is, we just wrap around it, and if stream
* is a NULL pointer, we gracefully treat this as if opening failed.
* Try to 'open' the given stream. That is, wrap around it, and if the stream
* is a NULL pointer, gracefully treat this as if opening failed.
* @note Must not be called if this file already is open (i.e. if isOpen returns true).
*
* @param stream a pointer to a SeekableReadStream, or 0
* @param name a string describing the 'file' corresponding to stream
* @return true if stream was non-zero, false otherwise
* @param stream Pointer to a SeekableReadStream, or 0.
* @param name String describing the 'file' corresponding to the stream.
* @return True if the stream was non-zero, false otherwise.
*/
virtual bool open(SeekableReadStream *stream, const String &name);
@ -113,39 +113,39 @@ public:
virtual void close();
/**
* Checks if the object opened a file successfully.
* Check if the object opened a file successfully.
*
* @return: true if any file is opened, false otherwise.
* @return True if any file is opened, false otherwise.
*/
bool isOpen() const;
/**
* Returns the filename of the opened file for debugging purposes.
* Return the file name of the opened file for debugging purposes.
*
* @return: the filename
* @return The file name of the opened file.
*/
const char *getName() const { return _name.c_str(); }
bool err() const override; // implement abstract Stream method
void clearErr() override; // implement abstract Stream method
bool eos() const override; // implement abstract SeekableReadStream method
bool err() const override; /*!< Implement abstract Stream method. */
void clearErr() override; /*!< Implement abstract Stream method. */
bool eos() const override; /*!< Implement abstract SeekableReadStream method. */
int32 pos() const override; // implement abstract SeekableReadStream method
int32 size() const override; // implement abstract SeekableReadStream method
bool seek(int32 offs, int whence = SEEK_SET) override; // implement abstract SeekableReadStream method
uint32 read(void *dataPtr, uint32 dataSize) override; // implement abstract SeekableReadStream method
int32 pos() const override; /*!< Implement abstract SeekableReadStream method. */
int32 size() const override; /*!< Implement abstract SeekableReadStream method. */
bool seek(int32 offs, int whence = SEEK_SET) override; /*!< Implement abstract SeekableReadStream method. */
uint32 read(void *dataPtr, uint32 dataSize) override; /*!< Implement abstract SeekableReadStream method. */
};
/**
* TODO: document this class
* @todo Document this class
*
* Some design ideas:
* - automatically drop all files into dumps/ dir? Might not be desired in all cases
*/
class DumpFile : public SeekableWriteStream, public NonCopyable {
protected:
/** File handle to the actual file; 0 if no file is open. */
/** File handle to the actual file. 0 if no file is open. */
WriteStream *_handle;
public:
@ -158,9 +158,9 @@ public:
virtual void close();
/**
* Checks if the object opened a file successfully.
* Check if the object opened a file successfully.
*
* @return: true if any file is opened, false otherwise.
* @return True if any file is opened, false otherwise.
*/
bool isOpen() const;

4
common/frac.h
View file

@ -35,8 +35,8 @@
*/
/**
* The precision of the fractional (fixed point) type we define below.
* Normally you should never have to modify this value.
* The precision of the fractional (fixed-point) type that is defined below.
* Normally, you should never need to modify this value.
*/
enum {
FRAC_BITS = 16,

145
common/fs.h
View file

@ -48,20 +48,20 @@ class SeekableReadStream;
class WriteStream;
/**
* List of multiple file system nodes. E.g. the contents of a given directory.
* This is subclass instead of just a typedef so that we can use forward
* declarations of it in other places.
* List of multiple file system nodes. For example, the contents of a given directory.
* This is a subclass instead of just a typedef so that forward declarations
* of it can be used in other places.
*/
class FSList : public Array<FSNode> {};
/**
* FSNode, short for "File System Node", provides an abstraction for file
* paths, allowing for portable file system browsing. This means for example,
* paths, allowing for portable file system browsing. This means, for example,
* that multiple or single roots have to be supported (compare Unix with a
* single root, Windows with multiple roots C:, D:, ...).
*
* To this end, we abstract away from paths; implementations can be based on
* paths (and it's left to them whether / or \ or : is the path separator :-);
* paths (and it is left to them whether '/', '\', or ':' is the path separator)
* but it is also possible to use inodes or vrefs (MacOS 9) or anything else.
*/
class FSNode : public ArchiveMember {
@ -69,7 +69,7 @@ private:
friend class ::AbstractFSNode;
SharedPtr<AbstractFSNode> _realNode;
/**
* Construct a FSNode from a backend's AbstractFSNode implementation.
* Construct an FSNode from a backend's AbstractFSNode implementation.
*
* @param realNode Pointer to a heap allocated instance. FSNode will take
* ownership of the pointer.
@ -87,7 +87,7 @@ public:
};
/**
* Create a new pathless FSNode. Since there's no path associated
* Create a new pathless FSNode. Since there is no path associated
* with this node, path-related operations (i.e. exists(), isDirectory(),
* getPath()) will always return false or raise an assertion.
*/
@ -97,9 +97,9 @@ public:
* Create a new FSNode referring to the specified path. This is
* the counterpart to the path() method.
*
* If path is empty or equals ".", then a node representing the "current
* If the path is empty or equals ".", then a node representing the "current
* directory" will be created. If that is not possible (since e.g. the
* operating system doesn't support the concept), some other directory is
* operating system does not support the concept), some other directory is
* used (usually the root directory).
*/
explicit FSNode(const String &path);
@ -113,9 +113,9 @@ public:
bool operator<(const FSNode& node) const;
/**
* Indicates whether the object referred by this node exists in the filesystem or not.
* Indicate whether the object referred by this node exists in the file system or not.
*
* @return bool true if the node exists, false otherwise.
* @return True if the node exists, false otherwise.
*/
bool exists() const;
@ -131,10 +131,10 @@ public:
* this should affect what exists/isDirectory/isReadable/isWritable return
* for existing nodes. However, this is not the case for many existing
* FSNode implementations. Either fix those, or document that FSNodes
* can become 'stale'...
* can become 'stale'.
*
* @param name the name of a child of this directory
* @return the node referring to the child with the given name
* @param name Name of a child of this directory.
* @return The node referring to the child with the given name.
*/
FSNode getChild(const String &name) const;
@ -142,40 +142,40 @@ public:
* Return a list of all child nodes of this directory node. If called on a node
* that does not represent a directory, false is returned.
*
* @return true if successful, false otherwise (e.g. when the directory does not exist).
* @return True if successful, false otherwise (e.g. when the directory does not exist).
*/
bool getChildren(FSList &fslist, ListMode mode = kListDirectoriesOnly, bool hidden = true) const;
/**
* Return a human readable string for this node, usable for display (e.g.
* Return a human-readable string for this node, usable for display (e.g.
* in the GUI code). Do *not* rely on it being usable for anything else,
* like constructing paths!
* like constructing paths.
*
* @return the display name
* @return The display name.
*/
virtual String getDisplayName() const;
/**
* Return a string representation of the name of the file. This can be
* used e.g. by detection code that relies on matching the name of a given
* file. But it is *not* suitable for use with fopen / File::open, nor
* file. However, it is *not* suitable for use with fopen / File::open, nor
* should it be archived.
*
* @return the file name
* @return The file name.
*/
virtual String getName() const;
/**
* Return a string representation of the file which is suitable for
* Return a string representation of the file that is suitable for
* archiving (i.e. writing to the config file). This will usually be a
* 'path' (hence the name of the method), but can be anything that meets
* the above criterions. What a 'path' is differs greatly from system to
* system anyway.
* the above criteria. What a 'path' is differs greatly from system to
* system.
*
* @note Do not assume that this string contains (back)slashes or any
* other kind of 'path separators'.
*
* @return the 'path' represented by this filesystem node
* @return The 'path' represented by this file system node.
*/
String getPath() const;
@ -186,7 +186,7 @@ public:
FSNode getParent() const;
/**
* Indicates whether the node refers to a directory or not.
* Indicate whether the node refers to a directory or not.
*
* @todo Currently we assume that a node that is not a directory
* automatically is a file (ignoring things like symlinks or pipes).
@ -197,7 +197,7 @@ public:
bool isDirectory() const;
/**
* Indicates whether the object referred by this node can be read from or not.
* Indicate whether the object referred by this node can be read from or not.
*
* If the node refers to a directory, readability implies being able to read
* and list the directory entries.
@ -205,63 +205,63 @@ public:
* If the node refers to a file, readability implies being able to read the
* contents of the file.
*
* @return true if the object can be read, false otherwise.
* @return True if the object can be read, false otherwise.
*/
bool isReadable() const;
/**
* Indicates whether the object referred by this node can be written to or not.
* Indicate whether the object referred by this node can be written to or not.
*
* If the node refers to a directory, writability implies being able to modify
* the directory entry (i.e. rename the directory, remove it or write files inside of it).
* the directory entry (i.e. rename the directory, remove it, or write files inside of it).
*
* If the node refers to a file, writability implies being able to write data
* to the file.
*
* @return true if the object can be written to, false otherwise.
* @return True if the object can be written to, false otherwise.
*/
bool isWritable() const;
/**
* Creates a SeekableReadStream instance corresponding to the file
* Create a SeekableReadStream instance corresponding to the file
* referred by this node. This assumes that the node actually refers
* to a readable file. If this is not the case, 0 is returned.
*
* @return pointer to the stream object, 0 in case of a failure
* @return Pointer to the stream object, 0 in case of a failure.
*/
virtual SeekableReadStream *createReadStream() const;
/**
* Creates a WriteStream instance corresponding to the file
* Create a WriteStream instance corresponding to the file
* referred by this node. This assumes that the node actually refers
* to a readable file. If this is not the case, 0 is returned.
*
* @return pointer to the stream object, 0 in case of a failure
* @return Pointer to the stream object, 0 in case of a failure.
*/
WriteStream *createWriteStream() const;
/**
* Creates a directory referred by this node. This assumes that this
* node refers to non-existing directory. If this is not the case,
* Create a directory referred by this node. This assumes that this
* node refers to a non-existing directory. If this is not the case,
* false is returned.
*
* @return true if the directory was created, false otherwise.
* @return True if the directory was created, false otherwise.
*/
bool createDirectory() const;
};
/**
* FSDirectory models a directory tree from the filesystem and allows users
* FSDirectory models a directory tree from the file system and allows users
* to access it through the Archive interface. Searching is case-insensitive,
* since the intended goal is supporting retrieval of game data.
* since the intended goal is to support retrieval of game data.
*
* FSDirectory can represent a single directory, or a tree with specified depth,
* depending on the value passed to the 'depth' parameter in the constructors.
* In the default mode, filenames are cached with their relative path,
* In the default mode, file names are cached with their relative path,
* with elements separated by slashes, e.g.:
*
* @code
* c:\my\data\file.ext
*
* @endcode
* would be cached as 'data/file.ext' if FSDirectory was created on 'c:/my' with
* depth > 1. If depth was 1, then the 'data' subdirectory would have been
* ignored, instead.
@ -269,24 +269,27 @@ public:
* underlying file system.
*
* Relative paths can be specified when calling matching functions like createReadStreamForMember(),
* hasFile(), listMatchingMembers() and listMembers(). Please see the function
* specific comments for more information.
* hasFile(), listMatchingMembers(), and listMembers(). See the function-specific
* documentation for more information.
*
* If the 'flat' argument to the constructor is true, files in subdirectories
* are cached without the relative path, so in the example above
* c:\my\data\file.ext would be cached as file.ext.
* are cached without the relative path, so in the following example:
* @code
* c:\my\data\file.ext
* @endcode
* would be cached as 'file.ext'.
*
* When the 'ignoreClashes' argument to the constructor is true, name clashes are
* expected by the engine. It means that files which clash should be identical and
* getSubDirectory shouldn't be used on clashing directories. This flag is useful
* in flat mode when there are directories with same name at different places in the
* tree whose name isn't relevant for the engine code.
* expected by the engine. It means that files that clash should be identical and
* getSubDirectory should not be used on clashing directories. This flag is useful
* in flat mode when there are directories with the same name at different places in the
* tree whose name is not relevant for the engine code.
*
* Client code can customize cache by using the constructors with the 'prefix'
* Client code can customize the cache by using constructors with the 'prefix'
* parameter. In this case, the prefix is prepended to each entry in the cache,
* and effectively treated as a 'virtual' parent subdirectory. FSDirectory adds
* a trailing slash to prefix if needed. Following on with the previous example
* and using 'your' as prefix, the cache entry would have been 'your/data/file.ext'.
* a trailing slash to the prefix if needed. Following on with the previous example
* and using 'your' as a prefix, the cache entry would have been 'your/data/file.ext'.
* This is done both in non-flat and flat mode.
*
*/
@ -318,64 +321,74 @@ class FSDirectory : public Archive {
public:
/**
* Create a FSDirectory representing a tree with the specified depth. Will result in an
* unbound FSDirectory if name is not found on the filesystem or if the node is not a
* unbound FSDirectory if name is not found in the file system or if the node is not a
* valid directory.
*/
FSDirectory(const String &name, int depth = 1, bool flat = false,
bool ignoreClashes = false, bool includeDirectories = false);
/**
* @overload
*/
FSDirectory(const FSNode &node, int depth = 1, bool flat = false,
bool ignoreClashes = false, bool includeDirectories = false);
/**
* Create a FSDirectory representing a tree with the specified depth. The parameter
* prefix is prepended to the keys in the cache. See class comment.
* prefix is prepended to the keys in the cache. See @ref FSDirectory.
*/
FSDirectory(const String &prefix, const String &name, int depth = 1,
bool flat = false, bool ignoreClashes = false, bool includeDirectories = false);
/**
* @overload
*/
FSDirectory(const String &prefix, const FSNode &node, int depth = 1,
bool flat = false, bool ignoreClashes = false, bool includeDirectories = false);
virtual ~FSDirectory();
/**
* This return the underlying FSNode of the FSDirectory.
* Return the underlying FSNode of the FSDirectory.
*/
FSNode getFSNode() const;
/**
* Create a new FSDirectory pointing to a sub directory of the instance. See class comment
* for an explanation of the prefix parameter.
* @return a new FSDirectory instance
* Create a new FSDirectory pointing to a subdirectory of the instance.
* @return A new FSDirectory instance.
*/
FSDirectory *getSubDirectory(const String &name, int depth = 1, bool flat = false,
bool ignoreClashes = false);
/**
* Create a new FSDirectory pointing to a subdirectory of the instance. See FSDirectory
* for an explanation of the prefix parameter.
* @return A new FSDirectory instance.
*/
FSDirectory *getSubDirectory(const String &prefix, const String &name, int depth = 1,
bool flat = false, bool ignoreClashes = false);
/**
* Checks for existence in the cache. A full match of relative path and filename is needed
* for success.
* Check for the existence of a file in the cache. A full match of relative path and file name
* is needed for success.
*/
virtual bool hasFile(const String &name) const;
/**
* Returns a list of matching file names. Pattern can use GLOB wildcards.
* Return a list of matching file names. Pattern can use GLOB wildcards.
*/
virtual int listMatchingMembers(ArchiveMemberList &list, const String &pattern) const;
/**
* Returns a list of all the files in the cache.
* Return a list of all the files in the cache.
*/
virtual int listMembers(ArchiveMemberList &list) const;
/**
* Get a ArchiveMember representation of the specified file. A full match of relative
* path and filename is needed for success.
* Get an ArchiveMember representation of the specified file. A full match of relative
* path and file name is needed for success.
*/
virtual const ArchiveMemberPtr getMember(const String &name) const;
/**
* Open the specified file. A full match of relative path and filename is needed
* Open the specified file. A full match of relative path and file name is needed
* for success.
*/
virtual SeekableReadStream *createReadStreamForMember(const String &name) const;

4
common/gui_options.h
View file

@ -111,8 +111,8 @@ String parseGameGUIOptions(const String &str);
const String getGameGUIOptionsDescription(const String &options);
/**
* Updates the GUI options of the current config manager
* domain, when they differ to the ones passed as
* Update the GUI options of the current config manager
* domain when they differ to the ones passed as
* parameter.
*/
void updateGameGUIOptions(const String &options, const String &langOption);

2
common/hash-ptr.h
View file

@ -37,7 +37,7 @@ namespace Common {
*/
/**
* Partial specialization of the Hash functor to be able to use pointers as HashMap keys
* Partial specialization of the Hash functor allowing to use pointers as HashMap keys.
*/
template<typename T>
struct Hash<T *> {

77
common/hashmap.h
View file

@ -26,19 +26,16 @@
#ifndef COMMON_HASHMAP_H
#define COMMON_HASHMAP_H
/**
* @def DEBUG_HASH_COLLISIONS
* Enable the following #define if you want to check how many collisions the
* code produces (many collisions indicate either a bad hash function, or a
* hash table that is too small).
*/
// Enable the following #define if you want to check how many collisions the
// code produces (many collisions indicate either a bad hash function, or a
// hash table that is too small).
//#define DEBUG_HASH_COLLISIONS
/**
* @def USE_HASHMAP_MEMORY_POOL
* Enable the following define to let HashMaps use a memory pool for the
nodes they contain. * This increases memory usage, but also can improve
speed quite a bit.
* nodes they contain. This increases memory usage, but can also improve
* speed quite a bit.
*/
#define USE_HASHMAP_MEMORY_POOL
@ -53,8 +50,6 @@
#include "common/memorypool.h"
#endif
namespace Common {
/**
@ -76,15 +71,15 @@ template<class T> class IteratorImpl;
/**
* HashMap<Key,Val> maps objects of type Key to objects of type Val.
* For each used Key type, we need an "size_type hashit(Key,size_type)" function
* that computes a hash for the given Key object and returns it as an
* an integer from 0 to hashsize-1, and also an "equality functor".
* that returns true if if its two arguments are to be considered
* equal. Also, we assume that "=" works on Val objects for assignment.
* For each used Key type, a "size_type hashit(Key,size_type)" function
* is required that computes a hash for the given Key object and returns it as
* an integer from 0 to hashsize-1. An "equality functor" is also required
* that returns true if its two arguments are to be considered
* equal. Also, it is assumed that "=" works on Val objects for assignment.
*
* If aa is an HashMap<Key,Val>, then space is allocated each time aa[key] is
* If aa is a HashMap<Key,Val>, then space is allocated each time aa[key] is
* referenced, for a new key. If the object is const, then an assertion is
* triggered instead. Hence if you are not sure whether a key is contained in
* triggered instead. Hence, if you are not sure whether a key is contained in
* the map, use contains() first to check for its presence.
*/
template<class Key, class Val, class HashFunc = Hash<Key>, class EqualFunc = EqualTo<Key> >
@ -301,7 +296,7 @@ public:
}
// TODO: insert() method?
/** Return true if hashmap is empty. */
bool empty() const {
return (_size == 0);
}
@ -332,8 +327,8 @@ HashMap<Key, Val, HashFunc, EqualFunc>::HashMap() : _defaultVal() {
/**
* Copy constructor, creates a full copy of the given hashmap.
* We must provide a custom copy constructor as we use pointers
* to heap buffers for the internal storage.
* A custom copy constructor must be provided as pointers
* to heap buffers are used for the internal storage.
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
HashMap<Key, Val, HashFunc, EqualFunc>::HashMap(const HM_t &map) :
@ -365,7 +360,7 @@ HashMap<Key, Val, HashFunc, EqualFunc>::~HashMap() {
* Internal method for assigning the content of another HashMap
* to this one.
*
* @note We do *not* deallocate the previous storage here -- the caller is
* @note The previous storage here is *not* deallocated here -- the caller is
* responsible for doing that!
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
@ -393,6 +388,9 @@ void HashMap<Key, Val, HashFunc, EqualFunc>::assign(const HM_t &map) {
assert(_deleted == map._deleted);
}
/**
* Clear all values in the hashmap.
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
void HashMap<Key, Val, HashFunc, EqualFunc>::clear(bool shrinkArray) {
@ -555,6 +553,9 @@ typename HashMap<Key, Val, HashFunc, EqualFunc>::size_type HashMap<Key, Val, Has
return ctr;
}
/**
* Check whether the hashmap contains the given key.
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
bool HashMap<Key, Val, HashFunc, EqualFunc>::contains(const Key &key) const {
@ -562,16 +563,28 @@ bool HashMap<Key, Val, HashFunc, EqualFunc>::contains(const Key &key) const {
return (_storage[ctr] != nullptr);
}
/**
* Get a value from the hashmap.
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
Val &HashMap<Key, Val, HashFunc, EqualFunc>::operator[](const Key &key) {
return getVal(key);
}
/**
* @overload
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
const Val &HashMap<Key, Val, HashFunc, EqualFunc>::operator[](const Key &key) const {
return getVal(key);
}
/**
* Get a value from the hashmap.
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
Val &HashMap<Key, Val, HashFunc, EqualFunc>::getVal(const Key &key) {
size_type ctr = lookupAndCreateIfMissing(key);
@ -579,11 +592,19 @@ Val &HashMap<Key, Val, HashFunc, EqualFunc>::getVal(const Key &key) {
return _storage[ctr]->_value;
}
/**
* @overload
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
const Val &HashMap<Key, Val, HashFunc, EqualFunc>::getVal(const Key &key) const {
return getVal(key, _defaultVal);
}
/**
* Get a value from the hashmap. If the key is not present, then return @p defaultVal.
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
const Val &HashMap<Key, Val, HashFunc, EqualFunc>::getVal(const Key &key, const Val &defaultVal) const {
size_type ctr = lookup(key);
@ -593,6 +614,10 @@ const Val &HashMap<Key, Val, HashFunc, EqualFunc>::getVal(const Key &key, const
return defaultVal;
}
/**
* Assign an element specified by @p key to a value @p val.
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
bool HashMap<Key, Val, HashFunc, EqualFunc>::tryGetVal(const Key &key, Val &out) const {
size_type ctr = lookup(key);
@ -611,6 +636,10 @@ void HashMap<Key, Val, HashFunc, EqualFunc>::setVal(const Key &key, const Val &v
_storage[ctr]->_value = val;
}
/**
* Erase an element referred to by an iterator.
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
void HashMap<Key, Val, HashFunc, EqualFunc>::erase(iterator entry) {
// Check whether we have a valid iterator
@ -628,6 +657,10 @@ void HashMap<Key, Val, HashFunc, EqualFunc>::erase(iterator entry) {
_deleted++;
}
/**
* Erase an element specified by a key.
*/
template<class Key, class Val, class HashFunc, class EqualFunc>
void HashMap<Key, Val, HashFunc, EqualFunc>::erase(const Key &key) {

24
common/huffman.h
View file

@ -32,13 +32,13 @@
namespace Common {
/**
* @defgroup common_huffmann Huffman bitstream decoding
* @defgroup common_huffmann Huffman bit stream decoding
* @ingroup common
*
* @brief API for operations related to Huffman bitstream decoding.
* @brief API for operations related to Huffman bit stream decoding.
*
* @details Used in engines:
* - scumm
* - SCUMM
*
* @{
*/
@ -53,7 +53,7 @@ inline uint32 REVERSEBITS(uint32 x) {
}
/**
* Huffman bitstream decoding
* Huffman bit stream decoding.
*
*/
template<class BITSTREAM>
@ -61,15 +61,15 @@ class Huffman {
public:
/** Construct a Huffman decoder.
*
* @param maxLength Maximal code length. If 0, it's searched for.
* @param maxLength Maximal code length. If 0, it is searched for.
* @param codeCount Number of codes.
* @param codes The actual codes.
* @param lengths Lengths of the individual codes.
* @param symbols The symbols. If 0, assume they are identical to the code indices.
* @param codes The actual codes.
* @param lengths Lengths of the individual codes.
* @param symbols The symbols. If 0, assume they are identical to the code indices.
*/
Huffman(uint8 maxLength, uint32 codeCount, const uint32 *codes, const uint8 *lengths, const uint32 *symbols = nullptr);
/** Return the next symbol in the bitstream. */
/** Return the next symbol in the bit stream. */
uint32 getSymbol(BITSTREAM &bits) const;
private:
@ -111,13 +111,13 @@ Huffman<BITSTREAM>::Huffman(uint8 maxLength, uint32 codeCount, const uint32 *cod
assert(maxLength <= 32);
// Codes that don't fit in the prefix table are stored in the _codes array
// Codes that do not fit in the prefix table are stored in the _codes array.
_codes.resize(MAX(maxLength - _prefixTableBits, 0));
for (uint i = 0; i < codeCount; i++) {
uint8 length = lengths[i];
// The symbol. If none were specified, just assume it's identical to the code index
// The symbol. If none was specified, assume it is identical to the code index.
uint32 symbol = symbols ? symbols[i] : i;
if (length <= _prefixTableBits) {
@ -138,7 +138,7 @@ Huffman<BITSTREAM>::Huffman(uint8 maxLength, uint32 codeCount, const uint32 *cod
_prefixTable[index].length = length;
}
} else {
// Put the code and symbol into the correct list for the length
// Put the code and symbol into the correct list for the length.
_codes[lengths[i] - 1 - _prefixTableBits].push_back(Symbol(codes[i], symbol));
}
}

91
common/ini-file.h
View file

@ -43,48 +43,51 @@ class SeekableReadStream;
class WriteStream;
/**
* This class allows reading/writing INI style config files.
* This class allows for reading and writing INI-style config files.
*
* Lines starting with a '#' are ignored (i.e. treated as comments).
* Some effort is made to preserve comments, though.
*
* This class makes no attempts to provide fast access to key/value pairs.
* In particular, it stores all sections and k/v pairs in lists, not
* In particular, it stores all sections and key/value pairs in lists, not
* in dictionaries/maps. This makes it very easy to read/write the data
* from/to files, but of course is not appropriate for fast access.
* The main reason is that this class is indeed geared toward doing precisely
* that!
* that.
*/
class INIFile {
public:
struct KeyValue {
String key;
String value;
String comment;
String key; /*!< Key of the configuration entry. */
String value; /*!< Value of the configuration entry. */
String comment; /*!< Comment within an INI file. */
};
typedef List<KeyValue> SectionKeyList;
typedef List<KeyValue> SectionKeyList; /*!< A list of all key/value pairs in this section. */
/** A section in a ini file. I.e. corresponds to something like this:
* [mySection]
* key=value
/** A section in an INI file.
*
* Comments are also stored, to keep users happy who like editing their
* ini files manually.
* Corresponds to the following:
* @code
* [mySection]
* key=value
* @endcode
* Comments are also stored, for convenience of users who prefer to edit
* INI files manually.
*/
struct Section {
String name;
List<KeyValue> keys;
String comment;
String name; /*!< Name of the section. */
List<KeyValue> keys; /*!< List of all keys in this section. */
String comment; /*!< Comment within the section. */
bool hasKey(const String &key) const;
const KeyValue* getKey(const String &key) const;
void setKey(const String &key, const String &value);
void removeKey(const String &key);
const SectionKeyList getKeys() const { return keys; }
bool hasKey(const String &key) const; /*!< Check whether the section has a @p key. */
const KeyValue* getKey(const String &key) const; /*!< Get the value assigned to a @p key. */
void setKey(const String &key, const String &value); /*!< Assign a @p value to a @p key. */
void removeKey(const String &key); /*!< Remove a @p key from this section. */
const SectionKeyList getKeys() const { return keys; } /*!< Get a list of all keys in the section. */
};
typedef List<Section> SectionList;
typedef List<Section> SectionList; /*!< A list of all sections in this INI file. */
public:
INIFile();
@ -94,40 +97,40 @@ public:
/**
* Check whether the given string is a valid section or key name.
* For that, it must only consist of letters, numbers, dashes and
* underscores. In particular, white space and "#", "=", "[", "]"
* are not valid!
* For that, it must only consist of letters, numbers, dashes, and
* underscores. In particular, whitespace and "#", "=", "[", "]"
* are not valid.
*/
bool isValidName(const String &name) const;
/** Reset everything stored in this ini file. */
/** Reset everything stored in this INI file. */
void clear();
bool loadFromFile(const String &filename);
bool loadFromSaveFile(const String &filename);
bool loadFromStream(SeekableReadStream &stream);
bool saveToFile(const String &filename);
bool saveToSaveFile(const String &filename);
bool saveToStream(WriteStream &stream);
bool loadFromFile(const String &filename); /*!< Load configuration from a file. */
bool loadFromSaveFile(const String &filename); /*!< Load configuration from a save file. */
bool loadFromStream(SeekableReadStream &stream); /*!< Load configuration from a @ref SeekableReadStream. */
bool saveToFile(const String &filename); /*!< Save the current configuration to a file. */
bool saveToSaveFile(const String &filename); /*!< Save the current configuration to a save file. */
bool saveToStream(WriteStream &stream); /*!< Save the current configuration to a @ref WriteStream. */
bool hasSection(const String &section) const;
void addSection(const String &section);
void removeSection(const String &section);
void renameSection(const String &oldName, const String &newName);
bool hasSection(const String &section) const; /*!< Check whether the INI file has a section with the specified name. */
void addSection(const String &section); /*!< Add a section with the specified name to the INI file. */
void removeSection(const String &section); /*!< Remove the @p section from the INI file. */
void renameSection(const String &oldName, const String &newName); /*!< Rename the INI file from @p oldName to @p newName. */
void setDefaultSectionName(const String &name); ///< sets initial section name for section-less ini files
void setDefaultSectionName(const String &name); /*!< Set initial section name for section-less INI files. */
bool hasKey(const String &key, const String &section) const;
bool getKey(const String &key, const String &section, String &value) const;
void setKey(const String &key, const String &section, const String &value);
void removeKey(const String &key, const String &section);
bool hasKey(const String &key, const String &section) const; /*!< Check whether the @p section has a @p key. */
bool getKey(const String &key, const String &section, String &value) const; /*!< Get the @p value of a @p key in a @p section. */
void setKey(const String &key, const String &section, const String &value); /*!< Assign a @p value to a @p key in a @p section. */
void removeKey(const String &key, const String &section); /*!< Remove a @p key from this @p section. */
const SectionList getSections() const { return _sections; }
const SectionKeyList getKeys(const String &section) const;
const SectionList getSections() const { return _sections; } /*!< Get a list of sections in this INI file. */
const SectionKeyList getKeys(const String &section) const; /*!< Get a list of keys in a @p section. */
void listKeyValues(StringMap &kv);
void listKeyValues(StringMap &kv); /*!< Get a list of all key/value pairs in this INI file. */
void allowNonEnglishCharacters();
void allowNonEnglishCharacters(); /*!< Allow non-English characters in this INI file. */
private:
String _defaultSectionName;

14
doc/doxygen/scummvm.doxyfile
View file

@ -238,10 +238,7 @@ TAB_SIZE = 4
# "Side Effects:". You can put \n's in the value part of an alias to insert
# newlines.
ALIASES = "tip_s=<span class=\"tip\">" \
"tip_e=</span>" \
"warn_s=<span class=\"warn\">" \
"warn_e=</span>" \
ALIASES =
# This tag can be used to specify a number of word-keyword mappings (TCL only).
# A mapping has the form "name=value". For example adding "class=itcl::class"
@ -626,7 +623,7 @@ STRICT_PROTO_MATCHING = NO
# list. This list is created by putting \todo commands in the documentation.
# The default value is: YES.
GENERATE_TODOLIST = YES
GENERATE_TODOLIST = NO
# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test
# list. This list is created by putting \test commands in the documentation.
@ -2048,7 +2045,7 @@ ENABLE_PREPROCESSING = YES
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
MACRO_EXPANSION = NO
MACRO_EXPANSION = YES
# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
# the macro expansion is limited to the macros specified with the PREDEFINED and
@ -2088,7 +2085,10 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
PREDEFINED =
PREDEFINED = USE_SYSDIALOGS \
SCUMM_NEED_ALIGNMENT \
SCUMM_LITTLE_ENDIAN \
SCUMM_BIG_ENDIAN \
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The