This class manages a virtual volume organizing efficient voxel access to the output image of an input module given as input inIdx of thisBaseOp. More...

#include <mlVirtualVolume.h>

Public Types
enum	PageMapped { IsMapped, IsUnMapped }
	Enum which describes whether a page is mapped into the currently used page list or unmapped from used pages. More...
typedef void(*	PageFunc )(VirtualVolume obj, PageBuffer page, PageMapped mapped, void *userData)
	Function type which can be registered in the TVirtualVolume and which is called when a page is mapped or unmapped.
Public Member Functions
	VirtualVolume (PagedImage *image, MLDataType dType, MLint maxNumKB=-1, bool areExceptionsOnFlag=false)
	Constructor to map a pagedImg.
	VirtualVolume (const ImageVector &ext=ImageVector(0), MLdouble fillVal=0, MLDataType dType=MLuint8Type, MLint maxNumKB=-1, bool areExceptionsOnFlag=false)
	Constructor to map an image of extents ext (default is 256) filled with fillVal (default is 0).
virtual	~VirtualVolume ()
	Destructor.
MLint	getDim () const
	Return dimension of specified volume.
const SubImageBox &	getBox () const
	Get box extents of input volume.
ImageVector	getExtent () const
	Get extents of input volume.
MLDataType	getDataType () const
	Return data type enum.
Module *	getModule () const
	Returns the pointer to the module which contains the paged image the virtual volume is associated with.
PagedImage *	getInputImage () const
	Returns the pointer to the paged image the virtual volume is associated with.
MLint	getInputIndex () const
	Returns the output index of the input baseOp or -1 if there is no input baseOp.
bool	isValid () const
	Returns true if instance is valid, otherwise false.
void	invalidate ()
	Invalidates state of virtual volume, e.g. after an error.
MLuint	getNumMappedPages () const
	Returns number of currently mapped (volatile) pages. Written pages are counted only temporarily here.
MLuint	getNumWrittenPages ()
	Returns number of written (and therefore locked) pages.
MLuint	getNumPages ()
	Returns number of all (mapped and written) pages.
MLuint	getNumBytes ()
	Returns number of bytes currently allocated as pages in the virtual volume.
bool	areExceptionsOn () const
	Returns true if exception handling is enabled otherwise false.
const ImageVector &	getPageExtent () const
	Returns the extent of any written/read page used by the virtual volume.
const ImageVector &	getPageArrayExtent () const
	Returns the extent of the array of page buffers.
const SubImageBox &	getWrittenPageBox (MLuint32 wp)
	Returns box of written page no.
void *	getWrittenPageData (MLuint32 wp)
	Returns untyped pointer to data of written page with page id wp.
void	unMapAndClearWrittenPages ()
	This function throws away all written pages.
void	registerPageFunction (PageFunc pFunc, void *userData)
	Register a function to be called when a page is mapped or unmapped.
void	resize (const ImageVector &newExt)
	This method resizes the virtual volume to the extents given by ext.
void	copyTileFromInputImage (const SubImageBox &box, PagedImage &image, const ImageVector &shift, const ScaleShiftData &scaleShift=ScaleShiftData())
	Copy an image region box from the `image` and write to the position resulting from box + shift into the virtual volume.
void	copyToSubImage (SubImage &outSubImg)
	Copy area from virtual volume into outSubImg.
BitImage *	getUsedPagesMask (bool enableMappedPages=true, bool enableWrittenPages=true) const
	Returns a pointer BitImage containing a bit for each page of the virtual volume.
void *	createTypedVirtualVolume ()
	Creates and returns a typed version of this virtual volume as void pointer or NULL on failure.
Static Public Member Functions
static void	destroyTypedVirtualVolume (void *tVV, MLDataType dt)
	Destroys a typed version of a virtual volume given by a void pointer tVV of data type dt.
Friends
class	VirtualVolumeMemoryTracker
Deprecated methods.
class	TVirtualVolume
	For performance reasons permit direct member access of TVirtualVolume to this class.
