lib/tacontrol.h

   1 /* tacontrol.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 __TACONTROL_H__
  17 #define __TACONTROL_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 CONTROL_DELTA_SHIFT 3 /* 1/8px */
  31 #define CONTROL_DELTA_FACTOR (1 << CONTROL_DELTA_SHIFT)
  32
  33 #define CONTROL_DELTA_SHIFT_MAX ((1.0 / CONTROL_DELTA_FACTOR) * 8)
  34 #define CONTROL_DELTA_SHIFT_MIN -CONTROL_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 CONTROL_DELTA_PPEM_MIN 6
  51 #define CONTROL_DELTA_PPEM_MAX 53
  52
  53
  54 /*
  55  * The control type.
  56  */
  57
  58 typedef enum Control_Type_
  59 {
  60   Control_Delta_before_IUP,
  61   Control_Delta_after_IUP,
  62   Control_One_Point_Segment
  63 } Control_Type;
  64
  65
  66 /*
  67  * A structure to hold control instructions for a glyph.  A linked list of it
  68  * gets allocated by a successful call to `TA_control_parse_buffer'.  Use
  69  * `TA_control_free' to deallocate the list.
  70  *
  71  * `x_shift' and `y_shift' are always in the range [-8;8].
  72  *
  73  * The `Control' typedef is in `ta.h'.
  74  */
  75
  76 struct Control_
  77 {
  78   Control_Type type;
  79
  80   long font_idx;
  81   long glyph_idx;
  82   number_range* points;
  83   char x_shift;
  84   char y_shift;
  85   number_range* ppems;
  86
  87   struct Control_* next;
  88 };
  89
  90
  91 /*
  92  * A structure to hold a single control instruction.
  93  */
  94
  95 typedef struct Ctrl_
  96 {
  97   Control_Type type;
  98
  99   long font_idx;
 100   long glyph_idx;
 101   int ppem;
 102   int point_idx;
 103
 104   char x_shift;
 105   char y_shift;
 106 } Ctrl;
 107
 108
 109 /*
 110  * This structure is used for communication with `TA_control_parse'.
 111  */
 112
 113 typedef struct Control_Context_
 114 {
 115   /* The error code returned by the parser or lexer. */
 116   TA_Error error;
 117
 118   /* If no error, this holds the parsing result. */
 119   Control* result;
 120
 121   /*
 122    * The parser's or lexer's error message in case of error; might be the
 123    * empty string.
 124    */
 125   char errmsg[256];
 126
 127   /*
 128    * In case of error, `errline_num' gives the line number of the offending
 129    * line in `font->control_buf', starting with value 1; `errline_pos_left'
 130    * and `errline_pos_right' hold the left and right position of the
 131    * offending token in this line, also starting with value 1.  For
 132    * allocation errors or internal parser or lexer errors those values are
 133    * meaningless, though.
 134    */
 135   int errline_num;
 136   int errline_pos_left;
 137   int errline_pos_right;
 138
 139   /*
 140    * The current font index, useful for `TA_Err_Control_Invalid_Font_Index'.
 141    */
 142   long font_idx;
 143
 144   /*
 145    * The current glyph index, useful for
 146    * `TA_Err_Control_Invalid_Glyph_Index'.
 147    */
 148   long glyph_idx;
 149
 150   /*
 151    * If the returned error is `TA_Err_Control_Invalid_Range', these two
 152    * values set up the allowed range.
 153    */
 154   long number_set_min;
 155   long number_set_max;
 156
 157   /* private flex data */
 158   void* scanner;
 159   int eof;
 160   jmp_buf jump_buffer;
 161
 162   /* private bison data */
 163   FONT* font;
 164 } Control_Context;
 165
 166
 167 /*
 168  * Create and initialize a `Control' object.  In case of an allocation error,
 169  * the return value is NULL.  `point_set' and `ppem_set' are expected to be
 170  * in reverse list order; `TA_control_new' then reverts them to normal order.
 171  */
 172
 173 Control*
 174 TA_control_new(Control_Type type,
 175                long font_idx,
 176                long glyph_idx,
 177                number_range* point_set,
 178                double x_shift,
 179                double y_shift,
 180                number_range* ppem_set);
 181
 182
 183 /*
 184  * Prepend `element' to `list' of `Control' objects.  If `element' is NULL,
 185  * return `list.
 186  */
 187
 188 Control*
 189 TA_control_prepend(Control* list,
 190                    Control* element);
 191
 192
 193 /*
 194  * Reverse a list of `Control' objects.
 195  */
 196
 197 Control*
 198 TA_control_reverse(Control* list);
 199
 200
 201 /*
 202  * Initialize the scanner data within a `Control_Context' object.
 203  * `font->control_buf' is the control instructions buffer to be parsed,
 204  * `font->control_len' its length.
 205  *
 206  * This function is defined in `tacontrol.flex'.
 207  */
 208
 209 void
 210 TA_control_scanner_init(Control_Context* context,
 211                         FONT* font);
 212
 213
 214 /*
 215  * Free the scanner data within a `Control_Context' object.
 216  *
 217  * This function is defined in `tacontrol.flex'.
 218  */
 219
 220 void
 221 TA_control_scanner_done(Control_Context* context);
 222
 223
 224 /*
 225  * Parse buffer with ttfautohint control instructions, stored in
 226  * `font->control_buf' with length `font->control_len'.
 227  *
 228  * The format of entries in such a control instructions buffer is given in
 229  * `ttfautohint.h' (option `control-file'); the following describes more
 230  * technical details, using the constants defined above.
 231  *
 232  * x shift and y shift values represent floating point numbers that get
 233  * rounded to multiples of 1/(2^CONTROL_DELTA_SHIFT) pixels.
 234  *
 235  * Values for x and y shifts must be in the range
 236  * [CONTROL_DELTA_SHIFT_MIN;CONTROL_DELTA_SHIFT_MAX].  Values for ppems must
 237  * be in the range [CONTROL_DELTA_PPEM_MIN;CONTROL_DELTA_PPEM_MAX].
 238  *
 239  * The returned error codes are 0 (TA_Err_Ok) or in the range 0x200-0x2FF;
 240  * see `ttfautohint-errors.h' for all possible values.
 241  *
 242  * `TA_control_parse_buffer' stores the parsed result in `font->control', to
 243  * be freed with `TA_control_free' after use.  If there is no control
 244  * instructions data (for example, an empty string or whitespace only)
 245  * nothing gets allocated, and `font->control' is set to NULL.
 246  *
 247  * In case of error, `error_string_p' holds an error message, `errlinenum_p'
 248  * gives the line number in the control instructions buffer where the error
 249  * occurred, `errline_p' the corresponding line, and `errpos_p' the position
 250  * in this line.  After use, `error_string_p' and `errline_p' must be
 251  * deallocated by the user.  Note that `errline_p' and `errpos_p' can be
 252  * NULL even in case of an error.  If there is no error, those four values
 253  * are undefined.
 254  */
 255
 256 TA_Error
 257 TA_control_parse_buffer(FONT* font,
 258                         char** error_string_p,
 259                         unsigned int* errlinenum_p,
 260                         char** errline_p,
 261                         char** errpos_p);
 262
 263
 264 /*
 265  * Free the allocated data in `control'.
 266  */
 267
 268 void
 269 TA_control_free(Control* control);
 270
 271
 272 /*
 273  * Return a string representation of `font->control'.  After use, the string
 274  * should be deallocated with a call to `free'.  In case of an allocation
 275  * error, the return value is NULL.
 276  */
 277
 278 char*
 279 TA_control_show(FONT* font);
 280
 281
 282 /*
 283  * Build a tree providing sequential access to the control instructions data
 284  * in `font->control'.  This also sets `font->control_data_cur' to the first
 285  * element (or NULL if there isn't one).
 286  */
 287
 288 TA_Error
 289 TA_control_build_tree(FONT* font);
 290
 291
 292 /*
 293  * Free the control instructions data tree.
 294  */
 295
 296 void
 297 TA_control_free_tree(FONT* font);
 298
 299
 300 /*
 301  * Get next control instruction and store it in `font->control_data_cur'.
 302  */
 303
 304 void
 305 TA_control_get_next(FONT* font);
 306
 307
 308 /*
 309  * Access control instruction.  Return NULL if there is no more data.
 310  */
 311 const Ctrl*
 312 TA_control_get_ctrl(FONT* font);
 313
 314 #ifdef __cplusplus
 315 } /* extern "C" */
 316 #endif
 317
 318 #endif /* __TACONTROL_H__ */
 319
 320 /* end of control.h */