RenderEffect Progress Callback Mechanism

You can control the main Rendering Effect dialog progress bar resp. the Renderer progress bar using an on apply handler with progressCB , the progress callback interface object.

The following syntax lets you do this:

on apply <bitmap> progressCB: do <fn>

The first argument is the bitmap value to be modified by the effect and progressCB is a progress callback interface object. This interface has several methods you can call during the course of processing the bitmap that control the progress bar and check for user cancellation.

Methods

progressCB.setTitle <string>

Sets the title on the progress bar.

progressCB.progress <done> <total>

Defines the progress of the rendering. Both arguments are integers; done indicates how much of the rendering has been completed and total indicates the total amount of work to be done. For instance, in a main loop of a render effect going through all lines of a bitmap, done must be set to the current line number being processed and total must be set to the number of lines in the bitmap (its vertical resolution).

When this is called, either the main Rendering Effect progress bar or the Renderer progress bar is updated to reflect this progress depending on whether the effect is being updated by the Rendering Effect dialog or called by the renderer.

This function also returns a boolean, which if true indicates that the user has hit the Escape key to cancel the effect rendering.

progressCB.check()

Indicates whether the user has hit the escape key to cancel the effect rendering. This function returns a boolean; false if processing must continue and true if the user has cancelled the rendering.

EXAMPLE:

   on apply bm progressCB: do
   (
   ...
   progressCB.setTitle "My Effect Pass1"
   ...
   oldEscapeEnable = escapeEnable -- get old state of escape processing
   escapeEnable = false -- turn off MAXScript escape processing
   total = bm.height -- define total as the height of the bitmap
   for i in ...
   (
   <the effect rendering loop>
   ...
   if progressCB.progress i total then exit --i lines done out of total
   )--end i loop
   ...
   escapeEnable = oldEscapeEnable --restore original state
   ...
   )--end on apply

The progress bar update is done inside the main processing loop and the check for user cancel is done on the same call, which causes the loop to exit prematurely in this example.

For a real-world practical example of the RenderEffect Progress Callback usage, see the How To ... Create a MonoChrome RenderEffect tutorial.