Context Navigation

source: trunk/poppler/freetype2/include/freetype/ftcache.h @ 262

Last change on this file since 262 was 262, checked in by Eugene Romanenko, 12 years ago
PDF plugin: freetype library updated to version 2.3.8
File size: 59.9 KB

Line
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 */

Note: See TracBrowser for help on using the repository browser.

Download in other formats: