source: trunk/poppler/freetype-2.1.10/include/freetype/ftcache.h @ 2

Last change on this file since 2 was 2, checked in by Eugene Romanenko, 15 years ago

First import

File size: 49.6 KB
Line 
1/***************************************************************************/
2/*                                                                         */
3/*  ftcache.h                                                              */
4/*                                                                         */
5/*    FreeType Cache subsystem (specification).                            */
6/*                                                                         */
7/*  Copyright 1996-2001, 2002, 2003, 2004 by                               */
8/*  David Turner, Robert Wilhelm, and Werner Lemberg.                      */
9/*                                                                         */
10/*  This file is part of the FreeType project, and may only be used,       */
11/*  modified, and distributed under the terms of the FreeType project      */
12/*  license, LICENSE.TXT.  By continuing to use, modify, or distribute     */
13/*  this file you indicate that you have read the license and              */
14/*  understand and accept it fully.                                        */
15/*                                                                         */
16/***************************************************************************/
17
18
19  /*************************************************************************/
20  /*************************************************************************/
21  /*************************************************************************/
22  /*************************************************************************/
23  /*************************************************************************/
24  /*********                                                       *********/
25  /*********             WARNING, THIS IS BETA CODE.               *********/
26  /*********                                                       *********/
27  /*************************************************************************/
28  /*************************************************************************/
29  /*************************************************************************/
30  /*************************************************************************/
31  /*************************************************************************/
32
33
34#ifndef __FTCACHE_H__
35#define __FTCACHE_H__
36
37
38#include <ft2build.h>
39#include FT_GLYPH_H
40
41
42FT_BEGIN_HEADER
43
44
45  /*************************************************************************/
46  /*                                                                       */
47  /* <Section>                                                             */
48  /*    cache_subsystem                                                    */
49  /*                                                                       */
50  /* <Title>                                                               */
51  /*    Cache Sub-System                                                   */
52  /*                                                                       */
53  /* <Abstract>                                                            */
54  /*    How to cache face, size, and glyph data with FreeType 2.           */
55  /*                                                                       */
56  /* <Description>                                                         */
57  /*   This section describes the FreeType 2 cache sub-system which is     */
58  /*   still in beta.                                                      */
59  /*                                                                       */
60  /* <Order>                                                               */
61  /*   FTC_Manager                                                         */
62  /*   FTC_FaceID                                                          */
63  /*   FTC_Face_Requester                                                  */
64  /*                                                                       */
65  /*   FTC_Manager_New                                                     */
66  /*   FTC_Manager_Reset                                                   */
67  /*   FTC_Manager_Done                                                    */
68  /*   FTC_Manager_LookupFace                                              */
69  /*   FTC_Manager_LookupSize                                              */
70  /*   FTC_Manager_RemoveFaceID                                            */
71  /*                                                                       */
72  /*   FTC_Node                                                            */
73  /*   FTC_Node_Unref                                                      */
74  /*                                                                       */
75  /*   FTC_Font                                                            */
76  /*   FTC_ImageCache                                                      */
77  /*   FTC_ImageCache_New                                                  */
78  /*   FTC_ImageCache_Lookup                                               */
79  /*                                                                       */
80  /*   FTC_SBit                                                            */
81  /*   FTC_SBitCache                                                       */
82  /*   FTC_SBitCache_New                                                   */
83  /*   FTC_SBitCache_Lookup                                                */
84  /*                                                                       */
85  /*   FTC_CMapCache                                                       */
86  /*   FTC_CMapCache_New                                                   */
87  /*   FTC_CMapCache_Lookup                                                */
88  /*                                                                       */
89  /*************************************************************************/
90
91
92  /*************************************************************************/
93  /*************************************************************************/
94  /*************************************************************************/
95  /*****                                                               *****/
96  /*****                    BASIC TYPE DEFINITIONS                     *****/
97  /*****                                                               *****/
98  /*************************************************************************/
99  /*************************************************************************/
100  /*************************************************************************/
101
102
103  /*************************************************************************/
104  /*                                                                       */
105  /* <Type>                                                                */
106  /*    FTC_FaceID                                                         */
107  /*                                                                       */
108  /* <Description>                                                         */
109  /*    An opaque pointer type that is used to identity face objects.  The */
110  /*    contents of such objects is application-dependent.                 */
111  /*                                                                       */
112  typedef struct FTC_FaceIDRec_*  FTC_FaceID;
113
114
115  /*************************************************************************/
116  /*                                                                       */
117  /* <FuncType>                                                            */
118  /*    FTC_Face_Requester                                                 */
119  /*                                                                       */
120  /* <Description>                                                         */
121  /*    A callback function provided by client applications.  It is used   */
122  /*    to translate a given @FTC_FaceID into a new valid @FT_Face object. */
123  /*                                                                       */
124  /* <Input>                                                               */
125  /*    face_id :: The face ID to resolve.                                 */
126  /*                                                                       */
127  /*    library :: A handle to a FreeType library object.                  */
128  /*                                                                       */
129  /*    data    :: Application-provided request data.                      */
130  /*                                                                       */
131  /* <Output>                                                              */
132  /*    aface   :: A new @FT_Face handle.                                  */
133  /*                                                                       */
134  /* <Return>                                                              */
135  /*    FreeType error code.  0 means success.                             */
136  /*                                                                       */
137  /* <Note>                                                                */
138  /*    The face requester should not perform funny things on the returned */
139  /*    face object, like creating a new @FT_Size for it, or setting a     */
140  /*    transformation through @FT_Set_Transform!                          */
141  /*                                                                       */
142  typedef FT_Error
143  (*FTC_Face_Requester)( FTC_FaceID  face_id,
144                         FT_Library  library,
145                         FT_Pointer  request_data,
146                         FT_Face*    aface );
147
148
149  /*************************************************************************/
150  /*                                                                       */
151  /* <Struct>                                                              */
152  /*    FTC_FontRec                                                        */
153  /*                                                                       */
154  /* <Description>                                                         */
155  /*    A simple structure used to describe a given `font' to the cache    */
156  /*    manager.  Note that a `font' is the combination of a given face    */
157  /*    with a given character size.                                       */
158  /*                                                                       */
159  /* <Fields>                                                              */
160  /*    face_id    :: The ID of the face to use.                           */
161  /*                                                                       */
162  /*    pix_width  :: The character width in integer pixels.               */
163  /*                                                                       */
164  /*    pix_height :: The character height in integer pixels.              */
165  /*                                                                       */
166  typedef struct  FTC_FontRec_
167  {
168    FTC_FaceID  face_id;
169    FT_UShort   pix_width;
170    FT_UShort   pix_height;
171
172  } FTC_FontRec;
173
174
175  /* */
176
177
178#define FTC_FONT_COMPARE( f1, f2 )                  \
179          ( (f1)->face_id    == (f2)->face_id    && \
180            (f1)->pix_width  == (f2)->pix_width  && \
181            (f1)->pix_height == (f2)->pix_height )
182
183#define FT_POINTER_TO_ULONG( p )  ((FT_ULong)(FT_Pointer)(p))
184
185#define FTC_FACE_ID_HASH( i )                              \
186          ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \
187                       ( FT_POINTER_TO_ULONG( i ) << 7 ) ) )
188
189#define FTC_FONT_HASH( f )                              \
190          (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \
191                       ((f)->pix_width << 8)          ^ \
192                       ((f)->pix_height)              )
193
194
195  /*************************************************************************/
196  /*                                                                       */
197  /* <Type>                                                                */
198  /*    FTC_Font                                                           */
199  /*                                                                       */
200  /* <Description>                                                         */
201  /*    A simple handle to an @FTC_FontRec structure.                      */
202  /*                                                                       */
203  typedef FTC_FontRec*  FTC_Font;
204
205
206  /*************************************************************************/
207  /*************************************************************************/
208  /*************************************************************************/
209  /*****                                                               *****/
210  /*****                      CACHE MANAGER OBJECT                     *****/
211  /*****                                                               *****/
212  /*************************************************************************/
213  /*************************************************************************/
214  /*************************************************************************/
215
216
217  /*************************************************************************/
218  /*                                                                       */
219  /* <Type>                                                                */
220  /*    FTC_Manager                                                        */
221  /*                                                                       */
222  /* <Description>                                                         */
223  /*    This object is used to cache one or more @FT_Face objects, along   */
224  /*    with corresponding @FT_Size objects.                               */
225  /*                                                                       */
226  typedef struct FTC_ManagerRec_*  FTC_Manager;
227
228
229  /*************************************************************************/
230  /*                                                                       */
231  /* <Type>                                                                */
232  /*    FTC_Node                                                           */
233  /*                                                                       */
234  /* <Description>                                                         */
235  /*    An opaque handle to a cache node object.  Each cache node is       */
236  /*    reference-counted.  A node with a count of 0 might be flushed      */
237  /*    out of a full cache whenever a lookup request is performed.        */
238  /*                                                                       */
239  /*    If you lookup nodes, you have the ability to "acquire" them, i.e., */
240  /*    to increment their reference count.  This will prevent the node    */
241  /*    from being flushed out of the cache until you explicitly "release" */
242  /*    it (see @FTC_Node_Unref).                                          */
243  /*                                                                       */
244  /*    See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup.         */
245  /*                                                                       */
246  typedef struct FTC_NodeRec_*  FTC_Node;
247
248
249  /*************************************************************************/
250  /*                                                                       */
251  /* <Function>                                                            */
252  /*    FTC_Manager_New                                                    */
253  /*                                                                       */
254  /* <Description>                                                         */
255  /*    Creates a new cache manager.                                       */
256  /*                                                                       */
257  /* <Input>                                                               */
258  /*    library     :: The parent FreeType library handle to use.          */
259  /*                                                                       */
260  /*    max_bytes   :: Maximum number of bytes to use for cached data.     */
261  /*                   Use 0 for defaults.                                 */
262  /*                                                                       */
263  /*    requester   :: An application-provided callback used to translate  */
264  /*                   face IDs into real @FT_Face objects.                */
265  /*                                                                       */
266  /*    req_data    :: A generic pointer that is passed to the requester   */
267  /*                   each time it is called (see @FTC_Face_Requester).   */
268  /*                                                                       */
269  /* <Output>                                                              */
270  /*    amanager  :: A handle to a new manager object.  0 in case of       */
271  /*                 failure.                                              */
272  /*                                                                       */
273  /* <Return>                                                              */
274  /*    FreeType error code.  0 means success.                             */
275  /*                                                                       */
276  FT_EXPORT( FT_Error )
277  FTC_Manager_New( FT_Library          library,
278                   FT_UInt             max_faces,
279                   FT_UInt             max_sizes,
280                   FT_ULong            max_bytes,
281                   FTC_Face_Requester  requester,
282                   FT_Pointer          req_data,
283                   FTC_Manager        *amanager );
284
285
286  /*************************************************************************/
287  /*                                                                       */
288  /* <Function>                                                            */
289  /*    FTC_Manager_Reset                                                  */
290  /*                                                                       */
291  /* <Description>                                                         */
292  /*    Empties a given cache manager.  This simply gets rid of all the    */
293  /*    currently cached @FT_Face and @FT_Size objects within the manager. */
294  /*                                                                       */
295  /* <InOut>                                                               */
296  /*    manager :: A handle to the manager.                                */
297  /*                                                                       */
298  FT_EXPORT( void )
299  FTC_Manager_Reset( FTC_Manager  manager );
300
301
302  /*************************************************************************/
303  /*                                                                       */
304  /* <Function>                                                            */
305  /*    FTC_Manager_Done                                                   */
306  /*                                                                       */
307  /* <Description>                                                         */
308  /*    Destroys a given manager after emptying it.                        */
309  /*                                                                       */
310  /* <Input>                                                               */
311  /*    manager :: A handle to the target cache manager object.            */
312  /*                                                                       */
313  FT_EXPORT( void )
314  FTC_Manager_Done( FTC_Manager  manager );
315
316
317  /*************************************************************************/
318  /*                                                                       */
319  /* <Function>                                                            */
320  /*    FTC_Manager_LookupFace                                             */
321  /*                                                                       */
322  /* <Description>                                                         */
323  /*    Retrieves the @FT_Face object that corresponds to a given face ID  */
324  /*    through a cache manager.                                           */
325  /*                                                                       */
326  /* <Input>                                                               */
327  /*    manager :: A handle to the cache manager.                          */
328  /*                                                                       */
329  /*    face_id :: The ID of the face object.                              */
330  /*                                                                       */
331  /* <Output>                                                              */
332  /*    aface   :: A handle to the face object.                            */
333  /*                                                                       */
334  /* <Return>                                                              */
335  /*    FreeType error code.  0 means success.                             */
336  /*                                                                       */
337  /* <Note>                                                                */
338  /*    The returned @FT_Face object is always owned by the manager.  You  */
339  /*    should never try to discard it yourself.                           */
340  /*                                                                       */
341  /*    The @FT_Face object doesn't necessarily have a current size object */
342  /*    (i.e., face->size can be 0).  If you need a specific `font size',  */
343  /*    use @FTC_Manager_LookupSize instead.                               */
344  /*                                                                       */
345  /*    Never change the face's transformation matrix (i.e., never call    */
346  /*    the @FT_Set_Transform function) on a returned face!  If you need   */
347  /*    to transform glyphs, do it yourself after glyph loading.           */
348  /*                                                                       */
349  FT_EXPORT( FT_Error )
350  FTC_Manager_LookupFace( FTC_Manager  manager,
351                          FTC_FaceID   face_id,
352                          FT_Face     *aface );
353
354
355  /*************************************************************************/
356  /*                                                                       */
357  /* <Struct>                                                              */
358  /*    FTC_ScalerRec                                                      */
359  /*                                                                       */
360  /* <Description>                                                         */
361  /*    A structure used to describe a given character size in either      */
362  /*    pixels or points to the cache manager.  See                        */
363  /*    @FTC_Manager_LookupSize.                                           */
364  /*                                                                       */
365  /* <Fields>                                                              */
366  /*    face_id :: The source face ID.                                     */
367  /*                                                                       */
368  /*    width   :: The character width.                                    */
369  /*                                                                       */
370  /*    height  :: The character height.                                   */
371  /*                                                                       */
372  /*    pixel   :: A Boolean.  If TRUE, the `width' and `height' fields    */
373  /*               are interpreted as integer pixel character sizes.       */
374  /*               Otherwise, they are expressed as 1/64th of points.      */
375  /*                                                                       */
376  /*    x_res   :: Only used when `pixel' is FALSE to indicate the         */
377  /*               horizontal resolution in dpi.                           */
378  /*                                                                       */
379  /*    y_res   :: Only used when `pixel' is FALSE to indicate the         */
380  /*               vertical resolution in dpi.                             */
381  /*                                                                       */
382  /* <Note>                                                                */
383  /*    This type is mainly used to retrieve @FT_Size objects through the  */
384  /*    cache manager.                                                     */
385  /*                                                                       */
386  typedef struct  FTC_ScalerRec_
387  {
388    FTC_FaceID  face_id;
389    FT_UInt     width;
390    FT_UInt     height;
391    FT_Int      pixel;
392    FT_UInt     x_res;
393    FT_UInt     y_res;
394
395  } FTC_ScalerRec, *FTC_Scaler;
396
397
398  /*************************************************************************/
399  /*                                                                       */
400  /* <Function>                                                            */
401  /*    FTC_Manager_LookupSize                                             */
402  /*                                                                       */
403  /* <Description>                                                         */
404  /*    Retrieve the @FT_Size object that corresponds to a given           */
405  /*    @FTC_Scaler through a cache manager.                               */
406  /*                                                                       */
407  /* <Input>                                                               */
408  /*    manager :: A handle to the cache manager.                          */
409  /*                                                                       */
410  /*    scaler  :: A scaler handle.                                        */
411  /*                                                                       */
412  /* <Output>                                                              */
413  /*    asize   :: A handle to the size object.                            */
414  /*                                                                       */
415  /* <Return>                                                              */
416  /*    FreeType error code.  0 means success.                             */
417  /*                                                                       */
418  /* <Note>                                                                */
419  /*    The returned @FT_Size object is always owned by the manager.  You  */
420  /*    should never try to discard it by yourself.                        */
421  /*                                                                       */
422  /*    You can access the parent @FT_Face object simply as `size->face'   */
423  /*    if you need it.  Note that this object is also owned by the        */
424  /*    manager.                                                           */
425  /*                                                                       */
426  FT_EXPORT( FT_Error )
427  FTC_Manager_LookupSize( FTC_Manager  manager,
428                          FTC_Scaler   scaler,
429                          FT_Size     *asize );
430
431
432  /*************************************************************************/
433  /*                                                                       */
434  /* <Function>                                                            */
435  /*    FTC_Node_Unref                                                     */
436  /*                                                                       */
437  /* <Description>                                                         */
438  /*    Decrement a cache node's internal reference count.  When the count */
439  /*    reaches 0, it is not destroyed but becomes eligible for subsequent */
440  /*    cache flushes.                                                     */
441  /*                                                                       */
442  /* <Input>                                                               */
443  /*    node    :: The cache node handle.                                  */
444  /*                                                                       */
445  /*    manager :: The cache manager handle.                               */
446  /*                                                                       */
447  FT_EXPORT( void )
448  FTC_Node_Unref( FTC_Node     node,
449                  FTC_Manager  manager );
450
451
452  /* remove all nodes belonging to a given face_id */
453  FT_EXPORT( void )
454  FTC_Manager_RemoveFaceID( FTC_Manager  manager,
455                            FTC_FaceID   face_id );
456
457
458  /*************************************************************************/
459  /*                                                                       */
460  /* <Section>                                                             */
461  /*    cache_subsystem                                                    */
462  /*                                                                       */
463  /*************************************************************************/
464
465  /************************************************************************
466   *
467   * @type:
468   *    FTC_CMapCache
469   *
470   * @description:
471   *    An opaque handle used to manager a charmap cache.  This cache is
472   *    to hold character codes -> glyph indices mappings.
473   */
474  typedef struct FTC_CMapCacheRec_*  FTC_CMapCache;
475
476
477  /*************************************************************************/
478  /*                                                                       */
479  /* @function:                                                            */
480  /*    FTC_CMapCache_New                                                  */
481  /*                                                                       */
482  /* @description:                                                         */
483  /*    Create a new charmap cache.                                        */
484  /*                                                                       */
485  /* @input:                                                               */
486  /*    manager :: A handle to the cache manager.                          */
487  /*                                                                       */
488  /* @output:                                                              */
489  /*    acache  :: A new cache handle.  NULL in case of error.             */
490  /*                                                                       */
491  /* @return:                                                              */
492  /*    FreeType error code.  0 means success.                             */
493  /*                                                                       */
494  /* @note:                                                                */
495  /*    Like all other caches, this one will be destroyed with the cache   */
496  /*    manager.                                                           */
497  /*                                                                       */
498  FT_EXPORT( FT_Error )
499  FTC_CMapCache_New( FTC_Manager     manager,
500                     FTC_CMapCache  *acache );
501
502
503  /*************************************************************************/
504  /*                                                                       */
505  /* @function:                                                            */
506  /*    FTC_CMapCache_Lookup                                               */
507  /*                                                                       */
508  /* @description:                                                         */
509  /*    Translate a character code into a glyph index, using the charmap   */
510  /*    cache.                                                             */
511  /*                                                                       */
512  /* @input:                                                               */
513  /*    cache      :: A charmap cache handle.                              */
514  /*                                                                       */
515  /*    face_id    :: The source face ID.                                  */
516  /*                                                                       */
517  /*    cmap_index :: The index of the charmap in the source face.         */
518  /*                                                                       */
519  /*    char_code  :: The character code (in the corresponding charmap).   */
520  /*                                                                       */
521  /* @return:                                                              */
522  /*    Glyph index.  0 means `no glyph'.                                  */
523  /*                                                                       */
524  FT_EXPORT( FT_UInt )
525  FTC_CMapCache_Lookup( FTC_CMapCache  cache,
526                        FTC_FaceID     face_id,
527                        FT_Int         cmap_index,
528                        FT_UInt32      char_code );
529
530
531  /*************************************************************************/
532  /*                                                                       */
533  /* <Section>                                                             */
534  /*    cache_subsystem                                                    */
535  /*                                                                       */
536  /*************************************************************************/
537
538
539  /*************************************************************************/
540  /*************************************************************************/
541  /*************************************************************************/
542  /*****                                                               *****/
543  /*****                       IMAGE CACHE OBJECT                      *****/
544  /*****                                                               *****/
545  /*************************************************************************/
546  /*************************************************************************/
547  /*************************************************************************/
548
549  typedef struct  FTC_ImageTypeRec_
550  {
551    FTC_FaceID   face_id;
552    FT_Int       width;
553    FT_Int       height;
554    FT_Int32     flags;
555
556  } FTC_ImageTypeRec;
557
558  typedef struct FTC_ImageTypeRec_*   FTC_ImageType;
559
560 /* */
561
562#define FTC_IMAGE_TYPE_COMPARE( d1, d2 )                    \
563          ( FTC_FONT_COMPARE( &(d1)->font, &(d2)->font ) && \
564            (d1)->flags == (d2)->flags                   )
565
566#define FTC_IMAGE_TYPE_HASH( d )                    \
567          (FT_UFast)( FTC_FONT_HASH( &(d)->font ) ^ \
568                      ( (d)->flags << 4 )         )
569
570
571  /*************************************************************************/
572  /*                                                                       */
573  /* <Type>                                                                */
574  /*    FTC_ImageCache                                                     */
575  /*                                                                       */
576  /* <Description>                                                         */
577  /*    A handle to an glyph image cache object.  They are designed to     */
578  /*    hold many distinct glyph images while not exceeding a certain      */
579  /*    memory threshold.                                                  */
580  /*                                                                       */
581  typedef struct FTC_ImageCacheRec_*  FTC_ImageCache;
582
583
584  /*************************************************************************/
585  /*                                                                       */
586  /* <Function>                                                            */
587  /*    FTC_ImageCache_New                                                 */
588  /*                                                                       */
589  /* <Description>                                                         */
590  /*    Creates a new glyph image cache.                                   */
591  /*                                                                       */
592  /* <Input>                                                               */
593  /*    manager :: The parent manager for the image cache.                 */
594  /*                                                                       */
595  /* <Output>                                                              */
596  /*    acache  :: A handle to the new glyph image cache object.           */
597  /*                                                                       */
598  /* <Return>                                                              */
599  /*    FreeType error code.  0 means success.                             */
600  /*                                                                       */
601  FT_EXPORT( FT_Error )
602  FTC_ImageCache_New( FTC_Manager      manager,
603                      FTC_ImageCache  *acache );
604
605
606  /*************************************************************************/
607  /*                                                                       */
608  /* <Function>                                                            */
609  /*    FTC_ImageCache_Lookup                                              */
610  /*                                                                       */
611  /* <Description>                                                         */
612  /*    Retrieves a given glyph image from a glyph image cache.            */
613  /*                                                                       */
614  /* <Input>                                                               */
615  /*    cache  :: A handle to the source glyph image cache.                */
616  /*                                                                       */
617  /*    type   :: A pointer to a glyph image type descriptor.              */
618  /*                                                                       */
619  /*    gindex :: The glyph index to retrieve.                             */
620  /*                                                                       */
621  /* <Output>                                                              */
622  /*    aglyph :: The corresponding @FT_Glyph object.  0 in case of        */
623  /*              failure.                                                 */
624  /*                                                                       */
625  /*    anode  :: Used to return the address of of the corresponding cache */
626  /*              node after incrementing its reference count (see note    */
627  /*              below).                                                  */
628  /*                                                                       */
629  /* <Return>                                                              */
630  /*    FreeType error code.  0 means success.                             */
631  /*                                                                       */
632  /* <Note>                                                                */
633  /*    The returned glyph is owned and managed by the glyph image cache.  */
634  /*    Never try to transform or discard it manually!  You can however    */
635  /*    create a copy with @FT_Glyph_Copy and modify the new one.          */
636  /*                                                                       */
637  /*    If `anode' is _not_ NULL, it receives the address of the cache     */
638  /*    node containing the glyph image, after increasing its reference    */
639  /*    count.  This ensures that the node (as well as the FT_Glyph) will  */
640  /*    always be kept in the cache until you call @FTC_Node_Unref to      */
641  /*    `release' it.                                                      */
642  /*                                                                       */
643  /*    If `anode' is NULL, the cache node is left unchanged, which means  */
644  /*    that the FT_Glyph could be flushed out of the cache on the next    */
645  /*    call to one of the caching sub-system APIs.  Don't assume that it  */
646  /*    is persistent!                                                     */
647  /*                                                                       */
648  FT_EXPORT( FT_Error )
649  FTC_ImageCache_Lookup( FTC_ImageCache  cache,
650                         FTC_ImageType   type,
651                         FT_UInt         gindex,
652                         FT_Glyph       *aglyph,
653                         FTC_Node       *anode );
654
655
656  /*************************************************************************/
657  /*                                                                       */
658  /* <Type>                                                                */
659  /*    FTC_SBit                                                           */
660  /*                                                                       */
661  /* <Description>                                                         */
662  /*    A handle to a small bitmap descriptor.  See the @FTC_SBitRec       */
663  /*    structure for details.                                             */
664  /*                                                                       */
665  typedef struct FTC_SBitRec_*  FTC_SBit;
666
667
668  /*************************************************************************/
669  /*                                                                       */
670  /* <Struct>                                                              */
671  /*    FTC_SBitRec                                                        */
672  /*                                                                       */
673  /* <Description>                                                         */
674  /*    A very compact structure used to describe a small glyph bitmap.    */
675  /*                                                                       */
676  /* <Fields>                                                              */
677  /*    width     :: The bitmap width in pixels.                           */
678  /*                                                                       */
679  /*    height    :: The bitmap height in pixels.                          */
680  /*                                                                       */
681  /*    left      :: The horizontal distance from the pen position to the  */
682  /*                 left bitmap border (a.k.a. `left side bearing', or    */
683  /*                 `lsb').                                               */
684  /*                                                                       */
685  /*    top       :: The vertical distance from the pen position (on the   */
686  /*                 baseline) to the upper bitmap border (a.k.a. `top     */
687  /*                 side bearing').  The distance is positive for upwards */
688  /*                 Y coordinates.                                        */
689  /*                                                                       */
690  /*    format    :: The format of the glyph bitmap (monochrome or gray).  */
691  /*                                                                       */
692  /*    max_grays :: Maximum gray level value (in the range 1 to 255).     */
693  /*                                                                       */
694  /*    pitch     :: The number of bytes per bitmap line.  May be positive */
695  /*                 or negative.                                          */
696  /*                                                                       */
697  /*    xadvance  :: The horizontal advance width in pixels.               */
698  /*                                                                       */
699  /*    yadvance  :: The vertical advance height in pixels.                */
700  /*                                                                       */
701  /*    buffer    :: A pointer to the bitmap pixels.                       */
702  /*                                                                       */
703  typedef struct  FTC_SBitRec_
704  {
705    FT_Byte   width;
706    FT_Byte   height;
707    FT_Char   left;
708    FT_Char   top;
709
710    FT_Byte   format;
711    FT_Byte   max_grays;
712    FT_Short  pitch;
713    FT_Char   xadvance;
714    FT_Char   yadvance;
715
716    FT_Byte*  buffer;
717
718  } FTC_SBitRec;
719
720
721  /*************************************************************************/
722  /*                                                                       */
723  /* <Type>                                                                */
724  /*    FTC_SBitCache                                                      */
725  /*                                                                       */
726  /* <Description>                                                         */
727  /*    A handle to a small bitmap cache.  These are special cache objects */
728  /*    used to store small glyph bitmaps (and anti-aliased pixmaps) in a  */
729  /*    much more efficient way than the traditional glyph image cache     */
730  /*    implemented by @FTC_ImageCache.                                    */
731  /*                                                                       */
732  typedef struct FTC_SBitCacheRec_*  FTC_SBitCache;
733
734
735  /*************************************************************************/
736  /*                                                                       */
737  /* <Function>                                                            */
738  /*    FTC_SBitCache_New                                                  */
739  /*                                                                       */
740  /* <Description>                                                         */
741  /*    Creates a new cache to store small glyph bitmaps.                  */
742  /*                                                                       */
743  /* <Input>                                                               */
744  /*    manager :: A handle to the source cache manager.                   */
745  /*                                                                       */
746  /* <Output>                                                              */
747  /*    acache  :: A handle to the new sbit cache.  NULL in case of error. */
748  /*                                                                       */
749  /* <Return>                                                              */
750  /*    FreeType error code.  0 means success.                             */
751  /*                                                                       */
752  FT_EXPORT( FT_Error )
753  FTC_SBitCache_New( FTC_Manager     manager,
754                     FTC_SBitCache  *acache );
755
756
757  /*************************************************************************/
758  /*                                                                       */
759  /* <Function>                                                            */
760  /*    FTC_SBitCache_Lookup                                               */
761  /*                                                                       */
762  /* <Description>                                                         */
763  /*    Looks up a given small glyph bitmap in a given sbit cache and      */
764  /*    `lock' it to prevent its flushing from the cache until needed.     */
765  /*                                                                       */
766  /* <Input>                                                               */
767  /*    cache  :: A handle to the source sbit cache.                       */
768  /*                                                                       */
769  /*    type   :: A pointer to the glyph image type descriptor.            */
770  /*                                                                       */
771  /*    gindex :: The glyph index.                                         */
772  /*                                                                       */
773  /* <Output>                                                              */
774  /*    sbit   :: A handle to a small bitmap descriptor.                   */
775  /*                                                                       */
776  /*    anode  :: Used to return the address of of the corresponding cache */
777  /*              node after incrementing its reference count (see note    */
778  /*              below).                                                  */
779  /*                                                                       */
780  /* <Return>                                                              */
781  /*    FreeType error code.  0 means success.                             */
782  /*                                                                       */
783  /* <Note>                                                                */
784  /*    The small bitmap descriptor and its bit buffer are owned by the    */
785  /*    cache and should never be freed by the application.  They might    */
786  /*    as well disappear from memory on the next cache lookup, so don't   */
787  /*    treat them as persistent data.                                     */
788  /*                                                                       */
789  /*    The descriptor's `buffer' field is set to 0 to indicate a missing  */
790  /*    glyph bitmap.                                                      */
791  /*                                                                       */
792  /*    If `anode' is _not_ NULL, it receives the address of the cache     */
793  /*    node containing the bitmap, after increasing its reference count.  */
794  /*    This ensures that the node (as well as the image) will always be   */
795  /*    kept in the cache until you call @FTC_Node_Unref to `release' it.  */
796  /*                                                                       */
797  /*    If `anode' is NULL, the cache node is left unchanged, which means  */
798  /*    that the bitmap could be flushed out of the cache on the next      */
799  /*    call to one of the caching sub-system APIs.  Don't assume that it  */
800  /*    is persistent!                                                     */
801  /*                                                                       */
802  FT_EXPORT( FT_Error )
803  FTC_SBitCache_Lookup( FTC_SBitCache    cache,
804                        FTC_ImageType    type,
805                        FT_UInt          gindex,
806                        FTC_SBit        *sbit,
807                        FTC_Node        *anode );
808
809
810 /* */
811
812FT_END_HEADER
813
814#endif /* __FTCACHE_H__ */
815
816
817/* END */
Note: See TracBrowser for help on using the repository browser.