1asfont(1) AfterStep X11 window manager asfont(1)
2
6 asfont - text drawing functionality and handling of TTF and X11 fonts
7 libAfterImage/asfont.h
8
11 Text drawing functionality.
12 Text is drawn as an ASImage with only alpha channel. Since alpha
13 channel is 8 bit widths that allows for 256 shades to be used in
14 rendered glyphs. That in turn allows for smoothing and antialiasing
15 of the drawn text. Such an approcah allows for easy manipulation of
16 the drawn text, such as changing color, making it transparent,
17 texturizing, rotation, etc.
18 libAfterImage supports two types of fonts :
20 Fonts that could be rendered using standard Xlib functionality, and
21 fonts rendered by FreeType 2 library. That may include TrueType
22 fonts. When fonts are obtained via Xlib special processing is
23 performed in order to smooth its shape and leverage 256 shades
24 palette available.
25 Any font being used is has to be opened first. At that time its
27 properties are analysed and glyphs are cached in clients memory.
28 Special RLE compression method is used for font glyphs, significantly
29 reducing memory utilization without any effect on performance.
30 Font management and drawing functionality has been designed with
32 internatiolization in mind, althou support for locales is not
33 complete yet.
34
36 Structures :
37 ASFontManager
38 ASFont
39 ASGlyph
40 ASGlyphRange
41 Functions :
43 create_font_manager(), destroy_font_manager(),
44 open_freetype_font(), open_X11_font(), get_asfont(),
45 destroy_font(), print_asfont(), print_asglyph(),
46 draw_text(),
47 get_asfont_glyph_spacing(), set_asfont_glyph_spacing()
48 Other libAfterImage modules :
50 ascmap.h asfont.h asimage.h asvisual.h blender.h export.h
51 import.h transform.h ximage.h
52
54 Sasha Vasko <sasha at aftercode dot net>
55
57 - Max value of glyphs per font allowed. We need that so we can detect
58 and avoid broken fonts somehow.
59
62 Source :
63 #define MAX_GLYPHS_PER_FONT 2048
64
66 - Supported types of fonts - Xlib or FreeType 2 ASF_GuessWho will
67 enable autodetection of the font type. It is attempted to be opened as
68 FreeType font first, and if that fails - it will be opened as Xlib
69 font.
70
73 Source :
74 typedef enum
75 {
76 ASF_X11 = 0,
77 ASF_Freetype = (0x01<<0),
78 ASF_GuessWho = (0x01<<1),
79 #define ASF_TypeMask (ASF_GuessWho|ASF_Freetype)
80 /* flags below should be combined with one of the above values */
82 ASF_Monospaced = (0x01<<2),
83 ASF_RightToLeft = (0x01<<3), /* direction of the text flow */
84 ASF_HasKerning = (0x01<<4)
85 }ASFontType;
86
89 Stores glyph's image, as well as width, height and other
90 characteristics of the glyph.
91
93 Source :
94 typedef struct ASGlyph
95 {
96 CARD8 *pixmap ; /* glyph's RLE encoded pixmap */
97 short width, height ; /* meaningfull width and height
98 * of the glyphs pixmap */
99 short lead, step ; /* distance pen position to glyph
100 * beginning and to the next glyph */
101 /* in XRender it should be used as so:
102 * x = -lead, xOff = step
103 */
104 short ascend, descend ; /* distance of the top of the
105 * glyph from the baseline */
106 /* in XRender it should be used as so:
107 * y = -ascend, yOff = 0
108 */
109 unsigned int font_gid ; /* index of the glyph inside the font( TTF only ) */
110 long xrender_gid ; /* Used only with XRender - gid of the glyph in GlyphSet */
111 }ASGlyph;
112
115 Organizes glyphs that belongs to the continuos range of char codes.
116 ASGlyphRange structures could be tied together to cover entire
117 codeset supported by the font.
118
120 Source :
121 typedef struct ASGlyphRange
122 {
123 unsigned long min_char, max_char; /* Code range.
124 * for some locales that would
125 * be sufficient to simply set
126 * range of characteres
127 * supported by font */
128 ASGlyph *glyphs; /* array of glyphs belonging to
129 * that code range */
130 struct ASGlyphRange *below, *above;
131 }ASGlyphRange;
132
135 Structure to contain all the font characteristics, as well as
136 set of glyph images. Such structure has to be created/opened prior to
137 being able to draw characters with any font.
138
140 Source :
141 typedef struct ASFont
142 {
143 unsigned long magic ;
144 int ref_count ;
145 struct ASFontManager *fontman; /* our owner */
147 char *name;
148 ASFontType type ;
150 ASFlagType flags ;
151 ASGlyphRange *codemap; /* linked list of glyphsets, each
153 * representing continuos range of
154 * available codes - used for ASCII
155 * codes */
156 ASHashTable *locale_glyphs; /* hash of locale specific glyphs */
157 ASGlyph default_glyph; /* valid glyph to be drawn when
159 * code is not valid */
160 int max_height; /* maximiu height of the character
162 * glyph */
163 int max_ascend, /* maximum distance from the baseline
164 * to the top of the character glyph */
165 max_descend; /* need both descend and ascend to be
166 able to dynamically recalculate font
167 height while adding new characters */
168 int space_size; /* fixed width value to be used when
169 * rendering spaces and tabs */
170 int spacing_x, spacing_y;
171 /* If these are set to anything above 0 then all the glyphs has to be
172 * padded ( if its smaller then the cell ) or scaled down
173 * ( if its bigger then the cell )
174 */
175 int cell_width, cell_height ;
176 #ifdef HAVE_FREETYPE
178 FT_Face ft_face; /* free type font handle */
179 #else
180 CARD32 *pad;
181 #endif
182 unsigned long xrender_glyphset ; /* GlyphSet is the actuall datatype,
184 * but for easier compilation -
185 * we use generic which is the same */
186 }ASFont;
187
190 Global data identifying connection to external libraries, as well as
191 fonts location paths.
192 This structure has to be created/initialized prior to any font being
193 loaded.
194 It also holds list of fonts that are currently open, allowing for
195 easy access to fonts.
196 When ASFontManagaer object is destroyd it automagically closes all
197 the open fonts.
198
200 Source :
201 typedef struct ASFontManager
202 {
203 Display *dpy;
204 char *font_path ;
205 ASHashTable *fonts_hash ;
207 size_t unicode_used;
209 CARD32 *local_unicode; /* list of unicodes from current locale
210 * - we use it to limit number of glyphs
211 * we load */
212 Bool ft_ok ;
213 #ifdef HAVE_FREETYPE
214 FT_Library ft_library; /* free type library handle */
215 #else
216 void *pad ;
217 #endif
218 }ASFontManager;
219
221 - Available types of 3D text to be drawn.
222
225 Source :
226 typedef enum ASText3DType{
227 AST_Plain =0, /* regular 2D text */
228 AST_Embossed,
229 AST_Sunken,
230 AST_ShadeAbove,
231 AST_ShadeBelow,
232 AST_EmbossedThick,
233 AST_SunkenThick,
234 AST_OutlineAbove,
235 AST_OutlineBelow,
236 AST_OutlineFull,
237 AST_3DTypes
238 }ASText3DType;
239
241 - Attributes for text rendering
242
245 Source :
246 typedef struct ASTextAttributes
247 {
248 #define ASTA_UseTabStops (0x01<<0)
249 unsigned int version ;
250 /* structure version, so we can implement future
251 * extensions without breaking binary apps */
252 ASFlagType rendition_flags ;
253 ASText3DType type;
254 ASCharType char_type;
255 unsigned int tab_size ; /* tab size in chars - defaults to 8 */
256 unsigned int origin ; /* distance from the left margin
257 * (in pixels) */
258 unsigned int *tab_stops ; /* tab stops in pixels where
259 * left margin is 0 */
260 unsigned int tab_stops_num ;
261 ARGB32 fore_color ; /* used with 3D type of Outlined */
263 unsigned int width;
264 #define ASTA_VERSION_1 1
265 #define ASTA_VERSION_INTERNAL ASTA_VERSION_1
267 }ASTextAttributes;
268
271 ASFontManager *create_font_manager( Display *dpy,
272 const char *font_path,
273 ASFontManager *reusable_memory );
274
276 dpy - pointer to valid and opened Display.
277 font_path
279 - string, representing colon separated list of directories to
280 search for FreeType fonts.
281 reusable_memory
283 - optional preallocated memory for the ASFontMagaer object
284
287 Pointer to Initialized ASFontManager object on success.
288 NULL otherwise.
289
291 create_font_manager() will create new ASFontManager structure if
292 needed. It wioll then store copy of font_path and supplied pointer to
293 Display in it. At that time Hash table of loaded fonts is initialized,
294 and if needed FreeType library is initialized as well.
295 ASFontManager object returned by this functions has to be open at all
296 times untill text drawing is no longer needed.
297
300 void destroy_font_manager( ASFontManager *fontman,
301 Bool reusable );
302
304 fontman
305 - pointer to valid ASFontManager object to be deallocated.
306 reusable
308 - If True, then memory holding object itself will not be freed -
309 only resources will be deallocated. That is usefull for struc‐
310 tures created on stack.
311
314 destroy_font_manager() closes all the fonts open with this
315 ASFontManager. It will also close connection to FreeType library, and
316 deallocate all cached data. If reusable is False - then memory used
317 for object itself will not be freed.
318
321 ASFont *open_freetype_font( ASFontManager *fontman,
322 const char *font_string,
323 int face_no,
324 int size, Bool verbose);
325
327 fontman
328 - pointer to previously created ASFontManager. Needed for con‐
329 nection to FreeType library, as well as path to search fonts in.
330 font_string
332 - filename of the file containing font's data.
333 face_no
335 - number of face within the font file
336 size - font size in points. Applicable only to scalable fonts, such
338 as TrueType.
339 verbose
341 - if True, extensive error messages will be printed if problems
342 encountered.
343
346 pointer to Opened ASFont structure, containing all the glyphs of the
347 font, as well as other relevant info. On failure returns NULL.
348
350 open_freetype_font() will attempt to find font file in any of the
351 directories specified in ASFontManager's font_path. If it fails to do
352 so - then it will check if filename has alldigit extentions. It will
353 then try to interpret that extention as a face number, and try and
354 find the file with extention stripped off.
355 If file was found function will atempt to read it using FreeType
356 library. If requested face is not available in the font - face 0 will
357 be used.
358 On success all the font's glyphs will be rendered and cached, and
359 needed font geometry info collected.
360 When FreeType Library is not available that function does nothing.
361
364 ASFont *open_X11_font( ASFontManager *fontman,
365 const char *font_string);
366
368 fontman
369 - pointer to previously created ASFontManager. Needed for con‐
370 nection X Server.
371 font_string
373 - name of the font as recognized by Xlib.
374
377 pointer to Opened ASFont structure, containing all the glyphs of the
378 font, as well as other relevant info. On failure returns NULL.
379
381 open_X11_font() attempts to load and query font using Xlib calls.
382 On success it goes thgroughthe codemap of the font and renders all
383 the glyphs available. Glyphs then gets transfered to the client's
384 memory and encoded using RLE compression. At this time smoothing
385 filters are applied on glyph pixmaps, if its size exceeds threshold.
386
388 implement proper XFontSet support, when used with I18N enabled.
389
392 ASFont *get_asfont( ASFontManager *fontman,
393 const char *font_string,
394 int face_no, int size,
395 ASFontType type );
396
398 fontman
399 - pointer to previously created ASFontManager. Needed for con‐
400 nection to FreeType library, path to search fonts in, and X
401 Server connection.
402 font_string
404 - font name or filename of the file containing font's data.
405 face_no
407 - number of face within the font file
408 size - font size in points. Applicable only to scalable fonts, such
410 as TrueType.
411 type - specifies the type of the font, or GuessWho for autodetection.
413
416 pointer to Opened ASFont structure, containing all the glyphs of the
417 font, as well as other relevant info. On failure returns NULL.
418
420 This function provides unified interface to font loading. It performs
421 search in ASFontManager's list to see if this specific font has been
422 loaded already, and if so - returns pointer to relevant structure.
423 Otherwise it tryes to load font as FreeType font first, and then
424 Xlib font, unless exact font type is specifyed.
425
428 void release_font( ASFont *font );
429
431 font - pointer to the valid ASFont structure containing loaded font.
432
435 returns current reference count. -1 means that object has been
436 destroyed.
437
439 This function will decrement reference count on loaded font and if
440 reference count will be less then 0 ( meaning that release_font() has
441 been called more times then get_asfont() ) it will close the font,
442 remove it from ASFontManager's list, destroy all the glyphs and
443 generally free everything else used by ASFont.
444 Otherwise font will remain in memory for faster reuse.
445
448 void print_asfont( FILE* stream,
449 ASFont* font);
450
452 stream - output file pointer
453 font - pointer to ASFont structure to print.
455
458 prints all the geometry information about font.
459
462 void print_asglyph( FILE* stream,
463 ASFont* font, unsigned long c);
464
466 stream - output file pointer
467 font - pointer to ASFont structure to print.
469 c - character code to print glyph for
471
474 prints out contents of the cached glyph for specifyed character code.
475
477 draw_fancy_text()
478 get_text_size()
480 get_fancy_text_size();
482
486 ASImage *draw_text( const char *text,
487 ASFont *font, ASText3DType type,
488 int compression );
489 ASImage *draw_fancy_text( const void *text,
490 struct ASFont *font, ASTextAttributes *attr,
491 int compression,
492 int length );
493 Bool get_text_size( const char *text,
494 ASFont *font, ASText3DType type,
495 unsigned int *width, unsigned int *height );
496 Bool get_fancy_text_size( const void *text,
497 struct ASFont *font, ASTextAttributes *attr,
498 unsigned int *width, unsigned int *height,
499 int length,
500 int *x_positions );
501
503 text - actuall text to render
504 font - pointer to ASFont to render text with
506 type - one of the few available types of 3D text.
508 compression
510 - compression level to attempt on resulting ASImage.
511 width - pointer to value to be set to text width.
513 height - pointer to value to be set to text height.
515
518 Pointer to new ASImage containing rendered text on success.
519 NULL on failure.
520
522 draw_text() creates new ASImage of the size big enough to contain
523 entire text. It then renders the text using supplied font as an alpha
524 channel of ASImage.
525 get_text_size() can be used to determine the size of the text about
526 to be drawn, so that appropriate drawable can be prepared.
527
530 Bool get_asfont_glyph_spacing( ASFont* font, int *x, int *y );
531
533 font - Loaded ASFont structure.
534 x - pointer to the variable to receive horizontal spacing value.
536 y - pointer to the variable to receive vertical spacing value.
538
541 True if meaningfull information has been returned.
542
544 Returns inter-glyph spacing of specified font.
545
548 Bool set_asfont_glyph_spacing( ASFont* font, int x, int y );
549
551 font - Loaded ASFont structure.
552 x - new horizontal spacing value.
554 y - new vertical spacing value.
556
559 TRue on success.
560
562 Changes inter-glyph spacing of the specified font.
5633rd Berkeley Distribution AfterStep v.2.2.6 asfont(1)