ImageVector	getExt () const
BaseOp *	getBaseOp () const
PagedImage *	getInImg () const
MLint	getInIdx () const
const ImageVector &	getPageExt () const
const ImageVector &	getPageArrayExt () const
void	copyTileFromInImg (const SubImageBox &box, PagedImage &image, const ImageVector &shift, const ScaleShiftData &scaleShift=ScaleShiftData())
void	copyToSubImg (SubImage &outSubImg)
ML_DEPRECATED_CONSTRUCTOR	VirtualVolume (Module *baseOp, MLint connIdx, MLDataType dType, MLint maxNumKB=-1, bool areExceptionsOnFlag=false, bool useOutConnectors=false)
void	copyTileFromInImg (const SubImageBox &box, Module &op, MLint outIdx, const ImageVector &shift, const ScaleShiftData &scaleShift=ScaleShiftData())
void	_init (PagedImage *img, const ImageVector &ext, MLdouble fillVal, MLDataType dType, MLint maxNumKB=-1, bool areExceptionsOnFlag=false)
	Constructor-like initialization of the instance.
void	_reset ()
	Cleans up all allocated memory and resets instance to state after _default().
void	_cleanUpMemory ()
	Cleans up all allocated memory areas.
void	_default ()
	Set all members to default values without freeing anything.
void *	_loadPage (PageBuffer *pageBuffer)
	This function really loads the page into the memory and updates the corresponding page buffer so that it contains the page and that it uses other, faster access functions.
void	_updateWrittenPages ()
	This function moves all written pages to _writtenPages to have a valid base to work on all written pages.
PageBuffer *	_getPageBuffer6D (const ImageVector &pos)
	Returns the pageBuffer containing the voxel passed as position.
static void *	_getPageCB (PageBuffer *pageBuffer)
	Simply return the data of the page. This is the normal access function to page data.
static void *	_loadPageCB (PageBuffer *pageBuffer)
	This function calls the page loading method of Virtual volume.

Detailed Description

This class manages a virtual volume organizing efficient voxel access to the output image of an input module given as input inIdx of thisBaseOp.

The image data will be allocated and managed in data type dType. maxNumKB determines the size of a temporary buffer for input pages. Only the number of read pages is limited by maxNumKB. Written pages are always buffered since they cannot be freed without data information loss; their number has nothing to do with maxNumKB. The default value of -1 for maxNumKB automatically permits enough memory for the buffered read pages such that one horizontal x-line can be accessed without remapping/swapping of pages. Note:

This class still does not implement any set or get methods for voxels since this is done by the specialized class TVirtualVolume.

Definition at line 70 of file mlVirtualVolume.h.

Member Typedef Documentation

typedef void(* ml::VirtualVolume::PageFunc)(VirtualVolume *obj, PageBuffer *page, PageMapped mapped, void *userData)

Function type which can be registered in the TVirtualVolume and which is called when a page is mapped or unmapped.

The pointer to the virtual volume which handles this page is passed in obj, the pointer to the manipulated page is passed in page and mapped returns a PageMapped enumerator which describes whether the page is mapped/created or unmapped/removed.

Definition at line 177 of file mlVirtualVolume.h.

Member Enumeration Documentation

enum ml::VirtualVolume::PageMapped

Enum which describes whether a page is mapped into the currently used page list or unmapped from used pages.

Enumerator:

IsMapped
IsUnMapped

Definition at line 170 of file mlVirtualVolume.h.

Constructor & Destructor Documentation

ml::VirtualVolume::VirtualVolume	(	PagedImage *	image,
		MLDataType	dType,
		MLint	maxNumKB = `-1`,
		bool	areExceptionsOnFlag = `false`
	)

Constructor to map a pagedImg.

Requires the module and its input to be mapped. See init for parameters.

ml::VirtualVolume::VirtualVolume	(	const ImageVector &	ext = `ImageVector(0)`,
		MLdouble	fillVal = `0`,
		MLDataType	dType = `MLuint8Type`,
		MLint	maxNumKB = `-1`,
		bool	areExceptionsOnFlag = `false`
	)

Constructor to map an image of extents ext (default is 256) filled with fillVal (default is 0).

dType defines the data type of the virtual volume (default is MLuint8Type). maxNumKB=-1 means that enough pages are buffered so that at least one horizontal line of image data can be accessed without swapping pages. Otherwise maxNumKB determines the maximum buffer size for all swapped read pages. Enable testing of all calls if areExceptionsOnFlag is true, otherwise errors only partially throw exceptions.

virtual ml::VirtualVolume::~VirtualVolume ( ) [inline, virtual]

Destructor.

Definition at line 98 of file mlVirtualVolume.h.

