layerMode

Type

property

Summary

Specifies whether an object is dynamic or static.

Syntax

set the layerMode of <object> to <mode>

get the [effective] layerMode of <object>

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.

Examples

set the layerMode of button 1 to "static"

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

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

Related

property: compositorTileSize, compositorType, compositorCacheLimit

Compatibility and Support

Introduced

LiveCode 5.0

OS

mac

windows

linux

ios

android

Platforms

desktop

mobile