libretro/scummvm
1
0
Fork 0
mirror of https://github.com/libretro/scummvm.git synced 2024-11-30 21:00:39 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

ALL: Sync with ScummVM rev: c52f7e0e04

Browse Source
This commit is contained in:
Pawel Kolodziejski 2020-10-05 14:54:26 +02:00
parent b05551ec2d
commit 4f8f566299
18 changed files with 584 additions and 389 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitignore vendored
View File

@ -62,6 +62,9 @@ lib*.a
/dists/codeblocks/*.layout
/dists/codeblocks/residualvm*
/doc/doxygen/html
/doc/doxygen/doxygen_warnings.txt
#Ignore XCode user data and build files
xcuserdata
project.xcworkspace

3
Makefile.common
View File

@ -37,7 +37,8 @@ MODULES += \
audio \
math \
common \
po
po \
doc
ifdef USE_MT32EMU
MODULES += audio/softsynth/mt32

113
common/achievements.h
View File

@ -51,58 +51,135 @@ enum AchievementsPlatform {
/**
* Per-game achievements information structure item.
* Information structure for game-specific achievements.
*/
struct AchievementDescription {
const char *id; // achievement internal id, e.g. "ACHIEVEMENT_TIMING"
bool isHidden; // achievement is hidden
const char *title; // achievement displayed text, e.g. "Marathon Runner"
const char *comment; // optional achievement hint / comment, e.g. "Finish the game in less than 4 hours"
const char *id; //!< Achievement internal ID, such as "ACHIEVEMENT_TIMING".
bool isHidden; //!< Whether the achievement is hidden.
const char *title; //!< Achievement displayed text, such as "Marathon Runner".
const char *comment; //!< Optional achievement hint or comment, such as "Finish the game in less than 4 hours".
};
/**
* Per-game achievements information structure item.
* Information structure for platform-specific achievements.
*/
struct AchievementsInfo {
Common::AchievementsPlatform platform; // achievements platform, e.g. STEAM_ACHIEVEMENTS
Common::String appId; // achievements application ID of given platform
Common::Array<AchievementDescription> descriptions; // descriptions of all game achievements
Common::AchievementsPlatform platform; //!< Achievements platform, such as "STEAM_ACHIEVEMENTS".
Common::String appId; //!< Achievements application ID of the given platform.
Common::Array<AchievementDescription> descriptions; //!< Descriptions of all game achievements.
AchievementsInfo() {platform = Common::UNK_ACHIEVEMENTS;}
};
/**
* Class for manipulating the achievements.
*
* Use the Achievements Manager class to edit the in-game achievements.
*/
class AchievementsManager : public Singleton<AchievementsManager> {
public:
AchievementsManager();
~AchievementsManager();
/**
* Set a platform and application ID as active domain.
*
* @param[in] platform Achievements platform.
* @param[in] appId Achievements application ID of the given platform.
*/
bool setActiveDomain(AchievementsPlatform platform, const String &appId);
bool unsetActiveDomain();
bool isReady() { return _iniFile != nullptr; }
bool unsetActiveDomain(); //!< Unset the current active domain.
bool isReady() { return _iniFile != nullptr; } //!< Check whether the domain is ready.
/**
* @name Methods for manipulating individual achievements
* @{
*/
/** Set an achievement.
*
* @param[in] id Internal ID of the achievement.
* @param[in] displayedMessage Message displayed when the achievement is achieved.
*/
// Methods to manipulate individual achievements
bool setAchievement(const String &id, const String &displayedMessage);
/**
* Set an achievement as achieved.
*
* @param[in] id Internal ID of the achievement.
*/
bool isAchieved(const String &id);
/**
* Clear an achieved achievement.
*
* @param[in] id Internal ID of the achievement.
*/
bool clearAchievement(const String &id);
/** @} */
/**
* @name Methods for manipulating individual statistics
* @{
*/
// Methods to manipulate individual statistics
/**
* Get a statistic (integer).
*
* @param[in] id Internal ID of the achievement.
*/
int getStatInt(const String &id);
/**
* Set a statistic to an integer number.
*
* @param[in] id Internal ID of the achievement.
* @param[in] value Value to which the statistic is set.
*/
bool setStatInt(const String &id, int value);
/**
* Get a statistic (float).
*
* @param[in] id Internal ID of the achievement.
*/
float getStatFloat(const String &id);
/**
* Set a statistic to a float number.
*
* @param[in] id Internal ID of the achievement.
* @param[in] value Value to which the statistic is set.
*/
bool setStatFloat(const String &id, float value);
// Methods to reset everything
bool resetAllAchievements();
bool resetAllStats();
/** @} */
/**
* @name Methods for resetting achievements and statistics
* @{
*/
bool resetAllAchievements(); //!< Reset all achievements.
bool resetAllStats(); //!< Reset all statistics.
/** @} */
private:
INIFile *_iniFile;
String _iniFileName;
};
/** Shortcut for accessing the achievements manager. */
/** Shortcut for accessing the Achievements Manager. */
#define AchMan Common::AchievementsManager::instance()
/** @} */

135
common/algorithm.h
View File

