Using Progress Functions
Sometimes making HOOPS perform a task won't give an immediate result. And insofar as the API is not concurrent, performing any time consuming operation will block your application until it's finished. This is the case when loading files or processing CAD models where the operation may take a little while.
To give you feedback on the evolution of such operations, you can provide the API with a set of callback functions which are automatically called to update you about the progress of a long running task.
Setting up the callbacks
To define the callback functions, call
A3DDllSetCallbacksProgress. It accepts 5 functions and a pointer to a control flag that can be used to stop the process:
All functions must be set.
Progress Start and End
When the API starts a new progress,
on_start is called. This function receives an indicator of the type of the performed operation:
1: File Read
2: File Write
3: Any operation done after reading
- The current version of HOOPS API does not provide an exhaustive set of identifiers. For a more precise description of the task being performed, please see the description of the
All incoming calls to your callback functions address the same progress until
on_end is called by the API:
Getting a description of the executing task
Right after the progress starts,
on_title is called and is given a descriptive string of the performing task. If the current progress is the loading of a CAD file, the value contains the name of the file.
Please note that the lifetime of
in_pcTitle is clamped to the call of this function.
Being notified about the progress
The progress of the task is expressed using a range of integer values where the maximum is passed to
- Please note that there is no direct relation between this value and a potential time estimation for the performed task. The value given for
in_iMaxin set internally and shouldn't be interpreted to any specific meaning.
Then each time HOOPS notifies about its progress, it calls
on_increment which is given a value between 0 and
Stopping the progress
Some operations may be cancelled while running. To do so, simply change the value given to
A3DDllSetCallbacksProgress to any non-zero integer.
- Because the value passed to
A3DDllSetCallbacksProgressis a pointer to a local variable, please be cautious with the lifetime of the actual variable.
This complete example can be used to display any progress in the standard output.
Some elements of this code snippets are worth some precisions:
- Because there is no order guarantee in the function calls,
on_incrementshouldn't assume that
maxis non-zero. To avoid a zero-division, we display only the title of the progress in that case.
- For the same reason,
titlemay not be set when
on_incrementis called. This is why is it initialized first to a default value.