Layer class abstract

A composited layer.

During painting, the render tree generates a tree of composited layers that are uploaded into the engine and displayed by the compositor. This class is the base class for all composited layers.

Most layers can have their properties mutated, and layers can be moved to different parents. The scene must be explicitly recomposited after such changes are made; the layer tree does not maintain its own dirty state.

To composite the tree, create a SceneBuilder object, pass it to the root Layer object's addToScene method, and then call SceneBuilder.build to obtain a Scene. A Scene can then be painted using dart:ui.FlutterView.render.

Memory

Layers retain resources between frames to speed up rendering. A layer will retain these resources until all LayerHandles referring to the layer have nulled out their references.

Layers must not be used after disposal. If a RenderObject needs to maintain a layer for later usage, it must create a handle to that layer. This is handled automatically for the RenderObject.layer property, but additional layers must use their own LayerHandle.

This RenderObject is a repaint boundary that pushes an additional ClipRectLayer.
link
class ClippingRenderObject extends RenderBox {
  final LayerHandle<ClipRectLayer> _clipRectLayer = LayerHandle<ClipRectLayer>();

  @override
  bool get isRepaintBoundary => true; // The [layer] property will be used.

  @override
  void paint(PaintingContext context, Offset offset) {
    _clipRectLayer.layer = context.pushClipRect(
      needsCompositing,
      offset,
      Offset.zero & size,
      super.paint,
      oldLayer: _clipRectLayer.layer,
    );
  }

  @override
  void dispose() {
    _clipRectLayer.layer = null;
    super.dispose();
  }
}
See also:

Mixed in types
Implementers

Constructors

Layer()
Creates an instance of Layer.

Properties

alwaysNeedsAddToScene bool
Subclasses may override this to true to disable retained rendering.
no setter
attached bool
Whether the layer tree containing this layer is attached to an owner.
no setter
debugCreator Object?
The object responsible for creating this layer.
getter/setter pair
debugDisposed bool
If asserts are enabled, returns whether dispose has been called since the last time any retained resources were created.
no setter
debugHandleCount int
Returns the number of objects holding a LayerHandle to this layer.
no setter
debugSubtreeNeedsAddToScene bool?
Whether this or any descendant layer in the subtree needs addToScene.
no setter
depth int
The depth of this layer in the layer tree.
no setter
engineLayer EngineLayer?
Stores the engine layer created for this layer in order to reuse engine resources across frames for better app performance.
getter/setter pair
hashCode int
The hash code for this object.
no setterinherited
nextSibling Layer?
This layer's next sibling in the parent layer's child list.
no setter
owner Object?
The owner for this layer (null if unattached).
no setter
parent ContainerLayer?
This layer's parent in the layer tree.
no setter
previousSibling Layer?
This layer's previous sibling in the parent layer's child list.
no setter
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
subtreeHasCompositionCallbacks bool
Whether the subtree rooted at this layer has any composition callback observers.
no setter

Methods

addCompositionCallback(CompositionCallback callback) VoidCallback
Adds a callback for when the layer tree that this layer is part of gets composited, or when it is detached and will not be rendered again.
addToScene(SceneBuilder builder) → void
Override this method to upload this layer to the engine.
attach(covariant Object owner) → void
Mark this layer as attached to the given owner.
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
override
debugMarkClean() → void
Mark that this layer is in sync with engine.
describeClipBounds() Rect?
Describes the clip that would be applied to contents of this layer, if any.
detach() → void
Mark this layer as detached from its owner.
dispose() → void
Clears any retained resources that this layer holds.
find<S extends Object>(Offset localPosition) → S?
Search this layer and its subtree for the first annotation of type S under the point described by localPosition.
findAllAnnotations<S extends Object>(Offset localPosition) AnnotationResult<S>
Search this layer and its subtree for all annotations of type S under the point described by localPosition.
findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, {required bool onlyFirst}) bool
Search this layer and its subtree for annotations of type S at the location described by localPosition.
markNeedsAddToScene() → void
Mark that this layer has changed and addToScene needs to be called.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
redepthChildren() → void
Adjust the depth of this node's children, if any.
remove() → void
Removes this layer from its parent layer's child list.
supportsRasterization() bool
Whether or not this layer, or any child layers, can be rasterized with Scene.toImage or Scene.toImageSync.
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object.
inherited
toStringShort() String
A brief description of this object, usually just the runtimeType and the hashCode.
override
updateSubtreeNeedsAddToScene() → void
Traverses the layer subtree starting from this layer and determines whether it needs addToScene.

Operators

operator ==(Object other) bool
The equality operator.
inherited