2 * kmscon - Font handling
4 * Copyright (c) 2012-2013 David Herrmann <dh.herrmann@googlemail.com>
6 * Permission is hereby granted, free of charge, to any person obtaining
7 * a copy of this software and associated documentation files
8 * (the "Software"), to deal in the Software without restriction, including
9 * without limitation the rights to use, copy, modify, merge, publish,
10 * distribute, sublicense, and/or sell copies of the Software, and to
11 * permit persons to whom the Software is furnished to do so, subject to
12 * the following conditions:
14 * The above copyright notice and this permission notice shall be included
15 * in all copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
20 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
21 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
28 * @short_description: Font handling
31 * The text renderer needs a backend that draws glyphs which then can be shown
32 * on the screen. This font handling subsystem provides a very simple API to
33 * load arbitrary font-renderer backends. That is, you can choose from
34 * in-memory bitmap fonts up to full Unicode compatible font libraries like
35 * pango during runtime.
37 * This system does not provide any renderer by itself. You need to register one
38 * of the available font-renderers first which then is used as backend for this
39 * system. kmscon_font_register() and kmscon_font_unregister() can be used to
40 * register font-renderers manually.
42 * @kmscon_font_attr is used to specify font-attributes for the fonts you want.
43 * Please see kmscon_font_find() for more information on font-attributes. This
44 * function returns a matching font which then can be used for drawing.
45 * kmscon_font_ref()/kmscon_font_unref() are used for reference counting.
46 * kmscon_font_render() renders a single unicode glyph and returns the glyph
47 * buffer. kmscon_font_drop() frees this buffer again. A kmscon_glyph object
48 * contains a memory-buffer with the rendered glyph plus some metrics like
49 * height/width but also ascent/descent.
51 * Font-backends must take into account that this API must be thread-safe as it
52 * is shared between different threads to reduce memory-footprint.
60 #include "kmscon_module.h"
61 #include "shl_dlist.h"
64 #include "shl_register.h"
66 #define LOG_SUBSYSTEM "font"
68 static struct shl_register font_reg = SHL_REGISTER_INIT(font_reg);
71 * kmscon_font_attr_normalize:
72 * @attr: Attribute to normalize
74 * This normalizes @attr and fills out missing entries. The following is done:
75 * - If attr->name is empty, then it is set to KMSCON_FONT_DEFAULT_NAME
76 * - If attr->ppi is 0, it is set to KMSCON_FONT_DEFAULT_PPI
77 * - If attr->height is not set but attr->points is given, then attr->heights is
78 * calculated from attr->points.
79 * - If attr->height is set, then attr->points is recalculated and overwritten
81 * The other fields are not changed. If attr->points is set but attr->height is
82 * not set, then the height is calculated and after that the points are
83 * recalculated so we will never have division-errors.
86 void kmscon_font_attr_normalize(struct kmscon_font_attr *attr)
92 memcpy(attr->name, KMSCON_FONT_DEFAULT_NAME,
93 sizeof(KMSCON_FONT_DEFAULT_NAME));
96 attr->ppi = KMSCON_FONT_DEFAULT_PPI;
98 if (!attr->height && attr->points)
99 attr->height = attr->points * attr->ppi / 72;
101 attr->points = attr->height * 72 / attr->ppi;
105 * kmscon_font_attr_match:
106 * @a1: First attribute to match
107 * @a2: Second attribute to match
109 * Compares @a1 and @a2 and returns true if they match. Both must be normalized
110 * before comparing them, otherwise the comparison may return inexact results.
111 * If width, height or *name is 0, then the fields are _not_ compared so you can
112 * have wildmask matches.
113 * points and dpi are never compared as the normalization already computes the
114 * height correctly. So there is no need to use these.
116 * Returns: true if they match, otherwise false
119 bool kmscon_font_attr_match(const struct kmscon_font_attr *a1,
120 const struct kmscon_font_attr *a2)
125 if (a1->width && a2->width && a1->width != a2->width)
127 if (a1->height && a2->height && a1->height != a2->height)
129 if (a1->bold != a2->bold)
131 if (a1->italic != a2->italic)
133 if (*a1->name && *a2->name && strcmp(a1->name, a2->name))
139 static inline void kmscon_font_destroy(void *data)
141 const struct kmscon_font_ops *ops = data;
143 kmscon_module_unref(ops->owner);
147 * kmscon_font_register:
148 * @ops: Font operations and name for new font backend
150 * This register a new font backend with operations set to @ops. The name
151 * @ops->name must be valid.
153 * The first font that is registered automatically becomes the default font and
154 * the fallback font. So make sure you register a safe fallback as first font.
155 * If this font is unregistered, the next font in the list becomes the default
158 * Returns: 0 on success, negative error code on failure
161 int kmscon_font_register(const struct kmscon_font_ops *ops)
168 log_debug("register font backend %s", ops->name);
170 ret = shl_register_add_cb(&font_reg, ops->name, (void*)ops,
171 kmscon_font_destroy);
173 log_error("cannot register font backend %s: %d", ops->name,
178 kmscon_module_ref(ops->owner);
183 * kmscon_font_unregister:
184 * @name: Name of font backend
186 * This unregisters the font-backend that is registered with name @name. If
187 * @name is not found, a warning is printed but nothing else is done.
190 void kmscon_font_unregister(const char *name)
192 log_debug("unregister font backend %s", name);
193 shl_register_remove(&font_reg, name);
196 static int new_font(struct kmscon_font *font,
197 const struct kmscon_font_attr *attr, const char *backend)
199 struct shl_register_record *record;
200 const char *name = backend ? backend : "<default>";
203 memset(font, 0, sizeof(*font));
207 record = shl_register_find(&font_reg, backend);
209 record = shl_register_first(&font_reg);
212 log_error("requested backend '%s' not found", name);
216 font->record = record;
217 font->ops = record->data;
220 ret = font->ops->init(font, attr);
225 log_warning("backend %s cannot create font", name);
226 shl_register_record_unref(record);
235 * @out: A pointer to the new font is stored here
236 * @attr: Attribute describing the font
237 * @backend: Backend to use or NULL for default backend
239 * Lookup a font by the given attributes. It uses the font backend @backend. If
240 * it is NULL, the default backend is used. If the given backend cannot find
241 * a suitable font, the fallback backend is tried. This backend should always
242 * find a suitable font.
244 * Stores a pointer to the new font in @out and returns 0. Otherwise, @out is
245 * not touched and an error is returned.
247 * The attributes in @attr are not always matched. There are even font backends
248 * which have only one fixed font and always return this one so you cannot rely
249 * on this behavior. That is, this function cannot be used to get an exact
250 * match, it rather returns the best matching font.
251 * There is currently no need to get an exact match so no API is available to
252 * get this. Instead, you should always use the best match and the user must be
253 * happy. We do print warnings if no close match can be found, though. The user
254 * should read them if they want more information what font fallback was used.
256 * If this functions fails, you must not assume that there is another font that
257 * might work. Moreover, you must not implement a fallback font yourself as this
258 * is already implemented inside of this function! This function fails only due
259 * to internal errors like failed memory allocations. If it fails, the chances
260 * that you can allocate your own fallback font are pretty small so don't do it.
262 * About DPI and Point Sizes:
263 * Many computer graphics systems use "Points" as measurement for font sizes.
264 * However, most of them also use 72 or 96 as fixed DPI size for monitors. This
265 * means, the Point sizes can be directly converted into pixels. But lets
267 * 1 Point is defined as 1/72 of an inch. That is, a 10 Point font will be
268 * exactly 10 / 72 inches, which is ~0.13889 inches, which is
269 * 0.13889 * 2.54 cm, which is approximately 0.3528 cm. This applies to
270 * printed paper. If we want the same on a monitor, we must need more
271 * information. First, the monitor renders in pixels, that is, we must know
272 * how many Pixels per Inch (PPI) are displayed. Often the same information is
273 * given as Dots per Inch (DPI) but these two are identical in this context.
274 * If the DPI is 96, we know that our 10 Point font is 10 / 72 inches. Which
275 * then means it is 10 / 72 * 96 pixels, which is ~13.333 pixels. So we
276 * internally render the font with 13 pixels and display it as 13 pixels. This
277 * guarantees, that the font will be 10 Point big which means 0.3528 cm on the
278 * display. This of course requires that we know the exact PPI/DPI of the
280 * But if we take into account that Windows uses fixed 96 PPI and Mac OS X 72
281 * PPI (independent of the monitor), they drop all this information and instead
282 * render the font in pixel sizes. Because if you use fixed 72 PPI, a 10 Point
283 * font will always be 10 / 72 * 72 = 10 pixels high. This means, it would be
284 * rather convenient to directly specify pixel-sizes on the monitor. If you want
285 * to work with documents that shall be printed, you want to specify Points so
286 * the printed result will look nice. But the disadvantage is, that your monitor
287 * can print this font in the weirdest size if it uses PPI much bigger or lower
288 * than the common 96 or 72. Therefore, if you work with a monitor you probably
289 * want to also specify the pixel-height of the font as you probably don't know
290 * the PPI of your monitor and don't want to do all that math in your head.
291 * Therefore, for applications that will probably never print their output (like
292 * the virtual (!) console this is for), it is often requested that we can
293 * specify the pixel size instead of the Point size of a font so you can
294 * predict the output better.
295 * Hence, we provide both. If pixel information is given, that is, attr->height
296 * is not 0, then we try to return a font with this pixel height.
297 * If it is 0, attr->points is used together with attr->ppi to calculate the
298 * pixel size. If attr->ppi is 0, then 72 is used.
299 * After the font was chosen, all fields "points", "ppi", "height" and "width"
300 * will contain the exact values for this font. If "ppi" was zero and pixel
301 * sizes where specified, then the resulting "points" size is calculated with
302 * "ppi" = 72 again. So if you use the "points" field please always specify
305 * Returns: 0 on success, error code on failure
307 int kmscon_font_find(struct kmscon_font **out,
308 const struct kmscon_font_attr *attr,
311 struct kmscon_font *font;
317 log_debug("searching for: be: %s nm: %s ppi: %u pt: %u b: %d i: %d he: %u wt: %u",
318 backend, attr->name, attr->ppi, attr->points,
319 attr->bold, attr->italic, attr->height,
322 font = malloc(sizeof(*font));
324 log_error("cannot allocate memory for new font");
328 ret = new_font(font, attr, backend);
331 ret = new_font(font, attr, NULL);
336 log_debug("using: be: %s nm: %s ppi: %u pt: %u b: %d i: %d he: %u wt: %u",
337 font->ops->name, font->attr.name, font->attr.ppi,
338 font->attr.points, font->attr.bold, font->attr.italic,
339 font->attr.height, font->attr.width);
350 * @font: Valid font object
352 * This increases the reference count of @font by one.
354 void kmscon_font_ref(struct kmscon_font *font)
356 if (!font || !font->ref)
364 * @font: Valid font object
366 * This decreases the reference count of @font by one. If it drops to zero, the
369 void kmscon_font_unref(struct kmscon_font *font)
371 if (!font || !font->ref || --font->ref)
374 log_debug("freeing font");
375 if (font->ops->destroy)
376 font->ops->destroy(font);
377 shl_register_record_unref(font->record);
382 * kmscon_font_render:
383 * @font: Valid font object
384 * @id: Unique ID that identifies @ch globally
385 * @ch: Symbol to find a glyph for
386 * @len: Length of @ch
387 * @out: Output buffer for glyph
389 * Renders the glyph for symbol @sym and places a pointer to the glyph in @out.
390 * If the glyph cannot be found or is invalid, an error is returned. The glyph
391 * is cached internally and removed when the last reference to this font is
393 * If the glyph is no available in this font-set, then -ERANGE is returned.
395 * Returns: 0 on success, negative error code on failure
398 int kmscon_font_render(struct kmscon_font *font,
399 uint32_t id, const uint32_t *ch, size_t len,
400 const struct kmscon_glyph **out)
402 if (!font || !out || !ch || !len)
405 return font->ops->render(font, id, ch, len, out);
409 * kmscon_font_render_empty:
410 * @font: Valid font object
411 * @out: Output buffer for glyph
413 * Same as kmscon_font_render() but this renders a glyph that has no content and
414 * can be used to blit solid backgrounds. That is, the resulting buffer will be
415 * all 0 but the dimensions are the same as for all other glyphs.
417 * Returns: 0 on success, negative error code on failure
420 int kmscon_font_render_empty(struct kmscon_font *font,
421 const struct kmscon_glyph **out)
426 return font->ops->render_empty(font, out);
430 * kmscon_font_render_inval:
431 * @font: Valid font object
432 * @out: Output buffer for glyph
434 * Same sa kmscon_font_render_empty() but renders a glyph that can be used as
435 * replacement for any other non-drawable glyph. That is, if
436 * kmscon_font_render() returns -ERANGE, then this glyph can be used as
439 * Returns: 0 on success ,engative error code on failure
442 int kmscon_font_render_inval(struct kmscon_font *font,
443 const struct kmscon_glyph **out)
448 return font->ops->render_inval(font, out);