ml::Host Class Reference

The Host is the central image processing class in the ML. More...

#include <mlHost.h>

List of all members.

Public Member Functions
void	setProgressCB (void *userData, MLHostProgressCB *callback)
	Sets callback for progress/busy cursor updates.
MLHostProgressCB *	getProgressCB () const
	Returns current callback for progress/busy cursor updates.
void *	getProgressCBUserData () const
	Returns user data of current callback for progress/busy cursor updates.
void	updateProgress (const char *info1, const char *info2)
	Calls the busy cursor/progress callback if it is set.
void	setBreakCheckCB (void *userData, MLHostBreakCheckCB *callback)
	Sets callback for break checking.
MLHostBreakCheckCB *	getBreakCheckCB () const
	Returns current callback for break checking.
void *	getBreakCheckCBUserData () const
	Returns user data of current callback for break checking.
bool	shouldTerminate () const
	Checks if current calculation should be terminated.
Field *	getPressedNotifyField ()
	Checks if a notify button was pressed (outside of normal notification) It returns the notify field or NULL if nothing was pressed.
void	setMaxNumThreads (MLint32 numThreads)
	Sets maximum number of permitted threads to numThreads.
MLint32	getMaxNumThreads () const
	Returns maximum number of permitted threads.
MLuint32	isProcessingActive () const
	Non-zero return values mean that (image) processing is currently active.
Computation of image data in different memory allocation variations
MLErrorCode	getTile (PagedImage &outputImage, SubImageBox location, MLDataType dataType, void **data, const ScaleShiftData &scaleShiftData=ScaleShiftData())
	Requests the image region location from the image outputImage.
MLErrorCode	getTile (PagedImage &outputImage, SubImage &subImage, const ScaleShiftData &scaleShiftData=ScaleShiftData())
	Requests the image region subImage.getBox() from output image outputImage.
void	freeTile (void *data)
	Frees (image) memory which has been allocated with any getTile() function of the Host class.
Sequential image processing.
MLErrorCode	processAllPages (Module &module, MLint outputIndex, SubImageBox region=SubImageBox())
	Processes all pages of a module for easy implementation of page-based image processing of complete images.
MLErrorCode	processAllPages (Module &module, ProcessAllPagesHandler &handler, SubImageBox region=SubImageBox())
	Processes input images with a ProcessAllPagesHandler on a temporary output image (which allocates no data) For details, see processAllPages(-1) above.
Update image properties at module output.
MLErrorCode	updateImageProperties (Module &module, MLint outputIndex)
	/deprecated Updates the module graph under module and including the output image at outputIndex of module.
MLErrorCode	updateImageProperties (PagedImage &outputImage)
	Updates the module graph under outputImage->getModule() and including outputImage.
Static Public Member Functions
static Host &	getDefaultHost ()
	Return a reference to the always existing default Host.
static void	destroyDefaultHost ()
	Destroys and cleans up allocated memory of default Host.
static MLErrorCode	pushDefaultHost ()
	Creates a new Host instance with initialization state, sets it as default host and pushes the previous default Host on a stack.
static MLErrorCode	popDefaultHost ()
	Destroys the current default Host and uses the previous one from stack as default Host.
static unsigned int	getMemoryManagerId ()
	Returns the memory manager id that is used for allocation of memory by the ML.
static SubImageBox	calculateInputSubImageBoxDebug (Module &module, int inIndex, const SubImageBox &outputSubImageBox, int outputIndex)
	This is a method that allows access to the (otherwise protected) calculateInputSubImageBox of a module, which should only be used for diagnosis purposes.
Protected Member Functions
void	_setProcessingActive ()
	Enables the flag that indicates active image processing.
void	_unsetProcessingActive ()
	Disables the flag that indicates active image processing.
Friends
class	PageRequestProcessor
struct	CalcPagesWorkerThreadFunction
	make the worker thread function a friend
Initialization
static void	registerWithMemoryManager ()
	Registers the Host as library using the memory manager and initializes the memory manager id.
	Host ()
	Constructor.
virtual	~Host ()
	Destructor. Frees also the Cache managed by the Host.
Deprecated methods.
static SubImageBox	calcInSubImageBoxDebug (Module &module, int inIndex, const SubImageBox &outSubImgBox, int outIndex)
MLErrorCode	getTile (Module &op, MLint outIndex, SubImageBox loc, MLDataType dataType, void **data, const ScaleShiftData &scaleShiftData=ScaleShiftData())
MLErrorCode	getTile (Module &op, MLint outIndex, SubImage &subImg, const ScaleShiftData &scaleShiftData=ScaleShiftData())
MLErrorCode	updateImageProps (Module &op, MLint outIndex)

---

Detailed Description

The Host is the central image processing class in the ML.

It contains the entire management of pages, their transport between modules, their (temporary) storage in the Cache, the parallel processing of pages (multithreading) and the (de)composition of images and image fragments from/to pages or subimages.

The host operates on a network of modules derived from the class Module which must be a organized in a directed and non cyclic graph.

Typically modules are only working on demand - all of their image processing behavior is completely controlled by the Host - it is responsible to solve an image processing request by making use of the module interface available by the Module class interface. The image processing interface of a module it basically defined by the virtual calculate* method defined in the Module class interface.

Note: The Host typically works in the "background": Direct calls to Host functionality are usually forbidden. All important stuff is wrapped as static functions in the Module interface. Including the mlHost.h or using its functions is typically an error and should be avoided since it limits the possibility of Host revisions without changing the module database.

Properties of image processing:

• For the memory optimized image processing of images or image fragments each module supports the so called page-based image processing, i.e., each image is decomposed into pages (up to 6d-retangular, non overlapping subimages). These pages are processed and propagated subsequently through the modules and at the end they are composed to the result (sub)image. The extents of those pages is an image property which can be controlled by any module and which is also supported by many (unfortunately not all) file formats (e.g., Tiff). So also page based loading and saving of images is available by certain modules. Using pages with extents of the entire image should be avoided because it degrades page based image processing to standard image processing. This however sometimes can be difficult; please read ML literature for specialized base classes which support global image processing without leaving the page based approach. (E.g., see VirtualVolume, Module::processAllPages, slice based image processing, mlKernel(Base)Module, etc.)

• For the time optimized image processing all calculated result pages of each module are stored within the Cache (a Host instance always has a Cache member) as long as they do not need more than Cache::setMaxCacheSizeKB() which is set by default or by the environment variable ML_CACHE_SIZE_IN_KB. So already calculated pages can be recycled without recalculation. This can drastically speed up applications using the ML. If the cache reaches its limit then pages are cleaned up dependent on their priority which is assigned to them when they are calculated. So expensive pages (in the context of calculation time) are maintained longer than pages which can be recalculated fast.

Exception handling is controlled by mlUtils. If MLIsExceptionHandlingEnabled==0 (False), exceptions typically cause program termination. This is especially useful for debugging purposes. So Module::Module (mlAPI) Module::~Module (mlAPI) Module::calculateOutputSubImage (mlHost) Module::calculateInputSubImageBox (mlHost) Module::calculateOutputImageProperties (mlHost) Module::handleNotification (mlHost) are not checked with exception catching, i.e., the ML crashes on errors. Otherwise exceptions are caught and redirected to the ErrorOutput class.

The default is off in debug mode so that all bugs lead to a crash which needs to be debugged. In release mode, this flag will always be set to true so that all exceptions are passed to the ML error output class to handled the errors.

Definition at line 127 of file mlHost.h.

---

Constructor & Destructor Documentation

ml::Host::Host

(

)

Constructor.

In the current ML version there should be only one Host instance which is automatically created as a singleton accessible by Host::getDefaultHost().

virtual ml::Host::~Host

(

)

[virtual]

Destructor. Frees also the Cache managed by the Host.

---

Member Function Documentation

void ml::Host::_setProcessingActive

(

)

[protected]

Enables the flag that indicates active image processing.

Note that this flag is counted; i.e., many calls require as many _unsetProcessActive() calls.

void ml::Host::_unsetProcessingActive

(

)

[protected]

Disables the flag that indicates active image processing.

Note that this flag is counted; i.e., each set call requires an unset call. A really disabled flag, however, remains disabled.

static SubImageBox ml::Host::calcInSubImageBoxDebug	(	Module &	module,
		int	inIndex,
		const SubImageBox &	outSubImgBox,
		int	outIndex
	)			[inline, static]

Deprecated:

Use calculateInputSubImageBoxDebug() instead.

Definition at line 387 of file mlHost.h.

static SubImageBox ml::Host::calculateInputSubImageBoxDebug	(	Module &	module,
		int	inIndex,
		const SubImageBox &	outputSubImageBox,
		int	outputIndex
	)			[static]

This is a method that allows access to the (otherwise protected) calculateInputSubImageBox of a module, which should only be used for diagnosis purposes.

static void ml::Host::destroyDefaultHost

(

)

[static]

Destroys and cleans up allocated memory of default Host.

void ml::Host::freeTile

(

void *

data

)

Frees (image) memory which has been allocated with any getTile() function of the Host class.

It is explicitly permitted to pass NULL pointer which then will be ignored.

MLHostBreakCheckCB* ml::Host::getBreakCheckCB

(

)

const

Returns current callback for break checking.

void* ml::Host::getBreakCheckCBUserData

(

)

const

Returns user data of current callback for break checking.

static Host& ml::Host::getDefaultHost

(

)

[static]

Return a reference to the always existing default Host.

MLint32 ml::Host::getMaxNumThreads

(

)

const

Returns maximum number of permitted threads.

<=0:multithreading off, 2:Default.

static unsigned int ml::Host::getMemoryManagerId

(

)

[inline, static]

Returns the memory manager id that is used for allocation of memory by the ML.

Definition at line 354 of file mlHost.h.

Field* ml::Host::getPressedNotifyField

(

)

Checks if a notify button was pressed (outside of normal notification) It returns the notify field or NULL if nothing was pressed.

Note that more than one field may have been notified; so use a loop until NULL is returned to be sure that all NotifyFields have been checked.

MLHostProgressCB* ml::Host::getProgressCB

(

)

const

Returns current callback for progress/busy cursor updates.

void* ml::Host::getProgressCBUserData

(

)

const

Returns user data of current callback for progress/busy cursor updates.

MLErrorCode ml::Host::getTile	(	Module &	op,
		MLint	outIndex,
		SubImage &	subImg,
		const ScaleShiftData &	scaleShiftData = ScaleShiftData()
	)

Deprecated:

Use getTile() with PagedImage instead.

MLErrorCode ml::Host::getTile	(	Module &	op,
		MLint	outIndex,
		SubImageBox	loc,
		MLDataType	dataType,
		void **	data,
		const ScaleShiftData &	scaleShiftData = ScaleShiftData()
	)

Deprecated:

Use getTile() with PagedImage instead.

MLErrorCode ml::Host::getTile	(	PagedImage &	outputImage,
		SubImage &	subImage,
		const ScaleShiftData &	scaleShiftData = ScaleShiftData()
	)

Requests the image region subImage.getBox() from output image outputImage.

If subImage.getData() is a non NULL pointer, it must be large enough to hold the entire requested image data. If subImage.getData() is NULL, the getTile function will allocate enough memory for the image data and update the pointer in subImage. The image data will be stored in that memory as data type subImage.getDataType. The data will be scaled linearly dependent on the settings of the scaleShiftData (see ScaleShiftData). The value subImage.getData() then will point to the (allocated) image data. IMPORTANT: Memory allocated with any Host::getTile function must be freed with the Host::freeTile function or with the corresponding mapped freeTile function of the class Module. This subImg will only be a wrapper for that memory chunk but it will not deallocate it if subImg is deleted or changed.

MLErrorCode ml::Host::getTile	(	PagedImage &	outputImage,
		SubImageBox	location,
		MLDataType	dataType,
		void **	data,
		const ScaleShiftData &	scaleShiftData = ScaleShiftData()
	)

Requests the image region location from the image outputImage.

If *data is a non NULL pointer, it must be large enough to hold the entire requested image data. If *data is NULL, the getTile function will allocate enough memory for the image data. The image data will be stored in that memory as data type dataType. The data will be scaled linearly dependent on the settings of the scaleShiftData (see ScaleShiftData). The return value data then pointer to the allocated memory. IMPORTANT: Memory allocated with any Host::getTile function must be freed with the Host::freeTile function or with the corresponding mapped freeTile function of the class Module.

MLuint32 ml::Host::isProcessingActive

(

)

const

Non-zero return values mean that (image) processing is currently active.

static MLErrorCode ml::Host::popDefaultHost

(

)

[static]

Destroys the current default Host and uses the previous one from stack as default Host.

