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

Parameters:
object: The name or ID of the object.
mode (enum): A string specifying the mode of the object. One of the following:
- "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).

Value: Getting the <layerMode> property of the target object returns the value in the it variable.

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 property>) - 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'.

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.

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 property> of the stack is not empty.

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

Tags: windowing
