Name
AsyncDrawFrame -- draw the next frame of an asynchronous object (V4.0)
Synopsis
finish = AsyncDrawFrame(id[, frame])
Function
This function can be used to draw the next frame of an asynchronous draw object created by one of functions from the transition effect or move object libraries. AsyncDrawFrame() will return False if there are frames left in its queue. Thus, you should normally call this function until it returns True, which means that you have now drawn all frames that were in the asynchronous draw object's queue.

When this function returns True, it automatically deletes the asynchronous draw object so that is no longer valid and can no longer be used. If you want to stop an asynchronous drawing sequence before all frames have been drawn, you can use the CancelAsyncDraw() function. If you want to stop an asynchronous drawing object and make it execute its finishing code, you have to use the FinishAsyncDraw() function.

Starting with Hollywood 4.5, AsyncDrawFrame() accepts an optional argument which allows you to explicitly specify which frame you want to have drawn. To find out the number of frames of an asynchronous draw object, you have to call GetAttribute() on it using #ATTRNUMFRAMES. The value you get from this call is the largest valid frame number. To draw the first frame, you have to pass 1. To draw the next frame, pass the value 0 which is also the default and used if the frame argument is omitted.

If you manually specify the frame to draw, you also need to pay attention that your asynchronous drawing object is freed correctly. If you do not use the optional argument, the async drawing object is automatically freed when AsyncDrawFrame() returns True. If you specify a frame manually, the async draw object is never freed. Even if you specify the last frame, Hollywood will not free the async draw object because it must be possible to seek to the last frame and back to the another frame. If Hollywood automatically freed the async draw object if you chose to draw the last frame, then this would not be possible. So if you are manually setting the current frame, make sure that you call FinishAsyncDraw() on the asynchronous drawing object when you are done.

Please note that currently some restrictions apply to this function:

  1. Asynchronous frames can only be drawn to the main display window. You cannot use this function to draw to brushes currently.

  2. While there are asynchronous draw objects, you cannot switch the layer mode. Calls to EnableLayers() or DisableLayers() will be disabled while asynchronous draw objects are active.

  3. You cannot switch background pictures while there asynchronous draw objects.

  4. Frame seeking only works with asynchronous drawing objects that are associated with a layer.

  5. Frame seeking does only work with asynchronous drawing objects of type #ADF_FX.

Inputs
id
identifier of the asynchronous draw object to use
frame
optional: the frame you wish to draw; works only with async draw objects associated with a layer (V4.5)
Results
finish
False if there are more frames left to be drawn or True if the asynchronous draw object has finished
Example
obj = DisplayBrushFX(1, #CENTER, #CENTER, {Type = #WATER1, Async = True})
Repeat
   done = AsyncDrawFrame(obj)
   VWait
Until done = True
The code above displays brush 1 in the center of the screen with the #WATER1 transition effect. As you can see, the effect is not displayed by DisplayBrushFX() but in the AsyncDrawFrame() loop below so that you could do some other things as well during the transition effect. 

EnableLayers
DisplayBrush(1, #CENTER, #CENTER)
obj = ShowLayerFX(1, {Type = #WALLPAPERTOP, Async = True})
frames = GetAttribute(#ASYNCDRAW, obj, #ATTRNUMFRAMES)
For Local k = frames To 1 Step -1
   AsyncDrawFrame(obj, k)
   VWait
Next
For Local k = 1 To frames
   AsyncDrawFrame(obj, k)
   VWait
Next
FinishAsyncDraw(obj)
The code above shows brush number 1 using #WALLPAPERTOP. The effect is first displayed the other way round and then in normal order. Note that we have to manually free the draw object using FinishAsyncDraw().
Show TOC