src/font.h

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