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  * A structure to hold a single delta exception.
  75  */
  76
  77 typedef struct Delta_
  78 {
  79   long font_idx;
  80   long glyph_idx;
  81   int ppem;
  82   int point_idx;
  83
  84   char x_shift;
  85   char y_shift;
  86 } Delta;
  87
  88
  89 /*
  90  * Parse a delta exceptions file.
  91  *
  92  * The format of lines in a delta exceptions file is given in
  93  * `ttfautohint.h' (option `deltas-file'); the following gives more
  94  * technical details, using the constants defined above.
  95  *
  96  * x shift and y shift values represent floating point numbers that get
  97  * rounded to multiples of 1/(2^DELTA_SHIFT) pixels.
  98  *
  99  * Values for x and y shifts must be in the range
 100  * [DELTA_SHIFT_MIN;DELTA_SHIFT_MAX].  Values for ppems must be in the range
 101  * [DELTA_PPEM_MIN;DELTA_PPEM_MAX].
 102  *
 103  * The returned error codes are in the range 0x200-0x2FF; see
 104  * `ttfautohint-errors.h' for all possible values.
 105  *
 106  * If the user provides a non-NULL `deltas' value, `TA_deltas_parse' stores
 107  * the parsed result in `*deltas'.  If there is no data (for example, an
 108  * empty string or whitespace only) nothing gets allocated, and `*deltas' is
 109  * set to NULL.
 110  *
 111  * In case of error, `errlinenum_p' gives the line number in the delta
 112  * exceptions file where the error occurred, `errline_p' the corresponding
 113  * line, and `errpos_p' the position in this line.  If there is no error,
 114  * those three values are undefined.  Both `errline_p' and `errpos_p' can be
 115  * NULL even in case of an error; otherwise `errline_p' must be deallocated
 116  * by the user.
 117  */
 118
 119 TA_Error
 120 TA_deltas_parse(FONT* font,
 121                 Deltas** deltas,
 122                 unsigned int* errlinenum_p,
 123                 char** errline_p,
 124                 char** errpos_p);
 125
 126
 127 /*
 128  * Free the allocated data in `deltas'.
 129  */
 130
 131 void
 132 TA_deltas_free(Deltas* deltas);
 133
 134
 135 /*
 136  * Return a string representation of `deltas'.  After use, the string should
 137  * be deallocated with a call to `free'.  In case of an allocation error,
 138  * the return value is NULL.
 139  */
 140
 141 char*
 142 TA_deltas_show(FONT* font,
 143                Deltas* deltas);
 144
 145
 146 /*
 147  * Build a tree providing sequential access to the delta exceptions data.
 148  * This also sets `deltas_data_cur' to the first element (or NULL if there
 149  * isn't one).
 150  */
 151
 152 TA_Error
 153 TA_deltas_build_tree(FONT* font,
 154                      Deltas* deltas);
 155
 156
 157 /*
 158  * Free the delta exceptions data tree.
 159  */
 160
 161 void
 162 TA_deltas_free_tree(FONT* font);
 163
 164
 165 /*
 166  * Get next delta exception and store it in `font->deltas_data_cur'.
 167  */
 168
 169 void
 170 TA_deltas_get_next(FONT* font);
 171
 172
 173 /*
 174  * Access delta exception.  Return NULL if there is no more data.
 175  */
 176 const Delta*
 177 TA_deltas_get_delta(FONT* font);
 178
 179 #ifdef __cplusplus
 180 } /* extern "C" */
 181 #endif
 182
 183 #endif /* __DELTAS_H__ */
 184
 185 /* end of deltas.h */