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

#include <mlHost.h>

Public Member Functions
void	setProgressCB (void userData, MLHostProgressCB callback)
	Sets callback for progress/busy cursor updates. More...

MLHostProgressCB *	getProgressCB () const
	Returns current callback for progress/busy cursor updates. More...

void *	getProgressCBUserData () const
	Returns user data of current callback for progress/busy cursor updates. More...

void	updateProgress (const char info1, const char info2)
	Calls the busy cursor/progress callback if it is set. More...

void	setBreakCheckCB (void userData, MLHostBreakCheckCB callback)
	Sets callback for break checking. More...

MLHostBreakCheckCB *	getBreakCheckCB () const
	Returns the current callback for break checking. More...

void *	getBreakCheckCBUserData () const
	Returns user data of the current callback for break checking. More...

bool	shouldTerminate () const
	Checks whether the current calculation should be terminated. More...

Field *	getPressedNotifyField ()
	Checks whether a notify button was pressed (outside of normal notification). More...

void	setMaxNumThreads (MLint32 numThreads)
	Sets maximum number of permitted worker threads to `numThreads`. More...

MLint32	getMaxNumThreads () const
	Returns the maximum number of permitted worker threads. More...

void	setRestrictMaxNumThreads (MLint32 numThreads)
	Restricts the maximum number of permitted worker threads to be less or equal to `numThreads`. More...

MLint32	getRestrictMaxNumThreads () const
	Returns the restriction for setMaxNumThreads(). More...

MLuint32	isProcessingActive () const
	Non-zero return values mean that (image) processing is currently active. More...

ClassicHost *	getClassicHostDebug ()
	Returns access to the classic ML host (for debugging purposes only!). More...

void	setUseClassicHost (bool flag)
	Enables/disables usage of the classic ML host. More...

bool	getUseClassicHost () const
	Returns whether the classic ML host is used. More...

PageRequestProcessor *	getPageRequestProcessor ()
	Returns the currently responsible page request processor. More...

ProcessingTimeLine &	getProcessingTimeLine ()
	Returns access to the processing timeline. More...

void	enableTimeLineProfiling (bool flag)
	Enables/disables timeline profiling. More...

Computation of image data in different memory allocation variations
MLErrorCode	getTile (PagedImage &outputImage, SubImageBox location, MLDataType dataType, void *data, const ScaleShiftData &scaleShiftData=ScaleShiftData(), MLRequestProgressCB progressCallback=nullptr, void *progressCallbackUserData=nullptr)
	Requests the image region `location` from the image `outputImage`. More...

MLErrorCode	getTile (PagedImage &outputImage, SubImage &subImage, const ScaleShiftData &scaleShiftData=ScaleShiftData(), MLRequestProgressCB progressCallback=nullptr, void progressCallbackUserData=nullptr)
	Requests the image region subImage.getBox() from output image `outputImage`. More...

void	freeTile (void *data)
	Frees (image) memory that has been allocated with any getTile() function of the Host class. More...

Sequential image processing.
MLErrorCode	processAllPages (Module &module, MLint outputIndex, SubImageBox region=SubImageBox(), MLRequestProgressCB progressCallback=nullptr, void progressCallbackUserData=nullptr)
	See Module::processAllPages() for details on this method. More...

MLErrorCode	processAllPages (Module &module, ProcessAllPagesHandler &handler, SubImageBox region=SubImageBox(), MLRequestProgressCB progressCallback=nullptr, void progressCallbackUserData=nullptr)
	Processes input images with a ProcessAllPagesHandler on a temporary output image (which allocates no data). More...

MLErrorCode	processMissingPages (Module &module, MLint outputIndex, SubImageBox region=SubImageBox(), MLRequestProgressCB progressCallback=nullptr, void progressCallbackUserData=nullptr)
	See Module::processMissingPages() for details on this method. More...

MLErrorCode	processAllPagesWithInputImage (PagedImage &inputImage, ProcessAllPagesHandler &handler, const SubImageBox &region=SubImageBox(), MLRequestProgressCB progressCallback=nullptr, void progressCallbackUserData=nullptr)
	Processes all pages as specified by the `handler` using `inputImage` as single input. More...

MLErrorCode	processAllPagesWithInputImages (const std::vector< PagedImage * > &inputImages, ProcessAllPagesHandler &handler, const SubImageBox &region=SubImageBox(), MLRequestProgressCB progressCallback=nullptr, void progressCallbackUserData=nullptr)
	Processes all pages as specified by the `handler` using `inputImages` as inputs. More...

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

MLErrorCode	updateImageProperties (PagedImage &outputImage)
	Updates the module graph under outputImage->getModule() and including `outputImage`. More...

Static Public Member Functions
static Host &	getDefaultHost ()
	Returns a reference to the Host singleton. More...

static void	destroyDefaultHost ()
	Destroys and cleans up allocated memory of default Host. More...

static unsigned int	getMemoryManagerId ()
	Returns the memory manager ID that is used for allocation of memory by the ML. More...

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

Protected Member Functions
void	_setProcessingActive ()
	Enables the flag that indicates active image processing. More...

void	_unsetProcessingActive ()
	Disables the flag that indicates active image processing. More...

Friends
class	PageRequestProcessor

class	SingleThreadedPageRequestProcessor

class	MultiThreadedPageRequestProcessor

class	ClassicHost

Initialization
static void	registerWithMemoryManager ()
	Registers the Host as library using the memory manager and initializes the memory manager ID. More...

	Host ()
	Constructor. More...

virtual	~Host ()
	Destructor. More...

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 is basically defined by the virtual calculate* method defined in the Module class interface.

Properties of image processing:

For the memory optimized image processing of images or image fragments, each module support the so-called page-based image processing, i.e., each image is decomposed into pages (up to 6D-rectangular, non overlapping subimages). These pages are processed and propagated subsequently through the modules and in the end, they are composed to the result (sub)image. The extents of these pages is an image property, which can be controlled by any module and which is also supported by many file formats. Using pages with extents of the entire image should be avoided, as it degrades page based image processing to standard image processing. However, this sometimes can be difficult; please read ML literature for specialized base classes that support global image processing without leaving the page based approach. For example, see VirtualVolume, Module::processAllPages, slice based image processing, mlKernel(Base)Module.
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. This way, 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. This way, expensive pages (in the context of calculation time) are maintained longer than pages that 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 that 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 114 of file mlHost.h.

Constructor & Destructor Documentation

◆ Host()

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

◆ ~Host()

virtual ml::Host::~Host ( )

virtual

Destructor.

Member Function Documentation

◆ _setProcessingActive()

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.

◆ _unsetProcessingActive()

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.

◆ calculateInputSubImageBoxDebug()

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.

◆ destroyDefaultHost()

static void ml::Host::destroyDefaultHost ( )

static

Destroys and cleans up allocated memory of default Host.

◆ enableTimeLineProfiling()

void ml::Host::enableTimeLineProfiling ( bool flag )

Enables/disables timeline profiling.

◆ freeTile()

void ml::Host::freeTile ( void * data )

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

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

◆ getBreakCheckCB()

MLHostBreakCheckCB* ml::Host::getBreakCheckCB ( ) const

Returns the current callback for break checking.

◆ getBreakCheckCBUserData()

void* ml::Host::getBreakCheckCBUserData ( ) const

Returns user data of the current callback for break checking.

◆ getClassicHostDebug()

ClassicHost* ml::Host::getClassicHostDebug ( )

inline

Returns access to the classic ML host (for debugging purposes only!).

Definition at line 391 of file mlHost.h.

◆ getDefaultHost()

static Host& ml::Host::getDefaultHost ( )

static

Returns a reference to the Host singleton.

◆ getMaxNumThreads()

MLint32 ml::Host::getMaxNumThreads ( ) const

Returns the maximum number of permitted worker threads.

◆ getMemoryManagerId()

static unsigned int ml::Host::getMemoryManagerId ( )

inlinestatic

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

Definition at line 384 of file mlHost.h.

◆ getPageRequestProcessor()

PageRequestProcessor* ml::Host::getPageRequestProcessor ( )

Returns the currently responsible page request processor.

◆ getPressedNotifyField()

Field* ml::Host::getPressedNotifyField ( )

Checks whether 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.

◆ getProcessingTimeLine()

ProcessingTimeLine& ml::Host::getProcessingTimeLine ( )

Returns access to the processing timeline.

◆ getProgressCB()

MLHostProgressCB* ml::Host::getProgressCB ( ) const

Returns current callback for progress/busy cursor updates.

◆ getProgressCBUserData()

void* ml::Host::getProgressCBUserData ( ) const

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

◆ getRestrictMaxNumThreads()

MLint32 ml::Host::getRestrictMaxNumThreads ( ) const

inline

Returns the restriction for setMaxNumThreads().

Definition at line 202 of file mlHost.h.

◆ getTile() [1/2]

MLErrorCode ml::Host::getTile	(	PagedImage &	outputImage,
		SubImage &	subImage,
		const ScaleShiftData &	scaleShiftData = `ScaleShiftData()`,
		MLRequestProgressCB *	progressCallback = `nullptr`,
		void *	progressCallbackUserData = `nullptr`
	)

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 depending on the settings of the scaleShiftData (see ScaleShiftData). The value subImage.getData() then will point to the (allocated) image data.

A progressCallback and its user data can be passed to the method and will be called with a value from 0 to 1 indicating the progress of the request. Note that this callback will only be called when the request takes longer than the internal update interval and that the Host will take care of updating the GUI afterwards. This way, you can simply forward the progress value to, e.g., a DoubleField::setValueCallback and show the value with a ProgressBar on the GUI. There is no guarantee that the progress starts at 0 and reaches 1, you should set the progress to 1 on success in your module instead.

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.

◆ getTile() [2/2]

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

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 depending on the settings of the scaleShiftData (see ScaleShiftData). The returned value data then points to the allocated memory.

A progressCallback and its user data can be passed to the method and will be called with a value from 0 to 1 indicating the progress of the request. Note that this callback will only be called when the request takes longer than the internal update interval, and that the Host will take care of updating the GUI afterwards. This way, you can simply forward the progress value to, e.g., a DoubleField::setValueCallback and show the value with a ProgressBar on the GUI. There is no guarantee that the progress starts at 0 and reaches 1, you should set the progress to 1 on success in your module instead.

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.

◆ getUseClassicHost()

bool ml::Host::getUseClassicHost ( ) const

inline

Returns whether the classic ML host is used.

Definition at line 397 of file mlHost.h.

◆ isProcessingActive()

MLuint32 ml::Host::isProcessingActive ( ) const

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

◆ processAllPages() [1/2]

MLErrorCode ml::Host::processAllPages	(	Module &	module,
		MLint	outputIndex,
		SubImageBox	region = `SubImageBox()`,
		MLRequestProgressCB *	progressCallback = `nullptr`,
		void *	progressCallbackUserData = `nullptr`
	)

See Module::processAllPages() for details on this method.

For details on progressCallback, see Host::getTile().

◆ processAllPages() [2/2]

MLErrorCode ml::Host::processAllPages	(	Module &	module,
		ProcessAllPagesHandler &	handler,
		SubImageBox	region = `SubImageBox()`,
		MLRequestProgressCB *	progressCallback = `nullptr`,
		void *	progressCallbackUserData = `nullptr`
	)

Processes input images with a ProcessAllPagesHandler on a temporary output image (which allocates no data).

For details, see Module::processAllPages() For details on progressCallback, see Host::getTile().

◆ processAllPagesWithInputImage()

MLErrorCode ml::Host::processAllPagesWithInputImage	(	PagedImage &	inputImage,
		ProcessAllPagesHandler &	handler,
		const SubImageBox &	region = `SubImageBox()`,
		MLRequestProgressCB *	progressCallback = `nullptr`,
		void *	progressCallbackUserData = `nullptr`
	)

Processes all pages as specified by the handler using inputImage as single input.

Internally, a (dummy) module is created that is connected to inputImage. Afterwards, the handler is applied. The advantage of this method over the other processAllPages() methods is that you do not need your own module to apply a handler. For details on progressCallback, see Host::getTile().

◆ processAllPagesWithInputImages()

MLErrorCode ml::Host::processAllPagesWithInputImages	(	const std::vector< PagedImage * > &	inputImages,
		ProcessAllPagesHandler &	handler,
		const SubImageBox &	region = `SubImageBox()`,
		MLRequestProgressCB *	progressCallback = `nullptr`,
		void *	progressCallbackUserData = `nullptr`
	)

Processes all pages as specified by the handler using inputImages as inputs.

