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. More...

Public Member Functions
	VirtualVolume (PagedImage *image, MLDataType dType, MLint maxNumKB=-1, bool areExceptionsOnFlag=false)
	Constructor to map a pagedImg. More...

	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). More...

	VirtualVolume (const ImageVector &extent, const ImageVector &pageExtent, MLdouble fillVal=0, MLDataType dType=MLuint8Type, MLint maxNumKB=-1, bool areExceptionsOnFlag=false)
	Constructor that allows to pass the pageExtent. More...

virtual	~VirtualVolume ()
	Destructor. More...

MLint	getDim () const
	Return dimension of specified volume. More...

const SubImageBox &	getBox () const
	Get box extents of input volume. More...

ImageVector	getExtent () const
	Get extents of input volume. More...

MLDataType	getDataType () const
	Return data type enum. More...

Module *	getModule () const
	Returns the pointer to the module which contains the paged image the virtual volume is associated with. More...

PagedImage *	getInputImage () const
	Returns the pointer to the paged image the virtual volume is associated with. More...

MLint	getInputIndex () const
	Returns the output index of the input baseOp or -1 if there is no input baseOp. More...

bool	isValid () const
	Returns true if instance is valid, otherwise false. More...

void	invalidate ()
	Invalidates state of virtual volume, e.g. after an error. More...

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

MLuint	getNumWrittenPages ()
	Returns number of written (and therefore locked) pages. More...

MLuint	getNumPages ()
	Returns number of all (mapped and written) pages. More...

MLuint	getNumBytes ()
	Returns number of bytes currently allocated as pages in the virtual volume. More...

bool	areExceptionsOn () const
	Returns true if exception handling is enabled otherwise false. More...

const ImageVector &	getPageExtent () const
	Returns the extent of any written/read page used by the virtual volume. More...

const ImageVector &	getPageArrayExtent () const
	Returns the extent of the array of page buffers. More...

const SubImageBox &	getWrittenPageBox (MLuint32 wp)
	Returns box of written page no. More...

void *	getWrittenPageData (MLuint32 wp)
	Returns untyped pointer to data of written page with page id wp. More...

void	unMapAndClearWrittenPages ()
	This function throws away all written pages. More...

void	registerPageFunction (PageFunc pFunc, void *userData)
	Register a function to be called when a page is mapped or unmapped. More...

void	resize (const ImageVector &newExt)
	This method resizes the virtual volume to the extents given by ext. More...

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. More...

void	copyToSubImage (SubImage &outSubImg)
	Copy area from virtual volume into outSubImg. More...

BitImage *	getUsedPagesMask (bool enableMappedPages=true, bool enableWrittenPages=true) const
	Returns a pointer BitImage containing a bit for each page of the virtual volume. More...

void *	createTypedVirtualVolume ()
	Creates and returns a typed version of this virtual volume as void pointer or NULL on failure. More...

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. More...

Protected Member Functions
void	_init (PagedImage *img, const ImageVector &ext, const ImageVector &pageExtent, MLdouble fillVal, MLDataType dType, MLint maxNumKB=-1, bool areExceptionsOnFlag=false)
	Constructor-like initialization of the instance. More...

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

void	_cleanUpMemory ()
	Cleans up all allocated memory areas. More...

void	_default ()
	Set all members to default values without freeing anything. More...

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. More...

void	_updateWrittenPages ()
	This function moves all written pages to _writtenPages to have a valid base to work on all written pages. More...

PageBuffer *	_getPageBuffer6D (const ImageVector &pos)
	Returns the pageBuffer containing the voxel passed as position. More...

Static Protected Member Functions
static void *	_getPageCB (PageBuffer *pageBuffer)
	Simply return the data of the page. This is the normal access function to page data. More...

static void *	_loadPageCB (PageBuffer *pageBuffer)
	This function calls the page loading method of Virtual volume. More...

Friends
template<typename >
class	TVirtualVolume
	For performance reasons permit direct member access of TVirtualVolume to this class. More...

class	VirtualVolumeMemoryTracker

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 74 of file mlVirtualVolume.h.

Member Typedef Documentation

◆ PageFunc

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 188 of file mlVirtualVolume.h.

Member Enumeration Documentation

◆ PageMapped

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 181 of file mlVirtualVolume.h.

Constructor & Destructor Documentation

◆ VirtualVolume() [1/3]

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.

◆ VirtualVolume() [2/3]

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.

◆ VirtualVolume() [3/3]

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

Constructor that allows to pass the pageExtent.

◆ ~VirtualVolume()

virtual ml::VirtualVolume::~VirtualVolume ( )

inlinevirtual

Destructor.

Definition at line 109 of file mlVirtualVolume.h.

Member Function Documentation

◆ _cleanUpMemory()

void ml::VirtualVolume::_cleanUpMemory ( )

protected

Cleans up all allocated memory areas.

◆ _default()

void ml::VirtualVolume::_default ( )

protected

Set all members to default values without freeing anything.

◆ _getPageBuffer6D()

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

protected

Returns the pageBuffer containing the voxel passed as position.

Returns NULL if voxel is outside image.

◆ _getPageCB()

void * ml::VirtualVolume::_getPageCB ( PageBuffer * pageBuffer )

inlinestaticprotected

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 568 of file mlVirtualVolume.h.

References ml::PageBuffer::_page.

◆ _init()

