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 ui.SceneBuilder object using RendererBinding.createSceneBuilder, pass it to the root Layer object's addToScene method, and then call ui.SceneBuilder.build to obtain a ui.Scene. A ui.Scene can then be painted using 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.

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();
  }
}

• RenderView.compositeFrame, which implements this recomposition protocol for painting RenderObject trees on the display.