src/font.h

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