void ml::VirtualVolume::_init	(	PagedImage *	img,
		const ImageVector &	ext,
		const ImageVector &	pageExtent,
		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.

◆ _loadPage()

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!

◆ _loadPageCB()

static void* ml::VirtualVolume::_loadPageCB ( PageBuffer * pageBuffer )

staticprotected

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.

◆ _reset()

void ml::VirtualVolume::_reset ( )

protected

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

◆ _updateWrittenPages()

void ml::VirtualVolume::_updateWrittenPages ( )

protected

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

◆ areExceptionsOn()

bool ml::VirtualVolume::areExceptionsOn ( ) const

inline

Returns true if exception handling is enabled otherwise false.

Definition at line 153 of file mlVirtualVolume.h.

◆ copyTileFromInputImage()

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.

◆ copyToSubImage()

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.

◆ createTypedVirtualVolume()

void* ml::VirtualVolume::createTypedVirtualVolume ( )

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

◆ destroyTypedVirtualVolume()

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.

◆ getBox()

const SubImageBox& ml::VirtualVolume::getBox ( ) const

inline

Get box extents of input volume.

Definition at line 115 of file mlVirtualVolume.h.

◆ getDataType()

MLDataType ml::VirtualVolume::getDataType ( void ) const

inline

Return data type enum.

Definition at line 121 of file mlVirtualVolume.h.

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

◆ getDim()

MLint ml::VirtualVolume::getDim ( ) const

inline

Return dimension of specified volume.

Definition at line 112 of file mlVirtualVolume.h.

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

◆ getExtent()

ImageVector ml::VirtualVolume::getExtent ( ) const

inline

Get extents of input volume.

Definition at line 118 of file mlVirtualVolume.h.

◆ getInputImage()

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 129 of file mlVirtualVolume.h.

◆ getInputIndex()

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 132 of file mlVirtualVolume.h.

◆ getModule()

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 125 of file mlVirtualVolume.h.

◆ getNumBytes()

MLuint ml::VirtualVolume::getNumBytes ( )

inline

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

Definition at line 150 of file mlVirtualVolume.h.

◆ getNumMappedPages()

MLuint ml::VirtualVolume::getNumMappedPages ( ) const

inline

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

Definition at line 141 of file mlVirtualVolume.h.

◆ getNumPages()

MLuint ml::VirtualVolume::getNumPages ( )

inline

Returns number of all (mapped and written) pages.

Definition at line 147 of file mlVirtualVolume.h.

◆ getNumWrittenPages()

MLuint ml::VirtualVolume::getNumWrittenPages ( )

inline

Returns number of written (and therefore locked) pages.

Definition at line 144 of file mlVirtualVolume.h.

◆ getPageArrayExtent()

const ImageVector& ml::VirtualVolume::getPageArrayExtent ( ) const

inline

Returns the extent of the array of page buffers.

Definition at line 159 of file mlVirtualVolume.h.

◆ getPageExtent()

const ImageVector& ml::VirtualVolume::getPageExtent ( ) const

inline

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

Definition at line 156 of file mlVirtualVolume.h.

◆ getUsedPagesMask()

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.

◆ getWrittenPageBox()

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.

◆ getWrittenPageData()

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().

◆ invalidate()

void ml::VirtualVolume::invalidate ( )

inline

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

Definition at line 138 of file mlVirtualVolume.h.

◆ isValid()

bool ml::VirtualVolume::isValid ( void ) const

inline

Returns true if instance is valid, otherwise false.

Definition at line 135 of file mlVirtualVolume.h.

◆ registerPageFunction()

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.

◆ resize()

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.

◆ unMapAndClearWrittenPages()

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

◆ TVirtualVolume

template<typename >

friend class TVirtualVolume

friend

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

Definition at line 369 of file mlVirtualVolume.h.

◆ VirtualVolumeMemoryTracker

friend class VirtualVolumeMemoryTracker

friend

Definition at line 522 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

Protected Member Functions

Static Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ PageFunc

Member Enumeration Documentation

◆ PageMapped

Constructor & Destructor Documentation

◆ VirtualVolume() [1/3]

◆ VirtualVolume() [2/3]

◆ VirtualVolume() [3/3]

◆ ~VirtualVolume()

Member Function Documentation

◆ _cleanUpMemory()

◆ _default()

◆ _getPageBuffer6D()

◆ _getPageCB()

◆ _init()

◆ _loadPage()

◆ _loadPageCB()

◆ _reset()

◆ _updateWrittenPages()

◆ areExceptionsOn()

◆ copyTileFromInputImage()

◆ copyToSubImage()

◆ createTypedVirtualVolume()

◆ destroyTypedVirtualVolume()

◆ getBox()

◆ getDataType()

◆ getDim()

◆ getExtent()

◆ getInputImage()

◆ getInputIndex()

◆ getModule()

◆ getNumBytes()

◆ getNumMappedPages()

◆ getNumPages()

◆ getNumWrittenPages()

◆ getPageArrayExtent()

◆ getPageExtent()

◆ getUsedPagesMask()

◆ getWrittenPageBox()

◆ getWrittenPageData()

◆ invalidate()

◆ isValid()

◆ registerPageFunction()

◆ resize()

◆ unMapAndClearWrittenPages()

Friends And Related Function Documentation

◆ TVirtualVolume

◆ VirtualVolumeMemoryTracker