include/font.H

   1 /****************************************************************************************/\r
   2 /*  FONT.H                                                                              */\r
   3 /*                                                                                      */\r
   4 /*  Author: Thom Robertson                                                              */\r
   5 /*  Description: Bitmapped font support interface                                       */\r
   6 /*               This implementation supports any TrueType fonts provided by Windows    */\r
   7 /*                                                                                      */\r
   8 /*  The contents of this file are subject to the Genesis3D Public License               */\r
   9 /*  Version 1.01 (the "License"); you may not use this file except in                   */\r
  10 /*  compliance with the License. You may obtain a copy of the License at                */\r
  11 /*  http://www.genesis3d.com                                                            */\r
  12 /*                                                                                      */\r
  13 /*  Software distributed under the License is distributed on an "AS IS"                 */\r
  14 /*  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See                */\r
  15 /*  the License for the specific language governing rights and limitations              */\r
  16 /*  under the License.                                                                  */\r
  17 /*                                                                                      */\r
  18 /*  The Original Code is Genesis3D, released March 25, 1999.                            */\r
  19 /*  Genesis3D Version 1.1 released November 15, 1999                                 */\r
  20 /*  Copyright (C) 1999 WildTangent, Inc. All Rights Reserved           */\r
  21 /*                                                                                      */\r
  22 /****************************************************************************************/\r
  23 #ifndef GE_FONT_H\r
  24 #define GE_FONT_H\r
  25 \r
  26 // includes\r
  27 #include "genesis.h"\r
  28 #include "basetype.h"\r
  29 #include "bitmap.h"\r
  30 // **************************\r
  31 // to use this API:\r
  32 \r
  33 // 2.  geFont_CreateFont().\r
  34 \r
  35 // 3.  (Optionally) geFont_AddCharacters().\r
  36 // 3A. Otherwise, IF you intend to use geFont_DrawText(), call geFont_AddBitmapBuffer().\r
  37 \r
  38 // 4.  Between geEngine_BeginFrame() and geEngine_EndFrame(), and after geEngine_RenderWorld(),\r
  39 //       geFont_DrawText(). You may call geFont_DrawTextToBitmap() anytime, though.\r
  40 \r
  41 // 5.  When finished, geFont_Destroy().\r
  42 \r
  43 \r
  44 \r
  45 //*************************************************************************************** \r
  46 // these are bit flags for _DrawText(). Currently only _WORDWRAP is implemented, and without\r
  47 // it, the function will still wrap, just not on word boundaries.\r
  48 // Note that these will fail for non ascii fonts.\r
  49 #define GE_FONT_WRAP                0x00000001  // wrap to fit inside the drawing rect\r
  50 #define GE_FONT_WORDWRAP            0x00000002  // wrap on word boundaries\r
  51 #define GE_FONT_JUST_RETURN_FIT     0x00000004  // returns number of characters that fit in drawing rectangle, WITHOUT drawing anything.\r
  52 #define GE_FONT_JUSTIFY_RIGHT       0x00000008\r
  53 #define GE_FONT_JUSTIFY_CENTER      0x00000010\r
  54 \r
  55 #ifdef __cplusplus\r
  56 extern "C" {\r
  57 #endif\r
  58 \r
  59 // opaque structure headers.\r
  60 typedef struct geFont geFont;                   // an instance of a font\r
  61 \r
  62 \r
  63 //*************************************************************************************** \r
  64 GENESISAPI geFont *GENESISCC geFont_Create(const geEngine *Engine, const char *fontNameString, \r
  65                                                const int fontSize,\r
  66                                                                                            const int fontWeight , const geBoolean antialiased) ;\r
  67    // Creates a font, and returns a pointer to it.\r
  68    // Pass in the string name of the TrueType font (case sensitive), and the height in pixels.\r
  69    \r
  70    // ARGUMENTS:\r
  71    // fontNameString - char pointer to a string containing the case sensitive name of the font.\r
  72    // fontSize - the pixel height of the requested font.\r
  73 \r
  74    // RETURNS:\r
  75    // success: pointer to the newly created font.\r
  76    // failure: NULL.\r
  77 \r
  78    // NOTE: the new font set has NO actual characters in it at first.  You must add characters\r
  79    // to it with the _AddCharacters() function before you can use the font.\r
  80    // NOTE: all fonts start out with a grayscale palette, with the range 0 to 128.\r
  81 \r
  82 //*************************************************************************************** \r
  83 GENESISAPI void GENESISCC geFont_CreateRef(geFont *font);\r
  84 \r
  85 \r
  86 //*************************************************************************************** \r
  87 GENESISAPI void GENESISCC geFont_Destroy(geFont **font);\r
  88    // destroys a font.\r
  89 \r
  90    // ARGUMENTS:\r
  91    // font - pointer to the font to be destroyed.\r
  92 \r
  93    // RETURNS:\r
  94    // nothing.\r
  95 \r
  96 //*************************************************************************************** \r
  97 GENESISAPI geBoolean GENESISCC geFont_AddCharacters(geFont *font, \r
  98                                                   unsigned char leastIndex, \r
  99                                                   unsigned char mostIndex\r
 100                                                   );\r
 101    // Adds a set of characters to the font defined by the ascii range passed in \r
 102    // (leastIndex and mostIndex, inclusive).\r
 103 \r
 104    // ARGUMENTS:\r
 105    // font - pointer to the font to add characters to.\r
 106    // e - pointer to a valid geEngine.\r
 107    // leastIndex and mostIndex - the ASCII range of characters to add.\r
 108    // cellBuffer - an allocated hunk of ram to temproarily store the character image\r
 109    // bufferSize - length of the above buffer\r
 110 \r
 111    // RETURNS:\r
 112    // success: GE_TRUE.\r
 113    // failure: GE_FALSE.\r
 114 \r
 115    // NOTES:\r
 116    // This is the function that actually uses the\r
 117    // Win32 GetGlyphOutline() function to draw the character onto a geBitmap, which can be\r
 118    // blitted to the screen.\r
 119 \r
 120 \r
 121 //*******************************************************************************\r
 122 GENESISAPI void GENESISCC geFont_DestroyBitmapBuffer( geFont *font );\r
 123    // destroys any valid "scratch-pad" buffer attached to the geFont.\r
 124    // ARGUMENTS:\r
 125    // font - pointer to the geFont.\r
 126    //\r
 127    // NOTES:\r
 128    // you'll rarely need to call this function; it's called by geFont_Destroy() anyway.\r
 129    // Calling this function with a geFont that has no initialized buffer doesn't\r
 130    // hurt anything.\r
 131 \r
 132 //*******************************************************************************\r
 133 GENESISAPI geBoolean GENESISCC geFont_AddBitmapBuffer(\r
 134                                   geFont *font, const uint32 width, const uint32 height);\r
 135    // Adds a geBitmap to the geFont, to be used as a temporary "scratch-pad".  This is\r
 136    // required for using geFont_DrawText() when no characters have been added.\r
 137 \r
 138    // ARGUMENTS:\r
 139    // font - pointer to the geFont to add a buffer to.\r
 140    // width and height - the size of the buffer to create.  Make sure this size is >=\r
 141    // the biggest rectagle of text you'll want to write to the screen using this geFont\r
 142    // and DrawText().\r
 143 \r
 144    // RETURNS:\r
 145    // success: GE_TRUE.\r
 146    // failure: GE_FALSE.\r
 147 \r
 148    // NOTES:\r
 149    // You don't need to call this function IF you _AddCharacters() to this geFont.\r
 150    // You call this function for each geFont you need to use.  geFont's don't share buffers.\r
 151    // if you call this function on a geFont that already has a valid buffer, the buffer is\r
 152    // destroyed, and replaced by the new one.\r
 153 \r
 154 //*************************************************************************************** \r
 155 GENESISAPI geBoolean GENESISCC geFont_DrawText(geFont *font, const char *textString, \r
 156                                            const GE_Rect *Rect, const GE_RGBA *Color, \r
 157                                            uint32 flags, const GE_Rect *clipRect);\r
 158    // This is the function you put between geEngine_BeginFrame() and _EndFrame(), the function\r
 159    // that draws text to the screen.\r
 160 \r
 161    // ARGUMENTS:\r
 162    // font - pointer to the font to draw with.  IF the font has NO characters in it\r
 163    //  (added by geFont_AddCharacters() ) then a different, more windows-intensive way is\r
 164    //  used to draw out the characters.\r
 165    // textString - pointer to the text string to output to the screen.\r
 166    // Rect - screen rectangle to place the text within.\r
 167    // Color - RGB color the text should be.\r
 168    // flags - a bitfield of GE_FONT_ values.\r
 169    // clipRect - pointer to a screen rectangle to clip the text to.  MAY BE NULL, in which\r
 170    // case the text is only clipped by the boundaries of the screen.\r
 171 \r
 172    // RETURNS:\r
 173    // success: GE_TRUE.\r
 174    // failure: GE_FALSE.\r
 175 \r
 176    // NOTES:\r
 177    // Assuming you've added characters to the font, characters which have NOT been added\r
 178    // WILL cause an assert if you try to draw them.  \r
 179    // Only GE_FONTSET_WORDWRAP is meaningfull right now.  Using any other flags will cause\r
 180    // an assert.\r
 181    // As stated above, you can use an entirely different way of creating a string, by\r
 182    // making a font with no characters in it.  This\r
 183    // jumps through Windows DIB hoops, and draws the text in a non-anti-aliased, but\r
 184    // (hopefully) more unicode-tolerant way (DrawText() ).\r
 185 \r
 186 \r
 187 //*************************************************************************************** \r
 188 GENESISAPI geBoolean GENESISCC geFont_DrawTextToBitmap(geFont *font, const char *textString, \r
 189                                            const GE_Rect *Rect, const GE_RGBA *Color, \r
 190                                            uint32 flags, const GE_Rect *clipRect,\r
 191                                            geBitmap *targetBitmap);\r
 192    // This is the function you put between geEngine_BeginFrame() and _EndFrame(), the function\r
 193    // that draws text to the screen.\r
 194 \r
 195    // ARGUMENTS:\r
 196    // font - pointer to the font to draw with.  IF the font has NO characters in it\r
 197    //  (added by geFont_AddCharacters() ) then a different, more windows-intensive way is\r
 198    //  used to draw out the characters.\r
 199    // textString - pointer to the text string to output to the screen.\r
 200    // Rect - screen rectangle to place the text within.\r
 201    // Color - RGB color the text should be.\r
 202    // flags - a bitfield of GE_FONT_ values.\r
 203    // clipRect - pointer to a screen rectangle to clip the text to.  MAY BE NULL, in which\r
 204    // case the text is only clipped by the boundaries of the screen.\r
 205    // targetBitmap - pointer to a target bitmap to draw the text into.  MAY NOT BE NULL,\r
 206    // and MUST BE GE_PIXELFORMAT_8BIT.\r
 207 \r
 208    // RETURNS:\r
 209    // success: GE_TRUE.\r
 210    // failure: GE_FALSE.\r
 211 \r
 212    // NOTES:\r
 213    // Assuming you've added characters to the font, characters which have NOT been added\r
 214    // WILL cause an assert if you try to draw them.  \r
 215    // Only GE_FONTSET_WORDWRAP is meaningfull right now.  Using any other flags will cause\r
 216    // an assert.\r
 217    // As stated above, you can use an entirely different way of creating a string, by\r
 218    // making a font with no characters in it.  This\r
 219    // jumps through Windows DIB hoops, and draws the text in a non-anti-aliased, but\r
 220    // (hopefully) more unicode-tolerant way (DrawText() ).\r
 221    // The Color argument is will be used to modify the existing palette of the targetBitmap\r
 222    // passed in.  Therefore, you won't be able to _DrawTextToBitmap() a red piece of text,\r
 223    // then a green piece, then a blue piece.  You'll end up with three lines of blue text.\r
 224 \r
 225 \r
 226 //*************************************************************************************** \r
 227 GENESISAPI int32 GENESISCC geFont_GetStringPixelWidth (geFont *font, const char *textString);\r
 228 GENESISAPI int32 GENESISCC geFont_GetStringPixelHeight(geFont *font, const char *textString);\r
 229    // These two functions return the pixel width and height of the string passed in.\r
 230 \r
 231    // ARGUMENTS:\r
 232    // font - pointer to the font to draw with.\r
 233    // textString - pointer to the text string to output to the screen.\r
 234 \r
 235    // RETURNS:\r
 236    // success: a positive value in pixels.  IF the text passed in contains characters\r
 237    //          which haven't been added to the font yet, BUT other characters HAVE\r
 238    //          been added, the function asserts.\r
 239    // failure: -1.\r
 240    // NOTES:\r
 241    // these two functions assume no text wrapping!\r
 242 \r
 243 //*************************************************************************************** \r
 244 GENESISAPI geBitmap* GENESISCC geFont_GetBuffer(geFont *font);\r
 245    // This function returns a pointer to the drawing buffer contained by the font.\r
 246 \r
 247    // ARGUMENTS:\r
 248    // font - pointer to the font.\r
 249 \r
 250    // RETURNS:\r
 251    // a valid pointer to a geBitmap, OR NULL, signifying that the buffer wasn't initialized.\r
 252 \r
 253 \r
 254 //*************************************************************************************** \r
 255 GENESISAPI geBoolean GENESISCC geFont_GetCharMap(geFont *font, uint8 character, GE_Rect *Rect, \r
 256                                                                                                  geBitmap **targetBitmap, int32 *fullWidth, int32 *fullHeight, \r
 257                                                                                                  int32 *offsetX, int32 *offsetY);\r
 258 \r
 259 //*************************************************************************************** \r
 260 GENESISAPI void GENESISCC geFont_EnableAntialiasing(geFont *font, const geBoolean anti);\r
 261 //*************************************************************************************** \r
 262 GENESISAPI geBoolean GENESISCC geFont_IsAntialiased(geFont *font);\r
 263 \r
 264 #ifdef __cplusplus\r
 265 }\r
 266 #endif\r
 267 \r
 268 #endif\r
 269 \r