The SoVirtualVolume class for fast voxel based access to paged ML images; see also mlVirtualVolume and mlTVirtualVolume in project MLTools for examples etc. More...

#include <SoVirtualVolume.h>

Public Member Functions
SO_VIRTUALVOLUME_EXPORT	SoVirtualVolume (SoSFMLImage &image, MLDataType dType=ML_INVALID_DATA_TYPE, long maxNumKB=-1, bool useExceptions=false)
	Constructor which creates a `SoVirtualVolume` interface to an ML paged image hidden behind `image`.

SO_VIRTUALVOLUME_EXPORT	SoVirtualVolume (const XVImageSize &ext=XVImageSize(0), double fillVal=0, MLDataType dType=MLuint8Type, long maxNumKB=-1, bool useExceptions=false)
	Constructor to map an image of extents `ext` filled with `fillVal`.

virtual SO_VIRTUALVOLUME_EXPORT	~SoVirtualVolume ()
	Destructor.

SO_VIRTUALVOLUME_EXPORT bool	isValid () const
	Returns true if access methods may be called, otherwise false.

SO_VIRTUALVOLUME_EXPORT SoSFMLImage *	getImage () const
	Returns the `SoSFMLImage` the `SoVirtualVolume` is associated to or NULL if it's a Virtual Volume of user defined extents and contents.

SO_VIRTUALVOLUME_EXPORT MLDataType	getDataType () const
	Returns the data type used as internal data type of the virtual volume or - if currently no valid virtual volume exists - the value passed as `dType` to the constructor.

long	getMaxNumKB () const
	Returns the `maxNumKB` value passed to the constructor.

bool	areExceptionsOn () const
	Returns the `useExceptions` value passed to the constructor.


SO_VIRTUALVOLUME_EXPORT MLuint	getNumMappedPages () const
	Access functions to virtual volume. Only to be called if `isValid()` returns true!

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

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

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

SO_VIRTUALVOLUME_EXPORT XVImageSize	getPageExtent () const
	Returns extents of a written and read pages used by the virtual volume.

SO_VIRTUALVOLUME_EXPORT XVImageSize	getPageArrayExtent () const
	Returns extents of the array of page buffers.

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

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

SO_VIRTUALVOLUME_EXPORT void	resize (const XVImageSize &newExt)
	This method resizes the virtual volume to the extents given by `ext`.

Functions for virtual volume access and cursor movement, filling etc.
See documentation of corresponding functions in ML_NAMESPACE::TVirtualVolume for a detailed description. Note Template versions of cursor voxel and voxel access functions are often faster since data values are not cast as in the non template versions. Casting `XVIMageSize` to `ml:ImageVector` is legal, the guarantee that they can be cast is guaranteed by checks in SoVirtualVolumeInit. Without that cast a strong performance downgrade would result.
const XVImageSize &	getCursorPosition ()

MLint	getIntValue (const XVImageSize &pos)

MLint64	getInt64Value (const XVImageSize &pos)

MLdouble	getDoubleValue (const XVImageSize &pos)

MLldouble	getLDoubleValue (const XVImageSize &pos)

MLint	getIntCursorValue ()

MLint64	getInt64CursorValue ()

MLdouble	getDoubleCursorValue ()

MLldouble	getLDoubleCursorValue ()

bool	isMapped (const XVImageSize &pos)

void	setCursorPosition (const XVImageSize &pos)

void	setIntValue (const XVImageSize &pos, MLint v)

void	setInt64Value (const XVImageSize &pos, MLint64 v)

void	setDoubleValue (const XVImageSize &pos, MLdouble v)

void	setLDoubleValue (const XVImageSize &pos, MLldouble v)

void	setIntCursorValue (MLint v)

void	setInt64CursorValue (MLint64 v)

void	setDoubleCursorValue (MLdouble v)

void	setLDoubleCursorValue (MLldouble v)

void	fillInt (const XVImageSize &boxV1, const XVImageSize &boxV2, MLint v)

void	fillInt64 (const XVImageSize &boxV1, const XVImageSize &boxV2, MLint64 v)

void	fillDouble (const XVImageSize &boxV1, const XVImageSize &boxV2, MLdouble v)

void	fillLDouble (const XVImageSize &boxV1, const XVImageSize &boxV2, MLldouble v)

void	moveCursorX ()

void	moveCursorY ()

void	moveCursorZ ()

void	moveCursorC ()

void	moveCursorT ()

void	moveCursorU ()

void	reverseMoveCursorX ()

void	reverseMoveCursorY ()

void	reverseMoveCursorZ ()

void	reverseMoveCursorC ()

void	reverseMoveCursorT ()

void	reverseMoveCursorU ()

void	moveCursorByOffset (const XVImageSize &off)

void	resetCursor ()

bool	moveCursorXWrapAround ()

