lib/tadeltas.h

   1 /* tadeltas.h */
   2
   3 /*
   4  * Copyright (C) 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 #include <setjmp.h>  /* for flex error handling */
  24
  25
  26 /* see the section `Managing exceptions' in chapter 6 */
  27 /* (`The TrueType Instruction Set') of the OpenType reference */
  28 /* how `delta_shift' works */
  29
  30 #define DELTA_SHIFT 3 /* 1/8px */
  31 #define DELTA_FACTOR (1 << DELTA_SHIFT)
  32
  33 #define DELTA_SHIFT_MAX ((1.0 / DELTA_FACTOR) * 8)
  34 #define DELTA_SHIFT_MIN -DELTA_SHIFT_MAX
  35
  36
  37 /*
  38  * For the generated TrueType bytecode, we use
  39  *
  40  *   delta_base = 6   ,
  41  *
  42  * which gives us the following ppem ranges for the three delta
  43  * instructions:
  44  *
  45  *   DELTAP1    6-21ppem
  46  *   DELTAP2   22-37ppem
  47  *   DELTAP3   38-53ppem   .
  48  */
  49
  50 #define DELTA_PPEM_MIN 6
  51 #define DELTA_PPEM_MAX 53
  52
  53
  54 /*
  55  * A structure to hold delta exceptions for a glyph.  A linked list of it
  56  * gets allocated by a successful call to `TA_deltas_parse_buffer'.  Use
  57  * `TA_deltas_free' to deallocate the list.
  58  *
  59  * `x_shift' and `y_shift' are always in the range [-8;8].
  60  *
  61  * The `Deltas' typedef is in `ta.h'.
  62  */
  63
  64 struct Deltas_
  65 {
  66   long font_idx;
  67   long glyph_idx;
  68   number_range* points;
  69   char x_shift;
  70   char y_shift;
  71   number_range* ppems;
  72
  73   struct Deltas_* next;
  74 };
  75
  76
  77 /*
  78  * A structure to hold a single delta exception.
  79  */
  80
  81 typedef struct Delta_
  82 {
  83   long font_idx;
  84   long glyph_idx;
  85   int ppem;
  86   int point_idx;
  87
  88   char x_shift;
  89   char y_shift;
  90 } Delta;
  91
  92
  93 /*
  94  * This structure is used for communication with `TA_deltas_parse'.
  95  */
  96
  97 typedef struct Deltas_Context_
  98 {
  99   /* The error code returned by the parser or lexer. */
 100   TA_Error error;
 101
 102   /* If no error, this holds the parsing result. */
 103   Deltas* result;
 104
 105   /*
 106    * The parser's or lexer's error message in case of error; might be the
 107    * empty string.
 108    */
 109   char errmsg[256];
 110
 111   /*
 112    * In case of error, `errline_num' gives the line number of the offending
 113    * line in `font->delta_buf', starting with value 1; `errline_pos_left'
 114    * and `errline_pos_right' hold the left and right position of the
 115    * offending token in this line, also starting with value 1.  For
 116    * allocation errors or internal parser or lexer errors those values are
 117    * meaningless, though.
 118    */
 119   int errline_num;
 120   int errline_pos_left;
 121   int errline_pos_right;
 122
 123   /*
 124    * The current font index, useful for `TA_Err_Deltas_Invalid_Font_Index'.
 125    */
 126   long font_idx;
 127
 128   /*
 129    * The current glyph index, useful for
 130    * `TA_Err_Deltas_Invalid_Glyph_Index'.
 131    */
 132   long glyph_idx;
 133
 134   /*
 135    * If the returned error is `TA_Err_Deltas_Invalid_Range', these two
 136    * values set up the allowed range.
 137    */
 138   long number_set_min;
 139   long number_set_max;
 140
 141   /* private flex data */
 142   void* scanner;
 143   int eof;
 144   jmp_buf jump_buffer;
 145
 146   /* private bison data */
 147   FONT* font;
 148 } Deltas_Context;
 149
 150
 151 /*
 152  * Create and initialize a `Deltas' object.  In case of an allocation error,
 153  * the return value is NULL.  `point_set' and `ppem_set' are expected to be
 154  * in reverse list order; `TA_deltas_new' then reverts them to normal order.
 155  */
 156
 157 Deltas*
 158 TA_deltas_new(long font_idx,
 159               long glyph_idx,
 160               number_range* point_set,
 161               double x_shift,
 162               double y_shift,
 163               number_range* ppem_set);
 164
 165
 166 /*
 167  * Prepend `element' to `list' of `Deltas' objects.  If `element' is NULL,
 168  * return `list.
 169  */
 170
 171 Deltas*
 172 TA_deltas_prepend(Deltas* list,
 173                   Deltas* element);
 174
 175
 176 /*
 177  * Reverse a list of `Deltas' objects.
 178  */
 179
 180 Deltas*
 181 TA_deltas_reverse(Deltas* list);
 182
 183
 184 /*
 185  * Initialize the scanner data within a `Deltas_Context' object.
 186  * `font->delta_buf' is the delta exceptions buffer to be parsed,
 187  * `font->delta_len' its length.
 188  *
 189  * This function is defined in `tadeltas.l'.
 190  */
 191
 192 void
 193 TA_deltas_scanner_init(Deltas_Context* context,
 194                        FONT* font);
 195
 196
 197 /*
 198  * Free the scanner data within a `Deltas_Context' object.
 199  *
 200  * This function is defined in `tadeltas.l'.
 201  */
 202
 203 void
 204 TA_deltas_scanner_done(Deltas_Context* context);
 205
 206
 207 /*
 208  * Parse buffer with descriptions of delta exceptions, stored in
 209  * `font->deltas_buf' with length `font->deltas_len'.
 210  *
 211  * The format of lines in such a delta exceptions buffer is given in
 212  * `ttfautohint.h' (option `deltas-file'); the following describes more
 213  * technical details, using the constants defined above.
 214  *
 215  * x shift and y shift values represent floating point numbers that get
 216  * rounded to multiples of 1/(2^DELTA_SHIFT) pixels.
 217  *
 218  * Values for x and y shifts must be in the range
 219  * [DELTA_SHIFT_MIN;DELTA_SHIFT_MAX].  Values for ppems must be in the range
 220  * [DELTA_PPEM_MIN;DELTA_PPEM_MAX].
 221  *
 222  * The returned error codes are 0 (TA_Err_Ok) or in the range 0x200-0x2FF;
 223  * see `ttfautohint-errors.h' for all possible values.
 224  *
 225  * `TA_deltas_parse_buffer' stores the parsed result in `font->deltas', to
 226  * be freed with `TA_deltas_free' after use.  If there is no delta
 227  * exceptions data (for example, an empty string or whitespace only) nothing
 228  * gets allocated, and `font->deltas' is set to NULL.
 229  *
 230  * In case of error, `error_string_p' holds an error message, `errlinenum_p'
 231  * gives the line number in the delta exceptions buffer where the error
 232  * occurred, `errline_p' the corresponding line, and `errpos_p' the position
 233  * in this line.  After use, `error_string_p' and `errline_p' must be
 234  * deallocated by the user.  Note that `errline_p' and `errpos_p' can be
 235  * NULL even in case of an error.  If there is no error, those four values
 236  * are undefined.
 237  */
 238
 239 TA_Error
 240 TA_deltas_parse_buffer(FONT* font,
 241                        char** error_string_p,
 242                        unsigned int* errlinenum_p,
 243                        char** errline_p,
 244                        char** errpos_p);
 245
 246
 247 /*
 248  * Free the allocated data in `deltas'.
 249  */
 250
 251 void
 252 TA_deltas_free(Deltas* deltas);
 253
 254
 255 /*
 256  * Return a string representation of `font->deltas'.  After use, the string
 257  * should be deallocated with a call to `free'.  In case of an allocation
 258  * error, the return value is NULL.
 259  */
 260
 261 char*
 262 TA_deltas_show(FONT* font);
 263
 264
 265 /*
 266  * Build a tree providing sequential access to the delta exceptions data in
 267  * `font->deltas'.  This also sets `font->deltas_data_cur' to the first
 268  * element (or NULL if there isn't one).
 269  */
 270
 271 TA_Error
 272 TA_deltas_build_tree(FONT* font);
 273
 274
 275 /*
 276  * Free the delta exceptions data tree.
 277  */
 278
 279 void
 280 TA_deltas_free_tree(FONT* font);
 281
 282
 283 /*
 284  * Get next delta exception and store it in `font->deltas_data_cur'.
 285  */
 286
 287 void
 288 TA_deltas_get_next(FONT* font);
 289
 290
 291 /*
 292  * Access delta exception.  Return NULL if there is no more data.
 293  */
 294 const Delta*
 295 TA_deltas_get_delta(FONT* font);
 296
 297 #ifdef __cplusplus
 298 } /* extern "C" */
 299 #endif
 300
 301 #endif /* __DELTAS_H__ */
 302
 303 /* end of deltas.h */