src/include/font.h

   1 // -*- C++ -*-
   2 /* Copyright (C) 1989, 1990, 1991, 1992, 2002, 2004, 2006
   3    Free Software Foundation, Inc.
   4      Written by James Clark (jjc@jclark.com)
   5
   6 This file is part of groff.
   7
   8 groff is free software; you can redistribute it and/or modify it under
   9 the terms of the GNU General Public License as published by the Free
  10 Software Foundation; either version 2, or (at your option) any later
  11 version.
  12
  13 groff is distributed in the hope that it will be useful, but WITHOUT ANY
  14 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  15 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  16 for more details.
  17
  18 You should have received a copy of the GNU General Public License along
  19 with groff; see the file COPYING.  If not, write to the Free Software
  20 Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA. */
  21
  22 // A function of this type can be registered to define the semantics of
  23 // arbitrary commands in a font DESC file.
  24 typedef void (*FONT_COMMAND_HANDLER)(const char *,      // command
  25                                      const char *,      // arg
  26                                      const char *,      // file
  27                                      int);              // lineno
  28
  29 // A glyph is represented by a font-independent `glyph *' pointer.
  30 // The functions name_to_glyph and number_to_glyph return such a pointer.
  31 //
  32 // There are two types of glyphs:
  33 //
  34 //   - those with a name, and among these in particular:
  35 //     `charNNN' denoting a single `char' in the input character set,
  36 //     `uXXXX' denoting a Unicode character,
  37 //
  38 //   - those with a number, referring to the the font-dependent glyph with
  39 //     the given number.
  40
  41 // The statically allocated information about a glyph.
  42 //
  43 // This is an abstract class; only its subclass `charinfo' is instantiated.
  44 // `charinfo' exists in two versions: one in roff/troff/input.cpp for troff,
  45 // and one in libs/libgroff/nametoindex.cpp for the preprocessors and the
  46 // postprocessors.
  47 struct glyph {
  48   int index;                    // A font-independent integer value.
  49   int number;                   // Glyph number or -1.
  50   friend class character_indexer;
  51 };
  52
  53 #define UNDEFINED_GLYPH ((glyph *) NULL)
  54
  55 // The next three functions exist in two versions: one in
  56 // roff/troff/input.cpp for troff, and one in
  57 // libs/libgroff/nametoindex.cpp for the preprocessors and the
  58 // postprocessors.
  59 extern glyph *name_to_glyph(const char *);      // Convert the glyph with
  60                         // the given name (arg1) to a `glyph' object.  This
  61                         // has the same semantics as the groff escape sequence
  62                         // \C'name'.  If such a `glyph' object does not yet
  63                         // exist, a new one is allocated.
  64 extern glyph *number_to_glyph(int);     // Convert the font-dependent glyph
  65                         // with the given number (in the font) to a `glyph'
  66                         // object.  This has the same semantics as the groff
  67                         // escape sequence \N'number'.  If such a `glyph'
  68                         // object does not yet exist, a new one is allocated.
  69 extern const char *glyph_to_name(glyph *);      // Convert the given glyph
  70                         // back to its name.  Return NULL if the glyph
  71                         // doesn't have a name.
  72 inline int glyph_to_number(glyph *);    // Convert the given glyph back to
  73                         // its number.  Return -1 if it does not designate
  74                         // a numbered character.
  75 inline int glyph_to_index(glyph *);     // Return the unique index that is
  76                         // associated with the given glyph. It is >= 0.
  77
  78 inline int glyph_to_number(glyph *g)
  79 {
  80   return g->number;
  81 }
  82
  83 inline int glyph_to_index(glyph *g)
  84 {
  85   return g->index;
  86 }
  87
  88 // Types used in non-public members of `class font'.
  89 struct font_kern_list;
  90 struct font_char_metric;
  91 struct font_widths_cache;
  92
  93 // A `class font' instance represents the relevant information of a font of
  94 // the given device.  This includes the set of glyphs represented by the
  95 // font, and metrics for each glyph.
  96 class font {
  97 public:
  98   enum {                // The valid argument values of `has_ligature'.
  99     LIG_ff = 1,
 100     LIG_fi = 2,
 101     LIG_fl = 4,
 102     LIG_ffi = 8,
 103     LIG_ffl = 16
 104   };
 105
 106   virtual ~font();      // Destructor.
 107   int contains(glyph *);        // Return 1 if this font contains the given
 108                         // glyph, 0 otherwise.
 109   int is_special();     // Return 1 if this font is special, 0 otherwise.
 110                         // See section `Special Fonts' in the info file of
 111                         // groff.  Used by make_glyph_node().
 112   int get_width(glyph *, int);  // A rectangle represents the shape of the
 113                         // given glyph (arg1) at the given point size
 114                         // (arg2).  Return the horizontal dimension of this
 115                         // rectangle.
 116   int get_height(glyph *, int); // A rectangle represents the shape of the
 117                         // given glyph (arg1) at the given point size
 118                         // (arg2).  Return the distance between the base
 119                         // line and the top of this rectangle.
 120                         // This is often also called the `ascent' of the
 121                         // glyph.  If the top is above the base line, this
 122                         // value is positive.
 123   int get_depth(glyph *, int);  // A rectangle represents the shape of the
 124                         // given glyph (arg1) at the given point size
 125                         // (arg2).  Return the distance between the base
 126                         // line and the bottom of this rectangle.
 127                         // This is often also called the `descent' of the
 128                         // glyph.  If the bottom is below the base line,
 129                         // this value is positive.
 130   int get_space_width(int);     // Return the normal width of a space at the
 131                         // given point size.
 132   int get_character_type(glyph *);      // Return a bit mask describing the
 133                         // shape of the given glyph.  Bit 0 is set if the
 134                         // character has a descender.  Bit 1 is set if the
 135                         // character has a tall glyph.  See groff manual,
 136                         // description of \w and the `ct' register.
 137   int get_kern(glyph *, glyph *, int);  // Return the kerning between the
 138                         // given glyphs (arg1 and arg2), both at the given
 139                         // point size (arg3).
 140   int get_skew(glyph *, int, int);      // A rectangle represents the shape
 141                         // of the given glyph (arg1) at the given point size
 142                         // (arg2).  For slanted fonts like Times-Italic, the
 143                         // optical vertical axis is naturally slanted.  The
 144                         // natural slant value (measured in degrees;
 145                         // positive values mean aslant to the right) is
 146                         // specified in the font's description file (see
 147                         // member variable SLANT below).  In addition to
 148                         // this, any font can be artificially slanted.  This
 149                         // artificial slant value (arg3, measured in
 150                         // degrees; positive values mean a slant to the
 151                         // right) is specified with the \S escape.
 152                         //
 153                         // Return the skew value which is the horizontal
 154                         // distance between the upper left corner of the
 155                         // glyph box and the upper left corner of the glyph
 156                         // box thought to be slanted by the sum of the
 157                         // natural and artificial slant.  It basically means
 158                         // how much an accent must be shifted horizontally
 159                         // to put it on the optical axis of the glyph.
 160   int has_ligature(int);        // Return a non-zero value if this font has
 161                         // the given ligature type (one of LIG_ff, LIG_fi,
 162                         // etc.), 0 otherwise.
 163   int get_italic_correction(glyph *, int);      // If the given glyph (arg1)
 164                         // at the given point size (arg2) is followed by an
 165                         // unslanted glyph, some horizontal white space may
 166                         // need to be inserted in between.  See the groff
 167                         // manual, description of \/.  Return the amount
 168                         // (width) of this white space.
 169   int get_left_italic_correction(glyph *, int); // If the given glyph (arg1)
 170                         // at the given point size (arg2) is preceded by an
 171                         // unslanted roman glyph, some horizontal white
 172                         // space may need to be inserted in between.  See
 173                         // the groff manual, description of \,.  Return the
 174                         // amount (width) of this white space.
 175   int get_subscript_correction(glyph *, int);   // If the given glyph (arg1)
 176                         // at the given point size (arg2)is followed by a
 177                         // subscript glyph, the horizontal position may need
 178                         // to be advanced by some (possibly negative)
 179                         // amount.  See groff manual, description of \w and
 180                         // the `ssc' register.  Return this amount.
 181   void set_zoom(int);   // Set the font's zoom factor * 1000.  Must be a
 182                         // non-negative value.
 183   int get_zoom();       // Return the font's zoom factor * 1000.
 184   int get_code(glyph *);        // Return the code point in the physical
 185                         // font of the given glyph.
 186   const char *get_special_device_encoding(glyph *);     // Return special
 187                         // device dependent information about the given
 188                         // glyph.  Return NULL if there is no special
 189                         // information.
 190   const char *get_name();       // Return the name of this font.
 191   const char *get_internal_name();      // Return the `internalname'
 192                         // attribute of this font.  Return NULL if it has
 193                         // none.
 194   const char *get_image_generator();    // Return the `image_generator'
 195                         // attribute of this font.  Return NULL if it has
 196                         // none.
 197   static int scan_papersize(const char *, const char **,
 198                             double *, double *);        // Parse the
 199                         // `papersize' attribute in a DESC file (given in
 200                         // arg1).  Return the name of the size (in arg2),
 201                         // and the length and width (in arg3 and arg4).
 202                         // Return 1 in case of success, 0 otherwise.
 203   static font *load_font(const char *, int * = 0, int = 0);     // Load the
 204                         // font description file with the given name (arg1)
 205                         // and return it as a `font' class.  If arg2 points
 206                         // to an integer variable, set it to 1 if the file
 207                         // is not found, without emitting an error message.
 208                         // If arg2 is NULL, print an error message if the
 209                         // file is not found.  If arg3 is nonzero, only the
 210                         // part of the font description file before the
 211                         // `charset' and `kernpairs' sections is loaded.
 212                         // Return NULL in case of failure.
 213   static void command_line_font_dir(const char *);      // Prepend given
 214                         // path (arg1) to the list of directories in which
 215                         // to look up fonts.
 216   static FILE *open_file(const char *, char **);        // Open a font file
 217                         // with the given name (arg1), searching along the
 218                         // current font path.  If arg2 points to a string
 219                         // pointer, set it to the found file name (this
 220                         // depends on the device also).  Return the opened
 221                         // file.  If not found, arg2 is unchanged, and NULL
 222                         // is returned.
 223   static int load_desc();       // Open the DESC file (depending on the
 224                         // device) and initialize some static variables with
 225                         // info from there.
 226   static FONT_COMMAND_HANDLER
 227     set_unknown_desc_command_handler(FONT_COMMAND_HANDLER);     // Register
 228                         // a function which defines the semantics of
 229                         // arbitrary commands in the font DESC file.
 230   // Now the variables from the DESC file, shared by all fonts.
 231   static int res;       // The `res' attribute given in the DESC file.
 232   static int hor;       // The `hor' attribute given in the DESC file.
 233   static int vert;      // The `vert' attribute given in the DESC file.
 234   static int unitwidth; // The `unitwidth' attribute given in the DESC file.
 235   static int paperwidth;        // The `paperwidth' attribute given in the
 236                         // DESC file, or derived from the `papersize'
 237                         // attribute given in the DESC file.
 238   static int paperlength;       // The `paperlength' attribute given in the
 239                         // DESC file, or derived from the `papersize'
 240                         // attribute given in the DESC file.
 241   static const char *papersize;
 242   static int biggestfont;       // The `biggestfont' attribute given in the
 243                         // DESC file.
 244   static int spare2;
 245   static int sizescale; // The `sizescale' attribute given in the DESC file.
 246   static int tcommand;  // Nonzero if the DESC file has the `tcommand'
 247                         // attribute.
 248   static int unscaled_charwidths;       // Nonzero if the DESC file has the
 249                         // `unscaled_charwidths' attribute.
 250   static int pass_filenames;    // Nonzero if the DESC file has the
 251                         // `pass_filenames' attribute.
 252   static int use_charnames_in_special;  // Nonzero if the DESC file has the
 253                         // `use_charnames_in_special' attribute.
 254   static int is_unicode; // Nonzero if the DESC file has the `unicode'
 255                         // attribute.
 256   static const char *image_generator;   // The `image_generator' attribute
 257                         // given in the DESC file.
 258   static const char **font_name_table;  // The `fonts' attribute given in
 259                         // the DESC file, as a NULL-terminated array of
 260                         // strings.
 261   static const char **style_table;      // The `styles' attribute given in
 262                         // the DESC file, as a NULL-terminated array of
 263                         // strings.
 264   static const char *family;    // The `family' attribute given in the DESC
 265                         // file.
 266   static int *sizes;    // The `sizes' attribute given in the DESC file, as
 267                         // an array of intervals of the form { lower1,
 268                         // upper1, ... lowerN, upperN, 0 }.
 269
 270 private:
 271   unsigned ligatures;   // Bit mask of available ligatures.  Used by
 272                         // has_ligature().
 273   font_kern_list **kern_hash_table;     // Hash table of kerning pairs.
 274                         // Used by get_kern().
 275   int space_width;      // The normal width of a space.  Used by
 276                         // get_space_width().
 277   int special;          // 1 if this font is special, 0 otherwise.  Used by
 278                         // is_special().
 279   char *name;           // The name of this font.  Used by get_name().
 280   char *internalname;   // The `internalname' attribute of this font, or
 281                         // NULL.  Used by get_internal_name().
 282   double slant;         // The natural slant angle (in degrees) of this font.
 283   int zoom;             // The font's magnification, multiplied by 1000.
 284                         // Used by scale().  A zero value means `no zoom'.
 285   int *ch_index;        // Conversion table from font-independent character
 286                         // indices to indices for this particular font.
 287   int nindices;
 288   font_char_metric *ch; // Metrics information for every character in this
 289                         // font (if !is_unicode) or for just some characters
 290                         // (if is_unicode).  The indices of this array are
 291                         // font-specific, found as values in ch_index[].
 292   int ch_used;
 293   int ch_size;
 294   font_widths_cache *widths_cache;      // A cache of scaled character
 295                         // widths.  Used by the get_width() function.
 296
 297   static FONT_COMMAND_HANDLER unknown_desc_command_handler;     // A
 298                         // function defining the semantics of arbitrary
 299                         // commands in the DESC file.
 300   enum { KERN_HASH_TABLE_SIZE = 503 };  // Size of the hash table of kerning
 301                         // pairs.
 302
 303   // These methods add new characters to the ch_index[] and ch[] arrays.
 304   void add_entry(glyph *,                       // glyph
 305                  const font_char_metric &);     // metric
 306   void copy_entry(glyph *,                      // new_glyph
 307                   glyph *);                     // old_glyph
 308   void alloc_ch_index(int);                     // index
 309   void extend_ch();
 310   void compact();
 311
 312   void add_kern(glyph *, glyph *, int); // Add to the kerning table a
 313                         // kerning amount (arg3) between two given glyphs
 314                         // (arg1 and arg2).
 315   static int hash_kern(glyph *, glyph *);       // Return a hash code for
 316                         // the pair of glyphs (arg1 and arg2).
 317
 318   /* Returns w * pointsize / unitwidth, rounded to the nearest integer.  */
 319   int scale(int w, int pointsize);
 320   static int unit_scale(double *, char); // Convert value in arg1 from the
 321                         // given unit (arg2; possible values are `i', `c',
 322                         // `p', and `P' as documented in the info file of
 323                         // groff, section `Measurements') to inches.  Store
 324                         // the result in arg1 and return 1.  If the unit is
 325                         // invalid, return 0.
 326   virtual void handle_unknown_font_command(const char *,        // command
 327                                            const char *,        // arg
 328                                            const char *,        // file
 329                                            int);                // lineno
 330
 331 protected:
 332   font(const char *);   // Initialize a font with the given name.
 333
 334   int load(int * = 0, int = 0); // Load the font description file with the
 335                         // given name (in member variable NAME) into this
 336                         // object.  If arg1 points to an integer variable,
 337                         // set it to 1 if the file is not found, without
 338                         // emitting an error message.  If arg1 is NULL,
 339                         // print an error message if the file is not found.
 340                         // If arg2 is nonzero, only the part of the font
 341                         // description file before the `charset' and
 342                         // `kernpairs' sections is loaded.  Return NULL in
 343                         // case of failure.
 344 };
 345
 346 // end of font.h