PtexCache Class Reference

File-handle and memory cache for reading ptex files. More...

#include <Ptexture.h>

Inheritance diagram for PtexCache:

Classes
struct	Stats

Public Member Functions
virtual void	release ()=0
	Release PtexCache. Cache will be immediately destroyed and all resources will be released. More...
virtual void	setSearchPath (const char *path)=0
	Set a search path for finding textures. More...
virtual const char *	getSearchPath ()=0
	Query the search path. More...
virtual PtexTexture *	get (const char *path, Ptex::String &error)=0
	Access a texture. More...
virtual void	purge (PtexTexture *texture)=0
	Remove a texture file from the cache. More...
virtual void	purge (const char *path)=0
	Remove a texture file from the cache by pathname. More...
virtual void	purgeAll ()=0
	Remove all texture files from the cache. More...
virtual void	getStats (Stats &stats)=0
	Get stats. More...

Static Public Member Functions
static PtexCache *	create (int maxFiles, size_t maxMem, bool premultiply=false, PtexInputHandler *inputHandler=0, PtexErrorHandler *errorHandler=0)
	Create a cache with the specified limits. More...

Protected Member Functions
virtual	~PtexCache ()
	Destructor not for public use. Use release() instead. More...

Detailed Description

File-handle and memory cache for reading ptex files.

The PtexCache class allows cached read access to multiple ptex files while constraining the open file count and memory usage to specified limits. File and data objects accessed via the cache are added back to the cache when their release method is called. Released objects are maintained in an LRU list and only destroyed when the specified resource limits are exceeded.

The cache is fully multi-threaded. Cached data will be shared among all threads that have access to the cache, and the data are protected with internal locks. See PtexCache.cpp for details about the caching and locking implementation.

Definition at line 697 of file Ptexture.h.

Constructor & Destructor Documentation

~PtexCache()

virtual PtexCache::~PtexCache ( )

inlineprotectedvirtual

Destructor not for public use. Use release() instead.

Definition at line 700 of file Ptexture.h.

Member Function Documentation

create()

PtexCache * PtexCache::create ( int  maxFiles, size_t  maxMem, bool  premultiply = false, PtexInputHandler *  inputHandler = 0, PtexErrorHandler *  errorHandler = 0  )

static

Create a cache with the specified limits.

Parameters

maxFiles	Maximum open file handles. If zero, limit is set to 100 open files.
maxMem	Maximum allocated memory, in bytes. If zero the cache is unlimited.
premultiply	If true, textures will be premultiplied by the alpha channel (if any) when read from disk. For authoring purposes, this should generally be set to false, and for rendering purposes, this should generally be set to true. See PtexTexture and PtexWriter for more details.
inputHandler	If specified, all input calls made through this cache will be directed through the handler.
errorHandler	If specified, errors encounted with files access through this cache will be directed to the handler. By default, errors will be reported to stderr.

Definition at line 177 of file PtexCache.cpp.

get()

virtual PtexTexture* PtexCache::get ( const char *  path, Ptex::String &  error  )

pure virtual

Access a texture.

If the specified path was previously accessed from the cache, then a pointer to the cached texture will be returned.

If the specified path hasn't been opened yet or was purged from the cache (via the purge or purgeAll methods) then the file will be opened. If the path is relative (i.e. doesn't begin with a '/') then the search path will be used to locate the file.

The texture will be accessible until the PtexTexture::release method is called, at which point the texture will be returned to the cache. Once released, the texture may have it's data pruned (immediately or some time later) to stay within the maximum cache size.

If the texture could not be opened, null will be returned and an error string will be set. If an error were previously encountered with the file (include the file not being found), null will be returned and no error string will be set.

Parameters

path	File path. If path is relative, search path will be used to find the file.
error	Error string set if texture could not be opened.

Implemented in PtexReaderCache.

getSearchPath()

virtual const char* PtexCache::getSearchPath ( )

pure virtual

Query the search path.

Returns string set via setSearchPath.

Implemented in PtexReaderCache.

getStats()

virtual void PtexCache::getStats ( Stats &  stats )

pure virtual

Get stats.

Implemented in PtexReaderCache.

purge() [1/2]

virtual void PtexCache::purge ( const char *  path )

pure virtual

Remove a texture file from the cache by pathname.

The path must match the full path as opened. This function will not search for the file, but if a search path was used, the path must match the path as found by the search path.

Implemented in PtexReaderCache.

purge() [2/2]

virtual void PtexCache::purge ( PtexTexture *  texture )

pure virtual

Remove a texture file from the cache.

If the texture is in use by another thread, that reference will remain valid and the file will be purged once it is no longer in use. This texture should be released immediately after purging.

Implemented in PtexReaderCache.

purgeAll()

virtual void PtexCache::purgeAll ( )

pure virtual

Remove all texture files from the cache.

Textures with active PtexTexture* handles will remain valid and will be purged upon release.

Implemented in PtexReaderCache.

release()

virtual void PtexCache::release ( )

pure virtual

Release PtexCache. Cache will be immediately destroyed and all resources will be released.

Implemented in PtexReaderCache.

setSearchPath()

virtual void PtexCache::setSearchPath ( const char *  path )

pure virtual

Set a search path for finding textures.

Note: if an input handler is installed the search path will be ignored.

Parameters

path	colon-delimited search path.

Implemented in PtexReaderCache.

---

The documentation for this class was generated from the following files:

• Ptexture.h
• PtexCache.cpp