lib/tadeltas.h

   1 /* tadeltas.h */
   2
   3 /*
   4  * Copyright (C) 2012-2014 by Werner Lemberg.
   5  *
   6  * This file is part of the ttfautohint library, and may only be used,
   7  * modified, and distributed under the terms given in `COPYING'.  By
   8  * continuing to use, modify, or distribute this file you indicate that you
   9  * have read `COPYING' and understand and accept it fully.
  10  *
  11  * The file `COPYING' mentioned in the previous paragraph is distributed
  12  * with the ttfautohint library.
  13  */
  14
  15
  16 #ifndef __DELTAS_H__
  17 #define __DELTAS_H__
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23
  24 /* see the section `Managing exceptions' in chapter 6 */
  25 /* (`The TrueType Instruction Set') of the OpenType reference */
  26 /* how `delta_shift' works */
  27
  28 #define DELTA_SHIFT 3 /* 1/8px */
  29 #define DELTA_FACTOR (1 << DELTA_SHIFT)
  30
  31 #define DELTA_SHIFT_MAX ((1.0 / DELTA_FACTOR) * 8)
  32 #define DELTA_SHIFT_MIN -DELTA_SHIFT_MAX
  33
  34
  35 /*
  36  * For the generated TrueType bytecode, we use
  37  *
  38  *   delta_base = 6   ,
  39  *
  40  * which gives us the following ppem ranges for the three delta
  41  * instructions:
  42  *
  43  *   DELTAP1    6-21ppem
  44  *   DELTAP2   22-37ppem
  45  *   DELTAP3   38-53ppem   .
  46  */
  47
  48 #define DELTA_PPEM_MIN 6
  49 #define DELTA_PPEM_MAX 53
  50
  51
  52 /*
  53  * A structure to hold delta exceptions for a glyph.  A linked list of it
  54  * gets allocated by a successful call to `TA_deltas_parse'.  Use
  55  * `TA_deltas_free' to deallocate the list.
  56  *
  57  * `x_shift' and `y_shift' are always in the range [-8;8].
  58  */
  59
  60 typedef struct Deltas_
  61 {
  62   long font_idx;
  63   long glyph_idx;
  64   number_range* points;
  65   char x_shift;
  66   char y_shift;
  67   number_range* ppems;
  68
  69   struct Deltas_* next;
  70 } Deltas;
  71
  72
  73 /*
  74  * Parse a delta exceptions file.
  75  *
  76  * A line in a delta exceptions file has the following syntax:
  77  *
  78  *   [<font idx>] <glyph id> p <points> [x <x shift>] [y <y shift>] @ <ppems>
  79  *
  80  * <font idx> gives the index of the font in a TrueType Collection.  If
  81  * missing, it is set to zero.  For normal TrueType fonts, only value zero
  82  * is valid.  If starting with `0x' the number is interpreted as
  83  * hexadecimal.  If starting with `0' it gets interpreted as an octal value,
  84  * and as a decimal value otherwise.
  85  *
  86  * <glyph id> is a glyph's name as listed in the `post' SFNT table or a
  87  * glyph index.  A glyph name consists of characters from the set
  88  * `A-Za-z0-9._' only and does not start with a digit or period, with the
  89  * exceptions of the names `.notdef' and `.null'.  A glyph index can be
  90  * specified in decimal, octal, or hexadecimal format, the latter two
  91  * indicated by the prefixes `0' and `0x', respectively.
  92  *
  93  * Both <points> and <ppems> are number ranges as described in
  94  * `numberset.h'; they are parsed using `number_set_parse'.
  95  *
  96  * <x shift> and <y shift> represent floating point numbers that get rounded
  97  * to multiples of 1/8 pixels.  The entries for `x' and `y' are optional; if
  98  * missing, the corresponding value is set to zero.
  99  *
 100  * Values for <x shift>, <y shift> must be in the range
 101  * [DELTA_SHIFT_MIN;DELTA_SHIFT_MAX].  Values for <ppems> must be in the
 102  * range [DELTA_PPEM_MIN;DELTA_PPEM_MAX].  Values for <points> are limited
 103  * by the number of points in the glyph.
 104  *
 105  * A comment starts with character `#'; the rest of the line is ignored.  An
 106  * empty line is ignored also.
 107  *
 108  * The returned error codes are in the range 0x200-0x2FF; see
 109  * `ttfautohint-errors.h' for all possible values.
 110  *
 111  * If the user provides a non-NULL `deltas' value, `TA_deltas_parse' stores
 112  * the parsed result in `*deltas'.  If there is no data (for example, an
 113  * empty string or whitespace only) nothing gets allocated, and `*deltas' is
 114  * set to NULL.
 115  *
 116  * In case of error, `errlinenum_p' gives the line number in the delta
 117  * exceptions file where the error occurred, `errline_p' the corresponding
 118  * line, and `errpos_p' the position in this line.  If there is no error,
 119  * those three values are undefined.  Both `errline_p' and `errpos_p' can be
 120  * NULL even in case of an error; otherwise `errline_p' must be deallocated
 121  * by the user.
 122  */
 123
 124 TA_Error
 125 TA_deltas_parse(FONT* font,
 126                 Deltas** deltas,
 127                 unsigned int* errlinenum_p,
 128                 char** errline_p,
 129                 char** errpos_p);
 130
 131
 132 /*
 133  * Free the allocated data in `deltas'.
 134  */
 135
 136 void
 137 TA_deltas_free(Deltas* deltas);
 138
 139
 140 /*
 141  * Return a string representation of `deltas'.  After use, the string should
 142  * be deallocated with a call to `free'.  In case of an allocation error,
 143  * the return value is NULL.
 144  */
 145
 146 char*
 147 TA_deltas_show(FONT* font,
 148                Deltas* deltas);
 149
 150 #ifdef __cplusplus
 151 } /* extern "C" */
 152 #endif
 153
 154 #endif /* __DELTAS_H__ */
 155
 156 /* end of deltas.h */