• file
• revisions
• annotate
• diff
• comparison
• raw

modules/freetype2/include/ftcache.h@6474c204b198 (annotated)

modules/freetype2/include/ftcache.h

Wed, 31 Dec 2014 06:09:35 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Wed, 31 Dec 2014 06:09:35 +0100

changeset 0

6474c204b198

permissions

-rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

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