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  * A structure to hold delta exceptions for a glyph.  It gets allocated by a
  37  * successful call to `TA_deltas_parse'.  Use `TA_deltas_free' to deallocate
  38  * it.
  39  *
  40  * `x_shift' and `y_shift' are always in the range [-8;8].
  41  */
  42
  43 typedef struct Deltas_
  44 {
  45   long font_idx;
  46   long glyph_idx;
  47   number_range* points;
  48   char x_shift;
  49   char y_shift;
  50   number_range* ppems;
  51 } Deltas;
  52
  53
  54 /*
  55  * Parse a delta exceptions description in string `s', which has the
  56  * following syntax:
  57  *
  58  *   [<font idx>] <glyph id> p <points> [x <x shift>] [y <y shift>] @ <ppems>
  59  *
  60  * <font idx> gives the index of the font in a TrueType Collection.  If
  61  * missing, it is set to zero.  For normal TrueType fonts, only value zero
  62  * is valid.  If starting with `0x' the number is interpreted as
  63  * hexadecimal.  If starting with `0' it gets interpreted as an octal value,
  64  * and as a decimal value otherwise.
  65  *
  66  * <glyph id> is a glyph's name as listed in the `post' SFNT table or a
  67  * glyph index.  A glyph name consists of characters from the set
  68  * `A-Za-z0-9._' only and does not start with a digit or period, with the
  69  * exceptions of the names `.notdef' and `.null'.  A glyph index can be
  70  * specified in decimal, octal, or hexadecimal format, the latter two
  71  * indicated by the prefixes `0' and `0x', respectively.
  72  *
  73  * Both <points> and <ppems> are number ranges as described in
  74  * `numberset.h'; they are parsed using `number_set_parse'.
  75  *
  76  * <x shift> and <y shift> represent floating point numbers that get rounded
  77  * to multiples of 1/8 pixels.  The entries for `x' and `y' are optional; if
  78  * missing, the corresponding value is set to zero.
  79  *
  80  * Values for <x shift>, <y shift> must be in the range
  81  * [DELTA_SHIFT_MIN;DELTA_SHIFT_MAX].  Values for <ppems> must be in the
  82  * range given by `ppem_min' and `ppem_max'.  Values for <points> are
  83  * limited by the number of points in the glyph.
  84  *
  85  * A comment starts with character `#'; the rest of the line is ignored.  An
  86  * empty line is ignored also.
  87  *
  88  * In case of success (this is, the delta exceptions description in `s' is
  89  * valid), `pos' is a pointer to the final zero byte in string `s'.  In case
  90  * of an error, it points to the offending character in string `s'.
  91  *
  92  * If s is NULL, the function exits immediately, with NULL as the value of
  93  * `pos'.
  94  *
  95  * If the user provides a non-NULL `deltas' value, `TA_deltas_parse' stores
  96  * the parsed result in `*deltas', allocated with `malloc'.  If there is no
  97  * data (for example, an empty string or whitespace only) nothing gets
  98  * allocated, and `*deltas' is set to NULL.
  99  *
 100  * The returned error codes are in the range 0x200-0x2FF; see
 101  * `ttfautohint-errors.h' for all possible values.
 102  */
 103
 104 TA_Error
 105 TA_deltas_parse(FONT* font,
 106                 const char* s,
 107                 char** err_pos,
 108                 Deltas** deltas,
 109                 int ppem_min, int ppem_max);
 110
 111
 112 /*
 113  * Free the allocated data in `deltas'.
 114  */
 115
 116 void
 117 TA_deltas_free(Deltas* deltas);
 118
 119
 120 /*
 121  * Return a string representation of `deltas'.  After use, the string should
 122  * be deallocated with a call to `free'.  In case of an allocation error,
 123  * the return value is NULL.
 124  */
 125
 126 char*
 127 TA_deltas_show(FONT* font,
 128                Deltas* deltas);
 129
 130 #ifdef __cplusplus
 131 } /* extern "C" */
 132 #endif
 133
 134 #endif /* __DELTAS_H__ */
 135
 136 /* end of deltas.h */