Internally, a (dummy) module is created that is connected to the inputImages. Afterwards, the handler is applied. The advantage of this method over the other processAllPages() methods is that you do not need your own module to apply a handler. For details on progressCallback, see Host::getTile().

◆ processMissingPages()

MLErrorCode ml::Host::processMissingPages	(	Module &	module,
		MLint	outputIndex,
		SubImageBox	region = `SubImageBox()`,
		MLRequestProgressCB *	progressCallback = `nullptr`,
		void *	progressCallbackUserData = `nullptr`
	)

See Module::processMissingPages() for details on this method.

For details on progressCallback, see Host::getTile().

◆ registerWithMemoryManager()

static void ml::Host::registerWithMemoryManager ( )

static

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

◆ setBreakCheckCB()

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

Sets callback for break checking.

◆ setMaxNumThreads()

void ml::Host::setMaxNumThreads ( MLint32 numThreads )

Sets maximum number of permitted worker threads to numThreads.

A value of 0 or 1 turns multithreading off. If setMaxNumThreads() is restricted via setRestrictMaxNumThreads(), the given value is silently clamped to getRestrictMaxNumThreads().

◆ setProgressCB()

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

Sets callback for progress/busy cursor updates.

◆ setRestrictMaxNumThreads()

void ml::Host::setRestrictMaxNumThreads ( MLint32 numThreads )

Restricts the maximum number of permitted worker threads to be less or equal to numThreads.

Once this has been set, the number of threads cannot be set to a higher value than numThreads via the setMaxNumThreads() API. This can be used by an application to enforce that, e.g., only one thread is used. Default is -1, which means that setMaxNumThreads() has no restriction.

◆ setUseClassicHost()

void ml::Host::setUseClassicHost ( bool flag )

Enables/disables usage of the classic ML host.

◆ shouldTerminate()

bool ml::Host::shouldTerminate ( ) const

Checks whether the current calculation should be terminated.

Calls the callback set by setBreakCheckCB if there is one.

◆ updateImageProperties() [1/2]

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.

◆ updateImageProperties() [2/2]

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.

◆ updateProgress()

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

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

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

Friends And Related Function Documentation

◆ ClassicHost

friend class ClassicHost

friend

Definition at line 122 of file mlHost.h.

◆ MultiThreadedPageRequestProcessor

friend class MultiThreadedPageRequestProcessor

friend

Definition at line 121 of file mlHost.h.

◆ PageRequestProcessor

friend class PageRequestProcessor

friend

Definition at line 119 of file mlHost.h.

◆ SingleThreadedPageRequestProcessor

friend class SingleThreadedPageRequestProcessor

friend

Definition at line 120 of file mlHost.h.

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

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Initialization

Detailed Description

Constructor & Destructor Documentation

◆ Host()

◆ ~Host()

Member Function Documentation

◆ _setProcessingActive()

◆ _unsetProcessingActive()

◆ calculateInputSubImageBoxDebug()

◆ destroyDefaultHost()

◆ enableTimeLineProfiling()

◆ freeTile()

◆ getBreakCheckCB()

◆ getBreakCheckCBUserData()

◆ getClassicHostDebug()

◆ getDefaultHost()

◆ getMaxNumThreads()

◆ getMemoryManagerId()

◆ getPageRequestProcessor()

◆ getPressedNotifyField()

◆ getProcessingTimeLine()

◆ getProgressCB()

◆ getProgressCBUserData()

◆ getRestrictMaxNumThreads()

◆ getTile() [1/2]

◆ getTile() [2/2]

◆ getUseClassicHost()

◆ isProcessingActive()

◆ processAllPages() [1/2]

◆ processAllPages() [2/2]

◆ processAllPagesWithInputImage()

◆ processAllPagesWithInputImages()

◆ processMissingPages()

◆ registerWithMemoryManager()

◆ setBreakCheckCB()

◆ setMaxNumThreads()

◆ setProgressCB()

◆ setRestrictMaxNumThreads()

◆ setUseClassicHost()

◆ shouldTerminate()

◆ updateImageProperties() [1/2]

◆ updateImageProperties() [2/2]

◆ updateProgress()

Friends And Related Function Documentation

◆ ClassicHost

◆ MultiThreadedPageRequestProcessor

◆ PageRequestProcessor

◆ SingleThreadedPageRequestProcessor