projects / reactos.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
history | raw | HEAD
Sync with trunk head
[reactos.git] / lib / 3rdparty / freetype / include / freetype / ftcache.h
1 /***************************************************************************/
2 /* */
3 /* ftcache.h */
4 /* */
5 /* FreeType Cache subsystem (specification). */
6 /* */
7 /* Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006, 2007 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 #ifndef __FTCACHE_H__
20 #define __FTCACHE_H__
21
22
23 #include <ft2build.h>
24 #include FT_GLYPH_H
25
26
27 FT_BEGIN_HEADER
28
29
30 /*************************************************************************
31 *
32 * <Section>
33 * cache_subsystem
34 *
35 * <Title>
36 * Cache Sub-System
37 *
38 * <Abstract>
39 * How to cache face, size, and glyph data with FreeType 2.
40 *
41 * <Description>
42 * This section describes the FreeType 2 cache sub-system, which is used
43 * to limit the number of concurrently opened @FT_Face and @FT_Size
44 * objects, as well as caching information like character maps and glyph
45 * images while limiting their maximum memory usage.
46 *
47 * Note that all types and functions begin with the `FTC_' prefix.
48 *
49 * The cache is highly portable and thus doesn't know anything about the
50 * fonts installed on your system, or how to access them. This implies
51 * the following scheme:
52 *
53 * First, available or installed font faces are uniquely identified by
54 * @FTC_FaceID values, provided to the cache by the client. Note that
55 * the cache only stores and compares these values, and doesn't try to
56 * interpret them in any way.
57 *
58 * Second, the cache calls, only when needed, a client-provided function
59 * to convert a @FTC_FaceID into a new @FT_Face object. The latter is
60 * then completely managed by the cache, including its termination
61 * through @FT_Done_Face.
62 *
63 * Clients are free to map face IDs to anything else. The most simple
64 * usage is to associate them to a (pathname,face_index) pair that is
65 * used to call @FT_New_Face. However, more complex schemes are also
66 * possible.
67 *
68 * Note that for the cache to work correctly, the face ID values must be
69 * *persistent*, which means that the contents they point to should not
70 * change at runtime, or that their value should not become invalid.
71 *
72 * If this is unavoidable (e.g., when a font is uninstalled at runtime),
73 * you should call @FTC_Manager_RemoveFaceID as soon as possible, to let
74 * the cache get rid of any references to the old @FTC_FaceID it may
75 * keep internally. Failure to do so will lead to incorrect behaviour
76 * or even crashes.
77 *
78 * To use the cache, start with calling @FTC_Manager_New to create a new
79 * @FTC_Manager object, which models a single cache instance. You can
80 * then look up @FT_Face and @FT_Size objects with
81 * @FTC_Manager_LookupFace and @FTC_Manager_LookupSize, respectively.
82 *
83 * If you want to use the charmap caching, call @FTC_CMapCache_New, then
84 * later use @FTC_CMapCache_Lookup to perform the equivalent of
85 * @FT_Get_Char_Index, only much faster.
86 *
87 * If you want to use the @FT_Glyph caching, call @FTC_ImageCache, then
88 * later use @FTC_ImageCache_Lookup to retrieve the corresponding
89 * @FT_Glyph objects from the cache.
90 *
91 * If you need lots of small bitmaps, it is much more memory efficient
92 * to call @FTC_SBitCache_New followed by @FTC_SBitCache_Lookup. This
93 * returns @FTC_SBitRec structures, which are used to store small
94 * bitmaps directly. (A small bitmap is one whose metrics and
95 * dimensions all fit into 8-bit integers).
96 *
97 * We hope to also provide a kerning cache in the near future.
98 *
99 *
100 * <Order>
101 * FTC_Manager
102 * FTC_FaceID
103 * FTC_Face_Requester
104 *
105 * FTC_Manager_New
106 * FTC_Manager_Reset
107 * FTC_Manager_Done
108 * FTC_Manager_LookupFace
109 * FTC_Manager_LookupSize
110 * FTC_Manager_RemoveFaceID
111 *
112 * FTC_Node
113 * FTC_Node_Unref
114 *
115 * FTC_ImageCache
116 * FTC_ImageCache_New
117 * FTC_ImageCache_Lookup
118 *
119 * FTC_SBit
120 * FTC_SBitCache
121 * FTC_SBitCache_New
122 * FTC_SBitCache_Lookup
123 *
124 * FTC_CMapCache
125 * FTC_CMapCache_New
126 * FTC_CMapCache_Lookup
127 *
128 *************************************************************************/
129
130
131 /*************************************************************************/
132 /*************************************************************************/
133 /*************************************************************************/
134 /***** *****/
135 /***** BASIC TYPE DEFINITIONS *****/
136 /***** *****/
137 /*************************************************************************/
138 /*************************************************************************/
139 /*************************************************************************/
140
141
142 /*************************************************************************
143 *
144 * @type: FTC_FaceID
145 *
146 * @description:
147 * An opaque pointer type that is used to identity face objects. The
148 * contents of such objects is application-dependent.
149 *
150 * These pointers are typically used to point to a user-defined
151 * structure containing a font file path, and face index.
152 *
153 * @note:
154 * Never use NULL as a valid @FTC_FaceID.
155 *
156 * Face IDs are passed by the client to the cache manager, which calls,
157 * when needed, the @FTC_Face_Requester to translate them into new
158 * @FT_Face objects.
159 *
160 * If the content of a given face ID changes at runtime, or if the value
161 * becomes invalid (e.g., when uninstalling a font), you should
162 * immediately call @FTC_Manager_RemoveFaceID before any other cache
163 * function.
164 *
165 * Failure to do so will result in incorrect behaviour or even
166 * memory leaks and crashes.
167 */
168 typedef struct FTC_FaceIDRec_* FTC_FaceID;
169
170
171 /************************************************************************
172 *
173 * @functype:
174 * FTC_Face_Requester
175 *
176 * @description:
177 * A callback function provided by client applications. It is used by
178 * the cache manager to translate a given @FTC_FaceID into a new valid
179 * @FT_Face object, on demand.
180 *
181 * <Input>
182 * face_id ::
183 * The face ID to resolve.
184 *
185 * library ::
186 * A handle to a FreeType library object.
187 *
188 * req_data ::
189 * Application-provided request data (see note below).
190 *
191 * <Output>
192 * aface ::
193 * A new @FT_Face handle.
194 *
195 * <Return>
196 * FreeType error code. 0 means success.
197 *
198 * <Note>
199 * The third parameter `req_data' is the same as the one passed by the
200 * client when @FTC_Manager_New is called.
201 *
202 * The face requester should not perform funny things on the returned
203 * face object, like creating a new @FT_Size for it, or setting a
204 * transformation through @FT_Set_Transform!
205 */
206 typedef FT_Error
207 (*FTC_Face_Requester)( FTC_FaceID face_id,
208 FT_Library library,
209 FT_Pointer request_data,
210 FT_Face* aface );
211
212 /* */
213
214 #define FT_POINTER_TO_ULONG( p ) ( (FT_ULong)(FT_Pointer)(p) )
215
216 #define FTC_FACE_ID_HASH( i ) \
217 ((FT_UInt32)(( FT_POINTER_TO_ULONG( i ) >> 3 ) ^ \
218 ( FT_POINTER_TO_ULONG( i ) << 7 ) ) )
219
220
221 /*************************************************************************/
222 /*************************************************************************/
223 /*************************************************************************/
224 /***** *****/
225 /***** CACHE MANAGER OBJECT *****/
226 /***** *****/
227 /*************************************************************************/
228 /*************************************************************************/
229 /*************************************************************************/
230
231
232 /*************************************************************************/
233 /* */
234 /* <Type> */
235 /* FTC_Manager */
236 /* */
237 /* <Description> */
238 /* This object corresponds to one instance of the cache-subsystem. */
239 /* It is used to cache one or more @FT_Face objects, along with */
240 /* corresponding @FT_Size objects. */
241 /* */
242 /* The manager intentionally limits the total number of opened */
243 /* @FT_Face and @FT_Size objects to control memory usage. See the */
244 /* `max_faces' and `max_sizes' parameters of @FTC_Manager_New. */
245 /* */
246 /* The manager is also used to cache `nodes' of various types while */
247 /* limiting their total memory usage. */
248 /* */
249 /* All limitations are enforced by keeping lists of managed objects */
250 /* in most-recently-used order, and flushing old nodes to make room */
251 /* for new ones. */
252 /* */
253 typedef struct FTC_ManagerRec_* FTC_Manager;
254
255
256 /*************************************************************************/
257 /* */
258 /* <Type> */
259 /* FTC_Node */
260 /* */
261 /* <Description> */
262 /* An opaque handle to a cache node object. Each cache node is */
263 /* reference-counted. A node with a count of 0 might be flushed */
264 /* out of a full cache whenever a lookup request is performed. */
265 /* */
266 /* If you lookup nodes, you have the ability to `acquire' them, i.e., */
267 /* to increment their reference count. This will prevent the node */
268 /* from being flushed out of the cache until you explicitly `release' */
269 /* it (see @FTC_Node_Unref). */
270 /* */
271 /* See also @FTC_SBitCache_Lookup and @FTC_ImageCache_Lookup. */
272 /* */
273 typedef struct FTC_NodeRec_* FTC_Node;
274
275
276 /*************************************************************************/
277 /* */
278 /* <Function> */
279 /* FTC_Manager_New */
280 /* */
281 /* <Description> */
282 /* Creates a new cache manager. */
283 /* */
284 /* <Input> */
285 /* library :: The parent FreeType library handle to use. */
286 /* */
287 /* max_faces :: Maximum number of opened @FT_Face objects managed by */
288 /* this cache instance. Use 0 for defaults. */
289 /* */
290 /* max_sizes :: Maximum number of opened @FT_Size objects managed by */
291 /* this cache instance. Use 0 for defaults. */
292 /* */
293 /* max_bytes :: Maximum number of bytes to use for cached data nodes. */
294 /* Use 0 for defaults. Note that this value does not */
295 /* account for managed @FT_Face and @FT_Size objects. */
296 /* */
297 /* requester :: An application-provided callback used to translate */
298 /* face IDs into real @FT_Face objects. */
299 /* */
300 /* req_data :: A generic pointer that is passed to the requester */
301 /* each time it is called (see @FTC_Face_Requester). */
302 /* */
303 /* <Output> */
304 /* amanager :: A handle to a new manager object. 0 in case of */
305 /* failure. */
306 /* */
307 /* <Return> */
308 /* FreeType error code. 0 means success. */
309 /* */
310 FT_EXPORT( FT_Error )
311 FTC_Manager_New( FT_Library library,
312 FT_UInt max_faces,
313 FT_UInt max_sizes,
314 FT_ULong max_bytes,
315 FTC_Face_Requester requester,
316 FT_Pointer req_data,
317 FTC_Manager *amanager );
318
319
320 /*************************************************************************/
321 /* */
322 /* <Function> */
323 /* FTC_Manager_Reset */
324 /* */
325 /* <Description> */
326 /* Empties a given cache manager. This simply gets rid of all the */
327 /* currently cached @FT_Face and @FT_Size objects within the manager. */
328 /* */
329 /* <InOut> */
330 /* manager :: A handle to the manager. */
331 /* */
332 FT_EXPORT( void )
333 FTC_Manager_Reset( FTC_Manager manager );
334
335
336 /*************************************************************************/
337 /* */
338 /* <Function> */
339 /* FTC_Manager_Done */
340 /* */
341 /* <Description> */
342 /* Destroys a given manager after emptying it. */
343 /* */
344 /* <Input> */
345 /* manager :: A handle to the target cache manager object. */
346 /* */
347 FT_EXPORT( void )
348 FTC_Manager_Done( FTC_Manager manager );
349
350
351 /*************************************************************************/
352 /* */
353 /* <Function> */
354 /* FTC_Manager_LookupFace */
355 /* */
356 /* <Description> */
357 /* Retrieves the @FT_Face object that corresponds to a given face ID */
358 /* through a cache manager. */
359 /* */
360 /* <Input> */
361 /* manager :: A handle to the cache manager. */
362 /* */
363 /* face_id :: The ID of the face object. */
364 /* */
365 /* <Output> */
366 /* aface :: A handle to the face object. */
367 /* */
368 /* <Return> */
369 /* FreeType error code. 0 means success. */
370 /* */
371 /* <Note> */
372 /* The returned @FT_Face object is always owned by the manager. You */
373 /* should never try to discard it yourself. */
374 /* */
375 /* The @FT_Face object doesn't necessarily have a current size object */
376 /* (i.e., face->size can be 0). If you need a specific `font size', */
377 /* use @FTC_Manager_LookupSize instead. */
378 /* */
379 /* Never change the face's transformation matrix (i.e., never call */
380 /* the @FT_Set_Transform function) on a returned face! If you need */
381 /* to transform glyphs, do it yourself after glyph loading. */
382 /* */
383 /* When you perform a lookup, out-of-memory errors are detected */
384 /* _within_ the lookup and force incremental flushes of the cache */
385 /* until enough memory is released for the lookup to succeed. */
386 /* */
387 /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */
388 /* already been completely flushed, and still no memory was available */
389 /* for the operation. */
390 /* */
391 FT_EXPORT( FT_Error )
392 FTC_Manager_LookupFace( FTC_Manager manager,
393 FTC_FaceID face_id,
394 FT_Face *aface );
395
396
397 /*************************************************************************/
398 /* */
399 /* <Struct> */
400 /* FTC_ScalerRec */
401 /* */
402 /* <Description> */
403 /* A structure used to describe a given character size in either */
404 /* pixels or points to the cache manager. See */
405 /* @FTC_Manager_LookupSize. */
406 /* */
407 /* <Fields> */
408 /* face_id :: The source face ID. */
409 /* */
410 /* width :: The character width. */
411 /* */
412 /* height :: The character height. */
413 /* */
414 /* pixel :: A Boolean. If 1, the `width' and `height' fields are */
415 /* interpreted as integer pixel character sizes. */
416 /* Otherwise, they are expressed as 1/64th of points. */
417 /* */
418 /* x_res :: Only used when `pixel' is value 0 to indicate the */
419 /* horizontal resolution in dpi. */
420 /* */
421 /* y_res :: Only used when `pixel' is value 0 to indicate the */
422 /* vertical resolution in dpi. */
423 /* */
424 /* <Note> */
425 /* This type is mainly used to retrieve @FT_Size objects through the */
426 /* cache manager. */
427 /* */
428 typedef struct FTC_ScalerRec_
429 {
430 FTC_FaceID face_id;
431 FT_UInt width;
432 FT_UInt height;
433 FT_Int pixel;
434 FT_UInt x_res;
435 FT_UInt y_res;
436
437 } FTC_ScalerRec, *FTC_Scaler;
438
439
440 /*************************************************************************/
441 /* */
442 /* <Function> */
443 /* FTC_Manager_LookupSize */
444 /* */
445 /* <Description> */
446 /* Retrieve the @FT_Size object that corresponds to a given */
447 /* @FTC_ScalerRec pointer through a cache manager. */
448 /* */
449 /* <Input> */
450 /* manager :: A handle to the cache manager. */
451 /* */
452 /* scaler :: A scaler handle. */
453 /* */
454 /* <Output> */
455 /* asize :: A handle to the size object. */
456 /* */
457 /* <Return> */
458 /* FreeType error code. 0 means success. */
459 /* */
460 /* <Note> */
461 /* The returned @FT_Size object is always owned by the manager. You */
462 /* should never try to discard it by yourself. */
463 /* */
464 /* You can access the parent @FT_Face object simply as `size->face' */
465 /* if you need it. Note that this object is also owned by the */
466 /* manager. */
467 /* */
468 /* <Note> */
469 /* When you perform a lookup, out-of-memory errors are detected */
470 /* _within_ the lookup and force incremental flushes of the cache */
471 /* until enough memory is released for the lookup to succeed. */
472 /* */
473 /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */
474 /* already been completely flushed, and still no memory is available */
475 /* for the operation. */
476 /* */
477 FT_EXPORT( FT_Error )
478 FTC_Manager_LookupSize( FTC_Manager manager,
479 FTC_Scaler scaler,
480 FT_Size *asize );
481
482
483 /*************************************************************************/
484 /* */
485 /* <Function> */
486 /* FTC_Node_Unref */
487 /* */
488 /* <Description> */
489 /* Decrement a cache node's internal reference count. When the count */
490 /* reaches 0, it is not destroyed but becomes eligible for subsequent */
491 /* cache flushes. */
492 /* */
493 /* <Input> */
494 /* node :: The cache node handle. */
495 /* */
496 /* manager :: The cache manager handle. */
497 /* */
498 FT_EXPORT( void )
499 FTC_Node_Unref( FTC_Node node,
500 FTC_Manager manager );
501
502
503 /*************************************************************************
504 *
505 * @function:
506 * FTC_Manager_RemoveFaceID
507 *
508 * @description:
509 * A special function used to indicate to the cache manager that
510 * a given @FTC_FaceID is no longer valid, either because its
511 * content changed, or because it was deallocated or uninstalled.
512 *
513 * @input:
514 * manager ::
515 * The cache manager handle.
516 *
517 * face_id ::
518 * The @FTC_FaceID to be removed.
519 *
520 * @note:
521 * This function flushes all nodes from the cache corresponding to this
522 * `face_id', with the exception of nodes with a non-null reference
523 * count.
524 *
525 * Such nodes are however modified internally so as to never appear
526 * in later lookups with the same `face_id' value, and to be immediately
527 * destroyed when released by all their users.
528 *
529 */
530 FT_EXPORT( void )
531 FTC_Manager_RemoveFaceID( FTC_Manager manager,
532 FTC_FaceID face_id );
533
534
535 /*************************************************************************/
536 /* */
537 /* <Section> */
538 /* cache_subsystem */
539 /* */
540 /*************************************************************************/
541
542 /*************************************************************************
543 *
544 * @type:
545 * FTC_CMapCache
546 *
547 * @description:
548 * An opaque handle used to model a charmap cache. This cache is to
549 * hold character codes -> glyph indices mappings.
550 *
551 */
552 typedef struct FTC_CMapCacheRec_* FTC_CMapCache;
553
554
555 /*************************************************************************
556 *
557 * @function:
558 * FTC_CMapCache_New
559 *
560 * @description:
561 * Create a new charmap cache.
562 *
563 * @input:
564 * manager ::
565 * A handle to the cache manager.
566 *
567 * @output:
568 * acache ::
569 * A new cache handle. NULL in case of error.
570 *
571 * @return:
572 * FreeType error code. 0 means success.
573 *
574 * @note:
575 * Like all other caches, this one will be destroyed with the cache
576 * manager.
577 *
578 */
579 FT_EXPORT( FT_Error )
580 FTC_CMapCache_New( FTC_Manager manager,
581 FTC_CMapCache *acache );
582
583
584 /************************************************************************
585 *
586 * @function:
587 * FTC_CMapCache_Lookup
588 *
589 * @description:
590 * Translate a character code into a glyph index, using the charmap
591 * cache.
592 *
593 * @input:
594 * cache ::
595 * A charmap cache handle.
596 *
597 * face_id ::
598 * The source face ID.
599 *
600 * cmap_index ::
601 * The index of the charmap in the source face.
602 *
603 * char_code ::
604 * The character code (in the corresponding charmap).
605 *
606 * @return:
607 * Glyph index. 0 means `no glyph'.
608 *
609 */
610 FT_EXPORT( FT_UInt )
611 FTC_CMapCache_Lookup( FTC_CMapCache cache,
612 FTC_FaceID face_id,
613 FT_Int cmap_index,
614 FT_UInt32 char_code );
615
616
617 /*************************************************************************/
618 /* */
619 /* <Section> */
620 /* cache_subsystem */
621 /* */
622 /*************************************************************************/
623
624
625 /*************************************************************************/
626 /*************************************************************************/
627 /*************************************************************************/
628 /***** *****/
629 /***** IMAGE CACHE OBJECT *****/
630 /***** *****/
631 /*************************************************************************/
632 /*************************************************************************/
633 /*************************************************************************/
634
635
636 /*************************************************************************
637 *
638 * @struct:
639 * FTC_ImageTypeRec
640 *
641 * @description:
642 * A structure used to model the type of images in a glyph cache.
643 *
644 * @fields:
645 * face_id ::
646 * The face ID.
647 *
648 * width ::
649 * The width in pixels.
650 *
651 * height ::
652 * The height in pixels.
653 *
654 * flags ::
655 * The load flags, as in @FT_Load_Glyph.
656 *
657 */
658 typedef struct FTC_ImageTypeRec_
659 {
660 FTC_FaceID face_id;
661 FT_Int width;
662 FT_Int height;
663 FT_Int32 flags;
664
665 } FTC_ImageTypeRec;
666
667
668 /*************************************************************************
669 *
670 * @type:
671 * FTC_ImageType
672 *
673 * @description:
674 * A handle to an @FTC_ImageTypeRec structure.
675 *
676 */
677 typedef struct FTC_ImageTypeRec_* FTC_ImageType;
678
679
680 /* */
681
682
683 #define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \
684 ( (d1)->face_id == (d2)->face_id && \
685 (d1)->width == (d2)->width && \
686 (d1)->flags == (d2)->flags )
687
688 #define FTC_IMAGE_TYPE_HASH( d ) \
689 (FT_UFast)( FTC_FACE_ID_HASH( (d)->face_id ) ^ \
690 ( (d)->width << 8 ) ^ (d)->height ^ \
691 ( (d)->flags << 4 ) )
692
693
694 /*************************************************************************/
695 /* */
696 /* <Type> */
697 /* FTC_ImageCache */
698 /* */
699 /* <Description> */
700 /* A handle to an glyph image cache object. They are designed to */
701 /* hold many distinct glyph images while not exceeding a certain */
702 /* memory threshold. */
703 /* */
704 typedef struct FTC_ImageCacheRec_* FTC_ImageCache;
705
706
707 /*************************************************************************/
708 /* */
709 /* <Function> */
710 /* FTC_ImageCache_New */
711 /* */
712 /* <Description> */
713 /* Creates a new glyph image cache. */
714 /* */
715 /* <Input> */
716 /* manager :: The parent manager for the image cache. */
717 /* */
718 /* <Output> */
719 /* acache :: A handle to the new glyph image cache object. */
720 /* */
721 /* <Return> */
722 /* FreeType error code. 0 means success. */
723 /* */
724 FT_EXPORT( FT_Error )
725 FTC_ImageCache_New( FTC_Manager manager,
726 FTC_ImageCache *acache );
727
728
729 /*************************************************************************/
730 /* */
731 /* <Function> */
732 /* FTC_ImageCache_Lookup */
733 /* */
734 /* <Description> */
735 /* Retrieves a given glyph image from a glyph image cache. */
736 /* */
737 /* <Input> */
738 /* cache :: A handle to the source glyph image cache. */
739 /* */
740 /* type :: A pointer to a glyph image type descriptor. */
741 /* */
742 /* gindex :: The glyph index to retrieve. */
743 /* */
744 /* <Output> */
745 /* aglyph :: The corresponding @FT_Glyph object. 0 in case of */
746 /* failure. */
747 /* */
748 /* anode :: Used to return the address of of the corresponding cache */
749 /* node after incrementing its reference count (see note */
750 /* below). */
751 /* */
752 /* <Return> */
753 /* FreeType error code. 0 means success. */
754 /* */
755 /* <Note> */
756 /* The returned glyph is owned and managed by the glyph image cache. */
757 /* Never try to transform or discard it manually! You can however */
758 /* create a copy with @FT_Glyph_Copy and modify the new one. */
759 /* */
760 /* If `anode' is _not_ NULL, it receives the address of the cache */
761 /* node containing the glyph image, after increasing its reference */
762 /* count. This ensures that the node (as well as the @FT_Glyph) will */
763 /* always be kept in the cache until you call @FTC_Node_Unref to */
764 /* `release' it. */
765 /* */
766 /* If `anode' is NULL, the cache node is left unchanged, which means */
767 /* that the @FT_Glyph could be flushed out of the cache on the next */
768 /* call to one of the caching sub-system APIs. Don't assume that it */
769 /* is persistent! */
770 /* */
771 FT_EXPORT( FT_Error )
772 FTC_ImageCache_Lookup( FTC_ImageCache cache,
773 FTC_ImageType type,
774 FT_UInt gindex,
775 FT_Glyph *aglyph,
776 FTC_Node *anode );
777
778
779 /*************************************************************************/
780 /* */
781 /* <Function> */
782 /* FTC_ImageCache_LookupScaler */
783 /* */
784 /* <Description> */
785 /* A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec */
786 /* to specify the face ID and its size. */
787 /* */
788 /* <Input> */
789 /* cache :: A handle to the source glyph image cache. */
790 /* */
791 /* scaler :: A pointer to a scaler descriptor. */
792 /* */
793 /* load_flags :: The corresponding load flags. */
794 /* */
795 /* gindex :: The glyph index to retrieve. */
796 /* */
797 /* <Output> */
798 /* aglyph :: The corresponding @FT_Glyph object. 0 in case of */
799 /* failure. */
800 /* */
801 /* anode :: Used to return the address of of the corresponding */
802 /* cache node after incrementing its reference count */
803 /* (see note below). */
804 /* */
805 /* <Return> */
806 /* FreeType error code. 0 means success. */
807 /* */
808 /* <Note> */
809 /* The returned glyph is owned and managed by the glyph image cache. */
810 /* Never try to transform or discard it manually! You can however */
811 /* create a copy with @FT_Glyph_Copy and modify the new one. */
812 /* */
813 /* If `anode' is _not_ NULL, it receives the address of the cache */
814 /* node containing the glyph image, after increasing its reference */
815 /* count. This ensures that the node (as well as the @FT_Glyph) will */
816 /* always be kept in the cache until you call @FTC_Node_Unref to */
817 /* `release' it. */
818 /* */
819 /* If `anode' is NULL, the cache node is left unchanged, which means */
820 /* that the @FT_Glyph could be flushed out of the cache on the next */
821 /* call to one of the caching sub-system APIs. Don't assume that it */
822 /* is persistent! */
823 /* */
824 FT_EXPORT( FT_Error )
825 FTC_ImageCache_LookupScaler( FTC_ImageCache cache,
826 FTC_Scaler scaler,
827 FT_ULong load_flags,
828 FT_UInt gindex,
829 FT_Glyph *aglyph,
830 FTC_Node *anode );
831
832
833 /*************************************************************************/
834 /* */
835 /* <Type> */
836 /* FTC_SBit */
837 /* */
838 /* <Description> */
839 /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */
840 /* structure for details. */
841 /* */
842 typedef struct FTC_SBitRec_* FTC_SBit;
843
844
845 /*************************************************************************/
846 /* */
847 /* <Struct> */
848 /* FTC_SBitRec */
849 /* */
850 /* <Description> */
851 /* A very compact structure used to describe a small glyph bitmap. */
852 /* */
853 /* <Fields> */
854 /* width :: The bitmap width in pixels. */
855 /* */
856 /* height :: The bitmap height in pixels. */
857 /* */
858 /* left :: The horizontal distance from the pen position to the */
859 /* left bitmap border (a.k.a. `left side bearing', or */
860 /* `lsb'). */
861 /* */
862 /* top :: The vertical distance from the pen position (on the */
863 /* baseline) to the upper bitmap border (a.k.a. `top */
864 /* side bearing'). The distance is positive for upwards */
865 /* Y coordinates. */
866 /* */
867 /* format :: The format of the glyph bitmap (monochrome or gray). */
868 /* */
869 /* max_grays :: Maximum gray level value (in the range 1 to 255). */
870 /* */
871 /* pitch :: The number of bytes per bitmap line. May be positive */
872 /* or negative. */
873 /* */
874 /* xadvance :: The horizontal advance width in pixels. */
875 /* */
876 /* yadvance :: The vertical advance height in pixels. */
877 /* */
878 /* buffer :: A pointer to the bitmap pixels. */
879 /* */
880 typedef struct FTC_SBitRec_
881 {
882 FT_Byte width;
883 FT_Byte height;
884 FT_Char left;
885 FT_Char top;
886
887 FT_Byte format;
888 FT_Byte max_grays;
889 FT_Short pitch;
890 FT_Char xadvance;
891 FT_Char yadvance;
892
893 FT_Byte* buffer;
894
895 } FTC_SBitRec;
896
897
898 /*************************************************************************/
899 /* */
900 /* <Type> */
901 /* FTC_SBitCache */
902 /* */
903 /* <Description> */
904 /* A handle to a small bitmap cache. These are special cache objects */
905 /* used to store small glyph bitmaps (and anti-aliased pixmaps) in a */
906 /* much more efficient way than the traditional glyph image cache */
907 /* implemented by @FTC_ImageCache. */
908 /* */
909 typedef struct FTC_SBitCacheRec_* FTC_SBitCache;
910
911
912 /*************************************************************************/
913 /* */
914 /* <Function> */
915 /* FTC_SBitCache_New */
916 /* */
917 /* <Description> */
918 /* Creates a new cache to store small glyph bitmaps. */
919 /* */
920 /* <Input> */
921 /* manager :: A handle to the source cache manager. */
922 /* */
923 /* <Output> */
924 /* acache :: A handle to the new sbit cache. NULL in case of error. */
925 /* */
926 /* <Return> */
927 /* FreeType error code. 0 means success. */
928 /* */
929 FT_EXPORT( FT_Error )
930 FTC_SBitCache_New( FTC_Manager manager,
931 FTC_SBitCache *acache );
932
933
934 /*************************************************************************/
935 /* */
936 /* <Function> */
937 /* FTC_SBitCache_Lookup */
938 /* */
939 /* <Description> */
940 /* Looks up a given small glyph bitmap in a given sbit cache and */
941 /* `lock' it to prevent its flushing from the cache until needed. */
942 /* */
943 /* <Input> */
944 /* cache :: A handle to the source sbit cache. */
945 /* */
946 /* type :: A pointer to the glyph image type descriptor. */
947 /* */
948 /* gindex :: The glyph index. */
949 /* */
950 /* <Output> */
951 /* sbit :: A handle to a small bitmap descriptor. */
952 /* */
953 /* anode :: Used to return the address of of the corresponding cache */
954 /* node after incrementing its reference count (see note */
955 /* below). */
956 /* */
957 /* <Return> */
958 /* FreeType error code. 0 means success. */
959 /* */
960 /* <Note> */
961 /* The small bitmap descriptor and its bit buffer are owned by the */
962 /* cache and should never be freed by the application. They might */
963 /* as well disappear from memory on the next cache lookup, so don't */
964 /* treat them as persistent data. */
965 /* */
966 /* The descriptor's `buffer' field is set to 0 to indicate a missing */
967 /* glyph bitmap. */
968 /* */
969 /* If `anode' is _not_ NULL, it receives the address of the cache */
970 /* node containing the bitmap, after increasing its reference count. */
971 /* This ensures that the node (as well as the image) will always be */
972 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */
973 /* */
974 /* If `anode' is NULL, the cache node is left unchanged, which means */
975 /* that the bitmap could be flushed out of the cache on the next */
976 /* call to one of the caching sub-system APIs. Don't assume that it */
977 /* is persistent! */
978 /* */
979 FT_EXPORT( FT_Error )
980 FTC_SBitCache_Lookup( FTC_SBitCache cache,
981 FTC_ImageType type,
982 FT_UInt gindex,
983 FTC_SBit *sbit,
984 FTC_Node *anode );
985
986
987 /*************************************************************************/
988 /* */
989 /* <Function> */
990 /* FTC_SBitCache_LookupScaler */
991 /* */
992 /* <Description> */
993 /* A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec */
994 /* to specify the face ID and its size. */
995 /* */
996 /* <Input> */
997 /* cache :: A handle to the source sbit cache. */
998 /* */
999 /* scaler :: A pointer to the scaler descriptor. */
1000 /* */
1001 /* load_flags :: The corresponding load flags. */
1002 /* */
1003 /* gindex :: The glyph index. */
1004 /* */
1005 /* <Output> */
1006 /* sbit :: A handle to a small bitmap descriptor. */
1007 /* */
1008 /* anode :: Used to return the address of of the corresponding */
1009 /* cache node after incrementing its reference count */
1010 /* (see note below). */
1011 /* */
1012 /* <Return> */
1013 /* FreeType error code. 0 means success. */
1014 /* */
1015 /* <Note> */
1016 /* The small bitmap descriptor and its bit buffer are owned by the */
1017 /* cache and should never be freed by the application. They might */
1018 /* as well disappear from memory on the next cache lookup, so don't */
1019 /* treat them as persistent data. */
1020 /* */
1021 /* The descriptor's `buffer' field is set to 0 to indicate a missing */
1022 /* glyph bitmap. */
1023 /* */
1024 /* If `anode' is _not_ NULL, it receives the address of the cache */
1025 /* node containing the bitmap, after increasing its reference count. */
1026 /* This ensures that the node (as well as the image) will always be */
1027 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */
1028 /* */
1029 /* If `anode' is NULL, the cache node is left unchanged, which means */
1030 /* that the bitmap could be flushed out of the cache on the next */
1031 /* call to one of the caching sub-system APIs. Don't assume that it */
1032 /* is persistent! */
1033 /* */
1034 FT_EXPORT( FT_Error )
1035 FTC_SBitCache_LookupScaler( FTC_SBitCache cache,
1036 FTC_Scaler scaler,
1037 FT_ULong load_flags,
1038 FT_UInt gindex,
1039 FTC_SBit *sbit,
1040 FTC_Node *anode );
1041
1042
1043 /* */
1044
1045 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
1046
1047 /*@***********************************************************************/
1048 /* */
1049 /* <Struct> */
1050 /* FTC_FontRec */
1051 /* */
1052 /* <Description> */
1053 /* A simple structure used to describe a given `font' to the cache */
1054 /* manager. Note that a `font' is the combination of a given face */
1055 /* with a given character size. */
1056 /* */
1057 /* <Fields> */
1058 /* face_id :: The ID of the face to use. */
1059 /* */
1060 /* pix_width :: The character width in integer pixels. */
1061 /* */
1062 /* pix_height :: The character height in integer pixels. */
1063 /* */
1064 typedef struct FTC_FontRec_
1065 {
1066 FTC_FaceID face_id;
1067 FT_UShort pix_width;
1068 FT_UShort pix_height;
1069
1070 } FTC_FontRec;
1071
1072
1073 /* */
1074
1075
1076 #define FTC_FONT_COMPARE( f1, f2 ) \
1077 ( (f1)->face_id == (f2)->face_id && \
1078 (f1)->pix_width == (f2)->pix_width && \
1079 (f1)->pix_height == (f2)->pix_height )
1080
1081 #define FTC_FONT_HASH( f ) \
1082 (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \
1083 ((f)->pix_width << 8) ^ \
1084 ((f)->pix_height) )
1085
1086 typedef FTC_FontRec* FTC_Font;
1087
1088
1089 FT_EXPORT( FT_Error )
1090 FTC_Manager_Lookup_Face( FTC_Manager manager,
1091 FTC_FaceID face_id,
1092 FT_Face *aface );
1093
1094 FT_EXPORT( FT_Error )
1095 FTC_Manager_Lookup_Size( FTC_Manager manager,
1096 FTC_Font font,
1097 FT_Face *aface,
1098 FT_Size *asize );
1099
1100 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */
1101
1102
1103 /* */
1104
1105 FT_END_HEADER
1106
1107 #endif /* __FTCACHE_H__ */
1108
1109
1110 /* END */
A free Windows-compatible Operating System