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:
0
: Undefined1
: File Read2
: File Write3
: Any operation done after reading
- Warning
- 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
on_title
callback below.
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 on_size
.
- Warning
- 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_iMax
in 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 max
:
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.
- Warning
- Because the value passed to
A3DDllSetCallbacksProgress
is a pointer to a local variable, please be cautious with the lifetime of the actual variable.
Full example
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_increment
shouldn't assume thatmax
is non-zero. To avoid a zero-division, we display only the title of the progress in that case. - For the same reason,
title
may not be set whenon_increment
is called. This is why is it initialized first to a default value.