• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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-2018 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 void
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_Int     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 #define FT_DEFINE_PSHINTER_INTERFACE(        \
684           class_,                            \
685           get_globals_funcs_,                \
686           get_t1_funcs_,                     \
687           get_t2_funcs_ )                    \
688   static const PSHinter_Interface  class_ =  \
689   {                                          \
690     get_globals_funcs_,                      \
691     get_t1_funcs_,                           \
692     get_t2_funcs_                            \
693   };
694 
695 
696 FT_END_HEADER
697 
698 #endif /* PSHINTS_H_ */
699 
700 
701 /* END */
702