src/font.h

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