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