Typed access functions. Only to be called if \c isValid() returns true and \c DATATYPE matches getDataType()!
template<typename DATATYPE >
SO_VIRTUALVOLUME_EXPORT void	getValue (const XVImageSize &pos, DATATYPE &retVal)
	Get a voxel from the virtual volume.

template<typename DATATYPE >
SO_VIRTUALVOLUME_EXPORT void	setValue (const XVImageSize &pos, DATATYPE data)
	Write a voxel into the virtual volume.

template<typename DATATYPE >
SO_VIRTUALVOLUME_EXPORT void	setCursorValue (DATATYPE val)
	Set value under cursor and lock page.

template<typename DATATYPE >
SO_VIRTUALVOLUME_EXPORT void	getCursorValue (DATATYPE &retVal)

template<typename DATATYPE >
SO_VIRTUALVOLUME_EXPORT void	fill (const XVImageSize &boxV1, const XVImageSize &boxV2, DATATYPE value)
	Fill the area box in the virtual image with voxel value `value`.

template<typename DATATYPE >
SO_VIRTUALVOLUME_EXPORT void	getWrittenPageData (MLuint32 wp, DATATYPE *&dataPtr) const
	Returns typed pointer to voxel data of written page number `wp`.

Protected Member Functions
SO_VIRTUALVOLUME_EXPORT	SoVirtualVolume (const SoVirtualVolume &virtVol)
	Copy constructor.

SO_VIRTUALVOLUME_EXPORT SoVirtualVolume &	operator= (const SoVirtualVolume &virtVol)
	Assignment operator.

SO_VIRTUALVOLUME_EXPORT void	_updateVirtualVolumes (const XVImageSize &ext=XVImageSize(0), double fillVal=0, MLDataType dType=MLuint8Type, long maxNumKB=-1, bool useExceptions=false)
	If there is a non NULL `SoSFMLImage` pointer in `_image` which contains a valid connection to a valid ML image then this method recreates the virtual volume with the extents of _image.

SO_VIRTUALVOLUME_EXPORT void	_createTypedVirtualVolume ()
	Create the typed version of the virtual volume and set up all function pointers from function wrapper.

SO_VIRTUALVOLUME_EXPORT void	_removeVirtualVolumes (bool removeOnlyTyped=false)
	Removes all current virtual volumes.

void	_enforceInstPub ()
	Template instantiation helper function. This function must not be called.

void	_enforceInstPub2 ()
	Template instantiation helper function. This function must not be called.

Static Protected Member Functions
static SO_VIRTUALVOLUME_EXPORT void	_imageChangedCB (void clientData, SoSensor sensor)
	Static function called if `_fieldSensor` detects a change of `_image`; it updates the internal virtual volumes to image changes.

Protected Attributes
SoSFMLImage *	_image
	Reference to the `SoSFMLImage` passed in the constructor.

MLDataType	_constructorDataType
	Extents passed to constructor.

long	_constructorMaxNumKB
	maxNumKB passed to constructor.

bool	_constructorAreExceptionsOn
	useExceptions passed to constructor.

SoFieldSensor	_fieldSensor
	Field sensor attached to the `SoSFMLImage` passed in the constructor.

ml::VirtualVolume *	_virtualVolume
	Pointer to the current untyped virtual volume or NULL if there is none.

void *	_tVirtualVolume
	Pointer to the current typed virtual volume or NULL if there is none.

Detailed Description

The SoVirtualVolume class for fast voxel based access to paged ML images; see also mlVirtualVolume and mlTVirtualVolume in project MLTools for examples etc.

Definition at line 38 of file SoVirtualVolume.h.

Constructor & Destructor Documentation

◆ SoVirtualVolume() [1/3]

SO_VIRTUALVOLUME_EXPORT SoVirtualVolume::SoVirtualVolume	(	SoSFMLImage &	image,
		MLDataType	dType = ML_INVALID_DATA_TYPE,
		long	maxNumKB = -1,
		bool	useExceptions = false )

Constructor which creates a SoVirtualVolume interface to an ML paged image hidden behind image.

If possible a SoVirtualVolume should be created as soon as possible after the SoSFMLImage initialization to be sure that it's notified first before other sensors on changes of image. So accesses to the SoVirtualVolume take place before other notifications.

Parameters

image	is the SoSFMLImage which shall be interfaced by the SoSVirtualVolume.
dType	is the ML data type the SoVirtualVolume shall use internally. If passed as -1 the data type of `image` is used.
maxNumKB
useExceptions	controls whether the virtual volume runs save accesses to the image or unsafe ones. If disabled invalid accesses will lead to undefined program state; if enabled the controlled exceptions will be thrown which can be handled safely. See mlVirtualVolume.h in project MLTools for more infos.

◆ SoVirtualVolume() [2/3]

