layerMode

Typeproperty
DictionaryLCS
LibraryLiveCode Script
Syntax
set the layerMode of <object> to <mode>
get the [effective] layerMode of <object>
Associationsfield, button, graphic, scrollbar, player, image
Summary

Specifies whether an object is dynamic or static.

Introduced5.0
OSmac, windows, linux, ios, android
Platformsdesktop, mobile
Example
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
Values
NameTypeDescription
Value

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).
RelatedProperty: compositorTileSize, compositorType, compositorCacheLimit
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.

Tagswindowing