diff --git a/src/text.h b/src/text.h index 7267979..0c1712f 100644 --- a/src/text.h +++ b/src/text.h @@ -2,257 +2,390 @@ #define TEXT_H #include "intraFont/intraFont.h" + +/** @file text.h + * @brief Text handling functions in OSLib. + * + * This file provides all text-related functions, structures, and macros + * necessary for rendering and managing fonts in OSLib, including + * loading custom fonts, handling intraFont, and drawing text on the screen. + * + * Don't forget to check the 'Debug Console' section (subsection of the 'Main' section) + * for further debugging-related functions. + */ + /** @defgroup text Text functions + * @brief Text functions in OSLib. + * + * This module provides various text-related functionalities, including font management, + * text drawing, and intraFont handling. + * @{ + */ - Text functions in OSLib. Don't forget to look at the 'Debug Console' section (subsection of the 'Main' section). - @{ -*/ - -/** Loaded font */ -typedef struct { - OSL_IMAGE *img; //!< Image containing character sprites - unsigned char *charWidths; //!< Table containing the width of each character (256 entries) - unsigned short *charPositions; //!< Position of characters in the image (16-bits: y:7, x:9) - int isCharWidthConstant; //!< Internal (pour savoir s'il faut libérer charWidth) - int charWidth; - int charHeight; //!< Height of characters (constant) - int recentrage; //!< Add this to text positions when drawing it (à ajouter aux positions pour le dessin du texte) - unsigned char addedSpace; //!< Space added between characters on the texture (allows to make characters bigger than indicated by charWidths) - int fontType; //!< Font type (OSL_FONT_OFT or OSL_FONT_INTRA) - intraFont *intra; //!< IntraFont data +/** @brief Loaded font structure. + * + * This struct represents a loaded font in OSLib, holding its image, character widths, + * positions, and other properties like font type and intraFont data. + */ +typedef struct { + OSL_IMAGE *img; //!< Image containing character sprites. + unsigned char *charWidths; //!< Table containing the width of each character (256 entries). + unsigned short *charPositions; //!< Position of characters in the image (16-bits: y:7, x:9). + int isCharWidthConstant; //!< Internal (to determine if charWidth needs to be freed). + int charWidth; //!< Width of characters. + int charHeight; //!< Height of characters (constant). + int recentrage; //!< Added to text positions when drawing. + unsigned char addedSpace; //!< Space added between characters on the texture (allows making characters bigger than indicated by charWidths). + int fontType; //!< Font type (OSL_FONT_OFT or OSL_FONT_INTRA). + intraFont *intra; //!< IntraFont data. } OSL_FONT; -/** Font information type */ -typedef struct { - void *fontdata; //!< Character image data - short pixelFormat; //!< 1 = 1 bit (default) - unsigned char *charWidths; //!< Width of characters - int charWidth; //!< Default char width (if charWidths is NULL) - int charHeight; //!< Height of characters (constant) - int lineWidth; //!< Number of bytes of data per line - int recentrage; //!< Added to text positions for drawing text (recentering) - unsigned char addedSpace; //!< Space added between the characters on the texture (allows to make characters graphically bigger than what indicated by charWidths) - unsigned short paletteCount; //!< Palette count - unsigned long *paletteData; //!< Palette data +/** @brief Font information type. + * + * This structure holds information about a font, including character image data, + * palette data, and information about character sizes and widths. + */ +typedef struct { + void *fontdata; //!< Character image data. + short pixelFormat; //!< 1 = 1 bit (default). + unsigned char *charWidths; //!< Width of characters. + int charWidth; //!< Default character width (if charWidths is NULL). + int charHeight; //!< Height of characters (constant). + int lineWidth; //!< Number of bytes of data per line. + int recentrage; //!< Added to text positions for drawing text (recentering). + unsigned char addedSpace; //!< Space added between characters on the texture. + unsigned short paletteCount; //!< Palette count. + unsigned long *paletteData; //!< Palette data. } OSL_FONTINFO; -/** Header of a .oft file (Oslib FonT) */ -typedef struct { - char strVersion[12]; //!< "OSLFont v01" - unsigned char pixelFormat; //!< Number of bits per pixel (1 = 1 bit, default) - unsigned char variableWidth; //!< If true, the first 256 bytes of data specify the character widths - int charWidth, charHeight; //!< Mean character sizes (used for the console) - int lineWidth; //!< Number of bytes of data per line - unsigned char addedSpace; //!< Space added between the characters on the texture (allows to make characters graphically bigger than what indicated by charWidths) - unsigned short paletteCount; //!< Text palette data - unsigned char reserved[29]; //!< Must be null (reserved) +/** @brief Header of a .oft file (Oslib FonT). + * + * This structure represents the header for a font file used in OSLib. + */ +typedef struct { + char strVersion[12]; //!< "OSLFont v01". + unsigned char pixelFormat; //!< Number of bits per pixel (1 = 1 bit, default). + unsigned char variableWidth; //!< True if the first 256 bytes specify the character widths. + int charWidth, charHeight; //!< Mean character sizes (used for the console). + int lineWidth; //!< Number of bytes of data per line. + unsigned char addedSpace; //!< Space added between characters on the texture. + unsigned short paletteCount; //!< Palette count. + unsigned char reserved[29]; //!< Must be null (reserved). } OSL_FONT_FORMAT_HEADER; -/** Current font. You can read from it but please do not write to it, use #oslSetFont instead. */ +/** Current font. + * + * This pointer holds the currently selected font for text rendering. + * You can read from it, but use #oslSetFont to modify it. + */ extern OSL_FONT *osl_curFont; -/** Sets the current font. For forward compatibilty, please use this function rather than osl_curFont = yourFont. - -\code -//Save the current font -OSL_FONT *oldFont = osl_curFont; -//Temporarily set another font -oslSetFont(newFont); -oslPrintf("Using the new font.\n"); -//Restore the old font -oslSetFont(oldFont); -oslPrintf("Using the normal font.\n"); -\endcode */ -#define oslSetFont(f) (osl_curFont = f) -//extern void oslSetFont(OSL_FONT *f); - -//System defines +/** @brief Sets the current font. + * + * Sets the current font to the specified font. Use this function instead of + * directly modifying #osl_curFont for forward compatibility. + * + * @param f Pointer to the new font to be set as the current font. + * + * \code + * // Save the current font + * OSL_FONT *oldFont = osl_curFont; + * // Temporarily set another font + * oslSetFont(newFont); + * oslPrintf("Using the new font.\n"); + * // Restore the old font + * oslSetFont(oldFont); + * oslPrintf("Using the normal font.\n"); + * \endcode + */ +#define oslSetFont(f) (osl_curFont = f) + +// System defines #define OSL_TEXT_TEXWIDTH 512 #define OSL_TEXT_TEXDECAL 9 -/**Font type OFT*/ +// Font type defines +/** @brief Font type for OFT. */ #define OSL_FONT_OFT 1 -/**Font type INTRA*/ +/** @brief Font type for INTRA. */ #define OSL_FONT_INTRA 2 -//Returns the position of a character 'i' in the font 'f' texture as a pair (x, y). -#define OSL_TEXT_CHARPOSXY(f,i) (f)->charPositions[i]&(OSL_TEXT_TEXWIDTH-1), ((f)->charPositions[i]>>OSL_TEXT_TEXDECAL)*(f)->charHeight +// Character position macro +/** @brief Returns the position of a character 'i' in the font 'f' texture as a pair (x, y). + * @param f The font structure. + * @param i The character index. + */ +#define OSL_TEXT_CHARPOSXY(f,i) (f)->charPositions[i]&(OSL_TEXT_TEXWIDTH-1), ((f)->charPositions[i]>>OSL_TEXT_TEXDECAL)*(f)->charHeight -/** Initializes the console. You do not need to call this anymore, as it's automatically done upon #oslInitGfx. */ +/** @brief Initializes the console. + * + * This function is automatically called by #oslInitGfx, so manual initialization + * of the console is not required. + */ extern void oslInitConsole(); -/** Loads a font from a file. Remember that you can load virtual files located in RAM, see the VirtualFile section for more information. Also, there is an application (font2osl) which converts fonts to -the OldSchool Library Font format (.oft). - -\code -OSL_FONT *f = oslLoadFontFile("verdana.oft"); -oslSetFont(f); -oslDrawString(0, 0, "Hello world using verdana!"); -\endcode */ +/** @brief Loads a font from a file. + * + * Loads a font file (.oft format) from the specified file path. + * + * @param filename The path to the .oft font file. + * @return A pointer to the loaded font. + * + * \code + * OSL_FONT *f = oslLoadFontFile("verdana.oft"); + * oslSetFont(f); + * oslDrawString(0, 0, "Hello world using verdana!"); + * \endcode + */ extern OSL_FONT *oslLoadFontFile(const char *filename); -/** Loads a font from a #OSL_FONTINFO file (located in RAM). Rather use oslLoadFontFile, which is more friendly. -Use this ONLY with OFT fonts (doesen't work with intraFont). -*/ +/** @brief Loads a font from a #OSL_FONTINFO file (located in RAM). + * + * Use this ONLY with OFT fonts (doesn't work with intraFont). It is recommended + * to use oslLoadFontFile, which is more user-friendly. + * + * @param fi A pointer to the OSL_FONTINFO structure in RAM. + * @return A pointer to the loaded font. + */ extern OSL_FONT *oslLoadFont(OSL_FONTINFO *fi); -/** Draws a single character at the specified x and y positions. -If you must draw several characters placed one after the other, use oslDrawString, as indiviudal oslDrawChar calls will be slightly slower. */ +/** @brief Draws a character at the specified position. + * + * This function draws a single character at the given coordinates (x, y). For drawing multiple characters, + * use oslDrawString for better performance. + * + * @param x X position on the screen. + * @param y Y position on the screen. + * @param c The character to draw. + */ extern void oslDrawChar(int x, int y, unsigned char c); -/** Draws a string litteral at the specified x and y positions. - -\code -oslDrawString(0, 0, "Test string"); -\endcode */ +/** @brief Draws a string literal at the specified position. + * + * This function draws a string at the given coordinates (x, y). + * + * @param x X position on the screen. + * @param y Y position on the screen. + * @param str The string to draw. + * + * \code + * oslDrawString(0, 0, "Test string"); + * \endcode + */ extern void oslDrawString(int x, int y, const char *str); -/** Draws a string litteral at the specified x and y positions limiting it to a given width. - -\code -oslDrawStringLimited(0, 0, 200, "Test string"); -\endcode */ +/** @brief Draws a string literal at the specified position, limited to a given width. + * + * This function draws a string at the given coordinates (x, y) but limits the drawing + * to a specified width. + * + * @param x X position on the screen. + * @param y Y position on the screen. + * @param width The maximum width for the string. + * @param str The string to draw. + * + * \code + * oslDrawStringLimited(0, 0, 200, "Test string"); + * \endcode + */ extern void oslDrawStringLimited(int x, int y, int width, const char *str); -/** Draws a formatted string litteral at the specified x and y positions. - -\code -oslDrawStringf(0, 0, "Test string %i", 1); -\endcode */ -#define oslDrawStringf(x, y, ...) { char __str[1000]; sprintf(__str , __VA_ARGS__); oslDrawString(x, y, __str); } +/** @brief Draws a formatted string literal at the specified position. + * + * This function allows you to format a string and draw it at the specified coordinates (x, y). + * + * @param x X position on the screen. + * @param y Y position on the screen. + * @param ... The formatted string to draw. + * + * \code + * oslDrawStringf(0, 0, "Test string %i", 1); + * \endcode + */ +#define oslDrawStringf(x, y, ...) { char __str[1000]; sprintf(__str , __VA_ARGS__); oslDrawString(x, y, __str); } -/** Outputs a text to the console at the current cursor position, and moves it. Here for debugging purposes, not very useful in a game. */ +/** @brief Outputs a text to the console at the current cursor position. + * + * This function prints a string to the console at the current cursor position and moves + * the cursor. It is intended for debugging purposes. + * + * @param str The string to print. + */ extern void oslConsolePrint(const char *str); -/** Sets the current text color. -This doesen't work with intraFont (use oslIntraFontSetStyle) -*/ +/** @brief Sets the current text color. + * + * Sets the color of the text to be drawn. This function does not work with intraFont + * (use oslIntraFontSetStyle instead). + * + * @param color The color to set for the text. + */ extern void oslSetTextColor(OSL_COLOR color); -/** Sets the text background color. Setting a transparent color (e.g. RGBA(0, 0, 0, 0)) will disable drawing a background. In this case, the text rendering will be faster. -This doesen't work with intraFont (use oslIntraFontSetStyle) -*/ +/** @brief Sets the text background color. + * + * Sets the background color for the text. Setting a transparent color (e.g., RGBA(0, 0, 0, 0)) + * will disable the background, resulting in faster text rendering. This function does not work + * with intraFont (use oslIntraFontSetStyle instead). + * + * @param color The background color to set. + */ extern void oslSetBkColor(OSL_COLOR color); -/** Draws a text box, that is, text contained in a rectangle. The text will automatically be wrapped at the end of a line and be placed below. - \param x0, y0 - Top-left corner of the text box. - \param x1, y1 - Bottom-right corner of the text box. - \param text - Text to be drawn. Can contain \n characters to make a carriage return. - \param format - Let it 0. -*/ +/** @brief Draws a text box with automatic line wrapping. + * + * Draws text within a rectangle defined by (x0, y0) and (x1, y1). The text will automatically wrap + * at the end of a line and move to the next line. + * + * @param x0 X position of the top-left corner. + * @param y0 Y position of the top-left corner. + * @param x1 X position of the bottom-right corner. + * @param y1 Y position of the bottom-right corner. + * @param text The text to be drawn. Can contain \n characters for line breaks. + * @param format Reserved, set to 0. + */ extern void oslDrawTextBox(int x0, int y0, int x1, int y1, const char *text, int format); -/** Draws a text box, that is, text contained in a rectangle. The text will automatically be wrapped at the end of a line and be placed below. - Draw text by word's and not by char's - \param x0, y0 - Top-left corner of the text box. - \param x1, y1 - Bottom-right corner of the text box. - \param text - Text to be drawn. Can contain \n characters to make a carriage return. - \param format - Let it 0. -*/ +/** @brief Draws a text box with automatic word wrapping. + * + * Similar to oslDrawTextBox, but wraps the text by words instead of characters. + * + * @param x0 X position of the top-left corner. + * @param y0 Y position of the top-left corner. + * @param x1 X position of the bottom-right corner. + * @param y1 Y position of the bottom-right corner. + * @param text The text to be drawn. Can contain \n characters for line breaks. + * @param format Reserved, set to 0. + */ extern void oslDrawTextBoxByWords(int x0, int y0, int x1, int y1, const char *text, int format); -/** Deletes a font. - -\b Warning: the font must NOT be currently selected (that is f != #osl_curFont) else your program will crash the next time you'll try to draw a character (or later). */ +/** @brief Deletes a font. + * + * Deletes the specified font. Ensure that the font to be deleted is not currently selected + * (i.e., f != #osl_curFont), or the program will crash the next time you attempt to draw a character. + * + * @param f The font to be deleted. + */ extern void oslDeleteFont(OSL_FONT *f); -/** Returns the size (in pixels) of a text, using the currently selected font. Note that you can get the height of the text and some other parameters by exploring the #OSL_FONT structure. The following -sample shows you how to center a text horizontally and align it to the bottom of the screen: - -\code -const char *text = "© 2007 Brunni"; -int width = oslGetStringWidth(text); -oslDrawString((SCREEN_WIDTH - width) / 2, SCREEN_HEIGHT - osl_curFont->charHeight, text); -\endcode */ +/** @brief Returns the width of a string in pixels. + * + * Calculates the width of a string using the currently selected font. To center text horizontally + * or align it at the bottom of the screen, use this function to get the width. + * + * @param str The string whose width is to be calculated. + * @return The width of the string in pixels. + * + * \code + * const char *text = "© 2007 Brunni"; + * int width = oslGetStringWidth(text); + * oslDrawString((SCREEN_WIDTH - width) / 2, SCREEN_HEIGHT - osl_curFont->charHeight, text); + * \endcode + */ extern int oslGetStringWidth(const char *str); -/** Returns the height (in pixels) which would take a text box drawn with #oslDrawTextBox. */ +/** @brief Returns the height of a text box. + * + * Calculates the height (in pixels) required to draw a text box with the specified width, + * maxHeight, and format. + * + * @param width The width of the text box. + * @param maxHeight The maximum height of the text box. + * @param text The text to be drawn. + * @param format Reserved, set to 0. + * @return The height of the text box in pixels. + */ extern int oslGetTextBoxHeight(int width, int maxHeight, const char *text, int format); -/** Console horizontal position (in pixels). Use #oslMoveTo to move the cursor. */ +/** Console horizontal position (in pixels). + * Use #oslMoveTo to move the cursor. + */ extern int osl_consolePosX; + /** Console vertical position (in pixels). */ extern int osl_consolePosY; -/** System OSLib font. */ +/** @brief System OSLib font. + * + * A pointer to the system font used by OSLib. + */ extern OSL_FONT *osl_sceFont; -//Font to be loaded +/** @brief Font to be loaded. + * + * Holds information about the system font to be loaded. + */ extern OSL_FONTINFO osl_sceFontInfo; -//IntraFont functions: -/**Inits intraFont (MUST be called before loading any pgf font). -The same options will be applied to all intraFonts - \param options - INTRAFONT_XXX flags as defined above including flags related to CACHE (ored together) - -\code -#define INTRAFONT_ADVANCE_H 0x00000000 //default: advance horizontaly from one char to the next -#define INTRAFONT_ADVANCE_V 0x00000100 -#define INTRAFONT_ALIGN_LEFT 0x00000000 //default: left-align the text -#define INTRAFONT_ALIGN_CENTER 0x00000200 -#define INTRAFONT_ALIGN_RIGHT 0x00000400 -#define INTRAFONT_WIDTH_VAR 0x00000000 //default: variable-width -#define INTRAFONT_WIDTH_FIX 0x00000800 //set your custom fixed witdh to 24 pixels: INTRAFONT_WIDTH_FIX | 24 - //(max is 255, set to 0 to use default fixed width, this width will be scaled by size) -#define INTRAFONT_ACTIVE 0x00001000 //assumes the font-texture resides inside sceGuTex already, prevents unecessary reloading -> very small speed-gain -#define INTRAFONT_STRING_ASCII 0x00000000 //default: interpret strings as ascii text -#define INTRAFONT_STRING_SJIS 0x00002000 //interpret strings as shifted-jis (japanese) -#define INTRAFONT_STRING_UTF8 0x00010000 //interpret strings as UTF-8 -#define INTRAFONT_CACHE_MED 0x00000000 //default: 256x256 texture (enough to cache about 100 chars) -#define INTRAFONT_CACHE_LARGE 0x00004000 //512x512 texture(enough to cache all chars of ltn0.pgf or ... or ltn15.pgf or kr0.pgf) -#define INTRAFONT_CACHE_ASCII 0x00008000 //try to cache all ASCII chars during fontload (uses less memory and is faster to draw text, but slower to load font) - - //if it fails: (because the cache is too small) it will automatically switch to chache on-the-fly with a medium texture - //if it succeeds: (all chars and shadows fit into chache) it will free some now unneeded memory -#define INTRAFONT_CACHE_ALL 0x0000C000 //try to cache all chars during fontload (uses less memory and is faster to draw text, but slower to load font) - //if it fails: (because the cache is too small) it will automatically switch to chache on-the-fly with a large texture - //if it succeeds: (all chars and shadows fit into chache) it will free some now unneeded memory -\endcode -*/ +// IntraFont functions: +/** @brief Initializes intraFont. + * + * Must be called before loading any pgf font. The same options will be applied + * to all intraFonts. + * + * @param options INTRAFONT_XXX flags as defined in the code above. + * @return 0 on success, non-zero on failure. + */ extern int oslIntraFontInit(unsigned int options); -/** Loads a font from a pgf file (intraFont). Use this if you want to load a pgf font with options different from the one passed to oslIntraFontInit. - -\code -OSL_FONT *f = oslLoadIntraFontFile("verdana.pgf", INTRAFONT_CACHE_ALL | INTRAFONT_STRING_UTF8); -oslSetFont(f); -oslDrawString(0, 0, "Hello world using verdana!"); -\endcode */ +/** @brief Loads a font from a pgf file (intraFont). + * + * Use this function to load a pgf font with options different from those passed + * to oslIntraFontInit. + * + * @param filename The path to the pgf font file. + * @param options The options for loading the font. + * @return A pointer to the loaded font. + * + * \code + * OSL_FONT *f = oslLoadIntraFontFile("verdana.pgf", INTRAFONT_CACHE_ALL | INTRAFONT_STRING_UTF8); + * oslSetFont(f); + * oslDrawString(0, 0, "Hello world using verdana!"); + * \endcode + */ extern OSL_FONT *oslLoadIntraFontFile(const char *filename, unsigned int options); -extern void oslLoadAltIntraFontFile(OSL_FONT *font, const char *filename); -/**Sets style for a pgf font (works ONLY with pgf font) */ -extern void oslIntraFontSetStyle(OSL_FONT *f, float size, unsigned int color, unsigned int shadowColor, float angle, unsigned int options); - -/** - * Draw text along the baseline starting at x, y. +/** @brief Loads an alternative intraFont file. * - * @param f - A valid ::OSL_FONT with type ::OSL_FONT_INTRA + * Use this function to load an alternative font file for an existing font. * - * @param x - X position on screen + * @param font The font structure to update. + * @param filename The path to the alternative font file. + */ +extern void oslLoadAltIntraFontFile(OSL_FONT *font, const char *filename); + +/** @brief Sets the style for a pgf font. * - * @param y - Y position on screen + * Applies the specified style to the pgf font. Works only with pgf fonts. * - * @param width - column width for automatic line breaking (intraFontPrintColumn... versions only) + * @param f The font structure. + * @param size The size of the font. + * @param color The color of the text. + * @param shadowColor The color of the text shadow. + * @param angle The rotation angle of the text. + * @param options Additional style options. + */ +extern void oslIntraFontSetStyle(OSL_FONT *f, float size, unsigned int color, unsigned int shadowColor, float angle, unsigned int options); + +/** @brief Draws text along the baseline starting at x, y. * - * @param text - Text to draw (ASCII & extended ASCII, S-JIS or UTF-8 encoded) + * Draws text along the baseline starting at the specified (x, y) coordinates. * - * @returns The x position after the last char + * @param f A valid ::OSL_FONT with type ::OSL_FONT_INTRA. + * @param x X position on the screen. + * @param y Y position on the screen. + * @param width Column width for automatic line breaking (intraFontPrintColumn versions only). + * @param text The text to draw (ASCII & extended ASCII, S-JIS, or UTF-8 encoded). + * @return The x position after the last character. */ extern float oslIntraFontPrintColumn(OSL_FONT *f, float x, float y, float width, const char *text); -/**Shuts down intraFont */ +/** @brief Shuts down intraFont. + * + * Cleans up and shuts down intraFont, freeing any allocated resources. + */ extern void oslIntraFontShutdown(); -/** @} */ // end of text +/** @} */ // end of text group -#endif +#endif // TEXT_H