1 /* font.h -- Interface definition for font handling.
2 Copyright (C) 2006-2023 Free Software Foundation, Inc.
3 Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011
4 National Institute of Advanced Industrial Science and Technology (AIST)
5 Registration Number H13PRO009
6
7 This file is part of GNU Emacs.
8
9 GNU Emacs is free software: you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation, either version 3 of the License, or (at
12 your option) any later version.
13
14 GNU Emacs is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */
21
22 #ifndef EMACS_FONT_H
23 #define EMACS_FONT_H
24
25 #ifdef HAVE_HARFBUZZ
26 #include <hb.h>
27 #endif /* HAVE_HARFBUZZ */
28
29 struct composition_it;
30 struct face;
31 struct glyph_string;
32
33 INLINE_HEADER_BEGIN
34
35 /* We have three types of Lisp objects related to font.
36
37 FONT-SPEC
38
39 Pseudo vector (length FONT_SPEC_MAX) of font properties. Some
40 properties can be left unspecified (i.e. nil). Emacs asks
41 font-drivers to find a font by FONT-SPEC. A fontset entry
42 specifies requisite properties whereas a face specifies just
43 preferable properties.
44
45 FONT-ENTITY
46
47 Pseudo vector (length FONT_ENTITY_MAX) of fully instantiated
48 font properties that a font-driver returns upon a request of
49 FONT-SPEC.
50
51 Note: Only the method `list' and `match' of a font-driver can
52 create this object, and it should never be modified by Lisp.
53
54 FONT-OBJECT
55
56 Pseudo vector (length FONT_OBJECT_MAX) of an opened font.
57
58 Lisp object encapsulating "struct font". This corresponds to
59 an opened font.
60
61 Note: Only the method `open_font' of a font-driver can create this
62 object, and it should never be modified by Lisp. */
63
64
65 /* An enumerator for each font property. This is used as an index to
66 the vector of FONT-SPEC and FONT-ENTITY.
67
68 Note: The order is important and should not be changed. */
69
70 enum font_property_index
71 {
72 /* FONT-TYPE is a symbol indicating a font backend; currently `x',
73 `xft', `xfthb', `ftrc', and `ftcrhb' are available on X;
74 `harfbuzz', `uniscribe', and `gdi' on Windows, and `ns' under
75 Cocoa / GNUstep. */
76 FONT_TYPE_INDEX,
77
78 /* FONT-FOUNDRY is a foundry name (symbol). */
79 FONT_FOUNDRY_INDEX,
80
81 /* FONT-FAMILY is a family name (symbol). */
82 FONT_FAMILY_INDEX,
83
84 /* FONT-ADSTYLE is an additional style name (symbol). */
85 FONT_ADSTYLE_INDEX,
86
87 /* FONT-REGISTRY is a combination of a charset-registry and
88 charset-encoding name (symbol). */
89 FONT_REGISTRY_INDEX,
90
91 /* FONT-WEIGHT is a numeric value of weight (e.g. medium, bold) of
92 the font. The lowest 8 bits is an index determining the
93 symbolic name, and the higher bits is the actual numeric value
94 defined in `font-weight-table'. */
95 FONT_WEIGHT_INDEX,
96
97 /* FONT-SLANT is a numeric value of slant (e.g. r, i, o) of the
98 font. The lowest 8 bits is an index determining the symbolic
99 name, and the higher bits is the actual numeric value defined
100 in `font-slant-table'. */
101 FONT_SLANT_INDEX,
102
103 /* FONT-WIDTH is a numeric value of setwidth (e.g. normal) of the
104 font. The lowest 8 bits is an index determining the symbolic
105 name, and the higher bits is the actual numeric value defined
106 `font-width-table'. */
107 FONT_WIDTH_INDEX,
108
109 /* FONT-SIZE is a size of the font. If integer, it is a pixel
110 size. For a font-spec, the value can be a float specifying
111 the point size. The value zero means that the font is
112 scalable. */
113 FONT_SIZE_INDEX,
114
115 /* FONT-DPI is a resolution (dot per inch) for which the font is
116 designed. */
117 FONT_DPI_INDEX,
118
119 /* FONT-SPACING is a spacing (mono, proportional, charcell) of the
120 font (integer; one of enum font_spacing). */
121 FONT_SPACING_INDEX,
122
123 /* FONT-AVGWIDTH is an average width (1/10 pixel unit) of the
124 font. */
125 FONT_AVGWIDTH_INDEX,
126
127 #if false
128 /* The following two members are to substitute for the above 6
129 members (FONT_WEIGHT_INDEX to FONT_AVGWIDTH_INDEX excluding
130 FONT_SIZE_INDEX) if it is found that font-entities consumes too
131 much memory. */
132
133 /* FONT-STYLE is a 24-bit integer containing indices for
134 style-related properties WEIGHT, SLANT, and WIDTH. The lowest
135 8 bits is an index to the weight table AREF (font_style_table,
136 0), the next 8 bits is an index to the slant table AREF
137 (font_style_table, 1), the highest 8 bits is an index to the
138 slant table AREF (font_style_table, 2). The index 0 indicates
139 that the corresponding style is not specified. This way, we
140 can represent at most 255 different names for each style, which
141 is surely sufficient. */
142 FONT_STYLE_INDEX,
143
144 /* FONT-METRICS is a 27-bit integer containing metrics-related
145 properties DPI, AVGWIDTH, SPACING. The lowest 12 bits is for
146 DPI, the next 12 bits is for AVGWIDTH, the highest 3 bits is for
147 SPACING. In each bit field, the highest bit indicates that the
148 corresponding value is set or not. This way, we can represent
149 DPI by 11-bit (0 to 2047), AVGWIDTH by 11-bit (0 to 2047),
150 SPACING by 3-bit (0 for proportional, 1 for dual, 2 for mono, 3
151 for charcell), which is surely sufficient. */
152 FONT_METRICS_INDEX,
153 #endif
154
155 /* In a font-spec, the value is an alist of extra information of a
156 font such as name, OpenType features, and language coverage.
157 In addition, in a font-entity, the value may contain a pair
158 (font-entity . INFO) where INFO is extra information to
159 identify a font (font-driver dependent). In a font-entity,
160 this holds font driver-specific information. */
161 FONT_EXTRA_INDEX, /* alist alist */
162
163 /* This value is the length of font-spec vector. */
164 FONT_SPEC_MAX,
165
166 /* The followings are used only for a font-entity and a font-object. */
167
168 /* List of font-objects opened from the font-entity. */
169 FONT_OBJLIST_INDEX = FONT_SPEC_MAX,
170
171 /* This value is the length of font-entity vector. */
172 FONT_ENTITY_MAX,
173
174 /* The followings are used only for a font-object. */
175
176 /* XLFD name of the font (string). */
177 FONT_NAME_INDEX = FONT_ENTITY_MAX,
178
179 /* Full name of the font (string). It is the name extracted from
180 the opened font, and may be different from the above. It may be
181 nil if the opened font doesn't give a name. */
182 FONT_FULLNAME_INDEX,
183
184 /* File name of the font or nil if a file associated with the font
185 is not available. */
186 FONT_FILE_INDEX,
187
188 /* This value is the length of font-object vector. */
189 FONT_OBJECT_MAX
190 };
191
192 /* Return the numeric weight value of FONT. */
193 #define FONT_WEIGHT_NUMERIC(font) \
194 (FIXNUMP (AREF ((font), FONT_WEIGHT_INDEX)) \
195 ? (XFIXNUM (AREF ((font), FONT_WEIGHT_INDEX)) >> 8) : -1)
196 /* Return the numeric slant value of FONT. */
197 #define FONT_SLANT_NUMERIC(font) \
198 (FIXNUMP (AREF ((font), FONT_SLANT_INDEX)) \
199 ? (XFIXNUM (AREF ((font), FONT_SLANT_INDEX)) >> 8) : -1)
200 /* Return the numeric width value of FONT. */
201 #define FONT_WIDTH_NUMERIC(font) \
202 (FIXNUMP (AREF ((font), FONT_WIDTH_INDEX)) \
203 ? (XFIXNUM (AREF ((font), FONT_WIDTH_INDEX)) >> 8) : -1)
204 /* Return the symbolic weight value of FONT. */
205 #define FONT_WEIGHT_SYMBOLIC(font) \
206 font_style_symbolic (font, FONT_WEIGHT_INDEX, false)
207 /* Return the symbolic slant value of FONT. */
208 #define FONT_SLANT_SYMBOLIC(font) \
209 font_style_symbolic (font, FONT_SLANT_INDEX, false)
210 /* Return the symbolic width value of FONT. */
211 #define FONT_WIDTH_SYMBOLIC(font) \
212 font_style_symbolic (font, FONT_WIDTH_INDEX, false)
213 /* Return the face-weight corresponding to the weight of FONT. */
214 #define FONT_WEIGHT_FOR_FACE(font) \
215 font_style_symbolic (font, FONT_WEIGHT_INDEX, true)
216 /* Return the face-slant corresponding to the slant of FONT. */
217 #define FONT_SLANT_FOR_FACE(font) \
218 font_style_symbolic (font, FONT_SLANT_INDEX, true)
219 /* Return the face-swidth corresponding to the slant of FONT. */
220 #define FONT_WIDTH_FOR_FACE(font) \
221 font_style_symbolic (font, FONT_WIDTH_INDEX, true)
222
223 /* Return the numeric weight value corresponding to the symbol NAME. */
224 #define FONT_WEIGHT_NAME_NUMERIC(name) \
225 (font_style_to_value (FONT_WEIGHT_INDEX, (name), false) >> 8)
226 /* Return the numeric slant value corresponding to the symbol NAME. */
227 #define FONT_SLANT_NAME_NUMERIC(name) \
228 (font_style_to_value (FONT_SLANT_INDEX, (name), false) >> 8)
229 /* Return the numeric width value corresponding to the symbol NAME. */
230 #define FONT_WIDTH_NAME_NUMERIC(name) \
231 (font_style_to_value (FONT_WIDTH_INDEX, (name), false) >> 8)
232
233 /* Set the font property PROP of FONT to VAL. PROP is one of
234 style-related font property index (FONT_WEIGHT/SLANT/WIDTH_INDEX).
235 VAL (integer or symbol) is the numeric or symbolic style value. */
236 #define FONT_SET_STYLE(font, prop, val) \
237 ASET ((font), prop, make_fixnum (font_style_to_value (prop, val, true)))
238
239 #ifndef MSDOS
240 #define FONT_WIDTH(f) ((f)->max_width)
241 #else
242 #define FONT_WIDTH(f) 1
243 #endif
244 #define FONT_HEIGHT(f) ((f)->height)
245 #define FONT_BASE(f) ((f)->ascent)
246 #define FONT_DESCENT(f) ((f)->descent)
247
248
249 /* Structure for a font-spec. */
250
251 struct font_spec
252 {
253 union vectorlike_header header;
254 Lisp_Object props[FONT_SPEC_MAX];
255 };
256
257 /* Structure for a font-entity. */
258
259 struct font_entity
260 {
261 union vectorlike_header header;
262 Lisp_Object props[FONT_ENTITY_MAX];
263 };
264
265 /* A value which may appear in the member `encoding' of struct font
266 indicating that a font itself doesn't tell which encoding to be
267 used. */
268 #define FONT_ENCODING_NOT_DECIDED 255
269
270 /* Structure for a font-object. */
271
272 struct font
273 {
274 union vectorlike_header header;
275
276 /* All Lisp_Object components must come first.
277 That ensures they are all aligned normally. */
278
279 Lisp_Object props[FONT_OBJECT_MAX];
280
281 /* Beyond here, there should be no more Lisp_Object components. */
282
283 /* Minimum and maximum glyph widths, in pixels. Some font backends,
284 such as xft, lack the information to easily compute minimum and
285 maximum widths over all characters; in that case, these values
286 are approximate. */
287 int min_width;
288 int max_width;
289
290 /* By which pixel size the font is opened. */
291 int pixel_size;
292
293 /* Height of the font. On X window system, this is the same as
294 (font->ascent + font->descent). */
295 int height;
296
297 /* Width of the space glyph of the font. If the font doesn't have a
298 SPACE glyph, the value is 0. */
299 int space_width;
300
301 /* Average width of glyphs in the font. If the font itself doesn't
302 have that information, but has glyphs of ASCII characters, the
303 value is the average width of those glyphs. Otherwise, the value
304 is 0. */
305 int average_width;
306
307 /* Ascent and descent of the font (in pixels). */
308 int ascent, descent;
309
310 /* The following members makes sense on graphic displays only. */
311
312 #if defined (HAVE_WINDOW_SYSTEM)
313
314 /* Vertical pixel width of the underline. If is zero if that
315 information is not in the font. */
316 int underline_thickness;
317
318 /* Vertical pixel position (relative to the baseline) of the
319 underline. If it is positive, it is below the baseline. It is
320 negative if that information is not in the font. */
321 int underline_position;
322
323 /* True if `vertical-centering-font-regexp' matches this font name.
324 In this case, we render characters at vertical center positions
325 of lines. */
326 bool vertical_centering;
327
328 /* The baseline position of a font is normally `ascent' value of the
329 font. However, there exist many fonts which don't set `ascent' to
330 an appropriate value to be used as baseline position. This is
331 typical in such ASCII fonts which are designed to be used with
332 Chinese, Japanese, Korean characters. When we use mixture of
333 such fonts and normal fonts (having correct `ascent' value), a
334 display line gets very ugly. Since we have no way to fix it
335 automatically, it is user's responsibility to supply well designed
336 fonts or correct `ascent' value of fonts. But, the latter
337 requires heavy work (modifying all bitmap data in BDF files).
338 So, Emacs accepts a private font property
339 `_MULE_BASELINE_OFFSET'. If a font has this property, we
340 calculate the baseline position by subtracting the value from
341 `ascent'. In other words, the value indicates how many pixels
342 higher than normal ASCII text we should draw a character of the
343 font for better appearance.
344
345 We also have to consider the fact that the concept of `baseline'
346 differs among scripts to which each character belongs. For
347 instance, baseline should be at the bottom-most position of all
348 glyphs for Chinese, Japanese, and Korean. But, many of existing
349 fonts for those characters don't have correct `ascent' values
350 because they are designed to be used with ASCII fonts. To
351 display characters of different language on the same line, the
352 best way will be to arrange them in the middle of the line. So,
353 in such a case, again, we utilize the font property
354 `_MULE_BASELINE_OFFSET'. If the value is larger than `ascent' we
355 calculate baseline so that a character is arranged in the middle
356 of a line. */
357 int baseline_offset;
358
359 /* Non-zero means a character should be composed at a position
360 relative to the height (or depth) of previous glyphs in the
361 following cases:
362 (1) The bottom of the character is higher than this value. In
363 this case, the character is drawn above the previous glyphs.
364 (2) The top of the character is lower than 0 (i.e. baseline
365 height). In this case, the character is drawn below the
366 previous glyphs.
367
368 This value is taken from a private font property
369 `_MULE_RELATIVE_COMPOSE' which is introduced by Emacs. */
370 int relative_compose;
371
372 /* Non-zero means an ascent value to be used for a character
373 registered in char-table `use-default-ascent'. */
374 int default_ascent;
375
376 /* Charset to encode a character code into a glyph code of the font.
377 -1 means that the font doesn't require this information to encode
378 a character. */
379 int encoding_charset;
380
381 /* Charset to check if a character code is supported by the font.
382 -1 means that the contents of the font must be looked up to
383 determine it. */
384 int repertory_charset;
385
386 #endif /* HAVE_WINDOW_SYSTEM */
387
388 /* Font-driver for the font. */
389 struct font_driver const *driver;
390
391 /* There are more members in this structure, but they are private
392 to the font-driver. */
393 };
394
395 enum font_spacing
396 {
397 FONT_SPACING_PROPORTIONAL = 0,
398 FONT_SPACING_DUAL = 90,
399 FONT_SPACING_MONO = 100,
400 FONT_SPACING_CHARCELL = 110
401 };
402
403 struct font_metrics
404 {
405 short lbearing, rbearing, width, ascent, descent;
406 };
407
408 struct font_bitmap
409 {
410 int bits_per_pixel;
411 int rows;
412 int width;
413 int pitch;
414 unsigned char *buffer;
415 int left;
416 int top;
417 int advance;
418 };
419
420 /* Predicates to check various font-related objects. */
421
422 /* True iff X is one of font-spec, font-entity, and font-object. */
423 INLINE bool
424 FONTP (Lisp_Object x)
425 {
426 return PSEUDOVECTORP (x, PVEC_FONT);
427 }
428
429 /* True iff X is font-spec. */
430 INLINE bool
431 FONT_SPEC_P (Lisp_Object x)
432 {
433 return FONTP (x) && PVSIZE (x) == FONT_SPEC_MAX;
434 }
435
436 /* Like FONT_SPEC_P, but can be used in the garbage collector. */
437 INLINE bool
438 GC_FONT_SPEC_P (Lisp_Object x)
439 {
440 return FONTP (x) && (gc_asize (x) & PSEUDOVECTOR_SIZE_MASK) == FONT_SPEC_MAX;
441 }
442
443 /* True iff X is font-entity. */
444 INLINE bool
445 FONT_ENTITY_P (Lisp_Object x)
446 {
447 return FONTP (x) && PVSIZE (x) == FONT_ENTITY_MAX;
448 }
449
450 /* Like FONT_ENTITY_P, but can be used in the garbage collector. */
451 INLINE bool
452 GC_FONT_ENTITY_P (Lisp_Object x)
453 {
454 return FONTP (x) && (gc_asize (x) & PSEUDOVECTOR_SIZE_MASK) == FONT_ENTITY_MAX;
455 }
456
457 /* True iff X is font-object. */
458 INLINE bool
459 FONT_OBJECT_P (Lisp_Object x)
460 {
461 return FONTP (x) && PVSIZE (x) == FONT_OBJECT_MAX;
462 }
463
464 /* Like FONT_OBJECT_P, but can be used in the garbage collector. */
465 INLINE bool
466 GC_FONT_OBJECT_P (Lisp_Object x)
467 {
468 return FONTP (x) && (gc_asize (x) & PSEUDOVECTOR_SIZE_MASK) == FONT_OBJECT_MAX;
469 }
470
471 /* Type checking functions for various font-related objects. */
472
473 INLINE void
474 CHECK_FONT (Lisp_Object x)
475 {
476 CHECK_TYPE (FONTP (x), Qfont, x);
477 }
478
479 INLINE void
480 CHECK_FONT_SPEC (Lisp_Object x)
481 {
482 CHECK_TYPE (FONT_SPEC_P (x), Qfont_spec, x);
483 }
484
485 INLINE void
486 CHECK_FONT_ENTITY (Lisp_Object x)
487 {
488 CHECK_TYPE (FONT_ENTITY_P (x), Qfont_entity, x);
489 }
490
491 INLINE void
492 CHECK_FONT_OBJECT (Lisp_Object x)
493 {
494 CHECK_TYPE (FONT_OBJECT_P (x), Qfont_object, x);
495 }
496
497 /* C pointer extraction functions for various font-related objects. */
498
499 INLINE struct font_spec *
500 XFONT_SPEC (Lisp_Object p)
501 {
502 eassert (FONT_SPEC_P (p));
503 return XUNTAG (p, Lisp_Vectorlike, struct font_spec);
504 }
505
506 INLINE struct font_spec *
507 GC_XFONT_SPEC (Lisp_Object p)
508 {
509 eassert (GC_FONT_SPEC_P (p));
510 return XUNTAG (p, Lisp_Vectorlike, struct font_spec);
511 }
512
513 INLINE struct font_entity *
514 XFONT_ENTITY (Lisp_Object p)
515 {
516 eassert (FONT_ENTITY_P (p));
517 return XUNTAG (p, Lisp_Vectorlike, struct font_entity);
518 }
519
520 INLINE struct font_entity *
521 GC_XFONT_ENTITY (Lisp_Object p)
522 {
523 eassert (GC_FONT_ENTITY_P (p));
524 return XUNTAG (p, Lisp_Vectorlike, struct font_entity);
525 }
526
527 INLINE struct font *
528 XFONT_OBJECT (Lisp_Object p)
529 {
530 eassert (FONT_OBJECT_P (p));
531 return XUNTAG (p, Lisp_Vectorlike, struct font);
532 }
533
534 INLINE struct font *
535 GC_XFONT_OBJECT (Lisp_Object p)
536 {
537 eassert (GC_FONT_OBJECT_P (p));
538 return XUNTAG (p, Lisp_Vectorlike, struct font);
539 }
540
541 #define XSETFONT(a, b) (XSETPSEUDOVECTOR (a, b, PVEC_FONT))
542
543 INLINE struct font *
544 CHECK_FONT_GET_OBJECT (Lisp_Object x)
545 {
546 CHECK_FONT_OBJECT (x);
547 return XFONT_OBJECT (x);
548 }
549
550 /* Number of pt per inch (from the TeXbook). */
551 #define PT_PER_INCH 72.27
552
553 /* Return a pixel size (integer) corresponding to POINT size (double)
554 on resolution DPI. */
555 #define POINT_TO_PIXEL(POINT, DPI) ((POINT) * (DPI) / PT_PER_INCH + 0.5)
556
557 /* Return a point size corresponding to POINT size (integer)
558 on resolution DPI. Note that though point size is a double, we expect
559 it to be rounded to an int, so we add 0.5 here. If the desired value
560 is tenths of points (as in xfld specs), then the pixel size should
561 be multiplied BEFORE the conversion to avoid magnifying the error. */
562 #define PIXEL_TO_POINT(PIXEL, DPI) ((PIXEL) * PT_PER_INCH / (DPI) + 0.5)
563
564 /* Ignore the difference of font pixel sizes less than or equal to
565 this value. */
566 #define FONT_PIXEL_SIZE_QUANTUM 1
567
568 #define FONT_INVALID_CODE 0xFFFFFFFF
569
570 /* Font driver. Members specified as "optional" can be NULL. */
571
572 struct font_driver
573 {
574 /* Symbol indicating the type of the font-driver. */
575 Lisp_Object type;
576
577 /* True iff the font's foundry, family, and adstyle names are case
578 sensitive. */
579 bool case_sensitive;
580
581 /* Return a cache of font-entities on frame F. The cache must be a
582 cons whose cdr part is the actual cache area. */
583 Lisp_Object (*get_cache) (struct frame *f);
584
585 /* List fonts exactly matching FONT_SPEC on FRAME. The value is
586 a list of font-entities. The font properties to be considered
587 are: :foundry, :family, :adstyle, :registry, :script, :lang, and
588 :otf. See the function `font-spec' for their meanings. Note
589 that the last three properties are stored in FONT_EXTRA_INDEX
590 slot of FONT_SPEC.
591
592 The returned value is a list of font-entities. Each font-entity
593 has :type property whose value is the same as the above `type'.
594 It also has these properties if they are available from the
595 corresponding font; :foundry, :family, :adstyle, :registry,
596 :weight, :slant, :width, :size, :dpi, :spacing, :avgwidth. If
597 the font is scalable, :size and :avgwidth must be 0.
598
599 The `open_font' method of the same font-backend is called with one of
600 the returned font-entities. If the backend needs additional
601 information to be used in `open_font' method, this method can add any
602 Lispy value using the property :font-entity to the entities.
603
604 This and the following `match' are the only APIs that allocate
605 font-entities. */
606 Lisp_Object (*list) (struct frame *frame, Lisp_Object font_spec);
607
608 /* Return a font-entity most closely matching FONT_SPEC on FRAME.
609 Which font property to consider, and how to calculate the
610 closeness, is determined by the font backend, thus
611 `face-font-selection-order' is ignored here.
612
613 The properties that the font-entity has are the same as described
614 for the `list' method above. */
615 Lisp_Object (*match) (struct frame *f, Lisp_Object font_spec);
616
617 /* Optional.
618 List available families. The value is a list of family names
619 (symbols). */
620 Lisp_Object (*list_family) (struct frame *f);
621
622 /* Optional.
623 Free FONT_EXTRA_INDEX field of FONT_ENTITY. */
624 void (*free_entity) (Lisp_Object font_entity);
625
626 /* Open a font specified by FONT_ENTITY on frame F. If the font is
627 scalable, open it with PIXEL_SIZE. */
628 Lisp_Object (*open_font) (struct frame *f, Lisp_Object font_entity,
629 int pixel_size);
630
631 /* Close FONT. NOTE: this can be called by GC. */
632 void (*close_font) (struct font *font);
633
634 /* Prepare FACE for displaying characters by FONT on frame F by
635 storing some data in FACE->extra. */
636 void (*prepare_face) (struct frame *f, struct face *face);
637
638 /* Optional.
639 Done with FACE for displaying characters by FACE->font on frame F. */
640 void (*done_face) (struct frame *f, struct face *face);
641
642 /* Optional.
643 If FONT (FONT-ENTITY or FONT-OBJECT) has a glyph for character C
644 (Unicode code point), return 1. If not, return 0. If FONT is
645 FONT-ENTITY and it must be opened to check it, return -1. */
646 int (*has_char) (Lisp_Object font, int c);
647
648 /* Return a glyph code of FONT for character C (Unicode code point).
649 If FONT doesn't have such a glyph, return FONT_INVALID_CODE. */
650 unsigned (*encode_char) (struct font *font, int c);
651
652 /* Compute the total metrics of the NGLYPHS glyphs specified by
653 the font FONT and the sequence of glyph codes CODE, and store the
654 result in METRICS. */
655 void (*text_extents) (struct font *font,
656 const unsigned *code, int nglyphs,
657 struct font_metrics *metrics);
658
659 #ifdef HAVE_WINDOW_SYSTEM
660
661 /* Optional.
662 Draw glyphs between FROM and TO of S->char2b at (X Y) pixel
663 position of frame S->f with S->face and S->gc. If WITH_BACKGROUND,
664 fill the background in advance. It is assured that WITH_BACKGROUND
665 is false when (FROM > 0 || TO < S->nchars). */
666 int (*draw) (struct glyph_string *s, int from, int to,
667 int x, int y, bool with_background);
668
669 /* Optional.
670 Store bitmap data for glyph-code CODE of FONT in BITMAP. It is
671 intended that this method is called from other font-driver
672 methods for actual drawing. */
673 int (*get_bitmap) (struct font *font, unsigned code,
674 struct font_bitmap *bitmap,
675 int bits_per_pixel);
676
677 /* Optional.
678 Free bitmap data in BITMAP. */
679 void (*free_bitmap) (struct font *font, struct font_bitmap *bitmap);
680
681 #endif /* HAVE_WINDOW_SYSTEM */
682
683 /* Optional.
684 Get coordinates of the INDEXth anchor point of the glyph whose
685 code is CODE. Store the coordinates in *X and *Y. Return 0 if
686 the operation was successful. Otherwise return -1. */
687 int (*anchor_point) (struct font *font, unsigned code, int index,
688 int *x, int *y);
689
690 /* Optional.
691 Return a list describing which scripts/languages FONT
692 supports by which GSUB/GPOS features of OpenType tables.
693 The list should be of the form (GSUB GPOS), where both
694 GSUB and GPOS are lists of the form
695 ((SCRIPT (LANGSYS FEATURE ...) ...) ...) */
696 Lisp_Object (*otf_capability) (struct font *font);
697
698 /* Optional.
699 Apply FONT's OTF-FEATURES to the glyph string.
700
701 FEATURES specifies which OTF features to apply in this format:
702 (SCRIPT LANGSYS GSUB-FEATURE GPOS-FEATURE)
703 See the documentation of `font-drive-otf' for the details.
704
705 This method applies the specified features to the codes in the
706 elements of GSTRING-IN (between FROMth and TOth). The output
707 codes are stored in GSTRING-OUT at the IDXth element and the
708 following elements.
709
710 Return the number of output codes. If none of the features are
711 applicable to the input data, return 0. If GSTRING-OUT is too
712 short, return -1.
713
714 Note: This method is currently not implemented by any font
715 back-end, and is only called by 'font-drive-otf' and
716 'font-otf-alternates', which are themselves ifdef'ed away. */
717 int (*otf_drive) (struct font *font, Lisp_Object features,
718 Lisp_Object gstring_in, int from, int to,
719 Lisp_Object gstring_out, int idx, bool alternate_subst);
720
721 /* Optional.
722 Make the font driver ready for frame F. Usually this function
723 makes some data specific to F and stores it in F's font_data
724 member by calling font_put_frame_data. */
725 int (*start_for_frame) (struct frame *f);
726
727 /* Optional.
728 End using the driver for frame F. Usually this function frees
729 some font data stored in frame F's font_data member. */
730 int (*end_for_frame) (struct frame *f);
731
732 /* Optional.
733 Shape text in GSTRING. See the docstring of
734 `composition-get-gstring' for the format of GSTRING. If the
735 (N+1)th element of GSTRING is nil, input of shaping is from the
736 1st to (N)th elements. In each input glyph, FROM, TO, CHAR, and
737 CODE are already set.
738 DIRECTION is either L2R or R2L, or nil if unknown. During
739 redisplay, this comes from applying the UBA, is passed from
740 composition_reseat_it, and is used by the HarfBuzz shaper.
741
742 This function updates all fields of the input glyphs. If the
743 output glyphs (M) are more than the input glyphs (N), (N+1)th
744 through (M)th elements of GSTRING are updated possibly by making
745 a new glyph object and storing it in GSTRING. If (M) is greater
746 than the length of GSTRING, this method should return nil. In
747 that case, the method is called again with a larger GSTRING. */
748 Lisp_Object (*shape) (Lisp_Object lgstring, Lisp_Object direction);
749
750 /* Optional.
751 If FONT is usable on frame F, return 0. Otherwise return -1.
752 This method is used only for debugging. If this method is NULL,
753 Emacs assumes that the font is usable on any frame. */
754 int (*check) (struct frame *f, struct font *font);
755
756 /* Optional.
757 Return the number of variation glyphs of character C supported by
758 FONT. VARIATIONS is an array of 256 elements. If the variation
759 selector N (1..256) defines a glyph, that glyph code is stored in
760 the (N-1)th element of VARIATIONS. */
761 int (*get_variation_glyphs) (struct font *font,
762 int c, unsigned variations[256]);
763
764 /* Optional.
765 Set attributes of FONT according to PROPERTIES.
766 PROPERTIES is an alist of pairs (KEY . VALUE) that specifies
767 font properties. This method should use font-put to set
768 properties of FONT supported by the font driver.
769 See font_filter_properties for more details. */
770 void (*filter_properties) (Lisp_Object font, Lisp_Object properties);
771
772 /* Optional.
773 Return non-zero if FONT_OBJECT can be used as a (cached) font
774 for ENTITY on frame F. */
775 bool (*cached_font_ok) (struct frame *f,
776 Lisp_Object font_object,
777 Lisp_Object entity);
778
779 /* Optional.
780 Return non-nil if the driver supports rendering of combining
781 characters for FONT according to Unicode combining class. */
782 Lisp_Object (*combining_capability) (struct font *font);
783
784 /* Optional.
785 Called when frame F is double-buffered and its size changes; Xft
786 relies on this hook to throw away its old XftDraw (which won't
787 work after the size change) and get a new one. */
788 void (*drop_xrender_surfaces) (struct frame *f);
789
790 #ifdef HAVE_HARFBUZZ
791 /* Optional.
792 Return a HarfBuzz font object for FONT and store to
793 *POSITION_UNIT the scale factor to convert a hb_position_t value
794 to the number of pixels. Return NULL if HarfBuzz font object is
795 not available for FONT. */
796 hb_font_t *(*begin_hb_font) (struct font *font, double *position_unit);
797
798 /* Optional.
799 Called when the return value (passed as HB_FONT) of begin_hb_font
800 above is no longer used. Not called if the return value of
801 begin_hb_font was NULL. */
802 void (*end_hb_font) (struct font *font, hb_font_t *hb_font);
803 #endif /* HAVE_HARFBUZZ */
804 };
805
806
807 /* Chain of font drivers. There's one global font driver list
808 (font_driver_list in font.c). In addition, each frame has
809 its own font driver list at F->font_driver_list. */
810
811 struct font_driver_list
812 {
813 /* True iff this driver is currently used. It is ignored in the global
814 font driver list.*/
815 bool on;
816 /* Pointer to the font driver. */
817 struct font_driver const *driver;
818 /* Pointer to the next element of the chain. */
819 struct font_driver_list *next;
820 };
821
822 extern Lisp_Object copy_font_spec (Lisp_Object);
823 extern Lisp_Object merge_font_spec (Lisp_Object, Lisp_Object);
824
825 extern Lisp_Object font_make_entity (void);
826 extern Lisp_Object font_make_object (int, Lisp_Object, int);
827 #if defined (HAVE_XFT) || defined (HAVE_FREETYPE) || defined (HAVE_NS)
828 extern Lisp_Object font_build_object (int, Lisp_Object, Lisp_Object, double);
829 #endif
830
831 extern Lisp_Object find_font_encoding (Lisp_Object);
832 extern int font_registry_charsets (Lisp_Object, struct charset **,
833 struct charset **);
834 extern int font_style_to_value (enum font_property_index prop,
835 Lisp_Object name, bool noerror);
836 extern Lisp_Object font_style_symbolic (Lisp_Object font,
837 enum font_property_index prop,
838 bool for_face);
839
840 extern bool font_match_p (Lisp_Object spec, Lisp_Object font);
841 extern bool font_is_ignored (const char *name, ptrdiff_t namelen);
842 extern Lisp_Object font_list_entities (struct frame *, Lisp_Object);
843
844 extern Lisp_Object font_get_name (Lisp_Object font_object);
845 extern Lisp_Object font_spec_from_name (Lisp_Object font_name);
846 extern Lisp_Object font_get_frame (Lisp_Object font_object);
847 extern int font_has_char (struct frame *, Lisp_Object, int);
848
849 extern void font_clear_prop (Lisp_Object *attrs,
850 enum font_property_index prop);
851 extern Lisp_Object font_find_for_lface (struct frame *f, Lisp_Object *lface,
852 Lisp_Object spec, int c);
853 extern Lisp_Object font_open_for_lface (struct frame *f, Lisp_Object entity,
854 Lisp_Object *lface,
855 Lisp_Object spec);
856 extern Lisp_Object font_load_for_lface (struct frame *f, Lisp_Object *lface,
857 Lisp_Object spec);
858 extern void font_prepare_for_face (struct frame *f, struct face *face);
859 extern void font_done_for_face (struct frame *f, struct face *face);
860 extern void clear_font_cache (struct frame *);
861
862 extern Lisp_Object font_open_by_spec (struct frame *f, Lisp_Object spec);
863 extern Lisp_Object font_open_by_name (struct frame *f, Lisp_Object name);
864
865 extern Lisp_Object font_intern_prop (const char *str, ptrdiff_t len,
866 bool force_symbol);
867 extern void font_update_sort_order (int *order);
868
869 extern void font_parse_family_registry (Lisp_Object family,
870 Lisp_Object registry,
871 Lisp_Object spec);
872
873 extern int font_parse_xlfd (char *name, ptrdiff_t len, Lisp_Object font);
874 extern ptrdiff_t font_unparse_xlfd (Lisp_Object font, int pixel_size,
875 char *name, int bytes);
876 extern void register_font_driver (struct font_driver const *, struct frame *);
877 extern void free_font_driver_list (struct frame *f);
878 #ifdef ENABLE_CHECKING
879 extern bool valid_font_driver (struct font_driver const *);
880 #else
881 INLINE bool
882 valid_font_driver (struct font_driver const *d)
883 {
884 return true;
885 }
886 #endif
887 extern Lisp_Object font_update_drivers (struct frame *f, Lisp_Object list);
888 extern Lisp_Object font_range (ptrdiff_t, ptrdiff_t, ptrdiff_t *,
889 struct window *, struct face *,
890 Lisp_Object, int);
891 extern void font_fill_lglyph_metrics (Lisp_Object, struct font *, unsigned int);
892
893 extern Lisp_Object font_put_extra (Lisp_Object font, Lisp_Object prop,
894 Lisp_Object val);
895
896 #ifdef HAVE_HARFBUZZ
897 extern Lisp_Object hbfont_otf_capability (struct font *);
898 extern Lisp_Object hbfont_shape (Lisp_Object, Lisp_Object);
899 extern Lisp_Object hbfont_combining_capability (struct font *);
900 #endif
901
902 #if defined (HAVE_XFT) || defined (HAVE_FREETYPE)
903 extern void font_put_frame_data (struct frame *, Lisp_Object, void *);
904 extern void *font_get_frame_data (struct frame *f, Lisp_Object);
905 #endif /* HAVE_XFT || HAVE_FREETYPE */
906
907 extern void font_filter_properties (Lisp_Object font,
908 Lisp_Object alist,
909 const char *const boolean_properties[],
910 const char *const non_boolean_properties[]);
911
912 extern void font_drop_xrender_surfaces (struct frame *f);
913
914 #ifdef HAVE_FREETYPE
915 extern int ftfont_anchor_point (struct font *, unsigned int, int,
916 int *, int *);
917 extern int ftfont_get_bitmap (struct font *, unsigned int,
918 struct font_bitmap *, int);
919 extern int ftfont_has_char (Lisp_Object, int);
920 extern int ftfont_variation_glyphs (struct font *, int, unsigned[256]);
921 extern Lisp_Object ftfont_combining_capability (struct font *);
922 extern Lisp_Object ftfont_get_cache (struct frame *);
923 extern Lisp_Object ftfont_list2 (struct frame *, Lisp_Object, Lisp_Object);
924 extern Lisp_Object ftfont_list_family (struct frame *);
925 extern Lisp_Object ftfont_match2 (struct frame *, Lisp_Object, Lisp_Object);
926 extern Lisp_Object ftfont_open (struct frame *, Lisp_Object, int);
927 extern Lisp_Object ftfont_otf_capability (struct font *);
928 extern Lisp_Object ftfont_shape (Lisp_Object, Lisp_Object);
929 extern unsigned ftfont_encode_char (struct font *, int);
930 extern void ftfont_close (struct font *);
931 extern void ftfont_filter_properties (Lisp_Object, Lisp_Object);
932 extern void ftfont_text_extents (struct font *, const unsigned *, int,
933 struct font_metrics *);
934 #ifdef HAVE_HARFBUZZ
935 extern hb_font_t *fthbfont_begin_hb_font (struct font *, double *);
936 #endif /* HAVE_HARFBUZZ */
937 extern void syms_of_ftfont (void);
938 #endif /* HAVE_FREETYPE */
939 #ifdef HAVE_X_WINDOWS
940 extern struct font_driver const xfont_driver;
941 extern Lisp_Object xfont_get_cache (struct frame *);
942 extern void syms_of_xfont (void);
943 #ifdef HAVE_XFT
944 extern struct font_driver const xftfont_driver;
945 #ifdef HAVE_HARFBUZZ
946 extern struct font_driver xfthbfont_driver;
947 #endif /* HAVE_HARFBUZZ */
948 #endif
949 #if defined HAVE_FREETYPE || defined HAVE_XFT
950 extern void syms_of_xftfont (void);
951 #endif
952 #ifdef HAVE_BDFFONT
953 extern void syms_of_bdffont (void);
954 #endif /* HAVE_BDFFONT */
955 #endif /* HAVE_X_WINDOWS */
956 #ifdef HAVE_NTGUI
957 extern struct font_driver w32font_driver;
958 extern struct font_driver uniscribe_font_driver;
959 #ifdef HAVE_HARFBUZZ
960 extern struct font_driver harfbuzz_font_driver;
961 #endif
962 extern void syms_of_w32font (void);
963 #endif /* HAVE_NTGUI */
964 #ifdef HAVE_NS
965 extern struct font_driver const nsfont_driver;
966 extern void syms_of_nsfont (void);
967 extern void syms_of_macfont (void);
968 #endif /* HAVE_NS */
969 #if defined (USE_CAIRO) || defined (USE_BE_CAIRO)
970 extern struct font_driver const ftcrfont_driver;
971 #ifdef HAVE_HARFBUZZ
972 extern struct font_driver ftcrhbfont_driver;
973 #endif /* HAVE_HARFBUZZ */
974 extern void syms_of_ftcrfont (void);
975 #endif
976
977 #ifndef FONT_DEBUG
978 #define FONT_DEBUG
979 #endif
980
981 extern void font_add_log (const char *, Lisp_Object, Lisp_Object);
982 extern void font_deferred_log (const char *, Lisp_Object, Lisp_Object);
983
984 #define FONT_ADD_LOG(ACTION, ARG, RESULT) \
985 do { \
986 if (! EQ (Vfont_log, Qt)) \
987 font_add_log ((ACTION), (ARG), (RESULT)); \
988 } while (false)
989
990 #define FONT_DEFERRED_LOG(ACTION, ARG, RESULT) \
991 do { \
992 if (! EQ (Vfont_log, Qt)) \
993 font_deferred_log ((ACTION), (ARG), (RESULT)); \
994 } while (false)
995
996 /* FIXME: This is for use in functions that can be called while
997 garbage-collecting, but which assume that Lisp data structures are
998 properly-formed. This invalid assumption can lead to core dumps
999 (Bug#20890). */
1000 INLINE bool
1001 font_data_structures_may_be_ill_formed (void)
1002 {
1003 #if defined USE_CAIRO || defined USE_BE_CAIRO
1004 /* Although this works around Bug#20890, it is probably not the
1005 right thing to do. */
1006 return gc_in_progress;
1007 #else
1008 return false;
1009 #endif
1010 }
1011
1012 INLINE_HEADER_END
1013
1014 #endif /* not EMACS_FONT_H */