Name
BeginRefresh -- start an optimized refresh section (V5.3)
Synopsis
BeginRefresh([force])
Function
This command starts an optimized refresh section for the currently active display. "Optimized refresh" means that all drawing commands that follow after this call are deferred until you call EndRefresh(). This is useful for systems that do not support partial screen refreshes but always require a full refresh even if only a few pixels have changed.

Imagine the following situation: On every new frame your game has to draw 48 sprites to the screen. On systems that do not support partial screen refresh this would mean that Hollywood would have to redraw the whole screen 48 times and this 50 times a second if your game runs at 50fps. Thus, 2400 complete screen refreshes (48 * 50) would be necessary per second (!). This of course will kill your game's performance immediately. If you encapsulate the drawing of the 48 sprites inside a BeginRefresh() and EndRefresh() section instead, Hollywood will only have to refresh the screen once per frame (50 times per second), which leads to a much smoother appearance. Thus, using BeginRefresh() in this case is absolutely mandatory to ensure a good performance of your game.

Optimized refresh can also greatly enhance the performance of your script when autoscaling is active. If you use normal drawing with autoscaling, Hollywood will have to scale its refresh buffer to the desired dimensions on every single command that draws something. If you use a BeginRefresh() section here instead, Hollywood will just have to scale its refresh buffer once EndRefresh() is called. This of course can also enhance the performance significantly.

By default, BeginRefresh() will only use optimized refresh if the host platform does not support partial screen refresh or if autoscaling is enabled. You can change this behaviour by passing True in the optional force argument. If force is set to True, BeginRefresh() will always use optimized refresh but this is not recommended because optimized refresh can also be slower than normal refresh in some cases. That is why you should leave the decision whether to use optimized refresh or not to Hollywood.

As of Hollywood 5.3 the only platform that does not support partial screen refresh is Android. All other platforms support partial screen refresh. Thus, BeginRefresh() will simply do nothing on all platforms besides Android. But you should still use BeginRefresh() even if you are not targetting Android because as soon as autoscaling is enabled, using BeginRefresh() can enhance the performance significantly (see above). Hence, it is always a good idea to encapsulate your drawing code using a BeginRefresh() and EndRefresh() section because it ensures that your script will run at a good performance on Android and with autoscaling enabled.

Please note that you only need to use BeginRefresh() sections if your script does its drawing without a double buffer. If your script uses a double-buffer, drawing is already pipelined to one refresh per frame and thus using BeginRefresh() is not needed in this case.

Inputs
force
optional: force the use of optimized refresh or leave the decision to Hollywood. See above for more information (defaults to False which means leave the decision to Hollywood)
Example
BeginRefresh()
For Local k = 1 To 48
   DisplaySprite(k, sprites[k].x, sprites[k].y)
Next
EndRefresh()
The code above places 48 sprites on their positions using a BeginRefresh() section. This means that on systems that do not support partial screen refresh (e.g. Android) Hollywood just has to update the screen once to reposition all 48 sprites. Without BeginRefresh() Hollywood would have to update the screen 48 times which is of course much slower.

Show TOC