?  search:
summary | log | graphiclog1 | graphiclog2 | commit | commitdiff | tree | refs | edit | fork
blame | history | raw | HEAD
clarify the gui
[open-ps2-loader.git] / thirdparty / freetype-2.3.12 / include / freetype / ftcache.h
blob0916d70a37efd62e39876d34b1e5de317edd90b0
1 /***************************************************************************/
2 /* */
3 /* ftcache.h */
4 /* */
5 /* FreeType Cache subsystem (specification). */
6 /* */
7 /* Copyright 1996-2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 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 FT_Pointer 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 /* Create 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 /* Empty 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 /* Destroy 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 /* Retrieve 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;
438
439
440 /*************************************************************************/
441 /* */
442 /* <Struct> */
443 /* FTC_Scaler */
444 /* */
445 /* <Description> */
446 /* A handle to an @FTC_ScalerRec structure. */
447 /* */
448 typedef struct FTC_ScalerRec_* FTC_Scaler;
449
450
451 /*************************************************************************/
452 /* */
453 /* <Function> */
454 /* FTC_Manager_LookupSize */
455 /* */
456 /* <Description> */
457 /* Retrieve the @FT_Size object that corresponds to a given */
458 /* @FTC_ScalerRec pointer through a cache manager. */
459 /* */
460 /* <Input> */
461 /* manager :: A handle to the cache manager. */
462 /* */
463 /* scaler :: A scaler handle. */
464 /* */
465 /* <Output> */
466 /* asize :: A handle to the size object. */
467 /* */
468 /* <Return> */
469 /* FreeType error code. 0~means success. */
470 /* */
471 /* <Note> */
472 /* The returned @FT_Size object is always owned by the manager. You */
473 /* should never try to discard it by yourself. */
474 /* */
475 /* You can access the parent @FT_Face object simply as `size->face' */
476 /* if you need it. Note that this object is also owned by the */
477 /* manager. */
478 /* */
479 /* <Note> */
480 /* When you perform a lookup, out-of-memory errors are detected */
481 /* _within_ the lookup and force incremental flushes of the cache */
482 /* until enough memory is released for the lookup to succeed. */
483 /* */
484 /* If a lookup fails with `FT_Err_Out_Of_Memory' the cache has */
485 /* already been completely flushed, and still no memory is available */
486 /* for the operation. */
487 /* */
488 FT_EXPORT( FT_Error )
489 FTC_Manager_LookupSize( FTC_Manager manager,
490 FTC_Scaler scaler,
491 FT_Size *asize );
492
493
494 /*************************************************************************/
495 /* */
496 /* <Function> */
497 /* FTC_Node_Unref */
498 /* */
499 /* <Description> */
500 /* Decrement a cache node's internal reference count. When the count */
501 /* reaches 0, it is not destroyed but becomes eligible for subsequent */
502 /* cache flushes. */
503 /* */
504 /* <Input> */
505 /* node :: The cache node handle. */
506 /* */
507 /* manager :: The cache manager handle. */
508 /* */
509 FT_EXPORT( void )
510 FTC_Node_Unref( FTC_Node node,
511 FTC_Manager manager );
512
513
514 /*************************************************************************
515 *
516 * @function:
517 * FTC_Manager_RemoveFaceID
518 *
519 * @description:
520 * A special function used to indicate to the cache manager that
521 * a given @FTC_FaceID is no longer valid, either because its
522 * content changed, or because it was deallocated or uninstalled.
523 *
524 * @input:
525 * manager ::
526 * The cache manager handle.
527 *
528 * face_id ::
529 * The @FTC_FaceID to be removed.
530 *
531 * @note:
532 * This function flushes all nodes from the cache corresponding to this
533 * `face_id', with the exception of nodes with a non-null reference
534 * count.
535 *
536 * Such nodes are however modified internally so as to never appear
537 * in later lookups with the same `face_id' value, and to be immediately
538 * destroyed when released by all their users.
539 *
540 */
541 FT_EXPORT( void )
542 FTC_Manager_RemoveFaceID( FTC_Manager manager,
543 FTC_FaceID face_id );
544
545
546 /*************************************************************************/
547 /* */
548 /* <Section> */
549 /* cache_subsystem */
550 /* */
551 /*************************************************************************/
552
553 /*************************************************************************
554 *
555 * @type:
556 * FTC_CMapCache
557 *
558 * @description:
559 * An opaque handle used to model a charmap cache. This cache is to
560 * hold character codes -> glyph indices mappings.
561 *
562 */
563 typedef struct FTC_CMapCacheRec_* FTC_CMapCache;
564
565
566 /*************************************************************************
567 *
568 * @function:
569 * FTC_CMapCache_New
570 *
571 * @description:
572 * Create a new charmap cache.
573 *
574 * @input:
575 * manager ::
576 * A handle to the cache manager.
577 *
578 * @output:
579 * acache ::
580 * A new cache handle. NULL in case of error.
581 *
582 * @return:
583 * FreeType error code. 0~means success.
584 *
585 * @note:
586 * Like all other caches, this one will be destroyed with the cache
587 * manager.
588 *
589 */
590 FT_EXPORT( FT_Error )
591 FTC_CMapCache_New( FTC_Manager manager,
592 FTC_CMapCache *acache );
593
594
595 /************************************************************************
596 *
597 * @function:
598 * FTC_CMapCache_Lookup
599 *
600 * @description:
601 * Translate a character code into a glyph index, using the charmap
602 * cache.
603 *
604 * @input:
605 * cache ::
606 * A charmap cache handle.
607 *
608 * face_id ::
609 * The source face ID.
610 *
611 * cmap_index ::
612 * The index of the charmap in the source face. Any negative value
613 * means to use the cache @FT_Face's default charmap.
614 *
615 * char_code ::
616 * The character code (in the corresponding charmap).
617 *
618 * @return:
619 * Glyph index. 0~means `no glyph'.
620 *
621 */
622 FT_EXPORT( FT_UInt )
623 FTC_CMapCache_Lookup( FTC_CMapCache cache,
624 FTC_FaceID face_id,
625 FT_Int cmap_index,
626 FT_UInt32 char_code );
627
628
629 /*************************************************************************/
630 /* */
631 /* <Section> */
632 /* cache_subsystem */
633 /* */
634 /*************************************************************************/
635
636
637 /*************************************************************************/
638 /*************************************************************************/
639 /*************************************************************************/
640 /***** *****/
641 /***** IMAGE CACHE OBJECT *****/
642 /***** *****/
643 /*************************************************************************/
644 /*************************************************************************/
645 /*************************************************************************/
646
647
648 /*************************************************************************
649 *
650 * @struct:
651 * FTC_ImageTypeRec
652 *
653 * @description:
654 * A structure used to model the type of images in a glyph cache.
655 *
656 * @fields:
657 * face_id ::
658 * The face ID.
659 *
660 * width ::
661 * The width in pixels.
662 *
663 * height ::
664 * The height in pixels.
665 *
666 * flags ::
667 * The load flags, as in @FT_Load_Glyph.
668 *
669 */
670 typedef struct FTC_ImageTypeRec_
671 {
672 FTC_FaceID face_id;
673 FT_Int width;
674 FT_Int height;
675 FT_Int32 flags;
676
677 } FTC_ImageTypeRec;
678
679
680 /*************************************************************************
681 *
682 * @type:
683 * FTC_ImageType
684 *
685 * @description:
686 * A handle to an @FTC_ImageTypeRec structure.
687 *
688 */
689 typedef struct FTC_ImageTypeRec_* FTC_ImageType;
690
691
692 /* */
693
694
695 #define FTC_IMAGE_TYPE_COMPARE( d1, d2 ) \
696 ( (d1)->face_id == (d2)->face_id && \
697 (d1)->width == (d2)->width && \
698 (d1)->flags == (d2)->flags )
699
700 #define FTC_IMAGE_TYPE_HASH( d ) \
701 (FT_UFast)( FTC_FACE_ID_HASH( (d)->face_id ) ^ \
702 ( (d)->width << 8 ) ^ (d)->height ^ \
703 ( (d)->flags << 4 ) )
704
705
706 /*************************************************************************/
707 /* */
708 /* <Type> */
709 /* FTC_ImageCache */
710 /* */
711 /* <Description> */
712 /* A handle to an glyph image cache object. They are designed to */
713 /* hold many distinct glyph images while not exceeding a certain */
714 /* memory threshold. */
715 /* */
716 typedef struct FTC_ImageCacheRec_* FTC_ImageCache;
717
718
719 /*************************************************************************/
720 /* */
721 /* <Function> */
722 /* FTC_ImageCache_New */
723 /* */
724 /* <Description> */
725 /* Create a new glyph image cache. */
726 /* */
727 /* <Input> */
728 /* manager :: The parent manager for the image cache. */
729 /* */
730 /* <Output> */
731 /* acache :: A handle to the new glyph image cache object. */
732 /* */
733 /* <Return> */
734 /* FreeType error code. 0~means success. */
735 /* */
736 FT_EXPORT( FT_Error )
737 FTC_ImageCache_New( FTC_Manager manager,
738 FTC_ImageCache *acache );
739
740
741 /*************************************************************************/
742 /* */
743 /* <Function> */
744 /* FTC_ImageCache_Lookup */
745 /* */
746 /* <Description> */
747 /* Retrieve a given glyph image from a glyph image cache. */
748 /* */
749 /* <Input> */
750 /* cache :: A handle to the source glyph image cache. */
751 /* */
752 /* type :: A pointer to a glyph image type descriptor. */
753 /* */
754 /* gindex :: The glyph index to retrieve. */
755 /* */
756 /* <Output> */
757 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */
758 /* failure. */
759 /* */
760 /* anode :: Used to return the address of of the corresponding cache */
761 /* node after incrementing its reference count (see note */
762 /* below). */
763 /* */
764 /* <Return> */
765 /* FreeType error code. 0~means success. */
766 /* */
767 /* <Note> */
768 /* The returned glyph is owned and managed by the glyph image cache. */
769 /* Never try to transform or discard it manually! You can however */
770 /* create a copy with @FT_Glyph_Copy and modify the new one. */
771 /* */
772 /* If `anode' is _not_ NULL, it receives the address of the cache */
773 /* node containing the glyph image, after increasing its reference */
774 /* count. This ensures that the node (as well as the @FT_Glyph) will */
775 /* always be kept in the cache until you call @FTC_Node_Unref to */
776 /* `release' it. */
777 /* */
778 /* If `anode' is NULL, the cache node is left unchanged, which means */
779 /* that the @FT_Glyph could be flushed out of the cache on the next */
780 /* call to one of the caching sub-system APIs. Don't assume that it */
781 /* is persistent! */
782 /* */
783 FT_EXPORT( FT_Error )
784 FTC_ImageCache_Lookup( FTC_ImageCache cache,
785 FTC_ImageType type,
786 FT_UInt gindex,
787 FT_Glyph *aglyph,
788 FTC_Node *anode );
789
790
791 /*************************************************************************/
792 /* */
793 /* <Function> */
794 /* FTC_ImageCache_LookupScaler */
795 /* */
796 /* <Description> */
797 /* A variant of @FTC_ImageCache_Lookup that uses an @FTC_ScalerRec */
798 /* to specify the face ID and its size. */
799 /* */
800 /* <Input> */
801 /* cache :: A handle to the source glyph image cache. */
802 /* */
803 /* scaler :: A pointer to a scaler descriptor. */
804 /* */
805 /* load_flags :: The corresponding load flags. */
806 /* */
807 /* gindex :: The glyph index to retrieve. */
808 /* */
809 /* <Output> */
810 /* aglyph :: The corresponding @FT_Glyph object. 0~in case of */
811 /* failure. */
812 /* */
813 /* anode :: Used to return the address of of the corresponding */
814 /* cache node after incrementing its reference count */
815 /* (see note below). */
816 /* */
817 /* <Return> */
818 /* FreeType error code. 0~means success. */
819 /* */
820 /* <Note> */
821 /* The returned glyph is owned and managed by the glyph image cache. */
822 /* Never try to transform or discard it manually! You can however */
823 /* create a copy with @FT_Glyph_Copy and modify the new one. */
824 /* */
825 /* If `anode' is _not_ NULL, it receives the address of the cache */
826 /* node containing the glyph image, after increasing its reference */
827 /* count. This ensures that the node (as well as the @FT_Glyph) will */
828 /* always be kept in the cache until you call @FTC_Node_Unref to */
829 /* `release' it. */
830 /* */
831 /* If `anode' is NULL, the cache node is left unchanged, which means */
832 /* that the @FT_Glyph could be flushed out of the cache on the next */
833 /* call to one of the caching sub-system APIs. Don't assume that it */
834 /* is persistent! */
835 /* */
836 /* Calls to @FT_Set_Char_Size and friends have no effect on cached */
837 /* glyphs; you should always use the FreeType cache API instead. */
838 /* */
839 FT_EXPORT( FT_Error )
840 FTC_ImageCache_LookupScaler( FTC_ImageCache cache,
841 FTC_Scaler scaler,
842 FT_ULong load_flags,
843 FT_UInt gindex,
844 FT_Glyph *aglyph,
845 FTC_Node *anode );
846
847
848 /*************************************************************************/
849 /* */
850 /* <Type> */
851 /* FTC_SBit */
852 /* */
853 /* <Description> */
854 /* A handle to a small bitmap descriptor. See the @FTC_SBitRec */
855 /* structure for details. */
856 /* */
857 typedef struct FTC_SBitRec_* FTC_SBit;
858
859
860 /*************************************************************************/
861 /* */
862 /* <Struct> */
863 /* FTC_SBitRec */
864 /* */
865 /* <Description> */
866 /* A very compact structure used to describe a small glyph bitmap. */
867 /* */
868 /* <Fields> */
869 /* width :: The bitmap width in pixels. */
870 /* */
871 /* height :: The bitmap height in pixels. */
872 /* */
873 /* left :: The horizontal distance from the pen position to the */
874 /* left bitmap border (a.k.a. `left side bearing', or */
875 /* `lsb'). */
876 /* */
877 /* top :: The vertical distance from the pen position (on the */
878 /* baseline) to the upper bitmap border (a.k.a. `top */
879 /* side bearing'). The distance is positive for upwards */
880 /* y~coordinates. */
881 /* */
882 /* format :: The format of the glyph bitmap (monochrome or gray). */
883 /* */
884 /* max_grays :: Maximum gray level value (in the range 1 to~255). */
885 /* */
886 /* pitch :: The number of bytes per bitmap line. May be positive */
887 /* or negative. */
888 /* */
889 /* xadvance :: The horizontal advance width in pixels. */
890 /* */
891 /* yadvance :: The vertical advance height in pixels. */
892 /* */
893 /* buffer :: A pointer to the bitmap pixels. */
894 /* */
895 typedef struct FTC_SBitRec_
896 {
897 FT_Byte width;
898 FT_Byte height;
899 FT_Char left;
900 FT_Char top;
901
902 FT_Byte format;
903 FT_Byte max_grays;
904 FT_Short pitch;
905 FT_Char xadvance;
906 FT_Char yadvance;
907
908 FT_Byte* buffer;
909
910 } FTC_SBitRec;
911
912
913 /*************************************************************************/
914 /* */
915 /* <Type> */
916 /* FTC_SBitCache */
917 /* */
918 /* <Description> */
919 /* A handle to a small bitmap cache. These are special cache objects */
920 /* used to store small glyph bitmaps (and anti-aliased pixmaps) in a */
921 /* much more efficient way than the traditional glyph image cache */
922 /* implemented by @FTC_ImageCache. */
923 /* */
924 typedef struct FTC_SBitCacheRec_* FTC_SBitCache;
925
926
927 /*************************************************************************/
928 /* */
929 /* <Function> */
930 /* FTC_SBitCache_New */
931 /* */
932 /* <Description> */
933 /* Create a new cache to store small glyph bitmaps. */
934 /* */
935 /* <Input> */
936 /* manager :: A handle to the source cache manager. */
937 /* */
938 /* <Output> */
939 /* acache :: A handle to the new sbit cache. NULL in case of error. */
940 /* */
941 /* <Return> */
942 /* FreeType error code. 0~means success. */
943 /* */
944 FT_EXPORT( FT_Error )
945 FTC_SBitCache_New( FTC_Manager manager,
946 FTC_SBitCache *acache );
947
948
949 /*************************************************************************/
950 /* */
951 /* <Function> */
952 /* FTC_SBitCache_Lookup */
953 /* */
954 /* <Description> */
955 /* Look up a given small glyph bitmap in a given sbit cache and */
956 /* `lock' it to prevent its flushing from the cache until needed. */
957 /* */
958 /* <Input> */
959 /* cache :: A handle to the source sbit cache. */
960 /* */
961 /* type :: A pointer to the glyph image type descriptor. */
962 /* */
963 /* gindex :: The glyph index. */
964 /* */
965 /* <Output> */
966 /* sbit :: A handle to a small bitmap descriptor. */
967 /* */
968 /* anode :: Used to return the address of of the corresponding cache */
969 /* node after incrementing its reference count (see note */
970 /* below). */
971 /* */
972 /* <Return> */
973 /* FreeType error code. 0~means success. */
974 /* */
975 /* <Note> */
976 /* The small bitmap descriptor and its bit buffer are owned by the */
977 /* cache and should never be freed by the application. They might */
978 /* as well disappear from memory on the next cache lookup, so don't */
979 /* treat them as persistent data. */
980 /* */
981 /* The descriptor's `buffer' field is set to~0 to indicate a missing */
982 /* glyph bitmap. */
983 /* */
984 /* If `anode' is _not_ NULL, it receives the address of the cache */
985 /* node containing the bitmap, after increasing its reference count. */
986 /* This ensures that the node (as well as the image) will always be */
987 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */
988 /* */
989 /* If `anode' is NULL, the cache node is left unchanged, which means */
990 /* that the bitmap could be flushed out of the cache on the next */
991 /* call to one of the caching sub-system APIs. Don't assume that it */
992 /* is persistent! */
993 /* */
994 FT_EXPORT( FT_Error )
995 FTC_SBitCache_Lookup( FTC_SBitCache cache,
996 FTC_ImageType type,
997 FT_UInt gindex,
998 FTC_SBit *sbit,
999 FTC_Node *anode );
1000
1001
1002 /*************************************************************************/
1003 /* */
1004 /* <Function> */
1005 /* FTC_SBitCache_LookupScaler */
1006 /* */
1007 /* <Description> */
1008 /* A variant of @FTC_SBitCache_Lookup that uses an @FTC_ScalerRec */
1009 /* to specify the face ID and its size. */
1010 /* */
1011 /* <Input> */
1012 /* cache :: A handle to the source sbit cache. */
1013 /* */
1014 /* scaler :: A pointer to the scaler descriptor. */
1015 /* */
1016 /* load_flags :: The corresponding load flags. */
1017 /* */
1018 /* gindex :: The glyph index. */
1019 /* */
1020 /* <Output> */
1021 /* sbit :: A handle to a small bitmap descriptor. */
1022 /* */
1023 /* anode :: Used to return the address of of the corresponding */
1024 /* cache node after incrementing its reference count */
1025 /* (see note below). */
1026 /* */
1027 /* <Return> */
1028 /* FreeType error code. 0~means success. */
1029 /* */
1030 /* <Note> */
1031 /* The small bitmap descriptor and its bit buffer are owned by the */
1032 /* cache and should never be freed by the application. They might */
1033 /* as well disappear from memory on the next cache lookup, so don't */
1034 /* treat them as persistent data. */
1035 /* */
1036 /* The descriptor's `buffer' field is set to~0 to indicate a missing */
1037 /* glyph bitmap. */
1038 /* */
1039 /* If `anode' is _not_ NULL, it receives the address of the cache */
1040 /* node containing the bitmap, after increasing its reference count. */
1041 /* This ensures that the node (as well as the image) will always be */
1042 /* kept in the cache until you call @FTC_Node_Unref to `release' it. */
1043 /* */
1044 /* If `anode' is NULL, the cache node is left unchanged, which means */
1045 /* that the bitmap could be flushed out of the cache on the next */
1046 /* call to one of the caching sub-system APIs. Don't assume that it */
1047 /* is persistent! */
1048 /* */
1049 FT_EXPORT( FT_Error )
1050 FTC_SBitCache_LookupScaler( FTC_SBitCache cache,
1051 FTC_Scaler scaler,
1052 FT_ULong load_flags,
1053 FT_UInt gindex,
1054 FTC_SBit *sbit,
1055 FTC_Node *anode );
1056
1057
1058 /* */
1059
1060 #ifdef FT_CONFIG_OPTION_OLD_INTERNALS
1061
1062 /*@***********************************************************************/
1063 /* */
1064 /* <Struct> */
1065 /* FTC_FontRec */
1066 /* */
1067 /* <Description> */
1068 /* A simple structure used to describe a given `font' to the cache */
1069 /* manager. Note that a `font' is the combination of a given face */
1070 /* with a given character size. */
1071 /* */
1072 /* <Fields> */
1073 /* face_id :: The ID of the face to use. */
1074 /* */
1075 /* pix_width :: The character width in integer pixels. */
1076 /* */
1077 /* pix_height :: The character height in integer pixels. */
1078 /* */
1079 typedef struct FTC_FontRec_
1080 {
1081 FTC_FaceID face_id;
1082 FT_UShort pix_width;
1083 FT_UShort pix_height;
1084
1085 } FTC_FontRec;
1086
1087
1088 /* */
1089
1090
1091 #define FTC_FONT_COMPARE( f1, f2 ) \
1092 ( (f1)->face_id == (f2)->face_id && \
1093 (f1)->pix_width == (f2)->pix_width && \
1094 (f1)->pix_height == (f2)->pix_height )
1095
1096 #define FTC_FONT_HASH( f ) \
1097 (FT_UInt32)( FTC_FACE_ID_HASH((f)->face_id) ^ \
1098 ((f)->pix_width << 8) ^ \
1099 ((f)->pix_height) )
1100
1101 typedef FTC_FontRec* FTC_Font;
1102
1103
1104 FT_EXPORT( FT_Error )
1105 FTC_Manager_Lookup_Face( FTC_Manager manager,
1106 FTC_FaceID face_id,
1107 FT_Face *aface );
1108
1109 FT_EXPORT( FT_Error )
1110 FTC_Manager_Lookup_Size( FTC_Manager manager,
1111 FTC_Font font,
1112 FT_Face *aface,
1113 FT_Size *asize );
1114
1115 #endif /* FT_CONFIG_OPTION_OLD_INTERNALS */
1116
1117
1118 /* */
1119
1120 FT_END_HEADER
1121
1122 #endif /* __FTCACHE_H__ */
1123
1124
1125 /* END */
Open USB/SMB/HDD Game Loader for PS2/PS3