[Scummvm-git-logs] scummvm master -> 487b6af09091b837e62302667e549ab3fee0c55b
criezy
criezy at scummvm.org
Thu Nov 12 21:31:46 UTC 2020
This automated email contains information about 2 new commits which have been
pushed to the 'scummvm' repo located at https://github.com/scummvm/scummvm .
Summary:
0575130b35 COMMON: Improve ReadStreamEndian implementation
487b6af090 DOXYGEN: Changes to stream.h and system.h
Commit: 0575130b35edcaa244e5797c3d85ba1e5e3f0e86
https://github.com/scummvm/scummvm/commit/0575130b35edcaa244e5797c3d85ba1e5e3f0e86
Author: Thierry Crozat (criezy at scummvm.org)
Date: 2020-11-12T21:18:44Z
Commit Message:
COMMON: Improve ReadStreamEndian implementation
The commit does not change the behaviour of the class but makes
its implementation more logical, and in line with how it was
originaly implemented (before being refactored in commit 1011508).
Both FROM_BE_* and TO_BE_* do the same thingi for example, but you
use this stream class to read from a BE or LE stream and convert
the values to native endianness, and thus it makes more sense to
use FROM_BE_* and FROM_LE_* instead of TO_BE_* and TO_LE_* (which
suggested that we read values in native endianness and then
convert to the specified endianness).
Changed paths:
common/stream.h
diff --git a/common/stream.h b/common/stream.h
index 1dafd84180..64dbc27fe4 100644
--- a/common/stream.h
+++ b/common/stream.h
@@ -686,19 +686,19 @@ public:
uint16 readUint16() {
uint16 val;
read(&val, 2);
- return (_bigEndian) ? TO_BE_16(val) : TO_LE_16(val);
+ return (_bigEndian) ? FROM_BE_16(val) : FROM_LE_16(val);
}
uint32 readUint32() {
uint32 val;
read(&val, 4);
- return (_bigEndian) ? TO_BE_32(val) : TO_LE_32(val);
+ return (_bigEndian) ? FROM_BE_32(val) : FROM_LE_32(val);
}
uint64 readUint64() {
uint64 val;
read(&val, 8);
- return (_bigEndian) ? TO_BE_64(val) : TO_LE_64(val);
+ return (_bigEndian) ? FROM_BE_64(val) : FROM_LE_64(val);
}
FORCEINLINE int16 readSint16() {
Commit: 487b6af09091b837e62302667e549ab3fee0c55b
https://github.com/scummvm/scummvm/commit/487b6af09091b837e62302667e549ab3fee0c55b
Author: Bartosz Gentkowski (bartosz.gentkowski at nordicsemi.no)
Date: 2020-11-12T21:23:29Z
Commit Message:
DOXYGEN: Changes to stream.h and system.h
Review and improve doxygen comments in stream.h and system.h.
Changed paths:
common/stream.h
common/system.h
diff --git a/common/stream.h b/common/stream.h
index 64dbc27fe4..9c735b4577 100644
--- a/common/stream.h
+++ b/common/stream.h
@@ -49,21 +49,23 @@ public:
virtual ~Stream() {}
/**
- * Returns true if an I/O failure occurred.
+ * Return true if an I/O failure occurred.
+ *
* This flag is never cleared automatically. In order to clear it,
- * client code has to call clearErr() explicitly.
+ * the client code must call clearErr() explicitly.
*
- * @note The semantics of any implementation of this method are
- * supposed to match those of ISO C ferror().
+ * @note The semantics of any implementation of this method is
+ * supposed to match that of ISO C ferror().
*/
virtual bool err() const { return false; }
/**
* Reset the I/O error status as returned by err().
+ *
* For a ReadStream, also reset the end-of-stream status returned by eos().
*
- * @note The semantics of any implementation of this method are
- * supposed to match those of ISO C clearerr().
+ * @note The semantics of any implementation of this method is
+ * supposed to match that of ISO C clearerr().
*/
virtual void clearErr() {}
};
@@ -75,36 +77,39 @@ class WriteStream : virtual public Stream {
public:
/**
* Write data into the stream. Subclasses must implement this
- * method; all other write methods are implemented using it.
+ * method. All other write methods are implemented using it.
*
- * @note The semantics of any implementation of this method are
- * supposed to match those of ISO C fwrite().
+ * @note The semantics of any implementation of this method is
+ * supposed to match that of ISO C fwrite().
*
- * @param dataPtr pointer to the data to be written
- * @param dataSize number of bytes to be written
- * @return the number of bytes which were actually written.
+ * @param dataPtr Pointer to the data to be written.
+ * @param dataSize Number of bytes to be written.
+ *
+ * @return The number of bytes that were actually written.
*/
virtual uint32 write(const void *dataPtr, uint32 dataSize) = 0;
/**
* Commit any buffered data to the underlying channel or
- * storage medium; unbuffered streams can use the default
+ * storage medium. Unbuffered streams can use the default
* implementation.
*
- * @note The semantics of any implementation of this method are
- * supposed to match those of ISO C fflush().
+ * @note The semantics of any implementation of this method is
+ * supposed to match that of ISO C fflush().
*
- * @return true on success, false in case of a failure
+ * @return True on success, false in case of a failure.
*/
virtual bool flush() { return true; }
/**
- * Finalize and close this stream. To be called right before this
- * stream instance is deleted. The goal here is to enable calling
- * code to detect and handle I/O errors which might occur when
- * closing (and this flushing, if buffered) the stream.
+ * Finalize and close this stream.
+ *
+ * Call this method right before this stream instance is deleted.
+ * The goal is to enable the client code to detect
+ * and handle I/O errors that might occur when closing
+ * (and flushing, if buffered) the stream.
*
- * After this method has been called, no further writes may be
+ * After this method has been called, no further writes can be
* performed on the stream. Calling err() is allowed.
*
* By default, this just flushes the stream.
@@ -114,83 +119,115 @@ public:
}
/**
- * Obtains the current value of the stream position indicator of the
- * stream.
+ * Obtain the current value of the stream position indicator.
*
- * @return the current position indicator, or -1 if an error occurred.
+ * @return The current position indicator, or -1 if an error occurred.
*/
virtual int32 pos() const = 0;
-
- // The remaining methods all have default implementations; subclasses
- // need not (and should not) overload them.
-
+ /**
+ * @name Functions for writing data
+ *
+ * The following methods all have default implementations.
+ * Subclasses need not (and should not) overload them.
+ * @{
+ */
+
+ /**
+ * Write the given byte to the current position in the stream.
+ */
void writeByte(byte value) {
write(&value, 1);
}
-
+ /**
+ * Write the given signed byte to the current position in the stream.
+ */
void writeSByte(int8 value) {
write(&value, 1);
}
-
+ /**
+ * Write an unsigned 16-bit word stored in little endian order into the stream.
+ */
void writeUint16LE(uint16 value) {
value = TO_LE_16(value);
write(&value, 2);
}
-
+ /**
+ * Write an unsigned 32-bit word stored in little endian order into the stream.
+ */
void writeUint32LE(uint32 value) {
value = TO_LE_32(value);
write(&value, 4);
}
-
+ /**
+ * Write an unsigned 64-bit word stored in little endian order into the stream.
+ */
void writeUint64LE(uint64 value) {
value = TO_LE_64(value);
write(&value, 8);
}
-
+ /**
+ * Write an unsigned 16-bit word stored in big endian order into the stream.
+ */
void writeUint16BE(uint16 value) {
value = TO_BE_16(value);
write(&value, 2);
}
-
+ /**
+ * Write an unsigned 32-bit word stored in big endian order into the stream.
+ */
void writeUint32BE(uint32 value) {
value = TO_BE_32(value);
write(&value, 4);
}
-
+ /**
+ * Write an unsigned 64-bit word stored in big endian order into the stream.
+ */
void writeUint64BE(uint64 value) {
value = TO_BE_64(value);
write(&value, 8);
}
-
+ /**
+ * Write a signed 16-bit word stored in little endian order into the stream.
+ */
FORCEINLINE void writeSint16LE(int16 value) {
writeUint16LE((uint16)value);
}
-
+ /**
+ * Write a signed 32-bit word stored in little endian order into the stream.
+ */
FORCEINLINE void writeSint32LE(int32 value) {
writeUint32LE((uint32)value);
}
-
+ /**
+ * Write a signed 64-bit word stored in little endian order into the stream.
+ */
FORCEINLINE void writeSint64LE(int64 value) {
writeUint64LE((uint64)value);
}
-
+ /**
+ * Write a signed 16-bit word stored in big endian order into the stream.
+ */
FORCEINLINE void writeSint16BE(int16 value) {
writeUint16BE((uint16)value);
}
-
+ /**
+ * Write a signed 32-bit word stored in big endian order into the stream.
+ */
FORCEINLINE void writeSint32BE(int32 value) {
writeUint32BE((uint32)value);
}
-
+ /**
+ * Write a signed 64-bit word stored in big endian order into the stream.
+ */
FORCEINLINE void writeSint64BE(int64 value) {
writeUint64BE((uint64)value);
}
/**
- * Write the given 32-bit floating point value stored
- * in little endian(LSB first) order into the stream.
+ * Write a 32-bit floating point value
+ * stored in little endian (LSB first) order into the stream.
*/
FORCEINLINE void writeFloatLE(float value) {
uint32 n;
@@ -202,8 +239,8 @@ public:
/**
- * Write the given 32-bit floating point value stored
- * in big endian order into the stream.
+ * Write a 32-bit floating point value
+ * stored in big endian order into the stream.
*/
FORCEINLINE void writeFloatBE(float value) {
uint32 n;
@@ -214,8 +251,8 @@ public:
}
/**
- * Write the given 64-bit floating point value stored
- * in little endian(LSB first) order into the stream.
+ * Write a 64-bit floating point value (with decimals)
+ * stored in little endian (LSB first) order into the stream.
*/
FORCEINLINE void writeDoubleLE(double value) {
uint64 n;
@@ -227,8 +264,8 @@ public:
/**
- * Write the given 64-bit floating point value stored
- * in big endian order into the stream.
+ * Write the given 64-bit floating point value (with decimals)
+ * stored in big endian order into the stream.
*/
FORCEINLINE void writeDoubleBE(double value) {
uint64 n;
@@ -239,10 +276,18 @@ public:
}
/**
- * Write data from another stream to this one.
+ * Write at most @p dataSize of data from another stream into this one,
+ * starting from the current stream position.
+ *
+ * @return The number of bytes written into the stream.
*/
uint32 writeStream(ReadStream *stream, uint32 dataSize);
-
+ /**
+ * Write data from another stream into this one,
+ * starting from its current position to the end of the stream.
+ *
+ * @return The number of bytes written into the stream.
+ */
uint32 writeStream(SeekableReadStream *stream);
/**
@@ -250,35 +295,39 @@ public:
* This writes str.size() characters, but no terminating zero byte.
*/
void writeString(const String &str);
+ /** @} */
};
/**
- * Derived abstract base class for write streams streams that are seekable
+ * Derived abstract base class for write streams that are seekable.
*/
class SeekableWriteStream : public WriteStream {
public:
/**
- * Sets the stream position indicator for the stream. The new position,
- * measured in bytes, is obtained by adding offset bytes to the position
- * specified by whence. If whence is set to SEEK_SET, SEEK_CUR, or
- * SEEK_END, the offset is relative to the start of the file, the current
- * position indicator, or end-of-file, respectively. A successful call
- * to the seek() method clears the end-of-file indicator for the stream.
+ * Set the stream position indicator for the stream.
+ *
+ * The new position, measured in bytes, is obtained by adding offset bytes
+ * to the position specified by whence. If whence is set to SEEK_SET, SEEK_CUR,
+ * or SEEK_END, the offset is relative to the start of the file, the current
+ * position indicator, or end-of-stream, respectively. A successful call
+ * to the seek() method clears the end-of-stream indicator for the stream.
+ *
+ * @note The semantics of any implementation of this method is
+ * supposed to match that of ISO C fseek().
*
- * @note The semantics of any implementation of this method are
- * supposed to match those of ISO C fseek().
+ * @param offset The relative offset in bytes.
+ * @param whence The seek reference: SEEK_SET, SEEK_CUR, or SEEK_END.
*
- * @param offset the relative offset in bytes
- * @param whence the seek reference: SEEK_SET, SEEK_CUR, or SEEK_END
- * @return true on success, false in case of a failure
+ * @return True on success, false in case of a failure.
*/
virtual bool seek(int32 offset, int whence = SEEK_SET) = 0;
/**
- * Obtains the current size of the stream, measured in bytes.
- * If this value is unknown or can not be computed, -1 is returned.
+ * Obtain the current size of the stream, measured in bytes.
*
- * @return the size of the stream, or -1 if an error occurred
+ * If this value is unknown or cannot be computed, -1 is returned.
+ *
+ * @return The size of the stream, or -1 if an error occurred.
*/
virtual int32 size() const = 0;
};
@@ -291,39 +340,48 @@ public:
ReadStream() {}
/**
- * Returns true if a read failed because the stream end has been reached.
+ * Return true if a read failed because the stream end has been reached.
+ *
* This flag is cleared by clearErr().
- * For a SeekableReadStream, it is also cleared by a successful seek.
+ * For a SeekableReadStream, the flag is also cleared by a successful seek.
*
- * @note The semantics of any implementation of this method are
- * supposed to match those of ISO C feof(). In particular, in a stream
+ * @note The semantics of any implementation of this method is
+ * supposed to match that of ISO C feof(). In particular, in a stream
* with N bytes, reading exactly N bytes from the start should *not*
* set eos; only reading *beyond* the available data should set it.
*/
virtual bool eos() const = 0;
/**
- * Read data from the stream. Subclasses must implement this
- * method; all other read methods are implemented using it.
+ * Read data from the stream.
+ *
+ * Subclasses must implement this method.
+ * All other read methods are implemented using it.
*
- * @note The semantics of any implementation of this method are
- * supposed to match those of ISO C fread(), in particular where
+ * @note The semantics of any implementation of this method is
+ * supposed to match that of ISO C fread(), in particular where
* it concerns setting error and end of file/stream flags.
*
- * @param dataPtr pointer to a buffer into which the data is read
- * @param dataSize number of bytes to be read
- * @return the number of bytes which were actually read.
+ * @param dataPtr Pointer to a buffer into which the data is read.
+ * @param dataSize Number of bytes to be read.
+ *
+ * @return The number of bytes that were actually read.
*/
virtual uint32 read(void *dataPtr, uint32 dataSize) = 0;
-
- // The remaining methods all have default implementations; subclasses
- // in general should not overload them.
+ /**
+ * @name Functions for reading data
+ *
+ * The following methods all have default implementations.
+ * Subclasses in general should not overload them.
+ * @{
+ */
/**
* Read an unsigned byte from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
byte readByte() {
@@ -334,8 +392,9 @@ public:
/**
* Read a signed byte from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
FORCEINLINE int8 readSByte() {
@@ -345,8 +404,9 @@ public:
/**
* Read an unsigned 16-bit word stored in little endian (LSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
uint16 readUint16LE() {
@@ -358,8 +418,9 @@ public:
/**
* Read an unsigned 32-bit word stored in little endian (LSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
uint32 readUint32LE() {
@@ -371,8 +432,9 @@ public:
/**
* Read an unsigned 64-bit word stored in little endian (LSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
uint64 readUint64LE() {
@@ -384,8 +446,9 @@ public:
/**
* Read an unsigned 16-bit word stored in big endian (MSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
uint16 readUint16BE() {
@@ -397,8 +460,9 @@ public:
/**
* Read an unsigned 32-bit word stored in big endian (MSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
uint32 readUint32BE() {
@@ -410,8 +474,9 @@ public:
/**
* Read an unsigned 64-bit word stored in big endian (MSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
uint64 readUint64BE() {
@@ -423,8 +488,9 @@ public:
/**
* Read a signed 16-bit word stored in little endian (LSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
FORCEINLINE int16 readSint16LE() {
@@ -434,8 +500,9 @@ public:
/**
* Read a signed 32-bit word stored in little endian (LSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
FORCEINLINE int32 readSint32LE() {
@@ -445,8 +512,9 @@ public:
/**
* Read a signed 64-bit word stored in little endian (LSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
FORCEINLINE int64 readSint64LE() {
@@ -456,8 +524,9 @@ public:
/**
* Read a signed 16-bit word stored in big endian (MSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
FORCEINLINE int16 readSint16BE() {
@@ -467,8 +536,9 @@ public:
/**
* Read a signed 32-bit word stored in big endian (MSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
FORCEINLINE int32 readSint32BE() {
@@ -478,8 +548,9 @@ public:
/**
* Read a signed 64-bit word stored in big endian (MSB first) order
* from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
FORCEINLINE int64 readSint64BE() {
@@ -489,8 +560,9 @@ public:
/**
* Read a 32-bit floating point value stored in little endian (LSB first)
* order from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
FORCEINLINE float readFloatLE() {
@@ -505,8 +577,9 @@ public:
/**
* Read a 32-bit floating point value stored in big endian
* order from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
FORCEINLINE float readFloatBE() {
@@ -522,8 +595,9 @@ public:
/**
* Read a 64-bit floating point value stored in little endian (LSB first)
* order from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
FORCEINLINE double readDoubleLE() {
@@ -538,8 +612,9 @@ public:
/**
* Read a 64-bit floating point value stored in big endian
* order from the stream and return it.
+ *
* Performs no error checking. The return value is undefined
- * if a read error occurred (for which client code can check by
+ * if a read error occurred (for which the client code can check by
* calling err() and eos() ).
*/
FORCEINLINE double readDoubleBE() {
@@ -553,125 +628,137 @@ public:
/**
* Read the specified amount of data into a malloc'ed buffer
- * which then is wrapped into a MemoryReadStream.
- * The returned stream might contain less data than requested,
- * if reading more failed, because of an I/O error or because
- * the end of the stream was reached. Which can be determined by
+ * which is then wrapped into a MemoryReadStream.
+ *
+ * The returned stream might contain less data than requested
+ * if reading more data failed. This is because of an I/O error or because
+ * the end of the stream was reached. It can be determined by
* calling err() and eos().
*/
SeekableReadStream *readStream(uint32 dataSize);
/**
- * Read stream in Pascal format, that is, one byte is
- * string length, followed by string data
+ * Read a string in Pascal format, that is, one byte is
+ * string length, followed by string data.
*
- * @param transformCR if set (default), then transform \r into \n
+ * @param transformCR If set (default), then transform \\r into \\n.
*/
Common::String readPascalString(bool transformCR = true);
-
+ /** @} */
};
-
/**
- * Interface for a seekable & readable data stream.
+ * Interface for a seekable and readable data stream.
*
- * @todo Get rid of SEEK_SET, SEEK_CUR, or SEEK_END, use our own constants
+ * @todo Get rid of SEEK_SET, SEEK_CUR, or SEEK_END, use our own constants.
*/
class SeekableReadStream : virtual public ReadStream {
public:
/**
- * Obtains the current value of the stream position indicator of the
- * stream.
+ * Obtain the current value of the stream position indicator.
*
- * @return the current position indicator, or -1 if an error occurred.
+ * @return The current position indicator, or -1 if an error occurred.
*/
virtual int32 pos() const = 0;
/**
- * Obtains the total size of the stream, measured in bytes.
- * If this value is unknown or can not be computed, -1 is returned.
+ * Obtain the total size of the stream, measured in bytes.
+ * If this value is unknown or cannot be computed, -1 is returned.
*
- * @return the size of the stream, or -1 if an error occurred
+ * @return The size of the stream, or -1 if an error occurred.
*/
virtual int32 size() const = 0;
/**
- * Sets the stream position indicator for the stream. The new position,
- * measured in bytes, is obtained by adding offset bytes to the position
- * specified by whence. If whence is set to SEEK_SET, SEEK_CUR, or
- * SEEK_END, the offset is relative to the start of the file, the current
- * position indicator, or end-of-file, respectively. A successful call
- * to the seek() method clears the end-of-file indicator for the stream.
+ * Set the stream position indicator for the stream.
+ *
+ * The new position, measured in bytes, is obtained by adding offset bytes
+ * to the position specified by whence. If whence is set to SEEK_SET, SEEK_CUR,
+ * or SEEK_END, the offset is relative to the start of the file, the current
+ * position indicator, or end-of-stream, respectively. A successful call
+ * to the seek() method clears the end-of-stream indicator for the stream.
*
- * @note The semantics of any implementation of this method are
- * supposed to match those of ISO C fseek().
+ * @note The semantics of any implementation of this method is
+ * supposed to match that of ISO C fseek().
*
- * @param offset the relative offset in bytes
- * @param whence the seek reference: SEEK_SET, SEEK_CUR, or SEEK_END
- * @return true on success, false in case of a failure
+ * @param offset Relative offset in bytes.
+ * @param whence Seek reference: SEEK_SET, SEEK_CUR, or SEEK_END.
+ *
+ * @return True on success, false in case of a failure.
*/
virtual bool seek(int32 offset, int whence = SEEK_SET) = 0;
/**
- * TODO: Get rid of this??? Or keep it and document it
- * @return true on success, false in case of a failure
+ * Skip the given number of bytes in the stream.
+ *
+ * This is equivalent to calling:
+ * @code
+ * seek(offset, SEEK_CUR)
+ * @endcode
+ * to add the given number of bytes to the current position indicator of the stream.
+ *
+ * @return True on success, false in case of a failure.
*/
virtual bool skip(uint32 offset) { return seek(offset, SEEK_CUR); }
/**
- * Reads at most one less than the number of characters specified
- * by bufSize from the and stores them in the string buf. Reading
- * stops when the end of a line is reached (CR, CR/LF or LF), and
- * at end-of-file or error. The newline, if any, is retained (CR
- * and CR/LF are translated to LF = 0xA = '\n'). If any characters
- * are read and there is no error, a `\0' character is appended
+ * Read at most one less than the number of characters specified
+ * by @p bufSize from the stream and store them in the string buffer.
+ *
+ * Reading stops when the end of a line is reached (CR, CR/LF, or LF),
+ * and at end-of-stream or error. The newline, if any, is retained (CR
+ * and CR/LF are translated to ``LF = 0xA = '\n'``). If any characters
+ * are read and there is no error, a `\0` character is appended
* to end the string.
*
* Upon successful completion, return a pointer to the string. If
- * end-of-file occurs before any characters are read, returns NULL
- * and the buffer contents remain unchanged. If an error occurs,
+ * end-of-stream occurs before any characters are read, returns NULL
+ * and the buffer contents remain unchanged. If an error occurs,
* returns NULL and the buffer contents are indeterminate.
- * This method does not distinguish between end-of-file and error;
+ * This method does not distinguish between end-of-stream and error;
* callers must use err() or eos() to determine which occurred.
*
- * @note This methods is closely modeled after the standard fgets()
+ * @note This method is closely modeled after the standard fgets()
* function from stdio.h.
*
- * @param s the buffer to store into
- * @param bufSize the size of the buffer
- * @param handleCR if set (default), then CR and CR/LF are handled as well as LF
- * @return a pointer to the read string, or NULL if an error occurred
+ * @param s The buffer to store into.
+ * @param bufSize Size of the buffer.
+ * @param handleCR If set (default), then CR and CR/LF are handled, as well as LF.
+ *
+ * @return Pointer to the read string, or NULL if an error occurred.
*/
virtual char *readLine(char *s, size_t bufSize, bool handleCR = true);
/**
- * Reads a full line and returns it as a Common::String. Reading
- * stops when the end of a line is reached (CR, CR/LF or LF), and
- * at end-of-file or error.
+ * Read a full line and returns it as a Common::String.
+ *
+ * Reading stops when the end of a line is reached (CR, CR/LF, or LF),
+ * and at end-of-stream or error.
*
* Upon successful completion, return a string with the content
* of the line, *without* the end of a line marker. This method
* does not indicate whether an error occurred. Callers must use
* err() or eos() to determine whether an exception occurred.
*
- * @param handleCR if set (default), then CR and CR/LF are handled as well as LF
+ * @param handleCR If set (default), then CR and CR/LF are handled, as well as LF.
*/
virtual String readLine(bool handleCR = true);
/**
* Print a hexdump of the stream while maintaing position. The number
* of bytes per line is customizable.
- * @param len the length of that data
- * @param bytesPerLine number of bytes to print per line (default: 16)
- * @param startOffset shift the shown offsets by the starting offset (default: 0)
+ *
+ * @param len Length of this data.
+ * @param bytesPerLine Number of bytes to print per line (default: 16).
+ * @param startOffset Shift the shown offsets by the starting offset (default: 0).
*/
void hexdump(int len, int bytesPerLine = 16, int startOffset = 0);
};
/**
- * This is a ReadStream mixin subclass which adds non-endian read
+ * ReadStream mixin subclass that adds non-endian read
* methods whose endianness is set during the stream creation.
*/
class ReadStreamEndian : virtual public ReadStream {
@@ -679,47 +766,79 @@ private:
const bool _bigEndian;
public:
+ /**
+ * Set the endianness of the read stream.
+ *
+ * @param bigEndian If true, create a big endian stream.
+ * If false, create a little endian stream.
+ */
ReadStreamEndian(bool bigEndian) : _bigEndian(bigEndian) {}
-
+ /**
+ * Return true if data is encoded in big endian order.
+ */
bool isBE() const { return _bigEndian; }
-
+ /**
+ * Read an unsigned 16-bit word using the stream endianness
+ * and return it in native endianness.
+ */
uint16 readUint16() {
uint16 val;
read(&val, 2);
return (_bigEndian) ? FROM_BE_16(val) : FROM_LE_16(val);
}
-
+ /**
+ * Read an unsigned 32-bit word using the stream endianness
+ * and return it in native endianness.
+ */
uint32 readUint32() {
uint32 val;
read(&val, 4);
return (_bigEndian) ? FROM_BE_32(val) : FROM_LE_32(val);
}
-
+ /**
+ * Read an unsigned 64-bit word using the stream endianness
+ * and return it in native endianness.
+ */
uint64 readUint64() {
uint64 val;
read(&val, 8);
return (_bigEndian) ? FROM_BE_64(val) : FROM_LE_64(val);
}
-
+ /**
+ * Read a signed 16-bit word using the stream endianness
+ * and return it in native endianness.
+ */
FORCEINLINE int16 readSint16() {
return (int16)readUint16();
}
-
+ /**
+ * Read a signed 32-bit word using the stream endianness
+ * and return it in native endianness.
+ */
FORCEINLINE int32 readSint32() {
return (int32)readUint32();
}
-
+ /**
+ * Read a signed 64-bit word using the stream endianness
+ * and return it in native endianness.
+ */
FORCEINLINE int64 readSint64() {
return (int64)readUint64();
}
};
/**
- * This is a SeekableReadStream subclass which adds non-endian read
+ * SeekableReadStream subclass that adds non-endian read
* methods whose endianness is set during the stream creation.
*/
class SeekableReadStreamEndian : virtual public SeekableReadStream, virtual public ReadStreamEndian {
public:
+ /**
+ * Set the endianness of the read stream.
+ *
+ * @param bigEndian If true, create a big endian stream.
+ * If false, create a little endian stream.
+ */
SeekableReadStreamEndian(bool bigEndian) : ReadStreamEndian(bigEndian) {}
};
diff --git a/common/system.h b/common/system.h
index 8181116f18..8793222684 100644
--- a/common/system.h
+++ b/common/system.h
@@ -70,10 +70,10 @@ typedef Array<Keymap *> KeymapArray;
}
/**
- * @defgroup common_system System
+ * @defgroup common_system OSystem
* @ingroup common
*
- * @brief Operating system related API.
+ * @brief API related to OSystem - the main interface for ScummVM backends.
*
* @{
*/
@@ -83,44 +83,56 @@ class FilesystemFactory;
class PaletteManager;
/**
- * A structure describing time and date. This is a clone of struct tm
- * from time.h. We roll our own since not all systems provide time.h.
- * We also do not imitate all files of struct tm, only those we
- * actually need.
+ * Structure describing time and date.
*
- * @note For now, the members are named exactly as in struct tm to ease
+ * This is a clone of struct @c tm from time.h.
+ * We implement our own since not all systems provide time.h.
+ * This is not a one-to-one replacement of the @c tm struct,
+ * as only the fields that we need were added.
+ *
+ * @note For now, the members are named exactly as in struct @c tm to ease
* the transition.
*/
struct TimeDate {
- int tm_sec; ///< seconds (0 - 60)
- int tm_min; ///< minutes (0 - 59)
- int tm_hour; ///< hours (0 - 23)
- int tm_mday; ///< day of month (1 - 31)
- int tm_mon; ///< month of year (0 - 11)
- int tm_year; ///< year - 1900
- int tm_wday; ///< days since Sunday (0 - 6)
+ int tm_sec; /**< Seconds (0 - 60). */
+ int tm_min; /**< Minutes (0 - 59). */
+ int tm_hour; /**< Hours (0 - 23). */
+ int tm_mday; /**< Day of month (1 - 31). */
+ int tm_mon; /**< Month of year (0 - 11). */
+ int tm_year; /**< Year - 1900. */
+ int tm_wday; /**< Days since Sunday (0 - 6). */
};
namespace LogMessageType {
-
+/**
+ * Enumeration for log message types.
+ * @ingroup common_system
+ *
+ */
enum Type {
- kInfo,
- kError,
- kWarning,
- kDebug
+ kInfo, /**< Info logs. */
+ kError, /**< Error logs. */
+ kWarning, /**< Warning logs. */
+ kDebug /**< Debug logs. */
};
} // End of namespace LogMessageType
/**
- * Interface for ScummVM backends. If you want to port ScummVM to a system
- * which is not currently covered by any of our backends, this is the place
- * to start. ScummVM will create an instance of a subclass of this interface
+ * Interface for ScummVM backends.
+ *
+ * If you want to port ScummVM to a system that is not currently
+ * covered by any of our backends, this is the place to start.
+ * ScummVM will create an instance of a subclass of this interface
* and use it to interact with the system.
*
- * In particular, a backend provides a video surface for ScummVM to draw in;
- * methods to create timers, to handle user input events,
- * control audio CD playback, and sound output.
+ * In particular, a backend provides:
+ *
+ * - A video surface for ScummVM to draw in
+ * - Methods to create timers
+ * - Methods to handle user input events
+ * - Control audio CD playback
+ * - Sound output
*/
class OSystem : Common::NonCopyable {
friend class Common::Encoding;
@@ -130,24 +142,25 @@ protected:
protected:
/**
- * @name Module slots
+ * @defgroup common_system_module Subsystem modules
+ * @ingroup common_system
+ * @{
*
- * For backend authors only, the following pointers (= "slots) to various
+ * For backend authors only, the following pointers (= "slots") to various
* subsystem managers / factories / etc. can and should be set to
* a suitable instance of the respective type.
*
* For some of the slots, a default instance is set if your backend
- * does not do so. For details, please look at the documentation of
+ * does not do so. For details, refer to the documentation of
* each slot.
*
- * A backend may setup slot values in its initBackend() method,
- * its constructor or somewhere in between. But it must a slot's value
+ * A backend may set up slot values in its initBackend() method,
+ * its constructor, or somewhere in between. But it must set a slot's value
* no later than in its initBackend() implementation, because
* OSystem::initBackend() will create any default instances if
- * none has been set yet (and for other slots, will verify that
+ * none have been set yet (and for other slots, will verify that
* one has been set; if not, an error may be generated).
*/
- //@{
/**
* No default value is provided for _audiocdManager by OSystem.
@@ -234,10 +247,11 @@ protected:
*/
Common::U32String _clipboard;
- // WORKAROUND. The 014bef9eab9fb409cfb3ec66830e033e4aaa29a9 triggered a bug
- // in the osx_intel toolchain. Adding this variable fixes it.
+ /** Workaround for a bug in the osx_intel toolchain introduced by
+ * 014bef9eab9fb409cfb3ec66830e033e4aaa29a9. Adding this variable fixes it.
+ */
bool _dummyUnused;
-
+ /** @} */
private:
/**
* Indicate if initBackend() has been called.
@@ -249,19 +263,18 @@ private:
public:
/**
- *
* Destoy this OSystem instance.
*/
void destroy();
/**
- * The following method should be called once, after g_system is created.
+ * Call this method once, after g_system is created.
*/
virtual void init() {}
/**
* The following method is called once, from main.cpp, after all
- * config data (including command line params etc.) are fully loaded.
+ * config data (including command line params etc.) is fully loaded.
*
* @note Subclasses should always invoke the implementation of their
* parent class. They should do so near the end of their own
@@ -271,40 +284,53 @@ public:
/**
* Return false if initBackend() has not yet been called and true otherwise.
+ *
* Some functionalities such as mutexes cannot be used until the backend
* is initialized.
*/
bool backendInitialized() const { return _backendInitialized; }
/**
- * Allows the backend to perform engine specific init.
+ * Allow the backend to perform engine-specific initialization.
+ *
* Called just before the engine is run.
*/
virtual void engineInit() { }
/**
- * Allows the backend to perform engine specific de-init.
+ * Allow the backend to perform engine-specific deinitialization.
+ *
* Called after the engine finishes.
*/
virtual void engineDone() { }
- /** @name Feature flags */
- //@{
+ /**
+ * @defgroup common_system_flags Feature flags
+ * @ingroup common_system
+ * @{
+ */
/**
* A feature in this context means an ability of the backend which can be
- * either on or off. Examples include:
- * - fullscreen mode
- * - aspect ration correction
- * - a virtual keyboard for text entry (on PDAs)
+ * either on or off.
*
- * One has to distinguish between the *availability* of a feature,
- * which can be checked using hasFeature(), and its *state*.
+ * Examples include:
+ * - Fullscreen mode
+ * - Aspect ration correction
+ * - Virtual keyboard for text entry (on PDAs)
+ *
+ * There is a difference between the *availability* of a feature
+ * that can be checked using hasFeature(), and its *state*.
* For example, the SDL backend *has* the kFeatureFullscreenMode,
* so hasFeature returns true for it. On the other hand,
- * fullscreen mode may be active or not; this can be determined
- * by checking the state via getFeatureState(). Finally, to
+ * fullscreen mode may be active or not. This can be determined
+ * by checking the state using getFeatureState(). Finally, to
* switch between fullscreen and windowed mode, use setFeatureState().
+ *
+ * Some features, for example kFeatureClipboardSupport and kFeatureOpenUrl
+ * have no state and can only be used to check if the corresponding feature
+ * is available or not. Calling getFeatureState() or setFeatureState()
+ * for them is pointless.
*/
enum Feature {
/**
@@ -314,22 +340,25 @@ public:
kFeatureFullscreenMode,
/**
- * Control aspect ratio correction. Aspect ratio correction is used to
- * correct games running at 320x200 (i.e with an aspect ratio of 8:5),
- * but which on their original hardware were displayed with the
- * standard 4:3 ratio (that is, the original graphics used non-square
- * pixels). When the backend support this, then games running at
- * 320x200 pixels should be scaled up to 320x240 pixels. For all other
- * resolutions, ignore this feature flag.
- * @note Backend implementors can find utility functions in common/scaler.h
- * which can be used to implement aspect ratio correction. In
- * stretch200To240() can stretch a rect, including (very fast)
+ * Control aspect ratio correction.
+ *
+ * Aspect ratio correction is used for correcting games running at 320x200
+ * (i.e with an aspect ratio of 8:5), but which on their original hardware
+ * were displayed with the standard 4:3 ratio
+ * (which means that the original graphics used non-square pixels).
+ * When the backend supports this, then games running at
+ * 320x200 pixels should be scaled up to 320x240 pixels.
+ * For all other resolutions, ignore this feature flag.
+ *
+ * @note Backend implementors can find utility functions in common/scaler.h.
+ * These functions can be used to implement aspect ratio correction.
+ * You can use stretch200To240() can stretch a rect, including (very fast)
* particular, interpolation, and works in-place.
*/
kFeatureAspectRatioCorrection,
/**
- * If supported this flag can be used to switch between unfiltered and
+ * If supported, this flag can be used to switch between unfiltered and
* filtered graphics modes.
*/
kFeatureFilteringMode,
@@ -341,7 +370,7 @@ public:
/**
* Determine whether a virtual keyboard is to be shown or not.
- * This would mostly be implemented by backends for hand held devices,
+ * This would mostly be implemented by backends for handheld devices,
* like PocketPC, Palms, Symbian phones like the P800, Zaurus, etc.
*/
kFeatureVirtualKeyboard,
@@ -349,7 +378,7 @@ public:
/**
* Backends supporting this feature allow specifying a custom palette
* for the cursor. The custom palette is used if the feature state
- * is set to true by the client code via setFeatureState().
+ * is set to true by the client code using setFeatureState().
*
* It is currently used only by some Macintosh versions of Humongous
* Entertainment games. If the backend doesn't implement this feature
@@ -359,7 +388,7 @@ public:
kFeatureCursorPalette,
/**
- * A backend have this feature if its overlay pixel format has an alpha
+ * A backend has this feature if its overlay pixel format has an alpha
* channel which offers at least 3-4 bits of accuracy (as opposed to
* just a single alpha bit).
*
@@ -374,7 +403,7 @@ public:
kFeatureIconifyWindow,
/**
- * This feature flag can be used to check if hardware accelerated
+ * This feature flag can be used to check if hardware-accelerated
* OpenGL is supported and can be used for 3D game rendering.
*/
kFeatureOpenGLForGame,
@@ -390,10 +419,10 @@ public:
* When a backend supports this feature, it guarantees the graphics
* context is not destroyed when switching to and from fullscreen.
*
- * For OpenGL that means the context is kept with all of its content:
- * texture, programs...
+ * For OpenGL, that means the context is kept with all of its content:
+ * texture, programs, etc.
*
- * For TinyGL that means the backbuffer surface is kept.
+ * For TinyGL, that means the backbuffer surface is kept.
*/
kFeatureFullscreenToggleKeepsContext,
@@ -407,8 +436,10 @@ public:
/**
* The presence of this feature indicates whether the system clipboard is
- * available. If this feature is not present, the hasTextInClipboard(),
- * getTextFromClipboard() and setTextInClipboard() calls can still be used,
+ * available.
+ *
+ * If this feature is not present, the hasTextInClipboard(),
+ * getTextFromClipboard(), and setTextInClipboard() calls can still be used,
* however it should not be used in scenarios where the user is expected to
* copy data outside of the application.
*
@@ -425,46 +456,45 @@ public:
kFeatureOpenUrl,
/**
- * show on-screen control
+ * Show on-screen control.
*/
kFeatureOnScreenControl,
/**
- * mouse emulation mode
+ * Mouse emulation mode.
*/
kFeatureTouchpadMode,
/**
- * swap menu and back buttons
+ * Swap menu and back buttons.
*/
kFeatureSwapMenuAndBackButtons,
/**
- * keyboard mouse and joystick mouse speed
+ * Keyboard mouse and joystick mouse speed.
*/
kFeatureKbdMouseSpeed,
/**
- * change analog joystick deadzone
+ * Change analog joystick deadzone.
*/
kFeatureJoystickDeadzone,
/**
- * shaders
+ * Shaders.
*/
kFeatureShader,
/**
- * Supports for using the native system file browser dialog
+ * Support for using the native system file browser dialog
* through the DialogManager.
*/
kFeatureSystemBrowserDialog,
/**
- * For platforms that should not have a Quit button
+ * For platforms that should not have a Quit button.
*/
kFeatureNoQuit
-
};
/**
@@ -473,33 +503,37 @@ public:
virtual bool hasFeature(Feature f) { return false; }
/**
- * En-/disable the specified feature. For example, this may be used to
- * enable fullscreen mode, or to deactivate aspect correction, etc.
+ * Enable or disable the specified feature.
+ *
+ * For example, this may be used to enable fullscreen mode
+ * or to deactivate aspect correction, etc.
*/
virtual void setFeatureState(Feature f, bool enable) {}
/**
- * Query the state of the specified feature. For example, test whether
- * fullscreen mode is active or not.
+ * Query the state of the specified feature.
+ *
+ * For example, test whether fullscreen mode is active or not.
*/
virtual bool getFeatureState(Feature f) { return false; }
- //@}
+ /** @} */
/**
- * @name Graphics
+ * @defgroup common_system_graphics Graphics
+ * @ingroup common_system
+ * @{
*
- * The way graphics work in the class OSystem are meant to make
- * it possible for game frontends to implement all they need in
+ * The way graphics work in the OSystem class is meant to make
+ * it possible for game frontends to implement everything they need in
* an efficient manner. The downside of this is that it may be
* rather complicated for backend authors to fully understand and
* implement the semantics of the OSystem interface.
*
- *
* The graphics visible to the user in the end are actually
- * composed in three layers: the game graphics, the overlay
+ * composed of three layers: the game graphics, the overlay
* graphics, and the mouse.
*
* First, there are the game graphics. The methods in this section
@@ -510,81 +544,83 @@ public:
* the game graphics.
*
* Before the user sees these graphics, the backend may apply some
- * transformations to it; for example, the may be scaled to better
- * fit on the visible screen; or aspect ratio correction may be
+ * transformations to it. For example, they may be scaled to better
+ * fit the visible screen or aspect ratio correction may be
* performed (see kFeatureAspectRatioCorrection). As a result of
* this, a pixel of the game graphics may occupy a region bigger
- * than a single pixel on the screen. We define p_w and p_h to be
- * the width resp. height of a game pixel on the screen.
+ * than a single pixel on the screen. p_w and p_h are defined to be
+ * the width and, respectively, height of a game pixel on the screen.
*
* In addition, there is a vertical "shake offset" (as defined by
- * setShakePos) which is used in some games to provide a shaking
+ * setShakePos) that is used in some games to provide a shaking
* effect. Note that shaking is applied to all three layers, i.e.
- * also to the overlay and the mouse. We denote the shake offset
+ * also to the overlay and the mouse. The shake offset is denoted
* by S.
*
* Putting this together, a pixel (x,y) of the game graphics is
* transformed to a rectangle of height p_h and width p_w
* appearing at position (p_w * x, p_hw * (y + S)) on the real
- * screen (in addition, a backend may choose to offset
- * everything, e.g. to center the graphics on the screen).
- *
+ * screen. In addition, a backend may choose to offset
+ * everything, e.g. to center the graphics on the screen.
*
* The next layer is the overlay. It is composed over the game
- * graphics. Historically the overlay size had always been a
- * multiple of the game resolution, for example when the game
+ * graphics. Historically, the overlay size had always been a
+ * multiple of the game resolution. For example, if the game
* resolution was 320x200 and the user selected a 2x scaler and did
- * not enable aspect ratio correction it had a size of 640x400.
+ * not enable aspect ratio correction, it had a size of 640x400.
* An exception was the aspect ratio correction, which did allow
* for non multiples of the vertical resolution of the game screen.
- * Nowadays the overlay size does not need to have any relation to
+ * Currently, the overlay size does not need to have any relation to
* the game resolution though, for example the overlay resolution
* might be the same as the physical screen resolution.
- * The overlay is forced to a 16bpp mode right now.
+ * The overlay is forced to a 16 bpp mode right now.
*
- * Finally, there is the mouse layer. This layer doesn't have to
+ * Finally, there is the mouse layer. This layer does not have to
* actually exist within the backend -- it all depends on how a
- * backend chooses to implement mouse cursors, but in the default
+ * backend chooses to implement mouse cursors. However, in the default
* SDL backend, it really is a separate layer. The mouse can
* have a palette of its own, if the backend supports it.
*
- * On a note for OSystem users here. We do not require our graphics
- * to be thread safe and in fact most/all backends using OpenGL are
- * not. So do *not* try to call any of these functions from a timer
- * and/or audio callback (like readBuffer of AudioStreams).
+ * Graphics do not need to be thread-safe and in fact most/all backends
+ * using OpenGL are not. So do *not* try to call any of these functions
+ * from a timer and/or audio callback (like readBuffer of AudioStreams).
*/
- //@{
/**
* Description of a graphics mode.
*/
struct GraphicsMode {
/**
- * The 'name' of the graphics mode. This name is matched when selecting
- * a mode via the command line, or via the config file.
- * Examples: "1x", "advmame2x", "hq3x"
+ * The name of the graphics mode.
+ *
+ * This name is matched when selecting a mode using the command line
+ * or using the config file. Examples: "1x", "advmame2x", "hq3x".
*/
const char *name;
/**
- * Human readable description of the scaler.
- * Examples: "Normal (no scaling)", "AdvMAME2x", "HQ3x"
+ * Human-readable description of the scaler.
+ *
+ * Examples: "Normal (no scaling)", "AdvMAME2x", "HQ3x".
*/
const char *description;
/**
- * ID of the graphics mode. How to use this is completely up to the
- * backend. This value will be passed to the setGraphicsMode(int)
- * method by client code.
+ * ID of the graphics mode.
+ *
+ * How to use this is entirely up to the backend. This value is passed
+ * to the setGraphicsMode(int) method by the client code.
*/
int id;
};
/**
* Retrieve a list of all graphics modes supported by this backend.
- * This can be both video modes as well as graphic filters/scalers;
- * it is completely up to the backend maintainer to decide what is
+ *
+ * This can be both video modes as well as graphic filters/scalers.
+ * It is completely up to the backend maintainer to decide what is
* appropriate here and what not.
* The list is terminated by an all-zero entry.
- * @return a list of supported graphics modes
+ *
+ * @return List of supported graphics modes.
*/
virtual const GraphicsMode *getSupportedGraphicsModes() const {
static const GraphicsMode noGraphicsModes[] = {{"NONE", "Normal", 0}, {nullptr, nullptr, 0 }};
@@ -594,38 +630,43 @@ public:
/**
* Return the ID of the 'default' graphics mode. What exactly this means
* is up to the backend. This mode is set by the client code when no user
- * overrides are present (i.e. if no custom graphics mode is selected via
+ * overrides are present (i.e. if no custom graphics mode is selected using
* the command line or a config file).
*
- * @return the ID of the 'default' graphics mode
+ * @return ID of the 'default' graphics mode.
*/
virtual int getDefaultGraphicsMode() const { return 0; }
enum GfxModeFlags {
- kGfxModeNoFlags = 0, /**< No Flags */
- kGfxModeRender3d = (1 << 0) /**< Indicate 3d h/w accelerated in game gfx */
+ kGfxModeNoFlags = 0, /**< No flags. */
+ kGfxModeRender3d = (1 << 0) /**< Indicate 3D hardware-accelerated in-game GFX. */
};
/**
- * Switch to the specified graphics mode. If switching to the new mode
- * failed, this method returns false.
+ * Switch to the specified graphics mode.
+ *
+ * If switching to the new mode fails, this method returns false.
+ *
+ * The flag 'kGfxModeRender3d' is optional. It allows to switch to 3D-only rendering mode.
+ * In this mode, the game engine is allowed to use OpenGL(ES) directly.
*
- * The flag 'kGfxModeRender3d' is optional. It allow to switch to 3D only rendering mode.
- * Game engine is allowed to use OpenGL(ES) direclty.
+ * @param mode ID of the new graphics mode.
+ * @param flags Flags for the new graphics mode.
*
- * @param mode the ID of the new graphics mode
- * @param flags the flags for new graphics mode
- * @return true if the switch was successful, false otherwise
+ * @return True if the switch was successful, false otherwise.
*/
virtual bool setGraphicsMode(int mode, uint flags = kGfxModeNoFlags) { return (mode == 0); }
/**
- * Switch to the graphics mode with the given name. If 'name' is unknown,
- * or if switching to the new mode failed, this method returns false.
+ * Switch to the graphics mode with the given name.
+ *
+ * If @p name is unknown, or if switching to the new mode fails, this method returns false.
+ *
+ * @param name Name of the new graphics mode.
+ *
+ * @return True if the switch was successful, false otherwise.
*
- * @param name the name of the new graphics mode
- * @return true if the switch was successful, false otherwise
- * @note This is implemented via the setGraphicsMode(int) method, as well
+ * @note This is implemented using the setGraphicsMode(int) method, as well
* as getSupportedGraphicsModes() and getDefaultGraphicsMode().
* In particular, backends do not have to overload this!
*/
@@ -633,28 +674,33 @@ public:
/**
* Determine which graphics mode is currently active.
- * @return the ID of the active graphics mode
+ *
+ * @return ID of the active graphics mode.
*/
virtual int getGraphicsMode() const { return 0; }
#ifdef USE_RGB_COLOR
/**
* Determine the pixel format currently in use for screen rendering.
+ *
* @return the active screen pixel format.
+ *
* @see Graphics::PixelFormat
*/
virtual Graphics::PixelFormat getScreenFormat() const = 0;
/**
- * Returns a list of all pixel formats supported by the backend.
- * The first item in the list must be directly supported by hardware,
+ * Return a list of all pixel formats supported by the backend.
+ *
+ * The first item in the list must be directly supported by hardware
* and provide the largest color space of those formats with direct
* hardware support. It is also strongly recommended that remaining
- * formats should be placed in order of descending preference for the
+ * formats are placed in the order of descending preference for the
* backend to use.
*
- * EG: a backend that supports 32-bit ABGR and 16-bit 555 BGR in hardware
+ * Example: a backend that supports 32-bit ABGR and 16-bit 555 BGR in hardware
* and provides conversion from equivalent RGB(A) modes should order its list
+ * in the following way:
* 1) Graphics::PixelFormat(4, 0, 0, 0, 0, 0, 8, 16, 24)
* 2) Graphics::PixelFormat(2, 3, 3, 3, 8, 0, 5, 10, 0)
* 3) Graphics::PixelFormat(4, 0, 0, 0, 0, 24, 16, 8, 0)
@@ -680,10 +726,10 @@ public:
#endif
/**
- * Retrieve a list of supported levels of anti-aliasting.
- * Anti-aliasing only works when using one of the hardware
- * accelerated renderers. An empty list means anti-aliasing
- * is not supported.
+ * Retrieve a list of supported levels of anti-aliasing.
+ *
+ * Anti-aliasing only works when using one of the hardware-accelerated
+ * renderers. An empty list means anti-aliasing is not supported.
*/
virtual Common::Array<uint> getSupportedAntiAliasingLevels() const {
return Common::Array<uint>();
@@ -691,11 +737,13 @@ public:
/**
* Retrieve a list of all hardware shaders supported by this backend.
+ *
* This can be only hardware shaders.
- * it is completely up to the backend maintainer to decide what is
+ * It is completely up to the backend maintainer to decide what is
* appropriate here and what not.
* The list is terminated by an all-zero entry.
- * @return a list of supported shaders
+ *
+ * @return List of supported shaders.
*/
virtual const GraphicsMode *getSupportedShaders() const {
static const OSystem::GraphicsMode no_shader[2] = {{"NONE", "Normal (no shader)", 0}, {nullptr, nullptr, 0}};
@@ -703,31 +751,39 @@ public:
}
/**
- * Return the ID of the 'default' shader mode. What exactly this means
- * is up to the backend. This mode is set by the client code when no user
- * overrides are present (i.e. if no custom shader mode is selected via
+ * Return the ID of the 'default' shader mode.
+ *
+ * What exactly this means is up to the backend.
+ * This mode is set by the client code when no user overrides
+ * are present (i.e. if no custom shader mode is selected using
* the command line or a config file).
*
- * @return the ID of the 'default' shader mode
+ * @return ID of the 'default' shader mode.
*/
virtual int getDefaultShader() const { return 0; }
/**
- * Switch to the specified shader mode. If switching to the new mode
- * failed, this method returns false.
+ * Switch to the specified shader mode.
+ *
+ * If switching to the new mode fails, this method returns false.
+ *
+ * @param id ID of the new shader mode.
*
- * @param mode the ID of the new shader mode
- * @return true if the switch was successful, false otherwise
+ * @return True if the switch was successful, false otherwise.
*/
virtual bool setShader(int id) { return false; }
/**
- * Switch to the shader mode with the given name. If 'name' is unknown,
- * or if switching to the new mode failed, this method returns false.
+ * Switch to the shader mode with the given name.
*
- * @param name the name of the new shader mode
- * @return true if the switch was successful, false otherwise
- * @note This is implemented via the setShader(int) method, as well
+ * If @p name is unknown, or if switching to the new mode fails,
+ * this method returns false.
+ *
+ * @param name Name of the new shader mode.
+ *
+ * @return True if the switch was successful, false otherwise.
+ *
+ * @note This is implemented using the setShader(int) method, as well
* as getSupportedShaders() and getDefaultShader().
* In particular, backends do not have to overload this!
*/
@@ -735,15 +791,18 @@ public:
/**
* Determine which shader is currently active.
- * @return the ID of the active shader
+ *
+ * @return ID of the active shader.
*/
virtual int getShader() const { return 0; }
/**
* Retrieve a list of all stretch modes supported by this backend.
+ *
* It is completely up to the backend maintainer to decide what is
* appropriate here and what not.
* The list is terminated by an all-zero entry.
+ *
* @return a list of supported stretch modes
*/
virtual const GraphicsMode *getSupportedStretchModes() const {
@@ -752,31 +811,38 @@ public:
}
/**
- * Return the ID of the 'default' stretch mode. What exactly this means
- * is up to the backend. This mode is set by the client code when no user
- * overrides are present (i.e. if no custom stretch mode is selected via
- * the command line or a config file).
+ * Return the ID of the 'default' stretch mode.
*
- * @return the ID of the 'default' graphics mode
+ * What exactly this means is up to the backend. This mode is set
+ * by the client code when no user overrides are present
+ * (i.e. if no custom stretch mode is selected using the command line or a config file).
+ *
+ * @return ID of the 'default' graphics mode.
*/
virtual int getDefaultStretchMode() const { return 0; }
/**
- * Switch to the specified stretch mode. If switching to the new mode
- * failed, this method returns false.
+ * Switch to the specified stretch mode.
+ *
+ * If switching to the new mode fails, this method returns false.
*
- * @param mode the ID of the new graphics mode
- * @return true if the switch was successful, false otherwise
+ * @param mode ID of the new graphics mode.
+ *
+ * @return True if the switch was successful, false otherwise.
*/
virtual bool setStretchMode(int mode) { return false; }
/**
- * Switch to the stretch mode with the given name. If 'name' is unknown,
- * or if switching to the new mode failed, this method returns false.
+ * Switch to the stretch mode with the given name.
+ *
+ * If @p name is unknown, or if switching to the new mode fails,
+ * this method returns false.
*
- * @param name the name of the new stretch mode
- * @return true if the switch was successful, false otherwise
- * @note This is implemented via the setStretchMode(int) method, as well
+ * @param name Name of the new stretch mode.
+ *
+ * @return True if the switch was successful, false otherwise.
+ *
+ * @note This is implemented using the setStretchMode(int) method, as well
* as getSupportedStretchModes() and getDefaultStretchMode().
* In particular, backends do not have to overload this!
*/
@@ -784,36 +850,39 @@ public:
/**
* Determine which stretch mode is currently active.
- * @return the ID of the active stretch mode
+ *
+ * @return ID of the active stretch mode.
*/
virtual int getStretchMode() const { return 0; }
/**
- * Set the size and color format of the virtual screen. Typical sizes include:
- * - 320x200 (e.g. for most SCUMM games, and Simon)
- * - 320x240 (e.g. for FM-TOWN SCUMM games)
- * - 640x480 (e.g. for Curse of Monkey Island)
+ * Set the size and color format of the virtual screen.
+ *
+ * Typical sizes include:
+ * - 320x200 (e.g. for most SCUMM games, and Simon)
+ * - 320x240 (e.g. for FM-TOWN SCUMM games)
+ * - 640x480 (e.g. for Curse of Monkey Island)
*
- * This is the resolution for which the client code generates data;
- * this is not necessarily equal to the actual display size. For example,
- * a backend may magnify the graphics to fit on screen (see also the
- * GraphicsMode); stretch the data to perform aspect ratio correction;
+ * This is the resolution for which the client code generates data.
+ * This is not necessarily equal to the actual display size. For example,
+ * a backend may magnify the graphics to fit on the screen (see also the
+ * GraphicsMode), stretch the data to perform aspect ratio correction,
* or shrink it to fit on small screens (in cell phones).
*
* Typical formats include:
- * CLUT8 (e.g. 256 color, for most games)
- * RGB555 (e.g. 16-bit color, for later SCUMM HE games)
- * RGB565 (e.g. 16-bit color, for Urban Runner)
+ * - CLUT8 (e.g. 256 color, for most games)
+ * - RGB555 (e.g. 16-bit color, for later SCUMM HE games)
+ * - RGB565 (e.g. 16-bit color, for Urban Runner)
*
- * This is the pixel format for which the client code generates data;
- * this is not necessarily equal to the hardware pixel format. For example,
+ * This is the pixel format for which the client code generates data.
+ * It is not necessarily equal to the hardware pixel format. For example,
* a backend may perform color lookup of 8-bit graphics before pushing
* a screen to hardware, or correct the ARGB color order.
*
- * @param width the new virtual screen width
- * @param height the new virtual screen height
- * @param format the new virtual screen pixel format
+ * @param width New virtual screen width.
+ * @param height New virtual screen height.
+ * @param format New virtual screen pixel format.
*/
virtual void initSize(uint width, uint height, const Graphics::PixelFormat *format = nullptr) = 0;
@@ -825,112 +894,123 @@ public:
* should call this function prior to any call to initSize. Engines that use
* only a single screen size do not need to call this function.
*
- * @param modes the list of graphics modes the engine will probably use.
+ * @param modes List of graphics modes the engine will probably use.
*/
virtual void initSizeHint(const Graphics::ModeList &modes) {}
/**
- * Return an int value which is changed whenever any screen
- * parameters (like the resolution) change. That is, whenever a
- * EVENT_SCREEN_CHANGED would be sent. You can track this value
- * in your code to detect screen changes in case you do not have
- * full control over the event loop(s) being used (like the GUI
- * code).
+ * Return an int value that is changed whenever any screen
+ * parameters (like the resolution) change, i.e. whenever
+ * EVENT_SCREEN_CHANGED is sent.
*
- * @return an integer which can be used to track screen changes
+ * You can track this value in your code to detect screen changes in case
+ * you do not have full control over the event loop(s)
+ * being used (like the GUI code).
*
- * @note Backends which generate EVENT_SCREEN_CHANGED events MUST
+ * @return Integer that can be used to track screen changes.
+ *
+ * @note Backends that generate EVENT_SCREEN_CHANGED events must
* overload this method appropriately.
*/
virtual int getScreenChangeID() const { return 0; }
/**
* Begin a new GFX transaction, which is a sequence of GFX mode changes.
+ *
* The idea behind GFX transactions is to make it possible to activate
* several different GFX changes at once as a "batch" operation. For
* example, assume we are running in 320x200 with a 2x scaler (thus using
* 640x400 pixels in total). Now, we want to switch to 640x400 with the 1x
* scaler. Without transactions, we have to choose whether we want to first
* switch the scaler mode, or first to 640x400 mode. In either case,
- * depending on the backend implementation, some ugliness may result.
- * E.g. the window might briefly switch to 320x200 or 1280x800.
+ * depending on the backend implementation, problems may occur.
+ * For example, the window might briefly switch to 320x200 or 1280x800.
* Using transactions, this can be avoided.
*
* @note Transaction support is optional, and the default implementations
* of the relevant methods simply do nothing.
+ *
* @see endGFXTransaction
*/
virtual void beginGFXTransaction() {}
/**
- * This type is able to save the different errors which can happen while
+ * This type can save the different errors which can happen while
* changing GFX config values inside GFX transactions.
*
- * endGFXTransaction returns a ORed combination of the '*Failed' values
- * if any problem occures, on success 0.
+ * endGFXTransaction returns an ORed combination of the '*Failed' values
+ * if any problem occurs. It returns '0' on success.
*
* @see endGFXTransaction
*/
enum TransactionError {
- kTransactionSuccess = 0, /**< Everything fine (use EQUAL check for this one!) */
- kTransactionAspectRatioFailed = (1 << 0), /**< Failed switching aspect ratio correction mode */
- kTransactionFullscreenFailed = (1 << 1), /**< Failed switching fullscreen mode */
- kTransactionModeSwitchFailed = (1 << 2), /**< Failed switching the GFX graphics mode (setGraphicsMode) */
- kTransactionSizeChangeFailed = (1 << 3), /**< Failed switching the screen dimensions (initSize) */
- kTransactionFormatNotSupported = (1 << 4), /**< Failed setting the color format */
- kTransactionFilteringFailed = (1 << 5), /**< Failed setting the filtering mode */
- kTransactionStretchModeSwitchFailed = (1 << 6) /**< Failed setting the stretch mode */
+ kTransactionSuccess = 0, /**< Everything fine (use EQUAL check for this one!) */
+ kTransactionAspectRatioFailed = (1 << 0), /**< Failed switching aspect ratio correction mode */
+ kTransactionFullscreenFailed = (1 << 1), /**< Failed switching fullscreen mode */
+ kTransactionModeSwitchFailed = (1 << 2), /**< Failed switching the GFX graphics mode (setGraphicsMode) */
+ kTransactionSizeChangeFailed = (1 << 3), /**< Failed switching the screen dimensions (initSize) */
+ kTransactionFormatNotSupported = (1 << 4), /**< Failed setting the color format */
+ kTransactionFilteringFailed = (1 << 5), /**< Failed setting the filtering mode */
+ kTransactionStretchModeSwitchFailed = (1 << 6) /**< Failed setting the stretch mode */
};
/**
* End (and thereby commit) the current GFX transaction.
+ *
* @see beginGFXTransaction
* @see kTransactionError
- * @return returns a ORed combination of TransactionError values or 0 on success
+ *
+ * @return ORed combination of TransactionError values or 0 on success.
*/
virtual TransactionError endGFXTransaction() { return kTransactionSuccess; }
/**
- * Returns the currently set virtual screen height.
+ * Return the currently set virtual screen height.
+ *
* @see initSize
- * @return the currently set virtual screen height
+ *
+ * @return Currently set virtual screen height.
*/
virtual int16 getHeight() = 0;
/**
- * Returns the currently set virtual screen width.
+ * Return the currently set virtual screen width.
+ *
* @see initSize
- * @return the currently set virtual screen width
+ *
+ * @return Currently set virtual screen width.
*/
virtual int16 getWidth() = 0;
/**
- * Return the palette manager singleton. For more information, refer
- * to the PaletteManager documentation.
+ * Return the palette manager singleton.
+ *
+ * For more information, see @ref PaletteManager.
*/
virtual PaletteManager *getPaletteManager() = 0;
/**
* Blit a bitmap to the virtual screen.
+ *
* The real screen will not immediately be updated to reflect the changes.
- * Client code has to to call updateScreen to ensure any changes are
- * visible to the user. This can be used to optimize drawing and reduce
- * flicker.
+ * Client code must call updateScreen to ensure any changes are visible
+ * to the user. This can be used to optimize drawing and reduce flicker.
+ *
* If the current pixel format has one byte per pixel, the graphics data
* uses 8 bits per pixel, using the palette specified via setPalette.
* If more than one byte per pixel is in use, the graphics data uses the
* pixel format returned by getScreenFormat.
*
- * @param buf the buffer containing the graphics data source
- * @param pitch the pitch of the buffer (number of bytes in a scanline)
- * @param x the x coordinate of the destination rectangle
- * @param y the y coordinate of the destination rectangle
- * @param w the width of the destination rectangle
- * @param h the height of the destination rectangle
+ * @param buf Buffer containing the graphics data source.
+ * @param pitch Pitch of the buffer (number of bytes in a scanline).
+ * @param x x coordinate of the destination rectangle.
+ * @param y y coordinate of the destination rectangle.
+ * @param w Width of the destination rectangle.
+ * @param h Height of the destination rectangle.
*
* @note The specified destination rectangle must be completly contained
* in the visible screen space, and must be non-empty. If not, a
- * backend may or may not perform clipping, trigger an assert or
+ * backend may or may not perform clipping, trigger an assert, or
* silently corrupt memory.
*
* @see updateScreen
@@ -940,14 +1020,17 @@ public:
/**
* Lock the active screen framebuffer and return a Graphics::Surface
- * representing it. The caller can then perform arbitrary graphics
- * transformations on the framebuffer (blitting, scrolling, etc.).
- * Must be followed by matching call to unlockScreen(). Calling code
- * should make sure to only lock the framebuffer for the briefest
- * periods of time possible, as the whole system is potentially stalled
+ * representing it.
+ *
+ * The caller can then perform arbitrary graphics transformations
+ * on the framebuffer (blitting, scrolling, etc.).
+ * Must be followed by a matching call to unlockScreen().
+ * Code that is calling this should make sure to only lock the framebuffer
+ * for the shortest time possible, as the whole system is potentially stalled
* while the lock is active.
- * Returns 0 if an error occurred. Otherwise a surface with the pixel
- * format described by getScreenFormat is returned.
+ *
+ * @return 0 if an error occurs. Otherwise, a surface with the pixel
+ * format described by getScreenFormat is returned.
*
* The returned surface must *not* be deleted by the client code.
*
@@ -956,22 +1039,22 @@ public:
virtual Graphics::Surface *lockScreen() = 0;
/**
- * Unlock the screen framebuffer, and mark it as dirty (i.e. during the
+ * Unlock the screen framebuffer, and mark it as dirty, i.e. during the
* next updateScreen() call, the whole screen will be updated.
*/
virtual void unlockScreen() = 0;
/**
- * Fills the screen with a given color value.
+ * Fill the screen with the given color value.
*/
virtual void fillScreen(uint32 col) = 0;
/**
- * Flush the whole screen, that is render the current content of the screen
+ * Flush the whole screen, i.e. render the current content of the screen
* framebuffer to the display.
*
- * This method could be called very often by engines. Backends are hence
- * supposed to only perform any redrawing if it is necessary, and otherwise
+ * This method may be called very often by engines. Backends are hence
+ * supposed to only perform any redrawing if it is necessary and otherwise
* return immediately. See
* <https://wiki.scummvm.org/index.php/HOWTO-Backends#updateScreen.28.29_method>
*/
@@ -979,14 +1062,17 @@ public:
/**
* Set current shake position, a feature needed for some SCUMM screen
- * effects. The effect causes the displayed graphics to be shifted upwards
+ * effects.
+ *
+ * The effect causes the displayed graphics to be shifted upwards
* by the specified (always positive) offset. The area at the bottom of the
* screen which is moved into view by this is filled with black. This does
- * not cause any graphic data to be lost - that is, to restore the original
+ * not cause any graphic data to be lost. To restore the original
* view, the game engine only has to call this method again with offset
* equal to zero. No calls to copyRectToScreen are necessary.
- * @param shakeXOffset the shake x offset
- * @param shakeYOffset the shake y offset
+ *
+ * @param shakeXOffset Shake x offset.
+ * @param shakeYOffset Shake y offset.
*
* @note This is currently used in the SCUMM, QUEEN, KYRA, SCI, DREAMWEB,
* SUPERNOVA, TEENAGENT, TOLTECS, ULTIMA, and PETKA engines.
@@ -994,23 +1080,27 @@ public:
virtual void setShakePos(int shakeXOffset, int shakeYOffset) = 0;
/**
- * Sets the area of the screen that has the focus. For example, when a character
- * is speaking, they will have the focus. Allows for pan-and-scan style views
- * where the backend could follow the speaking character or area of interest on
- * the screen.
+ * Set the area of the screen that has the focus.
*
+ * For example, when a character is speaking, they will have the focus.
+ * This allows for pan-and-scan style views where the backend
+ * can follow the speaking character or area of interest on the screen.
+ *
* The backend is responsible for clipping the rectangle and deciding how best to
* zoom the screen to show any shape and size rectangle the engine provides.
*
- * @param rect A rectangle on the screen to be focused on
+ * @param rect Rectangle on the screen to be focused on.
+ *
* @see clearFocusRectangle
*/
virtual void setFocusRectangle(const Common::Rect& rect) {}
/**
- * Clears the focus set by a call to setFocusRectangle(). This allows the engine
- * to clear the focus during times when no particular area of the screen has the
- * focus.
+ * Clear the focus set by a call to setFocusRectangle().
+ *
+ * This allows the engine to clear the focus when no particular area
+ * of the screen has the focus.
+ *
* @see setFocusRectangle
*/
virtual void clearFocusRectangle() {}
@@ -1021,28 +1111,30 @@ public:
* The backend can persist it the way it considers appropriate.
*/
virtual void saveScreenshot() {}
- //@}
+ /** @} */
/**
- * @name Overlay
- * In order to be able to display dialogs atop the game graphics, backends
+ * @defgroup common_system_overlay Overlay
+ * @ingroup common_system
+ * @{
+ *
+ * To display dialogs atop the game graphics, backends
* must provide an overlay mode.
*
* The overlay is currently forced at 16 bpp.
*
- * For 'coolness' we usually want to have an overlay which is blended over
- * the game graphics. On backends which support alpha blending, this is
- * no issue; but on other systems this needs some trickery.
+ * For 'coolness' we usually want to have an overlay that is blended over
+ * the game graphics. On backends that support alpha blending, this is
+ * no issue but on other systems this needs some trickery.
*
* Essentially, we fake (alpha) blending on these systems by copying the
* current game graphics into the overlay buffer when activating the overlay,
- * then manually compose whatever graphics we want to show in the overlay.
+ * and then manually compose whatever graphics we want to show in the overlay.
* This works because we assume the game to be "paused" whenever an overlay
* is active.
*/
- //@{
/** Activate the overlay mode. */
virtual void showOverlay() = 0;
@@ -1050,11 +1142,12 @@ public:
/** Deactivate the overlay mode. */
virtual void hideOverlay() = 0;
- /** Returns true if the overlay mode is activated, false otherwise. */
+ /** Return true if the overlay mode is activated, false otherwise. */
virtual bool isOverlayVisible() const = 0;
/**
- * Returns the pixel format description of the overlay.
+ * Return the pixel format description of the overlay.
+ *
* @see Graphics::PixelFormat
*/
virtual Graphics::PixelFormat getOverlayFormat() const = 0;
@@ -1064,30 +1157,31 @@ public:
*
* After calling this method while the overlay mode is active, the user
* should be seeing only the game graphics. How this is achieved depends
- * on how the backend implements the overlay. Either it sets all pixels of
- * the overlay to be transparent (when alpha blending is used).
- *
- * Or, in case of fake alpha blending, it might just put a copy of the
+ * on how the backend implements the overlay. It either sets all pixels of
+ * the overlay to be transparent (when alpha blending is used) or,
+ * in case of fake alpha blending, it might just put a copy of the
* current game graphics screen into the overlay.
*/
virtual void clearOverlay() = 0;
/**
* Copy the content of the overlay into a buffer provided by the caller.
+ *
* This is only used to implement fake alpha blending.
*/
virtual void grabOverlay(void *buf, int pitch) = 0;
/**
* Blit a graphics buffer to the overlay.
+ *
* In a sense, this is the reverse of grabOverlay.
*
- * @param buf the buffer containing the graphics data source
- * @param pitch the pitch of the buffer (number of bytes in a scanline)
- * @param x the x coordinate of the destination rectangle
- * @param y the y coordinate of the destination rectangle
- * @param w the width of the destination rectangle
- * @param h the height of the destination rectangle
+ * @param buf Buffer containing the graphics data source.
+ * @param pitch Pitch of the buffer (number of bytes in a scanline).
+ * @param x x coordinate of the destination rectangle.
+ * @param y y coordinate of the destination rectangle.
+ * @param w Width of the destination rectangle.
+ * @param h Height of the destination rectangle.
*
* @see copyRectToScreen
* @see grabOverlay
@@ -1096,34 +1190,39 @@ public:
/**
* Return the height of the overlay.
+ *
* @see getHeight
*/
virtual int16 getOverlayHeight() = 0;
/**
* Return the width of the overlay.
+ *
* @see getWidth
*/
virtual int16 getOverlayWidth() = 0;
- //@}
+ /** @} */
- /** @name Mouse
+ /** @defgroup common_system_mouse Mouse
+ * @ingroup common_system
+ * @{
+ *
* This is the lower level implementation as provided by the
* backends. The engines should use the Graphics::CursorManager
- * class instead of using it directly.
+ * class instead of using this directly.
*/
- //@{
+
/**
* Show or hide the mouse cursor.
*
- * Currently the backend is not required to immediately draw the
+ * Currently, the backend is not required to immediately draw the
* mouse cursor on showMouse(true).
*
- * TODO: We might want to reconsider this fact,
+ * @todo We might want to reconsider this fact,
* check Graphics::CursorManager::showMouse for some details about
* this.
*
@@ -1140,54 +1239,58 @@ public:
/**
* Move ("warp") the mouse cursor to the specified position in virtual
* screen coordinates.
- * @param x the new x position of the mouse
- * @param y the new y position of the mouse
+ *
+ * @param x New x position of the mouse.
+ * @param y New y position of the mouse.
*/
virtual void warpMouse(int x, int y) = 0;
/**
* Set the bitmap used for drawing the cursor.
*
- * @param buf the pixmap data to be used
- * @param w width of the mouse cursor
- * @param h height of the mouse cursor
- * @param hotspotX horizontal offset from the left side to the hotspot
- * @param hotspotY vertical offset from the top side to the hotspot
- * @param keycolor transparency color value. This should not exceed the maximum color value of the specified format.
- * In case it does the behavior is undefined. The backend might just error out or simply ignore the
- * value. (The SDL backend will just assert to prevent abuse of this).
- * @param dontScale Whether the cursor should never be scaled. An exception are high ppi displays, where the cursor
- * would be too small to notice otherwise, these are allowed to scale the cursor anyway.
- * @param format pointer to the pixel format which cursor graphic uses (0 means CLUT8)
+ * @param buf Pixmap data to be used.
+ * @param w Width of the mouse cursor.
+ * @param h Height of the mouse cursor.
+ * @param hotspotX Horizontal offset from the left side to the hotspot.
+ * @param hotspotY Vertical offset from the top side to the hotspot.
+ * @param keycolor Transparency color value. This should not exceed the maximum color value of the specified format.
+ * In case it does, the behavior is undefined. The backend might just error out or simply ignore the
+ * value. (The SDL backend will just assert to prevent abuse of this).
+ * @param dontScale Whether the cursor should never be scaled. An exception is high ppi displays, where the cursor
+ * might be too small to notice otherwise, these are allowed to scale the cursor anyway.
+ * @param format Pointer to the pixel format that the cursor graphic uses (0 means CLUT8).
*/
virtual void setMouseCursor(const void *buf, uint w, uint h, int hotspotX, int hotspotY, uint32 keycolor, bool dontScale = false, const Graphics::PixelFormat *format = nullptr) = 0;
/**
- * Replace the specified range of cursor the palette with new colors.
+ * Replace the specified range of cursor palette with new colors.
+ *
* The palette entries from 'start' till (start+num-1) will be replaced - so
* a full palette update is accomplished via start=0, num=256.
*
- * Backends which implement it should have kFeatureCursorPalette flag set
+ * Backends which implement this should have the kFeatureCursorPalette flag set.
*
* @see setPalette
* @see kFeatureCursorPalette
*/
virtual void setCursorPalette(const byte *colors, uint start, uint num) {}
- //@}
+ /** @} */
- /** @name Events and Time */
- //@{
+ /** @defgroup common_system_event_time Events and Time
+ * @ingroup common_system
+ * @{
+ */
/** Get the number of milliseconds since the program was started.
-
- @param skipRecord Skip recording of this value by event recorder.
- This could be needed particularly when we are in
- an on-screen GUI loop where player can pause
- the recording.
- */
+ *
+ * @param skipRecord Skip recording of this value by the event recorder.
+ * This might be needed particularly when we are in
+ * an on-screen GUI loop where the player can pause
+ * the recording.
+ */
virtual uint32 getMillis(bool skipRecord = false) = 0;
/** Delay/sleep for the specified amount of milliseconds. */
@@ -1195,79 +1298,85 @@ public:
/**
* Get the current time and date, in the local timezone.
- * Corresponds on many systems to the combination of time()
+ *
+ * On many systems, this corresponds to the combination of time()
* and localtime().
*/
virtual void getTimeAndDate(TimeDate &t) const = 0;
/**
- * Return the timer manager singleton. For more information, refer
- * to the TimerManager documentation.
+ * Return the timer manager singleton.
+ *
+ * For more information, see @ref TimerManager.
*/
virtual Common::TimerManager *getTimerManager();
/**
- * Return the event manager singleton. For more information, refer
- * to the EventManager documentation.
+ * Return the event manager singleton.
+ *
+ * For more information, see @ref EventManager.
*/
inline Common::EventManager *getEventManager() {
return _eventManager;
}
/**
- * Register hardware inputs with keymapper
+ * Register hardware inputs with keymapper.
*
- * @return HardwareInputSet with all keys and recommended mappings
+ * @return HardwareInputSet with all keys and recommended mappings.
*
- * See keymapper documentation for further reference.
+ * For more information, see @ref keymapper.
*/
virtual Common::HardwareInputSet *getHardwareInputSet() { return nullptr; }
/**
- * Return a platform-specific global keymap
+ * Return a platform-specific global keymap.
*
- * @return Keymap with actions appropriate for the platform
+ * @return Keymap with actions appropriate for the platform.
*
* The caller will use and delete the return object.
*
- * See keymapper documentation for further reference.
+ * For more information, see @ref keymapper.
*/
virtual Common::KeymapArray getGlobalKeymaps() { return Common::KeymapArray(); }
/**
- * Return platform-specific default keybindings
+ * Return platform-specific default keybindings.
*
- * @return KeymapperDefaultBindings populated with keybindings
+ * @return KeymapperDefaultBindings populated with keybindings.
*
- * See keymapper documentation for further reference.
+ * For more information, see @ref keymapper.
*/
virtual Common::KeymapperDefaultBindings *getKeymapperDefaultBindings() { return nullptr; }
- //@}
+ /** @} */
/**
- * @name Mutex handling
- * Historically, the OSystem API used to have a method which allowed
- * creating threads. Hence mutex support was needed for thread syncing.
- * To ease portability, though, we decided to remove the threading API.
+ * @defgroup common_system_mutex Mutex handling
+ * @ingroup common_system
+ * @{
+ *
+ * Historically, the OSystem API used to have a method that allowed
+ * creating threads. Hence, mutex support was needed for thread syncing.
+ * To ease portability, we decided to remove the threading API.
* Instead, we now use timers (see setTimerCallback() and Common::Timer).
- * But since those may be implemented using threads (and in fact, that's
+ * But since those can be implemented using threads (and in fact, that is
* how our primary backend, the SDL one, does it on many systems), we
- * still have to do mutex syncing in our timer callbacks.
+ * still must do mutex syncing in our timer callbacks.
* In addition, the sound mixer uses a mutex in case the backend runs it
- * from a dedicated thread (as e.g. the SDL backend does).
+ * from a dedicated thread (as the SDL backend does).
*
- * Hence backends which do not use threads to implement the timers simply
- * can use dummy implementations for these methods.
+ * Hence, backends that do not use threads to implement the timers can simply
+ * use dummy implementations for these methods.
*/
- //@{
typedef struct OpaqueMutex *MutexRef;
/**
* Create a new mutex.
- * @return the newly created mutex, or 0 if an error occurred.
+ *
+ * @return The newly created mutex, or 0 if an error occurred.
*/
virtual MutexRef createMutex() = 0;
@@ -1275,67 +1384,80 @@ public:
* Lock the given mutex.
*
* @note ScummVM code assumes that the mutex implementation supports
- * recursive locking. That is, a thread may lock a mutex twice w/o
- * deadlocking. In case of a multilock, the mutex has to be unlocked
+ * recursive locking. That is, a thread can lock a mutex twice without
+ * deadlocking. In case of a multilock, the mutex must be unlocked
* as many times as it was locked befored it really becomes unlocked.
*
- * @param mutex the mutex to lock.
+ * @param mutex The mutex to lock.
*/
virtual void lockMutex(MutexRef mutex) = 0;
/**
* Unlock the given mutex.
- * @param mutex the mutex to unlock.
+ *
+ * @param mutex The mutex to unlock.
*/
virtual void unlockMutex(MutexRef mutex) = 0;
/**
- * Delete the given mutex. Make sure the mutex is unlocked before you delete it.
- * If you delete a locked mutex, the behavior is undefined, in particular, your
- * program may crash.
- * @param mutex the mutex to delete.
+ * Delete the given mutex.
+ *
+ * Make sure the mutex is unlocked before you delete it.
+ * If you delete a locked mutex, the behavior is undefined.
+ * In particular, your program may crash.
+ *
+ * @param mutex The mutex to delete.
*/
virtual void deleteMutex(MutexRef mutex) = 0;
- //@}
+ /** @} */
- /** @name Sound */
- //@{
+ /** @defgroup common_system_sound Sound
+ * @ingroup common_system
+ * @{
+ */
/**
- * Return the audio mixer. For more information, refer to the
- * Audio::Mixer documentation.
+ * Return the audio mixer.
+ *
+ * For more information, see @ref Audio::Mixer.
*/
virtual Audio::Mixer *getMixer() = 0;
- //@}
+ /** @} */
- /** @name Audio CD */
- //@{
+ /** @defgroup common_system_audio Audio CD
+ * @ingroup common_system
+ * @{
+ */
/**
- * Return the audio cd manager. For more information, refer to the
- * AudioCDManager documentation.
+ * Return the audio CD manager.
+ *
+ * For more information, see @ref AudioCDManager.
*/
inline AudioCDManager *getAudioCDManager() {
return _audiocdManager;
}
- //@}
+ /** @} */
- /** @name Miscellaneous */
- //@{
+ /** @defgroup common_system_misc Miscellaneous
+ * @ingroup common_system
+ * @{
+ */
+
/** Quit (exit) the application. */
virtual void quit() = 0;
/**
- * Signals that a fatal error inside the client code has happened.
+ * Signal that a fatal error inside the client code has occurred.
*
* This should quit the application.
*/
@@ -1343,35 +1465,38 @@ public:
/**
* Set a window caption or any other comparable status display to the
- * given value. The caption must be a pure ISO LATIN 1 string. Passing a
- * string with a different encoding may lead to unexpected behavior,
+ * given value.
+ *
+ * The caption must be a pure ISO LATIN 1 string. Passing a string
+ * with a different encoding may lead to unexpected behavior,
* even crashes.
*
- * @param caption the window caption to use, as an ISO LATIN 1 string
+ * @param caption The window caption to use, as an ISO LATIN 1 string.
*/
virtual void setWindowCaption(const char *caption) {}
/**
- * Display a message in an 'on screen display'. That is, display it in a
- * fashion where it is visible on or near the screen (e.g. in a transparent
- * rectangle over the regular screen content; or in a message box beneath
- * it; etc.).
+ * Display a message in an 'on-screen display'.
*
+ * Displays a message in such a way that it is visible on or near the screen,
+ * for example in a transparent rectangle over the regular screen content,
+ * or in a message box beneath it.
+ *
* The message is expected to be provided in the current TranslationManager
* charset.
*
- * @note There is a default implementation in BaseBackend which uses a
- * TimedMessageDialog to display the message. Hence implementing
+ * @note There is a default implementation in BaseBackend that uses a
+ * TimedMessageDialog to display the message. Hence, implementing
* this is optional.
*
- * @param msg the message to display on screen
+ * @param msg The message to display on the screen.
*/
virtual void displayMessageOnOSD(const Common::U32String &msg) = 0;
/**
- * Display an icon indicating background activity
+ * Display an icon that indicates background activity.
*
- * The icon is displayed in an 'on screen display'. It is visible above
+ * The icon is displayed in an 'on-screen display'. It is visible above
* the regular screen content or near it.
*
* The caller keeps ownership of the icon. It is acceptable to free
@@ -1383,35 +1508,42 @@ public:
* The caller must call this method again with a null pointer
* as a parameter to indicate the icon should no longer be displayed.
*
- * @param icon the icon to display on screen
+ * @param icon The icon to display on the screen.
*/
virtual void displayActivityIconOnOSD(const Graphics::Surface *icon) = 0;
-
+ /** @} */
+
/**
- * Return the SaveFileManager, used to store and load savestates
- * and other modifiable persistent game data. For more information,
- * refer to the SaveFileManager documentation.
+ * @addtogroup common_system_module
+ * @{
+ */
+
+ /**
+ * Return the SaveFileManager, which is used to store and load savestates
+ * and other modifiable persistent game data.
+ *
+ * For more information, see @ref SaveFileManager.
*/
virtual Common::SaveFileManager *getSavefileManager();
#if defined(USE_TASKBAR)
/**
- * Returns the TaskbarManager, used to handle progress bars,
- * icon overlay, tasks and recent items list on the taskbar.
+ * Return the TaskbarManager, which is used to handle progress bars,
+ * icon overlay, tasks, and recent items list on the taskbar.
*
- * @return the TaskbarManager for the current architecture
+ * @return The TaskbarManager for the current architecture.
*/
virtual Common::TaskbarManager *getTaskbarManager() {
return _taskbarManager;
}
#endif
-
+
#if defined(USE_UPDATES)
/**
- * Returns the UpdateManager, used to handle auto-updating,
+ * Return the UpdateManager, which is used to handle auto-updating
* and updating of ScummVM in general.
*
- * @return the UpdateManager for the current architecture
+ * @return The UpdateManager for the current architecture.
*/
virtual Common::UpdateManager *getUpdateManager() {
return _updateManager;
@@ -1420,9 +1552,9 @@ public:
#if defined(USE_TTS)
/**
- * Returns the TextToSpeechManager, used to handle text to speech features.
+ * Return the TextToSpeechManager, used to handle text-to-speech features.
*
- * @return the TextToSpeechManager for the current architecture
+ * @return The TextToSpeechManager for the current architecture.
*/
virtual Common::TextToSpeechManager *getTextToSpeechManager() {
return _textToSpeechManager;
@@ -1431,9 +1563,9 @@ public:
#if defined(USE_SYSDIALOGS)
/**
- * Returns the DialogManager, used to handle system dialogs.
+ * Return the DialogManager, which is used to handle system dialogs.
*
- * @return the DialogManager for the current architecture
+ * @return The DialogManager for the current architecture.
*/
virtual Common::DialogManager *getDialogManager() {
return _dialogManager;
@@ -1441,81 +1573,89 @@ public:
#endif
/**
- * Returns the FilesystemFactory object, depending on the current architecture.
+ * Return the FilesystemFactory object, depending on the current architecture.
*
- * @return the FSNode factory for the current architecture
+ * @return The FSNode factory for the current architecture.
*/
virtual FilesystemFactory *getFilesystemFactory();
-
+ /** @} */
+
/**
- * Add system specific Common::Archive objects to the given SearchSet.
- * E.g. on Unix the dir corresponding to DATA_PATH (if set), or on
- * Mac OS X the 'Resource' dir in the app bundle.
+ * @addtogroup common_system_misc
+ * @{
+ */
+
+ /** Add system-specific Common::Archive objects to the given SearchSet.
+ * For example, on Unix, the directory corresponding to DATA_PATH (if set), or, on
+ * Mac OS X, the 'Resource' dir in the app bundle.
*
- * @todo Come up with a better name. This one sucks.
+ * @todo Come up with a better name.
*
- * @param s the SearchSet to which the system specific dirs, if any, are added
- * @param priority the priority with which those dirs are added
+ * @param s SearchSet to which the system-specific dirs, if any, are added.
+ * @param priority Priority with which those dirs are added.
*/
virtual void addSysArchivesToSearchSet(Common::SearchSet &s, int priority = 0) {}
/**
- * Open the default config file for reading, by returning a suitable
- * ReadStream instance. It is the callers responsiblity to delete
- * the stream after use.
+ * Open the default config file for reading by returning a suitable
+ * ReadStream instance.
+ *
+ * It is the caller's responsiblity to delete the stream after use.
*/
virtual Common::SeekableReadStream *createConfigReadStream();
/**
- * Open the default config file for writing, by returning a suitable
- * WriteStream instance. It is the callers responsiblity to delete
- * the stream after use.
+ * Open the default config file for writing by returning a suitable
+ * WriteStream instance.
*
- * May return 0 to indicate that writing to config file is not possible.
+ * It is the callers responsiblity to delete the stream after use.
+ *
+ * May return 0 to indicate that writing to the config file is not possible.
*/
virtual Common::WriteStream *createConfigWriteStream();
/**
* Get the default file name (or even path) where the user configuration
* of ScummVM will be saved.
- * Note that not all ports may use this.
+ *
+ * Note that not all ports can use this.
*/
virtual Common::String getDefaultConfigFileName();
/**
- * Logs a given message.
+ * Log the given message.
*
* It is up to the backend where to log the different messages.
- * The backend should aim at using a non-buffered output for it
+ * The backend should aim at using a non-buffered output for it,
* so that no log data is lost in case of a crash.
*
* The default implementation outputs them on stdout/stderr.
*
- * @param type the type of the message
- * @param message the message itself
+ * @param type Type of the message.
+ * @param message The message itself.
*/
virtual void logMessage(LogMessageType::Type type, const char *message) = 0;
/**
* Open the log file in a way that allows the user to review it,
* and possibly email it (or parts of it) to the ScummVM team,
- * e.g. as part of a bug report.
+ * for example as part of a bug report.
*
* On a desktop operating system, this would typically launch
- * some kind of (external) text editor / viewer.
- * On a phone, it might also cause a context switch to another
+ * some kind of an (external) text editor / viewer.
+ * On a phone, it can also cause a context switch to another
* application. Finally, on some ports, it might not be supported
- * at all, and so do nothing.
+ * at all, and do nothing.
*
* The kFeatureDisplayLogFile feature flag can be used to
* test whether this call has been implemented by the active
* backend.
*
- * @return true if all seems to have gone fine, false if an error occurred
+ * @return True on success, false if an error occurred.
*
- * @note An error could mean that the log file did not exist,
- * or the editor could not launch. However, a return value of true does
- * not guarantee that the user actually will see the log file.
+ * @note An error might mean that the log file did not exist,
+ * or that the editor could not launch. However, a return value of true does
+ * not guarantee that the user will actually see the log file.
*
* @note It is up to the backend to ensure that the system is in a state
* that allows the user to actually see the displayed log files. This
@@ -1524,24 +1664,24 @@ public:
virtual bool displayLogFile() { return false; }
/**
- * Returns whether there is text available in the clipboard.
+ * Check whether there is text available in the clipboard.
*
* The kFeatureClipboardSupport feature flag can be used to
* test whether this call has been implemented by the active
* backend.
*
- * @return true if there is text in the clipboard, false otherwise
+ * @return True if there is text in the clipboard, false otherwise.
*/
virtual bool hasTextInClipboard() { return !_clipboard.empty(); }
/**
- * Returns clipboard contents as a String.
+ * Return clipboard contents as a string.
*
* The kFeatureClipboardSupport feature flag can be used to
* test whether this call has been implemented by the active
* backend.
*
- * @return clipboard contents ("" if hasTextInClipboard() == false)
+ * @return clipboard contents ("" if hasTextInClipboard() == false).
*/
virtual Common::U32String getTextFromClipboard() { return _clipboard; }
@@ -1552,50 +1692,49 @@ public:
* test whether this call has been implemented by the active
* backend.
*
- * @return true if the text was properly set in the clipboard, false otherwise
+ * @return True if the text has been properly set in the clipboard, false otherwise.
*/
virtual bool setTextInClipboard(const Common::U32String &text) { _clipboard = text; return true; }
/**
- * Open the given Url in the default browser (if available on the target
+ * Open the given URL in the default browser (if available on the target
* system).
*
- * @return true on success, false otherwise.
+ * @return True on success, false otherwise.
*
* @note It is up to the backend to ensure that the system is in a state
* that allows the user to actually see the web page. This might for
* example require leaving fullscreen mode.
*
- * @parem url the URL to open
+ * @param url The URL to open.
*/
virtual bool openUrl(const Common::String &url) {return false; }
/**
- * Returns the locale of the system.
+ * Return the locale of the system.
*
- * This returns the currently set up locale of the system, on which
+ * This returns the currently set locale of the system on which
* ScummVM is run.
*
* The format of the locale is language_country. These should match
* the POSIX locale values.
*
- * For information about POSIX locales read here:
- * http://en.wikipedia.org/wiki/Locale#POSIX-type_platforms
+ * For information about POSIX locales, see the following link:
+ * https://en.wikipedia.org/wiki/Locale_(computer_software)#POSIX_platforms
*
* The default implementation returns "en_US".
*
- * @return locale of the system
+ * @return Locale of the system.
*/
virtual Common::String getSystemLanguage() const;
/**
- * Returns whether connection's limited (if available on the target system).
+ * Return whether the connection is limited (if available on the target system).
*
- * Returns true if connection seems limited.
+ * @return True if the connection is limited.
*/
virtual bool isConnectionLimited();
- //@}
protected:
@@ -1613,6 +1752,7 @@ protected:
* and not delete[]), or nullptr if the conversion isn't possible.
*/
virtual char *convertEncoding(const char *to, const char *from, const char *string, size_t length) { return nullptr; }
+ /** @} */
};
More information about the Scummvm-git-logs
mailing list