µGFX  2.9
version 2.9
mf_font.h
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.io/license.html
6  */
7 
8 /* Generic font type that supports fonts with multiple kinds of compression.
9  * Provides an interface for decoding and rendering single characters.
10  */
11 
12 #ifndef _MF_FONT_H_
13 #define _MF_FONT_H_
14 
15 #include "mf_encoding.h"
16 
17 /* Callback function that writes pixels to screen / buffer / whatever.
18  *
19  * x: X coordinate of the first pixel to write.
20  * y: Y coordinate of the first pixel to write.
21  * count: Number of pixels to fill (horizontally).
22  * alpha: The "opaqueness" of the pixels, 0 for background, 255 for text.
23  * state: Free variable that was passed to render_character().
24  */
25 typedef void (*mf_pixel_callback_t) (gI16 x, gI16 y, gU8 count,
26  gU8 alpha, void *state);
27 
28 /* General information about a font. */
29 struct mf_font_s
30 {
31  /* Full name of the font, comes from the original font file. */
32  const char *full_name;
33 
34  /* Short name of the font, comes from file name. */
35  const char *short_name;
36 
37  /* Width and height of the character bounding box. */
38  gU8 width;
39  gU8 height;
40 
41  /* Minimum and maximum tracking width of characters. */
42  gU8 min_x_advance;
43  gU8 max_x_advance;
44 
45  /* Location of the text baseline relative to character. */
46  gI8 baseline_x;
47  gU8 baseline_y;
48 
49  /* Line height of the font (vertical advance). */
50  gU8 line_height;
51 
52  /* Flags identifying various aspects of the font. */
53  gU8 flags;
54 
55  /* Fallback character to use for missing glyphs. */
56  gU16 fallback_character;
57 
58  /* Function to get character width. Should return 0 if character is
59  * not found. */
60  gU8 (*character_width)(const struct mf_font_s *font, gU16 character);
61 
62  /* Function to render a character. Returns the character width or 0 if
63  * character is not found. */
64  gU8 (*render_character)(const struct mf_font_s *font,
65  gI16 x0, gI16 y0,
66  gU16 character,
67  mf_pixel_callback_t callback,
68  void *state);
69 };
70 
71 /* The flag definitions for the font.flags field. */
72 #define MF_FONT_FLAG_MONOSPACE 0x01
73 #define MF_FONT_FLAG_BW 0x02
74 
75 /* Lookup structure for searching fonts by name. */
76 struct mf_font_list_s
77 {
78  const struct mf_font_list_s *next;
79  const struct mf_font_s *font;
80 };
81 
82 
83 /* Function to decode and render a single character.
84  *
85  * font: Pointer to the font definition.
86  * x0, y0: Upper left corner of the target area.
87  * character: The character code (unicode) to render.
88  * callback: Callback function to write out the pixels.
89  * state: Free variable for caller to use (can be NULL).
90  *
91  * Returns width of the character.
92  */
93 MF_EXTERN gU8 mf_render_character(const struct mf_font_s *font,
94  gI16 x0, gI16 y0,
95  mf_char character,
96  mf_pixel_callback_t callback,
97  void *state);
98 
99 /* Function to get the width of a single character.
100  * This is not necessarily the bounding box of the character
101  * data, but rather the tracking width.
102  *
103  * font: Pointer to the font definition.
104  * character: The character code (unicode) to render.
105  *
106  * Returns width of the character in pixels.
107  */
108 MF_EXTERN gU8 mf_character_width(const struct mf_font_s *font,
109  mf_char character);
110 
111 /* Find a font based on name. The name can be either short name or full name.
112  * Note: You can pass MF_INCLUDED_FONTS to search among all the included .h
113  * files.
114  *
115  * name: Font name to search for.
116  * fonts: Pointer to the first font search entry.
117  *
118  * Returns a pointer to the font or NULL if not found.
119  */
120 MF_EXTERN const struct mf_font_s *mf_find_font(const char *name);
121 
122 /* Get the list of included fonts */
123 MF_EXTERN const struct mf_font_list_s *mf_get_font_list(void);
124 
125 #endif