00001 #ifndef ASFONT_HEADER_ICLUDED 00002 #define ASFONT_HEADER_ICLUDED 00003 00004 00005 #include "asvisual.h" 00006 #include "char2uni.h" 00007 00008 #ifdef __cplusplus 00009 extern "C" { 00010 #endif 00011 00012 00013 /****h* libAfterImage/asfont.h 00014 * NAME 00015 * asfont 00016 * DESCRIPTION 00017 * Text drawing functionality. 00018 * Text is drawn as an ASImage with only alpha channel. Since alpha 00019 * channel is 8 bit widths that allows for 256 shades to be used in 00020 * rendered glyphs. That in turn allows for smoothing and antialiasing 00021 * of the drawn text. Such an approcah allows for easy manipulation of 00022 * the drawn text, such as changing color, making it transparent, 00023 * texturizing, rotation, etc. 00024 * 00025 * libAfterImage supports two types of fonts : 00026 * Fonts that could be rendered using standard Xlib functionality, and 00027 * fonts rendered by FreeType 2 library. That may include TrueType 00028 * fonts. When fonts are obtained via Xlib special processing is 00029 * performed in order to smooth its shape and leverage 256 shades 00030 * palette available. 00031 * 00032 * Any font being used is has to be opened first. At that time its 00033 * properties are analysed and glyphs are cached in clients memory. 00034 * Special RLE compression method is used for font glyphs, significantly 00035 * reducing memory utilization without any effect on performance. 00036 * 00037 * Font management and drawing functionality has been designed with 00038 * internatiolization in mind, althou support for locales is not 00039 * complete yet. 00040 * SEE ALSO 00041 * Structures : 00042 * ASFontManager 00043 * ASFont 00044 * ASGlyph 00045 * ASGlyphRange 00046 * 00047 * Functions : 00048 * create_font_manager(), destroy_font_manager(), 00049 * open_freetype_font(), open_X11_font(), get_asfont(), 00050 * destroy_font(), print_asfont(), print_asglyph(), 00051 * draw_text(), 00052 * get_asfont_glyph_spacing(), set_asfont_glyph_spacing() 00053 * 00054 * Other libAfterImage modules : 00055 * ascmap.h asfont.h asimage.h asvisual.h blender.h export.h 00056 * import.h transform.h ximage.h 00057 * AUTHOR 00058 * Sasha Vasko <sasha at aftercode dot net> 00059 ******************/ 00060 00061 /****d* libAfterImage/MAX_GLYPHS_PER_FONT 00062 * NAME 00063 * MAX_GLYPHS_PER_FONT - Max value of glyphs per font allowed. 00064 * We need that so we can detect and avoid broken fonts somehow. 00065 * SOURCE 00066 */ 00067 #define MAX_GLYPHS_PER_FONT 2048 00068 /*************/ 00069 00070 /* magic number identifying ASFont data structure */ 00071 #define MAGIC_ASFONT 0xA3A3F098 00072 00073 /****d* libAfterImage/ASFontType 00074 * NAME 00075 * ASFontType - Supported types of fonts - Xlib or FreeType 2 00076 * ASF_GuessWho will enable autodetection of the font type. 00077 * It is attempted to be opened as FreeType font first, and if that 00078 * fails - it will be opened as Xlib font. 00079 * SOURCE 00080 */ 00081 typedef enum 00082 { 00083 ASF_X11 = 0, 00084 ASF_Freetype = (0x01<<0), 00085 ASF_GuessWho = (0x01<<1), 00086 #define ASF_TypeMask (ASF_GuessWho|ASF_Freetype) 00087 00088 /* flags below should be combined with one of the above values */ 00089 ASF_Monospaced = (0x01<<2), 00090 ASF_RightToLeft = (0x01<<3), /* direction of the text flow */ 00091 ASF_HasKerning = (0x01<<4) 00092 }ASFontType; 00093 /*************/ 00094 00095 struct ASFontManager; 00096 struct ASFont; 00097 00098 /****s* libAfterImage/ASGlyph 00099 * NAME 00100 * ASGlyph 00101 * DESCRIPTION 00102 * Stores glyph's image, as well as width, height and other 00103 * characteristics of the glyph. 00104 * SOURCE 00105 */ 00106 typedef struct ASGlyph 00107 { 00108 CARD8 *pixmap ; /* glyph's RLE encoded pixmap */ 00109 short width, height ; /* meaningfull width and height 00110 * of the glyphs pixmap */ 00111 short lead, step ; /* distance pen position to glyph 00112 * beginning and to the next glyph */ 00113 /* in XRender it should be used as so: 00114 * x = -lead, xOff = step 00115 */ 00116 short ascend, descend ; /* distance of the top of the 00117 * glyph from the baseline */ 00118 /* in XRender it should be used as so: 00119 * y = -ascend, yOff = 0 00120 */ 00121 unsigned int font_gid ; /* index of the glyph inside the font( TTF only ) */ 00122 long xrender_gid ; /* Used only with XRender - gid of the glyph in GlyphSet */ 00123 }ASGlyph; 00124 /*************/ 00125 00126 /****s* libAfterImage/ASGlyphRange 00127 * NAME 00128 * ASGlyphRange 00129 * DESCRIPTION 00130 * Organizes glyphs that belongs to the continuos range of char codes. 00131 * ASGlyphRange structures could be tied together to cover entire 00132 * codeset supported by the font. 00133 * SOURCE 00134 */ 00135 typedef struct ASGlyphRange 00136 { 00137 unsigned long min_char, max_char; /* Code range. 00138 * for some locales that would 00139 * be sufficient to simply set 00140 * range of characteres 00141 * supported by font */ 00142 ASGlyph *glyphs; /* array of glyphs belonging to 00143 * that code range */ 00144 struct ASGlyphRange *below, *above; 00145 }ASGlyphRange; 00146 /*************/ 00147 00148 #define MAX_SPECIAL_GLYPH ((ASGlyph*)0x00000003) 00149 #define GLYPH_TAB ((ASGlyph*)0x00000003) 00150 #define GLYPH_SPACE ((ASGlyph*)0x00000002) 00151 #define GLYPH_EOL ((ASGlyph*)0x00000001) 00152 #define GLYPH_EOT ((ASGlyph*)0x00000000) 00153 00154 /****s* libAfterImage/ASFont 00155 * NAME 00156 * ASFont 00157 * DESCRIPTION 00158 * Structure to contain all the font characteristics, as well as 00159 * set of glyph images. Such structure has to be created/opened prior to 00160 * being able to draw characters with any font. 00161 * SOURCE 00162 */ 00163 typedef struct ASFont 00164 { 00165 unsigned long magic ; 00166 int ref_count ; 00167 00168 struct ASFontManager *fontman; /* our owner */ 00169 char *name; 00170 00171 ASFontType type ; 00172 ASFlagType flags ; 00173 00174 ASGlyphRange *codemap; /* linked list of glyphsets, each 00175 * representing continuos range of 00176 * available codes - used for ASCII 00177 * codes */ 00178 ASHashTable *locale_glyphs; /* hash of locale specific glyphs */ 00179 00180 ASGlyph default_glyph; /* valid glyph to be drawn when 00181 * code is not valid */ 00182 00183 int max_height; /* maximiu height of the character 00184 * glyph */ 00185 int max_ascend, /* maximum distance from the baseline 00186 * to the top of the character glyph */ 00187 max_descend; /* need both descend and ascend to be 00188 able to dynamically recalculate font 00189 height while adding new characters */ 00190 int space_size; /* fixed width value to be used when 00191 * rendering spaces and tabs */ 00192 int spacing_x, spacing_y; 00193 /* If these are set to anything above 0 then all the glyphs has to be 00194 * padded ( if its smaller then the cell ) or scaled down 00195 * ( if its bigger then the cell ) 00196 */ 00197 int cell_width, cell_height ; 00198 00199 #ifdef HAVE_FREETYPE 00200 FT_Face ft_face; /* free type font handle */ 00201 #else 00202 CARD32 *pad; 00203 #endif 00204 00205 unsigned long xrender_glyphset ; /* GlyphSet is the actuall datatype, 00206 * but for easier compilation - 00207 * we use generic which is the same */ 00208 }ASFont; 00209 /*************/ 00210 /****s* libAfterImage/ASFontManager 00211 * NAME 00212 * ASFontManager 00213 * DESCRIPTION 00214 * Global data identifying connection to external libraries, as well as 00215 * fonts location paths. 00216 * This structure has to be created/initialized prior to any font being 00217 * loaded. 00218 * It also holds list of fonts that are currently open, allowing for 00219 * easy access to fonts. 00220 * When ASFontManagaer object is destroyd it automagically closes all 00221 * the open fonts. 00222 * SOURCE 00223 */ 00224 typedef struct ASFontManager 00225 { 00226 Display *dpy; 00227 char *font_path ; 00228 00229 ASHashTable *fonts_hash ; 00230 00231 size_t unicode_used; 00232 CARD32 *local_unicode; /* list of unicodes from current locale 00233 * - we use it to limit number of glyphs 00234 * we load */ 00235 Bool ft_ok ; 00236 #ifdef HAVE_FREETYPE 00237 FT_Library ft_library; /* free type library handle */ 00238 #else 00239 void *pad ; 00240 #endif 00241 }ASFontManager; 00242 /*************/ 00243 00244 /****d* libAfterImage/ASText3DType 00245 * NAME 00246 * ASText3DType - Available types of 3D text to be drawn. 00247 * SOURCE 00248 */ 00249 typedef enum ASText3DType{ 00250 AST_Plain =0, /* regular 2D text */ 00251 AST_Embossed, 00252 AST_Sunken, 00253 AST_ShadeAbove, 00254 AST_ShadeBelow, 00255 AST_EmbossedThick, 00256 AST_SunkenThick, 00257 AST_OutlineAbove, 00258 AST_OutlineBelow, 00259 AST_OutlineFull, 00260 AST_3DTypes 00261 }ASText3DType; 00262 /*************/ 00263 typedef enum { 00264 ASCT_UTF8 = 0, 00265 ASCT_Char = 1, 00266 ASCT_Unicode=sizeof(UNICODE_CHAR) 00267 }ASCharType; 00268 00269 00270 /****s* libAfterImage/ASTextAttributes 00271 * NAME 00272 * ASTextAttributes - Attributes for text rendering 00273 * SOURCE 00274 */ 00275 typedef struct ASTextAttributes 00276 { 00277 #define ASTA_UseTabStops (0x01<<0) 00278 unsigned int version ; 00279 /* structure version, so we can implement future 00280 * extensions without breaking binary apps */ 00281 ASFlagType rendition_flags ; 00282 ASText3DType type; 00283 ASCharType char_type; 00284 unsigned int tab_size ; /* tab size in chars - defaults to 8 */ 00285 unsigned int origin ; /* distance from the left margin 00286 * (in pixels) */ 00287 unsigned int *tab_stops ; /* tab stops in pixels where 00288 * left margin is 0 */ 00289 unsigned int tab_stops_num ; 00290 00291 ARGB32 fore_color ; /* used with 3D type of Outlined */ 00292 unsigned int width; 00293 #define ASTA_VERSION_1 1 00294 00295 #define ASTA_VERSION_INTERNAL ASTA_VERSION_1 00296 }ASTextAttributes; 00297 /*************/ 00298 00299 /****f* libAfterImage/asfont/create_font_manager() 00300 * NAME 00301 * create_font_manager() 00302 * SYNOPSIS 00303 * ASFontManager *create_font_manager( Display *dpy, 00304 * const char *font_path, 00305 * ASFontManager *reusable_memory ); 00306 * INPUTS 00307 * dpy - pointer to valid and opened Display. 00308 * font_path - string, representing colon separated list of 00309 * directories to search for FreeType fonts. 00310 * reusable_memory - optional preallocated memory for the ASFontMagaer 00311 * object 00312 * RETURN VALUE 00313 * Pointer to Initialized ASFontManager object on success. 00314 * NULL otherwise. 00315 * DESCRIPTION 00316 * create_font_manager() will create new ASFontManager structure if 00317 * needed. It wioll then store copy of font_path and supplied pointer to 00318 * Display in it. At that time Hash table of loaded fonts is initialized, 00319 * and if needed FreeType library is initialized as well. 00320 * ASFontManager object returned by this functions has to be open at all 00321 * times untill text drawing is no longer needed. 00322 *********/ 00323 /****f* libAfterImage/asfont/destroy_font_manager() 00324 * NAME 00325 * destroy_font_manager() 00326 * SYNOPSIS 00327 * void destroy_font_manager( ASFontManager *fontman, 00328 * Bool reusable ); 00329 * INPUTS 00330 * fontman - pointer to valid ASFontManager object to be deallocated. 00331 * reusable - If True, then memory holding object itself will not be 00332 * freed - only resources will be deallocated. That is 00333 * usefull for structures created on stack. 00334 * DESCRIPTION 00335 * destroy_font_manager() closes all the fonts open with this 00336 * ASFontManager. It will also close connection to FreeType library, and 00337 * deallocate all cached data. If reusable is False - then memory used 00338 * for object itself will not be freed. 00339 *********/ 00340 struct ASFontManager *create_font_manager( Display *dpy, const char * font_path, struct ASFontManager *reusable_memory ); 00341 void destroy_font_manager( struct ASFontManager *fontman, Bool reusable ); 00342 00343 /****f* libAfterImage/asfont/open_freetype_font() 00344 * NAME 00345 * open_freetype_font() 00346 * SYNOPSIS 00347 * ASFont *open_freetype_font( ASFontManager *fontman, 00348 * const char *font_string, 00349 * int face_no, 00350 * int size, Bool verbose); 00351 * INPUTS 00352 * fontman - pointer to previously created ASFontManager. Needed for 00353 * connection to FreeType library, as well as path to 00354 * search fonts in. 00355 * font_string - filename of the file containing font's data. 00356 * face_no - number of face within the font file 00357 * size - font size in points. Applicable only to scalable fonts, 00358 * such as TrueType. 00359 * verbose - if True, extensive error messages will be printed if 00360 * problems encountered. 00361 * RETURN VALUE 00362 * pointer to Opened ASFont structure, containing all the glyphs of the 00363 * font, as well as other relevant info. On failure returns NULL. 00364 * DESCRIPTION 00365 * open_freetype_font() will attempt to find font file in any of the 00366 * directories specified in ASFontManager's font_path. If it fails to do 00367 * so - then it will check if filename has alldigit extentions. It will 00368 * then try to interpret that extention as a face number, and try and 00369 * find the file with extention stripped off. 00370 * If file was found function will atempt to read it using FreeType 00371 * library. If requested face is not available in the font - face 0 will 00372 * be used. 00373 * On success all the font's glyphs will be rendered and cached, and 00374 * needed font geometry info collected. 00375 * When FreeType Library is not available that function does nothing. 00376 *********/ 00377 /****f* libAfterImage/asfont/open_X11_font() 00378 * NAME 00379 * open_X11_font() 00380 * SYNOPSIS 00381 * ASFont *open_X11_font( ASFontManager *fontman, 00382 * const char *font_string); 00383 * INPUTS 00384 * fontman - pointer to previously created ASFontManager. Needed for 00385 * connection X Server. 00386 * font_string - name of the font as recognized by Xlib. 00387 * RETURN VALUE 00388 * pointer to Opened ASFont structure, containing all the glyphs of the 00389 * font, as well as other relevant info. On failure returns NULL. 00390 * DESCRIPTION 00391 * open_X11_font() attempts to load and query font using Xlib calls. 00392 * On success it goes thgroughthe codemap of the font and renders all 00393 * the glyphs available. Glyphs then gets transfered to the client's 00394 * memory and encoded using RLE compression. At this time smoothing 00395 * filters are applied on glyph pixmaps, if its size exceeds threshold. 00396 * TODO 00397 * implement proper XFontSet support, when used with I18N enabled. 00398 *********/ 00399 /****f* libAfterImage/asfont/get_asfont() 00400 * NAME 00401 * get_asfont() 00402 * SYNOPSIS 00403 * ASFont *get_asfont( ASFontManager *fontman, 00404 * const char *font_string, 00405 * int face_no, int size, 00406 * ASFontType type ); 00407 * INPUTS 00408 * fontman - pointer to previously created ASFontManager. Needed for 00409 * connection to FreeType library, path to search fonts 00410 * in, and X Server connection. 00411 * font_string - font name or filename of the file containing font's data. 00412 * face_no - number of face within the font file 00413 * size - font size in points. Applicable only to scalable fonts, 00414 * such as TrueType. 00415 * type - specifies the type of the font, or GuessWho for 00416 * autodetection. 00417 * RETURN VALUE 00418 * pointer to Opened ASFont structure, containing all the glyphs of the 00419 * font, as well as other relevant info. On failure returns NULL. 00420 * DESCRIPTION 00421 * This function provides unified interface to font loading. It performs 00422 * search in ASFontManager's list to see if this specific font has been 00423 * loaded already, and if so - returns pointer to relevant structure. 00424 * Otherwise it tryes to load font as FreeType font first, and then 00425 * Xlib font, unless exact font type is specifyed. 00426 *********/ 00427 /****f* libAfterImage/asfont/release_font() 00428 * NAME 00429 * release_font() 00430 * SYNOPSIS 00431 * void release_font( ASFont *font ); 00432 * INPUTS 00433 * font - pointer to the valid ASFont structure containing loaded font. 00434 * RETURN VALUE 00435 * returns current reference count. -1 means that object has been 00436 * destroyed. 00437 * DESCRIPTION 00438 * This function will decrement reference count on loaded font and if 00439 * reference count will be less then 0 ( meaning that release_font() has 00440 * been called more times then get_asfont() ) it will close the font, 00441 * remove it from ASFontManager's list, destroy all the glyphs and 00442 * generally free everything else used by ASFont. 00443 * Otherwise font will remain in memory for faster reuse. 00444 *********/ 00445 struct ASFont *open_freetype_font( struct ASFontManager *fontman, const char *font_string, int face_no, int size, Bool verbose); 00446 struct ASFont *open_X11_font( struct ASFontManager *fontman, const char *font_string); 00447 struct ASFont *get_asfont( struct ASFontManager *fontman, const char *font_string, int face_no, int size, ASFontType type_and_flags ); 00448 struct ASFont *dup_asfont( ASFont *font ); 00449 int release_font( struct ASFont *font ); 00450 00451 /****f* libAfterImage/asfont/print_asfont() 00452 * NAME 00453 * print_asfont() 00454 * SYNOPSIS 00455 * void print_asfont( FILE* stream, 00456 * ASFont* font); 00457 * INPUTS 00458 * stream - output file pointer 00459 * font - pointer to ASFont structure to print. 00460 * DESCRIPTION 00461 * prints all the geometry information about font. 00462 *********/ 00463 /****f* libAfterImage/asfont/print_asglyph() 00464 * NAME 00465 * print_asglyph() 00466 * SYNOPSIS 00467 * void print_asglyph( FILE* stream, 00468 * ASFont* font, unsigned long c); 00469 * INPUTS 00470 * stream - output file pointer 00471 * font - pointer to ASFont structure to print. 00472 * c - character code to print glyph for 00473 * DESCRIPTION 00474 * prints out contents of the cached glyph for specifyed character code. 00475 *********/ 00476 void print_asfont( FILE* stream, struct ASFont* font); 00477 void print_asglyph( FILE* stream, struct ASFont* font, unsigned long c); 00478 00479 ASGlyph** get_text_glyph_list (const char *text, ASFont *font, ASCharType char_type, int length); 00480 00481 /****f* libAfterImage/asfont/draw_text() 00482 * NAME 00483 * draw_text() 00484 * NAME 00485 * draw_fancy_text() 00486 * NAME 00487 * get_text_size() 00488 * NAME 00489 * get_fancy_text_size(); 00490 * SYNOPSIS 00491 * ASImage *draw_text( const char *text, 00492 * ASFont *font, ASText3DType type, 00493 * int compression ); 00494 * ASImage *draw_fancy_text( const void *text, 00495 * struct ASFont *font, ASTextAttributes *attr, 00496 * int compression, 00497 * int length ); 00498 * Bool get_text_size( const char *text, 00499 * ASFont *font, ASText3DType type, 00500 * unsigned int *width, unsigned int *height ); 00501 * Bool get_fancy_text_size( const void *text, 00502 * struct ASFont *font, ASTextAttributes *attr, 00503 * unsigned int *width, unsigned int *height, 00504 * int length, 00505 * int *x_positions ); 00506 * 00507 * INPUTS 00508 * text - actuall text to render 00509 * font - pointer to ASFont to render text with 00510 * type - one of the few available types of 3D text. 00511 * compression - compression level to attempt on resulting ASImage. 00512 * width - pointer to value to be set to text width. 00513 * height - pointer to value to be set to text height. 00514 * RETURN VALUE 00515 * Pointer to new ASImage containing rendered text on success. 00516 * NULL on failure. 00517 * DESCRIPTION 00518 * draw_text() creates new ASImage of the size big enough to contain 00519 * entire text. It then renders the text using supplied font as an alpha 00520 * channel of ASImage. 00521 * get_text_size() can be used to determine the size of the text about 00522 * to be drawn, so that appropriate drawable can be prepared. 00523 *********/ 00524 struct ASImage *draw_text( const char *text, 00525 struct ASFont *font, ASText3DType type, 00526 int compression ); 00527 struct ASImage *draw_utf8_text( const char *text, 00528 struct ASFont *font, ASText3DType type, 00529 int compression ); 00530 struct ASImage *draw_unicode_text( const CARD32 *text, 00531 struct ASFont *font, ASText3DType type, 00532 int compression ); 00533 /* same as above only allows specifying the length of the text, instead of 00534 * using zero-terminated strings : 00535 * Note: if length <= 0 then call is equivalent to above. 00536 */ 00537 struct ASImage *draw_fancy_text( const void *text, 00538 struct ASFont *font, ASTextAttributes *attr, 00539 int compression, 00540 int length ); 00541 00542 Bool get_text_size( const char *text, 00543 struct ASFont *font, ASText3DType type, 00544 unsigned int *width, unsigned int *height ); 00545 Bool get_utf8_text_size( const char *text, 00546 struct ASFont *font, ASText3DType type, 00547 unsigned int *width, unsigned int *height ); 00548 Bool get_unicode_text_size( const CARD32 *text, 00549 struct ASFont *font, ASText3DType type, 00550 unsigned int *width, unsigned int *height ); 00551 00552 Bool get_fancy_text_size( const void *text, 00553 struct ASFont *font, ASTextAttributes *attr, 00554 unsigned int *width, unsigned int *height, 00555 int length, 00556 int *x_positions ); 00557 /* array of length elements or NULL */ 00558 /****f* libAfterImage/asfont/get_asfont_glyph_spacing() 00559 * NAME 00560 * get_asfont_glyph_spacing() 00561 * SYNOPSIS 00562 * Bool get_asfont_glyph_spacing( ASFont* font, int *x, int *y ); 00563 * INPUTS 00564 * font - Loaded ASFont structure. 00565 * x - pointer to the variable to receive horizontal spacing value. 00566 * y - pointer to the variable to receive vertical spacing value. 00567 * RETURN VALUE 00568 * True if meaningfull information has been returned. 00569 * DESCRIPTION 00570 * Returns inter-glyph spacing of specified font. 00571 *********/ 00572 /****f* libAfterImage/asfont/set_asfont_glyph_spacing() 00573 * NAME 00574 * set_asfont_glyph_spacing() 00575 * SYNOPSIS 00576 * Bool set_asfont_glyph_spacing( ASFont* font, int x, int y ); 00577 * INPUTS 00578 * font - Loaded ASFont structure. 00579 * x - new horizontal spacing value. 00580 * y - new vertical spacing value. 00581 * RETURN VALUE 00582 * TRue on success. 00583 * DESCRIPTION 00584 * Changes inter-glyph spacing of the specified font. 00585 *********/ 00586 00587 Bool get_asfont_glyph_spacing( ASFont* font, int *x, int *y ); 00588 Bool set_asfont_glyph_spacing( ASFont* font, int x, int y ); 00589 00590 #ifdef __cplusplus 00591 } 00592 #endif 00593 00594 00595 #endif
1.5.1