1/***************************************************************************/ 2/* */ 3/* ftoutln.h */ 4/* */ 5/* Support for the FT_Outline type used to store glyph shapes of */ 6/* most scalable font formats (specification). */ 7/* */ 8/* Copyright 1996-2018 by */ 9/* David Turner, Robert Wilhelm, and Werner Lemberg. */ 10/* */ 11/* This file is part of the FreeType project, and may only be used, */ 12/* modified, and distributed under the terms of the FreeType project */ 13/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ 14/* this file you indicate that you have read the license and */ 15/* understand and accept it fully. */ 16/* */ 17/***************************************************************************/ 18 19 20#ifndef FTOUTLN_H_ 21#define FTOUTLN_H_ 22 23 24#include <ft2build.h> 25#include FT_FREETYPE_H 26 27#ifdef FREETYPE_H 28#error "freetype.h of FreeType 1 has been loaded!" 29#error "Please fix the directory search order for header files" 30#error "so that freetype.h of FreeType 2 is found first." 31#endif 32 33 34FT_BEGIN_HEADER 35 36 37 /*************************************************************************/ 38 /* */ 39 /* <Section> */ 40 /* outline_processing */ 41 /* */ 42 /* <Title> */ 43 /* Outline Processing */ 44 /* */ 45 /* <Abstract> */ 46 /* Functions to create, transform, and render vectorial glyph images. */ 47 /* */ 48 /* <Description> */ 49 /* This section contains routines used to create and destroy scalable */ 50 /* glyph images known as `outlines'. These can also be measured, */ 51 /* transformed, and converted into bitmaps and pixmaps. */ 52 /* */ 53 /* <Order> */ 54 /* FT_Outline */ 55 /* FT_Outline_New */ 56 /* FT_Outline_Done */ 57 /* FT_Outline_Copy */ 58 /* FT_Outline_Translate */ 59 /* FT_Outline_Transform */ 60 /* FT_Outline_Embolden */ 61 /* FT_Outline_EmboldenXY */ 62 /* FT_Outline_Reverse */ 63 /* FT_Outline_Check */ 64 /* */ 65 /* FT_Outline_Get_CBox */ 66 /* FT_Outline_Get_BBox */ 67 /* */ 68 /* FT_Outline_Get_Bitmap */ 69 /* FT_Outline_Render */ 70 /* FT_Outline_Decompose */ 71 /* FT_Outline_Funcs */ 72 /* FT_Outline_MoveToFunc */ 73 /* FT_Outline_LineToFunc */ 74 /* FT_Outline_ConicToFunc */ 75 /* FT_Outline_CubicToFunc */ 76 /* */ 77 /* FT_Orientation */ 78 /* FT_Outline_Get_Orientation */ 79 /* */ 80 /* FT_OUTLINE_XXX */ 81 /* */ 82 /*************************************************************************/ 83 84 85 /*************************************************************************/ 86 /* */ 87 /* <Function> */ 88 /* FT_Outline_Decompose */ 89 /* */ 90 /* <Description> */ 91 /* Walk over an outline's structure to decompose it into individual */ 92 /* segments and Bezier arcs. This function also emits `move to' */ 93 /* operations to indicate the start of new contours in the outline. */ 94 /* */ 95 /* <Input> */ 96 /* outline :: A pointer to the source target. */ 97 /* */ 98 /* func_interface :: A table of `emitters', i.e., function pointers */ 99 /* called during decomposition to indicate path */ 100 /* operations. */ 101 /* */ 102 /* <InOut> */ 103 /* user :: A typeless pointer that is passed to each */ 104 /* emitter during the decomposition. It can be */ 105 /* used to store the state during the */ 106 /* decomposition. */ 107 /* */ 108 /* <Return> */ 109 /* FreeType error code. 0~means success. */ 110 /* */ 111 /* <Note> */ 112 /* A contour that contains a single point only is represented by a */ 113 /* `move to' operation followed by `line to' to the same point. In */ 114 /* most cases, it is best to filter this out before using the */ 115 /* outline for stroking purposes (otherwise it would result in a */ 116 /* visible dot when round caps are used). */ 117 /* */ 118 /* Similarly, the function returns success for an empty outline also */ 119 /* (doing nothing, this is, not calling any emitter); if necessary, */ 120 /* you should filter this out, too. */ 121 /* */ 122 FT_EXPORT( FT_Error ) 123 FT_Outline_Decompose( FT_Outline* outline, 124 const FT_Outline_Funcs* func_interface, 125 void* user ); 126 127 128 /*************************************************************************/ 129 /* */ 130 /* <Function> */ 131 /* FT_Outline_New */ 132 /* */ 133 /* <Description> */ 134 /* Create a new outline of a given size. */ 135 /* */ 136 /* <Input> */ 137 /* library :: A handle to the library object from where the */ 138 /* outline is allocated. Note however that the new */ 139 /* outline will *not* necessarily be *freed*, when */ 140 /* destroying the library, by @FT_Done_FreeType. */ 141 /* */ 142 /* numPoints :: The maximum number of points within the outline. */ 143 /* Must be smaller than or equal to 0xFFFF (65535). */ 144 /* */ 145 /* numContours :: The maximum number of contours within the outline. */ 146 /* This value must be in the range 0 to `numPoints'. */ 147 /* */ 148 /* <Output> */ 149 /* anoutline :: A handle to the new outline. */ 150 /* */ 151 /* <Return> */ 152 /* FreeType error code. 0~means success. */ 153 /* */ 154 /* <Note> */ 155 /* The reason why this function takes a `library' parameter is simply */ 156 /* to use the library's memory allocator. */ 157 /* */ 158 FT_EXPORT( FT_Error ) 159 FT_Outline_New( FT_Library library, 160 FT_UInt numPoints, 161 FT_Int numContours, 162 FT_Outline *anoutline ); 163 164 165 FT_EXPORT( FT_Error ) 166 FT_Outline_New_Internal( FT_Memory memory, 167 FT_UInt numPoints, 168 FT_Int numContours, 169 FT_Outline *anoutline ); 170 171 172 /*************************************************************************/ 173 /* */ 174 /* <Function> */ 175 /* FT_Outline_Done */ 176 /* */ 177 /* <Description> */ 178 /* Destroy an outline created with @FT_Outline_New. */ 179 /* */ 180 /* <Input> */ 181 /* library :: A handle of the library object used to allocate the */ 182 /* outline. */ 183 /* */ 184 /* outline :: A pointer to the outline object to be discarded. */ 185 /* */ 186 /* <Return> */ 187 /* FreeType error code. 0~means success. */ 188 /* */ 189 /* <Note> */ 190 /* If the outline's `owner' field is not set, only the outline */ 191 /* descriptor will be released. */ 192 /* */ 193 FT_EXPORT( FT_Error ) 194 FT_Outline_Done( FT_Library library, 195 FT_Outline* outline ); 196 197 198 FT_EXPORT( FT_Error ) 199 FT_Outline_Done_Internal( FT_Memory memory, 200 FT_Outline* outline ); 201 202 203 /*************************************************************************/ 204 /* */ 205 /* <Function> */ 206 /* FT_Outline_Check */ 207 /* */ 208 /* <Description> */ 209 /* Check the contents of an outline descriptor. */ 210 /* */ 211 /* <Input> */ 212 /* outline :: A handle to a source outline. */ 213 /* */ 214 /* <Return> */ 215 /* FreeType error code. 0~means success. */ 216 /* */ 217 /* <Note> */ 218 /* An empty outline, or an outline with a single point only is also */ 219 /* valid. */ 220 /* */ 221 FT_EXPORT( FT_Error ) 222 FT_Outline_Check( FT_Outline* outline ); 223 224 225 /*************************************************************************/ 226 /* */ 227 /* <Function> */ 228 /* FT_Outline_Get_CBox */ 229 /* */ 230 /* <Description> */ 231 /* Return an outline's `control box'. The control box encloses all */ 232 /* the outline's points, including Bezier control points. Though it */ 233 /* coincides with the exact bounding box for most glyphs, it can be */ 234 /* slightly larger in some situations (like when rotating an outline */ 235 /* that contains Bezier outside arcs). */ 236 /* */ 237 /* Computing the control box is very fast, while getting the bounding */ 238 /* box can take much more time as it needs to walk over all segments */ 239 /* and arcs in the outline. To get the latter, you can use the */ 240 /* `ftbbox' component, which is dedicated to this single task. */ 241 /* */ 242 /* <Input> */ 243 /* outline :: A pointer to the source outline descriptor. */ 244 /* */ 245 /* <Output> */ 246 /* acbox :: The outline's control box. */ 247 /* */ 248 /* <Note> */ 249 /* See @FT_Glyph_Get_CBox for a discussion of tricky fonts. */ 250 /* */ 251 FT_EXPORT( void ) 252 FT_Outline_Get_CBox( const FT_Outline* outline, 253 FT_BBox *acbox ); 254 255 256 /*************************************************************************/ 257 /* */ 258 /* <Function> */ 259 /* FT_Outline_Translate */ 260 /* */ 261 /* <Description> */ 262 /* Apply a simple translation to the points of an outline. */ 263 /* */ 264 /* <InOut> */ 265 /* outline :: A pointer to the target outline descriptor. */ 266 /* */ 267 /* <Input> */ 268 /* xOffset :: The horizontal offset. */ 269 /* */ 270 /* yOffset :: The vertical offset. */ 271 /* */ 272 FT_EXPORT( void ) 273 FT_Outline_Translate( const FT_Outline* outline, 274 FT_Pos xOffset, 275 FT_Pos yOffset ); 276 277 278 /*************************************************************************/ 279 /* */ 280 /* <Function> */ 281 /* FT_Outline_Copy */ 282 /* */ 283 /* <Description> */ 284 /* Copy an outline into another one. Both objects must have the */ 285 /* same sizes (number of points & number of contours) when this */ 286 /* function is called. */ 287 /* */ 288 /* <Input> */ 289 /* source :: A handle to the source outline. */ 290 /* */ 291 /* <Output> */ 292 /* target :: A handle to the target outline. */ 293 /* */ 294 /* <Return> */ 295 /* FreeType error code. 0~means success. */ 296 /* */ 297 FT_EXPORT( FT_Error ) 298 FT_Outline_Copy( const FT_Outline* source, 299 FT_Outline *target ); 300 301 302 /*************************************************************************/ 303 /* */ 304 /* <Function> */ 305 /* FT_Outline_Transform */ 306 /* */ 307 /* <Description> */ 308 /* Apply a simple 2x2 matrix to all of an outline's points. Useful */ 309 /* for applying rotations, slanting, flipping, etc. */ 310 /* */ 311 /* <InOut> */ 312 /* outline :: A pointer to the target outline descriptor. */ 313 /* */ 314 /* <Input> */ 315 /* matrix :: A pointer to the transformation matrix. */ 316 /* */ 317 /* <Note> */ 318 /* You can use @FT_Outline_Translate if you need to translate the */ 319 /* outline's points. */ 320 /* */ 321 FT_EXPORT( void ) 322 FT_Outline_Transform( const FT_Outline* outline, 323 const FT_Matrix* matrix ); 324 325 326 /*************************************************************************/ 327 /* */ 328 /* <Function> */ 329 /* FT_Outline_Embolden */ 330 /* */ 331 /* <Description> */ 332 /* Embolden an outline. The new outline will be at most 4~times */ 333 /* `strength' pixels wider and higher. You may think of the left and */ 334 /* bottom borders as unchanged. */ 335 /* */ 336 /* Negative `strength' values to reduce the outline thickness are */ 337 /* possible also. */ 338 /* */ 339 /* <InOut> */ 340 /* outline :: A handle to the target outline. */ 341 /* */ 342 /* <Input> */ 343 /* strength :: How strong the glyph is emboldened. Expressed in */ 344 /* 26.6 pixel format. */ 345 /* */ 346 /* <Return> */ 347 /* FreeType error code. 0~means success. */ 348 /* */ 349 /* <Note> */ 350 /* The used algorithm to increase or decrease the thickness of the */ 351 /* glyph doesn't change the number of points; this means that certain */ 352 /* situations like acute angles or intersections are sometimes */ 353 /* handled incorrectly. */ 354 /* */ 355 /* If you need `better' metrics values you should call */ 356 /* @FT_Outline_Get_CBox or @FT_Outline_Get_BBox. */ 357 /* */ 358 /* Example call: */ 359 /* */ 360 /* { */ 361 /* FT_Load_Glyph( face, index, FT_LOAD_DEFAULT ); */ 362 /* if ( face->glyph->format == FT_GLYPH_FORMAT_OUTLINE ) */ 363 /* FT_Outline_Embolden( &face->glyph->outline, strength ); */ 364 /* } */ 365 /* */ 366 /* To get meaningful results, font scaling values must be set with */ 367 /* functions like @FT_Set_Char_Size before calling FT_Render_Glyph. */ 368 /* */ 369 FT_EXPORT( FT_Error ) 370 FT_Outline_Embolden( FT_Outline* outline, 371 FT_Pos strength ); 372 373 374 /*************************************************************************/ 375 /* */ 376 /* <Function> */ 377 /* FT_Outline_EmboldenXY */ 378 /* */ 379 /* <Description> */ 380 /* Embolden an outline. The new outline will be `xstrength' pixels */ 381 /* wider and `ystrength' pixels higher. Otherwise, it is similar to */ 382 /* @FT_Outline_Embolden, which uses the same strength in both */ 383 /* directions. */ 384 /* */ 385 /* <Since> */ 386 /* 2.4.10 */ 387 /* */ 388 FT_EXPORT( FT_Error ) 389 FT_Outline_EmboldenXY( FT_Outline* outline, 390 FT_Pos xstrength, 391 FT_Pos ystrength ); 392 393 394 /*************************************************************************/ 395 /* */ 396 /* <Function> */ 397 /* FT_Outline_Reverse */ 398 /* */ 399 /* <Description> */ 400 /* Reverse the drawing direction of an outline. This is used to */ 401 /* ensure consistent fill conventions for mirrored glyphs. */ 402 /* */ 403 /* <InOut> */ 404 /* outline :: A pointer to the target outline descriptor. */ 405 /* */ 406 /* <Note> */ 407 /* This function toggles the bit flag @FT_OUTLINE_REVERSE_FILL in */ 408 /* the outline's `flags' field. */ 409 /* */ 410 /* It shouldn't be used by a normal client application, unless it */ 411 /* knows what it is doing. */ 412 /* */ 413 FT_EXPORT( void ) 414 FT_Outline_Reverse( FT_Outline* outline ); 415 416 417 /*************************************************************************/ 418 /* */ 419 /* <Function> */ 420 /* FT_Outline_Get_Bitmap */ 421 /* */ 422 /* <Description> */ 423 /* Render an outline within a bitmap. The outline's image is simply */ 424 /* OR-ed to the target bitmap. */ 425 /* */ 426 /* <Input> */ 427 /* library :: A handle to a FreeType library object. */ 428 /* */ 429 /* outline :: A pointer to the source outline descriptor. */ 430 /* */ 431 /* <InOut> */ 432 /* abitmap :: A pointer to the target bitmap descriptor. */ 433 /* */ 434 /* <Return> */ 435 /* FreeType error code. 0~means success. */ 436 /* */ 437 /* <Note> */ 438 /* This function does NOT CREATE the bitmap, it only renders an */ 439 /* outline image within the one you pass to it! Consequently, the */ 440 /* various fields in `abitmap' should be set accordingly. */ 441 /* */ 442 /* It will use the raster corresponding to the default glyph format. */ 443 /* */ 444 /* The value of the `num_grays' field in `abitmap' is ignored. If */ 445 /* you select the gray-level rasterizer, and you want less than 256 */ 446 /* gray levels, you have to use @FT_Outline_Render directly. */ 447 /* */ 448 FT_EXPORT( FT_Error ) 449 FT_Outline_Get_Bitmap( FT_Library library, 450 FT_Outline* outline, 451 const FT_Bitmap *abitmap ); 452 453 454 /*************************************************************************/ 455 /* */ 456 /* <Function> */ 457 /* FT_Outline_Render */ 458 /* */ 459 /* <Description> */ 460 /* Render an outline within a bitmap using the current scan-convert. */ 461 /* This function uses an @FT_Raster_Params structure as an argument, */ 462 /* allowing advanced features like direct composition, translucency, */ 463 /* etc. */ 464 /* */ 465 /* <Input> */ 466 /* library :: A handle to a FreeType library object. */ 467 /* */ 468 /* outline :: A pointer to the source outline descriptor. */ 469 /* */ 470 /* <InOut> */ 471 /* params :: A pointer to an @FT_Raster_Params structure used to */ 472 /* describe the rendering operation. */ 473 /* */ 474 /* <Return> */ 475 /* FreeType error code. 0~means success. */ 476 /* */ 477 /* <Note> */ 478 /* You should know what you are doing and how @FT_Raster_Params works */ 479 /* to use this function. */ 480 /* */ 481 /* The field `params.source' will be set to `outline' before the scan */ 482 /* converter is called, which means that the value you give to it is */ 483 /* actually ignored. */ 484 /* */ 485 /* The gray-level rasterizer always uses 256 gray levels. If you */ 486 /* want less gray levels, you have to provide your own span callback. */ 487 /* See the @FT_RASTER_FLAG_DIRECT value of the `flags' field in the */ 488 /* @FT_Raster_Params structure for more details. */ 489 /* */ 490 FT_EXPORT( FT_Error ) 491 FT_Outline_Render( FT_Library library, 492 FT_Outline* outline, 493 FT_Raster_Params* params ); 494 495 496 /************************************************************************** 497 * 498 * @enum: 499 * FT_Orientation 500 * 501 * @description: 502 * A list of values used to describe an outline's contour orientation. 503 * 504 * The TrueType and PostScript specifications use different conventions 505 * to determine whether outline contours should be filled or unfilled. 506 * 507 * @values: 508 * FT_ORIENTATION_TRUETYPE :: 509 * According to the TrueType specification, clockwise contours must 510 * be filled, and counter-clockwise ones must be unfilled. 511 * 512 * FT_ORIENTATION_POSTSCRIPT :: 513 * According to the PostScript specification, counter-clockwise contours 514 * must be filled, and clockwise ones must be unfilled. 515 * 516 * FT_ORIENTATION_FILL_RIGHT :: 517 * This is identical to @FT_ORIENTATION_TRUETYPE, but is used to 518 * remember that in TrueType, everything that is to the right of 519 * the drawing direction of a contour must be filled. 520 * 521 * FT_ORIENTATION_FILL_LEFT :: 522 * This is identical to @FT_ORIENTATION_POSTSCRIPT, but is used to 523 * remember that in PostScript, everything that is to the left of 524 * the drawing direction of a contour must be filled. 525 * 526 * FT_ORIENTATION_NONE :: 527 * The orientation cannot be determined. That is, different parts of 528 * the glyph have different orientation. 529 * 530 */ 531 typedef enum FT_Orientation_ 532 { 533 FT_ORIENTATION_TRUETYPE = 0, 534 FT_ORIENTATION_POSTSCRIPT = 1, 535 FT_ORIENTATION_FILL_RIGHT = FT_ORIENTATION_TRUETYPE, 536 FT_ORIENTATION_FILL_LEFT = FT_ORIENTATION_POSTSCRIPT, 537 FT_ORIENTATION_NONE 538 539 } FT_Orientation; 540 541 542 /************************************************************************** 543 * 544 * @function: 545 * FT_Outline_Get_Orientation 546 * 547 * @description: 548 * This function analyzes a glyph outline and tries to compute its 549 * fill orientation (see @FT_Orientation). This is done by integrating 550 * the total area covered by the outline. The positive integral 551 * corresponds to the clockwise orientation and @FT_ORIENTATION_POSTSCRIPT 552 * is returned. The negative integral corresponds to the counter-clockwise 553 * orientation and @FT_ORIENTATION_TRUETYPE is returned. 554 * 555 * Note that this will return @FT_ORIENTATION_TRUETYPE for empty 556 * outlines. 557 * 558 * @input: 559 * outline :: 560 * A handle to the source outline. 561 * 562 * @return: 563 * The orientation. 564 * 565 */ 566 FT_EXPORT( FT_Orientation ) 567 FT_Outline_Get_Orientation( FT_Outline* outline ); 568 569 /* */ 570 571 572FT_END_HEADER 573 574#endif /* FTOUTLN_H_ */ 575 576 577/* END */ 578 579 580/* Local Variables: */ 581/* coding: utf-8 */ 582/* End: */ 583