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 #if defined HAVE_ANDROID && !defined ANDROID_STUBIFY
265 /* Whether or not this is an Android font entity. */
266 bool is_android;
267 #endif
268 };
269
270 /* A value which may appear in the member `encoding' of struct font
271 indicating that a font itself doesn't tell which encoding to be
272 used. */
273 #define FONT_ENCODING_NOT_DECIDED 255
274
275 /* Structure for a font-object. */
276
277 struct font
278 {
279 union vectorlike_header header;
280
281 /* All Lisp_Object components must come first.
282 That ensures they are all aligned normally. */
283
284 Lisp_Object props[FONT_OBJECT_MAX];
285
286 /* Beyond here, there should be no more Lisp_Object components. */
287
288 /* Minimum and maximum glyph widths, in pixels. Some font backends,
289 such as xft, lack the information to easily compute minimum and
290 maximum widths over all characters; in that case, these values
291 are approximate. */
292 int min_width;
293 int max_width;
294
295 /* By which pixel size the font is opened. */
296 int pixel_size;
297
298 /* Height of the font. On X window system, this is the same as
299 (font->ascent + font->descent). */
300 int height;
301
302 /* Width of the space glyph of the font. If the font doesn't have a
303 SPACE glyph, the value is 0. */
304 int space_width;
305
306 /* Average width of glyphs in the font. If the font itself doesn't
307 have that information, but has glyphs of ASCII characters, the
308 value is the average width of those glyphs. Otherwise, the value
309 is 0. */
310 int average_width;
311
312 /* Ascent and descent of the font (in pixels). */
313 int ascent, descent;
314
315 /* The following members makes sense on graphic displays only. */
316
317 #if defined (HAVE_WINDOW_SYSTEM)
318
319 /* Vertical pixel width of the underline. If is zero if that
320 information is not in the font. */
321 int underline_thickness;
322
323 /* Vertical pixel position (relative to the baseline) of the
324 underline. If it is positive, it is below the baseline. It is
325 negative if that information is not in the font. */
326 int underline_position;
327
328 /* True if `vertical-centering-font-regexp' matches this font name.
329 In this case, we render characters at vertical center positions
330 of lines. */
331 bool vertical_centering;
332
333 /* The baseline position of a font is normally `ascent' value of the
334 font. However, there exist many fonts which don't set `ascent' to
335 an appropriate value to be used as baseline position. This is
336 typical in such ASCII fonts which are designed to be used with
337 Chinese, Japanese, Korean characters. When we use mixture of
338 such fonts and normal fonts (having correct `ascent' value), a
339 display line gets very ugly. Since we have no way to fix it
340 automatically, it is user's responsibility to supply well designed
341 fonts or correct `ascent' value of fonts. But, the latter
342 requires heavy work (modifying all bitmap data in BDF files).
343 So, Emacs accepts a private font property
344 `_MULE_BASELINE_OFFSET'. If a font has this property, we
345 calculate the baseline position by subtracting the value from
346 `ascent'. In other words, the value indicates how many pixels
347 higher than normal ASCII text we should draw a character of the
348 font for better appearance.
349
350 We also have to consider the fact that the concept of `baseline'
351 differs among scripts to which each character belongs. For
352 instance, baseline should be at the bottom-most position of all
353 glyphs for Chinese, Japanese, and Korean. But, many of existing
354 fonts for those characters don't have correct `ascent' values
355 because they are designed to be used with ASCII fonts. To
356 display characters of different language on the same line, the
357 best way will be to arrange them in the middle of the line. So,
358 in such a case, again, we utilize the font property
359 `_MULE_BASELINE_OFFSET'. If the value is larger than `ascent' we
360 calculate baseline so that a character is arranged in the middle
361 of a line. */
362 int baseline_offset;
363
364 /* Non-zero means a character should be composed at a position
365 relative to the height (or depth) of previous glyphs in the
366 following cases:
367 (1) The bottom of the character is higher than this value. In
368 this case, the character is drawn above the previous glyphs.
369 (2) The top of the character is lower than 0 (i.e. baseline
370 height). In this case, the character is drawn below the
371 previous glyphs.
372
373 This value is taken from a private font property
374 `_MULE_RELATIVE_COMPOSE' which is introduced by Emacs. */
375 int relative_compose;
376
377 /* Non-zero means an ascent value to be used for a character
378 registered in char-table `use-default-ascent'. */
379 int default_ascent;
380
381 /* Charset to encode a character code into a glyph code of the font.
382 -1 means that the font doesn't require this information to encode
383 a character. */
384 int encoding_charset;
385
386 /* Charset to check if a character code is supported by the font.
387 -1 means that the contents of the font must be looked up to
388 determine it. */
389 int repertory_charset;
390
391 #endif /* HAVE_WINDOW_SYSTEM */
392
393 /* Font-driver for the font. */
394 struct font_driver const *driver;
395
396 /* There are more members in this structure, but they are private
397 to the font-driver. */
398 };
399
400 enum font_spacing
401 {
402 FONT_SPACING_PROPORTIONAL = 0,
403 FONT_SPACING_DUAL = 90,
404 FONT_SPACING_MONO = 100,
405 FONT_SPACING_CHARCELL = 110
406 };
407
408 struct font_metrics
409 {
410 short lbearing, rbearing, width, ascent, descent;
411 };
412
413 struct font_bitmap
414 {
415 int bits_per_pixel;
416 int rows;
417 int width;
418 int pitch;
419 unsigned char *buffer;
420 int left;
421 int top;
422 int advance;
423 };
424
425 /* Predicates to check various font-related objects. */
426
427 /* True iff X is one of font-spec, font-entity, and font-object. */
428 INLINE bool
429 FONTP (Lisp_Object x)
430 {
431 return PSEUDOVECTORP (x, PVEC_FONT);
432 }
433
434 /* True iff X is font-spec. */
435 INLINE bool
436 FONT_SPEC_P (Lisp_Object x)
437 {
438 return FONTP (x) && PVSIZE (x) == FONT_SPEC_MAX;
439 }
440
441 /* Like FONT_SPEC_P, but can be used in the garbage collector. */
442 INLINE bool
443 GC_FONT_SPEC_P (Lisp_Object x)
444 {
445 return FONTP (x) && (gc_asize (x) & PSEUDOVECTOR_SIZE_MASK) == FONT_SPEC_MAX;
446 }
447
448 /* True iff X is font-entity. */
449 INLINE bool
450 FONT_ENTITY_P (Lisp_Object x)
451 {
452 return FONTP (x) && PVSIZE (x) == FONT_ENTITY_MAX;
453 }
454
455 /* Like FONT_ENTITY_P, but can be used in the garbage collector. */
456 INLINE bool
457 GC_FONT_ENTITY_P (Lisp_Object x)
458 {
459 return FONTP (x) && (gc_asize (x) & PSEUDOVECTOR_SIZE_MASK) == FONT_ENTITY_MAX;
460 }
461
462 /* True iff X is font-object. */
463 INLINE bool
464 FONT_OBJECT_P (Lisp_Object x)
465 {
466 return FONTP (x) && PVSIZE (x) == FONT_OBJECT_MAX;
467 }
468
469 /* Like FONT_OBJECT_P, but can be used in the garbage collector. */
470 INLINE bool
471 GC_FONT_OBJECT_P (Lisp_Object x)
472 {
473 return FONTP (x) && (gc_asize (x) & PSEUDOVECTOR_SIZE_MASK) == FONT_OBJECT_MAX;
474 }
475
476 /* Type checking functions for various font-related objects. */
477
478 INLINE void
479 CHECK_FONT (Lisp_Object x)
480 {
481 CHECK_TYPE (FONTP (x), Qfont, x);
482 }
483
484 INLINE void
485 CHECK_FONT_SPEC (Lisp_Object x)
486 {
487 CHECK_TYPE (FONT_SPEC_P (x), Qfont_spec, x);
488 }
489
490 INLINE void
491 CHECK_FONT_ENTITY (Lisp_Object x)
492 {
493 CHECK_TYPE (FONT_ENTITY_P (x), Qfont_entity, x);
494 }
495
496 INLINE void
497 CHECK_FONT_OBJECT (Lisp_Object x)
498 {
499 CHECK_TYPE (FONT_OBJECT_P (x), Qfont_object, x);
500 }
501
502 /* C pointer extraction functions for various font-related objects. */
503
504 INLINE struct font_spec *
505 XFONT_SPEC (Lisp_Object p)
506 {
507 eassert (FONT_SPEC_P (p));
508 return XUNTAG (p, Lisp_Vectorlike, struct font_spec);
509 }
510
511 INLINE struct font_spec *
512 GC_XFONT_SPEC (Lisp_Object p)
513 {
514 eassert (GC_FONT_SPEC_P (p));
515 return XUNTAG (p, Lisp_Vectorlike, struct font_spec);
516 }
517
518 INLINE struct font_entity *
519 XFONT_ENTITY (Lisp_Object p)
520 {
521 eassert (FONT_ENTITY_P (p));
522 return XUNTAG (p, Lisp_Vectorlike, struct font_entity);
523 }
524
525 INLINE struct font_entity *
526 GC_XFONT_ENTITY (Lisp_Object p)
527 {
528 eassert (GC_FONT_ENTITY_P (p));
529 return XUNTAG (p, Lisp_Vectorlike, struct font_entity);
530 }
531
532 INLINE struct font *
533 XFONT_OBJECT (Lisp_Object p)
534 {
535 eassert (FONT_OBJECT_P (p));
536 return XUNTAG (p, Lisp_Vectorlike, struct font);
537 }
538
539 INLINE struct font *
540 GC_XFONT_OBJECT (Lisp_Object p)
541 {
542 eassert (GC_FONT_OBJECT_P (p));
543 return XUNTAG (p, Lisp_Vectorlike, struct font);
544 }
545
546 #define XSETFONT(a, b) (XSETPSEUDOVECTOR (a, b, PVEC_FONT))
547
548 INLINE struct font *
549 CHECK_FONT_GET_OBJECT (Lisp_Object x)
550 {
551 CHECK_FONT_OBJECT (x);
552 return XFONT_OBJECT (x);
553 }
554
555 #ifndef HAVE_ANDROID
556 /* Number of pt per inch (from the TeXbook). */
557 #define PT_PER_INCH 72.27
558 #else
559 /* Android uses this value instead to compensate for different device
560 dimensions. */
561 #define PT_PER_INCH 160.00
562 #endif
563
564 /* Return a pixel size (integer) corresponding to POINT size (double)
565 on resolution DPI. */
566 #define POINT_TO_PIXEL(POINT, DPI) ((POINT) * (DPI) / PT_PER_INCH + 0.5)
567
568 /* Return a point size corresponding to POINT size (integer)
569 on resolution DPI. Note that though point size is a double, we expect
570 it to be rounded to an int, so we add 0.5 here. If the desired value
571 is tenths of points (as in xfld specs), then the pixel size should
572 be multiplied BEFORE the conversion to avoid magnifying the error. */
573 #define PIXEL_TO_POINT(PIXEL, DPI) ((PIXEL) * PT_PER_INCH / (DPI) + 0.5)
574
575 /* Ignore the difference of font pixel sizes less than or equal to
576 this value. */
577 #define FONT_PIXEL_SIZE_QUANTUM 1
578
579 #define FONT_INVALID_CODE 0xFFFFFFFF
580
581 /* Font driver. Members specified as "optional" can be NULL. */
582
583 struct font_driver
584 {
585 /* Symbol indicating the type of the font-driver. */
586 Lisp_Object type;
587
588 /* True iff the font's foundry, family, and adstyle names are case
589 sensitive. */
590 bool case_sensitive;
591
592 /* Return a cache of font-entities on frame F. The cache must be a
593 cons whose cdr part is the actual cache area. */
594 Lisp_Object (*get_cache) (struct frame *f);
595
596 /* List fonts exactly matching FONT_SPEC on FRAME. The value is
597 a list of font-entities. The font properties to be considered
598 are: :foundry, :family, :adstyle, :registry, :script, :lang, and
599 :otf. See the function `font-spec' for their meanings. Note
600 that the last three properties are stored in FONT_EXTRA_INDEX
601 slot of FONT_SPEC.
602
603 The returned value is a list of font-entities. Each font-entity
604 has :type property whose value is the same as the above `type'.
605 It also has these properties if they are available from the
606 corresponding font; :foundry, :family, :adstyle, :registry,
607 :weight, :slant, :width, :size, :dpi, :spacing, :avgwidth. If
608 the font is scalable, :size and :avgwidth must be 0.
609
610 The `open_font' method of the same font-backend is called with one of
611 the returned font-entities. If the backend needs additional
612 information to be used in `open_font' method, this method can add any
613 Lispy value using the property :font-entity to the entities.
614
615 This and the following `match' are the only APIs that allocate
616 font-entities. */
617 Lisp_Object (*list) (struct frame *frame, Lisp_Object font_spec);
618
619 /* Return a font-entity most closely matching FONT_SPEC on FRAME.
620 Which font property to consider, and how to calculate the
621 closeness, is determined by the font backend, thus
622 `face-font-selection-order' is ignored here.
623
624 The properties that the font-entity has are the same as described
625 for the `list' method above. */
626 Lisp_Object (*match) (struct frame *f, Lisp_Object font_spec);
627
628 /* Optional.
629 List available families. The value is a list of family names
630 (symbols). */
631 Lisp_Object (*list_family) (struct frame *f);
632
633 /* Optional.
634 Free FONT_EXTRA_INDEX field of FONT_ENTITY. */
635 void (*free_entity) (Lisp_Object font_entity);
636
637 /* Open a font specified by FONT_ENTITY on frame F. If the font is
638 scalable, open it with PIXEL_SIZE. */
639 Lisp_Object (*open_font) (struct frame *f, Lisp_Object font_entity,
640 int pixel_size);
641
642 /* Close FONT. NOTE: this can be called by GC. */
643 void (*close_font) (struct font *font);
644
645 /* Prepare FACE for displaying characters by FONT on frame F by
646 storing some data in FACE->extra. */
647 void (*prepare_face) (struct frame *f, struct face *face);
648
649 /* Optional.
650 Done with FACE for displaying characters by FACE->font on frame F. */
651 void (*done_face) (struct frame *f, struct face *face);
652
653 /* Optional.
654 If FONT (FONT-ENTITY or FONT-OBJECT) has a glyph for character C
655 (Unicode code point), return 1. If not, return 0. If FONT is
656 FONT-ENTITY and it must be opened to check it, return -1. */
657 int (*has_char) (Lisp_Object font, int c);
658
659 /* Return a glyph code of FONT for character C (Unicode code point).
660 If FONT doesn't have such a glyph, return FONT_INVALID_CODE. */
661 unsigned (*encode_char) (struct font *font, int c);
662
663 /* Compute the total metrics of the NGLYPHS glyphs specified by
664 the font FONT and the sequence of glyph codes CODE, and store the
665 result in METRICS. */
666 void (*text_extents) (struct font *font,
667 const unsigned *code, int nglyphs,
668 struct font_metrics *metrics);
669
670 #ifdef HAVE_WINDOW_SYSTEM
671
672 /* Optional.
673 Draw glyphs between FROM and TO of S->char2b at (X Y) pixel
674 position of frame S->f with S->face and S->gc. If WITH_BACKGROUND,
675 fill the background in advance. It is assured that WITH_BACKGROUND
676 is false when (FROM > 0 || TO < S->nchars). */
677 int (*draw) (struct glyph_string *s, int from, int to,
678 int x, int y, bool with_background);
679
680 /* Optional.
681 Store bitmap data for glyph-code CODE of FONT in BITMAP. It is
682 intended that this method is called from other font-driver
683 methods for actual drawing. */
684 int (*get_bitmap) (struct font *font, unsigned code,
685 struct font_bitmap *bitmap,
686 int bits_per_pixel);
687
688 /* Optional.
689 Free bitmap data in BITMAP. */
690 void (*free_bitmap) (struct font *font, struct font_bitmap *bitmap);
691
692 #endif /* HAVE_WINDOW_SYSTEM */
693
694 /* Optional.
695 Get coordinates of the INDEXth anchor point of the glyph whose
696 code is CODE. Store the coordinates in *X and *Y. Return 0 if
697 the operation was successful. Otherwise return -1. */
698 int (*anchor_point) (struct font *font, unsigned code, int index,
699 int *x, int *y);
700
701 /* Optional.
702 Return a list describing which scripts/languages FONT
703 supports by which GSUB/GPOS features of OpenType tables.
704 The list should be of the form (GSUB GPOS), where both
705 GSUB and GPOS are lists of the form
706 ((SCRIPT (LANGSYS FEATURE ...) ...) ...) */
707 Lisp_Object (*otf_capability) (struct font *font);
708
709 /* Optional.
710 Apply FONT's OTF-FEATURES to the glyph string.
711
712 FEATURES specifies which OTF features to apply in this format:
713 (SCRIPT LANGSYS GSUB-FEATURE GPOS-FEATURE)
714 See the documentation of `font-drive-otf' for the details.
715
716 This method applies the specified features to the codes in the
717 elements of GSTRING-IN (between FROMth and TOth). The output
718 codes are stored in GSTRING-OUT at the IDXth element and the
719 following elements.
720
721 Return the number of output codes. If none of the features are
722 applicable to the input data, return 0. If GSTRING-OUT is too
723 short, return -1.
724
725 Note: This method is currently not implemented by any font
726 back-end, and is only called by 'font-drive-otf' and
727 'font-otf-alternates', which are themselves ifdef'ed away. */
728 int (*otf_drive) (struct font *font, Lisp_Object features,
729 Lisp_Object gstring_in, int from, int to,
730 Lisp_Object gstring_out, int idx, bool alternate_subst);
731
732 /* Optional.
733 Make the font driver ready for frame F. Usually this function
734 makes some data specific to F and stores it in F's font_data
735 member by calling font_put_frame_data. */
736 int (*start_for_frame) (struct frame *f);
737
738 /* Optional.
739 End using the driver for frame F. Usually this function frees
740 some font data stored in frame F's font_data member. */
741 int (*end_for_frame) (struct frame *f);
742
743 /* Optional.
744 Shape text in GSTRING. See the docstring of
745 `composition-get-gstring' for the format of GSTRING. If the
746 (N+1)th element of GSTRING is nil, input of shaping is from the
747 1st to (N)th elements. In each input glyph, FROM, TO, CHAR, and
748 CODE are already set.
749 DIRECTION is either L2R or R2L, or nil if unknown. During
750 redisplay, this comes from applying the UBA, is passed from
751 composition_reseat_it, and is used by the HarfBuzz shaper.
752
753 This function updates all fields of the input glyphs. If the
754 output glyphs (M) are more than the input glyphs (N), (N+1)th
755 through (M)th elements of GSTRING are updated possibly by making
756 a new glyph object and storing it in GSTRING. If (M) is greater
757 than the length of GSTRING, this method should return nil. In
758 that case, the method is called again with a larger GSTRING. */
759 Lisp_Object (*shape) (Lisp_Object lgstring, Lisp_Object direction);
760
761 /* Optional.
762 If FONT is usable on frame F, return 0. Otherwise return -1.
763 This method is used only for debugging. If this method is NULL,
764 Emacs assumes that the font is usable on any frame. */
765 int (*check) (struct frame *f, struct font *font);
766
767 /* Optional.
768 Return the number of variation glyphs of character C supported by
769 FONT. VARIATIONS is an array of 256 elements. If the variation
770 selector N (1..256) defines a glyph, that glyph code is stored in
771 the (N-1)th element of VARIATIONS. */
772 int (*get_variation_glyphs) (struct font *font,
773 int c, unsigned variations[256]);
774
775 /* Optional.
776 Set attributes of FONT according to PROPERTIES.
777 PROPERTIES is an alist of pairs (KEY . VALUE) that specifies
778 font properties. This method should use font-put to set
779 properties of FONT supported by the font driver.
780 See font_filter_properties for more details. */
781 void (*filter_properties) (Lisp_Object font, Lisp_Object properties);
782
783 /* Optional.
784 Return non-zero if FONT_OBJECT can be used as a (cached) font
785 for ENTITY on frame F. */
786 bool (*cached_font_ok) (struct frame *f,
787 Lisp_Object font_object,
788 Lisp_Object entity);
789
790 /* Optional.
791 Return non-nil if the driver supports rendering of combining
792 characters for FONT according to Unicode combining class. */
793 Lisp_Object (*combining_capability) (struct font *font);
794
795 /* Optional.
796 Called when frame F is double-buffered and its size changes; Xft
797 relies on this hook to throw away its old XftDraw (which won't
798 work after the size change) and get a new one. */
799 void (*drop_xrender_surfaces) (struct frame *f);
800
801 #ifdef HAVE_HARFBUZZ
802 /* Optional.
803 Return a HarfBuzz font object for FONT and store to
804 *POSITION_UNIT the scale factor to convert a hb_position_t value
805 to the number of pixels. Return NULL if HarfBuzz font object is
806 not available for FONT. */
807 hb_font_t *(*begin_hb_font) (struct font *font, double *position_unit);
808
809 /* Optional.
810 Called when the return value (passed as HB_FONT) of begin_hb_font
811 above is no longer used. Not called if the return value of
812 begin_hb_font was NULL. */
813 void (*end_hb_font) (struct font *font, hb_font_t *hb_font);
814 #endif /* HAVE_HARFBUZZ */
815 };
816
817
818 /* Chain of font drivers. There's one global font driver list
819 (font_driver_list in font.c). In addition, each frame has
820 its own font driver list at F->font_driver_list. */
821
822 struct font_driver_list
823 {
824 /* True iff this driver is currently used. It is ignored in the global
825 font driver list.*/
826 bool on;
827 /* Pointer to the font driver. */
828 struct font_driver const *driver;
829 /* Pointer to the next element of the chain. */
830 struct font_driver_list *next;
831 };
832
833 extern Lisp_Object copy_font_spec (Lisp_Object);
834 extern Lisp_Object merge_font_spec (Lisp_Object, Lisp_Object);
835
836 extern Lisp_Object font_make_entity (void);
837 #ifdef HAVE_ANDROID
838 extern Lisp_Object font_make_entity_android (int);
839 #endif
840 extern Lisp_Object font_make_object (int, Lisp_Object, int);
841 #if defined (HAVE_XFT) || defined (HAVE_FREETYPE) || defined (HAVE_NS)
842 extern Lisp_Object font_build_object (int, Lisp_Object, Lisp_Object, double);
843 #endif
844
845 extern Lisp_Object find_font_encoding (Lisp_Object);
846 extern int font_registry_charsets (Lisp_Object, struct charset **,
847 struct charset **);
848 extern int font_style_to_value (enum font_property_index prop,
849 Lisp_Object name, bool noerror);
850 extern Lisp_Object font_style_symbolic (Lisp_Object font,
851 enum font_property_index prop,
852 bool for_face);
853
854 extern bool font_match_p (Lisp_Object spec, Lisp_Object font);
855 extern bool font_is_ignored (const char *name, ptrdiff_t namelen);
856 extern Lisp_Object font_list_entities (struct frame *, Lisp_Object);
857
858 extern Lisp_Object font_get_name (Lisp_Object font_object);
859 extern Lisp_Object font_spec_from_name (Lisp_Object font_name);
860 extern Lisp_Object font_get_frame (Lisp_Object font_object);
861 extern int font_has_char (struct frame *, Lisp_Object, int);
862
863 extern void font_clear_prop (Lisp_Object *attrs,
864 enum font_property_index prop);
865 extern Lisp_Object font_find_for_lface (struct frame *f, Lisp_Object *lface,
866 Lisp_Object spec, int c);
867 extern Lisp_Object font_open_for_lface (struct frame *f, Lisp_Object entity,
868 Lisp_Object *lface,
869 Lisp_Object spec);
870 extern Lisp_Object font_load_for_lface (struct frame *f, Lisp_Object *lface,
871 Lisp_Object spec);
872 extern void font_prepare_for_face (struct frame *f, struct face *face);
873 extern void font_done_for_face (struct frame *f, struct face *face);
874 extern void clear_font_cache (struct frame *);
875
876 extern Lisp_Object font_open_by_spec (struct frame *f, Lisp_Object spec);
877 extern Lisp_Object font_open_by_name (struct frame *f, Lisp_Object name);
878
879 extern Lisp_Object font_intern_prop (const char *str, ptrdiff_t len,
880 bool force_symbol);
881 extern void font_update_sort_order (int *order);
882
883 extern void font_parse_family_registry (Lisp_Object family,
884 Lisp_Object registry,
885 Lisp_Object spec);
886
887 extern int font_parse_xlfd (char *name, ptrdiff_t len, Lisp_Object font);
888 extern ptrdiff_t font_unparse_xlfd (Lisp_Object font, int pixel_size,
889 char *name, int bytes);
890 extern void register_font_driver (struct font_driver const *, struct frame *);
891 extern void free_font_driver_list (struct frame *f);
892 #ifdef ENABLE_CHECKING
893 extern bool valid_font_driver (struct font_driver const *);
894 #else
895 INLINE bool
896 valid_font_driver (struct font_driver const *d)
897 {
898 return true;
899 }
900 #endif
901 extern Lisp_Object font_update_drivers (struct frame *f, Lisp_Object list);
902 extern Lisp_Object font_range (ptrdiff_t, ptrdiff_t, ptrdiff_t *,
903 struct window *, struct face *,
904 Lisp_Object, int);
905 extern void font_fill_lglyph_metrics (Lisp_Object, struct font *, unsigned int);
906
907 extern Lisp_Object font_put_extra (Lisp_Object font, Lisp_Object prop,
908 Lisp_Object val);
909
910 #ifdef HAVE_HARFBUZZ
911 extern Lisp_Object hbfont_otf_capability (struct font *);
912 extern Lisp_Object hbfont_shape (Lisp_Object, Lisp_Object);
913 extern Lisp_Object hbfont_combining_capability (struct font *);
914 #endif
915
916 #if defined (HAVE_XFT) || defined (HAVE_FREETYPE)
917 extern void font_put_frame_data (struct frame *, Lisp_Object, void *);
918 extern void *font_get_frame_data (struct frame *f, Lisp_Object);
919 #endif /* HAVE_XFT || HAVE_FREETYPE */
920
921 extern void font_filter_properties (Lisp_Object font,
922 Lisp_Object alist,
923 const char *const boolean_properties[],
924 const char *const non_boolean_properties[]);
925
926 extern void font_drop_xrender_surfaces (struct frame *f);
927
928 #ifdef HAVE_FREETYPE
929 extern int ftfont_anchor_point (struct font *, unsigned int, int,
930 int *, int *);
931 extern int ftfont_get_bitmap (struct font *, unsigned int,
932 struct font_bitmap *, int);
933 extern int ftfont_has_char (Lisp_Object, int);
934 extern int ftfont_variation_glyphs (struct font *, int, unsigned[256]);
935 extern Lisp_Object ftfont_combining_capability (struct font *);
936 extern Lisp_Object ftfont_get_cache (struct frame *);
937 extern Lisp_Object ftfont_list2 (struct frame *, Lisp_Object, Lisp_Object);
938 extern Lisp_Object ftfont_list_family (struct frame *);
939 extern Lisp_Object ftfont_match2 (struct frame *, Lisp_Object, Lisp_Object);
940 extern Lisp_Object ftfont_open (struct frame *, Lisp_Object, int);
941 extern Lisp_Object ftfont_otf_capability (struct font *);
942 extern Lisp_Object ftfont_shape (Lisp_Object, Lisp_Object);
943 extern unsigned ftfont_encode_char (struct font *, int);
944 extern void ftfont_close (struct font *);
945 extern void ftfont_filter_properties (Lisp_Object, Lisp_Object);
946 extern void ftfont_text_extents (struct font *, const unsigned *, int,
947 struct font_metrics *);
948 #ifdef HAVE_HARFBUZZ
949 extern hb_font_t *fthbfont_begin_hb_font (struct font *, double *);
950 #endif /* HAVE_HARFBUZZ */
951 extern void syms_of_ftfont (void);
952 #endif /* HAVE_FREETYPE */
953 #ifdef HAVE_X_WINDOWS
954 extern struct font_driver const xfont_driver;
955 extern Lisp_Object xfont_get_cache (struct frame *);
956 extern void syms_of_xfont (void);
957 #ifdef HAVE_XFT
958 extern struct font_driver const xftfont_driver;
959 #ifdef HAVE_HARFBUZZ
960 extern struct font_driver xfthbfont_driver;
961 #endif /* HAVE_HARFBUZZ */
962 #endif
963 #if defined HAVE_FREETYPE || defined HAVE_XFT
964 extern void syms_of_xftfont (void);
965 #endif
966 #ifdef HAVE_BDFFONT
967 extern void syms_of_bdffont (void);
968 #endif /* HAVE_BDFFONT */
969 #endif /* HAVE_X_WINDOWS */
970 #ifdef HAVE_NTGUI
971 extern struct font_driver w32font_driver;
972 extern struct font_driver uniscribe_font_driver;
973 #ifdef HAVE_HARFBUZZ
974 extern struct font_driver harfbuzz_font_driver;
975 #endif
976 extern void syms_of_w32font (void);
977 #endif /* HAVE_NTGUI */
978 #ifdef HAVE_NS
979 extern struct font_driver const nsfont_driver;
980 extern void syms_of_nsfont (void);
981 extern void syms_of_macfont (void);
982 #endif /* HAVE_NS */
983 #if defined (USE_CAIRO) || defined (USE_BE_CAIRO)
984 extern struct font_driver const ftcrfont_driver;
985 #ifdef HAVE_HARFBUZZ
986 extern struct font_driver ftcrhbfont_driver;
987 #endif /* HAVE_HARFBUZZ */
988 extern void syms_of_ftcrfont (void);
989 #endif
990
991 #ifndef FONT_DEBUG
992 #define FONT_DEBUG
993 #endif
994
995 extern void font_add_log (const char *, Lisp_Object, Lisp_Object);
996 extern void font_deferred_log (const char *, Lisp_Object, Lisp_Object);
997
998 #define FONT_ADD_LOG(ACTION, ARG, RESULT) \
999 do { \
1000 if (! EQ (Vfont_log, Qt)) \
1001 font_add_log ((ACTION), (ARG), (RESULT)); \
1002 } while (false)
1003
1004 #define FONT_DEFERRED_LOG(ACTION, ARG, RESULT) \
1005 do { \
1006 if (! EQ (Vfont_log, Qt)) \
1007 font_deferred_log ((ACTION), (ARG), (RESULT)); \
1008 } while (false)
1009
1010 /* FIXME: This is for use in functions that can be called while
1011 garbage-collecting, but which assume that Lisp data structures are
1012 properly-formed. This invalid assumption can lead to core dumps
1013 (Bug#20890). */
1014 INLINE bool
1015 font_data_structures_may_be_ill_formed (void)
1016 {
1017 #if defined USE_CAIRO || defined USE_BE_CAIRO
1018 /* Although this works around Bug#20890, it is probably not the
1019 right thing to do. */
1020 return gc_in_progress;
1021 #else
1022 return false;
1023 #endif
1024 }
1025
1026 INLINE_HEADER_END
1027
1028 #endif /* not EMACS_FONT_H */