ML Reference
|
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. | |
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 worker threads to numThreads . | |
MLint32 | getMaxNumThreads () const |
Returns maximum number of permitted worker threads. | |
void | setRestrictMaxNumThreads (MLint32 numThreads) |
Restricts the maximum number of permitted worker threads to be lower or equal to numThreads . | |
MLint32 | getRestrictMaxNumThreads () const |
Get the restriction for setMaxNumThreads(). | |
MLuint32 | isProcessingActive () const |
Non-zero return values mean that (image) processing is currently active. | |
ClassicHost * | getClassicHostDebug () |
Get access to classic ML host (for debugging purposes only!) | |
void | setUseClassicHost (bool flag) |
Enable/disable usage of classic ML host. | |
bool | getUseClassicHost () const |
Returns if classic ML host is used. | |
PageRequestProcessor * | getPageRequestProcessor () |
Get the currently responsible page request processor. | |
ProcessingTimeLine & | getProcessingTimeLine () |
Get access to the processing time line. | |
void | enableTimeLineProfiling (bool flag) |
Enable/disable time line profiling. | |
Computation of image data in different memory allocation variations | |
MLErrorCode | getTile (PagedImage &outputImage, SubImageBox location, MLDataType dataType, void **data, const ScaleShiftData &scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED |
Requests the image region location from the image outputImage . | |
MLErrorCode | getTile (PagedImage &outputImage, SubImage &subImage, const ScaleShiftData &scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED |
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()) ML_RETURN_VALUE_SHOULD_BE_USED |
See Module::processAllPages() for details on this method. | |
MLErrorCode | processAllPages (Module &module, ProcessAllPagesHandler &handler, SubImageBox region=SubImageBox()) ML_RETURN_VALUE_SHOULD_BE_USED |
Processes input images with a ProcessAllPagesHandler on a temporary output image (which allocates no data) For details, see Module::processAllPages() | |
MLErrorCode | processMissingPages (Module &module, MLint outputIndex, SubImageBox region=SubImageBox()) ML_RETURN_VALUE_SHOULD_BE_USED |
See Module::processMissingPages() for details on this method. | |
Update image properties at module output. | |
MLErrorCode | updateImageProperties (Module &module, MLint outputIndex) ML_RETURN_VALUE_SHOULD_BE_USED |
/deprecated Updates the module graph under module and including the output image at outputIndex of module . | |
MLErrorCode | updateImageProperties (PagedImage &outputImage) ML_RETURN_VALUE_SHOULD_BE_USED |
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 |
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. | |
Host () | |
Constructor. | |
virtual | ~Host () |
Destructor. | |
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()) ML_RETURN_VALUE_SHOULD_BE_USED |
MLErrorCode | getTile (Module &op, MLint outIndex, SubImage &subImg, const ScaleShiftData &scaleShiftData=ScaleShiftData()) ML_RETURN_VALUE_SHOULD_BE_USED |
MLErrorCode | updateImageProps (Module &op, MLint outIndex) ML_RETURN_VALUE_SHOULD_BE_USED |
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:
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.
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.
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] |
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::enableTimeLineProfiling | ( | bool | flag | ) |
Enable/disable time line profiling.
void ml::Host::freeTile | ( | void * | data | ) |
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.
ClassicHost* ml::Host::getClassicHostDebug | ( | ) | [inline] |
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 worker threads.
static unsigned int ml::Host::getMemoryManagerId | ( | ) | [inline, static] |
PageRequestProcessor* ml::Host::getPageRequestProcessor | ( | ) |
Get the currently responsible page request processor.
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.
ProcessingTimeLine& ml::Host::getProcessingTimeLine | ( | ) |
Get access to the processing time line.
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.
MLint32 ml::Host::getRestrictMaxNumThreads | ( | ) | const [inline] |
Get the restriction for setMaxNumThreads().
MLErrorCode ml::Host::getTile | ( | Module & | op, |
MLint | outIndex, | ||
SubImageBox | loc, | ||
MLDataType | dataType, | ||
void ** | data, | ||
const ScaleShiftData & | scaleShiftData = ScaleShiftData() |
||
) |
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.
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 | ( | Module & | op, |
MLint | outIndex, | ||
SubImage & | subImg, | ||
const ScaleShiftData & | scaleShiftData = ScaleShiftData() |
||
) |
bool ml::Host::getUseClassicHost | ( | ) | const [inline] |
MLuint32 ml::Host::isProcessingActive | ( | ) | const |
Non-zero return values mean that (image) processing is currently active.
static MLErrorCode ml::Host::popDefaultHost | ( | ) | [static] |
MLErrorCode ml::Host::processAllPages | ( | Module & | module, |
MLint | outputIndex, | ||
SubImageBox | region = SubImageBox() |
||
) |
See Module::processAllPages() for details on this method.
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 Module::processAllPages()
MLErrorCode ml::Host::processMissingPages | ( | Module & | module, |
MLint | outputIndex, | ||
SubImageBox | region = SubImageBox() |
||
) |
See Module::processMissingPages() for details on this method.
static MLErrorCode ml::Host::pushDefaultHost | ( | ) | [static] |
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 worker threads to numThreads
.
A value of 0 or 1 turns multi-threading off. If setMaxNumThreads() is restricted via setRestrictMaxNumThreads(), the given value is silently clamped to getRestrictMaxNumThreads().
void ml::Host::setProgressCB | ( | void * | userData, |
MLHostProgressCB * | callback | ||
) |
Sets callback for progress/busy cursor updates.
void ml::Host::setRestrictMaxNumThreads | ( | MLint32 | numThreads | ) |
Restricts the maximum number of permitted worker threads to be lower or equal to numThreads
.
Once this has been set, the number of threads can not 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.
void ml::Host::setUseClassicHost | ( | bool | flag | ) |
Enable/disable usage of classic ML host.
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 | ( | 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::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::updateImageProps | ( | Module & | op, |
MLint | outIndex | ||
) | [inline] |
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.
friend class ClassicHost [friend] |
friend class MultiThreadedPageRequestProcessor [friend] |
friend class PageRequestProcessor [friend] |
friend class SingleThreadedPageRequestProcessor [friend] |