From 51672df70002602eb09a6460259ac92960aeaf53 Mon Sep 17 00:00:00 2001 From: Denis Kasak Date: Fri, 12 Jun 2009 09:45:12 +0000 Subject: Properly documented everything (including the new DraciFont class). Reshuffled some old comments. svn-id: r41467 --- engines/draci/barchive.h | 5 +-- engines/draci/font.cpp | 46 ++++++++++++++++++++++++- engines/draci/font.h | 13 +++++-- engines/draci/gpldisasm.cpp | 82 ++++++++++++++++++++++++++++----------------- engines/draci/gpldisasm.h | 11 ++++-- 5 files changed, 119 insertions(+), 38 deletions(-) diff --git a/engines/draci/barchive.h b/engines/draci/barchive.h index 0a0ecc832b..683ec50a67 100644 --- a/engines/draci/barchive.h +++ b/engines/draci/barchive.h @@ -31,7 +31,7 @@ namespace Draci { /** - * Represents individual files inside the archive + * Represents individual files inside the archive. */ struct BAFile { @@ -40,7 +40,8 @@ struct BAFile { byte *_data; byte _crc; - void closeFile(void) { //!< Releases the file data (for memory considerations) + /** Releases the file data (for memory considerations) */ + void closeFile(void) { delete _data; _data = NULL; } diff --git a/engines/draci/font.cpp b/engines/draci/font.cpp index d1c5eaa3be..5ea46ddb17 100644 --- a/engines/draci/font.cpp +++ b/engines/draci/font.cpp @@ -33,13 +33,30 @@ namespace Draci { DraciFont::DraciFont(Common::String &filename) : _fontHeight(0), _maxCharWidth(0), _charWidths(NULL), _charData(0) { - setFont(filename); + setFont(filename); } DraciFont::~DraciFont() { freeFont(); } +/** + * @brief Loads fonts from a file + * @param path Path to font file + * @return true if the font was loaded successfully, false otherwise + * + * Loads fonts from a file into a DraciFont instance. The original game uses two + * fonts (located inside files "Small.fon" and "Big.fon"). The characters in the + * font are indexed from the ASCII space (decimal value 32) so an appropriate + * offset must be added to convert them to equivalent char values, + * i.e. kDraciIndexOffset. + * + * font format: [1 byte] maximum character width + * [1 byte] font height + * [138 bytes] character widths of all 138 characters in the font + * [138 * fontHeight * maxWidth bytes] character data, stored row-wise + */ + bool DraciFont::setFont(Common::String &filename) { // If there is a font already loaded, free it @@ -89,6 +106,14 @@ uint8 DraciFont::getCharWidth(uint8 chr) const { return _charWidths[chr - kCharIndexOffset]; } +/** + * @brief Draw a char to a Graphics::Surface + * @param dst Pointer to the destination surface + * @param chr Character to draw (ASCII value) + * @param tx Horizontal offset on the surface + * @param ty Vertical offset on the surface + */ + void DraciFont::drawChar(Graphics::Surface *dst, uint8 chr, int tx, int ty) const { assert(dst != NULL); byte *ptr = (byte *)dst->getBasePtr(tx, ty); @@ -120,6 +145,16 @@ void DraciFont::drawChar(Graphics::Surface *dst, uint8 chr, int tx, int ty) cons } } +/** + * @brief Draw a string to a Graphics::Surface + * + * @param dst Pointer to the destination surface + * @param str String to draw + * @param x Horizontal offset on the surface + * @param y Vertical offset on the surface + * @param spacing Space to leave between individual characters. Defaults to 0. + */ + void DraciFont::drawString(Graphics::Surface *dst, Common::String str, int x, int y, int spacing) const { assert(dst != NULL); @@ -131,6 +166,15 @@ void DraciFont::drawString(Graphics::Surface *dst, Common::String str, } } +/** + * @brief Calculate the width of a string when drawn in the current font + * + * @param str String to draw + * @param spacing Space to leave between individual characters. Defaults to 0. + * + * @return The calculated width of the string + */ + int DraciFont::getStringWidth(Common::String &str, int spacing) const { int width = 0; uint len = str.size(); diff --git a/engines/draci/font.h b/engines/draci/font.h index 246bb4cc9f..d74951c783 100644 --- a/engines/draci/font.h +++ b/engines/draci/font.h @@ -27,6 +27,10 @@ namespace Draci { +/** + * Represents the game's fonts. See docs for setFont() for font format details. + */ + class DraciFont { public: @@ -44,15 +48,20 @@ public: private: uint8 _fontHeight; uint8 _maxCharWidth; + + /** Pointer to an array of individual char widths */ uint8 *_charWidths; + + /** Pointer to a raw byte array representing font pixels stored row-wise */ byte *_charData; - // Number of glyphs in the font + /** Number of glyphs in the font */ static const unsigned int kCharNum = 138; - // Chars are indexed from the ASCII space (decimal value 32) + /** Chars are indexed from the ASCII space (decimal value 32) */ static const unsigned int kCharIndexOffset = 32; + /** Internal function for freeing fonts when destructing/loading another */ void freeFont(); }; diff --git a/engines/draci/gpldisasm.cpp b/engines/draci/gpldisasm.cpp index 9024a2dd72..17ed5c7494 100644 --- a/engines/draci/gpldisasm.cpp +++ b/engines/draci/gpldisasm.cpp @@ -23,37 +23,6 @@ * */ -/** - * @brief GPL2 bytecode disassembler - * @param gplcode A pointer to the bytecode - * len Length of the bytecode - * - * GPL2 is short for Game Programming Language 2 which is the script language - * used by Draci Historie. This is a simple disassembler for the language. - * - * A compiled GPL2 program consists of a stream of bytes representing commands - * and their parameters. The syntax is as follows: - * - * Syntax of a command: - * - * - * Syntax of a parameter: - * - 1: integer number literally passed to the program - * - 2-1: string stored in the reservouir of game strings (i.e. something to be - * displayed) and stored as an index in this list - * - 2-2: string resolved by the compiler (i.e., a path to another file) and - * replaced by an integer index of this entity in the appropriate namespace - * (e.g., the index of the palette, location, ...) - * - 3-0: relative jump to a label defined in this code. Each label must be - * first declared in the beginning of the program. - * - 3-1 .. 3-9: index of an entity in several namespaces, defined in file ident - * - 4: mathematical expression compiled into a postfix format - * - * In the compiled program, parameters of type 1..3 are represented by a single - * 16-bit integer. The called command knows by its definition what namespace the - * value comes from. - */ - #include "common/debug.h" #include "common/stream.h" #include "common/stack.h" @@ -64,6 +33,8 @@ namespace Draci { // FIXME: Change parameter types to names once I figure out what they are exactly + +/** A table of all the commands the game player uses */ GPL2Command gplCommands[] = { { 0, 0, "gplend", 0, { 0 } }, { 0, 1, "exit", 0, { 0 } }, @@ -122,6 +93,7 @@ GPL2Command gplCommands[] = { { 27, 1, "FeedPassword", 3, { 1, 1, 1 } } }; +/** Operators used by the mathematical evaluator */ Common::String operators[] = { "oper_and", "oper_or", @@ -139,6 +111,7 @@ Common::String operators[] = { "oper_minus" }; +/** Functions used by the mathematical evaluator */ Common::String functions[] = { "F_Not", "F_Random", @@ -161,6 +134,7 @@ Common::String functions[] = { const unsigned int kNumCommands = sizeof gplCommands / sizeof gplCommands[0]; +/** Type of mathematical object */ enum mathExpressionObject { kMathEnd, kMathNumber, @@ -170,6 +144,12 @@ enum mathExpressionObject { }; // FIXME: The evaluator is now complete but I still need to implement callbacks + +/** + * @brief Evaluates mathematical expressions + * @param reader Stream reader set to the beginning of the expression + */ + void handleMathExpression(Common::MemoryReadStream &reader) { Common::Stack stk; mathExpressionObject obj; @@ -224,6 +204,15 @@ void handleMathExpression(Common::MemoryReadStream &reader) { return; } +/** + * @brief Find the current command in the internal table + * + * @param num Command number + * @param subnum Command subnumer + * + * @return NULL if command is not found. Otherwise, a pointer to a GPL2Command + * struct representing the command. + */ GPL2Command *findCommand(byte num, byte subnum) { unsigned int i = 0; while (1) { @@ -245,6 +234,37 @@ GPL2Command *findCommand(byte num, byte subnum) { return NULL; } +/** + * @brief GPL2 bytecode disassembler + * @param gplcode A pointer to the bytecode + * @param len Length of the bytecode + * + * GPL2 is short for Game Programming Language 2 which is the script language + * used by Draci Historie. This is a simple disassembler for the language. + * + * A compiled GPL2 program consists of a stream of bytes representing commands + * and their parameters. The syntax is as follows: + * + * Syntax of a command: + * + * + * Syntax of a parameter: + * - 1: integer number literally passed to the program + * - 2-1: string stored in the reservouir of game strings (i.e. something to be + * displayed) and stored as an index in this list + * - 2-2: string resolved by the compiler (i.e., a path to another file) and + * replaced by an integer index of this entity in the appropriate namespace + * (e.g., the index of the palette, location, ...) + * - 3-0: relative jump to a label defined in this code. Each label must be + * first declared in the beginning of the program. + * - 3-1 .. 3-9: index of an entity in several namespaces, defined in file ident + * - 4: mathematical expression compiled into a postfix format + * + * In the compiled program, parameters of type 1..3 are represented by a single + * 16-bit integer. The called command knows by its definition what namespace the + * value comes from. + */ + int gpldisasm(byte *gplcode, uint16 len) { Common::MemoryReadStream reader(gplcode, len); diff --git a/engines/draci/gpldisasm.h b/engines/draci/gpldisasm.h index d26fb5c978..17bd75767d 100644 --- a/engines/draci/gpldisasm.h +++ b/engines/draci/gpldisasm.h @@ -30,7 +30,14 @@ namespace Draci { -// FIXME: Add parameter types and function handlers +// FIXME: Add function handlers + +/** + * Represents a single command in the GPL scripting language bytecode. + * Each command is represented in the bytecode by a command number and a + * subnumber. + */ + struct GPL2Command { byte _number; byte _subNumber; @@ -39,7 +46,7 @@ struct GPL2Command { int _paramTypes[3]; }; -const int kMaxParams = 3; +const int kMaxParams = 3; //!< The maximum number of parameters for a GPL command int gpldisasm(byte *gplcode, uint16 len); -- cgit v1.2.3