1 /* 2 Copyright (C) 2010 COR Entertainment, LLC. 3 4 This program is free software; you can redistribute it and/or 5 modify it under the terms of the GNU General Public License 6 as published by the Free Software Foundation; either version 2 7 of the License, or (at your option) any later version. 8 9 This program is distributed in the hope that it will be useful, 10 but WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 12 13 See the GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with this program; if not, write to the Free Software 17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 18 */ 19 #ifndef __R_TEXT_H 20 #define __R_TEXT_H 21 22 /* Forward-declare the face structure and its pointer type */ 23 struct FNT_face_s; 24 typedef struct FNT_face_s * FNT_face_t; 25 26 /* Forward-declare the font structure and its pointer type */ 27 struct FNT_font_s; 28 typedef struct FNT_font_s * FNT_font_t; 29 30 /* Forward-declare the text window structure and its pointer type */ 31 struct FNT_window_s; 32 typedef struct FNT_window_s * FNT_window_t; 33 34 35 36 /**************************************************************************/ 37 /* CONSTANTS */ 38 /**************************************************************************/ 39 40 /* Maximal length of a font file's base name */ 41 #define FNT_FACE_NAME_MAX 48 42 43 /* Maximal length of a font key ("font name!font size") */ 44 #define FNT_FONT_KEY_MAX ( FNT_FACE_NAME_MAX + 11 ) 45 46 /* Color modes */ 47 #define FNT_CMODE_NONE 0 // Ignore color codes 48 #define FNT_CMODE_QUAKE 1 // Use Quake color codes 49 #define FNT_CMODE_QUAKE_SRS 2 // Use Quake color codes, but 50 // reset to default color when 51 // space is found 52 #define FNT_CMODE_TWO 3 // Use two colors, with bit 7 53 // of the string's characters 54 // to indicate the second one; 55 // Quake color codes will be 56 // stripped out. 57 58 /* Text alignment */ 59 #define FNT_ALIGN_LEFT 0 60 #define FNT_ALIGN_RIGHT 1 61 #define FNT_ALIGN_CENTER 2 62 63 /* Color table for Quake colors */ 64 extern float FNT_colors[ 8 ][ 4 ]; 65 66 67 68 /**************************************************************************/ 69 /* FUNCTION TYPES FOR FACES AND FONTS */ 70 /**************************************************************************/ 71 72 73 /* 74 * Face destruction function 75 * 76 * Parameters: 77 * face the face to destroy 78 */ 79 typedef void (* FNT_DestroyFace_funct)( FNT_face_t face ); 80 81 82 /* 83 * Font loader function - used by faces when initialising a font. 84 * 85 * Parameters: 86 * font a font structure where everything except the 87 * internal structure pointer has been initialised 88 * 89 * Returns: 90 * true on success, false on failure 91 */ 92 typedef qboolean (* FNT_GetFont_funct )( FNT_font_t font ); 93 94 95 /* 96 * Raw printing function. 97 * 98 * Used to draw some text at a specific location using a fixed colour. 99 * 100 * Parameters: 101 * font the font to draw text with 102 * text pointer to the string to draw 103 * text_length length of the string to draw 104 * r2l false for left-to-right, true for right-to-left 105 * x , y coordinates to start from 106 * color (R,G,B,A) colour to apply when drawing 107 * 108 * Notes: 109 * 1/ All control or non-ASCII characters will be skipped. 110 * 2/ No checks will be made regarding the string's end, only the 111 * specified length will be used. 112 * 3/ In right-to-left mode, the string will be read backwards. 113 */ 114 typedef void (* FNT_RawPrint_funct )( 115 FNT_font_t font , 116 const char * text , 117 unsigned int text_length , 118 qboolean r2l , 119 float x , 120 float y , 121 const float color[4] ); 122 123 124 /* 125 * Bounded printing function 126 * 127 * Draws a string in a region; does not perform wrapping, everything that is 128 * out of the specified box is ignored. 129 * 130 * Parameters: 131 * font the font to use 132 * text the text to draw 133 * cmode the color coding to use 134 * align the text's alignment 135 * box the text's window 136 * color the color (or colors) to use 137 * 138 * Notes: 139 * 1/ The initial window must include a valid width. 140 * 2/ In "two colors" mode, the "color" parameter should point to an 141 * array of 8 floats; in other modes, only 4 floats are needed. 142 * 3/ The window's width and height will be set to the actual space used 143 * by the text. 144 */ 145 typedef void (* FNT_BoundedPrint_funct)( 146 FNT_font_t font , 147 const char * text , 148 unsigned int cmode , 149 unsigned int align , 150 FNT_window_t box , 151 const float * color 152 ); 153 154 155 /* 156 * Printing function that supports word-wrapping. 157 * 158 * Draws a string in a region and performs wrapping as appropriate. If the 159 * region's height is not set to 0, stop printing when it is reached. 160 * 161 * Parameters: 162 * font the font to use 163 * text the text to draw 164 * cmode the color coding to use 165 * align the text's alignment 166 * indent the size of the indent when a line is wrapped 167 * box the text's window 168 * color the color (or colors) to use 169 * 170 * Notes: 171 * 1/ The initial window must include a valid width. 172 * 2/ In "two colors" mode, the "color" parameter should point to an 173 * array of 8 floats; in other modes, only 4 floats are needed. 174 * 3/ The window's width and height will be set to the actual space used 175 * by the text. 176 */ 177 typedef void (* FNT_WrappedPrint_funct)( 178 FNT_font_t font , 179 const char * text , 180 unsigned int cmode , 181 unsigned int align , 182 unsigned int indent , 183 FNT_window_t box , 184 const float * color 185 ); 186 187 188 /* 189 * Font destruction function 190 * 191 * Parameters: 192 * font the font to destroy 193 */ 194 typedef void (* FNT_DestroyFont_funct)( FNT_font_t font ); 195 196 197 /* 198 * Size prediction function 199 * 200 * Determine how long the given text would be if drawn in the given font. 201 * Assumes no wrapping or boundaries-- it could well return a number greater 202 * than the horizontal resolution of the display. 203 * 204 * Parameters: 205 * font the font to use 206 * text the text to use 207 * color enable ^color code filtering 208 * 209 * Returns: 210 * The width in pixels required to render the text in the font 211 */ 212 typedef int (* FNT_PredictSize_funct)( 213 FNT_font_t font , 214 const char * text, 215 qboolean color 216 ); 217 218 219 220 /**************************************************************************/ 221 /* STRUCTURES FOR FACES AND FONTS */ 222 /**************************************************************************/ 223 224 /* 225 * This structure corresponds to a "face" - a type of font, with no 226 * specifics such as size. 227 */ 228 struct FNT_face_s 229 { 230 /* The face's name */ 231 char name[ FNT_FACE_NAME_MAX + 1 ]; 232 233 /* The function that allows fonts to be initialised */ 234 FNT_GetFont_funct GetFont; 235 236 /* Destructor */ 237 FNT_DestroyFace_funct Destroy; 238 239 /* Amount of fonts using this face */ 240 unsigned int used; 241 242 /* Internal data used by the actual font renderer */ 243 void * internal; 244 }; 245 246 247 /* 248 * This structure corresponds to a generic font. 249 */ 250 struct FNT_font_s 251 { 252 /* The font's look-up key */ 253 char lookup[ FNT_FONT_KEY_MAX + 1 ]; 254 255 /* The font's face */ 256 FNT_face_t face; 257 258 /* The font's height in pixels */ 259 unsigned int size; 260 /* total line height in pixels, including spacing */ 261 unsigned int height; 262 /* theoretical maximum character width in pixels, given current size */ 263 unsigned int width; 264 265 /* Printing functions */ 266 FNT_RawPrint_funct RawPrint; 267 FNT_BoundedPrint_funct BoundedPrint; 268 FNT_WrappedPrint_funct WrappedPrint; 269 FNT_PredictSize_funct PredictSize; 270 271 /* Destructor */ 272 FNT_DestroyFont_funct Destroy; 273 274 /* Amount of "unfreed" GetFont's for this font */ 275 unsigned int used; 276 277 /* Internal data used by the actual font renderer */ 278 void * internal; 279 }; 280 281 282 /* 283 * This structure is used when drawing text, it carries coordinates/region size 284 * between the caller and the text drawing function. 285 */ 286 struct FNT_window_s 287 { 288 int x; 289 int y; 290 unsigned int width; 291 unsigned int height; 292 }; 293 294 295 /* 296 * This structure is used by wrapped printing functions, which use 297 * _FNT_NextWrappedUnit() to transform a string into an array of 298 * render information. 299 */ 300 struct _FNT_render_info_s 301 { 302 int toDraw; 303 const float * color; 304 int width; 305 int kerning; 306 }; 307 typedef struct _FNT_render_info_s * _FNT_render_info_t; 308 309 310 /* 311 * This structure is used for registration of auto-loaded fonts 312 */ 313 struct FNT_auto_s 314 { 315 /* List pointers */ 316 struct FNT_auto_s * previous; 317 struct FNT_auto_s * next; 318 319 /* Face to use / default face to use if CVar is set but there is 320 * no such face. */ 321 char face[ FNT_FACE_NAME_MAX + 1 ]; 322 323 /* CVar that replaces the default face, or NULL if the default 324 * is always used. */ 325 cvar_t * faceVar; 326 327 /* Default font size. May be <= 0 if the size is to be computed 328 * from the screen's size. */ 329 int size; 330 331 /* CVar that replaces the default size, or NULL if the default 332 * is always used. */ 333 cvar_t * sizeVar; 334 335 /* When automatic size computation is used, this indicates the 336 * amount of lines of text on the screen. */ 337 unsigned int lines; 338 339 /* The minimal size that can be selected, either automatically 340 * or through the variable. */ 341 unsigned int minSize; 342 343 /* The maximal size that can be selected, either automatically 344 * or through the variable. */ 345 unsigned int maxSize; 346 347 /* The current font used. May be NULL if unregistered, or may be 348 * the Null Font. */ 349 FNT_font_t font; 350 }; 351 typedef struct FNT_auto_s * FNT_auto_t; 352 353 354 355 /**************************************************************************/ 356 /* FONT FUNCTIONS */ 357 /**************************************************************************/ 358 359 360 /* 361 * Initialise the text drawing front-end. 362 * 363 * Returns: 364 * true on success, false on failure. 365 */ 366 qboolean FNT_Initialise( ); 367 368 369 /* 370 * Destroy the text drawing front-end. 371 */ 372 void FNT_Shutdown( ); 373 374 375 /* 376 * Create or access a face. 377 * 378 * Parameters: 379 * face_name name of the face's definition file 380 * 381 * Returns: 382 * a pointer to the face's structure, or NULL if the face could not 383 * be loaded. 384 * 385 * Notes: 386 * face_name corresponds to a file name; its path and extension are 387 * ignored: faces should be in the "fonts" directory, and they should 388 * be either TrueType fonts or bitmap fonts. If both files exist, the 389 * TrueType font will be used. 390 */ 391 FNT_face_t FNT_GetFace( const char * face_name ); 392 393 394 /* 395 * Create or access a font. 396 * 397 * Parameters: 398 * face the face to use to create the font 399 * size the font's desired height in pixels 400 * 401 * Returns: 402 * a pointer to the font's structure, or NULL if the font could not 403 * be initialised. 404 */ 405 FNT_font_t FNT_GetFont( FNT_face_t face , unsigned int size ); 406 407 408 /* 409 * Release a font 410 * 411 * This function needs to be called when a font is no longer needed by some 412 * part of the program. 413 * 414 * It will decrease the font's use count and, if necessary, destroy it. 415 * If the face is no longer in use, it will be freed as well. 416 * 417 * Parameters: 418 * font the font to release 419 */ 420 void FNT_ReleaseFont( FNT_font_t font ); 421 422 423 /* 424 * Print a raw string. See comment on FNT_RawPrint_funct for more information. 425 */ 426 #define FNT_RawPrint(font,text,text_length,r2l,x,y,color) \ 427 ( font->RawPrint( font,text,text_length,r2l,x,y,color ) ) 428 429 430 /* 431 * Print a string bounded by a box. See comment on FNT_BoundedPrint_funct for 432 * more information. 433 */ 434 #define FNT_BoundedPrint(font,text,cmode,align,box,color) \ 435 ( font->BoundedPrint( font , text , cmode , align , box , color ) ) 436 437 438 /* 439 * Print a string bounded by a box using word wrapping. See comment on 440 * FNT_WrappedPrint_funct for more information. 441 */ 442 #define FNT_WrappedPrint(font,text,cmode,align,indent,box,color) \ 443 ( font->WrappedPrint( font , text , cmode , align , indent , box , color ) ) 444 445 446 /* 447 * Determine how much space is required to print the string. See comment on 448 * FNT_PredictSize_funct for more information. 449 */ 450 #define FNT_PredictSize(font,text,color) \ 451 ( font->PredictSize( font , text , color ) ) 452 453 454 455 /**************************************************************************/ 456 /* AUTOMATIC FONT MANAGEMENT */ 457 /**************************************************************************/ 458 459 /* 460 * Initialise an automatic font structure. 461 * 462 * Parameters: 463 * auto_font automatic font structure to initialise 464 * default_face name of the default font face 465 * default_size default size of the font 466 * auto_lines amount of lines of text on the screen in automatic 467 * size mode 468 * min_size minimal font size 469 * max_size maximal font size 470 */ 471 void FNT_AutoInit( 472 FNT_auto_t auto_font , 473 const char * default_face , 474 int default_size , 475 unsigned int auto_lines , 476 unsigned int min_size , 477 unsigned int max_size 478 ); 479 480 481 /* 482 * Register an automatic font. 483 * 484 * Parameters: 485 * auto_font automatic font structure to register 486 * 487 * Notes: 488 * This function will either ignore the structure or crash, depending 489 * on whatever's in memory, if the structure hasn't been initialised. 490 */ 491 void FNT_AutoRegister( 492 FNT_auto_t auto_font 493 ); 494 495 496 /* 497 * Access the font from an automatic font structure. 498 * 499 * If the automatic font uses CVars and one of the variables has been 500 * modified, or if the game went through a video restart, the font 501 * will be reloaded automatically. 502 * 503 * Parameters: 504 * auto_font automatic font structure to access 505 * 506 * Returns: 507 * The font described by the automatic font structure. 508 * 509 * Notes: 510 * This function will probably crash (or at least yield undefined 511 * results) if the automatic font structure hasn't been registered. 512 */ 513 FNT_font_t FNT_AutoGet( 514 FNT_auto_t auto_font 515 ); 516 517 518 /**************************************************************************/ 519 /* HELPER FUNCTIONS */ 520 /**************************************************************************/ 521 522 /* 523 * Handle color codes in strings. 524 * 525 * This function finds color codes, allowing them to be skipped when rendering 526 * strings, while setting the current color vector accordingly. 527 * 528 * Parameters: 529 * pptr pointer to the text pointer, will be updated 530 * depending on what is found 531 * cmode color mode 532 * color default color vector(s) passed to the rendering 533 * function 534 * expectColor pointer to a boolean which is used to keep track 535 * of Quake escape characters 536 * colorChanged pointer to a boolean which will be set to true 537 * if the color has been changed 538 * curColor pointer to a color vector pointer, will be updated 539 * to the new color if needed 540 * 541 * Returns: 542 * true if the next character is to be rendered, false if it must be 543 * skipped 544 */ 545 qboolean _FNT_HandleColor( 546 const char ** pptr , 547 unsigned int cmode , 548 const float * color , 549 qboolean * expectColor , 550 qboolean * colorChanged , 551 const float ** curColor 552 ); 553 554 /* 555 * Find the next wrapped unit (i.e. line or rest of the string until EOL). 556 * 557 * Parameters: 558 * pptr pointer to the text pointer, will be updated to the 559 * character that follows the wrapped unit (i.e. after 560 * \n or \0) 561 * renderInfo start of the rendering information array 562 * unitLength pointer to an integer which will be updated to the 563 * amount of items in the rendering information array 564 * cmode color mode 565 * color default color vector(s) 566 * 567 * Returns: 568 * false if the end of the string has been reached, false otherwise 569 */ 570 qboolean _FNT_NextWrappedUnit( 571 const char ** pptr , 572 _FNT_render_info_t renderInfo , 573 unsigned int * unitLength , 574 unsigned int cmode , 575 const float * color 576 ); 577 578 579 580 #endif // __R_TEXT_H 581