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, 2002, 2003, 2005, 2006, 2007 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 FT_FREETYPE_H 27 #include FT_TYPE1_TABLES_H 28 29 30 FT_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 integers, used as (position,length) 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 174 * the 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_Long* 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 integers, holding 3 (position,length) pairs for the 201 * 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_Long* 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 380 * functions 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 384 * strange 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. 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 456 * element is an absolute position in font units, each odd element is a 457 * length in font units. 458 * 459 * A length can be negative, in which case it must be either -20 or 460 * -21. 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_UInt 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 486 * or 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 520 * (this 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' 591 * method. 592 * 593 * @input: 594 * hints :: 595 * A handle to the Type 2 hints recorder. 596 * 597 * outline :: 598 * A pointer to the target outline descriptor. 599 * 600 * globals :: 601 * The hinter globals for this font. 602 * 603 * hint_mode :: 604 * Hinting information. 605 * 606 * @return: 607 * FreeType error code. 0 means success. 608 * 609 * @note: 610 * On input, all points within the outline are in font coordinates. On 611 * output, they are in 1/64th of pixels. 612 * 613 * The scaling transformation is taken from the `globals' object which 614 * must correspond to the same font than the glyph. 615 * 616 */ 617 typedef FT_Error 618 (*T2_Hints_ApplyFunc)( T2_Hints hints, 619 FT_Outline* outline, 620 PSH_Globals globals, 621 FT_Render_Mode hint_mode ); 622 623 624 /************************************************************************* 625 * 626 * @struct: 627 * T2_Hints_FuncsRec 628 * 629 * @description: 630 * The structure used to provide the API to @T2_Hints objects. 631 * 632 * @fields: 633 * hints :: 634 * A handle to the T2 hints recorder object. 635 * 636 * open :: 637 * The function to open a recording session. 638 * 639 * close :: 640 * The function to close a recording session. 641 * 642 * stems :: 643 * The function to set the dimension's stems table. 644 * 645 * hintmask :: 646 * The function to set hint masks. 647 * 648 * counter :: 649 * The function to set counter masks. 650 * 651 * apply :: 652 * The function to apply the hints on the corresponding glyph outline. 653 * 654 */ 655 typedef struct T2_Hints_FuncsRec_ 656 { 657 T2_Hints hints; 658 T2_Hints_OpenFunc open; 659 T2_Hints_CloseFunc close; 660 T2_Hints_StemsFunc stems; 661 T2_Hints_MaskFunc hintmask; 662 T2_Hints_CounterFunc counter; 663 T2_Hints_ApplyFunc apply; 664 665 } T2_Hints_FuncsRec; 666 667 668 /* */ 669 670 671 typedef struct PSHinter_Interface_ 672 { 673 PSH_Globals_Funcs (*get_globals_funcs)( FT_Module module ); 674 T1_Hints_Funcs (*get_t1_funcs) ( FT_Module module ); 675 T2_Hints_Funcs (*get_t2_funcs) ( FT_Module module ); 676 677 } PSHinter_Interface; 678 679 typedef PSHinter_Interface* PSHinter_Service; 680 681 682 FT_END_HEADER 683 684 #endif /* __PSHINTS_H__ */ 685 686 687 /* END */ 688