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