Name: iphoneSetRedrawInterval

Type: command

Syntax: iphoneSetRedrawInterval <frameInterval>

Summary:
Synchronizes LiveCode redraws with the device's refresh rate.

Associations: stack

Introduced: 5.0

OS: ios

Platforms: mobile

Example:
iphoneSetRedrawInterval 1 -- Redraw with every iOS redraw request

Example:
iphoneSetRedrawInterval 2 -- Redraw on every other iOS redraw request

Example:
iphoneSetRedrawInterval 0 -- Don't use the redraw interval feature

Parameters:
frameInterval (enum):
A number specifying how often LiveCode should update the screen in line
with the screen's refresh rate.

-   "0": Turn off synchronized redraws and revert to default LiveCode
    redrawing behavior.
-   "1": Redraw every time iOS redraws.
-   "2": Redraw on every other iOS redraw.
-   "x": Redraw every x iOS redraws.


Description:
Use the <iphoneSetRedrawInterval> command to improve screen update
performance and smoothness on iOS devices by tying LiveCode redraw calls
to the device's refresh rate.

By default, LiveCode updates the screen immediately after any command
that requires it. This means that several small screen updates may occur
in quick succession when animation is combined with other dynamic screen
elements. On mobile devices this can affect smoothness of animation
where it would be better if multiple frequent redraws were replaced with
a single periodic redraw. Setting the <iphoneSetRedrawInterval> enables
this behaviour, where the screen is updated at a fixed interval tied to
iOS's redraw rate.

WHEN TO USE
This feature should be used for applications that cause the screen to be
redrawn often or where redraws are being called by various application
elements. For example, scrollers, dragging and the move command all
independently request redraws causing a build up which can lead to
'judders' and other unwanted drawing issues.

>*Warning:* When using this feature, updates do not occur after each
> command. 

>*Warning:* This feature should not be used if your scripts prevent
> system messages from being processed. For example, tight loops using
> the wait command. Screen redraws are dependent on LiveCode receiving
> iOS redraw calls.

References: compositorTileSize (property), layerMode (property),
compositorType (property), compositorCacheLimit (property)