ML_DEPRECATED_CONSTRUCTOR ml::VirtualVolume::VirtualVolume	(	Module *	baseOp,
		MLint	connIdx,
		MLDataType	dType,
		MLint	maxNumKB = `-1`,
		bool	areExceptionsOnFlag = `false`,
		bool	useOutConnectors = `false`
	)

Deprecated:: Use constructor with PagedImage instead.

Member Function Documentation

void ml::VirtualVolume::_cleanUpMemory ( ) [protected]

Cleans up all allocated memory areas.

void ml::VirtualVolume::_default ( ) [protected]

Set all members to default values without freeing anything.

PageBuffer* ml::VirtualVolume::_getPageBuffer6D ( const ImageVector & pos ) [protected]

Returns the pageBuffer containing the voxel passed as position.

Returns NULL if voxel is outside image.

void * ml::VirtualVolume::_getPageCB ( PageBuffer * pageBuffer ) [inline, static, protected]

Simply return the data of the page. This is the normal access function to page data.

Simply return the data of the page.

This is the normal access function to page data. This function is used as _getPageFkt after load of page.

Definition at line 567 of file mlVirtualVolume.h.

References ml::PageBuffer::_page.

void ml::VirtualVolume::_init	(	PagedImage *	img,
		const ImageVector &	ext,
		MLdouble	fillVal,
		MLDataType	dType,
		MLint	maxNumKB = `-1`,
		bool	areExceptionsOnFlag = `false`
	)		`[protected]`

Constructor-like initialization of the instance.

baseOp is the baseOp using the virtual volume. If NULL is passed empty pages filled with fillValue are constructed. inIdx determines the input number of baseOp from which the image shall be mapped. Ignored if baseOp is NULL. ext defines the extents of the volume if no baseOp is specified. Otherwise it's replaced by the extents of the input image inIdx of thisBaseOp. dType defines the data type of the virtual volume. maxNumKB=-1 means that enough pages are buffered so that at least one horizontal line of image data can be accessed without swapping pages. Otherwise maxNumKB determines the maximum buffer size for all swapped read pages. Written pages are handled extra and are not limited by maxNumKB. If areExceptionsOnFlag is true then in all access functions tests are applied and exceptions- are thrown if anything fails. These functions are slower then. If areExceptionsOnFlag is false then only at non time critical positions tests are performed and the corresponding exceptions are thrown. If useOutConnectors are false (which is the default) then connIdx is interpreted as the input connector index of baseOp from which to get the image data. If it's true the data is requested from the output connector connIdx of baseOp.

void* ml::VirtualVolume::_loadPage ( PageBuffer * pageBuffer ) [protected]

This function really loads the page into the memory and updates the corresponding page buffer so that it contains the page and that it uses other, faster access functions.

Time critical!

static void* ml::VirtualVolume::_loadPageCB ( PageBuffer * pageBuffer ) [static, protected]

This function calls the page loading method of Virtual volume.

It returns the page data like _getPageCB then. Important: This function must be static and implemented in the .cpp and NOT inline to make its function pointer unique, because it will be checked at many places whether this function or another is used.

void ml::VirtualVolume::_reset ( ) [protected]

Cleans up all allocated memory and resets instance to state after _default().

void ml::VirtualVolume::_updateWrittenPages ( ) [protected]

This function moves all written pages to _writtenPages to have a valid base to work on all written pages.

bool ml::VirtualVolume::areExceptionsOn ( ) const [inline]

Returns true if exception handling is enabled otherwise false.

Definition at line 142 of file mlVirtualVolume.h.

void ml::VirtualVolume::copyTileFromInImg	(	const SubImageBox &	box,
		Module &	op,
		MLint	outIdx,
		const ImageVector &	shift,
		const ScaleShiftData &	scaleShift = `ScaleShiftData()`
	)

Deprecated:: Use copyTileFromInputImage() with PagedImage instead.

void ml::VirtualVolume::copyTileFromInImg	(	const SubImageBox &	box,
		PagedImage &	image,
		const ImageVector &	shift,
		const ScaleShiftData &	scaleShift = `ScaleShiftData()`
	)		`[inline]`

Deprecated:: Use copyTileFromInputImage() instead.

Definition at line 293 of file mlVirtualVolume.h.

void ml::VirtualVolume::copyTileFromInputImage	(	const SubImageBox &	box,
		PagedImage &	image,
		const ImageVector &	shift,
		const ScaleShiftData &	scaleShift = `ScaleShiftData()`
	)

Copy an image region box from the image and write to the position resulting from box + shift into the virtual volume.

The data loaded from the input image is transformed by scaleShift whose default is the identical transformation. If necessary the data values from the input are cast to the virtual volume data type. Errors are reported by thrown exceptions if exception handling is enabled; otherwise they lead to ML_PRINT_ERROR or ML_PRINT_FATAL_ERROR messages. Only valid regions of the virtual volume are written; box is clipped against the virtual volume extents before writing the data region.

void ml::VirtualVolume::copyToSubImage ( SubImage & outSubImg )

Copy area from virtual volume into outSubImg.

Only areas which are valid in this and in outSubImg are copied. If necessary the image data type is cast to the data type of outSubImg. Errors are reported by thrown exceptions if exception handling is enabled; otherwise they lead to ML_PRINT_ERROR or ML_PRINT_FATAL_ERROR messages. Only valid regions of the virtual volume are read and written into outSubImg.

void ml::VirtualVolume::copyToSubImg ( SubImage & outSubImg ) [inline]

Deprecated:: Use copyToSubImage() instead.

Definition at line 300 of file mlVirtualVolume.h.

void* ml::VirtualVolume::createTypedVirtualVolume ( )

Creates and returns a typed version of this virtual volume as void pointer or NULL on failure.

static void ml::VirtualVolume::destroyTypedVirtualVolume	(	void *	tVV,
		MLDataType	dt
	)		`[static]`

Destroys a typed version of a virtual volume given by a void pointer tVV of data type dt.

Calls with tVV == NULL will be ignored without error.

BaseOp* ml::VirtualVolume::getBaseOp ( ) const

Deprecated:: Use getModule() instead.

const SubImageBox& ml::VirtualVolume::getBox ( ) const [inline]

Get box extents of input volume.

Definition at line 104 of file mlVirtualVolume.h.

MLDataType ml::VirtualVolume::getDataType ( void ) const [inline]

Return data type enum.

Definition at line 110 of file mlVirtualVolume.h.

Referenced by ml::TVirtualVolume< DATATYPE >::_init().

MLint ml::VirtualVolume::getDim ( ) const [inline]

Return dimension of specified volume.

Definition at line 101 of file mlVirtualVolume.h.

Referenced by ml::TVirtualVolume< DATATYPE >::_init().

ImageVector ml::VirtualVolume::getExt ( ) const [inline]

Deprecated:: Use getExtent() instead.

Definition at line 269 of file mlVirtualVolume.h.

ImageVector ml::VirtualVolume::getExtent ( ) const [inline]

Get extents of input volume.

Definition at line 107 of file mlVirtualVolume.h.

MLint ml::VirtualVolume::getInIdx ( ) const [inline]

Deprecated:: Use getInputIndex() instead.

Definition at line 281 of file mlVirtualVolume.h.

PagedImage* ml::VirtualVolume::getInImg ( ) const [inline]

Deprecated:: Use getInputImage() instead.

Definition at line 277 of file mlVirtualVolume.h.

PagedImage* ml::VirtualVolume::getInputImage ( ) const [inline]

Returns the pointer to the paged image the virtual volume is associated with.

It is NULL if there is no input image.

Definition at line 118 of file mlVirtualVolume.h.

MLint ml::VirtualVolume::getInputIndex ( ) const [inline]

Returns the output index of the input baseOp or -1 if there is no input baseOp.

Definition at line 121 of file mlVirtualVolume.h.

Module* ml::VirtualVolume::getModule ( ) const [inline]

Returns the pointer to the module which contains the paged image the virtual volume is associated with.

It is NULL if there is no input image.

Definition at line 114 of file mlVirtualVolume.h.

MLuint ml::VirtualVolume::getNumBytes ( ) [inline]

Returns number of bytes currently allocated as pages in the virtual volume.

Definition at line 139 of file mlVirtualVolume.h.

MLuint ml::VirtualVolume::getNumMappedPages ( ) const [inline]

Returns number of currently mapped (volatile) pages. Written pages are counted only temporarily here.

Definition at line 130 of file mlVirtualVolume.h.

MLuint ml::VirtualVolume::getNumPages ( ) [inline]

Returns number of all (mapped and written) pages.

Definition at line 136 of file mlVirtualVolume.h.

