src/font.h

   1 /* font.h -- Interface definition for font handling.
   2    Copyright (C) 2006 Free Software Foundation, Inc.
   3    Copyright (C) 2006
   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 2, or (at your option)
  12 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; see the file COPYING.  If not, write to
  21 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  22 Boston, MA 02110-1301, USA.  */
  23
  24 #ifndef EMACS_FONT_H
  25 #define EMACS_FONT_H
  26
  27 #include "ccl.h"
  28
  29 /* We have three types of Lisp objects related to font.
  30
  31    FONT-SPEC
  32
  33         Vector (length FONT_SPEC_MAX) of font properties.  Some
  34         properties can be left unspecified (i.e. nil).  Emacs asks
  35         font-drivers to find a font by FONT-SPEC.  A fontset entry
  36         specifies requisite properties whereas a face specifies just
  37         preferable properties.  This object is fully modifiable by
  38         Lisp.
  39
  40    FONT-ENTITY
  41
  42         Vector (length FONT_ENTITY_MAX) of fully specified font
  43         properties that a font-driver returns upon a request of
  44         FONT-SPEC.
  45
  46         Note: Only the method `list' of a font-driver can create this
  47         object, and should never be modified by Lisp.  In that sense,
  48         it may be cleaner to implement it as a Lisp object of a new
  49         type (e.g. struct Lisp_Font).
  50
  51    FONT-OBJECT
  52
  53         Lisp object of type Lisp_Misc_Save_Value encapsulating a
  54         pointer to "struct font".  This corresponds to an opened font.
  55
  56         Note: The note for FONT-ENTITY also applies to this.
  57 */
  58
  59
  60 struct font_driver;
  61 struct font;
  62
  63 /* An enumerator for each font property.  This is used as an index to
  64    the vector of FONT-SPEC and FONT-ENTITY.
  65
  66    Note: The order is important and should not be changed.  */
  67
  68 enum font_property_index
  69   {
  70     /* FONT-TYPE is a symbol indicating a font backend; currently `x',
  71        `xft', `ftx', `freetype' are available.  For windows, we need
  72        `bdf' and `windows'.  For Mac OS X, we need `atm'.  */
  73     FONT_TYPE_INDEX,
  74
  75     /* FONT-FOUNDRY is a foundry name (symbol).  */
  76     FONT_FOUNDRY_INDEX,
  77
  78     /* FONT-FAMILY is a family name (symbol).  */
  79     FONT_FAMILY_INDEX,
  80
  81     /* FONT-ADSTYLE is an additional style name (symbol).  */
  82     FONT_ADSTYLE_INDEX,
  83
  84     /* FONT-REGISTRY is a combination of a charset-registry and
  85        charset0encoding name (symbol).  */
  86     FONT_REGISTRY_INDEX,
  87
  88     /* FONT-WEIGHT is a numeric value of weight (e.g. medium, bold) of
  89        the font.  The value is what defined by FC_WEIGHT_* in
  90        fontconfig. */
  91     FONT_WEIGHT_INDEX,
  92
  93     /* FONT-SLANT is a numeric value of slant (e.g. r, i, o) of the
  94        font.  The value is what defined by FC_SLANT_* in
  95        fontconfig plus 100. */
  96     FONT_SLANT_INDEX,
  97
  98     /* FONT-WIDTH is a numeric value of setwidth (e.g. normal,
  99        condensed) of the font.  The value is what defined by
 100        FC_WIDTH_* in fontconfig. */
 101     FONT_WIDTH_INDEX,
 102
 103     /* FONT-SIZE is a size of the font.  If integer, it is a pixel
 104        size.  For a font-spec, the value can be float specifying a
 105        point size.  For a font-entity, the value can be zero meaning
 106        that the font is scalable.  */
 107     FONT_SIZE_INDEX,
 108
 109     /* In a font-spec, the value is an alist of extra information of a
 110        font such as name, OpenType features, and language coverage.
 111        In a font-entity, the value is an extra infomation for
 112        identifying a font (font-driver dependent).  */
 113     FONT_EXTRA_INDEX,           /* alist                alist */
 114
 115     /* This value is the length of font-spec vector.  */
 116     FONT_SPEC_MAX,
 117
 118     /* The followings are used only for a font-entity.  */
 119
 120     /* Frame on which the font is found.  The value is nil if the font
 121        can be opend on any frame.  */
 122     FONT_FRAME_INDEX = FONT_SPEC_MAX,
 123
 124     /* List of font-objects opened from the font-entity.  */
 125     FONT_OBJLIST_INDEX,
 126
 127     /* This value is the length of font-entity vector.  */
 128     FONT_ENTITY_MAX
 129   };
 130
 131 extern Lisp_Object QCspacing, QCdpi, QCscalable, QCotf, QClanguage, QCscript;
 132
 133 /* Important character set symbols.  */
 134 extern Lisp_Object Qiso8859_1, Qiso10646_1, Qunicode_bmp, Qunicode_sip;
 135
 136 extern Lisp_Object null_string;
 137 extern Lisp_Object null_vector;
 138
 139 /* Structure for an opened font.  We can safely cast this structure to
 140    "struct font_info".  */
 141
 142 struct font
 143 {
 144   struct font_info font;
 145
 146   /* From which font-entity the font is opened.  */
 147   Lisp_Object entity;
 148
 149   /* By which pixel size the font is opened.  */
 150   int pixel_size;
 151
 152   /* Font-driver for the font.  */
 153   struct font_driver *driver;
 154
 155   /* Symbol of font font; x, ttf, pcf, etc,   */
 156   Lisp_Object format;
 157
 158   /* File name of the font, or NULL if the font is not associated with
 159      a file.  */
 160   char *file_name;
 161
 162   /* Charset to encode a character code into a glyph code of the font.
 163      -1 means that the font doesn't require this information to encode
 164      a character.  */
 165   int encoding_charset;
 166
 167   /* Charset to check if a character code is supported by the font.
 168      -1 means that the contents of the font must be looked up to
 169      determine it.  */
 170   int repertory_charset;
 171
 172   /* Minimum glyph width (in pixels).  */
 173   int min_width;
 174
 175   /* Ascent and descent of the font (in pixels).  */
 176   int ascent, descent;
 177
 178   /* 1 iff the font is scalable.  */
 179   int scalable;
 180
 181   /* There will be more to this structure, but they are private to a
 182      font-driver.  */
 183 };
 184
 185 enum font_spacing
 186   {
 187     FONT_SPACING_PROPORTIONAL = 0,
 188     FONT_SPACING_DUAL = 90,
 189     FONT_SPACING_MONO = 100,
 190     FONT_SPACING_CHARCELL = 110
 191   };
 192
 193 struct font_metrics
 194 {
 195   short lbearing, rbearing, width, ascent, descent;
 196 };
 197
 198 struct font_bitmap
 199 {
 200   int rows;
 201   int width;
 202   int pitch;
 203   unsigned char *buffer;
 204   int left;
 205   int top;
 206   int advance;
 207   void *extra;
 208 };
 209
 210 /* Predicates to check various font-related objects.  */
 211
 212 #define FONTP(x)        \
 213   (VECTORP (x) && (ASIZE (x) == FONT_SPEC_MAX || ASIZE (x) == FONT_ENTITY_MAX))
 214 #define FONT_SPEC_P(x)  \
 215   (VECTORP (x) && ASIZE (x) == FONT_SPEC_MAX)
 216 #define FONT_ENTITY_P(x)        \
 217   (VECTORP (x) && ASIZE (x) == FONT_ENTITY_MAX)
 218 #define FONT_OBJECT_P(x)        \
 219   (XTYPE (x) == Lisp_Misc && XMISCTYPE (x) == Lisp_Misc_Save_Value)
 220
 221
 222 /* Check macros for various font-related objects.  */
 223
 224 #define CHECK_FONT(x)   \
 225   do { if (! FONTP (x)) x = wrong_type_argument (Qfont, x); } while (0)
 226 #define CHECK_FONT_SPEC(x)      \
 227   do { if (! FONT_SPEC_P (x)) x = wrong_type_argument (Qfont, x); } while (0)
 228 #define CHECK_FONT_ENTITY(x)    \
 229   do { if (! FONT_ENTITY_P (x)) x = wrong_type_argument (Qfont, x); } while (0)
 230 #define CHECK_FONT_OBJECT(x)    \
 231   do { if (! FONT_OBJECT_P (x)) x = wrong_type_argument (Qfont, x); } while (0)
 232
 233 #define CHECK_FONT_GET_OBJECT(x, font)                                  \
 234   do {                                                                  \
 235     if (! FONT_OBJECT_P (x)) x = wrong_type_argument (Qfont, x);        \
 236     if (! XSAVE_VALUE (x)->pointer) error ("Font already closed");      \
 237     font = XSAVE_VALUE (x)->pointer;                                    \
 238   } while (0)
 239
 240 /* Ignore the difference of font pixel sizes less than or equal to
 241    this value.  */
 242 #define FONT_PIXEL_SIZE_QUANTUM 1
 243
 244 struct face;
 245 struct composition;
 246
 247 /* Macros for lispy glyph-string.  */
 248 #define LGSTRING_FONT(lgs) AREF (AREF ((lgs), 0), 0)
 249 #define LGSTRING_LBEARING(lgs) AREF (AREF ((lgs), 0), 1)
 250 #define LGSTRING_RBEARING(lgs) AREF (AREF ((lgs), 0), 2)
 251 #define LGSTRING_WIDTH(lgs) AREF (AREF ((lgs), 0), 3)
 252 #define LGSTRING_ASCENT(lgs) AREF (AREF ((lgs), 0), 4)
 253 #define LGSTRING_DESCENT(lgs) AREF (AREF ((lgs), 0), 5)
 254 #define LGSTRING_SET_FONT(lgs, val) ASET (AREF ((lgs), 0), 0, (val))
 255 #define LGSTRING_SET_LBEARING(lgs, val) ASET (AREF ((lgs), 0), 1, (val))
 256 #define LGSTRING_SET_RBEARING(lgs, val) ASET (AREF ((lgs), 0), 2, (val))
 257 #define LGSTRING_SET_WIDTH(lgs, val) ASET (AREF ((lgs), 0), 3, (val))
 258 #define LGSTRING_SET_ASCENT(lgs, val) ASET (AREF ((lgs), 0), 4, (val))
 259 #define LGSTRING_SET_DESCENT(lgs, val) ASET (AREF ((lgs), 0), 5, (val))
 260
 261 #define LGSTRING_LENGTH(lgs) (ASIZE ((lgs)) - 1)
 262 #define LGSTRING_GLYPH(lgs, idx) AREF ((lgs), (idx) + 1)
 263
 264 #define LGLYPH_FROM(g) AREF ((g), 0)
 265 #define LGLYPH_TO(g) AREF ((g), 1)
 266 #define LGLYPH_CHAR(g) AREF ((g), 2)
 267 #define LGLYPH_CODE(g) AREF ((g), 3)
 268 #define LGLYPH_WIDTH(g) AREF ((g), 4)
 269 #define LGLYPH_ADJUSTMENT(g) AREF ((g), 5)
 270 #define LGLYPH_SET_FROM(g, val) ASET ((g), 0, (val))
 271 #define LGLYPH_SET_TO(g, val) ASET ((g), 1, (val))
 272 #define LGLYPH_SET_CHAR(g, val) ASET ((g), 2, (val))
 273 #define LGLYPH_SET_CODE(g, val) ASET ((g), 3, (val))
 274 #define LGLYPH_SET_WIDTH(g, val) ASET ((g), 4, (val))
 275 #define LGLYPH_SET_ADJUSTMENT(g, val) ASET ((g), 5, (val))
 276
 277 #define LGLYPH_XOFF(g) (VECTORP (LGLYPH_ADJUSTMENT (g)) \
 278                         ? XINT (AREF (LGLYPH_ADJUSTMENT (g), 0)) : 0)
 279 #define LGLYPH_YOFF(g) (VECTORP (LGLYPH_ADJUSTMENT (g)) \
 280                         ? XINT (AREF (LGLYPH_ADJUSTMENT (g), 1)) : 0)
 281 #define LGLYPH_WADJUST(g) (VECTORP (LGLYPH_ADJUSTMENT (g)) \
 282                            ? XINT (AREF (LGLYPH_ADJUSTMENT (g), 2)) : 0)
 283
 284 #define FONT_INVALID_CODE 0xFFFFFFFF
 285
 286 /* Font driver.  Members specified as "optional" can be NULL.  */
 287
 288 struct font_driver
 289 {
 290   /* Symbol indicating the type of the font-driver.  */
 291   Lisp_Object type;
 292
 293   /* Return a cache of font-entities on FRAME.  The cache must be a
 294      cons whose cdr part is the actual cache area.  */
 295   Lisp_Object (*get_cache) P_ ((Lisp_Object frame));
 296
 297   /* List fonts exactly matching with FONT_SPEC on FRAME.  The value
 298      is a vector of font-entities.  This is the sole API that
 299      allocates font-entities.  */
 300   Lisp_Object (*list) P_ ((Lisp_Object frame, Lisp_Object font_spec));
 301
 302   /* Return a font entity most closely maching with FONT_SPEC on
 303      FRAME.  The closeness is detemined by the font backend, thus
 304      `face-font-selection-order' is ignored here.  */
 305   Lisp_Object (*match) P_ ((Lisp_Object frame, Lisp_Object font_spec));
 306
 307   /* Optional.
 308      List available families.  The value is a list of family names
 309      (symbols).  */
 310   Lisp_Object (*list_family) P_ ((Lisp_Object frame));
 311
 312   /* Optional (if FONT_EXTRA_INDEX is not Lisp_Save_Value).
 313      Free FONT_EXTRA_INDEX field of FONT_ENTITY.  */
 314   void (*free_entity) P_ ((Lisp_Object font_entity));
 315
 316   /* Open a font specified by FONT_ENTITY on frame F.  If the font is
 317      scalable, open it with PIXEL_SIZE.  */
 318   struct font *(*open) P_ ((FRAME_PTR f, Lisp_Object font_entity,
 319                             int pixel_size));
 320
 321   /* Close FONT on frame F.  */
 322   void (*close) P_ ((FRAME_PTR f, struct font *font));
 323
 324   /* Optional (if FACE->extra is not used).
 325      Prepare FACE for displaying characters by FONT on frame F by
 326      storing some data in FACE->extra.  If successful, return 0.
 327      Otherwise, return -1.  */
 328   int (*prepare_face) P_ ((FRAME_PTR f, struct face *face));
 329
 330   /* Optional.
 331      Done FACE for displaying characters by FACE->font on frame F.  */
 332   void (*done_face) P_ ((FRAME_PTR f, struct face *face));
 333
 334   /* Optional.
 335      If FONT_ENTITY has a glyph for character C (Unicode code point),
 336      return 1.  If not, return 0.  If a font must be opened to check
 337      it, return -1.  */
 338   int (*has_char) P_ ((Lisp_Object entity, int c));
 339
 340   /* Return a glyph code of FONT for characer C (Unicode code point).
 341      If FONT doesn't have such a glyph, return FONT_INVALID_CODE.  */
 342   unsigned (*encode_char) P_ ((struct font *font, int c));
 343
 344   /* Perform the size computation of glyphs of FONT and fillin members
 345      of METRICS.  The glyphs are specified by their glyph codes in
 346      CODE (length NGLYPHS).  */
 347   int (*text_extents) P_ ((struct font *font,
 348                            unsigned *code, int nglyphs,
 349                            struct font_metrics *metrics));
 350
 351   /* Optional.
 352      Draw glyphs between FROM and TO of S->char2b at (X Y) pixel
 353      position of frame F with S->FACE and S->GC.  If WITH_BACKGROUND
 354      is nonzero, fill the background in advance.  It is assured that
 355      WITH_BACKGROUND is zero when (FROM > 0 || TO < S->nchars).  */
 356   int (*draw) P_ ((struct glyph_string *s, int from, int to,
 357                    int x, int y, int with_background));
 358
 359   /* Optional.
 360      Store bitmap data for glyph-code CODE of FONT in BITMAP.  It is
 361      intended that this method is callled from the other font-driver
 362      for actual drawing.  */
 363   int (*get_bitmap) P_ ((struct font *font, unsigned code,
 364                          struct font_bitmap *bitmap,
 365                          int bits_per_pixel));
 366
 367   /* Optional.
 368      Free bitmap data in BITMAP.  */
 369   void (*free_bitmap) P_ ((struct font *font, struct font_bitmap *bitmap));
 370
 371   /* Optional.
 372      Return an outline data for glyph-code CODE of FONT.  The format
 373      of the outline data depends on the font-driver.  */
 374   void *(*get_outline) P_ ((struct font *font, unsigned code));
 375
 376   /* Optional.
 377      Free OUTLINE (that is obtained by the above method).  */
 378   void (*free_outline) P_ ((struct font *font, void *outline));
 379
 380   /* Optional.
 381      Get coordinates of the INDEXth anchor point of the glyph whose
 382      code is CODE.  Store the coordinates in *X and *Y.  Return 0 if
 383      the operations was successfull.  Otherwise return -1.  */
 384   int (*anchor_point) P_ ((struct font *font, unsigned code, int index,
 385                            int *x, int *y));
 386
 387   /* Optional.
 388      Return a list describing which scripts/languages FONT
 389      supports by which GSUB/GPOS features of OpenType tables.  */
 390   Lisp_Object (*otf_capability) P_ ((struct font *font));
 391
 392   /* Optional.
 393      Apply FONT's OTF-FEATURES to the glyph string.
 394
 395      FEATURES specifies which OTF features to apply in this format:
 396         (SCRIPT LANGSYS GSUB-FEATURE GPOS-FEATURE)
 397      See the documentation of `font-drive-otf' for the detail.
 398
 399      This method applies the specified features to the codes in the
 400      elements of GSTRING-IN (between FROMth and TOth).  The output
 401      codes are stored in GSTRING-OUT at the IDXth element and the
 402      following elements.
 403
 404      Return the number of output codes.  If none of the features are
 405      applicable to the input data, return 0.  If GSTRING-OUT is too
 406      short, return -1.  */
 407   int (*otf_drive) P_ ((struct font *font, Lisp_Object features,
 408                        Lisp_Object gstring_in, int from, int to,
 409                        Lisp_Object gstring_out, int idx, int alternate_subst));
 410 };
 411
 412
 413 struct font_driver_list
 414 {
 415   /* 1 iff this driver is currently used.  */
 416   int on;
 417   struct font_driver *driver;
 418   struct font_driver_list *next;
 419 };
 420
 421 extern int enable_font_backend;
 422
 423 EXFUN (Ffont_spec, MANY);
 424 EXFUN (Flist_fonts, 4);
 425 EXFUN (Fclear_font_cache, 0);
 426 EXFUN (Ffont_xlfd_name, 1);
 427
 428 extern Lisp_Object font_symbolic_weight P_ ((Lisp_Object font));
 429 extern Lisp_Object font_symbolic_slant P_ ((Lisp_Object font));
 430 extern Lisp_Object font_symbolic_width P_ ((Lisp_Object font));
 431
 432 extern int font_match_p P_ ((Lisp_Object spec, Lisp_Object entity));
 433
 434 extern Lisp_Object font_find_object P_ ((struct font *font));
 435 extern Lisp_Object font_get_name P_ ((Lisp_Object font_object));
 436 extern Lisp_Object font_get_spec P_ ((Lisp_Object font_object));
 437 extern Lisp_Object font_get_frame P_ ((Lisp_Object font_object));
 438 extern int font_has_char P_ ((FRAME_PTR, Lisp_Object, int));
 439 extern unsigned font_encode_char P_ ((Lisp_Object, int));
 440
 441 extern int font_set_lface_from_name P_ ((FRAME_PTR f,
 442                                          Lisp_Object lface,
 443                                          Lisp_Object fontname,
 444                                          int force_p, int may_fail_p));
 445 extern Lisp_Object font_find_for_lface P_ ((FRAME_PTR f, Lisp_Object *lface,
 446                                             Lisp_Object spec));
 447 extern Lisp_Object font_open_for_lface P_ ((FRAME_PTR f, Lisp_Object entity,
 448                                             Lisp_Object *lface,
 449                                             Lisp_Object spec));
 450 extern void font_load_for_face P_ ((FRAME_PTR f, struct face *face));
 451 extern void font_prepare_for_face P_ ((FRAME_PTR f, struct face *face));
 452 extern Lisp_Object font_open_by_name P_ ((FRAME_PTR f, char *name));
 453 extern void font_close_object (FRAME_PTR f, Lisp_Object font_object);
 454
 455 extern Lisp_Object intern_downcase P_ ((char *str, int len));
 456 extern void font_update_sort_order P_ ((int *order));
 457
 458 extern void font_merge_old_spec P_ ((Lisp_Object name, Lisp_Object family,
 459                                      Lisp_Object registry, Lisp_Object spec));
 460
 461
 462 extern int font_parse_xlfd P_ ((char *name, Lisp_Object font));
 463 extern int font_unparse_xlfd P_ ((Lisp_Object font, int pixel_size,
 464                                   char *name, int bytes));
 465 extern int font_parse_fcname P_ ((char *name, Lisp_Object font));
 466 extern int font_unparse_fcname P_ ((Lisp_Object font, int pixel_size,
 467                                   char *name, int bytes));
 468 extern void register_font_driver P_ ((struct font_driver *driver, FRAME_PTR f));
 469 extern void free_font_driver_list P_ ((FRAME_PTR f));
 470 extern Lisp_Object font_update_drivers P_ ((FRAME_PTR f, Lisp_Object list));
 471 extern Lisp_Object font_at P_ ((int c, EMACS_INT pos, struct face *face,
 472                                 struct window *w, Lisp_Object object));
 473
 474 extern struct font *font_prepare_composition P_ ((struct composition *cmp));
 475
 476 extern Lisp_Object font_put_extra P_ ((Lisp_Object font, Lisp_Object prop,
 477                                        Lisp_Object val));
 478
 479 #ifdef HAVE_LIBOTF
 480 /* This can be used as `otf_capability' method of a font-driver.  */
 481 extern Lisp_Object font_otf_capability P_ ((struct font *font));
 482 /* This can be used as `otf_drive' method of a font-driver.  */
 483 extern int font_drive_otf P_ ((struct font *font, Lisp_Object otf_features,
 484                                Lisp_Object gstring_in, int from, int to,
 485                                Lisp_Object gstring_out, int idx,
 486                                int alternate_subst));
 487 #endif  /* HAVE_LIBOTF */
 488
 489 #ifdef HAVE_FREETYPE
 490 extern struct font_driver ftfont_driver;
 491 #endif  /* HAVE_FREETYPE */
 492 #ifdef HAVE_X_WINDOWS
 493 extern struct font_driver xfont_driver;
 494 extern struct font_driver ftxfont_driver;
 495 #ifdef HAVE_XFT
 496 extern struct font_driver xftfont_driver;
 497 #endif  /* HAVE_XFT */
 498 #endif  /* HAVE_X_WINDOWS */
 499 #ifdef WINDOWSNT
 500 extern struct font_driver w32font_driver;
 501 #endif  /* WINDOWSNT */
 502 #ifdef MAC_OS
 503 extern struct font_driver atmfont_driver;
 504 #endif  /* MAC_OS */
 505
 506 #endif  /* not EMACS_FONT_H */
 507
 508 /* arch-tag: 3b7260c3-5bec-4d6b-a0db-95c1b431b1a2
 509    (do not change this comment) */