@ -39,8 +39,14 @@ namespace Common {
*/
/**
* Copies data from the range [first, last) to [dst, dst + (last - first)).
* It requires the range [dst, dst + (last - first)) to be valid.
* @name Copy templates
* @{
*/
/**
* Copy data from the range [first, last) to [dst, dst + (last - first)).
*
* The function requires the range [dst, dst + (last - first)) to be valid.
* It also requires dst not to be in the range [first, last).
*/
template<class In, class Out>
@ -51,11 +57,12 @@ Out copy(In first, In last, Out dst) {
}
/**
* Copies data from the range [first, last) to [dst - (last - first), dst).
* It requires the range [dst - (last - first), dst) to be valid.
* Copy data from the range [first, last) to [dst - (last - first), dst).
*
* The function requires the range [dst - (last - first), dst) to be valid.
* It also requires dst not to be in the range [first, last).
*
* Unlike copy copy_backward copies the data from the end to the beginning.
* Unlike copy, copy_backward copies the data from the end to the beginning.
*/
template<class In, class Out>
Out copy_backward(In first, In last, Out dst) {
@ -65,11 +72,12 @@ Out copy_backward(In first, In last, Out dst) {
}
/**
* Copies data from the range [first, last) to [dst, dst + (last - first)).
* It requires the range [dst, dst + (last - first)) to be valid.
* Copy data from the range [first, last) to [dst, dst + (last - first)).
*
* The function requires the range [dst, dst + (last - first)) to be valid.
* It also requires dst not to be in the range [first, last).
*
* Unlike copy or copy_backward it does not copy all data. It only copies
* Unlike copy or copy_backward, it does not copy all data. It only copies
* a data element when operator() of the op parameter returns true for the
* passed data element.
*/
@ -83,23 +91,51 @@ Out copy_if(In first, In last, Out dst, Op op) {
return dst;
}
// Our 'specialized' 'fill' template for char, signed char and unsigned char arrays.
// Since C++ doesn't support partial specialized template functions (currently) we
// are going this way...
// With this we assure the usage of memset for those, which should be
// faster than a simple loop like for the generic 'fill'.
/**
* @}
*/
/**
* @name Fill templates
* @{
*/
/**
* A 'fill' template for signed char arrays.
*
* Since C++ does not currently support partial specialized template functions,
* this solution is implemented.
* With this template, the usage of memset is assured, which is
* faster than a simple loop like for the generic 'fill'.
*/
template<class Value>
signed char *fill(signed char *first, signed char *last, Value val) {
memset(first, (val & 0xFF), last - first);
return last;
}
/**
* A 'fill' template for unsigned char arrays.
*
* Since C++ does not currently support partial specialized template functions,
* this solution is implemented.
* With this template, the usage of memset is assured, which is
* faster than a simple loop like for the generic 'fill'.
*/
template<class Value>
unsigned char *fill(unsigned char *first, unsigned char *last, Value val) {
memset(first, (val & 0xFF), last - first);
return last;
}
/**
* A 'fill' template for char arrays.
*
* Since C++ does not currently support partial specialized template functions,
* this solution is implemented.
* With this template, the usage of memset is assured, which is
* faster than a simple loop like for the generic 'fill'.
*/
template<class Value>
char *fill(char *first, char *last, Value val) {
memset(first, (val & 0xFF), last - first);
@ -107,7 +143,16 @@ char *fill(char *first, char *last, Value val) {
}
/**
* Sets all elements in the range [first, last) to val.
* @}
*/
/**
* @name Range templates
* @{
*/
/**
* Set all elements in the range [first, last) to val.
*/
template<class In, class Value>
In fill(In first, In last, const Value &val) {
@ -117,8 +162,8 @@ In fill(In first, In last, const Value &val) {
}
/**
* Finds the first data value in the range [first, last) matching v.
* For data comperance it uses operator == of the data elements.
* Find the first data value in the range [first, last) matching v.
* For data comparison, it uses operator == of the data elements.
*/
template<class In, class T>
In find(In first, In last, const T &v) {
@ -131,7 +176,7 @@ In find(In first, In last, const T &v) {
}
/**
* Finds the first data value in the range [first, last) for which
* Find the first data value in the range [first, last), for which
* the specified predicate p returns true.
*/
template<class In, class Pred>
@ -145,7 +190,7 @@ In find_if(In first, In last, Pred p) {
}
/**
* Applies the function f on all elements of the range [first, last).
* Apply the function f on all elements from the range [first, last).
* The processing order is from beginning to end.
*/
template<class In, class Op>
@ -155,6 +200,10 @@ Op for_each(In first, In last, Op f) {
return f;
}
/**
* @}
*/
template<typename T>
unsigned int distance(T *first, T *last) {
return last - first;
@ -205,12 +254,18 @@ T sortPartition(T first, T last, T pivot, StrictWeakOrdering &comp) {
}
/**
* Simple sort function, modeled after std::sort.
* It compares data with the given comparator object comp.
* @name Sorting templates
* @{
*/
/**
* Simple sorting function, modeled after std::sort.
*
* Like std::sort this is not guaranteed to be stable.
* This function compares data with the given comparator object comp.
*
* Two small quotes from wikipedia about stability:
* Like std::sort, this is not guaranteed to be stable.
*
* Two quotes from Wikipedia about stability:
*
* Stable sorting algorithms maintain the relative order of records with
* equal keys.
@ -218,11 +273,16 @@ T sortPartition(T first, T last, T pivot, StrictWeakOrdering &comp) {
* Unstable sorting algorithms may change the relative order of records with
* equal keys, but stable sorting algorithms never do so.
*
* For more information on that topic check out:
* For more information, see:
* http://en.wikipedia.org/wiki/Sorting_algorithm#Stability
*
* NOTE: Actually as the time of writing our implementation is unstable.
* @note Currently, this implementation is unstable.
*
* @param[in] first First element to sort.
* @param[in] last Last element to sort.
* @param[in] comp Comparator object.
*/
template<typename T, class StrictWeakOrdering>
void sort(T first, T last, StrictWeakOrdering comp) {
if (first == last)
@ -235,18 +295,32 @@ void sort(T first, T last, StrictWeakOrdering comp) {
}
/**
* Simple sort function, modeled after std::sort.
* Simple sorting function, modeled after std::sort.
*
* @param[in] first First element to sort.
* @param[in] last Last element to sort.
*/
template<typename T>
void sort(T *first, T *last) {
sort(first, last, Less<T>());
}
/**
* Simple sorting function, modeled after std::sort.
*
* @param[in] first First element to sort.
* @param[in] last Last element to sort.
*/
template<class T>
void sort(T first, T last) {
sort(first, last, Less<typename T::ValueType>());
}
/**
* @}
*/
// MSVC is complaining about the minus operator being applied to an unsigned type
// We disable this warning for the affected section of code
#if defined(_MSC_VER)
@ -255,7 +329,7 @@ void sort(T first, T last) {
#endif
/**
* Euclid's algorithm to compute the greatest common divisor.
* Euclidean algorithm to compute the greatest common divisor.
*/
template<class T>
T gcd(T a, T b) {
@ -301,10 +375,10 @@ T nextHigher2(T v) {
*
* Replaces all occurrences of "original" in [begin, end) with occurrences of "replaced".
*
* @param[in, out] begin: First element to be examined.
* @param[in] end: Last element in the seubsection. Not examined.
* @param[in] original: Elements to be replaced.
* @param[in] replaced: Element to replace occurrences of "original".
* @param[in,out] begin First element to be examined.
* @param[in] end Last element in the subsection. Not examined.
* @param[in] original Elements to be replaced.
* @param[in] replaced Element to replace occurrences of @p original.
*
* @note Usage examples and unit tests may be found in "test/common/algorithm.h"
*/
@ -319,7 +393,6 @@ void replace(It begin, It end, const Dat &original, const Dat &replaced) {
/** @} */
} // End of namespace Common
#endif

101
common/archive.h
View File

@ -34,32 +34,30 @@ namespace Common {
* @defgroup common_arch Archive
* @ingroup common
*
* @brief The Archive module allows managing the member of arbitrary containers in a uniform
* @brief The Archive module allows for managing the members of arbitrary containers in a uniform
* fashion.
* It also supports looking up by names and file names, opening a file, and returning usable input stream.
*
* It also supports looking up by names and file names, opening a file, and returning a usable input stream.
* @{
*/
class FSNode;
class SeekableReadStream;
/**
* ArchiveMember is an abstract interface to represent elements inside
* implementations of Archive.
* The ArchiveMember class is an abstract interface to represent elements inside
* implementations of an archive.
*
* Archive subclasses must provide their own implementation of ArchiveMember,
* and use it when serving calls to listMembers() and listMatchingMembers().
* Alternatively, the GenericArchiveMember below can be used.
* and use it when serving calls to @ref Archive::listMembers and @ref Archive::listMatchingMembers.
* Alternatively, you can use the @ref GenericArchiveMember.
*/
class ArchiveMember {
public:
virtual ~ArchiveMember() { }
virtual SeekableReadStream *createReadStream() const = 0;
virtual String getName() const = 0;
virtual String getDisplayName() const { return getName(); }
virtual SeekableReadStream *createReadStream() const = 0; /*!< Create a read stream. */
virtual String getName() const = 0; /*!< Get the name of a read stream. */
virtual String getDisplayName() const { return getName(); } /*!< Get display name of a read stream. */
};
typedef SharedPtr<ArchiveMember> ArchiveMemberPtr;
@ -86,16 +84,16 @@ class GenericArchiveMember : public ArchiveMember {
const Archive *_parent;
const String _name;
public:
GenericArchiveMember(const String &name, const Archive *parent);
String getName() const;
GenericArchiveMember(const String &name, const Archive *parent); /*!< Create a generic archive member. */
String getName() const; /*!< Get the name of a generic archive member. */
SeekableReadStream *createReadStream() const;
};
/**
* Archive allows managing of member of arbitrary containers in a uniform
* fashion, allowing lookup by (file)names.
* It also supports opening a file and returning an usable input stream.
* The Archive class allows for managing the members of arbitrary containers in a uniform
* fashion, allowing lookup by (file) names.
* It also supports opening a file and returning a usable input stream.
*/
class Archive {
public:
@ -109,40 +107,42 @@ public:
virtual bool hasFile(const String &name) const = 0;
/**
* Add all members of the Archive matching the specified pattern to list.
* Add all members of the Archive matching the specified pattern to the list.
* Must only append to list, and not remove elements from it.
*
* @return the number of members added to list
* @return The number of members added to list.
*/
virtual int listMatchingMembers(ArchiveMemberList &list, const String &pattern) const;
/**
* Add all members of the Archive to list.
* Add all members of the Archive to the list.
* Must only append to list, and not remove elements from it.
*
* @return the number of names added to list
* @return The number of names added to list.
*/
virtual int listMembers(ArchiveMemberList &list) const = 0;
/**
* Returns a ArchiveMember representation of the given file.
* Return an ArchiveMember representation of the given file.
*/
virtual const ArchiveMemberPtr getMember(const String &name) const = 0;
/**
* Create a stream bound to a member with the specified name in the
* archive. If no member with this name exists, 0 is returned.
* @return the newly created input stream
*
* @return The newly created input stream.
*/
virtual SeekableReadStream *createReadStreamForMember(const String &name) const = 0;
};
/**
* SearchSet enables access to a group of Archives through the Archive interface.
* The SearchSet class enables access to a group of Archives through the Archive interface.
*
* Its intended usage is a situation in which there are no name clashes among names in the
* contained Archives, hence the simplistic policy of always looking for the first
* match. SearchSet *DOES* guarantee that searches are performed in *DESCENDING*
* match. SearchSet does guarantee that searches are performed in DESCENDING
* priority order. In case of conflicting priorities, insertion order prevails.
*/
class SearchSet : public Archive {
@ -161,8 +161,7 @@ class SearchSet : public Archive {
ArchiveNodeList::iterator find(const String &name);
ArchiveNodeList::const_iterator find(const String &name) const;
// Add an archive keeping the list sorted by descending priority.
void insert(const Node& node);
void insert(const Node& node); //!< Add an archive keeping the list sorted by descending priority.
bool _ignoreClashes;
@ -176,58 +175,56 @@ public:
void add(const String& name, Archive *arch, int priority = 0, bool autoFree = true);
/**
* Create and add a FSDirectory by name
* Create and add a FSDirectory by name.
*/
void addDirectory(const String &name, const String &directory, int priority = 0, int depth = 1, bool flat = false);
/**
* Create and add a FSDirectory by FSNode
* Create and add a FSDirectory by FSNode.
*/
void addDirectory(const String &name, const FSNode &directory, int priority = 0, int depth = 1, bool flat = false);
/**
* Create and add a sub directory by name (caseless).
* Create and add a subdirectory by name (caseless).
*
* It is also possible to add sub directories of sub directories (of any depth) with this function.
* The path seperator for this case is SLASH for *all* systems.
* It is also possible to add subdirectories of subdirectories (of any depth) with this function.
* The path seperator for this case is SLASH for all systems.
*
* An example would be:
* Example:
*
* "game/itedata"
*
* In this example the code would first try to search for all directories matching
* In this example, the code first tries to search for all directories matching
* "game" (case insensitive) in the path "directory" first and search through all
* of the matches for "itedata" (case insensitive too).
*
* Note that it will add *all* matches found!
* Note that it will add all matches found!
*
* Even though this method is currently implemented via addSubDirectoriesMatching it is not safe
* Even though this method is currently implemented via addSubDirectoriesMatching, it is not safe
* to assume that this method is using anything other than a simple case insensitive compare.
* Thus do not use any tokens like '*' or '?' in the "caselessName" parameter of this function!
* Thus, do not use any tokens like '*' or '?' in the "caselessName" parameter of this function.
*/
void addSubDirectoryMatching(const FSNode &directory, const String &caselessName, int priority = 0, int depth = 1, bool flat = false) {
addSubDirectoriesMatching(directory, caselessName, true, priority, depth, flat);
}
/**
* Create and add sub directories by pattern.
* Create and add subdirectories by pattern.
*
* It is also possible to add sub directories of sub directories (of any depth) with this function.
* The path seperator for this case is SLASH for *all* systems.
* It is also possible to add subdirectories of subdirectories (of any depth) with this function.
* The path seperator for this case is SLASH for all systems.
*
* An example would be:
* Example:
*
* "game/itedata"
*
* In this example the code would first try to search for all directories matching
* In this example, the code first tries to search for all directories matching
* "game" in the path "directory" first and search through all of the matches for
* "itedata". If "ingoreCase" is set to true, the code would do a case insensitive
* "itedata". If "ingoreCase" is set to true, the code does a case insensitive
* match, otherwise it is doing a case sensitive match.
*
* This method works of course also with tokens. For a list of available tokens
* see the documentation for Common::matchString.
*
* @see Common::matchString
* This method also works with tokens. For a list of available tokens,
* see @ref Common::matchString.
*/
void addSubDirectoriesMatching(const FSNode &directory, String origPattern, bool ignoreCase, int priority = 0, int depth = 1, bool flat = false);
@ -242,7 +239,7 @@ public:
bool hasArchive(const String &name) const;
/**
* Empties the searchable set.
* Empty the searchable set.
*/
virtual void clear();
@ -258,14 +255,14 @@ public:
virtual const ArchiveMemberPtr getMember(const String &name) const;
/**
* Implements createReadStreamForMember from Archive base class. The current policy is
* Implement createReadStreamForMember from the Archive base class. The current policy is
* opening the first file encountered that matches the name.
*/
virtual SeekableReadStream *createReadStreamForMember(const String &name) const;
/**
* Ignore clashes when adding directories. For more details see the corresponding parameter
* in FSDirectory documentation
* Ignore clashes when adding directories. For more details, see the corresponding parameter
* in FSDirectory documentation.
*/
void setIgnoreClashes(bool ignoreClashes) { _ignoreClashes = ignoreClashes; }
};
@ -275,7 +272,7 @@ class SearchManager : public Singleton<SearchManager>, public SearchSet {
public:
/**
* Resets the search manager to the default list of search paths (system
* Reset the Search Manager to the default list of search paths (system
* specific dirs + current dir).
*/
virtual void clear();
@ -285,7 +282,7 @@ private:
SearchManager();
};
/** Shortcut for accessing the search manager. */
/** Shortcut for accessing the Search Manager. */
#define SearchMan Common::SearchManager::instance()
/** @} */

39
common/array.h
View File

@ -38,17 +38,15 @@ namespace Common {
* @defgroup common_array Arrays
* @ingroup common
*
* @brief Functions for working on arrays.
*
* @brief Functions for replacing std arrays.
* @{
*/
/**
* This class implements a dynamically sized container, which
* can be accessed similar to a regular C++ array. Accessing
* can be accessed similarly to a regular C++ array. Accessing
* elements is performed in constant time (like with plain arrays).
* In addition, one can append, insert and remove entries (this
* In addition, you can append, insert, and remove entries (this
* is the 'dynamic' part). Doing that in general takes time
* proportional to the number of elements in the array.
*
@ -74,7 +72,7 @@ public:
Array() : _capacity(0), _size(0), _storage(nullptr) {}
/**
* Constructs an array with `count` default-inserted instances of T. No
* Construct an array with `count` default-inserted instances of @p T. No
* copies are made.
*/
explicit Array(size_type count) : _size(count) {
@ -84,7 +82,7 @@ public:
}
/**
* Constructs an array with `count` copies of elements with value `value`.
* Construct an array with `count` copies of elements with value `value`.
*/
Array(size_type count, const T &value) : _size(count) {
allocCapacity(count);
@ -134,7 +132,7 @@ public:
_capacity = _size = 0;
}
/** Appends element to the end of the array. */
/** Append an element to the end of the array. */
void push_back(const T &element) {
if (_size + 1 <= _capacity)
new ((void *)&_storage[_size++]) T(element);
@ -142,6 +140,7 @@ public:
insert_aux(end(), &element, &element + 1);
}
/** Append an element to the end of the array. */
void push_back(const Array<T> &array) {
if (_size + array.size() <= _capacity) {
uninitialized_copy(array.begin(), array.end(), end());
@ -150,7 +149,7 @@ public:
insert_aux(end(), array.begin(), array.end());
}
/** Removes the last element of the array. */
/** Remove the last element of the array. */
void pop_back() {
assert(_size > 0);
_size--;
@ -158,35 +157,35 @@ public:
_storage[_size].~T();
}
/** Returns a pointer to the underlying memory serving as element storage. */
/** Return a pointer to the underlying memory serving as element storage. */
const T *data() const {
return _storage;
}
/** Returns a pointer to the underlying memory serving as element storage. */
/** Return a pointer to the underlying memory serving as element storage. */
T *data() {
return _storage;
}
/** Returns a reference to the first element of the array. */
/** Return a reference to the first element of the array. */
T &front() {
assert(_size > 0);
return _storage[0];
}
/** Returns a reference to the first element of the array. */
/** Return a reference to the first element of the array. */
const T &front() const {
assert(_size > 0);
return _storage[0];
}
/** Returns a reference to the last element of the array. */
/** Return a reference to the last element of the array. */
T &back() {
assert(_size > 0);
return _storage[_size-1];
}
/** Returns a reference to the last element of the array. */
/** Return a reference to the last element of the array. */
const T &back() const {
assert(_size > 0);
return _storage[_size-1];
@ -204,7 +203,7 @@ public:
}
/**
* Inserts element before pos.
* Insert an element before @p pos.
*/
void insert(iterator pos, const T &element) {
insert_aux(pos, &element, &element + 1);
@ -377,7 +376,7 @@ protected:
* Unlike std::vector::insert, this method does not accept
* arbitrary iterators, mainly because our iterator system is
* seriously limited and does not distinguish between input iterators,
* output iterators, forward iterators or random access iterators.
* output iterators, forward iterators, or random access iterators.
*
* So, we simply restrict to Array iterators. Extending this to arbitrary
* random access iterators would be trivial.
@ -404,7 +403,7 @@ protected:
uninitialized_copy(oldStorage, oldStorage + idx, _storage);
// Copy the data we insert
uninitialized_copy(first, last, _storage + idx);
// Afterwards copy the old data from the position where we
// Afterwards, copy the old data from the position where we
// insert.
uninitialized_copy(oldStorage + idx, oldStorage + _size, _storage + idx + n);
@ -442,7 +441,7 @@ protected:
};
/**
* Double linked list with sorted nodes.
* Doubly linked list with sorted nodes.
*/
template<class T, typename CompareArgType = const void *>
class SortedArray : public Array<T> {
@ -456,7 +455,7 @@ public:
}
/**
* Inserts element at the sorted position.
* Insert an element at the sorted position.
*/
void insert(const T &element) {
if (!this->_size) {

54
common/bitstream.h
View File

@ -49,19 +49,19 @@ namespace Common {
* gives access to their bits, one at a time.
*
* For example, a bit stream with the layout parameters 32, true, false
* for valueBits, isLE and isMSB2LSB, reads 32bit little-endian values
* for valueBits, isLE and isMSB2LSB, reads 32-bit little-endian values
* from the data stream and hands out the bits in the order of LSB to MSB.
*/
template<class STREAM, int valueBits, bool isLE, bool MSB2LSB>
class BitStreamImpl {
private:
STREAM *_stream; ///< The input stream.
DisposeAfterUse::Flag _disposeAfterUse; ///< Should we delete the stream on destruction?
STREAM *_stream; //!< The input stream.
DisposeAfterUse::Flag _disposeAfterUse; //!< Whether to delete the stream on destruction.
uint64 _bitContainer; ///< The currently available bits.
uint8 _bitsLeft; ///< Number of bits currently left in the bit container.
uint32 _size; ///< Total bitstream size (in bits)
uint32 _pos; ///< Current bitstream position (in bits)
uint64 _bitContainer; //!< The currently available bits.
uint8 _bitsLeft; //!< Number of bits currently left in the bit container.
uint32 _size; //!< Total bit stream size (in bits).
uint32 _pos; //!< Current bit stream position (in bits).
/** Read a data value. */
inline uint32 readData() {
@ -85,7 +85,7 @@ private:
return 0;
}
/** Fill the container with at least min bits. */
/** Fill the container with at least @p min bits. */
inline void fillContainer(size_t min) {
while (_bitsLeft < min) {
@ -93,11 +93,11 @@ private:
if (_pos + _bitsLeft + valueBits <= _size) {
data = readData();
} else {
// Peeking data out of bounds is well defined and returns 0 bits.
// Peeking data out of bounds is well-defined and returns 0 bits.
// This is for convenience when using speed-up techniques reading
// more bits than actually available. Users should call eos() to
// check if data was actually read out of bounds. Peeking out of
// bounds does not set the eos flag.
// more bits than actually available. Call eos() to check if data
// was actually read out of bounds. Peeking out of bounds does not
// set the eos flag.
data = 0;
}
@ -111,7 +111,7 @@ private:
}
}
/** Get n bits from the bit container. */
/** Get @p n bits from the bit container. */
inline static uint32 getNBits(uint64 value, size_t n) {
if (n == 0)
return 0;
@ -183,7 +183,7 @@ public:
/**
* Read a multi-bit value from the bit stream, without changing the stream's position.
*
* The bit order is the same as in getBits().
* The bit order is the same as in @ref getBits().
*/
uint32 peekBits(size_t n) {
if (n > 32)
@ -196,12 +196,12 @@ public:
/**
* Read a multi-bit value from the bit stream.
*
* The value is read as if just taken as a whole from the bitstream.
* The value is read as if just taken as a whole from the bit stream.
*
* For example:
* Reading a 4-bit value from an 8-bit bitstream with the contents 01010011:
* If the bitstream is MSB2LSB, the 4-bit value would be 0101.
* If the bitstream is LSB2MSB, the 4-bit value would be 0011.
* Reading a 4-bit value from an 8-bit bit stream with the contents 01010011:
* If the bit stream is MSB2LSB, the 4-bit value would be 0101.
* If the bit stream is LSB2MSB, the 4-bit value would be 0011.
*/
uint32 getBits(size_t n) {
if (n > 32)
@ -218,12 +218,12 @@ public:
* Add a bit to the value x, making it an n+1-bit value.
*
* The current value is shifted and the bit is added to the
* appropriate place, dependant on the stream's bitorder.
* appropriate place, depending on the stream's bit order.
*
* For example:
* A bit y is added to the value 00001100 with size 4.
* If the stream's bitorder is MSB2LSB, the resulting value is 0001100y.
* If the stream's bitorder is LSB2MSB, the resulting value is 000y1100.
* If the stream's bit order is MSB2LSB, the resulting value is 0001100y.
* If the stream's bit order is LSB2MSB, the resulting value is 000y1100.
*/
void addBit(uint32 &x, uint32 n) {
if (n >= 32)
@ -244,7 +244,7 @@ public:
_pos = 0;
}
/** Skip the specified amount of bits. */
/** Skip the specified number of bits. */
void skip(uint32 n) {
while (n > 32) {
fillContainer(32);
@ -302,7 +302,7 @@ private:
uint32 _pos;
DisposeAfterUse::Flag _disposeMemory;
bool _eos;
/** @overload */
public:
BitStreamMemoryStream(const byte *dataPtr, uint32 dataSize, DisposeAfterUse::Flag disposeMemory = DisposeAfterUse::NO) :
_ptrOrig(dataPtr),
@ -428,8 +428,10 @@ public:
};
// typedefs for various memory layouts.
/**
* @name Typedefs for various memory layouts
* @{
*/
/** 8-bit data, MSB to LSB. */
typedef BitStreamImpl<SeekableReadStream, 8, false, true > BitStream8MSB;
@ -481,6 +483,8 @@ typedef BitStreamImpl<BitStreamMemoryStream, 32, false, false> BitStreamMemory32
/** @} */
/** @} */
} // End of namespace Common
#endif // COMMON_BITSTREAM_H

24
common/bufferedstream.h
View File

@ -38,36 +38,48 @@ namespace Common {
*/
/**
* Take an arbitrary ReadStream and wrap it in a custom stream which
* Take an arbitrary ReadStream and wrap it in a custom stream that
* transparently provides buffering.
* Users can specify how big the buffer should be, and whether the wrapped
* You can specify how big the buffer should be, and whether the wrapped
* stream should be disposed when the wrapper is disposed.
*
* It is safe to call this with a NULL parameter (in this case, NULL is
* returned).
*
* @param parentStream The ReadStream to wrap in a custom stream.
* @param bufSize Size of the buffer.
* @param disposeParentStream Flag indicating whether to dispose of the wrapped stream.
*/
ReadStream *wrapBufferedReadStream(ReadStream *parentStream, uint32 bufSize, DisposeAfterUse::Flag disposeParentStream);
/**
* Take an arbitrary SeekableReadStream and wrap it in a custom stream which
* Take an arbitrary SeekableReadStream and wrap it in a custom stream that
* transparently provides buffering.
* Users can specify how big the buffer should be, and whether the wrapped
* You can specify how big the buffer should be, and whether the wrapped
* stream should be disposed when the wrapper is disposed.
*
* It is safe to call this with a NULL parameter (in this case, NULL is
* returned).
*
* @param parentStream The SeekableReadStream to wrap in a custom stream.
* @param bufSize Size of the buffer.
* @param disposeParentStream Flag indicating whether to dispose of the wrapped stream.
*/
SeekableReadStream *wrapBufferedSeekableReadStream(SeekableReadStream *parentStream, uint32 bufSize, DisposeAfterUse::Flag disposeParentStream);
/**
* Take an arbitrary WriteStream and wrap it in a custom stream which
* Take an arbitrary WriteStream and wrap it in a custom stream that
* transparently provides buffering.
* Users can specify how big the buffer should be. Currently, the
* You can specify how big the buffer should be. Currently, the
* parent stream is \em always disposed when the wrapper is disposed.
*
* It is safe to call this with a NULL parameter (in this case, NULL is
* returned).
*
* @param parentStream The WriteStream to wrap in a custom stream.
* @param bufSize Size of the buffer.
*/
WriteStream *wrapBufferedWriteStream(WriteStream *parentStream, uint32 bufSize);
/** @} */

47
common/callback.h
View File

@ -29,37 +29,36 @@ namespace Common {
* @defgroup common_callback Callbacks
* @ingroup common
*
* @brief Callback templates.
*
* @brief Callback class templates.
* @{
*/
/**
* BaseCallback<S> is a simple base class for object-oriented callbacks.
*
* Object-oriented callbacks are such callbacks that know exact instance
* which method must be called.
* Object-oriented callbacks are callbacks that know the exact instance
* of the method that must be called.
*
* For backwards compatibility purposes, there is a GlobalFunctionCallback,
* For backward compatibility purposes, GlobalFunctionCallback is available,
* which is BaseCallback<void *>, so it can be used with global C-like
* functions too.
*
* <S> is the type, which is passed to operator() of this callback.
* This allows you to specify that you accept a callback, which wants
* to receive an <S> object.
* \<S\> is the type that is passed to operator() of this callback.
* This allows you to specify that you accept a callback that wants
* to receive an \<S\> object.
*/
template<typename S = void *> class BaseCallback {
public:
BaseCallback() {}
virtual ~BaseCallback() {}
virtual void operator()(S data) = 0;
virtual void operator()(S data) = 0; /*!< Type of the object passed to the operator. */
};
/**
* GlobalFunctionCallback<T> is a simple wrapper for global C functions.
*
* If there is a method, which accepts BaseCallback<T>, you can
* easily pass your C function by passing
* If a method accepts BaseCallback<T>, you can
* pass your C function by passing
* new GlobalFunctionCallback<T>(yourFunction)
*/
template<typename T> class GlobalFunctionCallback: public BaseCallback<T> {
@ -69,7 +68,7 @@ template<typename T> class GlobalFunctionCallback: public BaseCallback<T> {
public:
GlobalFunctionCallback(GlobalFunction cb): _callback(cb) {}
virtual ~GlobalFunctionCallback() {}
virtual void operator()(T data) {
virtual void operator()(T data) { /*!< C function passed to the operator. */
if (_callback) _callback(data);
}
};
@ -77,35 +76,37 @@ public:
/**
* Callback<T, S> implements an object-oriented callback.
*
* <T> stands for a class which method you want to call.
* <S>, again, is the type of an object passed to operator().
* \<T\> stands for a class whose method you want to call.
* \<S\> is the type of the object passed to operator().
*
* So, if you have void MyClass::myMethod(AnotherClass) method,
* the corresponding callback is Callback<MyClass, AnotherClass>.
* You create it similarly to this:
* You can create it in the following way:
* @code
* new Callback<MyClass, AnotherClass>(
* pointerToMyClassObject,
* &MyClass::myMethod
* )
* @endcode
*/
template<class T, typename S = void *> class Callback: public BaseCallback<S> {
protected:
typedef void(T::*TMethod)(S);
T *_object;
TMethod _method;
;
public:
Callback(T *object, TMethod method): _object(object), _method(method) {}
virtual ~Callback() {}
void operator()(S data) { (_object->*_method)(data); }
void operator()(S data) { (_object->*_method)(data); } /*!< Type of the object passed to the operator. */
};
/**
* CallbackBridge<T, OS, S> helps you to chain callbacks.
* CallbackBridge<T, OS, S> allows you to chain callbacks.
*
* CallbackBridge keeps a pointer to BaseCallback<OS>.
* When its operator() is called, it passes this pointer
* along with the actual data (of type <S>) to the method
* of <T> class.
* along with the actual data (of type \<S\>) to the method
* of \<T\> class.
*
* This is needed when you have to call a callback only
* when your own callback is called. So, your callback
@ -119,9 +120,9 @@ public:
* So, if you receive a BaseCallback<SomeClass> callback
* and you want to call it from your MyClass::myMethod method,
* you should create CallbackBridge<MyClass, SomeClass, S>,
* where <S> is data type you want to receive in MyClass::myMethod.
* where \<S\> is the data type you want to receive in MyClass::myMethod.
*
* You create it similarly to this:
* You can create it in the following way:
* new Callback<MyClass, SomeClass, AnotherClass>(
* pointerToMyClassObject,
* &MyClass::myMethod,
@ -139,7 +140,7 @@ public:
CallbackBridge(T *object, TCallbackMethod method, BaseCallback<OS> *outerCallback):
_object(object), _method(method), _outerCallback(outerCallback) {}
virtual ~CallbackBridge() {}
void operator()(S data) { (_object->*_method)(_outerCallback, data); }
void operator()(S data) { (_object->*_method)(_outerCallback, data); } /*!< Type of the object passed to the operator. */
};
/** @} */

83
common/config-manager.h
View File

@ -48,7 +48,7 @@ class SeekableReadStream;
* The (singleton) configuration manager, used to query & set configuration
* values using string keys.
*
* @todo Implement the callback based notification system (outlined below)
* TBD: Implement the callback based notification system (outlined below)
* which sends out notifications to interested parties whenever the value
* of some specific (or any) configuration key changes.
*/
@ -107,55 +107,64 @@ public:
static char const *const kCloudDomain;
#endif
void loadDefaultConfigFile();
void loadConfigFile(const String &filename);
void loadDefaultConfigFile(); /*!< Load the default configuration file. */
void loadConfigFile(const String &filename); /*!< Load a specific configuration file. */
/**
* Retrieve the config domain with the given name.
* @param domName the name of the domain to retrieve
* @return pointer to the domain, or 0 if the domain doesn't exist.
* @param domName Name of the domain to retrieve.
* @return Pointer to the domain, or 0 if the domain does not exist.
*/
Domain * getDomain(const String &domName);
const Domain * getDomain(const String &domName) const;
const Domain * getDomain(const String &domName) const; /*!< @overload */
//
// Generic access methods: No domain specified, use the values from the
// various domains in the order of their priority.
//
/**
* @name Generic access methods
* @brief No domain specified, use the values from the
* various domains in the order of their priority.
* @{
*/
bool hasKey(const String &key) const;
const String & get(const String &key) const;
void set(const String &key, const String &value);
/** @} */
/**
* Update a configuration entry for the active domain and flush
* the configuration file to disk if the value changed
* the configuration file to disk if the value changed.
*/
void setAndFlush(const String &key, const Common::String &value);
#if 1
//
// Domain specific access methods: Acces *one specific* domain and modify it.
// TODO: I'd like to get rid of most of those if possible, or at least reduce
// their usage, by using getDomain as often as possible. For example in the
// options dialog code...
//
/**
* @name Domain-specific access methods
* @brief Access one specific domain and modify it.
*
* TBD: Get rid of most of those if possible, or at least reduce
* their usage, by using getDomain as often as possible. For example in the
* options dialog code.
* @{
*/
bool hasKey(const String &key, const String &domName) const;
const String & get(const String &key, const String &domName) const;
void set(const String &key, const String &value, const String &domName);
void removeKey(const String &key, const String &domName);
/** @} */
#endif
//
// Some additional convenience accessors.
//
int getInt(const String &key, const String &domName = String()) const;
bool getBool(const String &key, const String &domName = String()) const;
void setInt(const String &key, int value, const String &domName = String());
void setBool(const String &key, bool value, const String &domName = String());
/**
* @name Additional convenience accessors
* @{
*/
int getInt(const String &key, const String &domName = String()) const; /*!< Get integer value. */
bool getBool(const String &key, const String &domName = String()) const; /*!< Get Boolean value. */
void setInt(const String &key, int value, const String &domName = String()); /*!< Set integer value. */
void setBool(const String &key, bool value, const String &domName = String()); /*!< Set integer value. */
void registerDefault(const String &key, const String &value);
@ -163,20 +172,20 @@ public:
void registerDefault(const String &key, int value);
void registerDefault(const String &key, bool value);
void flushToDisk();
void flushToDisk(); /*!< Flush configuration to disk. */
void setActiveDomain(const String &domName);
Domain * getActiveDomain() { return _activeDomain; }
const Domain * getActiveDomain() const { return _activeDomain; }
const String & getActiveDomainName() const { return _activeDomainName; }
void setActiveDomain(const String &domName); /*!< Set the given domain as active. */
Domain * getActiveDomain() { return _activeDomain; } /*!< Get the active domain. */
const Domain * getActiveDomain() const { return _activeDomain; } /*!< @overload */
const String & getActiveDomainName() const { return _activeDomainName; } /*!< Get the name of the active domain. */
void addGameDomain(const String &domName);
void removeGameDomain(const String &domName);
void renameGameDomain(const String &oldName, const String &newName);
void addGameDomain(const String &domName); /*!< Add a new game domain. */
void removeGameDomain(const String &domName); /*!< Remove a game domain. */
void renameGameDomain(const String &oldName, const String &newName); /*!< Rename a game domain. */
void addMiscDomain(const String &domName);
void removeMiscDomain(const String &domName);
void renameMiscDomain(const String &oldName, const String &newName);
void addMiscDomain(const String &domName); /*!< Add a miscellaneous domain. */
void removeMiscDomain(const String &domName); /*!< Remove a miscellaneous domain. */
void renameMiscDomain(const String &oldName, const String &newName); /*!< Rename a miscellaneous domain. */
bool hasGameDomain(const String &domName) const;
bool hasMiscDomain(const String &domName) const;
@ -187,7 +196,7 @@ public:
static void defragment(); // move in memory to reduce fragmentation
void copyFrom(ConfigManager &source);
/** @} */
private:
friend class Singleton<SingletonBaseType>;
ConfigManager();

220
common/coroutines.h
View File

@ -60,12 +60,12 @@ struct CoroBaseContext {
const char *_funcName;
#endif
/**
* Creates a coroutine context
* Create a coroutine context.
*/
CoroBaseContext(const char *func);
/**
* Destructor for coroutine context
* Destructor for coroutine context.
*/
virtual ~CoroBaseContext();
};
@ -74,7 +74,7 @@ typedef CoroBaseContext *CoroContext;
/** This is a special constant that can be temporarily used as a parameter to call coroutine-ised
* methods from code that haven't yet been converted to being a coroutine, so code at least
* methods from code that have not yet been converted to being a coroutine, so code at least
* compiles correctly. Be aware, though, that an error will occur if a coroutine that was passed
* the nullContext tries to sleep or yield control.
*/
@ -82,9 +82,9 @@ extern CoroContext nullContext;
/**
* Wrapper class which holds a pointer to a pointer to a CoroBaseContext.
* The interesting part is the destructor, which kills the context being held,
* Note that the destructor kills the context being held,
* but ONLY if the _sleep val of that context is zero. This way, a coroutine
* can just 'return' w/o having to worry about freeing the allocated context
* can just 'return' without freeing the allocated context
* (in Simon Tatham's original code, one had to use a special macro to
* return from a coroutine).
*/
@ -104,30 +104,30 @@ public:
}
};
/** Methods that have been converted to being a coroutine should have this as the first parameter */
/** Set this as the first parameter for methods that have been converted to being a coroutine. */
#define CORO_PARAM Common::CoroContext &coroParam
/**
* Begin the declaration of a coroutine context.
* This allows declaring variables which are 'persistent' during the
* lifetime of the coroutine. An example use would be:
*
* lifetime of the coroutine. Example usage:
* @code
* CORO_BEGIN_CONTEXT;
* int var;
* char *foo;
* CORO_END_CONTEXT(_ctx);
*
* @endcode
* It is not possible to initialize variables here, due to the way this
* macro is implemented. Furthermore, to use the variables declared in
* the coroutine context, you have to access them via the context variable
* name that was specified as parameter to CORO_END_CONTEXT, e.g.
* the coroutine context, you must access them through the context variable
* name that was specified as a parameter to @c CORO_END_CONTEXT, e.g.
* _ctx->var = 0;
*
* @see CORO_END_CONTEXT
*
* @note We declare a variable 'DUMMY' to allow the user to specify an 'empty'
* context, and so compilers won't complain about ";" following the macro.
* @note A 'DUMMY' variable is declared to allow the user to specify an 'empty'
* context, and so that compilers do not complain about ";" following the macro.
*/
#define CORO_BEGIN_CONTEXT \
struct CoroContextTag : Common::CoroBaseContext { \
@ -136,15 +136,14 @@ public:
/**
* End the declaration of a coroutine context.
* @param x name of the coroutine context
* @param x Name of the coroutine context.
* @see CORO_BEGIN_CONTEXT
*/
#define CORO_END_CONTEXT(x) } *x = (CoroContextTag *)coroParam
/**
* Begin the code section of a coroutine.
* @param x name of the coroutine context
* @see CORO_BEGIN_CODE
* @param x Name of the coroutine context.
*/
#define CORO_BEGIN_CODE(x) \
if (&coroParam == &Common::nullContext) assert(!Common::nullContext); \
@ -155,7 +154,6 @@ public:
/**
* End the code section of a coroutine.
* @see CORO_END_CODE
*/
#define CORO_END_CODE \
if (&coroParam == &Common::nullContext) { \
@ -181,9 +179,9 @@ public:
/**
* Stop the currently running coroutine and all calling coroutines.
*
* This sets _sleep to -1 rather than 0 so that the context doesn't get
* deleted by CoroContextHolder, since we want CORO_INVOKE_ARGS to
* propogate the _sleep value and return immediately (the scheduler will
* This sets _sleep to -1 rather than 0 so that the context does not get
* deleted by CoroContextHolder, since we want @ref CORO_INVOKE_ARGS to
* propagate the _sleep value and return immediately (the scheduler will
* then delete the entire coroutine's state, including all subcontexts).
*/
#define CORO_KILL_SELF() \
@ -191,8 +189,8 @@ public:
/**
* This macro is to be used in conjunction with CORO_INVOKE_ARGS and
* similar macros for calling coroutines-enabled subroutines.
* Use this macro in conjunction with @ref CORO_INVOKE_ARGS and
* similar macros for calling coroutine-enabled subroutines.
*/
#define CORO_SUBCTX coroParam->_subctx
@ -206,10 +204,10 @@ public:
* If the subcontext is null, the coroutine ended normally, and we can
* simply break out of the loop and continue execution.
*
* @param subCoro name of the coroutine-enabled function to invoke
* @param ARGS list of arguments to pass to subCoro
* @param subCoro Name of the coroutine-enabled function to invoke.
* @param ARGS List of arguments to pass to subCoro.
*
* @note ARGS must be surrounded by parentheses, and the first argument
* @note @p ARGS must be surrounded by parentheses, and the first argument
* in this list must always be CORO_SUBCTX. For example, the
* regular function call
* myFunc(a, b);
@ -230,9 +228,9 @@ public:
} while (0)
/**
* Invoke another coroutine. Similar to CORO_INVOKE_ARGS,
* Invoke another coroutine. Similar to @ref CORO_INVOKE_ARGS,
* but allows specifying a return value which is returned
* if invoked coroutine yields (thus causing the current
* if the invoked coroutine yields (thus causing the current
* coroutine to yield, too).
*/
#define CORO_INVOKE_ARGS_V(subCoro, RESULT, ARGS) \
@ -249,14 +247,14 @@ public:
} while (0)
/**
* Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine
* Convenience wrapper for @ref CORO_INVOKE_ARGS for invoking a coroutine
* with no parameters.
*/
#define CORO_INVOKE_0(subCoroutine) \
CORO_INVOKE_ARGS(subCoroutine, (CORO_SUBCTX))
/**
* Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine
* Convenience wrapper for @ref CORO_INVOKE_ARGS for invoking a coroutine
* with one parameter.
*/
#define CORO_INVOKE_1(subCoroutine, a0) \
@ -270,7 +268,7 @@ public:
CORO_INVOKE_ARGS(subCoroutine, (CORO_SUBCTX, a0, a1))
/**
* Convenience wrapper for CORO_INVOKE_ARGS for invoking a coroutine
* Convenience wrapper for @ref CORO_INVOKE_ARGS for invoking a coroutine
* with three parameters.
*/
#define CORO_INVOKE_3(subCoroutine, a0,a1,a2) \
@ -285,10 +283,10 @@ public:
// the size of process specific info
/** Size of process-specific information. */
#define CORO_PARAM_SIZE 32
// the maximum number of processes
/** Maximum number of processes. */
#define CORO_NUM_PROCESS 100
#define CORO_MAX_PROCESSES 100
#define CORO_MAX_PID_WAITING 5
@ -296,26 +294,26 @@ public:
#define CORO_INFINITE 0xffffffff
#define CORO_INVALID_PID_VALUE 0
/** Coroutine parameter for methods converted to coroutines */
/** Coroutine parameter for methods converted to coroutines. */
typedef void (*CORO_ADDR)(CoroContext &, const void *);
/** process structure */
struct PROCESS {
PROCESS *pNext; ///< pointer to next process in active or free list
PROCESS *pPrevious; ///< pointer to previous process in active or free list
PROCESS *pNext; ///< Pointer to the next process in an active or free list.
PROCESS *pPrevious; ///< Pointer to the previous process in an active or free list.
CoroContext state; ///< the state of the coroutine
CORO_ADDR coroAddr; ///< the entry point of the coroutine
CoroContext state; ///< State of the coroutine.
CORO_ADDR coroAddr; ///< Entry point of the coroutine.
int sleepTime; ///< number of scheduler cycles to sleep
uint32 pid; ///< process ID
uint32 pidWaiting[CORO_MAX_PID_WAITING]; ///< Process ID(s) process is currently waiting on
char param[CORO_PARAM_SIZE]; ///< process specific info
int sleepTime; ///< Number of scheduler cycles to sleep.
uint32 pid; ///< Process ID.
uint32 pidWaiting[CORO_MAX_PID_WAITING]; ///< Process ID(s) that the process is currently waiting on.
char param[CORO_PARAM_SIZE]; ///< Process-specific information.
};
typedef PROCESS *PPROCESS;
/** Event structure */
/** Event structure. */
struct EVENT {
uint32 pid;
bool manualReset;
@ -325,7 +323,7 @@ struct EVENT {
/**
* Creates and manages "processes" (really coroutines).
* Create and manage "processes" (really coroutines).
*/
class CoroutineScheduler : public Singleton<CoroutineScheduler> {
public:
@ -336,42 +334,42 @@ private:
friend class Singleton<CoroutineScheduler>;
/**
* Constructor
* Constructor.
*/
CoroutineScheduler();
/**
* Destructor
* Destructor.
*/
~CoroutineScheduler();
/** list of all processes */
/** List of all processes. */
PROCESS *processList;
/** active process list - also saves scheduler state */
/** Active process list. Saves scheduler state. */
PROCESS *active;
/** pointer to free process list */
/** Pointer to the free process list. */
PROCESS *pFreeProcesses;
/** the currently active process */
/** Currently active process. */
PROCESS *pCurrent;
/** Auto-incrementing process Id */
/** Auto-incrementing process ID. */
int pidCounter;
/** Event list */
/** Event list. */
Common::List<EVENT *> _events;
#ifdef DEBUG
// diagnostic process counters
/** Diagnostic process counters. */
int numProcs;
int maxProcs;
/**
* Checks both the active and free process list to insure all the links are valid,
* and that no processes have been lost
* Check both the active and free process list to ensure that all links are valid,
* and that no processes have been lost.
*/
void checkStack();
#endif
@ -386,24 +384,24 @@ private:
EVENT *getEvent(uint32 pid);
public:
/**
* Kills all processes and places them on the free list.
* Kill all processes and place them on the free list.
*/
void reset();
#ifdef DEBUG
/**
* Shows the maximum number of process used at once.
* Show the maximum number of processes used at once.
*/
void printStats();
#endif
/**
* Give all active processes a chance to run
* Give all active processes a chance to run.
*/
void schedule();
/**
* Reschedules all the processes to run again this tick
* Reschedule all processes to run again this tick.
*/
void rescheduleAll();
@ -414,151 +412,155 @@ public:
void reschedule(PPROCESS pReSchedProc = nullptr);
/**
* Moves the specified process to the end of the dispatch queue
* Move the specified process to the end of the dispatch queue
* allowing it to run again within the current game cycle.
* @param pGiveProc Which process
* @param pReSchedProc The process to move.
*/
void giveWay(PPROCESS pReSchedProc = nullptr);
/**
* Continously makes a given process wait for another process to finish or event to signal.
* Continously make a given process wait for another process to finish or event to signal.
*
* @param pid Process/Event identifier
* @param duration Duration in milliseconds
* @param expired If specified, set to true if delay period expired
* @param pid Process/Event identifier.
* @param duration Duration in milliseconds.
* @param expired If specified, set to true if the delay period expired.
*/
void waitForSingleObject(CORO_PARAM, int pid, uint32 duration, bool *expired = nullptr);
/**
* Continously makes a given process wait for given prcesses to finished or events to be set
* Continously make a given process wait for given processes to finish or events to be set.
*
* @param nCount Number of Id's being passed
* @param evtList List of pids to wait for
* @param bWaitAll Specifies whether all or any of the processes/events
* @param duration Duration in milliseconds
* @param expired Set to true if delay period expired
* @param nCount Number of IDs being passed.
* @param pidList List of process IDs to wait for.
* @param bWaitAll Whether to wait for all or any of the processes/events.
* @param duration Duration in milliseconds.
* @param expired Set to true if the delay period expired.
*/
void waitForMultipleObjects(CORO_PARAM, int nCount, uint32 *pidList, bool bWaitAll,
uint32 duration, bool *expired = nullptr);
/**
* Make the active process sleep for the given duration in milliseconds
* Make the active process sleep for the given duration in milliseconds.
*
* @param duration Duration in milliseconds
* @remarks This duration won't be precise, since it relies on the frequency the
* scheduler is called.
* @remarks This duration is not precise, since it relies on the frequency the
* scheduler is called.
*/
void sleep(CORO_PARAM, uint32 duration);
/**
* Creates a new process.
* Create a new process.
*
* @param pid process identifier
* @param coroAddr Coroutine start address
* @param pParam Process specific info
* @param sizeParam Size of process specific info
* @param pid Process identifier.
* @param coroAddr Coroutine start address.
* @param pParam Process-specific information.
* @param sizeParam Size of the process-specific information.
*/
PROCESS *createProcess(uint32 pid, CORO_ADDR coroAddr, const void *pParam, int sizeParam);
/**
* Creates a new process with an auto-incrementing Process Id.
* Create a new process with an auto-incrementing Process ID.
*
* @param coroAddr Coroutine start address
* @param pParam Process specific info
* @param sizeParam Size of process specific info
* @param coroAddr Coroutine start address.
* @param pParam Process-specific information.
* @param sizeParam Size of process-specific information.
*/
uint32 createProcess(CORO_ADDR coroAddr, const void *pParam, int sizeParam);
/**
* Creates a new process with an auto-incrementing Process Id, and a single pointer parameter.
* Create a new process with an auto-incrementing Process ID and a single pointer parameter.
*
* @param coroAddr Coroutine start address
* @param pParam Process specific info
* @param coroAddr Coroutine start address.
* @param pParam Process-specific information.
*/
uint32 createProcess(CORO_ADDR coroAddr, const void *pParam);
/**
* Kills the specified process.
* Kill the specified process.
*
* @param pKillProc Which process to kill
* @param pKillProc The process to kill.
*/
void killProcess(PROCESS *pKillProc);
/**
* Returns a pointer to the currently running process.
* Return a pointer to the currently running process.
*/
PROCESS *getCurrentProcess();
/**
* Returns the process identifier of the currently running process.
* Return the process identifier of the currently running process.
*/
int getCurrentPID() const;
/**
* Kills any process matching the specified PID. The current
* Kill any process matching the specified PID. The current
* process cannot be killed.
*
* @param pidKill Process identifier of process to kill
* @param pidMask Mask to apply to process identifiers before comparison
* @return The number of processes killed is returned.
* @param pidKill Process identifier of the process to kill.
* @param pidMask Mask to apply to process identifiers before comparison.
* @return The number of processes killed.
*/
int killMatchingProcess(uint32 pidKill, int pidMask = -1);
/**
* Set pointer to a function to be called by killProcess().
*
* May be called by a resource allocator, the function supplied is
* May be called by a resource allocator. The function supplied is
* called by killProcess() to allow the resource allocator to free
* resources allocated to the dying process.
*
* @param pFunc Function to be called by killProcess()
* @param pFunc Function to be called by killProcess().
*/
void setResourceCallback(VFPTRPP pFunc);
/* Event methods */
/** @name Event methods
* @{
*/
/**
* Creates a new event (semaphore) object
* Create a new event (semaphore) object.
*
* @param bManualReset Events needs to be manually reset. Otherwise,
* events will be automatically reset after a
* process waits on the event finishes
* process waits for the event to finish.
* @param bInitialState Specifies whether the event is signalled or not
* initially
* initially.
*/
uint32 createEvent(bool bManualReset, bool bInitialState);
/**
* Destroys the given event
* @param pidEvent Event Process Id
* Destroy the given event.
* @param pidEvent Event Process ID.
*/
void closeEvent(uint32 pidEvent);
/**
* Sets the event
* @param pidEvent Event Process Id
* Set the event.
* @param pidEvent Event Process ID.
*/
void setEvent(uint32 pidEvent);
/**
* Resets the event
* @param pidEvent Event Process Id
* Reset the event.
* @param pidEvent Event Process ID.
*/
void resetEvent(uint32 pidEvent);
/**
* Temporarily sets a given event to true, and then runs all waiting
* processes,allowing any processes waiting on the event to be fired. It
* Temporarily set a given event to true, and then run all waiting
* processes, allowing any processes waiting on the event to be fired. It
* then immediately resets the event again.
*
* @param pidEvent Event Process Id
* @param pidEvent Event Process ID.
*
* @remarks Should not be run inside of another process
* @remarks Should not be run inside of another process.
*/
void pulseEvent(uint32 pidEvent);
};
/** @} */
/** @} */
} // end of namespace Common
#endif // COMMON_COROUTINES_H

10
common/cosinetables.h
View File

@ -37,15 +37,15 @@ namespace Common {
class CosineTable {
public:
/**
* Construct a cosine table given the number of points
* Construct a cosine table given the number of points.
*
* @param nPoints Number of distinct radian points, which must be in range [16,65536] and be divisible by 4
* @param nPoints Number of distinct radian points that must be in range [16,65536] and be divisible by 4.
*/
CosineTable(int nPoints);
~CosineTable();
/**
* Get pointer to table.
* Get a pointer to a table.
*
* This table contains nPoints/2 entries.
* Prefer to use at()
@ -58,9 +58,9 @@ public:
const float *getTable() { return _tableEOS; }
/**
* Returns cos(2*pi * index / nPoints )
* Return cos(2*pi * index / nPoints )
* Index must be in range [0, nPoints - 1]
* Faster than atLegacy
* Faster than atLegacy.
*/
float at(int index) const;

39
common/dcl.h
View File

@ -20,11 +20,6 @@
*
*/
/**
*
*/
#ifndef COMMON_DCL_H
#define COMMON_DCL_H
@ -36,35 +31,43 @@ namespace Common {
* @defgroup common_dcl Data compression library
* @ingroup common
*
* @brief PKWARE data compression library.
* @brief PKWARE data compression library (DCL).
*
* @details PKWARE DCL ("explode") ("PKWARE data compression library") decompressor used in engines:
* - agos (exclusively for Simon 2 setup.shr file)
* - mohawk
* - neverhood
* - sci
*
* - AGOS (exclusively for Simon 2 setup.shr file)
* - Mohawk
* - Neverhood
* - SCI
* @{
*/
class ReadStream;
class SeekableReadStream;
/**
* Try to decompress a PKWARE DCL (PKWARE data compression library) compressed stream. Returns true if
* successful.
* Decompress a PKWARE DCL compressed stream.
*
* @return Returns true if successful.
*/
bool decompressDCL(ReadStream *sourceStream, byte *dest, uint32 packedSize, uint32 unpackedSize);
/**
* Try to decompress a PKWARE DCL (PKWARE data compression library) compressed stream. Returns a valid pointer
* if successful and 0 otherwise.
* @overload
*
* Decompress a PKWARE DCL compressed stream.
*
* @return Returns a valid pointer if successful or 0 otherwise.
*/
SeekableReadStream *decompressDCL(SeekableReadStream *sourceStream, uint32 packedSize, uint32 unpackedSize);
/**
* Try to decompress a PKWARE DCL (PKWARE data compression library) compressed stream. Returns a valid pointer
* if successful and 0 otherwise. This method is meant for cases, where the unpacked size is not known.
* @overload
*
* Decompress a PKWARE DCL compressed stream.
*
* This method is meant for cases, where the unpacked size is not known.
*
* @return Returns a valid pointer if successful or 0 otherwise.
*/
SeekableReadStream *decompressDCL(SeekableReadStream *sourceStream);

2
common/dct.h
View File

@ -50,7 +50,7 @@ namespace Common {
* (Inverse) Discrete Cosine Transforms.
*
* Used in engines:
* - scumm
* - Scumm
*/
class DCT {
public:

60
common/debug-channels.h
View File

@ -36,10 +36,9 @@ namespace Common {
/**
* @defgroup common_debug_channels Debug channels
* @ingroup common_debug
* @ingroup common
*
* @brief Functions for managing debug channels.
*
* @{
*/
@ -52,68 +51,69 @@ public:
DebugChannel(uint32 c, const String &n, const String &d)
: name(n), description(d), channel(c), enabled(false) {}
String name;
String description;
String name; /*!< Name of the channel */
String description; /*!< Description of the channel */
uint32 channel;
bool enabled;
uint32 channel; /*!< Channel number. */
bool enabled; /*!< Whether the channel is enabled. */
};
/**
* Adds a debug channel.
* Add a debug channel.
*
* A debug channel is considered roughly similar to what our debug levels described by
* A debug channel is considered roughly similar to what the debug levels described by
* gDebugLevel try to achieve:
*
* Debug channels should only affect the display of additional debug output, based on
* their state. That is if they are enabled, channel specific debug messages should
* be shown. If they are disabled on the other hand, those messages will be hidden.
* Debug channels should only affect the display of additional debug output, based on
* their state. That is, if they are enabled, channel-specific debug messages should
* be shown. If they are disabled on the other hand, those messages will be hidden.
*
* @see gDebugLevel.
* @see gDebugLevel
*
* Note that we have debug* functions which depend both on the debug level set and
* Note that we have debug* functions that depend both on the debug level set and
* specific debug channels. Those functions will only show output, when *both* criteria
* are satisfied.
*
* @param channel the channel flag (should be OR-able i.e. first one should be 1 then 2, 4, etc.)
* @param name the option name which is used in the debugger/on the command line to enable
* this special debug level (case will be ignored)
* @param description the description which shows up in the debugger
* @return true on success false on failure
* @param channel Channel flag (should be OR-able i.e. first one should be 1 then 2, 4, etc.).
* @param name The option name that is used in the debugger/on the command line to enable
* this special debug level (case will be ignored).
* @param description The description that shows up in the debugger.
*
* @return True on success, false on failure.
*/
bool addDebugChannel(uint32 channel, const String &name, const String &description);
/**
* Resets all engine specific debug channels.
* Reset all engine-specific debug channels.
*/
void clearAllDebugChannels();
/**
* Enables a debug channel.
* Enable a debug channel.
*
* @param name the name of the debug channel to enable
* @return true on success, false on failure
* @param name Name of the debug channel to enable.
* @return True on success, false on failure.
*/
bool enableDebugChannel(const String &name);
/**
* Enables a debug channel.
* @overload enableDebugChannel(uint32 channel)
*
* @param channel The debug channel
* @return true on success, false on failure
* @param channel Debug channel.
* @return True on success, false on failure.
*/
bool enableDebugChannel(uint32 channel);
/**
* Disables a debug channel.
* Disable a debug channel.
*
* @param name the name of the debug channel to disable
* @return true on success, false on failure
* @param name Name of the debug channel to disable.
* @return True on success, false on failure.
*/
bool disableDebugChannel(const String &name);
/**
* Disables a debug channel.
* @overload bool disableDebugChannel(uint32 channel)
*
* @param channel The debug channel
* @return true on success, false on failure
@ -154,7 +154,7 @@ private:
DebugManager() : gDebugChannelsEnabled(0) {}
};
/** Shortcut for accessing the debug manager. */
/** Shortcut for accessing the Debug Manager. */
#define DebugMan Common::DebugManager::instance()
/** @} */

18
common/debug.h
View File

@ -42,8 +42,7 @@ inline void debugCN(uint32 debugChannels, const char *s, ...) {}
* @defgroup common_debug Debug functions
* @ingroup common
*
* @brief Debug functions.
*
* @brief Functions for printing debug messages.
* @{
*/
@ -118,28 +117,29 @@ void debugCN(uint32 debugChannels, const char *s, ...) GCC_PRINTF(2, 3);
#endif
/**
* Returns true if the debug level is set to the specified level
* Check whether the debug level is set to the specified level.
*/
bool debugLevelSet(int level);
/**
* Returns true if the debug level and channel are active
* 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 level Debug level to check against. If set to -1, only channel check is active.
* @param debugChannels Debug channel to check against.
* @see enableDebugChannel
*/
bool debugChannelSet(int level, uint32 debugChannels);
/**
* The debug level. Initially set to -1, indicating that no debug output
* should be shown. Positive values usually imply an increasing number of
* debug output shall be generated, the higher the value, the more verbose the
* should be shown. Positive values usually imply that an increasing number of
* debug output shall be generated. The higher the value, the more verbose the
* information (although the exact semantics are up to the engines).
*/
extern int gDebugLevel;
/**
* Specify if we want to show only the debug channels and suppress
* Specify whether to show only the debug channels and suppress
* the non-channeled output.
*
* This option is useful when you want to have higher levels of channels
@ -147,7 +147,7 @@ extern int gDebugLevel;
*/
extern bool gDebugChannelsOnly;
//Global constant for EventRecorder debug channel
/** Global constant for EventRecorder debug channel. */
enum GlobalDebugLevels {
kDebugLevelEventRec = 1 << 30
};

14
doc/module.mk Normal file
View File

@ -0,0 +1,14 @@
DOXYGEN_OUTPUT_DIRECTORY := html
export DOXYGEN_OUTPUT_DIRECTORY
doxygen:
@echo "Generating reference documentation in $(srcdir)/doc/doxygen/${DOXYGEN_OUTPUT_DIRECTORY}..."
@cd $(srcdir)/doc/doxygen ; doxygen scummvm.doxyfile
clean-doxygen:
rm -rf $(srcdir)/doc/doxygen/html
rm -f $(srcdir)/doc/doxygen/doxygen_warnings.txt
doc: doxygen
clean-doc: clean-doxygen

8
ports.mk
View File

@ -315,15 +315,15 @@ endif
# Special target to create a static linked binary for Mac OS X.
# We use -force_cpusubtype_ALL to ensure the binary runs on every
# PowerPC machine.
residualvm-static: $(OBJS) $(DETECT_OBJS)
$(CXX) $(LDFLAGS) -force_cpusubtype_ALL -o residualvm-static $(OBJS) $(DETECT_OBJS) \
residualvm-static: $(DETECT_OBJS)
$(CXX) $(LDFLAGS) -force_cpusubtype_ALL -o residualvm-static $(DETECT_OBJS) $(OBJS) \
-framework CoreMIDI \
$(OSX_STATIC_LIBS) \
$(OSX_ZLIB)
# Special target to create a static linked binary for the iPhone (legacy, and iOS 7+)
iphone: $(OBJS)
$(CXX) $(LDFLAGS) -o residualvm $(OBJS) \
iphone: $(DETECT_OBJS) $(OBJS)
$(CXX) $(LDFLAGS) -o residualvm $(DETECT_OBJS) $(OBJS) \
$(OSX_STATIC_LIBS) \
-framework UIKit -framework CoreGraphics -framework OpenGLES \
-framework CoreFoundation -framework QuartzCore -framework Foundation \