Layer class Null safety
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.
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:
- RenderView.compositeFrame, which implements this recomposition protocol for painting RenderObject trees on the display.
- Inheritance
-
- Object
- AbstractNode
- Layer
- Mixed in types
- Implementers
Constructors
- Layer()
Properties
- alwaysNeedsAddToScene → bool
-
Subclasses may override this to true to disable retained rendering.
protected">@protectedread-only
- attached → bool
-
Whether this node is in a tree whose root is attached to something.
read-onlyinherited
- debugCreator ↔ Object?
-
The object responsible for creating this layer.
read / write
- debugDisposed → bool
-
If asserts are enabled, returns whether dispose has
been called since the last time any retained resources were created.
read-only
- debugHandleCount → int
-
Returns the number of objects holding a LayerHandle to this layer.
read-only
- debugSubtreeNeedsAddToScene → bool?
-
Whether this or any descendant layer in the subtree needs addToScene.
visibleForTesting">@visibleForTestingread-only
- depth → int
-
The depth of this node in the tree.
read-onlyinherited
- engineLayer ↔ EngineLayer?
-
Stores the engine layer created for this layer in order to reuse engine
resources across frames for better app performance.
protected">@protectedprotected">@protectedvisibleForTesting">@visibleForTestingvisibleForTesting">@visibleForTestingread / write
- hashCode → int
-
The hash code for this object.
read-onlyinherited
- nextSibling → Layer?
-
This layer's next sibling in the parent layer's child list.
read-only
- owner → Object?
-
The owner for this node (null if unattached).
read-onlyinherited
- parent → ContainerLayer?
-
This layer's parent in the layer tree.
read-onlyoverride
- previousSibling → Layer?
-
This layer's previous sibling in the parent layer's child list.
read-only
- runtimeType → Type
-
A representation of the runtime type of the object.
read-onlyinherited
- subtreeHasCompositionCallbacks → bool
-
Whether the subtree rooted at this layer has any composition callback
observers.
read-only
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.
protected">@protected
-
adoptChild(
covariant Layer child) → void -
Mark the given node as being a child of this node.
override
-
attach(
covariant Object owner) → void -
Mark this node as attached to the given owner.
mustCallSuper">@mustCallSuperinherited
-
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.
visibleForTesting">@visibleForTesting
-
describeClipBounds(
) → Rect? - Describes the clip that would be applied to contents of this layer, if any.
-
detach(
) → void -
Mark this node as detached.
mustCallSuper">@mustCallSuperinherited
-
dispose(
) → void - Clears any retained resources that this layer holds.
-
dropChild(
covariant Layer child) → void -
Disconnect the given node from this node.
override
-
find<
S extends Object> (Offset localPosition) → S? -
Search this layer and its subtree for the first annotation of type
S
under the point described bylocalPosition
. -
findAllAnnotations<
S extends Object> (Offset localPosition) → AnnotationResult< S> -
Search this layer and its subtree for all annotations of type
S
under the point described bylocalPosition
. -
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 bylocalPosition
.protected">@protected -
markNeedsAddToScene(
) → void -
Mark that this layer has changed and addToScene needs to be called.
protected">@protectedvisibleForTesting">@visibleForTesting
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a non-existent method or property is accessed.
inherited
-
redepthChild(
AbstractNode child) → void -
Adjust the depth of the given
child
to be greater than this node's own depth.protected">@protectedinherited -
redepthChildren(
) → void -
Adjust the depth of this node's children, if any.
inherited
-
remove(
) → void -
Removes this layer from its parent layer's child list.
mustCallSuper">@mustCallSuper
-
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.
protected">@protectedvisibleForTesting">@visibleForTesting
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited