NAME

     ilCacheImg	- class	to implement image data	caching

INHERITS FROM

     ilLink : ilImage

HEADER FILE

     #include <il/ilCacheImg.h>

CLASS DESCRIPTION

     ilCacheImg	implements an abstract model of	cached image data.  The	cache
     assumes that the image data is stored in fixed-size  rectangles called
     pages. The	main purpose of	this class is the definition of	a common API
     for cached	image objects.	Like ilImage, ilCacheImg is an abstract	class,
     requiring further derivation to be	used as	an object.  The	real work of
     implementing a caching mechanism is deferred to derived classes such as
     ilMemCacheImg.

CLASS MEMBER FUNCTION SUMMARY

     Page Management

	  virtual ilStatus flush(int discard=FALSE)
	  virtual size_t getCacheSize()

     Debugging and monitoring

	  void	addPagingCallback(ilCallback* cb, int autoDelete=FALSE)
	  ilStatus  removePagingCallback(ilCallback* cb)
	  int  hasPagingCallbacks()
	  ilStatus  doPagingCallbacks(ilPagingCbArg* callerArg)
	  virtual ilStatus  listResident(ilCallback* cb)

FUNCTION DESCRIPTIONS

     ilCacheImg()

	  ilCacheImg()


	  The constructor handles all necessary	initialization of the call
	  backs.  Derived classes are responsible for everything else.

     addPagingCallback()

	  void	addPagingCallback(ilCallback* cb, int autoDelete=FALSE)


	  This function	can used to add	a callback on paging operations	for
	  this object.	The cb parameter is a callback method or function.  A
	  new callback can be derived from the class ilPagingMethodCallback
	  (for a callback method), or from ilPagingFunctionCallback (for a
	  callback function).
	  For example, to define the member function doPaging of class Foo as
	  a paging callback method:

	       void Foo::doPaging(UserArgType* userArg,
			 ilPagingCbArg*	pageDesc);
	       typedef ilPagingMethodCallback<Foo,UserArgType*>
			 UserPagingCallback;

	       Foo foo;
	       UserArgType userArg;
	       UserPagingCallback pagingCB(&arg, Foo::doPaging,	&foo);

	       img->addPagingCallback(&pagingCB);

	  The userArg can be of	any type. Its purpose is to maintain context
	  for the callback; it is not referenced by IL.	 When the callback is
	  invoked, the pageDesc	argument will contain a	pointer	to this	image
	  object and the location and status of	the page.

     doPagingCallbacks()

	  void	doPagingCallbacks(ilPagingCbArg* callerArg)


	  This function	invokes	all defined paging callbacks for this image
	  object; the callerArg	argument specifies the page, and its img
	  member should	reference this image object.

     flush()

	  ilStatus flush(int discard=FALSE)


	  This is a virtual function that must be implemented by the derived
	  class.  Its purpose is to write any modified data in the cache to
	  the backing store (if	such a concept is relevant to the derived
	  class).  Derived classes that	access an image	file can call this
	  function in their destructor before the file is closed to ensure
	  that all data	is written. If discard is TRUE,	then the data in the
	  cache, after it is written out, is invalidated and all cache
	  parameters are reset.	If FALSE, then the data	in the cache remains
	  valid.

     getCacheSize()

	  virtual size_t getCacheSize()


	  This function	returns	the amount of cache memory, in bytes,
	  currently allocated by this image object.


     hasPagingCallbacks()

	  int  hasPagingCallbacks()


	  This function	returns	TRUE if	there are any paging callbacks defined
	  for this image object; FALSE otherwise.

     listResident()

	  virtual ilStatus  listResident(ilCallback* cb)


	  The function traverses all the resident pages, invoking the paging
	  callback cb once for each resident page of this image.  The callback
	  should have a	prototype as described for addPagingCallback().

     removePagingCallback()

	  ilStatus  removePagingCallback(ilCallback* cb)


	  This function	removes	a callback that	was previously added with
	  addPagingCallback().

INHERITED MEMBER FUNCTIONS

   Inherited from ilImage
     addInput(), allocFillData(), checkColorModel(), checkValidOrder(),
     checkValidType(), clipTile(), configureRetainedCache(), copy(),
     copyTile(), copyTile3D(), copyTileCfg(), fillTile(), fillTile3D(),
     fillTileRGB(), freeFillData(), getColorImg(), getColorModel(),
     getColormap(), getCompression(), getConfig(), getCopyConverter(),
     getCsize(), getDataType(),	getDimensions(), getDirectInput(),
     getDisplayCacheEnable(), getFill(), getFillData(),	getFillValue(),
     getHeight(), getHwEnable(), getHwHint(), getHwIntHint(), getHwOp(),
     getHwPassTable(), getInput(), getInputTileRequirement(),
     getLockTileSet(), getMaxColormapLevels(), getMaxValue(), getMinValue(),
     getNumChans(), getNumInputs(), getOrder(),	getOrientation(),
     getPageBorder(), getPageBorderX(),	getPageBorderY(), getPageBorderZ(),
     getPageCounts(), getPageDelta(), getPageDimensions(), getPageIndices(),
     getPageOrigin(), getPageOriginC(),	getPageOriginX(), getPageOriginY(),
     getPageOriginZ(), getPageSize(), getPageSizeC(), getPageSizePix(),
     getPageSizeVal(), getPageSizeX(), getPageSizeY(), getPageSizeZ(),
     getPixel(), getPixel3D(), getPriority(), getScaleMax(), getScaleMin(),
     getSize(),	getStrides(), getSubTile(), getSubTile3D(), getTile(),
     getTile3D(), getWidth(), getXsize(), getYsize(), getZsize(),
     hasPageBorder(), hasPages(), hwDefine(), hwGetPass(), inherit(),
     initColorModel(), initHwEnable(), initMinMax(), initPageSize(),
     initScaleMinMax(),	isColorImg(), isIntegral(), isMirrorOrientation(),
     isPartialPage(), isSigned(), isValidPage(), isWritable(), lockPage(),
     lockPageSet(), lockTile(),	lockTile3D(), mapFlipTrans(), mapFromInput(),
     mapFromSource(), mapOrientation(),	mapSize(), mapTile(), mapToInput(),
     mapToSource(), mapXY(), mapXYSign(), outOfBound(),	qCopyTileCfg(),
     qFillTile3D(), qFillTileRGB(), qGetSubTile3D(), qGetTile3D(),
     qLockPageSet(), qSetSubTile3D(), qSetTile3D(), removeHwHint(),
     removeInput(), reset(), setColorModel(), setColormap(), setCompression(),
     setCsize(), setDataType(),	setDisplayCacheEnable(), setFill(),
     setFillValue(), setHwEnable(), setHwHint(), setHwIntHint(), setInput(),
     setMaxColormapLevels(), setMaxValue(), setMinValue(), setNumChans(),
     setNumInputs(), setOrder(), setOrientation(), setPageBorder(),
     setPageSize(), setPageSizeC(), setPageSizeZ(), setPixel(),	setPixel3D(),
     setPriority(), setScaleMinMax(), setScaleType(), setSize(), setSubTile(),
     setSubTile3D(), setTile(),	setTile3D(), setTileRequirementFunction(),
     setWritable(), setXsize(),	setYsize(), setZsize(),	unlockPage(),
     unlockPageSet()

   Inherited from ilLink
     addResetCallback(), alterAction(),	anyAltered(), clearAllowed(),
     clearSet(), clearStatus(),	deleteRelated(), disableAltered(),
     dumpChain(), getClassPropSet(), getDescription(), getDirectParent(),
     getDisabledIndex(), getFloatProp(), getGenerationID(), getIntProp(),
     getMaxIndex(), getMinIndex(), getNumChildren(), getNumParents(),
     getParent(), getProp(), getProp(),	getPropSet(), getPtrProp(),
     getRelatedChild(),	getRelatedDelete(), getRelatedType(), getStatus(),
     hasResetCallbacks(), ilGetClassPropSet(), inProgress(), isAllowed(),
     isAltered(), isEnabled(), isRelated(), isSet(), markSet(),	mpUnlock(),
     neverReset(), newRelatedType(), removeParent(), removeProp(),
     removeResetCallback(), reset(), resetAltered(), resetCheck(),
     setAllowed(), setAltered(), setDescription(), setDisabledIndex(),
     setEnabled(), setParent(),	setProp(), setPropAltered(),
     setRelatedDelete(), setRelatedType(), setStatus(),	stopWatching(),
     unalterable(), watch(), watchNotify()

SEE ALSO

     ilImage, ilMemCacheImg