On success, ML_RESULT_OK is returned, otherwise a code describing the problem. Trying to pop from an empty stack will leave the current default Host unchanged and returns the ML_TOO_MANY_POPS_OR_REMOVES code.

MLErrorCode ml::Host::processAllPages	(	Module &	module,
		ProcessAllPagesHandler &	handler,
		SubImageBox	region = SubImageBox()
	)

Processes input images with a ProcessAllPagesHandler on a temporary output image (which allocates no data) For details, see processAllPages(-1) above.

MLErrorCode ml::Host::processAllPages	(	Module &	module,
		MLint	outputIndex,
		SubImageBox	region = SubImageBox()
	)

Processes all pages of a module for easy implementation of page-based image processing of complete images.

Internally all pages of the output image with outputIndex are requested like from a connected module. So a normal image processing takes place with the following changes:

• Before any calculation of pages eventually existing pages or memory image are cleared so that really all pages are processed.
• If outputIndex is -1, a temporary output image with index -1 is created. The properties for the temporary output image are copied from the input image 0. If outputIndex is positive, it must specify a legal module output index.
• If outputIndex is -1, in calculateOutputSubImage the output subimages must NOT be written since not data is collected for them to improve performance for pure input scan algorithms.
• If outputIndex is -1, in calculateOutputImageProperties method is called with outputIndex set to -1 and outputImage set to the temporary image. This allows to specify different properties for the temporary output image than the properties of image 0. Note: Module::getOutputImage(-1) will not work, but you can use calculateOutputImageProperties(MLInt outputIndex, PagedImage* outputImage) to access the outputImage.
• The outputIndex is passed to calculateOutputSubImage (even if it is negative). By a negative value you can see that the output must not be written.
• region can be passed by the caller to specify a region which covers all pages to be processed instead of all pages of the image. By default it is empty which means that all pages of the images are to be processed. The return value will ML_RESULT_OK on successful operation, otherwise a code describing the error.

static MLErrorCode ml::Host::pushDefaultHost

(

)

[static]

Creates a new Host instance with initialization state, sets it as default host and pushes the previous default Host on a stack.

static void ml::Host::registerWithMemoryManager

(

)

[static]

Registers the Host as library using the memory manager and initializes the memory manager id.

void ml::Host::setBreakCheckCB	(	void *	userData,
		MLHostBreakCheckCB *	callback
	)

Sets callback for break checking.

void ml::Host::setMaxNumThreads

(

MLint32

numThreads

)

Sets maximum number of permitted threads to numThreads.

0,1:multithreading off, 2=Default.

void ml::Host::setProgressCB	(	void *	userData,
		MLHostProgressCB *	callback
	)

Sets callback for progress/busy cursor updates.

bool ml::Host::shouldTerminate

(

)

const

Checks if current calculation should be terminated.

Calls the callback set by setBreakCheckCB if there is one.

MLErrorCode ml::Host::updateImageProperties

(

PagedImage &

outputImage

)

Updates the module graph under outputImage->getModule() and including outputImage.

If updating failed, ML_NO_IMAGE_PROPS is returned, on success ML_RESULT_OK is returned. On other failures the corresponding error messages are returned.

MLErrorCode ml::Host::updateImageProperties	(	Module &	module,
		MLint	outputIndex
	)

/deprecated Updates the module graph under module and including the output image at outputIndex of module.

If updating failed, ML_NO_IMAGE_PROPS is returned, on success ML_RESULT_OK is returned. On other failures the corresponding error messages are returned. Better use updateImageProperties with PagedImage.

MLErrorCode ml::Host::updateImageProps	(	Module &	op,
		MLint	outIndex
	)			[inline]

Deprecated:

Use updateImageProperties() instead.

Definition at line 383 of file mlHost.h.

void ml::Host::updateProgress	(	const char *	info1,
		const char *	info2
	)

Calls the busy cursor/progress callback if it is set.

Applications which have registered can update their status busy cursor or progress indicators in the callback. This method can especially be used by ML modules in regular intervals to give response during complex computations within notification handling.

---

Friends And Related Function Documentation

friend struct CalcPagesWorkerThreadFunction [friend]

make the worker thread function a friend

Definition at line 507 of file mlHost.h.

friend class PageRequestProcessor [friend]

Definition at line 132 of file mlHost.h.

---

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

• MeVis/Foundation/Sources/ML/include/mlHost.h