ref: 58e932157b02295427db073e19a36cbae33213e6
parent: b71c6af028715b35e35be15488c81d3636c522f0
author: David Turner <[email protected]>
date: Mon Sep 18 21:10:25 EDT 2000
removed obsolete file (ftcimage.h) updated header files
--- a/include/freetype/cache/ftcimage.h
+++ /dev/null
@@ -1,133 +1,0 @@
-/***************************************************************************/
-/* */
-/* ftcimage.h */
-/* */
-/* FreeType Image Cache (specification). */
-/* */
-/* Copyright 2000 by */
-/* David Turner, Robert Wilhelm, and Werner Lemberg. */
-/* */
-/* This file is part of the FreeType project, and may only be used, */
-/* modified, and distributed under the terms of the FreeType project */
-/* license, LICENSE.TXT. By continuing to use, modify, or distribute */
-/* this file you indicate that you have read the license and */
-/* understand and accept it fully. */
-/* */
-/***************************************************************************/
-
-
-#ifndef FTCIMAGE_H
-#define FTCIMAGE_H
-
-#include <freetype/cache/ftcmanag.h>
-#include <freetype/ftglyph.h>
-#include <stddef.h>
-
-#ifdef __cplusplus
- extern "C" {-#endif
-
-#define FTC_MAX_IMAGE_QUEUES 16
-
- typedef struct FTC_Image_QueueRec_* FTC_Image_Queue;
- typedef struct FTC_ImageNodeRec_* FTC_ImageNode;
-
-
- /* macros used to pack a glyph index and a queue index in a single ptr */
-#define FTC_PTR_TO_GINDEX( p ) ( (FT_UInt)( (FT_ULong)(p) >> 16 ) )
-#define FTC_PTR_TO_QINDEX( p ) ( (FT_UInt)( (FT_ULong)(p) & 0xFFFF ) )
-#define FTC_INDICES_TO_PTR( g, q ) \
- ( (FT_Pointer)( ( (FT_ULong)(g) << 16 ) | \
- ( (FT_ULong)(q) & 0xFFFF) ) )
-
- typedef struct FTC_ImageNodeRec_
- {- /* root1.data contains an FT_Glyph handle */
- FT_ListNodeRec root1;
-
- /* root2.data contains a glyph index + queue index */
- FT_ListNodeRec root2;
-
- } FTC_ImageNodeRec;
-
-
- /* macros to read/set the glyph & queue index in a FTC_ImageNode */
-#define FTC_IMAGENODE_GET_GINDEX( n ) FTC_PTR_TO_GINDEX( (n)->root2.data )
-#define FTC_IMAGENODE_GET_QINDEX( n ) FTC_PTR_TO_QINDEX( (n)->root2.data )
-#define FTC_IMAGENODE_GET_GLYPH( n ) ( (FT_Glyph)(n)->root1.data )
-#define FTC_IMAGENODE_SET_GLYPH( n, g ) \
- do \
- { \- (n)->root1.data = g; \
- } while ( 0 )
-
-#define FTC_IMAGENODE_SET_INDICES( n, g, q ) \
- do \
- { \- (n)->root2.data = FTC_INDICES_TO_PTR( g, q ); \
- } while ( 0 )
-
-
- /* this macro is used to extract a handle to the global LRU list node */
- /* corresponding to a given image node */
-#define FTC_IMAGENODE_TO_LISTNODE( n ) \
- ( (FT_ListNode)&(n)->root2 )
-
- /* this macro is used to extract a handle to a given image node from */
- /* the corresponding LRU glyph list node. That's a bit hackish.. */
-#define FTC_LISTNODE_TO_IMAGENODE( p ) \
- ( (FTC_ImageNode)( (char*)(p) - \
- offsetof( FTC_ImageNodeRec,root2 ) ) )
-
-
- typedef struct FTC_Image_CacheRec_
- {- FTC_CacheRec root;
-
- FT_Lru queues_lru; /* static queues lru list */
- FT_ListRec glyphs_lru; /* global lru list of glyph images */
-
- FTC_Image_Queue last_queue; /* small cache */
-
- } FTC_Image_CacheRec;
-
-
- /* a table of functions used to generate/manager glyph images */
- typedef struct FTC_Image_Class_
- {- FT_Error (*init_image)( FTC_Image_Queue queue,
- FTC_ImageNode node );
-
- void (*done_image)( FTC_Image_Queue queue,
- FTC_ImageNode node );
-
- FT_ULong (*size_image)( FTC_Image_Queue queue,
- FTC_ImageNode node );
-
- } FTC_Image_Class;
-
-
- typedef struct FTC_Image_QueueRec_
- {- FTC_Image_Cache cache;
- FTC_Manager manager;
- FT_Memory memory;
- FTC_Image_Class* clazz;
- FTC_Image_Desc descriptor;
- FT_UInt hash_size;
- FT_List buckets;
- FT_UInt index; /* index in parent cache */
-
- } FTC_Image_QueueRec;
-
-
-
-#ifdef __cplusplus
- }
-#endif
-
-
-#endif /* FTCIMAGE_H */
-
-
-/* END */
--- a/include/freetype/cache/ftcmanag.h
+++ b/include/freetype/cache/ftcmanag.h
@@ -13,9 +13,50 @@
/* this file you indicate that you have read the license and */
/* understand and accept it fully. */
/* */
+/* */
+/* A cache manager is in charge of the following: */
+/* */
+/* - maintain a mapping between generic FTC_FaceIDs and live */
+/* FT_Face objects. The mapping itself is performed through a */
+/* user-provided callback. However, the manager maintains a small */
+/* cache of FT_Face & FT_Size objects in order to speed things */
+/* considerably.. */
+/* */
+/* - manage one or more cache object. Each cache is in charge of */
+/* holding a varying number of "cache nodes". Each cache node */
+/* represents a minimal amount of individually-accessible cached */
+/* data. For example, a cache node can be a FT_Glyph image containing */
+/* a vector outline, or some glyph metrics, or anything else.. */
+/* */
+/* each cache node has a certain size in bytes that is added to the */
+/* total amount of "cache memory" within the manager. */
+/* */
+/* all cache nodes are located in a global LRU list, where the */
+/* oldest node is at the tail of the list */
+/* */
+/* each node belongs to a single cache, and includes a reference */
+/* count to avoid destroying it (due to caching) */
+/* */
/***************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /********* **********/
+ /********* **********/
+ /********* WARNING, THIS IS ALPHA CODE, THIS API **********/
+ /********* IS DUE TO CHANGE UNTIL STRICTLY NOTIFIED BY THE **********/
+ /********* FREETYPE DEVELOPMENT TEAM **********/
+ /********* **********/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+
#ifndef FTCMANAG_H
#define FTCMANAG_H
@@ -27,89 +68,132 @@
extern "C" {#endif
+/* default values */
+#define FTC_MAX_FACES_DEFAULT 4
+#define FTC_MAX_SIZES_DEFAULT 8
+#define FTC_MAX_BYTES_DEFAULT 65536 /* 64 Kb by default */
-#define FTC_MAX_FACES_DEFAULT 4
-#define FTC_MAX_SIZES_DEFAULT 8
-#define FTC_MAX_BYTES_DEFAULT 65536
+/* maximum number of caches registered in a single manager */
+#define FTC_MAX_CACHES 16
-#define FTC_MAX_CACHES 8
- /* opaque pointer to a cache object */
- typedef struct FTC_CacheRec_* FTC_Cache;
+ typedef struct FTC_ManagerRec_
+ {+ FT_Library library;
+ FT_Lru faces_lru;
+ FT_Lru sizes_lru;
+ FT_ULong max_bytes;
+ FT_ULong num_bytes;
+ FT_ListRec global_lru;
+ FTC_Cache caches[ FTC_MAX_CACHES ];
+
+ FT_Pointer request_data;
+ FTC_Face_Requester request_face;
+
+ } FTC_ManagerRec;
- /* a ftc node is used to
- typedef FT_ListNode FTC_Node;
+ /*********************************************************************/
+ /*********************************************************************/
+ /***** *****/
+ /***** CACHE NODE DEFINITIONS *****/
+ /***** *****/
+ /*********************************************************************/
+ /*********************************************************************/
+
+
- /* macros to read/set the glyph & queue index in a FTC_Node */
-#define FTC_IMAGENODE_GET_GINDEX( n ) FTC_PTR_TO_GINDEX( (n)->data )
-#define FTC_IMAGENODE_GET_QINDEX( n ) FTC_PTR_TO_QINDEX( (n)->data )
-
-#define FTC_IMAGENODE_SET_INDICES( n, g, q ) \
- do { \- (n)->data = FTC_INDICES_TO_PTR( g, q ); \
- } while ( 0 )
+ /* each cache controls one or more cache nodes. Each node */
+ /* is part of the global_lru list of the manager. Its "data" */
+ /* field however is used as a reference count for now.. */
+ /* */
+ /* a node can anything, depending on the type of information */
+ /* held by the cache. It can be an individual glyph image, */
+ /* a set of bitmaps glyphs for a given size, some metrics, */
+ /* etc.. */
+ /* */
+
+ typedef FT_ListNodeRec FTC_CacheNodeRec;
+ typedef FTC_CacheNodeRec* FTC_CacheNode;
-
-
- /* a function used to initialize a cache */
- typedef FT_Error (FTC_Cache_Init_Func) ( FTC_Cache cache );
+ /* the fields "cachenode.data" is typecasted to this type */
+ typedef struct FTC_CacheNode_Data_
+ {+ FT_UShort cache_index;
+ FT_Short ref_count;
- /* a function used to finalize a cache */
- typedef void (FTC_Cache_Done_Func) ( FTC_Cache cache );
+ } FTC_CacheNode_Data;
- /* a function used to return the size in bytes of a given cache node */
- typedef FT_ULong (FTC_Cache_Size_Func) ( FTC_Cache cache,
- FT_Pointer object );
-
- /* a function used to purge a given cache node */
- typedef void (FTC_Cache_Purge_Func)( FTC_Cache cache,
- FT_Pointer object );
+/* returns a pointer to the FTC_CacheNode_Data contained in a */
+/* CacheNode's "data" field.. */
+#define FTC_CACHENODE_TO_DATA_P(n) \
+ ((FTC_CacheNode_Data*)&(n)->data)
+#define FTC_LIST_TO_CACHENODE(n) ((FTC_CacheNode)(n))
- /* cache class */
- typedef struct FTC_Cache_Class_
- {- FT_UInt cache_size; /* size of cache object in bytes */
- FTC_Cache_Init_Func init;
- FTC_Cache_Done_Func done;
- FTC_Cache_Size_Func size;
- FTC_Cache_Purge_Func purge;
-
- } FTC_Cache_Class;
+ /* returns the size in bytes of a given cache node */
+ typedef FT_ULong (*FTC_CacheNode_SizeFunc)( FTC_CacheNode node,
+ FT_Pointer user );
+ /* finalise a given cache node */
+ typedef void (*FTC_CacheNode_DestroyFunc)( FTC_CacheNode node,
+ FT_Pointer user );
- typedef struct FTC_CacheRec_
+ /* this structure is used to provide functions to the cache manager */
+ /* It will use them to size and destroy cache nodes.. Note that there */
+ /* is no "init_node" there because cache objects are entirely */
+ /* responsible for the creation of new cache nodes */
+ /* */
+ typedef struct FTC_CacheNode_Class_
{- FTC_Manager manager; /* cache manager.. */
- FTC_Cache_Class* clazz; /* cache clazz */
- FT_Memory memory; /* memory allocator */
- FT_UInt cache_id;
+ FTC_CacheNode_SizeFunc size_node;
+ FTC_CacheNode_DestroyFunc destroy_node;
- } FTC_CacheRec;
+ } FTC_CacheNode_Class;
+
+ /*********************************************************************/
+ /*********************************************************************/
+ /***** *****/
+ /***** CACHE DEFINITIONS *****/
+ /***** *****/
+ /*********************************************************************/
+ /*********************************************************************/
+
- typedef struct FTC_ManagerRec_
+ typedef FT_Error (*FTC_Cache_InitFunc)( FTC_Cache cache );
+
+ typedef void (*FTC_Cache_DoneFunc)( FTC_Cache cache );
+
+
+ struct FTC_Cache_Class_
{- FT_Library library;
- FT_Lru faces_lru;
- FT_Lru sizes_lru;
+ FT_UInt cache_byte_size;
+ FTC_Cache_InitFunc init_cache;
+ FTC_Cache_DoneFunc done_cache;
+ };
+
+
+
+ typedef struct FTC_CacheRec_
+ {+ FTC_Manager manager;
+ FT_Memory memory;
+ FTC_Cache_Class* clazz;
+ FTC_CacheNode_Class* node_clazz;
- FT_Pointer request_data;
- FTC_Face_Requester request_face;
+ FT_UInt cache_index; /* in manager's table */
+ FT_Pointer cache_user; /* passed to cache node methods*/
- FT_ULong num_bytes; /* current number of bytes in the caches */
- FT_ULong max_bytes; /* maximum number of bytes in the caches */
- FT_ListRec global_lru; /* the global LRU list of nodes */
-
- FT_UInt num_caches;
- FT_UInt last_id;
- FTC_Cache caches[ FTC_MAX_CACHES ];
-
- } FTC_ManagerRec;
+ } FTC_CacheRec;
+
+ /* "compress" the manager's data, i.e. get rids of old cache nodes */
+ /* that are not referenced anymore in order to limit the total */
+ /* memory used by the cache.. */
+ FT_EXPORT_DEF(void) FTC_Manager_Compress( FTC_Manager manager );
#ifdef __cplusplus
--- a/include/freetype/cache/ftlru.h
+++ b/include/freetype/cache/ftlru.h
@@ -13,9 +13,47 @@
/* this file you indicate that you have read the license and */
/* understand and accept it fully. */
/* */
+/* */
+/* A LRU is a list that cannot hold more than a certain number of */
+/* elements ("max_elements"). All elements on the list are sorted */+/* in lest-recently-used order, i.e. the "oldest" element is at */
+/* the tail of the list */
+/* */
+/* When doing a lookup (either through "Lookup" or "Lookup_Node"), */
+/* the list is searched for an element with the corresponding key */
+/* if it is found, the element is moved to the head of the list */
+/* and is returned.. */
+/* */
+/* If no corresponding element is found, the lookup routine will */
+/* try to obtain a new element with the relevant key. If the list */
+/* is already full, the oldest element from the list is discarded */
+/* and replaced by a new one; a new element is added to the list */
+/* otherwise.. */
+/* */
+/* Note that it is possible to pre-allocate the element list nodes. */
+/* That's handy when "max_elements" is sufficiently small, as it */
+/* saves allocations/releases during the lookup process */
+/* */
/***************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /********* **********/
+ /********* **********/
+ /********* WARNING, THIS IS ALPHA CODE, THIS API **********/
+ /********* IS DUE TO CHANGE UNTIL STRICTLY NOTIFIED BY THE **********/
+ /********* FREETYPE DEVELOPMENT TEAM **********/
+ /********* **********/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+ /**************************************************************************/
+
#ifndef FTLRU_H
#define FTLRU_H
@@ -26,10 +64,11 @@
extern "C" {#endif
-
+ /* generic key type */
typedef FT_Pointer FT_LruKey;
+ /* a lru node - node.root.data points to the element */
typedef struct FT_LruNodeRec_
{FT_ListNodeRec root;
@@ -37,30 +76,43 @@
} FT_LruNodeRec, *FT_LruNode;
-
+ /* forward declaration */
typedef struct FT_LruRec_* FT_Lru;
+ /* LRU clazz */
typedef struct FT_Lru_Class_
{FT_UInt lru_size; /* object size in bytes */
+ /* this method is used to initialise a new list element node */
FT_Error (*init_element)( FT_Lru lru,
FT_LruNode node );
-
+
+ /* this method is used to finalise a given list element node */
void (*done_element)( FT_Lru lru,
FT_LruNode node );
+ /* when defined, this method is called when the list if full */
+ /* during the lookup process.. it is used to change the content */
+ /* of a list element node, instead of calling "done_element" */
+ /* then "init_element". Put it to 0 for default behaviour */
FT_Error (*flush_element)( FT_Lru lru,
FT_LruNode node,
FT_LruKey new_key );
-
+
+ /* when defined, this method is used to compare a list element node */
+ /* with a given key during a lookup. When set to 0, the "key" */
+ /* fields will be directly compared instead.. */
FT_Bool (*compare_element)( FT_LruNode node,
FT_LruKey key );
} FT_Lru_Class;
-
+ /* a selector is used to indicate wether a given list element node */
+ /* is part of a selection for FT_Lru_Remove_Selection. The function */
+ /* must returns true (i.e. non 0) to indicate that the node is part */
+ /* of it.. */
typedef FT_Bool (*FT_Lru_Selector)( FT_Lru lru,
FT_LruNode node,
FT_Pointer data );
@@ -89,9 +141,9 @@
FT_Bool pre_alloc,
FT_Lru* alru );
- FT_EXPORT_DEF( void ) FT_Lru_Reset( FT_Lru lru );
+ FT_EXPORT_DEF( void ) FT_Lru_Reset( FT_Lru lru );
- FT_EXPORT_DEF( void ) FT_Lru_Done( FT_Lru lru );
+ FT_EXPORT_DEF( void ) FT_Lru_Done( FT_Lru lru );
FT_EXPORT_DEF( FT_Error ) FT_Lru_Lookup_Node( FT_Lru lru,
FT_LruKey key,
@@ -101,12 +153,12 @@
FT_LruKey key,
FT_Pointer* aobject );
- FT_EXPORT_DEF( void ) FT_Lru_Remove_Node( FT_Lru lru,
- FT_LruNode node );
+ FT_EXPORT_DEF( void ) FT_Lru_Remove_Node( FT_Lru lru,
+ FT_LruNode node );
- FT_EXPORT_DEF( void ) FT_Lru_Remove_Selection( FT_Lru lru,
- FT_Lru_Selector selector,
- FT_Pointer data );
+ FT_EXPORT_DEF( void ) FT_Lru_Remove_Selection( FT_Lru lru,
+ FT_Lru_Selector selector,
+ FT_Pointer data );
#ifdef __cplusplus