SO_VIRTUALVOLUME_EXPORT SoVirtualVolume::SoVirtualVolume	(	const XVImageSize &	ext = XVImageSize(0),
		double	fillVal = 0,
		MLDataType	dType = MLuint8Type,
		long	maxNumKB = -1,
		bool	useExceptions = false )

Constructor to map an image of extents ext filled with fillVal.

Parameters

ext	specifies the extents of the virtual volume to be created. Default is 0.
fillVal	is the default value for all unwritten (i.e. background) virtual volume areas. Default is 0.
dType	defines the data type of the virtual volume. Default is `MLuint8Type`.
maxNumKB	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. Default is -1.
useExceptions	If true then testing of all calls for validity is enabled and exception are thrown on errors. Otherwise errors only partially throw exceptions or could lead to undefined program behaviour. See mlVirtualVolume.h in project MLTools for more infos.

◆ ~SoVirtualVolume()

virtual SO_VIRTUALVOLUME_EXPORT SoVirtualVolume::~SoVirtualVolume ( )

virtual

Destructor.

It destroys the voxel based access to the SoSFMLImage (if such a constructor was used). Anyway, you can keep on using that SoSFMLImage image after destruction of this.

◆ SoVirtualVolume() [3/3]

SO_VIRTUALVOLUME_EXPORT SoVirtualVolume::SoVirtualVolume ( const SoVirtualVolume & virtVol )

protected

Copy constructor.

Protected since copying of mapped virtual volumes is not well defined, especially if they're associated to SoSFMLImages.

Member Function Documentation

◆ _createTypedVirtualVolume()

SO_VIRTUALVOLUME_EXPORT void SoVirtualVolume::_createTypedVirtualVolume ( )

protected

Create the typed version of the virtual volume and set up all function pointers from function wrapper.

All former pointers are overwritten, even allocated pointers.

◆ _enforceInstPub()

void SoVirtualVolume::_enforceInstPub ( )

inlineprotected

Template instantiation helper function. This function must not be called.

Definition at line 429 of file SoVirtualVolume.h.

◆ _enforceInstPub2()

void SoVirtualVolume::_enforceInstPub2 ( )

inlineprotected

Template instantiation helper function. This function must not be called.

Definition at line 432 of file SoVirtualVolume.h.

◆ _imageChangedCB()

static SO_VIRTUALVOLUME_EXPORT void SoVirtualVolume::_imageChangedCB	(	void *	clientData,
		SoSensor *	sensor )

staticprotected

Static function called if _fieldSensor detects a change of _image; it updates the internal virtual volumes to image changes.

Parameters

clientData	Data passed to the sensor while it is attached to the image. In this case it will point to the instance, i.e. it is this.
sensor	The which has detected the field change and which is calling this function. In this case it's `&_fieldSensor`.

◆ _removeVirtualVolumes()

SO_VIRTUALVOLUME_EXPORT void SoVirtualVolume::_removeVirtualVolumes ( bool removeOnlyTyped = false )

protected

Removes all current virtual volumes.

If removeOnlyTyped is true then only the typed virtual volume is removed and the untyped one remains.

◆ _updateVirtualVolumes()

SO_VIRTUALVOLUME_EXPORT void SoVirtualVolume::_updateVirtualVolumes	(	const XVImageSize &	ext = XVImageSize(0),
		double	fillVal = 0,
		MLDataType	dType = MLuint8Type,
		long	maxNumKB = -1,
		bool	useExceptions = false )

protected

If there is a non NULL SoSFMLImage pointer in _image which contains a valid connection to a valid ML image then this method recreates the virtual volume with the extents of _image.

The data type of the virtual volume is set to dType if that's valid, otherwise the data type of the SoSFMLImage is used. The size of the page buffer is automatically determined if maxNumKB is < 0; otherwise a buffer size given by maxNumKB is assumed. Exception handling is enabled if areExceptionOn() is true; otherwise it's disabled. If no valid _image is set then a virtual volume of extents given by ext with data type dType is created. maxNumKB and useExceptions are handled as above. Passing an invalid dType there will lead to an error and the invalidation of the virtual volume.

Parameters

ext	Determines the extents of the virtual volume if `_image` is not valid. Default is (0,0,0,0,0,0).
fillVal	Determines the background/fill value of the virtual volume if `_image` is not valid. Default is 0.
dType	Determines the data type how data is stored in the virtual volume. If -1 then the type of `_image` is used. If that's not valid then an error is created and the virtual volume will be invalidated. Default is MLuint8Type.
maxNumKB	If -1 it 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. Default is -1.
useExceptions	Exception handling is enabled if `areExceptionOn()` is true; otherwise it's disabled. Default is false.

◆ areExceptionsOn()

bool SoVirtualVolume::areExceptionsOn ( ) const

