src/include/font.h

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