Commit 7d0f1137 authored by David Turner's avatar David Turner
Browse files

completed the sbit cache, though it's still buggy :-(

major reformatting of the cache subsystem (again)
added substantial documentation too in header files
parent 241cc2cc
......@@ -58,11 +58,11 @@
#define FTC_MAX_CHUNK_SETS 16
typedef struct FTC_ChunkRec_* FTC_Chunk;
typedef struct FTC_ChunkNodeRec_* FTC_ChunkNode;
typedef struct FTC_ChunkSetRec_* FTC_ChunkSet;
typedef struct FTC_Chunk_CacheRec_* FTC_Chunk_Cache;
typedef struct FTC_ChunkRec_
typedef struct FTC_ChunkNodeRec_
{
FTC_CacheNodeRec root;
FTC_ChunkSet cset;
......@@ -70,14 +70,21 @@
FT_UShort num_elements;
FT_Byte* elements;
} FTC_ChunkRec;
} FTC_ChunkNodeRec;
#define FTC_CHUNKNODE_TO_LRUNODE(x) ((FT_ListNode)(x))
#define FTC_LRUNODE_TO_CHUNKNODE(x) ((FTC_ChunkNode)(x))
/*************************************************************************/
/* */
/* chunk set methods */
/* */
/* used to set "element_max", "element_count" and "element_size" */
typedef FT_Error (*FTC_ChunkSet_SizesFunc) ( FTC_ChunkSet cset,
FT_Pointer type );
typedef FT_Error (*FTC_ChunkSet_InitFunc) ( FTC_ChunkSet cset,
FT_Pointer type );
......@@ -100,11 +107,12 @@
typedef struct FTC_ChunkSet_Class_
{
FT_UInt cset_size;
FT_UInt cset_byte_size;
FTC_ChunkSet_InitFunc init;
FTC_ChunkSet_DoneFunc done;
FTC_ChunkSet_CompareFunc compare;
FTC_ChunkSet_SizesFunc sizes;
FTC_ChunkSet_NewNodeFunc new_node;
FTC_ChunkSet_SizeNodeFunc size_node;
......@@ -119,11 +127,12 @@
FTC_Manager manager;
FT_Memory memory;
FTC_ChunkSet_Class* clazz;
FT_UInt cset_index; /* index in parent cache */
FT_UInt cset_index; /* index in parent cache */
FT_UInt element_max; /* maximum number of elements */
FT_UInt element_size; /* element size in bytes */
FT_UInt element_count; /* number of elements per chunk */
FT_UInt num_chunks;
FTC_ChunkNode* chunks;
......@@ -145,7 +154,7 @@
FTC_CacheRec root;
FT_Lru csets_lru; /* static chunk set lru list */
FTC_ChunkSet last_cset; /* small cache :-) */
} FTC_Chunk_CacheRec;
/*************************************************************************/
......@@ -155,7 +164,7 @@
/* cache sub-system internals. */
/* */
FT_EXPORT_FUNC( NV_Error )
FT_EXPORT_FUNC( FT_Error )
FTC_ChunkNode_Init( FTC_ChunkNode node,
FTC_ChunkSet cset,
FT_UInt index,
......@@ -186,10 +195,7 @@
FT_EXPORT_DEF( FT_Error )
FTC_ChunkSet_New( FTC_Chunk_Cache cache,
FT_Pointer type,
FT_UInt num_elements,
FT_UInt element_size,
FT_UInt chunk_size,
FTC_ChunkSet *aset )
FTC_ChunkSet *aset );
FT_EXPORT_DEF( FT_Error )
......
......@@ -2,7 +2,7 @@
/* */
/* ftcglyph.h */
/* */
/* FreeType glyph image (FT_Glyph) cache (specification). */
/* FreeType abstract glyph cache (specification). */
/* */
/* Copyright 2000 by */
/* David Turner, Robert Wilhelm, and Werner Lemberg. */
......@@ -24,6 +24,14 @@
/* For example, see `ftcimage.h' and `ftcimage.c' which */
/* implement a FT_Glyph cache based on this code. */
/* */
/* NOTE: for now, each glyph set is implemented as a static hash table */
/* it's be interesting to experiment with dynamic hashes to see */
/* if this improves performance or not (I don't know why but */
/* something tells me it won't ?!) */
/* */
/* in all cases, this change should not affect any derived */
/* glyph cache class.. */
/* */
/*************************************************************************/
......@@ -147,7 +155,7 @@
{
FTC_CacheRec root;
FT_Lru gsets_lru; /* static sets lru list */
FTC_GlyphSet last_gset; /* small cache :-) */
FTC_GlyphSet last_gset; /* small cache :o) */
} FTC_Glyph_CacheRec;
......
/***************************************************************************/
/* */
/* ftcimage.c */
/* */
/* FreeType Image cache (body). */
/* */
/* Each image cache really manages FT_Glyph objects :-) */
/* */
/* */
/* 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/ftcglyph.h>
#include <freetype/ftglyph.h>
#ifdef __cplusplus
extern "C" {
#endif
/*************************************************************************/
/*************************************************************************/
/*************************************************************************/
/***** *****/
/***** IMAGE CACHE OBJECT *****/
/***** *****/
/*************************************************************************/
/*************************************************************************/
/*************************************************************************/
#define FTC_IMAGE_FORMAT( x ) ( (x) & 7 )
/*************************************************************************/
/* */
/* <Enum> */
/* FTC_Image_Type */
/* */
/* <Description> */
/* An enumeration used to list the types of glyph images found in a */
/* glyph image cache. */
/* */
/* <Fields> */
/* ftc_image_mono :: Monochrome bitmap glyphs. */
/* */
/* ftc_image_grays :: Anti-aliased bitmap glyphs. */
/* */
/* ftc_image_outline :: Scaled (and hinted) outline glyphs. */
/* */
/* ftc_master_outline :: Unscaled original outline glyphs. */
/* */
/* <Note> */
/* Other types may be defined in the future. */
/* */
typedef enum FTC_Image_Type_
{
ftc_image_format_bitmap = 0,
ftc_image_format_outline = 1,
ftc_image_flag_monochrome = 16,
ftc_image_flag_unhinted = 32,
ftc_image_flag_autohinted = 64,
ftc_image_flag_unscaled = 128,
ftc_image_flag_no_sbits = 256,
ftc_image_mono = ftc_image_format_bitmap |
ftc_image_flag_monochrome, /* monochrome bitmap */
ftc_image_grays = ftc_image_format_bitmap, /* anti-aliased bitmap */
ftc_image_outline = ftc_image_format_outline /* scaled outline */
} FTC_Image_Type;
/*************************************************************************/
/* */
/* <Struct> */
/* FTC_Image_Desc */
/* */
/* <Description> */
/* A simple structure used to describe a given glyph image category. */
/* */
/* <Fields> */
/* size :: An FTC_SizeRec used to describe the glyph's face & */
/* size. */
/* */
/* image_type :: The glyph image's type. */
/* */
typedef struct FTC_Image_Desc_
{
FTC_FontRec font;
FT_UInt image_type;
} FTC_Image_Desc;
/*************************************************************************/
/* */
/* <Type> */
/* FTC_Image_Cache */
/* */
/* <Description> */
/* A handle to an glyph image cache object. They are designed to */
/* hold many distinct glyph images, while not exceeding a certain */
/* memory threshold. */
/* */
typedef struct FTC_Image_CacheRec_* FTC_Image_Cache;
/*************************************************************************/
/* */
/* <Function> */
/* FTC_Image_Cache_New */
/* */
/* <Description> */
/* Creates a new glyph image cache. */
/* */
/* <Input> */
/* manager :: The parent manager for the image cache. */
/* */
/* <Output> */
/* acache :: A handle to the new glyph image cache object. */
/* */
/* <Return> */
/* FreeType error code. 0 means success. */
/* */
FT_EXPORT_DEF( FT_Error ) FTC_Image_Cache_New( FTC_Manager manager,
FTC_Image_Cache* acache );
/*************************************************************************/
/* */
/* <Function> */
/* FTC_Image_Cache_Lookup */
/* */
/* <Description> */
/* Retrieves a given glyph image from a glyph image cache. */
/* */
/* <Input> */
/* cache :: A handle to the source glyph image cache. */
/* */
/* desc :: A pointer to a glyph image descriptor. */
/* */
/* gindex :: The glyph index to retrieve. */
/* */
/* <Output> */
/* aglyph :: The corresponding FT_Glyph object. 0 in case of */
/* failure. */
/* */
/* <Return> */
/* error code, 0 means success */
/* */
/* <Note> */
/* the returned glyph is owned and manager by the glyph image cache. */
/* Never try to transform or discard it manually! You can however */
/* create a copy with FT_Glyph_Copy() and modify the new one. */
/* */
/* Because the glyph image cache limits the total amount of memory */
/* taken by the glyphs it holds, the returned glyph might disappear */
/* on a later invocation of this function! It's a cache after all... */
/* */
FT_EXPORT_DEF( FT_Error )
FTC_Image_Cache_Lookup( FTC_Image_Cache cache,
FTC_Image_Desc* desc,
FT_UInt gindex,
FT_Glyph* aglyph );
#ifdef __cplusplus
}
#endif
#endif /* FTCIMAGE_H */
/* END */
......@@ -73,7 +73,6 @@
#endif
/* default values */
#define FTC_MAX_FACES_DEFAULT 2
#define FTC_MAX_SIZES_DEFAULT 4
#define FTC_MAX_BYTES_DEFAULT 200000 /* 200kByte by default! */
......@@ -82,6 +81,40 @@
#define FTC_MAX_CACHES 16
/****************************************************************
*
* <Struct> FTC_ManagerRec
*
* <Description>
* the cache manager structure. Each cache manager is in
* charge of performing two tasks:
*
* <Fields>
* library :: handle to FreeType library instance
* faces_lru :: lru list of FT_Face objects in cache
* sizes_lru :: lru list of FT_Size objects in cache
*
* max_bytes :: maximum number of bytes to be allocated
* in the cache. this is only related to
* the byte size of the nodes cached by
* the manager.
*
* num_bytes :: current number of bytes allocated in
* the cache. only related to the byte size
* of cached nodes.
*
* num_nodes :: current number of nodes in the manager
*
* global_lru :: the global lru list of all cache nodes
*
* caches :: a table of installed/registered cache
* objects
*
* request_data :: user-provided data passed to the requester
* request_face :: user-provided function used to implement
* a mapping between abstract FTC_FaceIDs
* and real FT_Face objects..
*/
typedef struct FTC_ManagerRec_
{
FT_Library library;
......@@ -90,6 +123,7 @@
FT_ULong max_bytes;
FT_ULong num_bytes;
FT_UInt num_nodes;
FT_ListRec global_lru;
FTC_Cache caches[FTC_MAX_CACHES];
......@@ -99,6 +133,31 @@
} FTC_ManagerRec;
/**********************************************************************
*
* <Function> FTC_Manager_Compress
*
* <Description>
* this function is used to check the state of the cache manager
* if its "num_bytes" field is greater than its "max_bytes"
* field, this function will flush as many old cache nodes as
* possible (ignoring cache nodes with a non-zero reference
* count).
*
* <input>
* manager :: handle to cache manager
*
* <note>
* client applications should not call this function directly.
* it is normally invoked by specific cache implementations.
*
* the reason this function is exported is to allow client-
* specific cache classes..
*
*/
FT_EXPORT_DEF( void ) FTC_Manager_Compress( FTC_Manager manager );
/*************************************************************************/
/*************************************************************************/
/***** *****/
......@@ -138,19 +197,56 @@
#define FTC_LIST_TO_CACHENODE( n ) ( (FTC_CacheNode)(n) )
/* return the size in bytes of a given cache node */
/**********************************************************************
*
* <FuncType> FTC_CacheNode_SizeFunc
*
* <Description>
* a function used to compute the total size in bytes of a given
* cache node. It is used by the cache manager to compute the
* number of old nodes to flush when the cache is full..
*
* <Input>
* node :: handle to target cache node
* cache_data :: a generic pointer passed to the destructor.
*/
typedef FT_ULong (*FTC_CacheNode_SizeFunc)( FTC_CacheNode node,
FT_Pointer user );
/* finalize a given cache node */
FT_Pointer cache_data );
/**********************************************************************
*
* <FuncType> FTC_CacheNode_DestroyFunc
*
* <Description>
* a function used to destroy a given cache node. It is called
* by the manager when the cache is full and old nodes need to
* be flushed out..
*
* <Input>
* node :: handle to target cache node
* cache_data :: a generic pointer passed to the destructor.
*/
typedef void (*FTC_CacheNode_DestroyFunc)( FTC_CacheNode node,
FT_Pointer user );
/* 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' because cache objects are entirely responsible */
/* for the creation of new cache nodes. */
/* */
FT_Pointer cache_data );
/**********************************************************************
*
* <Struct> FTC_CacheNode_Class
*
* <Description>
* a very simple structure used to describe a cache node's class
* to the cache manager
*
* <Fields>
* size_node :: a function used to size the node
* destroy_node :: a function used to destroy the node
*
* <Note>
* the cache node class doesn't include a "new_node" function
* because the cache manager never allocates cache node directly,
* it delegates this task to its cache objects..
*
*/
typedef struct FTC_CacheNode_Class_
{
FTC_CacheNode_SizeFunc size_node;
......@@ -168,10 +264,45 @@
/*************************************************************************/
/**********************************************************************
*
* <FuncType> FTC_Cache_InitFunc
*
* <Description>
* a function used to initialize a given cache object
*
* <Input>
* cache :: handle to new cache
*/
typedef FT_Error (*FTC_Cache_InitFunc)( FTC_Cache cache );
/**********************************************************************
*
* <FuncType> FTC_Cache_DoneFunc
*
* <Description>
* a function used to finalize a given cache object
*
* <Input>
* cache :: handle to target cache
*/
typedef void (*FTC_Cache_DoneFunc)( FTC_Cache cache );
/**********************************************************************
*
* <Struct> FTC_Cache_Class
*
* <Description>
* a structure used to describe a given cache object class to
* the cache manager.
*
* <Fields>
* cache_byte_size :: size of cache object in bytes
* init_cache :: cache object initializer
* done_cache :: cache object finalizer
*/
struct FTC_Cache_Class_
{
FT_UInt cache_byte_size;
......@@ -179,6 +310,23 @@
FTC_Cache_DoneFunc done_cache;
};
/**********************************************************************
*
* <Struct> FTC_CacheRec
*
* <Description>
* a structure used to describe an abstract cache object
*
* <Fields>
* manager :: handle to parent cache manager
* memory :: handle to memory manager
* clazz :: pointer to cache clazz
* node_clazz :: pointer to cache's node clazz
*
* cache_index :: index of cache in manager's table
* cache_data :: data passed to the cache node constructor/finalizer
*/
typedef struct FTC_CacheRec_
{
FTC_Manager manager;
......@@ -187,16 +335,11 @@
FTC_CacheNode_Class* node_clazz;
FT_UInt cache_index; /* in manager's table */
FT_Pointer cache_user; /* passed to cache node methods */
FT_Pointer cache_data; /* passed to cache node methods */
} FTC_CacheRec;
/* `Compress' the manager's data, i.e., get rid 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
}
......
......@@ -32,49 +32,24 @@
typedef struct FTC_SBit_CacheRec_* FTC_SBit_Cache;
/* format of small bitmaps */
typedef enum FTC_SBit_Format_
{
ftc_sbit_format_mono = 0,
ftc_sbit_format_aa256 = 1,
} FTC_SBit_Format;
/* a compact structure used to hold a single small bitmap */
typedef struct FTC_SBitRec_
{
FT_Byte width;
FT_Byte height;
FT_SChar left;
FT_SChar top;
FT_Char left;
FT_Char top;
FT_Byte format;
FT_SChar pitch;
FT_SChar xadvance;
FT_SChar yadvance;
FT_Char pitch;
FT_Char xadvance;
FT_Char yadvance;
FT_Byte* buffer;
} FTC_SBitRec;
typedef struct FTC_SBitSetRec_
{
FTC_ChunkSetRec root;
FTC_Image_Desc desc;
} FTC_SBitSet;
typedef struct FTC_SBit_CacheRec_
{
FTC_Chunk_CacheRec root;
} FTC_SBit_CacheRec;
FT_EXPORT_DEF( FT_Error )
FTC_SBit_Cache_New( FTC_Manager manager,
FTC_SBit_Cache *acache );
......@@ -83,6 +58,7 @@
FT_EXPORT_DEF( FT_Error )
FTC_SBit_Cache_Lookup( FTC_SBit_Cache cache,
FTC_Image_Desc* desc,
FT_UInt gindex,
FTC_SBit *sbit );
......
......@@ -72,7 +72,7 @@
typedef FT_Pointer FT_LruKey;
/* an lru node -- node.root.data points to the element */
/* an lru node -- root.data points to the element */
typedef struct FT_LruNodeRec_
{
FT_ListNodeRec root;
......@@ -80,6 +80,8 @@
} FT_LruNodeRec, *FT_LruNode;