MLuint ml::VirtualVolume::getNumWrittenPages ( ) [inline]

Returns number of written (and therefore locked) pages.

Definition at line 133 of file mlVirtualVolume.h.

const ImageVector& ml::VirtualVolume::getPageArrayExt ( ) const [inline]

Deprecated:: Use getPageArrayExtent() instead.

Definition at line 289 of file mlVirtualVolume.h.

const ImageVector& ml::VirtualVolume::getPageArrayExtent ( ) const [inline]

Returns the extent of the array of page buffers.

Definition at line 148 of file mlVirtualVolume.h.

const ImageVector& ml::VirtualVolume::getPageExt ( ) const [inline]

Deprecated:: Use getPageExtent() instead.

Definition at line 285 of file mlVirtualVolume.h.

const ImageVector& ml::VirtualVolume::getPageExtent ( ) const [inline]

Returns the extent of any written/read page used by the virtual volume.

Definition at line 145 of file mlVirtualVolume.h.

BitImage* ml::VirtualVolume::getUsedPagesMask	(	bool	enableMappedPages = `true`,
		bool	enableWrittenPages = `true`
	)		const

Returns a pointer BitImage containing a bit for each page of the virtual volume.

Unmapped or unwritten pages are always set to false. If enableMappedPages is true then all mapped pages are set to true. If enableWrittenPages is true then all written pages are set to true. On any type of failure, invalid virtual volume settings etc. NULL is returned. On non NULL returns the object must be deleted by the application. Returned BitImages will always have enabled exception handling.

const SubImageBox& ml::VirtualVolume::getWrittenPageBox ( MLuint32 wp ) [inline]

Returns box of written page no.

wp. wp must be within [0, getNumWrittenPages()-1]. Note: Page box may reach out of image if page is a border page.

void* ml::VirtualVolume::getWrittenPageData ( MLuint32 wp )

Returns untyped pointer to data of written page with page id wp.

Parameters:

wp	is the page id of the written page to access and it must be within [0, getNumWrittenPages()-1].

Returns:: The pointer to the data related to page with index wp or NULL if wp is out of range.

Note:: If page is a page crossed by the image border then it could also contain undefined data.; The number of voxels in such a page is given by getPageExtent().compMul().

void ml::VirtualVolume::invalidate ( ) [inline]

Invalidates state of virtual volume, e.g. after an error.

Definition at line 127 of file mlVirtualVolume.h.

bool ml::VirtualVolume::isValid ( void ) const [inline]

Returns true if instance is valid, otherwise false.

Definition at line 124 of file mlVirtualVolume.h.

void ml::VirtualVolume::registerPageFunction	(	PageFunc	pFunc,
		void *	userData
	)

Register a function to be called when a page is mapped or unmapped.

The first parameter is the function to be registered, the second parameter is the user data to be passed to the called function. Pass (NULL, NULL) as first parameter to unregister any registered function.

void ml::VirtualVolume::resize ( const ImageVector & newExt )

This method resizes the virtual volume to the extents given by ext.

Pages which do not overlap any longer with the image are thrown away and areas where new pages are needed there the corresponding tables are updated. Already mapped pages which are overlapped by the image before and after the resizing operation will remain without changing the mapping state. Note the resizing a virtual volume associated to a Module cannot work since the image of the Module would also need a resize. In that case of errors an MLErrorCode exception will be thrown if exception handling is enabled; otherwise ML_PRINT_ERROR or ML_PRINT_FATAL_ERROR messages will be generated. Resizing invalid virtual volumes or other errors will also be handled like this. IMPORTANT: TVirtualVolumes referencing VirtualVolume objects must be removed before calling resize and recreated after resizing. They become instable otherwise.

void ml::VirtualVolume::unMapAndClearWrittenPages ( )

This function throws away all written pages.

So accesses to the previously written pages will access the original data. Note that this destroys all written information in the image. Currently mapped pages which are not written remain mapped and unchanged.

Friends And Related Function Documentation

friend class TVirtualVolume [friend]

For performance reasons permit direct member access of TVirtualVolume to this class.

Definition at line 365 of file mlVirtualVolume.h.

friend class VirtualVolumeMemoryTracker [friend]

Definition at line 521 of file mlVirtualVolume.h.

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

MeVisLab/Standard/Sources/ML/MLTools/include/mlVirtualVolume.h

Public Types

Public Member Functions

Static Public Member Functions