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
  32 /*
  33  * A structure to hold delta exceptions for a glyph.  It gets allocated by a
  34  * successful call to `ta_deltas_parse'.  Use `ta_deltas_free' to deallocate
  35  * it.
  36  */
  37
  38 typedef struct Deltas_
  39 {
  40   long font_idx;
  41   long glyph_idx;
  42   number_range* points;
  43   double x_shift;
  44   double y_shift;
  45   number_range* ppems;
  46 } Deltas;
  47
  48
  49 /*
  50  * Parse a delta exceptions description in string `s', which has the
  51  * following syntax:
  52  *
  53  *   [<font idx>] <glyph name> p <points> [x <x shift>] [y <y shift>] @ <ppems>
  54  *
  55  * <font idx> gives the index of the font in a TrueType Collection.  If
  56  * missing, it is set to zero.  For normal TrueType fonts, only value zero
  57  * is valid.  If starting with `0x' the number is interpreted as
  58  * hexadecimal.  If starting with `0' it gets interpreted as an octal value,
  59  * and as a decimal value otherwise.
  60  *
  61  * <glyph name> is a glyph's name as listed in the `post' SFNT table.
  62  *
  63  * A glyph name consists of characters from the set `A-Za-z0-9._' only and
  64  * does not start with a digit or period, with the exceptions of the names
  65  * `.notdef' and `.null'.  Alternatively, it might be a number (in decimal,
  66  * octal, or hexadecimal format, the latter two indicated by the prefixes
  67  * `0' and `0x', respectively) to directly specify the glyph index.
  68  *
  69  * Both <points> and <ppems> are number ranges as described in
  70  * `numberset.h'.  Point values are limited by the glyph's number of points;
  71  * ppem values are limited by `ppem_min' and `ppem_max'; those parameters
  72  * are passed to `number_set_parse'.
  73  *
  74  * <x shift> and <y shift> represent floating point numbers.  The entries
  75  * for `x' and `y' are optional; if missing, the corresponding value is set
  76  * to zero.
  77  *
  78  * A comment starts with character `#'; the rest of the line is ignored.
  79  *
  80  * In case of success (this is, the delta exceptions description in `s' is
  81  * valid) the return value is a pointer to the final zero byte in string
  82  * `s'.  In case of an error, the return value is a pointer to the beginning
  83  * position of the offending character in string `s'.
  84  *
  85  * If s is NULL, the function exits immediately with NULL as the return
  86  * value.
  87  *
  88  * If the user provides a non-NULL `deltas' value, `ta_deltas_parse' stores
  89  * the parsed result in `*deltas', allocated with `malloc'.  If there is no
  90  * data (for example, an empty string or whitespace only) nothing gets
  91  * allocated, and `*deltas' is set to NULL.  In case of error, `*deltas'
  92  * returns an error code; you should use the following macros to compare
  93  * with.
  94  *
  95  * Values for <x shift>, <y shift>, and <ppems> must be in the ranges given
  96  * by `x_min' and `x_max', `y_min' and `y_max', and `ppem_min' and
  97  * `ppem_max', respectively.  Values for <points> are limited by the number
  98  * of points in the glyph.
  99  *
 100  * In case of error, `*deltas' returns an error code; you should use the
 101  * following macros definitions to compare with.
 102  *
 103  *   TA_DELTAS_SYNTAX_ERROR
 104  *     the function cannot parse the delta exceptions description string
 105  *   TA_DELTAS_INVALID_FONT_INDEX
 106  *     the specified font index in a TTC doesn't exist
 107  *   TA_DELTAS_INVALID_GLYPH_INDEX
 108  *     the glyph index is not present in the font or subfont
 109  *   TA_DELTAS_INVALID_GLYPH_NAME
 110  *     the glyph name is invalid or not present in the font or subfont
 111  *   TA_DELTAS_INVALID_CHARACTER
 112  *     invalid character in delta exceptions description string
 113  *   TA_DELTAS_INVALID_X_RANGE
 114  *     invalid range for the x shift, exceeding `x_min' or `x_max'
 115  *   TA_DELTAS_INVALID_Y_RANGE
 116  *     invalid range for the y shift, exceeding `y_min' or `y_max'
 117  *   TA_DELTAS_INVALID_POINT_RANGE
 118  *     invalid range for points, exceeding the number of glyph points
 119  *   TA_DELTAS_INVALID_PPEM_RANGE
 120  *     invalid range for ppems, exceeding `ppem_min' or `ppem_max'
 121  *   TA_DELTAS_OVERLAPPING_RANGES
 122  *     overlapping point or ppem ranges
 123  *   TA_DELTAS_NOT_ASCENDING
 124  *     not ascending point or ppem ranges or values
 125  *   TA_DELTAS_ALLOCATION_ERROR
 126  *     allocation error
 127  */
 128
 129 #define TA_DELTAS_SYNTAX_ERROR (Deltas*)-1
 130 #define TA_DELTAS_INVALID_FONT_INDEX (Deltas*)-2
 131 #define TA_DELTAS_INVALID_GLYPH_INDEX (Deltas*)-3
 132 #define TA_DELTAS_INVALID_GLYPH_NAME (Deltas*)-4
 133 #define TA_DELTAS_INVALID_CHARACTER (Deltas*)-5
 134 #define TA_DELTAS_INVALID_X_RANGE (Deltas*)-6
 135 #define TA_DELTAS_INVALID_Y_RANGE (Deltas*)-7
 136 #define TA_DELTAS_INVALID_POINT_RANGE (Deltas*)-8
 137 #define TA_DELTAS_INVALID_GLYPH (Deltas*)-9
 138 #define TA_DELTAS_INVALID_PPEM_RANGE (Deltas*)-10
 139 #define TA_DELTAS_OVERFLOW (Deltas*)-11
 140 #define TA_DELTAS_OVERLAPPING_RANGES (Deltas*)-12
 141 #define TA_DELTAS_NOT_ASCENDING (Deltas*)-13
 142 #define TA_DELTAS_ALLOCATION_ERROR (Deltas*)-14
 143
 144 const char*
 145 TA_deltas_parse(FONT* font,
 146                 const char* s,
 147                 Deltas** deltas,
 148                 int x_min, int x_max,
 149                 int y_min, int y_max,
 150                 int ppem_min, int ppem_max);
 151
 152
 153 /*
 154  * Free the allocated data in `deltas'.
 155  */
 156
 157 void
 158 TA_deltas_free(Deltas* deltas);
 159
 160 #ifdef __cplusplus
 161 } /* extern "C" */
 162 #endif
 163
 164 #endif /* __DELTAS_H__ */
 165
 166 /* end of deltas.h */