docs/reference/ft2-cff_driver.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2 "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6 <title>FreeType-2.8 API Reference</title>
   7 <style type="text/css">
   8   a:link { color: #0000EF; }
   9   a:visited { color: #51188E; }
  10   a:hover { color: #FF0000; }
  11
  12   body { font-family: Verdana, Geneva, Arial, Helvetica, serif;
  13          color: #000000;
  14          background: #FFFFFF;
  15          width: 87%;
  16          margin: auto; }
  17
  18   div.section { width: 75%;
  19                 margin: auto; }
  20   div.section hr { margin: 4ex 0 1ex 0; }
  21   div.section h4 { background-color: #EEEEFF;
  22                    font-size: medium;
  23                    font-style: oblique;
  24                    font-weight: bold;
  25                    margin: 3ex 0 1.5ex 9%;
  26                    padding: 0.3ex 0 0.3ex 1%; }
  27   div.section p { margin: 1.5ex 0 1.5ex 10%; }
  28   div.section pre { margin: 3ex 0 3ex 9%;
  29                     background-color: #D6E8FF;
  30                     padding: 2ex 0 2ex 1%; }
  31   div.section table.fields { width: 90%;
  32                              margin: 1.5ex 0 1.5ex 10%; }
  33   div.section table.toc { width: 95%;
  34                           margin: 1.5ex 0 1.5ex 5%; }
  35   div.timestamp { text-align: center;
  36                   font-size: 69%;
  37                   margin: 1.5ex 0 1.5ex 0; }
  38
  39   h1 { text-align: center; }
  40   h3 { font-size: medium;
  41        margin: 4ex 0 1.5ex 0; }
  42
  43   p { text-align: justify; }
  44
  45   pre.colored { color: blue; }
  46
  47   span.keyword { font-family: monospace;
  48                  text-align: left;
  49                  white-space: pre;
  50                  color: darkblue; }
  51
  52   table.fields td.val { font-weight: bold;
  53                         text-align: right;
  54                         width: 30%;
  55                         vertical-align: baseline;
  56                         padding: 1ex 1em 1ex 0; }
  57   table.fields td.desc { vertical-align: baseline;
  58                          padding: 1ex 0 1ex 1em; }
  59   table.fields td.desc p:first-child { margin: 0; }
  60   table.fields td.desc p { margin: 1.5ex 0 0 0; }
  61   table.index { margin: 6ex auto 6ex auto;
  62                 border: 0;
  63                 border-collapse: separate;
  64                 border-spacing: 1em 0.3ex; }
  65   table.index tr { padding: 0; }
  66   table.index td { padding: 0; }
  67   table.index-toc-link { width: 100%;
  68                          border: 0;
  69                          border-spacing: 0;
  70                          margin: 1ex 0 1ex 0; }
  71   table.index-toc-link td.left { padding: 0 0.5em 0 0.5em;
  72                                  font-size: 83%;
  73                                  text-align: left; }
  74   table.index-toc-link td.middle { padding: 0 0.5em 0 0.5em;
  75                                    font-size: 83%;
  76                                    text-align: center; }
  77   table.index-toc-link td.right { padding: 0 0.5em 0 0.5em;
  78                                   font-size: 83%;
  79                                   text-align: right; }
  80   table.synopsis { margin: 6ex auto 6ex auto;
  81                    border: 0;
  82                    border-collapse: separate;
  83                    border-spacing: 2em 0.6ex; }
  84   table.synopsis tr { padding: 0; }
  85   table.synopsis td { padding: 0; }
  86   table.toc td.link { width: 30%;
  87                       text-align: right;
  88                       vertical-align: baseline;
  89                       padding: 1ex 1em 1ex 0; }
  90   table.toc td.desc { vertical-align: baseline;
  91                       padding: 1ex 0 1ex 1em;
  92                       text-align: left; }
  93   table.toc td.desc p:first-child { margin: 0;
  94                                     text-align: left; }
  95   table.toc td.desc p { margin: 1.5ex 0 0 0;
  96                         text-align: left; }
  97
  98 </style>
  99 </head>
 100 <body>
 101
 102 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table>
 103 <h1>FreeType-2.8 API Reference</h1>
 104
 105 <h1 id="cff_driver">The CFF driver</h1>
 106 <h2>Synopsis</h2>
 107 <table class="synopsis">
 108 <tr><td><a href="#hinting-engine(cff)">hinting-engine</a></td><td>&nbsp;</td></tr>
 109 <tr><td><a href="#no-stem-darkening(cff)">no-stem-darkening</a></td><td><a href="#FT_CFF_HINTING_XXX">FT_CFF_HINTING_XXX</a></td></tr>
 110 <tr><td><a href="#darkening-parameters(cff)">darkening-parameters</a></td><td><a href="#FT_PARAM_TAG_RANDOM_SEED">FT_PARAM_TAG_RANDOM_SEED</a></td></tr>
 111 <tr><td><a href="#random-seed">random-seed</a></td><td></td></tr>
 112 </table>
 113
 114
 115 <p>While FreeType's CFF driver doesn't expose API functions by itself, it is possible to control its behaviour with <a href="ft2-module_management.html#FT_Property_Set">FT_Property_Set</a> and <a href="ft2-module_management.html#FT_Property_Get">FT_Property_Get</a>. The list below gives the available properties together with the necessary macros and structures.</p>
 116 <p>The CFF driver's module name is &lsquo;cff&rsquo;.</p>
 117 <p><b>Hinting</b> <b>and</b> <b>antialiasing</b> <b>principles</b> <b>of</b> <b>the</b> <b>new</b> <b>engine</b></p>
 118 <p>The rasterizer is positioning horizontal features (e.g., ascender height &amp; x-height, or crossbars) on the pixel grid and minimizing the amount of antialiasing applied to them, while placing vertical features (vertical stems) on the pixel grid without hinting, thus representing the stem position and weight accurately. Sometimes the vertical stems may be only partially black. In this context, &lsquo;antialiasing&rsquo; means that stems are not positioned exactly on pixel borders, causing a fuzzy appearance.</p>
 119 <p>There are two principles behind this approach.</p>
 120 <p>1) No hinting in the horizontal direction: Unlike &lsquo;superhinted&rsquo; TrueType, which changes glyph widths to accommodate regular inter-glyph spacing, Adobe's approach is &lsquo;faithful to the design&rsquo; in representing both the glyph width and the inter-glyph spacing designed for the font. This makes the screen display as close as it can be to the result one would get with infinite resolution, while preserving what is considered the key characteristics of each glyph. Note that the distances between unhinted and grid-fitted positions at small sizes are comparable to kerning values and thus would be noticeable (and distracting) while reading if hinting were applied.</p>
 121 <p>One of the reasons to not hint horizontally is antialiasing for LCD screens: The pixel geometry of modern displays supplies three vertical sub-pixels as the eye moves horizontally across each visible pixel. On devices where we can be certain this characteristic is present a rasterizer can take advantage of the sub-pixels to add increments of weight. In Western writing systems this turns out to be the more critical direction anyway; the weights and spacing of vertical stems (see above) are central to Armenian, Cyrillic, Greek, and Latin type designs. Even when the rasterizer uses greyscale antialiasing instead of color (a necessary compromise when one doesn't know the screen characteristics), the unhinted vertical features preserve the design's weight and spacing much better than aliased type would.</p>
 122 <p>2) Alignment in the vertical direction: Weights and spacing along the y&nbsp;axis are less critical; what is much more important is the visual alignment of related features (like cap-height and x-height). The sense of alignment for these is enhanced by the sharpness of grid-fit edges, while the cruder vertical resolution (full pixels instead of 1/3 pixels) is less of a problem.</p>
 123 <p>On the technical side, horizontal alignment zones for ascender, x-height, and other important height values (traditionally called &lsquo;blue zones&rsquo;) as defined in the font are positioned independently, each being rounded to the nearest pixel edge, taking care of overshoot suppression at small sizes, stem darkening, and scaling.</p>
 124 <p>Hstems (this is, hint values defined in the font to help align horizontal features) that fall within a blue zone are said to be &lsquo;captured&rsquo; and are aligned to that zone. Uncaptured stems are moved in one of four ways, top edge up or down, bottom edge up or down. Unless there are conflicting hstems, the smallest movement is taken to minimize distortion.</p>
 125
 126 <div class="section">
 127 <h3 id="hinting-engine(cff)">hinting-engine</h3>
 128
 129 <p>Thanks to Adobe, which contributed a new hinting (and parsing) engine, an application can select between &lsquo;freetype&rsquo; and &lsquo;adobe&rsquo; if compiled with CFF_CONFIG_OPTION_OLD_ENGINE. If this configuration macro isn't defined, &lsquo;hinting-engine&rsquo; does nothing.</p>
 130 <p>The default engine is &lsquo;freetype&rsquo; if CFF_CONFIG_OPTION_OLD_ENGINE is defined, and &lsquo;adobe&rsquo; otherwise.</p>
 131 <p>The following example code demonstrates how to select Adobe's hinting engine (omitting the error handling).</p>
 132 <pre class="colored">
 133   FT_Library  library;
 134   FT_UInt     hinting_engine = FT_CFF_HINTING_ADOBE;
 135
 136
 137   FT_Init_FreeType( &amp;library );
 138
 139   FT_Property_Set( library, "cff",
 140                             "hinting-engine", &amp;hinting_engine );
 141 </pre>
 142
 143 <h4>note</h4>
 144 <p>This property can be used with <a href="ft2-module_management.html#FT_Property_Get">FT_Property_Get</a> also.</p>
 145 <p>This property can be set via the &lsquo;FREETYPE_PROPERTIES&rsquo; environment variable (using values &lsquo;adobe&rsquo; or &lsquo;freetype&rsquo;).</p>
 146
 147 <hr>
 148 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 149
 150 <div class="section">
 151 <h3 id="no-stem-darkening(cff)">no-stem-darkening</h3>
 152
 153 <p>By default, the Adobe CFF engine darkens stems at smaller sizes, regardless of hinting, to enhance contrast. This feature requires a rendering system with proper gamma correction. Setting this property, stem darkening gets switched off.</p>
 154 <p>Note that stem darkening is never applied if <a href="ft2-base_interface.html#FT_LOAD_XXX">FT_LOAD_NO_SCALE</a> is set.</p>
 155 <pre class="colored">
 156   FT_Library  library;
 157   FT_Bool     no_stem_darkening = TRUE;
 158
 159
 160   FT_Init_FreeType( &amp;library );
 161
 162   FT_Property_Set( library, "cff",
 163                             "no-stem-darkening", &amp;no_stem_darkening );
 164 </pre>
 165
 166 <h4>note</h4>
 167 <p>This property can be used with <a href="ft2-module_management.html#FT_Property_Get">FT_Property_Get</a> also.</p>
 168 <p>This property can be set via the &lsquo;FREETYPE_PROPERTIES&rsquo; environment variable (using values 1 and 0 for &lsquo;on&rsquo; and &lsquo;off&rsquo;, respectively). It can also be set per face using <a href="ft2-base_interface.html#FT_Face_Properties">FT_Face_Properties</a> with <a href="ft2-auto_hinter.html#FT_PARAM_TAG_STEM_DARKENING">FT_PARAM_TAG_STEM_DARKENING</a>.</p>
 169
 170 <hr>
 171 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 172
 173 <div class="section">
 174 <h3 id="darkening-parameters(cff)">darkening-parameters</h3>
 175
 176 <p>By default, the Adobe CFF engine darkens stems as follows (if the &lsquo;no-stem-darkening&rsquo; property isn't set):</p>
 177 <pre class="colored">
 178   stem width &lt;= 0.5px:   darkening amount = 0.4px
 179   stem width  = 1px:     darkening amount = 0.275px
 180   stem width  = 1.667px: darkening amount = 0.275px
 181   stem width &gt;= 2.333px: darkening amount = 0px
 182 </pre>
 183 <p>and piecewise linear in-between. At configuration time, these four control points can be set with the macro &lsquo;CFF_CONFIG_OPTION_DARKENING_PARAMETERS&rsquo;. At runtime, the control points can be changed using the &lsquo;darkening-parameters&rsquo; property, as the following example demonstrates.</p>
 184 <pre class="colored">
 185   FT_Library  library;
 186   FT_Int      darken_params[8] = {  500, 300,   // x1, y1
 187                                    1000, 200,   // x2, y2
 188                                    1500, 100,   // x3, y3
 189                                    2000,   0 }; // x4, y4
 190
 191
 192   FT_Init_FreeType( &amp;library );
 193
 194   FT_Property_Set( library, "cff",
 195                             "darkening-parameters", darken_params );
 196 </pre>
 197 <p>The x&nbsp;values give the stem width, and the y&nbsp;values the darkening amount. The unit is 1000th of pixels. All coordinate values must be positive; the x&nbsp;values must be monotonically increasing; the y&nbsp;values must be monotonically decreasing and smaller than or equal to 500 (corresponding to half a pixel); the slope of each linear piece must be shallower than -1 (e.g., -.4).</p>
 198
 199 <h4>note</h4>
 200 <p>This property can be used with <a href="ft2-module_management.html#FT_Property_Get">FT_Property_Get</a> also.</p>
 201 <p>This property can be set via the &lsquo;FREETYPE_PROPERTIES&rsquo; environment variable, using eight comma-separated integers without spaces. Here the above example, using &lsquo;\&rsquo; to break the line for readability.</p>
 202 <pre class="colored">
 203   FREETYPE_PROPERTIES=\
 204   cff:darkening-parameters=500,300,1000,200,1500,100,2000,0
 205 </pre>
 206
 207 <hr>
 208 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 209
 210 <div class="section">
 211 <h3 id="random-seed">random-seed</h3>
 212
 213 <p>By default, the seed value for the CFF &lsquo;random&rsquo; operator is set to a random value. However, mainly for debugging purposes, it is often necessary to use a known value as a seed so that the pseudo-random number sequences generated by &lsquo;random&rsquo; are repeatable.</p>
 214 <p>The &lsquo;random-seed&rsquo; property does that. Its argument is a signed 32bit integer; if the value is zero or negative, the seed given by the &lsquo;intitialRandomSeed&rsquo; private DICT operator in a CFF file gets used (or a default value if there is no such operator). If the value is positive, use it instead of &lsquo;initialRandomSeed&rsquo;, which is consequently ignored.</p>
 215
 216 <h4>note</h4>
 217 <p>This property can be set via the &lsquo;FREETYPE_PROPERTIES&rsquo; environment variable. It can also be set per face using <a href="ft2-base_interface.html#FT_Face_Properties">FT_Face_Properties</a> with <a href="ft2-cff_driver.html#FT_PARAM_TAG_RANDOM_SEED">FT_PARAM_TAG_RANDOM_SEED</a>.</p>
 218
 219 <hr>
 220 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 221
 222 <div class="section">
 223 <h3 id="FT_CFF_HINTING_XXX">FT_CFF_HINTING_XXX</h3>
 224 <p>Defined in FT_CFF_DRIVER_H (freetype/ftcffdrv.h).</p>
 225 <pre>
 226 #define <a href="ft2-cff_driver.html#FT_CFF_HINTING_FREETYPE">FT_CFF_HINTING_FREETYPE</a>  0
 227 #define <a href="ft2-cff_driver.html#FT_CFF_HINTING_ADOBE">FT_CFF_HINTING_ADOBE</a>     1
 228 </pre>
 229
 230 <p>A list of constants used for the <a href="ft2-cff_driver.html#hinting-engine(cff)">hinting-engine</a> property to select the hinting engine for CFF fonts.</p>
 231
 232 <h4>values</h4>
 233 <table class="fields">
 234 <tr><td class="val" id="FT_CFF_HINTING_FREETYPE">FT_CFF_HINTING_FREETYPE</td><td class="desc">
 235 <p>Use the old FreeType hinting engine.</p>
 236 </td></tr>
 237 <tr><td class="val" id="FT_CFF_HINTING_ADOBE">FT_CFF_HINTING_ADOBE</td><td class="desc">
 238 <p>Use the hinting engine contributed by Adobe.</p>
 239 </td></tr>
 240 </table>
 241
 242 <hr>
 243 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 244
 245 <div class="section">
 246 <h3 id="FT_PARAM_TAG_RANDOM_SEED">FT_PARAM_TAG_RANDOM_SEED</h3>
 247 <p>Defined in FT_CFF_DRIVER_H (freetype/ftcffdrv.h).</p>
 248 <pre>
 249 #define <b>FT_PARAM_TAG_RANDOM_SEED</b> \
 250           <a href="ft2-basic_types.html#FT_MAKE_TAG">FT_MAKE_TAG</a>( 's', 'e', 'e', 'd' )
 251 </pre>
 252
 253 <p>An <a href="ft2-base_interface.html#FT_Parameter">FT_Parameter</a> tag to be used with <a href="ft2-base_interface.html#FT_Face_Properties">FT_Face_Properties</a>. The corresponding 32bit signed integer argument overrides the CFF module's random seed value with a face-specific one; see <a href="ft2-cff_driver.html#random-seed">random-seed</a>.</p>
 254
 255 <hr>
 256 <table class="index-toc-link"><tr><td class="left">[<a href="ft2-index.html">Index</a>]</td><td class="middle">[<a href="#">Top</a>]</td><td class="right">[<a href="ft2-toc.html">TOC</a>]</td></tr></table></div>
 257
 258 </body>
 259 </html>