Image caching

Caches currently used and preloaded images. More...

Classes
class	CGUIImageCache
	Image cache base class. More...
class	CGUIImageCacheImpl
	Implementation of Cache for Guiliani image resources. More...
class	CGUIImageCacheReplacementDummy
	Dummy replacement policy for use with the Guiliani image cache. More...
class	CGUIImageCacheReplacementFifo
	FIFO replacement policy for use with the Guiliani image cache. More...
class	CGUIImageCacheReplacementGreedy
	Greedy replacement policy for use with the Guiliani image cache. More...
class	CGUIImageCacheReplacementLru
	Least Recently Used replacement policy for use with the Guiliani image cache. More...
class	CGUIImageCacheReplacementManager
	Replacement manager for the image cache. More...
class	CGUIImageCacheReplacementManagerImpl
	Replacement manager for the image cache. More...
class	CGUIImageCacheReplacementPolicy
	Abstract replacement policy for use with the Guiliani image cache. More...

Enumerations
enum	ReplacementPolicyType_t { IC_REPLACEMENT_POLICY_DUMMY = 0 , IC_REPLACEMENT_POLICY_GREEDY = 1 , IC_REPLACEMENT_POLICY_FIFO = 2 , IC_REPLACEMENT_POLICY_LRU = 3 }

Detailed Description

Caches currently used and preloaded images.

The cache contains images currently used in the application (used list) and unused "permanent" images that are cached for later use (free list).

Images are loaded to the cache until the size limit is reached. When another image has to be loaded, space in the cache is freed by unloading unused "permanent" images. The order of unloading is determined by a replacement policy - lru (last recently used), fifo (first in first out, for images in the free list this equals lru) or greedy (largest image is unloaded first).

By default, the cache has a size limit of 100 MB and uses LRU policies for both lists.

No caching is applied to dynamic images, which were registered without supplying a filename. Since they can not be unloaded/reloaded on request, caching can not be done for those (see CGUIResourceManager::RegisterDynamicImage()).

Note that this 'cache' only works as a real cache for images that have the 'permanent' flag set (see CGUIResourceManager::RegisterImageResource()). Its main functionality is limiting the amount of memory used by images by explicitly unloading images when the size limit is reached and re-loading them when needed.

The example below shows the initialization of the GUIImageCache. The cache size and the policies should be adapted to the project needs.

// Create image cache of 2 MB (size in bytes) with greedy policy for used and fifo for free images
GETIMGCACHE->CreateInstance(1024*1024*2, IC_REPLACEMENT_POLICY_GREEDY, IC_REPLACEMENT_POLICY_FIFO);

Alternatively the ImageCache can configure itself by Loading a XML configuration.

ReadCacheSettingsFromFile("CacheConfig.xml");

Recognized XML Statements shall be surrounded by a <CacheConfig> element. In this Tag a <FileVersion> element is mandatory. Currently only version 1 is valid. Also an <Entries> element is mandatory. It specifies the number of configurations. These number of <ImageCacheConfig> elements are expected also in the <CacheConfig> element. For each ImageCacheConfig elements one <Resolution> element, one <CacheSize> element, one <ReplacementFree> element and one <ReplacementUsed> element is needed.

In the resolution element a string describing the resolution in the form "(X-Resolution)x(Y-Resolution)" is mandatory. A string "_(AppendString)" my be added to the resolution string. To Load a resolution with AppendString, the AppendString needs to be specified using SetReadResolutionAppendix(const eC_String& kAppendString).

The <CacheSize> element specifies the cache size in bytes

<ReplacementFree> element specifies the ReplacementPolicyType_t for Free replacement policy casted to a number

<ReplacementUsed> element specifies the ReplacementPolicyType_t for Used replacement policy casted to a number

A valid XML file looks like that:

<CacheConfig>
    <FileVersion>1</FileVersion>
    <Entries>2</Entries>
    <ImageCacheConfig>
        <Resolution>240x320</Resolution>
        <CacheSize>65535</CacheSize>
        <ReplacementFree>3</ReplacementFree>
        <ReplacementUsed>3</ReplacementUsed>
    </ImageCacheConfig>
    <ImageCacheConfig>
        <Resolution>480x640_AppendString</Resolution>
        <CacheSize>1048576</CacheSize>
        <ReplacementFree>2</ReplacementFree>
        <ReplacementUsed>1</ReplacementUsed>
    </ImageCacheConfig>
</CacheConfig>

Enumeration Type Documentation

ReplacementPolicyType_t

enum ReplacementPolicyType_t

Enumeration of replacement policies

Enumerator
IC_REPLACEMENT_POLICY_DUMMY	Images can be added, but not removed.
IC_REPLACEMENT_POLICY_GREEDY	Delete biggest image first.
IC_REPLACEMENT_POLICY_FIFO	First in first out.
IC_REPLACEMENT_POLICY_LRU	Last recently used.