inline

Returns the useExceptions value passed to the constructor.

Definition at line 103 of file SoVirtualVolume.h.

References _constructorAreExceptionsOn.

◆ fill()

template<typename DATATYPE >

SO_VIRTUALVOLUME_EXPORT void SoVirtualVolume::fill	(	const XVImageSize &	boxV1,
		const XVImageSize &	boxV2,
		DATATYPE	value )

Fill the area box in the virtual image with voxel value value.

If area reaches outside the valid virtual volume area it is automatically clamped to valid voxels.

Note: DATATYPE must fit the internal SoVirtualVolume type or crashes will occur.

◆ fillDouble()

void SoVirtualVolume::fillDouble	(	const XVImageSize &	boxV1,
		const XVImageSize &	boxV2,
		MLdouble	v )

inline

Definition at line 188 of file SoVirtualVolume.h.

References _tVirtualVolume, and mlrange_cast().

◆ fillInt()

void SoVirtualVolume::fillInt	(	const XVImageSize &	boxV1,
		const XVImageSize &	boxV2,
		MLint	v )

inline

Definition at line 186 of file SoVirtualVolume.h.

References _tVirtualVolume, and mlrange_cast().

◆ fillInt64()

void SoVirtualVolume::fillInt64	(	const XVImageSize &	boxV1,
		const XVImageSize &	boxV2,
		MLint64	v )

inline

Definition at line 187 of file SoVirtualVolume.h.

References _tVirtualVolume, and mlrange_cast().

◆ fillLDouble()

void SoVirtualVolume::fillLDouble	(	const XVImageSize &	boxV1,
		const XVImageSize &	boxV2,
		MLldouble	v )

inline

Definition at line 189 of file SoVirtualVolume.h.

References _tVirtualVolume, and mlrange_cast().

◆ getCursorPosition()

const XVImageSize & SoVirtualVolume::getCursorPosition ( )

inline

Definition at line 167 of file SoVirtualVolume.h.

SO_VIRTUALVOLUME_EXPORT void SoVirtualVolume::getValue	(	const XVImageSize &	pos,
		DATATYPE &	retVal )

SO_VIRTUALVOLUME_EXPORT void SoVirtualVolume::getWrittenPageData	(	MLuint32	wp,
		DATATYPE *&	dataPtr ) const

wp	must be within [0, vVol.getNumWrittenPages()-1].
dataPtr	is the reference to a pointer which shall point to the data of page `wp`.

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SoVirtualVolume() [1/3]

◆ SoVirtualVolume() [2/3]

◆ ~SoVirtualVolume()

◆ SoVirtualVolume() [3/3]

Member Function Documentation

◆ _createTypedVirtualVolume()

◆ _enforceInstPub()

◆ _enforceInstPub2()

◆ _imageChangedCB()

◆ _removeVirtualVolumes()

◆ _updateVirtualVolumes()

◆ areExceptionsOn()

◆ fill()

◆ fillDouble()

◆ fillInt()

◆ fillInt64()

◆ fillLDouble()

◆ getCursorPosition()

◆ getCursorValue()

◆ getDataType()

◆ getDoubleCursorValue()

◆ getDoubleValue()

◆ getImage()

◆ getInt64CursorValue()

◆ getInt64Value()

◆ getIntCursorValue()

◆ getIntValue()

◆ getLDoubleCursorValue()

◆ getLDoubleValue()

◆ getMaxNumKB()

◆ getNumBytes()

◆ getNumMappedPages()

◆ getNumPages()

◆ getNumWrittenPages()

◆ getPageArrayExtent()

◆ getPageExtent()

◆ getValue()

◆ getWrittenPageData() [1/2]

◆ getWrittenPageData() [2/2]

◆ isMapped()

◆ isValid()

◆ moveCursorByOffset()

◆ moveCursorC()

◆ moveCursorT()

◆ moveCursorU()

◆ moveCursorX()

◆ moveCursorXWrapAround()

◆ moveCursorY()

◆ moveCursorZ()

◆ operator=()

◆ resetCursor()

◆ resize()

◆ reverseMoveCursorC()

◆ reverseMoveCursorT()

◆ reverseMoveCursorU()

◆ reverseMoveCursorX()

◆ reverseMoveCursorY()

◆ reverseMoveCursorZ()

◆ setCursorPosition()

◆ setCursorValue()

◆ setDoubleCursorValue()

◆ setDoubleValue()

◆ setInt64CursorValue()

◆ setInt64Value()

◆ setIntCursorValue()

◆ setIntValue()

◆ setLDoubleCursorValue()

◆ setLDoubleValue()

◆ setValue()

◆ unMapAndClearWrittenPages()

Member Data Documentation

◆ _constructorAreExceptionsOn

◆ _constructorDataType

◆ _constructorMaxNumKB