pshints.h revision ee451cb395940862dad63c85adfe8f2fd55e864c
1/***************************************************************************/ 2/* */ 3/* pshints.h */ 4/* */ 5/* Interface to Postscript-specific (Type 1 and Type 2) hints */ 6/* recorders (specification only). These are used to support native */ 7/* T1/T2 hints in the `type1', `cid', and `cff' font drivers. */ 8/* */ 9/* Copyright 2001-2003, 2005-2007, 2009, 2012 by */ 10/* David Turner, Robert Wilhelm, and Werner Lemberg. */ 11/* */ 12/* This file is part of the FreeType project, and may only be used, */ 13/* modified, and distributed under the terms of the FreeType project */ 14/* license, LICENSE.TXT. By continuing to use, modify, or distribute */ 15/* this file you indicate that you have read the license and */ 16/* understand and accept it fully. */ 17/* */ 18/***************************************************************************/ 19 20 21#ifndef __PSHINTS_H__ 22#define __PSHINTS_H__ 23 24 25#include "../../ft2build.h" 26#include "../freetype.h" 27#include "../t1tables.h" 28 29 30FT_BEGIN_HEADER 31 32 33 /*************************************************************************/ 34 /*************************************************************************/ 35 /***** *****/ 36 /***** INTERNAL REPRESENTATION OF GLOBALS *****/ 37 /***** *****/ 38 /*************************************************************************/ 39 /*************************************************************************/ 40 41 typedef struct PSH_GlobalsRec_* PSH_Globals; 42 43 typedef FT_Error 44 (*PSH_Globals_NewFunc)( FT_Memory memory, 45 T1_Private* private_dict, 46 PSH_Globals* aglobals ); 47 48 typedef FT_Error 49 (*PSH_Globals_SetScaleFunc)( PSH_Globals globals, 50 FT_Fixed x_scale, 51 FT_Fixed y_scale, 52 FT_Fixed x_delta, 53 FT_Fixed y_delta ); 54 55 typedef void 56 (*PSH_Globals_DestroyFunc)( PSH_Globals globals ); 57 58 59 typedef struct PSH_Globals_FuncsRec_ 60 { 61 PSH_Globals_NewFunc create; 62 PSH_Globals_SetScaleFunc set_scale; 63 PSH_Globals_DestroyFunc destroy; 64 65 } PSH_Globals_FuncsRec, *PSH_Globals_Funcs; 66 67 68 /*************************************************************************/ 69 /*************************************************************************/ 70 /***** *****/ 71 /***** PUBLIC TYPE 1 HINTS RECORDER *****/ 72 /***** *****/ 73 /*************************************************************************/ 74 /*************************************************************************/ 75 76 /************************************************************************* 77 * 78 * @type: 79 * T1_Hints 80 * 81 * @description: 82 * This is a handle to an opaque structure used to record glyph hints 83 * from a Type 1 character glyph character string. 84 * 85 * The methods used to operate on this object are defined by the 86 * @T1_Hints_FuncsRec structure. Recording glyph hints is normally 87 * achieved through the following scheme: 88 * 89 * - Open a new hint recording session by calling the `open' method. 90 * This rewinds the recorder and prepare it for new input. 91 * 92 * - For each hint found in the glyph charstring, call the corresponding 93 * method (`stem', `stem3', or `reset'). Note that these functions do 94 * not return an error code. 95 * 96 * - Close the recording session by calling the `close' method. It 97 * returns an error code if the hints were invalid or something 98 * strange happened (e.g., memory shortage). 99 * 100 * The hints accumulated in the object can later be used by the 101 * PostScript hinter. 102 * 103 */ 104 typedef struct T1_HintsRec_* T1_Hints; 105 106 107 /************************************************************************* 108 * 109 * @type: 110 * T1_Hints_Funcs 111 * 112 * @description: 113 * A pointer to the @T1_Hints_FuncsRec structure that defines the API of 114 * a given @T1_Hints object. 115 * 116 */ 117 typedef const struct T1_Hints_FuncsRec_* T1_Hints_Funcs; 118 119 120 /************************************************************************* 121 * 122 * @functype: 123 * T1_Hints_OpenFunc 124 * 125 * @description: 126 * A method of the @T1_Hints class used to prepare it for a new Type 1 127 * hints recording session. 128 * 129 * @input: 130 * hints :: 131 * A handle to the Type 1 hints recorder. 132 * 133 * @note: 134 * You should always call the @T1_Hints_CloseFunc method in order to 135 * close an opened recording session. 136 * 137 */ 138 typedef void 139 (*T1_Hints_OpenFunc)( T1_Hints hints ); 140 141 142 /************************************************************************* 143 * 144 * @functype: 145 * T1_Hints_SetStemFunc 146 * 147 * @description: 148 * A method of the @T1_Hints class used to record a new horizontal or 149 * vertical stem. This corresponds to the Type 1 `hstem' and `vstem' 150 * operators. 151 * 152 * @input: 153 * hints :: 154 * A handle to the Type 1 hints recorder. 155 * 156 * dimension :: 157 * 0 for horizontal stems (hstem), 1 for vertical ones (vstem). 158 * 159 * coords :: 160 * Array of 2 coordinates in 16.16 format, used as (position,length) 161 * stem descriptor. 162 * 163 * @note: 164 * Use vertical coordinates (y) for horizontal stems (dim=0). Use 165 * horizontal coordinates (x) for vertical stems (dim=1). 166 * 167 * `coords[0]' is the absolute stem position (lowest coordinate); 168 * `coords[1]' is the length. 169 * 170 * The length can be negative, in which case it must be either -20 or 171 * -21. It is interpreted as a `ghost' stem, according to the Type 1 172 * specification. 173 * 174 * If the length is -21 (corresponding to a bottom ghost stem), then 175 * the real stem position is `coords[0]+coords[1]'. 176 * 177 */ 178 typedef void 179 (*T1_Hints_SetStemFunc)( T1_Hints hints, 180 FT_UInt dimension, 181 FT_Fixed* coords ); 182 183 184 /************************************************************************* 185 * 186 * @functype: 187 * T1_Hints_SetStem3Func 188 * 189 * @description: 190 * A method of the @T1_Hints class used to record three 191 * counter-controlled horizontal or vertical stems at once. 192 * 193 * @input: 194 * hints :: 195 * A handle to the Type 1 hints recorder. 196 * 197 * dimension :: 198 * 0 for horizontal stems, 1 for vertical ones. 199 * 200 * coords :: 201 * An array of 6 values in 16.16 format, holding 3 (position,length) 202 * pairs for the counter-controlled stems. 203 * 204 * @note: 205 * Use vertical coordinates (y) for horizontal stems (dim=0). Use 206 * horizontal coordinates (x) for vertical stems (dim=1). 207 * 208 * The lengths cannot be negative (ghost stems are never 209 * counter-controlled). 210 * 211 */ 212 typedef void 213 (*T1_Hints_SetStem3Func)( T1_Hints hints, 214 FT_UInt dimension, 215 FT_Fixed* coords ); 216 217 218 /************************************************************************* 219 * 220 * @functype: 221 * T1_Hints_ResetFunc 222 * 223 * @description: 224 * A method of the @T1_Hints class used to reset the stems hints in a 225 * recording session. 226 * 227 * @input: 228 * hints :: 229 * A handle to the Type 1 hints recorder. 230 * 231 * end_point :: 232 * The index of the last point in the input glyph in which the 233 * previously defined hints apply. 234 * 235 */ 236 typedef void 237 (*T1_Hints_ResetFunc)( T1_Hints hints, 238 FT_UInt end_point ); 239 240 241 /************************************************************************* 242 * 243 * @functype: 244 * T1_Hints_CloseFunc 245 * 246 * @description: 247 * A method of the @T1_Hints class used to close a hint recording 248 * session. 249 * 250 * @input: 251 * hints :: 252 * A handle to the Type 1 hints recorder. 253 * 254 * end_point :: 255 * The index of the last point in the input glyph. 256 * 257 * @return: 258 * FreeType error code. 0 means success. 259 * 260 * @note: 261 * The error code is set to indicate that an error occurred during the 262 * recording session. 263 * 264 */ 265 typedef FT_Error 266 (*T1_Hints_CloseFunc)( T1_Hints hints, 267 FT_UInt end_point ); 268 269 270 /************************************************************************* 271 * 272 * @functype: 273 * T1_Hints_ApplyFunc 274 * 275 * @description: 276 * A method of the @T1_Hints class used to apply hints to the 277 * corresponding glyph outline. Must be called once all hints have been 278 * recorded. 279 * 280 * @input: 281 * hints :: 282 * A handle to the Type 1 hints recorder. 283 * 284 * outline :: 285 * A pointer to the target outline descriptor. 286 * 287 * globals :: 288 * The hinter globals for this font. 289 * 290 * hint_mode :: 291 * Hinting information. 292 * 293 * @return: 294 * FreeType error code. 0 means success. 295 * 296 * @note: 297 * On input, all points within the outline are in font coordinates. On 298 * output, they are in 1/64th of pixels. 299 * 300 * The scaling transformation is taken from the `globals' object which 301 * must correspond to the same font as the glyph. 302 * 303 */ 304 typedef FT_Error 305 (*T1_Hints_ApplyFunc)( T1_Hints hints, 306 FT_Outline* outline, 307 PSH_Globals globals, 308 FT_Render_Mode hint_mode ); 309 310 311 /************************************************************************* 312 * 313 * @struct: 314 * T1_Hints_FuncsRec 315 * 316 * @description: 317 * The structure used to provide the API to @T1_Hints objects. 318 * 319 * @fields: 320 * hints :: 321 * A handle to the T1 Hints recorder. 322 * 323 * open :: 324 * The function to open a recording session. 325 * 326 * close :: 327 * The function to close a recording session. 328 * 329 * stem :: 330 * The function to set a simple stem. 331 * 332 * stem3 :: 333 * The function to set counter-controlled stems. 334 * 335 * reset :: 336 * The function to reset stem hints. 337 * 338 * apply :: 339 * The function to apply the hints to the corresponding glyph outline. 340 * 341 */ 342 typedef struct T1_Hints_FuncsRec_ 343 { 344 T1_Hints hints; 345 T1_Hints_OpenFunc open; 346 T1_Hints_CloseFunc close; 347 T1_Hints_SetStemFunc stem; 348 T1_Hints_SetStem3Func stem3; 349 T1_Hints_ResetFunc reset; 350 T1_Hints_ApplyFunc apply; 351 352 } T1_Hints_FuncsRec; 353 354 355 /*************************************************************************/ 356 /*************************************************************************/ 357 /***** *****/ 358 /***** PUBLIC TYPE 2 HINTS RECORDER *****/ 359 /***** *****/ 360 /*************************************************************************/ 361 /*************************************************************************/ 362 363 /************************************************************************* 364 * 365 * @type: 366 * T2_Hints 367 * 368 * @description: 369 * This is a handle to an opaque structure used to record glyph hints 370 * from a Type 2 character glyph character string. 371 * 372 * The methods used to operate on this object are defined by the 373 * @T2_Hints_FuncsRec structure. Recording glyph hints is normally 374 * achieved through the following scheme: 375 * 376 * - Open a new hint recording session by calling the `open' method. 377 * This rewinds the recorder and prepare it for new input. 378 * 379 * - For each hint found in the glyph charstring, call the corresponding 380 * method (`stems', `hintmask', `counters'). Note that these 381 * functions do not return an error code. 382 * 383 * - Close the recording session by calling the `close' method. It 384 * returns an error code if the hints were invalid or something 385 * strange happened (e.g., memory shortage). 386 * 387 * The hints accumulated in the object can later be used by the 388 * Postscript hinter. 389 * 390 */ 391 typedef struct T2_HintsRec_* T2_Hints; 392 393 394 /************************************************************************* 395 * 396 * @type: 397 * T2_Hints_Funcs 398 * 399 * @description: 400 * A pointer to the @T2_Hints_FuncsRec structure that defines the API of 401 * a given @T2_Hints object. 402 * 403 */ 404 typedef const struct T2_Hints_FuncsRec_* T2_Hints_Funcs; 405 406 407 /************************************************************************* 408 * 409 * @functype: 410 * T2_Hints_OpenFunc 411 * 412 * @description: 413 * A method of the @T2_Hints class used to prepare it for a new Type 2 414 * hints recording session. 415 * 416 * @input: 417 * hints :: 418 * A handle to the Type 2 hints recorder. 419 * 420 * @note: 421 * You should always call the @T2_Hints_CloseFunc method in order to 422 * close an opened recording session. 423 * 424 */ 425 typedef void 426 (*T2_Hints_OpenFunc)( T2_Hints hints ); 427 428 429 /************************************************************************* 430 * 431 * @functype: 432 * T2_Hints_StemsFunc 433 * 434 * @description: 435 * A method of the @T2_Hints class used to set the table of stems in 436 * either the vertical or horizontal dimension. Equivalent to the 437 * `hstem', `vstem', `hstemhm', and `vstemhm' Type 2 operators. 438 * 439 * @input: 440 * hints :: 441 * A handle to the Type 2 hints recorder. 442 * 443 * dimension :: 444 * 0 for horizontal stems (hstem), 1 for vertical ones (vstem). 445 * 446 * count :: 447 * The number of stems. 448 * 449 * coords :: 450 * An array of `count' (position,length) pairs in 16.16 format. 451 * 452 * @note: 453 * Use vertical coordinates (y) for horizontal stems (dim=0). Use 454 * horizontal coordinates (x) for vertical stems (dim=1). 455 * 456 * There are `2*count' elements in the `coords' array. Each even 457 * element is an absolute position in font units, each odd element is a 458 * length in font units. 459 * 460 * A length can be negative, in which case it must be either -20 or 461 * -21. It is interpreted as a `ghost' stem, according to the Type 1 462 * specification. 463 * 464 */ 465 typedef void 466 (*T2_Hints_StemsFunc)( T2_Hints hints, 467 FT_UInt dimension, 468 FT_UInt count, 469 FT_Fixed* coordinates ); 470 471 472 /************************************************************************* 473 * 474 * @functype: 475 * T2_Hints_MaskFunc 476 * 477 * @description: 478 * A method of the @T2_Hints class used to set a given hintmask (this 479 * corresponds to the `hintmask' Type 2 operator). 480 * 481 * @input: 482 * hints :: 483 * A handle to the Type 2 hints recorder. 484 * 485 * end_point :: 486 * The glyph index of the last point to which the previously defined 487 * or activated hints apply. 488 * 489 * bit_count :: 490 * The number of bits in the hint mask. 491 * 492 * bytes :: 493 * An array of bytes modelling the hint mask. 494 * 495 * @note: 496 * If the hintmask starts the charstring (before any glyph point 497 * definition), the value of `end_point' should be 0. 498 * 499 * `bit_count' is the number of meaningful bits in the `bytes' array; it 500 * must be equal to the total number of hints defined so far (i.e., 501 * horizontal+verticals). 502 * 503 * The `bytes' array can come directly from the Type 2 charstring and 504 * respects the same format. 505 * 506 */ 507 typedef void 508 (*T2_Hints_MaskFunc)( T2_Hints hints, 509 FT_UInt end_point, 510 FT_UInt bit_count, 511 const FT_Byte* bytes ); 512 513 514 /************************************************************************* 515 * 516 * @functype: 517 * T2_Hints_CounterFunc 518 * 519 * @description: 520 * A method of the @T2_Hints class used to set a given counter mask 521 * (this corresponds to the `hintmask' Type 2 operator). 522 * 523 * @input: 524 * hints :: 525 * A handle to the Type 2 hints recorder. 526 * 527 * end_point :: 528 * A glyph index of the last point to which the previously defined or 529 * active hints apply. 530 * 531 * bit_count :: 532 * The number of bits in the hint mask. 533 * 534 * bytes :: 535 * An array of bytes modelling the hint mask. 536 * 537 * @note: 538 * If the hintmask starts the charstring (before any glyph point 539 * definition), the value of `end_point' should be 0. 540 * 541 * `bit_count' is the number of meaningful bits in the `bytes' array; it 542 * must be equal to the total number of hints defined so far (i.e., 543 * horizontal+verticals). 544 * 545 * The `bytes' array can come directly from the Type 2 charstring and 546 * respects the same format. 547 * 548 */ 549 typedef void 550 (*T2_Hints_CounterFunc)( T2_Hints hints, 551 FT_UInt bit_count, 552 const FT_Byte* bytes ); 553 554 555 /************************************************************************* 556 * 557 * @functype: 558 * T2_Hints_CloseFunc 559 * 560 * @description: 561 * A method of the @T2_Hints class used to close a hint recording 562 * session. 563 * 564 * @input: 565 * hints :: 566 * A handle to the Type 2 hints recorder. 567 * 568 * end_point :: 569 * The index of the last point in the input glyph. 570 * 571 * @return: 572 * FreeType error code. 0 means success. 573 * 574 * @note: 575 * The error code is set to indicate that an error occurred during the 576 * recording session. 577 * 578 */ 579 typedef FT_Error 580 (*T2_Hints_CloseFunc)( T2_Hints hints, 581 FT_UInt end_point ); 582 583 584 /************************************************************************* 585 * 586 * @functype: 587 * T2_Hints_ApplyFunc 588 * 589 * @description: 590 * A method of the @T2_Hints class used to apply hints to the 591 * corresponding glyph outline. Must be called after the `close' 592 * method. 593 * 594 * @input: 595 * hints :: 596 * A handle to the Type 2 hints recorder. 597 * 598 * outline :: 599 * A pointer to the target outline descriptor. 600 * 601 * globals :: 602 * The hinter globals for this font. 603 * 604 * hint_mode :: 605 * Hinting information. 606 * 607 * @return: 608 * FreeType error code. 0 means success. 609 * 610 * @note: 611 * On input, all points within the outline are in font coordinates. On 612 * output, they are in 1/64th of pixels. 613 * 614 * The scaling transformation is taken from the `globals' object which 615 * must correspond to the same font than the glyph. 616 * 617 */ 618 typedef FT_Error 619 (*T2_Hints_ApplyFunc)( T2_Hints hints, 620 FT_Outline* outline, 621 PSH_Globals globals, 622 FT_Render_Mode hint_mode ); 623 624 625 /************************************************************************* 626 * 627 * @struct: 628 * T2_Hints_FuncsRec 629 * 630 * @description: 631 * The structure used to provide the API to @T2_Hints objects. 632 * 633 * @fields: 634 * hints :: 635 * A handle to the T2 hints recorder object. 636 * 637 * open :: 638 * The function to open a recording session. 639 * 640 * close :: 641 * The function to close a recording session. 642 * 643 * stems :: 644 * The function to set the dimension's stems table. 645 * 646 * hintmask :: 647 * The function to set hint masks. 648 * 649 * counter :: 650 * The function to set counter masks. 651 * 652 * apply :: 653 * The function to apply the hints on the corresponding glyph outline. 654 * 655 */ 656 typedef struct T2_Hints_FuncsRec_ 657 { 658 T2_Hints hints; 659 T2_Hints_OpenFunc open; 660 T2_Hints_CloseFunc close; 661 T2_Hints_StemsFunc stems; 662 T2_Hints_MaskFunc hintmask; 663 T2_Hints_CounterFunc counter; 664 T2_Hints_ApplyFunc apply; 665 666 } T2_Hints_FuncsRec; 667 668 669 /* */ 670 671 672 typedef struct PSHinter_Interface_ 673 { 674 PSH_Globals_Funcs (*get_globals_funcs)( FT_Module module ); 675 T1_Hints_Funcs (*get_t1_funcs) ( FT_Module module ); 676 T2_Hints_Funcs (*get_t2_funcs) ( FT_Module module ); 677 678 } PSHinter_Interface; 679 680 typedef PSHinter_Interface* PSHinter_Service; 681 682 683#ifndef FT_CONFIG_OPTION_PIC 684 685#define FT_DEFINE_PSHINTER_INTERFACE( \ 686 class_, \ 687 get_globals_funcs_, \ 688 get_t1_funcs_, \ 689 get_t2_funcs_ ) \ 690 static const PSHinter_Interface class_ = \ 691 { \ 692 get_globals_funcs_, \ 693 get_t1_funcs_, \ 694 get_t2_funcs_ \ 695 }; 696 697#else /* FT_CONFIG_OPTION_PIC */ 698 699#define FT_DEFINE_PSHINTER_INTERFACE( \ 700 class_, \ 701 get_globals_funcs_, \ 702 get_t1_funcs_, \ 703 get_t2_funcs_ ) \ 704 void \ 705 FT_Init_Class_ ## class_( FT_Library library, \ 706 PSHinter_Interface* clazz ) \ 707 { \ 708 FT_UNUSED( library ); \ 709 \ 710 clazz->get_globals_funcs = get_globals_funcs_; \ 711 clazz->get_t1_funcs = get_t1_funcs_; \ 712 clazz->get_t2_funcs = get_t2_funcs_; \ 713 } 714 715#endif /* FT_CONFIG_OPTION_PIC */ 716 717FT_END_HEADER 718 719#endif /* __PSHINTS_H__ */ 720 721 722/* END */ 723