1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/modules/freetype2/include/ftoutln.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,572 @@
1.4 +/***************************************************************************/
1.5 +/* */
1.6 +/* ftoutln.h */
1.7 +/* */
1.8 +/* Support for the FT_Outline type used to store glyph shapes of */
1.9 +/* most scalable font formats (specification). */
1.10 +/* */
1.11 +/* Copyright 1996-2003, 2005-2014 by */
1.12 +/* David Turner, Robert Wilhelm, and Werner Lemberg. */
1.13 +/* */
1.14 +/* This file is part of the FreeType project, and may only be used, */
1.15 +/* modified, and distributed under the terms of the FreeType project */
1.16 +/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
1.17 +/* this file you indicate that you have read the license and */
1.18 +/* understand and accept it fully. */
1.19 +/* */
1.20 +/***************************************************************************/
1.21 +
1.22 +
1.23 +#ifndef __FTOUTLN_H__
1.24 +#define __FTOUTLN_H__
1.25 +
1.26 +
1.27 +#include <ft2build.h>
1.28 +#include FT_FREETYPE_H
1.29 +
1.30 +#ifdef FREETYPE_H
1.31 +#error "freetype.h of FreeType 1 has been loaded!"
1.32 +#error "Please fix the directory search order for header files"
1.33 +#error "so that freetype.h of FreeType 2 is found first."
1.34 +#endif
1.35 +
1.36 +
1.37 +FT_BEGIN_HEADER
1.38 +
1.39 +
1.40 + /*************************************************************************/
1.41 + /* */
1.42 + /* <Section> */
1.43 + /* outline_processing */
1.44 + /* */
1.45 + /* <Title> */
1.46 + /* Outline Processing */
1.47 + /* */
1.48 + /* <Abstract> */
1.49 + /* Functions to create, transform, and render vectorial glyph images. */
1.50 + /* */
1.51 + /* <Description> */
1.52 + /* This section contains routines used to create and destroy scalable */
1.53 + /* glyph images known as `outlines'. These can also be measured, */
1.54 + /* transformed, and converted into bitmaps and pixmaps. */
1.55 + /* */
1.56 + /* <Order> */
1.57 + /* FT_Outline */
1.58 + /* FT_OUTLINE_FLAGS */
1.59 + /* FT_Outline_New */
1.60 + /* FT_Outline_Done */
1.61 + /* FT_Outline_Copy */
1.62 + /* FT_Outline_Translate */
1.63 + /* FT_Outline_Transform */
1.64 + /* FT_Outline_Embolden */
1.65 + /* FT_Outline_EmboldenXY */
1.66 + /* FT_Outline_Reverse */
1.67 + /* FT_Outline_Check */
1.68 + /* */
1.69 + /* FT_Outline_Get_CBox */
1.70 + /* FT_Outline_Get_BBox */
1.71 + /* */
1.72 + /* FT_Outline_Get_Bitmap */
1.73 + /* FT_Outline_Render */
1.74 + /* */
1.75 + /* FT_Outline_Decompose */
1.76 + /* FT_Outline_Funcs */
1.77 + /* FT_Outline_MoveTo_Func */
1.78 + /* FT_Outline_LineTo_Func */
1.79 + /* FT_Outline_ConicTo_Func */
1.80 + /* FT_Outline_CubicTo_Func */
1.81 + /* */
1.82 + /*************************************************************************/
1.83 +
1.84 +
1.85 + /*************************************************************************/
1.86 + /* */
1.87 + /* <Function> */
1.88 + /* FT_Outline_Decompose */
1.89 + /* */
1.90 + /* <Description> */
1.91 + /* Walk over an outline's structure to decompose it into individual */
1.92 + /* segments and Bézier arcs. This function also emits `move to' */
1.93 + /* operations to indicate the start of new contours in the outline. */
1.94 + /* */
1.95 + /* <Input> */
1.96 + /* outline :: A pointer to the source target. */
1.97 + /* */
1.98 + /* func_interface :: A table of `emitters', i.e., function pointers */
1.99 + /* called during decomposition to indicate path */
1.100 + /* operations. */
1.101 + /* */
1.102 + /* <InOut> */
1.103 + /* user :: A typeless pointer that is passed to each */
1.104 + /* emitter during the decomposition. It can be */
1.105 + /* used to store the state during the */
1.106 + /* decomposition. */
1.107 + /* */
1.108 + /* <Return> */
1.109 + /* FreeType error code. 0~means success. */
1.110 + /* */
1.111 + /* <Note> */
1.112 + /* A contour that contains a single point only is represented by a */
1.113 + /* `move to' operation followed by `line to' to the same point. In */
1.114 + /* most cases, it is best to filter this out before using the */
1.115 + /* outline for stroking purposes (otherwise it would result in a */
1.116 + /* visible dot when round caps are used). */
1.117 + /* */
1.118 + FT_EXPORT( FT_Error )
1.119 + FT_Outline_Decompose( FT_Outline* outline,
1.120 + const FT_Outline_Funcs* func_interface,
1.121 + void* user );
1.122 +
1.123 +
1.124 + /*************************************************************************/
1.125 + /* */
1.126 + /* <Function> */
1.127 + /* FT_Outline_New */
1.128 + /* */
1.129 + /* <Description> */
1.130 + /* Create a new outline of a given size. */
1.131 + /* */
1.132 + /* <Input> */
1.133 + /* library :: A handle to the library object from where the */
1.134 + /* outline is allocated. Note however that the new */
1.135 + /* outline will *not* necessarily be *freed*, when */
1.136 + /* destroying the library, by @FT_Done_FreeType. */
1.137 + /* */
1.138 + /* numPoints :: The maximum number of points within the outline. */
1.139 + /* Must be smaller than or equal to 0xFFFF (65535). */
1.140 + /* */
1.141 + /* numContours :: The maximum number of contours within the outline. */
1.142 + /* This value must be in the range 0 to `numPoints'. */
1.143 + /* */
1.144 + /* <Output> */
1.145 + /* anoutline :: A handle to the new outline. */
1.146 + /* */
1.147 + /* <Return> */
1.148 + /* FreeType error code. 0~means success. */
1.149 + /* */
1.150 + /* <Note> */
1.151 + /* The reason why this function takes a `library' parameter is simply */
1.152 + /* to use the library's memory allocator. */
1.153 + /* */
1.154 + FT_EXPORT( FT_Error )
1.155 + FT_Outline_New( FT_Library library,
1.156 + FT_UInt numPoints,
1.157 + FT_Int numContours,
1.158 + FT_Outline *anoutline );
1.159 +
1.160 +
1.161 + FT_EXPORT( FT_Error )
1.162 + FT_Outline_New_Internal( FT_Memory memory,
1.163 + FT_UInt numPoints,
1.164 + FT_Int numContours,
1.165 + FT_Outline *anoutline );
1.166 +
1.167 +
1.168 + /*************************************************************************/
1.169 + /* */
1.170 + /* <Function> */
1.171 + /* FT_Outline_Done */
1.172 + /* */
1.173 + /* <Description> */
1.174 + /* Destroy an outline created with @FT_Outline_New. */
1.175 + /* */
1.176 + /* <Input> */
1.177 + /* library :: A handle of the library object used to allocate the */
1.178 + /* outline. */
1.179 + /* */
1.180 + /* outline :: A pointer to the outline object to be discarded. */
1.181 + /* */
1.182 + /* <Return> */
1.183 + /* FreeType error code. 0~means success. */
1.184 + /* */
1.185 + /* <Note> */
1.186 + /* If the outline's `owner' field is not set, only the outline */
1.187 + /* descriptor will be released. */
1.188 + /* */
1.189 + /* The reason why this function takes an `library' parameter is */
1.190 + /* simply to use ft_mem_free(). */
1.191 + /* */
1.192 + FT_EXPORT( FT_Error )
1.193 + FT_Outline_Done( FT_Library library,
1.194 + FT_Outline* outline );
1.195 +
1.196 +
1.197 + FT_EXPORT( FT_Error )
1.198 + FT_Outline_Done_Internal( FT_Memory memory,
1.199 + FT_Outline* outline );
1.200 +
1.201 +
1.202 + /*************************************************************************/
1.203 + /* */
1.204 + /* <Function> */
1.205 + /* FT_Outline_Check */
1.206 + /* */
1.207 + /* <Description> */
1.208 + /* Check the contents of an outline descriptor. */
1.209 + /* */
1.210 + /* <Input> */
1.211 + /* outline :: A handle to a source outline. */
1.212 + /* */
1.213 + /* <Return> */
1.214 + /* FreeType error code. 0~means success. */
1.215 + /* */
1.216 + FT_EXPORT( FT_Error )
1.217 + FT_Outline_Check( FT_Outline* outline );
1.218 +
1.219 +
1.220 + /*************************************************************************/
1.221 + /* */
1.222 + /* <Function> */
1.223 + /* FT_Outline_Get_CBox */
1.224 + /* */
1.225 + /* <Description> */
1.226 + /* Return an outline's `control box'. The control box encloses all */
1.227 + /* the outline's points, including Bézier control points. Though it */
1.228 + /* coincides with the exact bounding box for most glyphs, it can be */
1.229 + /* slightly larger in some situations (like when rotating an outline */
1.230 + /* that contains Bézier outside arcs). */
1.231 + /* */
1.232 + /* Computing the control box is very fast, while getting the bounding */
1.233 + /* box can take much more time as it needs to walk over all segments */
1.234 + /* and arcs in the outline. To get the latter, you can use the */
1.235 + /* `ftbbox' component, which is dedicated to this single task. */
1.236 + /* */
1.237 + /* <Input> */
1.238 + /* outline :: A pointer to the source outline descriptor. */
1.239 + /* */
1.240 + /* <Output> */
1.241 + /* acbox :: The outline's control box. */
1.242 + /* */
1.243 + /* <Note> */
1.244 + /* See @FT_Glyph_Get_CBox for a discussion of tricky fonts. */
1.245 + /* */
1.246 + FT_EXPORT( void )
1.247 + FT_Outline_Get_CBox( const FT_Outline* outline,
1.248 + FT_BBox *acbox );
1.249 +
1.250 +
1.251 + /*************************************************************************/
1.252 + /* */
1.253 + /* <Function> */
1.254 + /* FT_Outline_Translate */
1.255 + /* */
1.256 + /* <Description> */
1.257 + /* Apply a simple translation to the points of an outline. */
1.258 + /* */
1.259 + /* <InOut> */
1.260 + /* outline :: A pointer to the target outline descriptor. */
1.261 + /* */
1.262 + /* <Input> */
1.263 + /* xOffset :: The horizontal offset. */
1.264 + /* */
1.265 + /* yOffset :: The vertical offset. */
1.266 + /* */
1.267 + FT_EXPORT( void )
1.268 + FT_Outline_Translate( const FT_Outline* outline,
1.269 + FT_Pos xOffset,
1.270 + FT_Pos yOffset );
1.271 +
1.272 +
1.273 + /*************************************************************************/
1.274 + /* */
1.275 + /* <Function> */
1.276 + /* FT_Outline_Copy */
1.277 + /* */
1.278 + /* <Description> */
1.279 + /* Copy an outline into another one. Both objects must have the */
1.280 + /* same sizes (number of points & number of contours) when this */
1.281 + /* function is called. */
1.282 + /* */
1.283 + /* <Input> */
1.284 + /* source :: A handle to the source outline. */
1.285 + /* */
1.286 + /* <Output> */
1.287 + /* target :: A handle to the target outline. */
1.288 + /* */
1.289 + /* <Return> */
1.290 + /* FreeType error code. 0~means success. */
1.291 + /* */
1.292 + FT_EXPORT( FT_Error )
1.293 + FT_Outline_Copy( const FT_Outline* source,
1.294 + FT_Outline *target );
1.295 +
1.296 +
1.297 + /*************************************************************************/
1.298 + /* */
1.299 + /* <Function> */
1.300 + /* FT_Outline_Transform */
1.301 + /* */
1.302 + /* <Description> */
1.303 + /* Apply a simple 2x2 matrix to all of an outline's points. Useful */
1.304 + /* for applying rotations, slanting, flipping, etc. */
1.305 + /* */
1.306 + /* <InOut> */
1.307 + /* outline :: A pointer to the target outline descriptor. */
1.308 + /* */
1.309 + /* <Input> */
1.310 + /* matrix :: A pointer to the transformation matrix. */
1.311 + /* */
1.312 + /* <Note> */
1.313 + /* You can use @FT_Outline_Translate if you need to translate the */
1.314 + /* outline's points. */
1.315 + /* */
1.316 + FT_EXPORT( void )
1.317 + FT_Outline_Transform( const FT_Outline* outline,
1.318 + const FT_Matrix* matrix );
1.319 +
1.320 +
1.321 + /*************************************************************************/
1.322 + /* */
1.323 + /* <Function> */
1.324 + /* FT_Outline_Embolden */
1.325 + /* */
1.326 + /* <Description> */
1.327 + /* Embolden an outline. The new outline will be at most 4~times */
1.328 + /* `strength' pixels wider and higher. You may think of the left and */
1.329 + /* bottom borders as unchanged. */
1.330 + /* */
1.331 + /* Negative `strength' values to reduce the outline thickness are */
1.332 + /* possible also. */
1.333 + /* */
1.334 + /* <InOut> */
1.335 + /* outline :: A handle to the target outline. */
1.336 + /* */
1.337 + /* <Input> */
1.338 + /* strength :: How strong the glyph is emboldened. Expressed in */
1.339 + /* 26.6 pixel format. */
1.340 + /* */
1.341 + /* <Return> */
1.342 + /* FreeType error code. 0~means success. */
1.343 + /* */
1.344 + /* <Note> */
1.345 + /* The used algorithm to increase or decrease the thickness of the */
1.346 + /* glyph doesn't change the number of points; this means that certain */
1.347 + /* situations like acute angles or intersections are sometimes */
1.348 + /* handled incorrectly. */
1.349 + /* */
1.350 + /* If you need `better' metrics values you should call */
1.351 + /* @FT_Outline_Get_CBox or @FT_Outline_Get_BBox. */
1.352 + /* */
1.353 + /* Example call: */
1.354 + /* */
1.355 + /* { */
1.356 + /* FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); */
1.357 + /* if ( face->slot->format == FT_GLYPH_FORMAT_OUTLINE ) */
1.358 + /* FT_Outline_Embolden( &face->slot->outline, strength ); */
1.359 + /* } */
1.360 + /* */
1.361 + /* To get meaningful results, font scaling values must be set with */
1.362 + /* functions like @FT_Set_Char_Size before calling FT_Render_Glyph. */
1.363 + /* */
1.364 + FT_EXPORT( FT_Error )
1.365 + FT_Outline_Embolden( FT_Outline* outline,
1.366 + FT_Pos strength );
1.367 +
1.368 +
1.369 + /*************************************************************************/
1.370 + /* */
1.371 + /* <Function> */
1.372 + /* FT_Outline_EmboldenXY */
1.373 + /* */
1.374 + /* <Description> */
1.375 + /* Embolden an outline. The new outline will be `xstrength' pixels */
1.376 + /* wider and `ystrength' pixels higher. Otherwise, it is similar to */
1.377 + /* @FT_Outline_Embolden, which uses the same strength in both */
1.378 + /* directions. */
1.379 + /* */
1.380 + FT_EXPORT( FT_Error )
1.381 + FT_Outline_EmboldenXY( FT_Outline* outline,
1.382 + FT_Pos xstrength,
1.383 + FT_Pos ystrength );
1.384 +
1.385 +
1.386 + /*************************************************************************/
1.387 + /* */
1.388 + /* <Function> */
1.389 + /* FT_Outline_Reverse */
1.390 + /* */
1.391 + /* <Description> */
1.392 + /* Reverse the drawing direction of an outline. This is used to */
1.393 + /* ensure consistent fill conventions for mirrored glyphs. */
1.394 + /* */
1.395 + /* <InOut> */
1.396 + /* outline :: A pointer to the target outline descriptor. */
1.397 + /* */
1.398 + /* <Note> */
1.399 + /* This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in */
1.400 + /* the outline's `flags' field. */
1.401 + /* */
1.402 + /* It shouldn't be used by a normal client application, unless it */
1.403 + /* knows what it is doing. */
1.404 + /* */
1.405 + FT_EXPORT( void )
1.406 + FT_Outline_Reverse( FT_Outline* outline );
1.407 +
1.408 +
1.409 + /*************************************************************************/
1.410 + /* */
1.411 + /* <Function> */
1.412 + /* FT_Outline_Get_Bitmap */
1.413 + /* */
1.414 + /* <Description> */
1.415 + /* Render an outline within a bitmap. The outline's image is simply */
1.416 + /* OR-ed to the target bitmap. */
1.417 + /* */
1.418 + /* <Input> */
1.419 + /* library :: A handle to a FreeType library object. */
1.420 + /* */
1.421 + /* outline :: A pointer to the source outline descriptor. */
1.422 + /* */
1.423 + /* <InOut> */
1.424 + /* abitmap :: A pointer to the target bitmap descriptor. */
1.425 + /* */
1.426 + /* <Return> */
1.427 + /* FreeType error code. 0~means success. */
1.428 + /* */
1.429 + /* <Note> */
1.430 + /* This function does NOT CREATE the bitmap, it only renders an */
1.431 + /* outline image within the one you pass to it! Consequently, the */
1.432 + /* various fields in `abitmap' should be set accordingly. */
1.433 + /* */
1.434 + /* It will use the raster corresponding to the default glyph format. */
1.435 + /* */
1.436 + /* The value of the `num_grays' field in `abitmap' is ignored. If */
1.437 + /* you select the gray-level rasterizer, and you want less than 256 */
1.438 + /* gray levels, you have to use @FT_Outline_Render directly. */
1.439 + /* */
1.440 + FT_EXPORT( FT_Error )
1.441 + FT_Outline_Get_Bitmap( FT_Library library,
1.442 + FT_Outline* outline,
1.443 + const FT_Bitmap *abitmap );
1.444 +
1.445 +
1.446 + /*************************************************************************/
1.447 + /* */
1.448 + /* <Function> */
1.449 + /* FT_Outline_Render */
1.450 + /* */
1.451 + /* <Description> */
1.452 + /* Render an outline within a bitmap using the current scan-convert. */
1.453 + /* This function uses an @FT_Raster_Params structure as an argument, */
1.454 + /* allowing advanced features like direct composition, translucency, */
1.455 + /* etc. */
1.456 + /* */
1.457 + /* <Input> */
1.458 + /* library :: A handle to a FreeType library object. */
1.459 + /* */
1.460 + /* outline :: A pointer to the source outline descriptor. */
1.461 + /* */
1.462 + /* <InOut> */
1.463 + /* params :: A pointer to an @FT_Raster_Params structure used to */
1.464 + /* describe the rendering operation. */
1.465 + /* */
1.466 + /* <Return> */
1.467 + /* FreeType error code. 0~means success. */
1.468 + /* */
1.469 + /* <Note> */
1.470 + /* You should know what you are doing and how @FT_Raster_Params works */
1.471 + /* to use this function. */
1.472 + /* */
1.473 + /* The field `params.source' will be set to `outline' before the scan */
1.474 + /* converter is called, which means that the value you give to it is */
1.475 + /* actually ignored. */
1.476 + /* */
1.477 + /* The gray-level rasterizer always uses 256 gray levels. If you */
1.478 + /* want less gray levels, you have to provide your own span callback. */
1.479 + /* See the @FT_RASTER_FLAG_DIRECT value of the `flags' field in the */
1.480 + /* @FT_Raster_Params structure for more details. */
1.481 + /* */
1.482 + FT_EXPORT( FT_Error )
1.483 + FT_Outline_Render( FT_Library library,
1.484 + FT_Outline* outline,
1.485 + FT_Raster_Params* params );
1.486 +
1.487 +
1.488 + /**************************************************************************
1.489 + *
1.490 + * @enum:
1.491 + * FT_Orientation
1.492 + *
1.493 + * @description:
1.494 + * A list of values used to describe an outline's contour orientation.
1.495 + *
1.496 + * The TrueType and PostScript specifications use different conventions
1.497 + * to determine whether outline contours should be filled or unfilled.
1.498 + *
1.499 + * @values:
1.500 + * FT_ORIENTATION_TRUETYPE ::
1.501 + * According to the TrueType specification, clockwise contours must
1.502 + * be filled, and counter-clockwise ones must be unfilled.
1.503 + *
1.504 + * FT_ORIENTATION_POSTSCRIPT ::
1.505 + * According to the PostScript specification, counter-clockwise contours
1.506 + * must be filled, and clockwise ones must be unfilled.
1.507 + *
1.508 + * FT_ORIENTATION_FILL_RIGHT ::
1.509 + * This is identical to @FT_ORIENTATION_TRUETYPE, but is used to
1.510 + * remember that in TrueType, everything that is to the right of
1.511 + * the drawing direction of a contour must be filled.
1.512 + *
1.513 + * FT_ORIENTATION_FILL_LEFT ::
1.514 + * This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to
1.515 + * remember that in PostScript, everything that is to the left of
1.516 + * the drawing direction of a contour must be filled.
1.517 + *
1.518 + * FT_ORIENTATION_NONE ::
1.519 + * The orientation cannot be determined. That is, different parts of
1.520 + * the glyph have different orientation.
1.521 + *
1.522 + */
1.523 + typedef enum FT_Orientation_
1.524 + {
1.525 + FT_ORIENTATION_TRUETYPE = 0,
1.526 + FT_ORIENTATION_POSTSCRIPT = 1,
1.527 + FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE,
1.528 + FT_ORIENTATION_FILL_LEFT = FT_ORIENTATION_POSTSCRIPT,
1.529 + FT_ORIENTATION_NONE
1.530 +
1.531 + } FT_Orientation;
1.532 +
1.533 +
1.534 + /**************************************************************************
1.535 + *
1.536 + * @function:
1.537 + * FT_Outline_Get_Orientation
1.538 + *
1.539 + * @description:
1.540 + * This function analyzes a glyph outline and tries to compute its
1.541 + * fill orientation (see @FT_Orientation). This is done by integrating
1.542 + * the total area covered by the outline. The positive integral
1.543 + * corresponds to the clockwise orientation and @FT_ORIENTATION_POSTSCRIPT
1.544 + * is returned. The negative integral corresponds to the counter-clockwise
1.545 + * orientation and @FT_ORIENTATION_TRUETYPE is returned.
1.546 + *
1.547 + * Note that this will return @FT_ORIENTATION_TRUETYPE for empty
1.548 + * outlines.
1.549 + *
1.550 + * @input:
1.551 + * outline ::
1.552 + * A handle to the source outline.
1.553 + *
1.554 + * @return:
1.555 + * The orientation.
1.556 + *
1.557 + */
1.558 + FT_EXPORT( FT_Orientation )
1.559 + FT_Outline_Get_Orientation( FT_Outline* outline );
1.560 +
1.561 +
1.562 + /* */
1.563 +
1.564 +
1.565 +FT_END_HEADER
1.566 +
1.567 +#endif /* __FTOUTLN_H__ */
1.568 +
1.569 +
1.570 +/* END */
1.571 +
1.572 +
1.573 +/* Local Variables: */
1.574 +/* coding: utf-8 */
1.575 +/* End: */
