Name: layerMode

Type: property

Syntax: set the layerMode of <object> to <mode>

Syntax: get the [effective] layerMode of <object>

Summary:
Specifies whether an object is dynamic or static.

Associations: field, button, graphic, scrollbar, player, image

Introduced: 5.0

OS: mac, windows, linux, ios, android

Platforms: desktop, mobile

Example:
set the layerMode of button 1 to "static"

Example:
set the layerMode of image "background" to "static"
set the layerMode of image "bouncing_ball" to "dynamic"

Example:
set the layerMode of group "scroller" to "scrolling"
get the effective layerMode of group "scroller"
if it is "dynamic" then
   answer "group needs updated for fast scrolling"
end if

Value (enum):
A string specifying the mode of the object.

-   static: (default) The object is static and does not move or change.
-   dynamic: The object is dynamic and subject to change and/or
    movement. 
-   scrolling: Applies to groups only and is used where the group
    contains contents to scroll. The group must be unadorned or the
    layerMode is set to 'dynamic' (no borders, no scrollbars).
-   container: Applies to groups only and is used where the group
    is intended only to organise or restrict the visible area of
    its contents. The group must be unadorned or the
    layerMode is set to 'dynamic' (no borders, no scrollbars).


Description:
Use the layerMode property to specify if an object is static or dynamic.
The LiveCode engine uses this to optimize rendering performance by
caching objects that are moving or changing regularly.

If you specify the effective keyword, getting the <layerMode> returns
how the engine is actually treating the layer, rather than what you
requested it to be. There can be a difference for a number of reasons:

1. You are not using a compositor (set using <compositorType>) -
effective layerMode is set to 'static'. 
2. You have a static <layerMode>
object with a non-copy/blendSrcOver ink set - effective layerMode is set
to 'dynamic'. 
3. You have a scrolling <layerMode> on a non-group or an
adorned group - effective layerMode is set to 'dynamic'.
4. You have a container <layerMode> on a non-group or an
adorned or opaque group - effective layerMode is set to 'static'.

**Scrolling**

The scrolling layerMode is pertinent to groups. It means that the engine
caches the content of the group unclipped, and then renders the cached
copies clipped; instead of caching the visible portion of the group.
This results in fast updates when setting the scroll properties of a
group. 

**Container**
The container layerMode is pertinent to groups. When a group has its
layerMode set to 'container', and all its ancestor groups (if any) have
their layerMode set to 'container', the engine ignores the group for the
purposes of accelerated rendering, allowing objects within the group to
have 'static', 'dynamic' or 'scrolling' layerModes; e.g. an image with
'dynamic' layerMode inside a group will behave the same as if it were a
top-level object with 'dynamic' layerMode *except* it will be clipped by
the rect of its owning group.

**Static vs Dynamic**

There are various contexts where setting the <layerMode> can have a big
impact on the performance of an application, in particular games or
interfaces with moving/changing elements. In these cases, the
<layerMode> should be set to 'dynamic'.

A PLATFORM GAME EXAMPLE

Take a platform game as an example. The main character, any animated
elements and scrolling platform components should all have a <layerMode>
of 'dynamic'. However, the background image should have a <layerMode> of
'static'. 

NON-GAME DRAG EXAMPLE

Consider a drag-drop interface where a user can 'pick' something up and
drop it elsewhere. While the object is being dragged across the stack
the <layerMode> can be set to 'dynamic' (particularly important if it
has graphic effects applied). Once in its final location the <layerMode>
can be returned to 'static'

>*Warning:* The <layerMode> only has an effect if the <compositorType>
> of the stack is not empty.

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

Tags: windowing

