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 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 extern Lisp_Object Qfont_spec, Qfont_entity, Qfont_object;
  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     /* Font-entity from which the font-object is opened.  */
 166     FONT_ENTITY_INDEX = FONT_SPEC_MAX,
 167
 168     /* This value is the length of font-entity vector.  */
 169     FONT_ENTITY_MAX,
 170
 171     /* The followings are used only for a font-object.  */
 172
 173     /* XLFD name of the font (string). */
 174     FONT_NAME_INDEX = FONT_ENTITY_MAX,
 175
 176     /* Full name of the font (string).  It is the name extracted from
 177        the opened font, and may be different from the above.  It may be
 178        nil if the opened font doesn't give a name.  */
 179     FONT_FULLNAME_INDEX,
 180
 181     /* File name of the font or nil if a file associated with the font
 182        is not available.  */
 183     FONT_FILE_INDEX,
 184
 185     /* Format of the font (symbol) or nil if unknown.  */
 186     FONT_FORMAT_INDEX,
 187
 188     /* This value is the length of font-object vector.  */
 189     FONT_OBJECT_MAX
 190   };
 191
 192 /* Return the numeric weight value of FONT.  */
 193 #define FONT_WEIGHT_NUMERIC(font)               \
 194   (INTEGERP (AREF ((font), FONT_WEIGHT_INDEX))  \
 195    ? (XINT (AREF ((font), FONT_WEIGHT_INDEX)) >> 8) : -1)
 196 /* Return the numeric slant value of FONT.  */
 197 #define FONT_SLANT_NUMERIC(font)                \
 198   (INTEGERP (AREF ((font), FONT_SLANT_INDEX))   \
 199    ? (XINT (AREF ((font), FONT_SLANT_INDEX)) >> 8) : -1)
 200 /* Return the numeric width value of FONT.  */
 201 #define FONT_WIDTH_NUMERIC(font)                \
 202   (INTEGERP (AREF ((font), FONT_WIDTH_INDEX))   \
 203    ? (XINT (AREF ((font), FONT_WIDTH_INDEX)) >> 8) : -1)
 204 /* Return the symbolic weight value of FONT.  */
 205 #define FONT_WEIGHT_SYMBOLIC(font)      \
 206   font_style_symbolic (font, FONT_WEIGHT_INDEX, false)
 207 /* Return the symbolic slant value of FONT.  */
 208 #define FONT_SLANT_SYMBOLIC(font)       \
 209   font_style_symbolic (font, FONT_SLANT_INDEX, false)
 210 /* Return the symbolic width value of FONT.  */
 211 #define FONT_WIDTH_SYMBOLIC(font)       \
 212   font_style_symbolic (font, FONT_WIDTH_INDEX, false)
 213 /* Return the face-weight corresponding to the weight of FONT.  */
 214 #define FONT_WEIGHT_FOR_FACE(font)      \
 215   font_style_symbolic (font, FONT_WEIGHT_INDEX, true)
 216 /* Return the face-slant corresponding to the slant of FONT.  */
 217 #define FONT_SLANT_FOR_FACE(font)       \
 218   font_style_symbolic (font, FONT_SLANT_INDEX, true)
 219 /* Return the face-swidth corresponding to the slant of FONT.  */
 220 #define FONT_WIDTH_FOR_FACE(font)       \
 221   font_style_symbolic (font, FONT_WIDTH_INDEX, true)
 222
 223 /* Return the numeric weight value corresponding ot the symbol NAME.  */
 224 #define FONT_WEIGHT_NAME_NUMERIC(name)  \
 225   (font_style_to_value (FONT_WEIGHT_INDEX, (name), false) >> 8)
 226 /* Return the numeric slant value corresponding ot the symbol NAME.  */
 227 #define FONT_SLANT_NAME_NUMERIC(name)   \
 228   (font_style_to_value (FONT_SLANT_INDEX, (name), false) >> 8)
 229 /* Return the numeric width value corresponding ot the symbol NAME.  */
 230 #define FONT_WIDTH_NAME_NUMERIC(name)   \
 231   (font_style_to_value (FONT_WIDTH_INDEX, (name), false) >> 8)
 232
 233 /* Set the font property PROP of FONT to VAL.  PROP is one of
 234    style-related font property index (FONT_WEIGHT/SLANT/WIDTH_INDEX).
 235    VAL (integer or symbol) is the numeric or symbolic style value.  */
 236 #define FONT_SET_STYLE(font, prop, val) \
 237   ASET ((font), prop, make_number (font_style_to_value (prop, val, true)))
 238
 239 #define FONT_WIDTH(f) ((f)->max_width)
 240 #define FONT_HEIGHT(f) ((f)->height)
 241 #define FONT_BASE(f) ((f)->ascent)
 242 #define FONT_DESCENT(f) ((f)->descent)
 243
 244 extern Lisp_Object QCspacing, QCdpi, QCscalable, QCotf, QClang, QCscript;
 245 extern Lisp_Object QCavgwidth, QCantialias, QCfont_entity;
 246 extern Lisp_Object Qp;
 247
 248
 249 /* Important character set symbols.  */
 250 extern Lisp_Object Qascii_0;
 251 extern Lisp_Object Qiso8859_1, Qiso10646_1, Qunicode_bmp, Qunicode_sip;
 252
 253 /* Special ADSTYLE properties to avoid fonts used for Latin characters.  */
 254 extern Lisp_Object Qja, Qko;
 255
 256 /* Structure for a font-spec.  */
 257
 258 struct font_spec
 259 {
 260   struct vectorlike_header header;
 261   Lisp_Object props[FONT_SPEC_MAX];
 262 };
 263
 264 /* Structure for a font-entity.  */
 265
 266 struct font_entity
 267 {
 268   struct vectorlike_header header;
 269   Lisp_Object props[FONT_ENTITY_MAX];
 270 };
 271
 272 /* A value which may appear in the member `encoding' of struct font
 273    indicating that a font itself doesn't tell which encoding to be
 274    used.  */
 275 #define FONT_ENCODING_NOT_DECIDED 255
 276
 277 /* Structure for a font-object.  */
 278
 279 struct font
 280 {
 281   struct vectorlike_header header;
 282
 283   /* All Lisp_Object components must come first.
 284      That ensures they are all aligned normally.  */
 285
 286   Lisp_Object props[FONT_OBJECT_MAX];
 287
 288   /* Beyond here, there should be no more Lisp_Object components.  */
 289
 290   /* Minimum and maximum glyph widths, in pixels.  Some font backends,
 291      such as xft, lack the information to easily compute minimum and
 292      maximum widths over all characters; in that case, these values
 293      are approximate.  */
 294   int min_width;
 295   int max_width;
 296
 297   /* By which pixel size the font is opened.  */
 298   int pixel_size;
 299
 300   /* Height of the font.  On X window, this is the same as
 301      (font->ascent + font->descent).  */
 302   int height;
 303
 304   /* Width of the space glyph of the font.  If the font doesn't have a
 305      SPACE glyph, the value is 0.  */
 306   int space_width;
 307
 308   /* Average width of glyphs in the font.  If the font itself doesn't
 309      have that information but has glyphs of ASCII characters, the
 310      value is the average width of those glyphs.  Otherwise, the value
 311      is 0.  */
 312   int average_width;
 313
 314   /* Ascent and descent of the font (in pixels).  */
 315   int ascent, descent;
 316
 317   /* The following members makes sense on graphic displays only.  */
 318
 319 #if defined (HAVE_WINDOW_SYSTEM)
 320
 321   /* Vertical pixel width of the underline.  If is zero if that
 322      information is not in the font.  */
 323   int underline_thickness;
 324
 325   /* Vertical pixel position (relative to the baseline) of the
 326      underline.  If it is positive, it is below the baseline.  It is
 327      negative if that information is not in the font.  */
 328   int underline_position;
 329
 330   /* True if `vertical-centering-font-regexp' matches this font name.
 331      In this case, we render characters at vertical center positions
 332      of lines.  */
 333   bool vertical_centering;
 334
 335   /* The baseline position of a font is normally `ascent' value of the
 336      font.  However, there exist many fonts which don't set `ascent' to
 337      an appropriate value to be used as baseline position.  This is
 338      typical in such ASCII fonts which are designed to be used with
 339      Chinese, Japanese, Korean characters.  When we use mixture of
 340      such fonts and normal fonts (having correct `ascent' value), a
 341      display line gets very ugly.  Since we have no way to fix it
 342      automatically, it is user's responsibility to supply well designed
 343      fonts or correct `ascent' value of fonts.  But, the latter
 344      requires heavy work (modifying all bitmap data in BDF files).
 345      So, Emacs accepts a private font property
 346      `_MULE_BASELINE_OFFSET'.  If a font has this property, we
 347      calculate the baseline position by subtracting the value from
 348      `ascent'.  In other words, the value indicates how many pixels
 349      higher than normal ASCII text we should draw a character of the
 350      font for better appearance.
 351
 352      We also have to consider the fact that the concept of `baseline'
 353      differs among scripts to which each character belongs.  For
 354      instance, baseline should be at the bottom-most position of all
 355      glyphs for Chinese, Japanese, and Korean.  But, many of existing
 356      fonts for those characters don't have correct `ascent' values
 357      because they are designed to be used with ASCII fonts.  To
 358      display characters of different language on the same line, the
 359      best way will be to arrange them in the middle of the line.  So,
 360      in such a case, again, we utilize the font property
 361      `_MULE_BASELINE_OFFSET'.  If the value is larger than `ascent' we
 362      calculate baseline so that a character is arranged in the middle
 363      of a line.  */
 364   int baseline_offset;
 365
 366   /* Non-zero means a character should be composed at a position
 367      relative to the height (or depth) of previous glyphs in the
 368      following cases:
 369         (1) The bottom of the character is higher than this value.  In
 370         this case, the character is drawn above the previous glyphs.
 371         (2) The top of the character is lower than 0 (i.e. baseline
 372         height).  In this case, the character is drawn below the
 373         previous glyphs.
 374
 375      This value is taken from a private font property
 376      `_MULE_RELATIVE_COMPOSE' which is introduced by Emacs.  */
 377   int relative_compose;
 378
 379   /* Non-zero means an ascent value to be used for a character
 380      registered in char-table `use-default-ascent'.  */
 381   int default_ascent;
 382
 383   /* Charset to encode a character code into a glyph code of the font.
 384      -1 means that the font doesn't require this information to encode
 385      a character.  */
 386   int encoding_charset;
 387
 388   /* Charset to check if a character code is supported by the font.
 389      -1 means that the contents of the font must be looked up to
 390      determine it.  */
 391   int repertory_charset;
 392
 393 #endif /* HAVE_WINDOW_SYSTEM */
 394
 395   /* Font-driver for the font.  */
 396   struct font_driver *driver;
 397
 398   /* There are more members in this structure, but they are private
 399      to the font-driver.  */
 400 };
 401
 402 enum font_spacing
 403   {
 404     FONT_SPACING_PROPORTIONAL = 0,
 405     FONT_SPACING_DUAL = 90,
 406     FONT_SPACING_MONO = 100,
 407     FONT_SPACING_CHARCELL = 110
 408   };
 409
 410 struct font_metrics
 411 {
 412   short lbearing, rbearing, width, ascent, descent;
 413 };
 414
 415 struct font_bitmap
 416 {
 417   int bits_per_pixel;
 418   int rows;
 419   int width;
 420   int pitch;
 421   unsigned char *buffer;
 422   int left;
 423   int top;
 424   int advance;
 425 };
 426
 427 /* Predicates to check various font-related objects.  */
 428
 429 /* True iff X is one of font-spec, font-entity, and font-object.  */
 430 #define FONTP(x) PSEUDOVECTORP (x, PVEC_FONT)
 431 /* True iff X is font-spec.  */
 432 #define FONT_SPEC_P(x)  \
 433   (FONTP (x) && (ASIZE (x) & PSEUDOVECTOR_SIZE_MASK) == FONT_SPEC_MAX)
 434 /* True iff X is font-entity.  */
 435 #define FONT_ENTITY_P(x)        \
 436   (FONTP (x) && (ASIZE (x) & PSEUDOVECTOR_SIZE_MASK) == FONT_ENTITY_MAX)
 437 /* True iff X is font-object.  */
 438 #define FONT_OBJECT_P(x)        \
 439   (FONTP (x) && (ASIZE (x) & PSEUDOVECTOR_SIZE_MASK) == FONT_OBJECT_MAX)
 440
 441 /* True iff ENTITY can't be loaded.  */
 442 #define FONT_ENTITY_NOT_LOADABLE(entity)        \
 443   EQ (AREF (entity, FONT_OBJLIST_INDEX), Qt)
 444
 445 /* Flag ENTITY not loadable.  */
 446 #define FONT_ENTITY_SET_NOT_LOADABLE(entity)    \
 447   ASET (entity, FONT_OBJLIST_INDEX, Qt)
 448
 449
 450 /* Check macros for various font-related objects.  */
 451
 452 #define CHECK_FONT(x)   \
 453   do { if (! FONTP (x)) wrong_type_argument (Qfont, x); } while (false)
 454 #define CHECK_FONT_SPEC(x)      \
 455   do { if (! FONT_SPEC_P (x)) wrong_type_argument (Qfont_spec, x); } \
 456   while (false)
 457 #define CHECK_FONT_ENTITY(x)    \
 458   do { if (! FONT_ENTITY_P (x)) wrong_type_argument (Qfont_entity, x); } \
 459   while (false)
 460 #define CHECK_FONT_OBJECT(x)    \
 461   do { if (! FONT_OBJECT_P (x)) wrong_type_argument (Qfont_object, x); } \
 462   while (false)
 463
 464 #define CHECK_FONT_GET_OBJECT(x, font)  \
 465   do {                                  \
 466     CHECK_FONT_OBJECT (x);              \
 467     font = XFONT_OBJECT (x);            \
 468   } while (false)
 469
 470 #define XFONT_SPEC(p)   \
 471   (eassert (FONT_SPEC_P (p)), (struct font_spec *) XUNTAG (p, Lisp_Vectorlike))
 472 #define XFONT_ENTITY(p) \
 473   (eassert (FONT_ENTITY_P (p)), \
 474    (struct font_entity *) XUNTAG (p, Lisp_Vectorlike))
 475 #define XFONT_OBJECT(p) \
 476   (eassert (FONT_OBJECT_P (p)), (struct font *) XUNTAG (p, Lisp_Vectorlike))
 477 #define XSETFONT(a, b) (XSETPSEUDOVECTOR (a, b, PVEC_FONT))
 478
 479 /* Number of pt per inch (from the TeXbook).  */
 480 #define PT_PER_INCH 72.27
 481
 482 /* Return a pixel size (integer) corresponding to POINT size (double)
 483    on resolution DPI.  */
 484 #define POINT_TO_PIXEL(POINT, DPI) ((POINT) * (DPI) / PT_PER_INCH + 0.5)
 485
 486 /* Return a point size corresponding to POINT size (integer)
 487    on resolution DPI.  Note that though point size is a double, we expect
 488    it to be rounded to an int, so we add 0.5 here.  If the desired value
 489    is tenths of points (as in xfld specs), then the pixel size should
 490    be multiplied BEFORE the conversion to avoid magnifying the error.  */
 491 #define PIXEL_TO_POINT(PIXEL, DPI) ((PIXEL) * PT_PER_INCH / (DPI) + 0.5)
 492
 493 /* Ignore the difference of font pixel sizes less than or equal to
 494    this value.  */
 495 #define FONT_PIXEL_SIZE_QUANTUM 1
 496
 497 #define FONT_INVALID_CODE 0xFFFFFFFF
 498
 499 /* Font driver.  Members specified as "optional" can be NULL.  */
 500
 501 struct font_driver
 502 {
 503   /* Symbol indicating the type of the font-driver.  */
 504   Lisp_Object type;
 505
 506   /* True iff the font's foundry, family, and adstyle names are case
 507      sensitive.  */
 508   bool case_sensitive;
 509
 510   /* Return a cache of font-entities on frame F.  The cache must be a
 511      cons whose cdr part is the actual cache area.  */
 512   Lisp_Object (*get_cache) (struct frame *f);
 513
 514   /* List fonts exactly matching with FONT_SPEC on FRAME.  The value
 515      is a list of font-entities.  The font properties to be considered
 516      are: :foundry, :family, :adstyle, :registry, :script, :lang, and
 517      :otf.  See the function `font-spec' for their meanings.  Note
 518      that the last three properties are stored in FONT_EXTRA_INDEX
 519      slot of FONT_SPEC.
 520
 521      The returned value is a list of font-entities.  Each font-entity
 522      has :type property whose value is the same as the above `type'.
 523      It also has these properties if they are available from the
 524      corresponding font; :foundry, :family, :adstyle, :registry,
 525      :weight, :slant, :width, :size, :dpi, :spacing, :avgwidth.  If
 526      the font is scalable, :size and :avgwidth must be 0.
 527
 528      The `open' method of the same font-backend is called with one of
 529      the returned font-entities.  If the backend needs additional
 530      information to be used in `open' method, this method can add any
 531      Lispy value by the property :font-entity to the entities.
 532
 533      This and the following `match' are the only APIs that allocate
 534      font-entities.  */
 535   Lisp_Object (*list) (struct frame *frame, Lisp_Object font_spec);
 536
 537   /* Return a font-entity most closely matching with FONT_SPEC on
 538      FRAME.  Which font property to consider, and how to calculate the
 539      closeness is determined by the font backend, thus
 540      `face-font-selection-order' is ignored here.
 541
 542      The properties that the font-entity has is the same as `list'
 543      method.  */
 544   Lisp_Object (*match) (struct frame *f, Lisp_Object spec);
 545
 546   /* Optional.
 547      List available families.  The value is a list of family names
 548      (symbols).  */
 549   Lisp_Object (*list_family) (struct frame *f);
 550
 551   /* Optional (if FONT_EXTRA_INDEX is not Lisp_Save_Value).
 552      Free FONT_EXTRA_INDEX field of FONT_ENTITY.  */
 553   void (*free_entity) (Lisp_Object font_entity);
 554
 555   /* Open a font specified by FONT_ENTITY on frame F.  If the font is
 556      scalable, open it with PIXEL_SIZE.  */
 557   Lisp_Object (*open) (struct frame *f, Lisp_Object font_entity,
 558                        int pixel_size);
 559
 560   /* Close FONT.  NOTE: this can be called by GC.  */
 561   void (*close) (struct font *font);
 562
 563   /* Optional (if FACE->extra is not used).
 564      Prepare FACE for displaying characters by FONT on frame F by
 565      storing some data in FACE->extra.  If successful, return 0.
 566      Otherwise, return -1.  */
 567   int (*prepare_face) (struct frame *f, struct face *face);
 568
 569   /* Optional.
 570      Done FACE for displaying characters by FACE->font on frame F.  */
 571   void (*done_face) (struct frame *f, struct face *face);
 572
 573   /* Optional.
 574      If FONT (FONT-ENTITY or FONT-OBJECT) has a glyph for character C
 575      (Unicode code point), return 1.  If not, return 0.  If FONT is
 576      FONT-ENTITY and it must be opened to check it, return -1.  */
 577   int (*has_char) (Lisp_Object font, int c);
 578
 579   /* Return a glyph code of FONT for character C (Unicode code point).
 580      If FONT doesn't have such a glyph, return FONT_INVALID_CODE.  */
 581   unsigned (*encode_char) (struct font *font, int c);
 582
 583   /* Compute the total metrics of the NGLYPHS glyphs specified by
 584      the font FONT and the sequence of glyph codes CODE, and store the
 585      result in METRICS.  */
 586   int (*text_extents) (struct font *font,
 587                        unsigned *code, int nglyphs,
 588                        struct font_metrics *metrics);
 589
 590 #ifdef HAVE_WINDOW_SYSTEM
 591
 592   /* Optional.
 593      Draw glyphs between FROM and TO of S->char2b at (X Y) pixel
 594      position of frame F with S->FACE and S->GC.  If WITH_BACKGROUND,
 595      fill the background in advance.  It is assured that WITH_BACKGROUND
 596      is false when (FROM > 0 || TO < S->nchars).  */
 597   int (*draw) (struct glyph_string *s, int from, int to,
 598                int x, int y, bool with_background);
 599
 600   /* Optional.
 601      Store bitmap data for glyph-code CODE of FONT in BITMAP.  It is
 602      intended that this method is called from the other font-driver
 603      for actual drawing.  */
 604   int (*get_bitmap) (struct font *font, unsigned code,
 605                      struct font_bitmap *bitmap,
 606                      int bits_per_pixel);
 607
 608   /* Optional.
 609      Free bitmap data in BITMAP.  */
 610   void (*free_bitmap) (struct font *font, struct font_bitmap *bitmap);
 611
 612 #endif /* HAVE_WINDOW_SYSTEM */
 613
 614   /* Optional.
 615      Return an outline data for glyph-code CODE of FONT.  The format
 616      of the outline data depends on the font-driver.  */
 617   void *(*get_outline) (struct font *font, unsigned code);
 618
 619   /* Optional.
 620      Free OUTLINE (that is obtained by the above method).  */
 621   void (*free_outline) (struct font *font, void *outline);
 622
 623   /* Optional.
 624      Get coordinates of the INDEXth anchor point of the glyph whose
 625      code is CODE.  Store the coordinates in *X and *Y.  Return 0 if
 626      the operations was successful.  Otherwise return -1.  */
 627   int (*anchor_point) (struct font *font, unsigned code, int index,
 628                        int *x, int *y);
 629
 630   /* Optional.
 631      Return a list describing which scripts/languages FONT
 632      supports by which GSUB/GPOS features of OpenType tables.  */
 633   Lisp_Object (*otf_capability) (struct font *font);
 634
 635   /* Optional.
 636      Apply FONT's OTF-FEATURES to the glyph string.
 637
 638      FEATURES specifies which OTF features to apply in this format:
 639         (SCRIPT LANGSYS GSUB-FEATURE GPOS-FEATURE)
 640      See the documentation of `font-drive-otf' for the details.
 641
 642      This method applies the specified features to the codes in the
 643      elements of GSTRING-IN (between FROMth and TOth).  The output
 644      codes are stored in GSTRING-OUT at the IDXth element and the
 645      following elements.
 646
 647      Return the number of output codes.  If none of the features are
 648      applicable to the input data, return 0.  If GSTRING-OUT is too
 649      short, return -1.  */
 650   int (*otf_drive) (struct font *font, Lisp_Object features,
 651                     Lisp_Object gstring_in, int from, int to,
 652                     Lisp_Object gstring_out, int idx, bool alternate_subst);
 653
 654   /* Optional.
 655      Make the font driver ready for frame F.  Usually this function
 656      makes some data specific to F and stores it in F by calling
 657      font_put_frame_data ().  */
 658   int (*start_for_frame) (struct frame *f);
 659
 660   /* Optional.
 661      End using the driver for frame F.  Usually this function free
 662      some data stored for F.  */
 663   int (*end_for_frame) (struct frame *f);
 664
 665   /* Optional.
 666
 667      Shape text in GSTRING.  See the docstring of
 668      `composition-get-gstring' for the format of GSTRING.  If the
 669      (N+1)th element of GSTRING is nil, input of shaping is from the
 670      1st to (N)th elements.  In each input glyph, FROM, TO, CHAR, and
 671      CODE are already set.
 672
 673      This function updates all fields of the input glyphs.  If the
 674      output glyphs (M) are more than the input glyphs (N), (N+1)th
 675      through (M)th elements of GSTRING are updated possibly by making
 676      a new glyph object and storing it in GSTRING.  If (M) is greater
 677      than the length of GSTRING, nil should be return.  In that case,
 678      this function is called again with the larger GSTRING.  */
 679   Lisp_Object (*shape) (Lisp_Object lgstring);
 680
 681   /* Optional.
 682
 683      If FONT is usable on frame F, return 0.  Otherwise return -1.
 684      This method is used only for debugging.  If this method is NULL,
 685      Emacs assumes that the font is usable on any frame.  */
 686   int (*check) (struct frame *f, struct font *font);
 687
 688   /* Optional.
 689
 690      Return the number of variation glyphs of character C supported by
 691      FONT.  VARIATIONS is an array of 256 elements.  If the variation
 692      selector N (1..256) defines a glyph, that glyph code is stored in
 693      the (N-1)th element of VARIATIONS.  */
 694   int (*get_variation_glyphs) (struct font *font,
 695                                int c, unsigned variations[256]);
 696
 697   void (*filter_properties) (Lisp_Object font, Lisp_Object properties);
 698
 699   /* Optional.
 700
 701      Return non-zero if FONT_OBJECT can be used as a (cached) font
 702      for ENTITY on frame F.  */
 703   bool (*cached_font_ok) (struct frame *f,
 704                           Lisp_Object font_object,
 705                           Lisp_Object entity);
 706 };
 707
 708
 709 /* Chain of font drivers.  There's one global font driver list
 710    (font_driver_list in font.c).  In addition, each frame has
 711    its own font driver list at F->font_driver_list.  */
 712
 713 struct font_driver_list
 714 {
 715   /* True iff this driver is currently used.  It is ignored in the global
 716      font driver list.*/
 717   bool on;
 718   /* Pointer to the font driver.  */
 719   struct font_driver *driver;
 720   /* Pointer to the next element of the chain.  */
 721   struct font_driver_list *next;
 722 };
 723
 724
 725 /* Chain of arbitrary data specific to each font driver.
 726    Each frame has its own font data list at F->font_data_list.  */
 727
 728 struct font_data_list
 729 {
 730   /* Pointer to the font driver.  */
 731   struct font_driver *driver;
 732   /* Data specific to the font driver.  */
 733   void *data;
 734   /* Pointer to the next element of the chain.  */
 735   struct font_data_list *next;
 736 };
 737
 738 extern Lisp_Object copy_font_spec (Lisp_Object);
 739 extern Lisp_Object merge_font_spec (Lisp_Object, Lisp_Object);
 740
 741 extern Lisp_Object font_make_entity (void);
 742 extern Lisp_Object font_make_object (int, Lisp_Object, int);
 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 int font_unparse_fcname (Lisp_Object font, int pixel_size,
 789                                 char *name, int bytes);
 790 extern void register_font_driver (struct font_driver *driver, struct frame *f);
 791 extern void free_font_driver_list (struct frame *f);
 792 #ifdef ENABLE_CHECKING
 793 extern bool valid_font_driver (struct font_driver *);
 794 #else
 795 INLINE bool
 796 valid_font_driver (struct font_driver *d)
 797 {
 798   return true;
 799 }
 800 #endif
 801 extern Lisp_Object font_update_drivers (struct frame *f, Lisp_Object list);
 802 extern Lisp_Object font_range (ptrdiff_t, ptrdiff_t, ptrdiff_t *,
 803                                struct window *, struct face *,
 804                                Lisp_Object);
 805 extern void font_fill_lglyph_metrics (Lisp_Object, Lisp_Object);
 806
 807 extern Lisp_Object font_put_extra (Lisp_Object font, Lisp_Object prop,
 808                                    Lisp_Object val);
 809
 810 extern int font_put_frame_data (struct frame *f,
 811                                 struct font_driver *driver,
 812                                 void *data);
 813 extern void *font_get_frame_data (struct frame *f,
 814                                   struct font_driver *driver);
 815
 816 extern void font_filter_properties (Lisp_Object font,
 817                                     Lisp_Object alist,
 818                                     const char *const boolean_properties[],
 819                                     const char *const non_boolean_properties[]);
 820
 821 #ifdef HAVE_FREETYPE
 822 extern struct font_driver ftfont_driver;
 823 extern void syms_of_ftfont (void);
 824 #endif  /* HAVE_FREETYPE */
 825 #ifdef HAVE_X_WINDOWS
 826 extern struct font_driver xfont_driver;
 827 extern void syms_of_xfont (void);
 828 extern void syms_of_ftxfont (void);
 829 #ifdef HAVE_XFT
 830 extern Lisp_Object Qxft;
 831 extern struct font_driver xftfont_driver;
 832 extern void syms_of_xftfont (void);
 833 #elif defined HAVE_FREETYPE
 834 extern struct font_driver ftxfont_driver;
 835 #endif
 836 #ifdef HAVE_BDFFONT
 837 extern void syms_of_bdffont (void);
 838 #endif  /* HAVE_BDFFONT */
 839 #endif  /* HAVE_X_WINDOWS */
 840 #ifdef HAVE_NTGUI
 841 extern struct font_driver w32font_driver;
 842 extern struct font_driver uniscribe_font_driver;
 843 extern void syms_of_w32font (void);
 844 #endif  /* HAVE_NTGUI */
 845 #ifdef HAVE_NS
 846 extern Lisp_Object Qfontsize;
 847 extern struct font_driver nsfont_driver;
 848 extern void syms_of_nsfont (void);
 849 extern void syms_of_macfont (void);
 850 #endif  /* HAVE_NS */
 851
 852 #ifndef FONT_DEBUG
 853 #define FONT_DEBUG
 854 #endif
 855
 856 extern Lisp_Object QCfoundry;
 857
 858 extern void font_add_log (const char *, Lisp_Object, Lisp_Object);
 859 extern void font_deferred_log (const char *, Lisp_Object, Lisp_Object);
 860
 861 #define FONT_ADD_LOG(ACTION, ARG, RESULT)       \
 862   do {                                          \
 863     if (! EQ (Vfont_log, Qt))                   \
 864       font_add_log ((ACTION), (ARG), (RESULT)); \
 865   } while (false)
 866
 867 #define FONT_DEFERRED_LOG(ACTION, ARG, RESULT)          \
 868   do {                                                  \
 869     if (! EQ (Vfont_log, Qt))                           \
 870       font_deferred_log ((ACTION), (ARG), (RESULT));    \
 871   } while (false)
 872
 873 INLINE_HEADER_END
 874
 875 #endif  /* not EMACS_FONT_H */