layer.dart [flutter/packages/flutter/lib/src/rendering/layer.dart]

1	// Copyright 2014 The Flutter Authors. All rights reserved.
2	// Use of this source code is governed by a BSD-style license that can be
3	// found in the LICENSE file.
4
5	import 'dart:ui' as ui;
6
7	import 'package:flutter/foundation.dart';
8	import 'package:flutter/gestures.dart';
9	import 'package:flutter/painting.dart';
10	import 'package:flutter/scheduler.dart';
11	import 'package:vector_math/vector_math_64.dart';
12
13	import 'debug.dart';
14
15	/// Information collected for an annotation that is found in the layer tree.
16	///
17	/// See also:
18	///
19	/// [Layer.findAnnotations], which create and use objects of this class.*
20	@immutable
21	class AnnotationEntry<T> {
22	/// Create an entry of found annotation by providing the object and related
23	/// information.
24	const AnnotationEntry({
25	required this.annotation,
26	required this.localPosition,
27	});
28
29	/// The annotation object that is found.
30	final T annotation;
31
32	/// The target location described by the local coordinate space of the
33	/// annotation object.
34	final Offset localPosition;
35
36	@override
37	String toString() {
38	return '${objectRuntimeType(this, 'AnnotationEntry')}(annotation: $annotation, localPosition: $localPosition)';
39	}
40	}
41
42	/// Information collected about a list of annotations that are found in the
43	/// layer tree.
44	///
45	/// See also:
46	///
47	/// [AnnotationEntry], which are members of this class.*
48	/// [Layer.findAllAnnotations], and [Layer.findAnnotations], which create and*
49	/// use an object of this class.
50	class AnnotationResult<T> {
51	final List<AnnotationEntry<T>> _entries = <AnnotationEntry<T>>[];
52
53	/// Add a new entry to the end of the result.
54	///
55	/// Usually, entries should be added in order from most specific to least
56	/// specific, typically during an upward walk of the tree.
57	void add(AnnotationEntry<T> entry) => _entries.add(entry);
58
59	/// An unmodifiable list of [AnnotationEntry] objects recorded.
60	///
61	/// The first entry is the most specific, typically the one at the leaf of
62	/// tree.
63	Iterable<AnnotationEntry<T>> get entries => _entries;
64
65	/// An unmodifiable list of annotations recorded.
66	///
67	/// The first entry is the most specific, typically the one at the leaf of
68	/// tree.
69	///
70	/// It is similar to [entries] but does not contain other information.
71	Iterable<T> get annotations {
72	return _entries.map((AnnotationEntry<T> entry) => entry.annotation);
73	}
74	}
75
76	const String _flutterRenderingLibrary = 'package:flutter/rendering.dart';
77
78	/// A composited layer.
79	///
80	/// During painting, the render tree generates a tree of composited layers that
81	/// are uploaded into the engine and displayed by the compositor. This class is
82	/// the base class for all composited layers.
83	///
84	/// Most layers can have their properties mutated, and layers can be moved to
85	/// different parents. The scene must be explicitly recomposited after such
86	/// changes are made; the layer tree does not maintain its own dirty state.
87	///
88	/// To composite the tree, create a [SceneBuilder] object, pass it to the
89	/// root [Layer] object's [addToScene] method, and then call
90	/// [SceneBuilder.build] to obtain a [Scene]. A [Scene] can then be painted
91	/// using [dart:ui.FlutterView.render].
92	///
93	/// ## Memory
94	///
95	/// Layers retain resources between frames to speed up rendering. A layer will
96	/// retain these resources until all [LayerHandle]s referring to the layer have
97	/// nulled out their references.
98	///
99	/// Layers must not be used after disposal. If a RenderObject needs to maintain
100	/// a layer for later usage, it must create a handle to that layer. This is
101	/// handled automatically for the [RenderObject.layer] property, but additional
102	/// layers must use their own [LayerHandle].
103	///
104	/// {@tool snippet}
105	///
106	/// This [RenderObject] is a repaint boundary that pushes an additional
107	/// [ClipRectLayer].
108	///
109	/// ```dart
110	/// class ClippingRenderObject extends RenderBox {
111	/// final LayerHandle<ClipRectLayer> _clipRectLayer = LayerHandle<ClipRectLayer>();
112	///
113	/// @override
114	/// bool get isRepaintBoundary => true; // The [layer] property will be used.
115	///
116	/// @override
117	/// void paint(PaintingContext context, Offset offset) {
118	/// _clipRectLayer.layer = context.pushClipRect(
119	/// needsCompositing,
120	/// offset,
121	/// Offset.zero & size,
122	/// super.paint,
123	/// oldLayer: _clipRectLayer.layer,
124	/// );
125	/// }
126	///
127	/// @override
128	/// void dispose() {
129	/// _clipRectLayer.layer = null;
130	/// super.dispose();
131	/// }
132	/// }
133	/// ```
134	/// {@end-tool}
135	/// See also:
136	///
137	/// [RenderView.compositeFrame], which implements this recomposition protocol*
138	/// for painting [RenderObject] trees on the display.
139	abstract class Layer with DiagnosticableTreeMixin {
140	/// Creates an instance of Layer.
141	Layer() {
142	if (kFlutterMemoryAllocationsEnabled) {
143	FlutterMemoryAllocations.instance.dispatchObjectCreated(
144	library: _flutterRenderingLibrary,
145	className: '$Layer',
146	object: this,
147	);
148	}
149	}
150
151	final Map<int, VoidCallback> _callbacks = <int, VoidCallback>{};
152	static int _nextCallbackId = `0`;
153
154	/// Whether the subtree rooted at this layer has any composition callback
155	/// observers.
156	///
157	/// This only evaluates to true if the subtree rooted at this node has
158	/// observers. For example, it may evaluate to true on a parent node but false
159	/// on a child if the parent has observers but the child does not.
160	///
161	/// See also:
162	///
163	/// [Layer.addCompositionCallback].*
164	bool get subtreeHasCompositionCallbacks => _compositionCallbackCount > `0`;
165
166	int _compositionCallbackCount = `0`;
167	void _updateSubtreeCompositionObserverCount(int delta) {
168	assert(delta != `0`);
169	_compositionCallbackCount += delta;
170	assert(_compositionCallbackCount >= `0`);
171	parent?._updateSubtreeCompositionObserverCount(delta);
172	}
173
174	void _fireCompositionCallbacks({required bool includeChildren}) {
175	if (_callbacks.isEmpty) {
176	return;
177	}
178	for (final VoidCallback callback in List<VoidCallback>.of(_callbacks.values)) {
179	callback();
180	}
181	}
182
183	bool _debugMutationsLocked = `false`;
184
185	/// Whether or not this layer, or any child layers, can be rasterized with
186	/// [Scene.toImage] or [Scene.toImageSync].
187	///
188	/// If `false`, calling the above methods may yield an image which is
189	/// incomplete.
190	///
191	/// This value may change throughout the lifetime of the object, as the
192	/// child layers themselves are added or removed.
193	bool supportsRasterization() {
194	return `true`;
195	}
196
197	/// Describes the clip that would be applied to contents of this layer,
198	/// if any.
199	Rect? describeClipBounds() => `null`;
200
201	/// Adds a callback for when the layer tree that this layer is part of gets
202	/// composited, or when it is detached and will not be rendered again.
203	///
204	/// This callback will fire even if an ancestor layer is added with retained
205	/// rendering, meaning that it will fire even if this layer gets added to the
206	/// scene via some call to [ui.SceneBuilder.addRetained] on one of its
207	/// ancestor layers.
208	///
209	/// The callback receives a reference to this layer. The recipient must not
210	/// mutate the layer during the scope of the callback, but may traverse the
211	/// tree to find information about the current transform or clip. The layer
212	/// may not be [attached] anymore in this state, but even if it is detached it
213	/// may still have an also detached parent it can visit.
214	///
215	/// If new callbacks are added or removed within the [callback], the new
216	/// callbacks will fire (or stop firing) on the _next_ compositing event.
217	///
218	/// {@template flutter.rendering.Layer.compositionCallbacks}
219	/// Composition callbacks are useful in place of pushing a layer that would
220	/// otherwise try to observe the layer tree without actually affecting
221	/// compositing. For example, a composition callback may be used to observe
222	/// the total transform and clip of the current container layer to determine
223	/// whether a render object drawn into it is visible or not.
224	///
225	/// Calling the returned callback will remove [callback] from the composition
226	/// callbacks.
227	/// {@endtemplate}
228	VoidCallback addCompositionCallback(CompositionCallback callback) {
229	_updateSubtreeCompositionObserverCount(`1`);
230	final int callbackId = _nextCallbackId += `1`;
231	_callbacks[callbackId] = () {
232	assert(() {
233	_debugMutationsLocked = `true`;
234	return `true`;
235	}());
236	callback(this);
237	assert(() {
238	_debugMutationsLocked = `false`;
239	return `true`;
240	}());
241	};
242	return () {
243	assert(debugDisposed \|\| _callbacks.containsKey(callbackId));
244	_callbacks.remove(callbackId);
245	_updateSubtreeCompositionObserverCount(-`1`);
246	};
247	}
248
249	/// If asserts are enabled, returns whether [dispose] has
250	/// been called since the last time any retained resources were created.
251	///
252	/// Throws an exception if asserts are disabled.
253	bool get debugDisposed {
254	late bool disposed;
255	assert(() {
256	disposed = _debugDisposed;
257	return `true`;
258	}());
259	return disposed;
260	}
261	bool _debugDisposed = `false`;
262
263	/// Set when this layer is appended to a [ContainerLayer], and
264	/// unset when it is removed.
265	///
266	/// This cannot be set from [attach] or [detach] which is called when an
267	/// entire subtree is attached to or detached from an owner. Layers may be
268	/// appended to or removed from a [ContainerLayer] regardless of whether they
269	/// are attached or detached, and detaching a layer from an owner does not
270	/// imply that it has been removed from its parent.
271	final LayerHandle<Layer> _parentHandle = LayerHandle<Layer>();
272
273	/// Incremented by [LayerHandle].
274	int _refCount = `0`;
275
276	/// Called by [LayerHandle].
277	void _unref() {
278	assert(!_debugMutationsLocked);
279	assert(_refCount > `0`);
280	_refCount -= `1`;
281	if (_refCount == `0`) {
282	dispose();
283	}
284	}
285
286	/// Returns the number of objects holding a [LayerHandle] to this layer.
287	///
288	/// This method throws if asserts are disabled.
289	int get debugHandleCount {
290	late int count;
291	assert(() {
292	count = _refCount;
293	return `true`;
294	}());
295	return count;
296	}
297
298	/// Clears any retained resources that this layer holds.
299	///
300	/// This method must dispose resources such as [EngineLayer] and [Picture]
301	/// objects. The layer is still usable after this call, but any graphics
302	/// related resources it holds will need to be recreated.
303	///
304	/// This method _only_ disposes resources for this layer. For example, if it
305	/// is a [ContainerLayer], it does not dispose resources of any children.
306	/// However, [ContainerLayer]s do remove any children they have when
307	/// this method is called, and if this layer was the last holder of a removed
308	/// child handle, the child may recursively clean up its resources.
309	///
310	/// This method automatically gets called when all outstanding [LayerHandle]s
311	/// are disposed. [LayerHandle] objects are typically held by the [parent]
312	/// layer of this layer and any [RenderObject]s that participated in creating
313	/// it.
314	///
315	/// After calling this method, the object is unusable.
316	@mustCallSuper
317	@protected
318	@visibleForTesting
319	void dispose() {
320	assert(!_debugMutationsLocked);
321	assert(
322	!_debugDisposed,
323	'Layers must only be disposed once. This is typically handled by '
324	'LayerHandle and createHandle. Subclasses should not directly call '
325	'dispose, except to call super.dispose() in an overridden dispose '
326	'method. Tests must only call dispose once.',
327	);
328	assert(() {
329	assert(
330	_refCount == `0`,
331	'Do not directly call dispose on a $runtimeType. Instead, '
332	'use createHandle and LayerHandle.dispose.',
333	);
334	_debugDisposed = `true`;
335	return `true`;
336	}());
337	if (kFlutterMemoryAllocationsEnabled) {
338	FlutterMemoryAllocations.instance.dispatchObjectDisposed(object: this);
339	}
340	_engineLayer?.dispose();
341	_engineLayer = `null`;
342	}
343
344	/// This layer's parent in the layer tree.
345	///
346	/// The [parent] of the root node in the layer tree is null.
347	///
348	/// Only subclasses of [ContainerLayer] can have children in the layer tree.
349	/// All other layer classes are used for leaves in the layer tree.
350	ContainerLayer? get parent => _parent;
351	ContainerLayer? _parent;
352
353	// Whether this layer has any changes since its last call to [addToScene].
354	//
355	// Initialized to true as a new layer has never called [addToScene], and is
356	// set to false after calling [addToScene]. The value can become true again
357	// if [markNeedsAddToScene] is called, or when [updateSubtreeNeedsAddToScene]
358	// is called on this layer or on an ancestor layer.
359	//
360	// The values of [_needsAddToScene] in a tree of layers are said to be
361	// _consistent_ if every layer in the tree satisfies the following:
362	//
363	// - If [alwaysNeedsAddToScene] is true, then [_needsAddToScene] is also true.
364	// - If [_needsAddToScene] is true and [parent] is not null, then
365	// `parent._needsAddToScene` is true.
366	//
367	// Typically, this value is set during the paint phase and during compositing.
368	// During the paint phase render objects create new layers and call
369	// [markNeedsAddToScene] on existing layers, causing this value to become
370	// true. After the paint phase the tree may be in an inconsistent state.
371	// During compositing [ContainerLayer.buildScene] first calls
372	// [updateSubtreeNeedsAddToScene] to bring this tree to a consistent state,
373	// then it calls [addToScene], and finally sets this field to false.
374	bool _needsAddToScene = `true`;
375
376	/// Mark that this layer has changed and [addToScene] needs to be called.
377	@protected
378	@visibleForTesting
379	void markNeedsAddToScene() {
380	assert(!_debugMutationsLocked);
381	assert(
382	!alwaysNeedsAddToScene,
383	'$runtimeType with alwaysNeedsAddToScene set called markNeedsAddToScene.\n'
384	"The layer's alwaysNeedsAddToScene is set to true, and therefore it should not call markNeedsAddToScene.",
385	);
386	assert(!_debugDisposed);
387
388	// Already marked. Short-circuit.
389	if (_needsAddToScene) {
390	return;
391	}
392
393	_needsAddToScene = `true`;
394	}
395
396	/// Mark that this layer is in sync with engine.
397	///
398	/// This is for debugging and testing purposes only. In release builds
399	/// this method has no effect.
400	@visibleForTesting
401	void debugMarkClean() {
402	assert(!_debugMutationsLocked);
403	assert(() {
404	_needsAddToScene = `false`;
405	return `true`;
406	}());
407	}
408
409	/// Subclasses may override this to true to disable retained rendering.
410	@protected
411	bool get alwaysNeedsAddToScene => `false`;
412
413	/// Whether this or any descendant layer in the subtree needs [addToScene].
414	///
415	/// This is for debug and test purpose only. It only becomes valid after
416	/// calling [updateSubtreeNeedsAddToScene].
417	@visibleForTesting
418	bool? get debugSubtreeNeedsAddToScene {
419	bool? result;
420	assert(() {
421	result = _needsAddToScene;
422	return `true`;
423	}());
424	return result;
425	}
426
427	/// Stores the engine layer created for this layer in order to reuse engine
428	/// resources across frames for better app performance.
429	///
430	/// This value may be passed to [ui.SceneBuilder.addRetained] to communicate
431	/// to the engine that nothing in this layer or any of its descendants
432	/// changed. The native engine could, for example, reuse the texture rendered
433	/// in a previous frame. The web engine could, for example, reuse the HTML
434	/// DOM nodes created for a previous frame.
435	///
436	/// This value may be passed as `oldLayer` argument to a "push" method to
437	/// communicate to the engine that a layer is updating a previously rendered
438	/// layer. The web engine could, for example, update the properties of
439	/// previously rendered HTML DOM nodes rather than creating new nodes.
440	@protected
441	@visibleForTesting
442	ui.EngineLayer? get engineLayer => _engineLayer;
443
444	/// Sets the engine layer used to render this layer.
445	///
446	/// Typically this field is set to the value returned by [addToScene], which
447	/// in turn returns the engine layer produced by one of [ui.SceneBuilder]'s
448	/// "push" methods, such as [ui.SceneBuilder.pushOpacity].
449	@protected
450	@visibleForTesting
451	set engineLayer(ui.EngineLayer? value) {
452	assert(!_debugMutationsLocked);
453	assert(!_debugDisposed);
454
455	_engineLayer?.dispose();
456	_engineLayer = value;
457	if (!alwaysNeedsAddToScene) {
458	// The parent must construct a new engine layer to add this layer to, and
459	// so we mark it as needing [addToScene].
460	//
461	// This is designed to handle two situations:
462	//
463	// 1. When rendering the complete layer tree as normal. In this case we
464	// call child `addToScene` methods first, then we call `set engineLayer`
465	// for the parent. The children will call `markNeedsAddToScene` on the
466	// parent to signal that they produced new engine layers and therefore
467	// the parent needs to update. In this case, the parent is already adding
468	// itself to the scene via [addToScene], and so after it's done, its
469	// `set engineLayer` is called and it clears the `_needsAddToScene` flag.
470	//
471	// 2. When rendering an interior layer (e.g. `OffsetLayer.toImage`). In
472	// this case we call `addToScene` for one of the children but not the
473	// parent, i.e. we produce new engine layers for children but not for the
474	// parent. Here the children will mark the parent as needing
475	// `addToScene`, but the parent does not clear the flag until some future
476	// frame decides to render it, at which point the parent knows that it
477	// cannot retain its engine layer and will call `addToScene` again.
478	if (parent != `null` && !parent!.alwaysNeedsAddToScene) {
479	parent!.markNeedsAddToScene();
480	}
481	}
482	}
483	ui.EngineLayer? _engineLayer;
484
485	/// Traverses the layer subtree starting from this layer and determines whether it needs [addToScene].
486	///
487	/// A layer needs [addToScene] if any of the following is true:
488	///
489	/// - [alwaysNeedsAddToScene] is true.
490	/// - [markNeedsAddToScene] has been called.
491	/// - Any of its descendants need [addToScene].
492	///
493	/// [ContainerLayer] overrides this method to recursively call it on its children.
494	@protected
495	@visibleForTesting
496	void updateSubtreeNeedsAddToScene() {
497	assert(!_debugMutationsLocked);
498	_needsAddToScene = _needsAddToScene \|\| alwaysNeedsAddToScene;
499	}
500
501	/// The owner for this layer (null if unattached).
502	///
503	/// The entire layer tree that this layer belongs to will have the same owner.
504	///
505	/// Typically the owner is a [RenderView].
506	Object? get owner => _owner;
507	Object? _owner;
508
509	/// Whether the layer tree containing this layer is attached to an owner.
510	///
511	/// This becomes true during the call to [attach].
512	///
513	/// This becomes false during the call to [detach].
514	bool get attached => _owner != `null`;
515
516	/// Mark this layer as attached to the given owner.
517	///
518	/// Typically called only from the [parent]'s [attach] method, and by the
519	/// [owner] to mark the root of a tree as attached.
520	///
521	/// Subclasses with children should override this method to
522	/// [attach] all their children to the same [owner]
523	/// after calling the inherited method, as in `super.attach(owner)`.
524	@mustCallSuper
525	void attach(covariant Object owner) {
526	assert(_owner == `null`);
527	_owner = owner;
528	}
529
530	/// Mark this layer as detached from its owner.
531	///
532	/// Typically called only from the [parent]'s [detach], and by the [owner] to
533	/// mark the root of a tree as detached.
534	///
535	/// Subclasses with children should override this method to
536	/// [detach] all their children after calling the inherited method,
537	/// as in `super.detach()`.
538	@mustCallSuper
539	void detach() {
540	assert(_owner != `null`);
541	_owner = `null`;
542	assert(parent == `null` \|\| attached == parent!.attached);
543	}
544
545	/// The depth of this layer in the layer tree.
546	///
547	/// The depth of nodes in a tree monotonically increases as you traverse down
548	/// the tree. There's no guarantee regarding depth between siblings.
549	///
550	/// The depth is used to ensure that nodes are processed in depth order.
551	int get depth => _depth;
552	int _depth = `0`;
553
554	/// Adjust the [depth] of this node's children, if any.
555	///
556	/// Override this method in subclasses with child nodes to call
557	/// [ContainerLayer.redepthChild] for each child. Do not call this method
558	/// directly.
559	@protected
560	void redepthChildren() {
561	// ContainerLayer provides an implementation since its the only one that
562	// can actually have children.
563	}
564
565	/// This layer's next sibling in the parent layer's child list.
566	Layer? get nextSibling => _nextSibling;
567	Layer? _nextSibling;
568
569	/// This layer's previous sibling in the parent layer's child list.
570	Layer? get previousSibling => _previousSibling;
571	Layer? _previousSibling;
572
573	/// Removes this layer from its parent layer's child list.
574	///
575	/// This has no effect if the layer's parent is already null.
576	@mustCallSuper
577	void remove() {
578	assert(!_debugMutationsLocked);
579	parent?._removeChild(this);
580	}
581
582	/// Search this layer and its subtree for annotations of type `S` at the
583	/// location described by `localPosition`.
584	///
585	/// This method is called by the default implementation of [find] and
586	/// [findAllAnnotations]. Override this method to customize how the layer
587	/// should search for annotations, or if the layer has its own annotations to
588	/// add.
589	///
590	/// The default implementation always returns `false`, which means neither
591	/// the layer nor its children has annotations, and the annotation search
592	/// is not absorbed either (see below for explanation).
593	///
594	/// ## About layer annotations
595	///
596	/// {@template flutter.rendering.Layer.findAnnotations.aboutAnnotations}
597	/// An annotation is an optional object of any type that can be carried with a
598	/// layer. An annotation can be found at a location as long as the owner layer
599	/// contains the location and is walked to.
600	///
601	/// The annotations are searched by first visiting each child recursively,
602	/// then this layer, resulting in an order from visually front to back.
603	/// Annotations must meet the given restrictions, such as type and position.
604	///
605	/// The common way for a value to be found here is by pushing an
606	/// [AnnotatedRegionLayer] into the layer tree, or by adding the desired
607	/// annotation by overriding [findAnnotations].
608	/// {@endtemplate}
609	///
610	/// ## Parameters and return value
611	///
612	/// The [result] parameter is where the method outputs the resulting
613	/// annotations. New annotations found during the walk are added to the tail.
614	///
615	/// The [onlyFirst] parameter indicates that, if true, the search will stop
616	/// when it finds the first qualified annotation; otherwise, it will walk the
617	/// entire subtree.
618	///
619	/// The return value indicates the opacity of this layer and its subtree at
620	/// this position. If it returns true, then this layer's parent should skip
621	/// the children behind this layer. In other words, it is opaque to this type
622	/// of annotation and has absorbed the search so that its siblings behind it
623	/// are not aware of the search. If the return value is false, then the parent
624	/// might continue with other siblings.
625	///
626	/// The return value does not affect whether the parent adds its own
627	/// annotations; in other words, if a layer is supposed to add an annotation,
628	/// it will always add it even if its children are opaque to this type of
629	/// annotation. However, the opacity that the parents return might be affected
630	/// by their children, hence making all of its ancestors opaque to this type
631	/// of annotation.
632	@protected
633	bool findAnnotations<S extends Object>(
634	AnnotationResult<S> result,
635	Offset localPosition, {
636	required bool onlyFirst,
637	}) {
638	return `false`;
639	}
640
641	/// Search this layer and its subtree for the first annotation of type `S`
642	/// under the point described by `localPosition`.
643	///
644	/// Returns null if no matching annotations are found.
645	///
646	/// By default this method calls [findAnnotations] with `onlyFirst:
647	/// true` and returns the annotation of the first result. Prefer overriding
648	/// [findAnnotations] instead of this method, because during an annotation
649	/// search, only [findAnnotations] is recursively called, while custom
650	/// behavior in this method is ignored.
651	///
652	/// ## About layer annotations
653	///
654	/// {@macro flutter.rendering.Layer.findAnnotations.aboutAnnotations}
655	///
656	/// See also:
657	///
658	/// [findAllAnnotations], which is similar but returns all annotations found*
659	/// at the given position.
660	/// [AnnotatedRegionLayer], for placing values in the layer tree.*
661	S? find<S extends Object>(Offset localPosition) {
662	final AnnotationResult<S> result = AnnotationResult<S>();
663	findAnnotations<S>(result, localPosition, onlyFirst: `true`);
664	return result.entries.isEmpty ? `null` : result.entries.first.annotation;
665	}
666
667	/// Search this layer and its subtree for all annotations of type `S` under
668	/// the point described by `localPosition`.
669	///
670	/// Returns a result with empty entries if no matching annotations are found.
671	///
672	/// By default this method calls [findAnnotations] with `onlyFirst:
673	/// false` and returns the annotations of its result. Prefer overriding
674	/// [findAnnotations] instead of this method, because during an annotation
675	/// search, only [findAnnotations] is recursively called, while custom
676	/// behavior in this method is ignored.
677	///
678	/// ## About layer annotations
679	///
680	/// {@macro flutter.rendering.Layer.findAnnotations.aboutAnnotations}
681	///
682	/// See also:
683	///
684	/// [find], which is similar but returns the first annotation found at the*
685	/// given position.
686	/// [AnnotatedRegionLayer], for placing values in the layer tree.*
687	AnnotationResult<S> findAllAnnotations<S extends Object>(Offset localPosition) {
688	final AnnotationResult<S> result = AnnotationResult<S>();
689	findAnnotations<S>(result, localPosition, onlyFirst: `false`);
690	return result;
691	}
692
693	/// Override this method to upload this layer to the engine.
694	@protected
695	void addToScene(ui.SceneBuilder builder);
696
697	void _addToSceneWithRetainedRendering(ui.SceneBuilder builder) {
698	assert(!_debugMutationsLocked);
699	// There can't be a loop by adding a retained layer subtree whose
700	// _needsAddToScene is false.
701	//
702	// Proof by contradiction:
703	//
704	// If we introduce a loop, this retained layer must be appended to one of
705	// its descendant layers, say A. That means the child structure of A has
706	// changed so A's _needsAddToScene is true. This contradicts
707	// _needsAddToScene being false.
708	if (!_needsAddToScene && _engineLayer != `null`) {
709	builder.addRetained(_engineLayer!);
710	return;
711	}
712	addToScene(builder);
713	// Clearing the flag _after_ calling `addToScene`, not _before_. This is
714	// because `addToScene` calls children's `addToScene` methods, which may
715	// mark this layer as dirty.
716	_needsAddToScene = `false`;
717	}
718
719	/// The object responsible for creating this layer.
720	///
721	/// Defaults to the value of [RenderObject.debugCreator] for the render object
722	/// that created this layer. Used in debug messages.
723	Object? debugCreator;
724
725	@override
726	String toStringShort() => '${super.toStringShort()}${ owner == `null` ? " DETACHED" : ""}';
727
728	@override
729	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
730	super.debugFillProperties(properties);
731	properties.add(DiagnosticsProperty<Object>('owner', owner, level: parent != `null` ? DiagnosticLevel.hidden : DiagnosticLevel.info, defaultValue: `null`));
732	properties.add(DiagnosticsProperty<Object?>('creator', debugCreator, defaultValue: `null`, level: DiagnosticLevel.debug));
733	if (_engineLayer != `null`) {
734	properties.add(DiagnosticsProperty<String>('engine layer', describeIdentity(_engineLayer)));
735	}
736	properties.add(DiagnosticsProperty<int>('handles', debugHandleCount));
737	}
738	}
739
740	/// A handle to prevent a [Layer]'s platform graphics resources from being
741	/// disposed.
742	///
743	/// [Layer] objects retain native resources such as [EngineLayer]s and [Picture]
744	/// objects. These objects may in turn retain large chunks of texture memory,
745	/// either directly or indirectly.
746	///
747	/// The layer's native resources must be retained as long as there is some
748	/// object that can add it to a scene. Typically, this is either its
749	/// [Layer.parent] or an undisposed [RenderObject] that will append it to a
750	/// [ContainerLayer]. Layers automatically hold a handle to their children, and
751	/// RenderObjects automatically hold a handle to their [RenderObject.layer] as
752	/// well as any [PictureLayer]s that they paint into using the
753	/// [PaintingContext.canvas]. A layer automatically releases its resources once
754	/// at least one handle has been acquired and all handles have been disposed.
755	/// [RenderObject]s that create additional layer objects must manually manage
756	/// the handles for that layer similarly to the implementation of
757	/// [RenderObject.layer].
758	///
759	/// A handle is automatically managed for [RenderObject.layer].
760	///
761	/// If a [RenderObject] creates layers in addition to its [RenderObject.layer]
762	/// and it intends to reuse those layers separately from [RenderObject.layer],
763	/// it must create a handle to that layer and dispose of it when the layer is
764	/// no longer needed. For example, if it re-creates or nulls out an existing
765	/// layer in [RenderObject.paint], it should dispose of the handle to the
766	/// old layer. It should also dispose of any layer handles it holds in
767	/// [RenderObject.dispose].
768	class LayerHandle<T extends Layer> {
769	/// Create a new layer handle, optionally referencing a [Layer].
770	LayerHandle([this._layer]) {
771	if (_layer != `null`) {
772	_layer!._refCount += `1`;
773	}
774	}
775
776	T? _layer;
777
778	/// The [Layer] whose resources this object keeps alive.
779	///
780	/// Setting a new value or null will dispose the previously held layer if
781	/// there are no other open handles to that layer.
782	T? get layer => _layer;
783
784	set layer(T? layer) {
785	assert(
786	layer?.debugDisposed != `true`,
787	'Attempted to create a handle to an already disposed layer: $layer.',
788	);
789	if (identical(layer, _layer)) {
790	return;
791	}
792	_layer?._unref();
793	_layer = layer;
794	if (_layer != `null`) {
795	_layer!._refCount += `1`;
796	}
797	}
798
799	@override
800	String toString() => 'LayerHandle(${_layer != `null` ? _layer.toString() : 'DISPOSED'})';
801	}
802
803	/// A composited layer containing a [Picture].
804	///
805	/// Picture layers are always leaves in the layer tree. They are also
806	/// responsible for disposing of the [Picture] object they hold. This is
807	/// typically done when their parent and all [RenderObject]s that participated
808	/// in painting the picture have been disposed.
809	class PictureLayer extends Layer {
810	/// Creates a leaf layer for the layer tree.
811	PictureLayer(this.canvasBounds);
812
813	/// The bounds that were used for the canvas that drew this layer's [picture].
814	///
815	/// This is purely advisory. It is included in the information dumped with
816	/// [debugDumpLayerTree] (which can be triggered by pressing "L" when using
817	/// "flutter run" at the console), which can help debug why certain drawing
818	/// commands are being culled.
819	final Rect canvasBounds;
820
821	/// The picture recorded for this layer.
822	///
823	/// The picture's coordinate system matches this layer's coordinate system.
824	///
825	/// The scene must be explicitly recomposited after this property is changed
826	/// (as described at [Layer]).
827	ui.Picture? get picture => _picture;
828	ui.Picture? _picture;
829	set picture(ui.Picture? picture) {
830	assert(!_debugDisposed);
831	markNeedsAddToScene();
832	_picture?.dispose();
833	_picture = picture;
834	}
835
836	/// Hints that the painting in this layer is complex and would benefit from
837	/// caching.
838	///
839	/// If this hint is not set, the compositor will apply its own heuristics to
840	/// decide whether the this layer is complex enough to benefit from caching.
841	///
842	/// The scene must be explicitly recomposited after this property is changed
843	/// (as described at [Layer]).
844	bool get isComplexHint => _isComplexHint;
845	bool _isComplexHint = `false`;
846	set isComplexHint(bool value) {
847	if (value != _isComplexHint) {
848	_isComplexHint = value;
849	markNeedsAddToScene();
850	}
851	}
852
853	/// Hints that the painting in this layer is likely to change next frame.
854	///
855	/// This hint tells the compositor not to cache this layer because the cache
856	/// will not be used in the future. If this hint is not set, the compositor
857	/// will apply its own heuristics to decide whether this layer is likely to be
858	/// reused in the future.
859	///
860	/// The scene must be explicitly recomposited after this property is changed
861	/// (as described at [Layer]).
862	bool get willChangeHint => _willChangeHint;
863	bool _willChangeHint = `false`;
864	set willChangeHint(bool value) {
865	if (value != _willChangeHint) {
866	_willChangeHint = value;
867	markNeedsAddToScene();
868	}
869	}
870
871	@override
872	void dispose() {
873	picture = `null`; // Will dispose _picture.
874	super.dispose();
875	}
876
877	@override
878	void addToScene(ui.SceneBuilder builder) {
879	assert(picture != `null`);
880	builder.addPicture(Offset.zero, picture!, isComplexHint: isComplexHint, willChangeHint: willChangeHint);
881	}
882
883	@override
884	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
885	super.debugFillProperties(properties);
886	properties.add(DiagnosticsProperty<Rect>('paint bounds', canvasBounds));
887	properties.add(DiagnosticsProperty<String>('picture', describeIdentity(_picture)));
888	properties.add(DiagnosticsProperty<String>(
889	'raster cache hints',
890	'isComplex = $isComplexHint, willChange = $willChangeHint',
891	));
892	}
893
894	@override
895	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
896	return `false`;
897	}
898	}
899
900	/// A composited layer that maps a backend texture to a rectangle.
901	///
902	/// Backend textures are images that can be applied (mapped) to an area of the
903	/// Flutter view. They are created, managed, and updated using a
904	/// platform-specific texture registry. This is typically done by a plugin
905	/// that integrates with host platform video player, camera, or OpenGL APIs,
906	/// or similar image sources.
907	///
908	/// A texture layer refers to its backend texture using an integer ID. Texture
909	/// IDs are obtained from the texture registry and are scoped to the Flutter
910	/// view. Texture IDs may be reused after deregistration, at the discretion
911	/// of the registry. The use of texture IDs currently unknown to the registry
912	/// will silently result in a blank rectangle.
913	///
914	/// Once inserted into the layer tree, texture layers are repainted autonomously
915	/// as dictated by the backend (e.g. on arrival of a video frame). Such
916	/// repainting generally does not involve executing Dart code.
917	///
918	/// Texture layers are always leaves in the layer tree.
919	///
920	/// See also:
921	///
922	/// [TextureRegistry](/javadoc/io/flutter/view/TextureRegistry.html)*
923	/// for how to create and manage backend textures on Android.
924	/// [TextureRegistry Protocol](/ios-embedder/protocol_flutter_texture_registry-p.html)*
925	/// for how to create and manage backend textures on iOS.
926	class TextureLayer extends Layer {
927	/// Creates a texture layer bounded by [rect] and with backend texture
928	/// identified by [textureId], if [freeze] is true new texture frames will not be
929	/// populated to the texture, and use [filterQuality] to set layer's [FilterQuality].
930	TextureLayer({
931	required this.rect,
932	required this.textureId,
933	this.freeze = `false`,
934	this.filterQuality = ui.FilterQuality.low,
935	});
936
937	/// Bounding rectangle of this layer.
938	final Rect rect;
939
940	/// The identity of the backend texture.
941	final int textureId;
942
943	/// When true the texture will not be updated with new frames.
944	///
945	/// This is used for resizing embedded Android views: when resizing there
946	/// is a short period during which the framework cannot tell if the newest
947	/// texture frame has the previous or new size; to work around this, the
948	/// framework "freezes" the texture just before resizing the Android view and
949	/// un-freezes it when it is certain that a frame with the new size is ready.
950	final bool freeze;
951
952	/// {@macro flutter.widgets.Texture.filterQuality}
953	final ui.FilterQuality filterQuality;
954
955	@override
956	void addToScene(ui.SceneBuilder builder) {
957	builder.addTexture(
958	textureId,
959	offset: rect.topLeft,
960	width: rect.width,
961	height: rect.height,
962	freeze: freeze,
963	filterQuality: filterQuality,
964	);
965	}
966
967	@override
968	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
969	return `false`;
970	}
971	}
972
973	/// A layer that shows an embedded [UIView](https://developer.apple.com/documentation/uikit/uiview)
974	/// on iOS.
975	class PlatformViewLayer extends Layer {
976	/// Creates a platform view layer.
977	PlatformViewLayer({
978	required this.rect,
979	required this.viewId,
980	});
981
982	/// Bounding rectangle of this layer in the global coordinate space.
983	final Rect rect;
984
985	/// The unique identifier of the UIView displayed on this layer.
986	///
987	/// A UIView with this identifier must have been created by [PlatformViewsService.initUiKitView].
988	final int viewId;
989
990	@override
991	bool supportsRasterization() {
992	return `false`;
993	}
994
995	@override
996	void addToScene(ui.SceneBuilder builder) {
997	builder.addPlatformView(
998	viewId,
999	offset: rect.topLeft,
1000	width: rect.width,
1001	height: rect.height,
1002	);
1003	}
1004	}
1005
1006	/// A layer that indicates to the compositor that it should display
1007	/// certain performance statistics within it.
1008	///
1009	/// Performance overlay layers are always leaves in the layer tree.
1010	class PerformanceOverlayLayer extends Layer {
1011	/// Creates a layer that displays a performance overlay.
1012	PerformanceOverlayLayer({
1013	required Rect overlayRect,
1014	required this.optionsMask,
1015	required this.rasterizerThreshold,
1016	required this.checkerboardRasterCacheImages,
1017	required this.checkerboardOffscreenLayers,
1018	}) : _overlayRect = overlayRect;
1019
1020	/// The rectangle in this layer's coordinate system that the overlay should occupy.
1021	///
1022	/// The scene must be explicitly recomposited after this property is changed
1023	/// (as described at [Layer]).
1024	Rect get overlayRect => _overlayRect;
1025	Rect _overlayRect;
1026	set overlayRect(Rect value) {
1027	if (value != _overlayRect) {
1028	_overlayRect = value;
1029	markNeedsAddToScene();
1030	}
1031	}
1032
1033	/// The mask is created by shifting 1 by the index of the specific
1034	/// [PerformanceOverlayOption] to enable.
1035	final int optionsMask;
1036
1037	/// The rasterizer threshold is an integer specifying the number of frame
1038	/// intervals that the rasterizer must miss before it decides that the frame
1039	/// is suitable for capturing an SkPicture trace for further analysis.
1040	final int rasterizerThreshold;
1041
1042	/// Whether the raster cache should checkerboard cached entries.
1043	///
1044	/// The compositor can sometimes decide to cache certain portions of the
1045	/// widget hierarchy. Such portions typically don't change often from frame to
1046	/// frame and are expensive to render. This can speed up overall rendering. However,
1047	/// there is certain upfront cost to constructing these cache entries. And, if
1048	/// the cache entries are not used very often, this cost may not be worth the
1049	/// speedup in rendering of subsequent frames. If the developer wants to be certain
1050	/// that populating the raster cache is not causing stutters, this option can be
1051	/// set. Depending on the observations made, hints can be provided to the compositor
1052	/// that aid it in making better decisions about caching.
1053	final bool checkerboardRasterCacheImages;
1054
1055	/// Whether the compositor should checkerboard layers that are rendered to offscreen
1056	/// bitmaps. This can be useful for debugging rendering performance.
1057	///
1058	/// Render target switches are caused by using opacity layers (via a [FadeTransition] or
1059	/// [Opacity] widget), clips, shader mask layers, etc. Selecting a new render target
1060	/// and merging it with the rest of the scene has a performance cost. This can sometimes
1061	/// be avoided by using equivalent widgets that do not require these layers (for example,
1062	/// replacing an [Opacity] widget with an [widgets.Image] using a [BlendMode]).
1063	final bool checkerboardOffscreenLayers;
1064
1065	@override
1066	void addToScene(ui.SceneBuilder builder) {
1067	builder.addPerformanceOverlay(optionsMask, overlayRect);
1068	builder.setRasterizerTracingThreshold(rasterizerThreshold);
1069	builder.setCheckerboardRasterCacheImages(checkerboardRasterCacheImages);
1070	builder.setCheckerboardOffscreenLayers(checkerboardOffscreenLayers);
1071	}
1072
1073	@override
1074	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
1075	return `false`;
1076	}
1077	}
1078
1079	/// The signature of the callback added in [Layer.addCompositionCallback].
1080	typedef CompositionCallback = void Function(Layer layer);
1081
1082	/// A composited layer that has a list of children.
1083	///
1084	/// A [ContainerLayer] instance merely takes a list of children and inserts them
1085	/// into the composited rendering in order. There are subclasses of
1086	/// [ContainerLayer] which apply more elaborate effects in the process.
1087	class ContainerLayer extends Layer {
1088	@override
1089	void _fireCompositionCallbacks({required bool includeChildren}) {
1090	super._fireCompositionCallbacks(includeChildren: includeChildren);
1091	if (!includeChildren) {
1092	return;
1093	}
1094	Layer? child = firstChild;
1095	while (child != `null`) {
1096	child._fireCompositionCallbacks(includeChildren: includeChildren);
1097	child = child.nextSibling;
1098	}
1099	}
1100
1101	/// The first composited layer in this layer's child list.
1102	Layer? get firstChild => _firstChild;
1103	Layer? _firstChild;
1104
1105	/// The last composited layer in this layer's child list.
1106	Layer? get lastChild => _lastChild;
1107	Layer? _lastChild;
1108
1109	/// Returns whether this layer has at least one child layer.
1110	bool get hasChildren => _firstChild != `null`;
1111
1112	@override
1113	bool supportsRasterization() {
1114	for (Layer? child = lastChild; child != `null`; child = child.previousSibling) {
1115	if (!child.supportsRasterization()) {
1116	return `false`;
1117	}
1118	}
1119	return `true`;
1120	}
1121
1122	/// Consider this layer as the root and build a scene (a tree of layers)
1123	/// in the engine.
1124	// The reason this method is in the `ContainerLayer` class rather than
1125	// `PipelineOwner` or other singleton level is because this method can be used
1126	// both to render the whole layer tree (e.g. a normal application frame) and
1127	// to render a subtree (e.g. `OffsetLayer.toImage`).
1128	ui.Scene buildScene(ui.SceneBuilder builder) {
1129	updateSubtreeNeedsAddToScene();
1130	addToScene(builder);
1131	if (subtreeHasCompositionCallbacks) {
1132	_fireCompositionCallbacks(includeChildren: `true`);
1133	}
1134	// Clearing the flag _after_ calling `addToScene`, not _before_. This is
1135	// because `addToScene` calls children's `addToScene` methods, which may
1136	// mark this layer as dirty.
1137	_needsAddToScene = `false`;
1138	final ui.Scene scene = builder.build();
1139	return scene;
1140	}
1141
1142	bool _debugUltimatePreviousSiblingOf(Layer child, { Layer? equals }) {
1143	assert(child.attached == attached);
1144	while (child.previousSibling != `null`) {
1145	assert(child.previousSibling != child);
1146	child = child.previousSibling!;
1147	assert(child.attached == attached);
1148	}
1149	return child == equals;
1150	}
1151
1152	bool _debugUltimateNextSiblingOf(Layer child, { Layer? equals }) {
1153	assert(child.attached == attached);
1154	while (child._nextSibling != `null`) {
1155	assert(child._nextSibling != child);
1156	child = child._nextSibling!;
1157	assert(child.attached == attached);
1158	}
1159	return child == equals;
1160	}
1161
1162	@override
1163	void dispose() {
1164	removeAllChildren();
1165	_callbacks.clear();
1166	super.dispose();
1167	}
1168
1169	@override
1170	void updateSubtreeNeedsAddToScene() {
1171	super.updateSubtreeNeedsAddToScene();
1172	Layer? child = firstChild;
1173	while (child != `null`) {
1174	child.updateSubtreeNeedsAddToScene();
1175	_needsAddToScene = _needsAddToScene \|\| child._needsAddToScene;
1176	child = child.nextSibling;
1177	}
1178	}
1179
1180	@override
1181	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
1182	for (Layer? child = lastChild; child != `null`; child = child.previousSibling) {
1183	final bool isAbsorbed = child.findAnnotations<S>(result, localPosition, onlyFirst: onlyFirst);
1184	if (isAbsorbed) {
1185	return `true`;
1186	}
1187	if (onlyFirst && result.entries.isNotEmpty) {
1188	return isAbsorbed;
1189	}
1190	}
1191	return `false`;
1192	}
1193
1194	@override
1195	void attach(Object owner) {
1196	assert(!_debugMutationsLocked);
1197	super.attach(owner);
1198	Layer? child = firstChild;
1199	while (child != `null`) {
1200	child.attach(owner);
1201	child = child.nextSibling;
1202	}
1203	}
1204
1205	@override
1206	void detach() {
1207	assert(!_debugMutationsLocked);
1208	super.detach();
1209	Layer? child = firstChild;
1210	while (child != `null`) {
1211	child.detach();
1212	child = child.nextSibling;
1213	}
1214	// Detach indicates that we may never be composited again. Clients
1215	// interested in observing composition need to get an update here because
1216	// they might otherwise never get another one even though the layer is no
1217	// longer visible.
1218	//
1219	// Children fired them already in child.detach().
1220	_fireCompositionCallbacks(includeChildren: `false`);
1221	}
1222
1223	/// Adds the given layer to the end of this layer's child list.
1224	void append(Layer child) {
1225	assert(!_debugMutationsLocked);
1226	assert(child != this);
1227	assert(child != firstChild);
1228	assert(child != lastChild);
1229	assert(child.parent == `null`);
1230	assert(!child.attached);
1231	assert(child.nextSibling == `null`);
1232	assert(child.previousSibling == `null`);
1233	assert(child._parentHandle.layer == `null`);
1234	assert(() {
1235	Layer node = this;
1236	while (node.parent != `null`) {
1237	node = node.parent!;
1238	}
1239	assert(node != child); // indicates we are about to create a cycle
1240	return `true`;
1241	}());
1242	_adoptChild(child);
1243	child._previousSibling = lastChild;
1244	if (lastChild != `null`) {
1245	lastChild!._nextSibling = child;
1246	}
1247	_lastChild = child;
1248	_firstChild ??= child;
1249	child._parentHandle.layer = child;
1250	assert(child.attached == attached);
1251	}
1252
1253	void _adoptChild(Layer child) {
1254	assert(!_debugMutationsLocked);
1255	if (!alwaysNeedsAddToScene) {
1256	markNeedsAddToScene();
1257	}
1258	if (child._compositionCallbackCount != `0`) {
1259	_updateSubtreeCompositionObserverCount(child._compositionCallbackCount);
1260	}
1261	assert(child._parent == `null`);
1262	assert(() {
1263	Layer node = this;
1264	while (node.parent != `null`) {
1265	node = node.parent!;
1266	}
1267	assert(node != child); // indicates we are about to create a cycle
1268	return `true`;
1269	}());
1270	child._parent = this;
1271	if (attached) {
1272	child.attach(_owner!);
1273	}
1274	redepthChild(child);
1275	}
1276
1277	@override
1278	void redepthChildren() {
1279	Layer? child = firstChild;
1280	while (child != `null`) {
1281	redepthChild(child);
1282	child = child.nextSibling;
1283	}
1284	}
1285
1286	/// Adjust the [depth] of the given [child] to be greater than this node's own
1287	/// [depth].
1288	///
1289	/// Only call this method from overrides of [redepthChildren].
1290	@protected
1291	void redepthChild(Layer child) {
1292	assert(child.owner == owner);
1293	if (child._depth <= _depth) {
1294	child._depth = _depth + `1`;
1295	child.redepthChildren();
1296	}
1297	}
1298
1299	// Implementation of [Layer.remove].
1300	void _removeChild(Layer child) {
1301	assert(child.parent == this);
1302	assert(child.attached == attached);
1303	assert(_debugUltimatePreviousSiblingOf(child, equals: firstChild));
1304	assert(_debugUltimateNextSiblingOf(child, equals: lastChild));
1305	assert(child._parentHandle.layer != `null`);
1306	if (child._previousSibling == `null`) {
1307	assert(_firstChild == child);
1308	_firstChild = child._nextSibling;
1309	} else {
1310	child._previousSibling!._nextSibling = child.nextSibling;
1311	}
1312	if (child._nextSibling == `null`) {
1313	assert(lastChild == child);
1314	_lastChild = child.previousSibling;
1315	} else {
1316	child.nextSibling!._previousSibling = child.previousSibling;
1317	}
1318	assert((firstChild == `null`) == (lastChild == `null`));
1319	assert(firstChild == `null` \|\| firstChild!.attached == attached);
1320	assert(lastChild == `null` \|\| lastChild!.attached == attached);
1321	assert(firstChild == `null` \|\| _debugUltimateNextSiblingOf(firstChild!, equals: lastChild));
1322	assert(lastChild == `null` \|\| _debugUltimatePreviousSiblingOf(lastChild!, equals: firstChild));
1323	child._previousSibling = `null`;
1324	child._nextSibling = `null`;
1325	_dropChild(child);
1326	child._parentHandle.layer = `null`;
1327	assert(!child.attached);
1328	}
1329
1330	void _dropChild(Layer child) {
1331	assert(!_debugMutationsLocked);
1332	if (!alwaysNeedsAddToScene) {
1333	markNeedsAddToScene();
1334	}
1335	if (child._compositionCallbackCount != `0`) {
1336	_updateSubtreeCompositionObserverCount(-child._compositionCallbackCount);
1337	}
1338	assert(child._parent == this);
1339	assert(child.attached == attached);
1340	child._parent = `null`;
1341	if (attached) {
1342	child.detach();
1343	}
1344	}
1345
1346	/// Removes all of this layer's children from its child list.
1347	void removeAllChildren() {
1348	assert(!_debugMutationsLocked);
1349	Layer? child = firstChild;
1350	while (child != `null`) {
1351	final Layer? next = child.nextSibling;
1352	child._previousSibling = `null`;
1353	child._nextSibling = `null`;
1354	assert(child.attached == attached);
1355	_dropChild(child);
1356	child._parentHandle.layer = `null`;
1357	child = next;
1358	}
1359	_firstChild = `null`;
1360	_lastChild = `null`;
1361	}
1362
1363	@override
1364	void addToScene(ui.SceneBuilder builder) {
1365	addChildrenToScene(builder);
1366	}
1367
1368	/// Uploads all of this layer's children to the engine.
1369	///
1370	/// This method is typically used by [addToScene] to insert the children into
1371	/// the scene. Subclasses of [ContainerLayer] typically override [addToScene]
1372	/// to apply effects to the scene using the [SceneBuilder] API, then insert
1373	/// their children using [addChildrenToScene], then reverse the aforementioned
1374	/// effects before returning from [addToScene].
1375	void addChildrenToScene(ui.SceneBuilder builder) {
1376	Layer? child = firstChild;
1377	while (child != `null`) {
1378	child._addToSceneWithRetainedRendering(builder);
1379	child = child.nextSibling;
1380	}
1381	}
1382
1383	/// Applies the transform that would be applied when compositing the given
1384	/// child to the given matrix.
1385	///
1386	/// Specifically, this should apply the transform that is applied to child's
1387	/// _origin_. When using [applyTransform] with a chain of layers, results will
1388	/// be unreliable unless the deepest layer in the chain collapses the
1389	/// `layerOffset` in [addToScene] to zero, meaning that it passes
1390	/// [Offset.zero] to its children, and bakes any incoming `layerOffset` into
1391	/// the [SceneBuilder] as (for instance) a transform (which is then also
1392	/// included in the transformation applied by [applyTransform]).
1393	///
1394	/// For example, if [addToScene] applies the `layerOffset` and then
1395	/// passes [Offset.zero] to the children, then it should be included in the
1396	/// transform applied here, whereas if [addToScene] just passes the
1397	/// `layerOffset` to the child, then it should not be included in the
1398	/// transform applied here.
1399	///
1400	/// This method is only valid immediately after [addToScene] has been called,
1401	/// before any of the properties have been changed.
1402	///
1403	/// The default implementation does nothing, since [ContainerLayer], by
1404	/// default, composites its children at the origin of the [ContainerLayer]
1405	/// itself.
1406	///
1407	/// The `child` argument should generally not be null, since in principle a
1408	/// layer could transform each child independently. However, certain layers
1409	/// may explicitly allow null as a value, for example if they know that they
1410	/// transform all their children identically.
1411	///
1412	/// Used by [FollowerLayer] to transform its child to a [LeaderLayer]'s
1413	/// position.
1414	void applyTransform(Layer? child, Matrix4 transform) {
1415	assert(child != `null`);
1416	}
1417
1418	/// Returns the descendants of this layer in depth first order.
1419	@visibleForTesting
1420	List<Layer> depthFirstIterateChildren() {
1421	if (firstChild == `null`) {
1422	return <Layer>[];
1423	}
1424	final List<Layer> children = <Layer>[];
1425	Layer? child = firstChild;
1426	while (child != `null`) {
1427	children.add(child);
1428	if (child is ContainerLayer) {
1429	children.addAll(child.depthFirstIterateChildren());
1430	}
1431	child = child.nextSibling;
1432	}
1433	return children;
1434	}
1435
1436	@override
1437	List<DiagnosticsNode> debugDescribeChildren() {
1438	final List<DiagnosticsNode> children = <DiagnosticsNode>[];
1439	if (firstChild == `null`) {
1440	return children;
1441	}
1442	Layer? child = firstChild;
1443	int count = `1`;
1444	while (`true`) {
1445	children.add(child!.toDiagnosticsNode(name: 'child $count'));
1446	if (child == lastChild) {
1447	break;
1448	}
1449	count += `1`;
1450	child = child.nextSibling;
1451	}
1452	return children;
1453	}
1454	}
1455
1456	/// A layer that is displayed at an offset from its parent layer.
1457	///
1458	/// Offset layers are key to efficient repainting because they are created by
1459	/// repaint boundaries in the [RenderObject] tree (see
1460	/// [RenderObject.isRepaintBoundary]). When a render object that is a repaint
1461	/// boundary is asked to paint at given offset in a [PaintingContext], the
1462	/// render object first checks whether it needs to repaint itself. If not, it
1463	/// reuses its existing [OffsetLayer] (and its entire subtree) by mutating its
1464	/// [offset] property, cutting off the paint walk.
1465	class OffsetLayer extends ContainerLayer {
1466	/// Creates an offset layer.
1467	///
1468	/// By default, [offset] is zero. It must be non-null before the compositing
1469	/// phase of the pipeline.
1470	OffsetLayer({ Offset offset = Offset.zero }) : _offset = offset;
1471
1472	/// Offset from parent in the parent's coordinate system.
1473	///
1474	/// The scene must be explicitly recomposited after this property is changed
1475	/// (as described at [Layer]).
1476	///
1477	/// The [offset] property must be non-null before the compositing phase of the
1478	/// pipeline.
1479	Offset get offset => _offset;
1480	Offset _offset;
1481	set offset(Offset value) {
1482	if (value != _offset) {
1483	markNeedsAddToScene();
1484	}
1485	_offset = value;
1486	}
1487
1488	@override
1489	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
1490	return super.findAnnotations<S>(result, localPosition - offset, onlyFirst: onlyFirst);
1491	}
1492
1493	@override
1494	void applyTransform(Layer? child, Matrix4 transform) {
1495	assert(child != `null`);
1496	transform.translate(offset.dx, offset.dy);
1497	}
1498
1499	@override
1500	void addToScene(ui.SceneBuilder builder) {
1501	// Skia has a fast path for concatenating scale/translation only matrices.
1502	// Hence pushing a translation-only transform layer should be fast. For
1503	// retained rendering, we don't want to push the offset down to each leaf
1504	// node. Otherwise, changing an offset layer on the very high level could
1505	// cascade the change to too many leaves.
1506	engineLayer = builder.pushOffset(
1507	offset.dx,
1508	offset.dy,
1509	oldLayer: _engineLayer as ui.OffsetEngineLayer?,
1510	);
1511	addChildrenToScene(builder);
1512	builder.pop();
1513	}
1514
1515	@override
1516	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
1517	super.debugFillProperties(properties);
1518	properties.add(DiagnosticsProperty<Offset>('offset', offset));
1519	}
1520
1521	ui.Scene _createSceneForImage(Rect bounds, { double pixelRatio = `1.0` }) {
1522	final ui.SceneBuilder builder = ui.SceneBuilder();
1523	final Matrix4 transform = Matrix4.diagonal3Values(pixelRatio, pixelRatio, `1`);
1524	transform.translate(-(bounds.left + offset.dx), -(bounds.top + offset.dy));
1525	builder.pushTransform(transform.storage);
1526	return buildScene(builder);
1527	}
1528
1529	/// Capture an image of the current state of this layer and its children.
1530	///
1531	/// The returned [ui.Image] has uncompressed raw RGBA bytes, will be offset
1532	/// by the top-left corner of [bounds], and have dimensions equal to the size
1533	/// of [bounds] multiplied by [pixelRatio].
1534	///
1535	/// The [pixelRatio] describes the scale between the logical pixels and the
1536	/// size of the output image. It is independent of the
1537	/// [dart:ui.FlutterView.devicePixelRatio] for the device, so specifying 1.0
1538	/// (the default) will give you a 1:1 mapping between logical pixels and the
1539	/// output pixels in the image.
1540	///
1541	/// This API functions like [toImageSync], except that it only returns after
1542	/// rasterization is complete.
1543	///
1544	/// See also:
1545	///
1546	/// [RenderRepaintBoundary.toImage] for a similar API at the render object level.*
1547	/// [dart:ui.Scene.toImage] for more information about the image returned.*
1548	Future<ui.Image> toImage(Rect bounds, { double pixelRatio = `1.0` }) async {
1549	final ui.Scene scene = _createSceneForImage(bounds, pixelRatio: pixelRatio);
1550
1551	try {
1552	// Size is rounded up to the next pixel to make sure we don't clip off
1553	// anything.
1554	return await scene.toImage(
1555	(pixelRatio * bounds.width).ceil(),
1556	(pixelRatio * bounds.height).ceil(),
1557	);
1558	} finally {
1559	scene.dispose();
1560	}
1561	}
1562
1563	/// Capture an image of the current state of this layer and its children.
1564	///
1565	/// The returned [ui.Image] has uncompressed raw RGBA bytes, will be offset
1566	/// by the top-left corner of [bounds], and have dimensions equal to the size
1567	/// of [bounds] multiplied by [pixelRatio].
1568	///
1569	/// The [pixelRatio] describes the scale between the logical pixels and the
1570	/// size of the output image. It is independent of the
1571	/// [dart:ui.FlutterView.devicePixelRatio] for the device, so specifying 1.0
1572	/// (the default) will give you a 1:1 mapping between logical pixels and the
1573	/// output pixels in the image.
1574	///
1575	/// This API functions like [toImage], except that rasterization begins eagerly
1576	/// on the raster thread and the image is returned before this is completed.
1577	///
1578	/// See also:
1579	///
1580	/// [RenderRepaintBoundary.toImage] for a similar API at the render object level.*
1581	/// [dart:ui.Scene.toImage] for more information about the image returned.*
1582	ui.Image toImageSync(Rect bounds, { double pixelRatio = `1.0` }) {
1583	final ui.Scene scene = _createSceneForImage(bounds, pixelRatio: pixelRatio);
1584
1585	try {
1586	// Size is rounded up to the next pixel to make sure we don't clip off
1587	// anything.
1588	return scene.toImageSync(
1589	(pixelRatio * bounds.width).ceil(),
1590	(pixelRatio * bounds.height).ceil(),
1591	);
1592	} finally {
1593	scene.dispose();
1594	}
1595	}
1596	}
1597
1598	/// A composite layer that clips its children using a rectangle.
1599	///
1600	/// When debugging, setting [debugDisableClipLayers] to true will cause this
1601	/// layer to be skipped (directly replaced by its children). This can be helpful
1602	/// to track down the cause of performance problems.
1603	class ClipRectLayer extends ContainerLayer {
1604	/// Creates a layer with a rectangular clip.
1605	///
1606	/// The [clipRect] argument must not be null before the compositing phase of
1607	/// the pipeline.
1608	///
1609	/// The [clipBehavior] argument must not be [Clip.none].
1610	ClipRectLayer({
1611	Rect? clipRect,
1612	Clip clipBehavior = Clip.hardEdge,
1613	}) : _clipRect = clipRect,
1614	_clipBehavior = clipBehavior,
1615	assert(clipBehavior != Clip.none);
1616
1617	/// The rectangle to clip in the parent's coordinate system.
1618	///
1619	/// The scene must be explicitly recomposited after this property is changed
1620	/// (as described at [Layer]).
1621	Rect? get clipRect => _clipRect;
1622	Rect? _clipRect;
1623	set clipRect(Rect? value) {
1624	if (value != _clipRect) {
1625	_clipRect = value;
1626	markNeedsAddToScene();
1627	}
1628	}
1629
1630	@override
1631	Rect? describeClipBounds() => clipRect;
1632
1633	/// {@template flutter.rendering.ClipRectLayer.clipBehavior}
1634	/// Controls how to clip.
1635	///
1636	/// Must not be set to null or [Clip.none].
1637	/// {@endtemplate}
1638	///
1639	/// Defaults to [Clip.hardEdge].
1640	Clip get clipBehavior => _clipBehavior;
1641	Clip _clipBehavior;
1642	set clipBehavior(Clip value) {
1643	assert(value != Clip.none);
1644	if (value != _clipBehavior) {
1645	_clipBehavior = value;
1646	markNeedsAddToScene();
1647	}
1648	}
1649
1650	@override
1651	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
1652	if (!clipRect!.contains(localPosition)) {
1653	return `false`;
1654	}
1655	return super.findAnnotations<S>(result, localPosition, onlyFirst: onlyFirst);
1656	}
1657
1658	@override
1659	void addToScene(ui.SceneBuilder builder) {
1660	assert(clipRect != `null`);
1661	bool enabled = `true`;
1662	assert(() {
1663	enabled = !debugDisableClipLayers;
1664	return `true`;
1665	}());
1666	if (enabled) {
1667	engineLayer = builder.pushClipRect(
1668	clipRect!,
1669	clipBehavior: clipBehavior,
1670	oldLayer: _engineLayer as ui.ClipRectEngineLayer?,
1671	);
1672	} else {
1673	engineLayer = `null`;
1674	}
1675	addChildrenToScene(builder);
1676	if (enabled) {
1677	builder.pop();
1678	}
1679	}
1680
1681	@override
1682	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
1683	super.debugFillProperties(properties);
1684	properties.add(DiagnosticsProperty<Rect>('clipRect', clipRect));
1685	properties.add(DiagnosticsProperty<Clip>('clipBehavior', clipBehavior));
1686	}
1687	}
1688
1689	/// A composite layer that clips its children using a rounded rectangle.
1690	///
1691	/// When debugging, setting [debugDisableClipLayers] to true will cause this
1692	/// layer to be skipped (directly replaced by its children). This can be helpful
1693	/// to track down the cause of performance problems.
1694	class ClipRRectLayer extends ContainerLayer {
1695	/// Creates a layer with a rounded-rectangular clip.
1696	///
1697	/// The [clipRRect] and [clipBehavior] properties must be non-null before the
1698	/// compositing phase of the pipeline.
1699	ClipRRectLayer({
1700	RRect? clipRRect,
1701	Clip clipBehavior = Clip.antiAlias,
1702	}) : _clipRRect = clipRRect,
1703	_clipBehavior = clipBehavior,
1704	assert(clipBehavior != Clip.none);
1705
1706	/// The rounded-rect to clip in the parent's coordinate system.
1707	///
1708	/// The scene must be explicitly recomposited after this property is changed
1709	/// (as described at [Layer]).
1710	RRect? get clipRRect => _clipRRect;
1711	RRect? _clipRRect;
1712	set clipRRect(RRect? value) {
1713	if (value != _clipRRect) {
1714	_clipRRect = value;
1715	markNeedsAddToScene();
1716	}
1717	}
1718
1719	@override
1720	Rect? describeClipBounds() => clipRRect?.outerRect;
1721
1722	/// {@macro flutter.rendering.ClipRectLayer.clipBehavior}
1723	///
1724	/// Defaults to [Clip.antiAlias].
1725	Clip get clipBehavior => _clipBehavior;
1726	Clip _clipBehavior;
1727	set clipBehavior(Clip value) {
1728	assert(value != Clip.none);
1729	if (value != _clipBehavior) {
1730	_clipBehavior = value;
1731	markNeedsAddToScene();
1732	}
1733	}
1734
1735	@override
1736	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
1737	if (!clipRRect!.contains(localPosition)) {
1738	return `false`;
1739	}
1740	return super.findAnnotations<S>(result, localPosition, onlyFirst: onlyFirst);
1741	}
1742
1743	@override
1744	void addToScene(ui.SceneBuilder builder) {
1745	assert(clipRRect != `null`);
1746	bool enabled = `true`;
1747	assert(() {
1748	enabled = !debugDisableClipLayers;
1749	return `true`;
1750	}());
1751	if (enabled) {
1752	engineLayer = builder.pushClipRRect(
1753	clipRRect!,
1754	clipBehavior: clipBehavior,
1755	oldLayer: _engineLayer as ui.ClipRRectEngineLayer?,
1756	);
1757	} else {
1758	engineLayer = `null`;
1759	}
1760	addChildrenToScene(builder);
1761	if (enabled) {
1762	builder.pop();
1763	}
1764	}
1765
1766	@override
1767	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
1768	super.debugFillProperties(properties);
1769	properties.add(DiagnosticsProperty<RRect>('clipRRect', clipRRect));
1770	properties.add(DiagnosticsProperty<Clip>('clipBehavior', clipBehavior));
1771	}
1772	}
1773
1774	/// A composite layer that clips its children using a path.
1775	///
1776	/// When debugging, setting [debugDisableClipLayers] to true will cause this
1777	/// layer to be skipped (directly replaced by its children). This can be helpful
1778	/// to track down the cause of performance problems.
1779	class ClipPathLayer extends ContainerLayer {
1780	/// Creates a layer with a path-based clip.
1781	///
1782	/// The [clipPath] and [clipBehavior] properties must be non-null before the
1783	/// compositing phase of the pipeline.
1784	ClipPathLayer({
1785	Path? clipPath,
1786	Clip clipBehavior = Clip.antiAlias,
1787	}) : _clipPath = clipPath,
1788	_clipBehavior = clipBehavior,
1789	assert(clipBehavior != Clip.none);
1790
1791	/// The path to clip in the parent's coordinate system.
1792	///
1793	/// The scene must be explicitly recomposited after this property is changed
1794	/// (as described at [Layer]).
1795	Path? get clipPath => _clipPath;
1796	Path? _clipPath;
1797	set clipPath(Path? value) {
1798	if (value != _clipPath) {
1799	_clipPath = value;
1800	markNeedsAddToScene();
1801	}
1802	}
1803
1804	@override
1805	Rect? describeClipBounds() => clipPath?.getBounds();
1806
1807	/// {@macro flutter.rendering.ClipRectLayer.clipBehavior}
1808	///
1809	/// Defaults to [Clip.antiAlias].
1810	Clip get clipBehavior => _clipBehavior;
1811	Clip _clipBehavior;
1812	set clipBehavior(Clip value) {
1813	assert(value != Clip.none);
1814	if (value != _clipBehavior) {
1815	_clipBehavior = value;
1816	markNeedsAddToScene();
1817	}
1818	}
1819
1820	@override
1821	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
1822	if (!clipPath!.contains(localPosition)) {
1823	return `false`;
1824	}
1825	return super.findAnnotations<S>(result, localPosition, onlyFirst: onlyFirst);
1826	}
1827
1828	@override
1829	void addToScene(ui.SceneBuilder builder) {
1830	assert(clipPath != `null`);
1831	bool enabled = `true`;
1832	assert(() {
1833	enabled = !debugDisableClipLayers;
1834	return `true`;
1835	}());
1836	if (enabled) {
1837	engineLayer = builder.pushClipPath(
1838	clipPath!,
1839	clipBehavior: clipBehavior,
1840	oldLayer: _engineLayer as ui.ClipPathEngineLayer?,
1841	);
1842	} else {
1843	engineLayer = `null`;
1844	}
1845	addChildrenToScene(builder);
1846	if (enabled) {
1847	builder.pop();
1848	}
1849	}
1850
1851	@override
1852	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
1853	super.debugFillProperties(properties);
1854	properties.add(DiagnosticsProperty<Clip>('clipBehavior', clipBehavior));
1855	}
1856	}
1857
1858	/// A composite layer that applies a [ColorFilter] to its children.
1859	class ColorFilterLayer extends ContainerLayer {
1860	/// Creates a layer that applies a [ColorFilter] to its children.
1861	///
1862	/// The [colorFilter] property must be non-null before the compositing phase
1863	/// of the pipeline.
1864	ColorFilterLayer({
1865	ColorFilter? colorFilter,
1866	}) : _colorFilter = colorFilter;
1867
1868	/// The color filter to apply to children.
1869	///
1870	/// The scene must be explicitly recomposited after this property is changed
1871	/// (as described at [Layer]).
1872	ColorFilter? get colorFilter => _colorFilter;
1873	ColorFilter? _colorFilter;
1874	set colorFilter(ColorFilter? value) {
1875	assert(value != `null`);
1876	if (value != _colorFilter) {
1877	_colorFilter = value;
1878	markNeedsAddToScene();
1879	}
1880	}
1881
1882	@override
1883	void addToScene(ui.SceneBuilder builder) {
1884	assert(colorFilter != `null`);
1885	engineLayer = builder.pushColorFilter(
1886	colorFilter!,
1887	oldLayer: _engineLayer as ui.ColorFilterEngineLayer?,
1888	);
1889	addChildrenToScene(builder);
1890	builder.pop();
1891	}
1892
1893	@override
1894	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
1895	super.debugFillProperties(properties);
1896	properties.add(DiagnosticsProperty<ColorFilter>('colorFilter', colorFilter));
1897	}
1898	}
1899
1900	/// A composite layer that applies an [ImageFilter] to its children.
1901	class ImageFilterLayer extends OffsetLayer {
1902	/// Creates a layer that applies an [ImageFilter] to its children.
1903	///
1904	/// The [imageFilter] property must be non-null before the compositing phase
1905	/// of the pipeline.
1906	ImageFilterLayer({
1907	ui.ImageFilter? imageFilter,
1908	super.offset,
1909	}) : _imageFilter = imageFilter;
1910
1911	/// The image filter to apply to children.
1912	///
1913	/// The scene must be explicitly recomposited after this property is changed
1914	/// (as described at [Layer]).
1915	ui.ImageFilter? get imageFilter => _imageFilter;
1916	ui.ImageFilter? _imageFilter;
1917	set imageFilter(ui.ImageFilter? value) {
1918	assert(value != `null`);
1919	if (value != _imageFilter) {
1920	_imageFilter = value;
1921	markNeedsAddToScene();
1922	}
1923	}
1924
1925	@override
1926	void addToScene(ui.SceneBuilder builder) {
1927	assert(imageFilter != `null`);
1928	engineLayer = builder.pushImageFilter(
1929	imageFilter!,
1930	offset: offset,
1931	oldLayer: _engineLayer as ui.ImageFilterEngineLayer?,
1932	);
1933	addChildrenToScene(builder);
1934	builder.pop();
1935	}
1936
1937	@override
1938	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
1939	super.debugFillProperties(properties);
1940	properties.add(DiagnosticsProperty<ui.ImageFilter>('imageFilter', imageFilter));
1941	}
1942	}
1943
1944	/// A composited layer that applies a given transformation matrix to its
1945	/// children.
1946	///
1947	/// This class inherits from [OffsetLayer] to make it one of the layers that
1948	/// can be used at the root of a [RenderObject] hierarchy.
1949	class TransformLayer extends OffsetLayer {
1950	/// Creates a transform layer.
1951	///
1952	/// The [transform] and [offset] properties must be non-null before the
1953	/// compositing phase of the pipeline.
1954	TransformLayer({ Matrix4? transform, super.offset })
1955	: _transform = transform;
1956
1957	/// The matrix to apply.
1958	///
1959	/// The scene must be explicitly recomposited after this property is changed
1960	/// (as described at [Layer]).
1961	///
1962	/// This transform is applied before [offset], if both are set.
1963	///
1964	/// The [transform] property must be non-null before the compositing phase of
1965	/// the pipeline.
1966	Matrix4? get transform => _transform;
1967	Matrix4? _transform;
1968	set transform(Matrix4? value) {
1969	assert(value != `null`);
1970	assert(value!.storage.every((double component) => component.isFinite));
1971	if (value == _transform) {
1972	return;
1973	}
1974	_transform = value;
1975	_inverseDirty = `true`;
1976	markNeedsAddToScene();
1977	}
1978
1979	Matrix4? _lastEffectiveTransform;
1980	Matrix4? _invertedTransform;
1981	bool _inverseDirty = `true`;
1982
1983	@override
1984	void addToScene(ui.SceneBuilder builder) {
1985	assert(transform != `null`);
1986	_lastEffectiveTransform = transform;
1987	if (offset != Offset.zero) {
1988	_lastEffectiveTransform = Matrix4.translationValues(offset.dx, offset.dy, `0.0`)
1989	..multiply(_lastEffectiveTransform!);
1990	}
1991	engineLayer = builder.pushTransform(
1992	_lastEffectiveTransform!.storage,
1993	oldLayer: _engineLayer as ui.TransformEngineLayer?,
1994	);
1995	addChildrenToScene(builder);
1996	builder.pop();
1997	}
1998
1999	Offset? _transformOffset(Offset localPosition) {
2000	if (_inverseDirty) {
2001	_invertedTransform = Matrix4.tryInvert(
2002	PointerEvent.removePerspectiveTransform(transform!),
2003	);
2004	_inverseDirty = `false`;
2005	}
2006	if (_invertedTransform == `null`) {
2007	return `null`;
2008	}
2009
2010	return MatrixUtils.transformPoint(_invertedTransform!, localPosition);
2011	}
2012
2013	@override
2014	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
2015	final Offset? transformedOffset = _transformOffset(localPosition);
2016	if (transformedOffset == `null`) {
2017	return `false`;
2018	}
2019	return super.findAnnotations<S>(result, transformedOffset, onlyFirst: onlyFirst);
2020	}
2021
2022	@override
2023	void applyTransform(Layer? child, Matrix4 transform) {
2024	assert(child != `null`);
2025	assert(_lastEffectiveTransform != `null` \|\| this.transform != `null`);
2026	if (_lastEffectiveTransform == `null`) {
2027	transform.multiply(this.transform!);
2028	} else {
2029	transform.multiply(_lastEffectiveTransform!);
2030	}
2031	}
2032
2033	@override
2034	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
2035	super.debugFillProperties(properties);
2036	properties.add(TransformProperty('transform', transform));
2037	}
2038	}
2039
2040	/// A composited layer that makes its children partially transparent.
2041	///
2042	/// When debugging, setting [debugDisableOpacityLayers] to true will cause this
2043	/// layer to be skipped (directly replaced by its children). This can be helpful
2044	/// to track down the cause of performance problems.
2045	///
2046	/// Try to avoid an [OpacityLayer] with no children. Remove that layer if
2047	/// possible to save some tree walks.
2048	class OpacityLayer extends OffsetLayer {
2049	/// Creates an opacity layer.
2050	///
2051	/// The [alpha] property must be non-null before the compositing phase of
2052	/// the pipeline.
2053	OpacityLayer({
2054	int? alpha,
2055	super.offset,
2056	}) : _alpha = alpha;
2057
2058	/// The amount to multiply into the alpha channel.
2059	///
2060	/// The opacity is expressed as an integer from 0 to 255, where 0 is fully
2061	/// transparent and 255 is fully opaque.
2062	///
2063	/// The scene must be explicitly recomposited after this property is changed
2064	/// (as described at [Layer]).
2065	int? get alpha => _alpha;
2066	int? _alpha;
2067	set alpha(int? value) {
2068	assert(value != `null`);
2069	if (value != _alpha) {
2070	if (value == `255` \|\| _alpha == `255`) {
2071	engineLayer = `null`;
2072	}
2073	_alpha = value;
2074	markNeedsAddToScene();
2075	}
2076	}
2077
2078	@override
2079	void addToScene(ui.SceneBuilder builder) {
2080	assert(alpha != `null`);
2081
2082	// Don't add this layer if there's no child.
2083	bool enabled = firstChild != `null`;
2084	if (!enabled) {
2085	// Ensure the engineLayer is disposed.
2086	engineLayer = `null`;
2087	// TODO(dnfield): Remove this if/when we can fix https://github.com/flutter/flutter/issues/90004
2088	return;
2089	}
2090
2091	assert(() {
2092	enabled = enabled && !debugDisableOpacityLayers;
2093	return `true`;
2094	}());
2095
2096	final int realizedAlpha = alpha!;
2097	// The type assertions work because the [alpha] setter nulls out the
2098	// engineLayer if it would have changed type (i.e. changed to or from 255).
2099	if (enabled && realizedAlpha < `255`) {
2100	assert(_engineLayer is ui.OpacityEngineLayer?);
2101	engineLayer = builder.pushOpacity(
2102	realizedAlpha,
2103	offset: offset,
2104	oldLayer: _engineLayer as ui.OpacityEngineLayer?,
2105	);
2106	} else {
2107	assert(_engineLayer is ui.OffsetEngineLayer?);
2108	engineLayer = builder.pushOffset(
2109	offset.dx,
2110	offset.dy,
2111	oldLayer: _engineLayer as ui.OffsetEngineLayer?,
2112	);
2113	}
2114	addChildrenToScene(builder);
2115	builder.pop();
2116	}
2117
2118	@override
2119	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
2120	super.debugFillProperties(properties);
2121	properties.add(IntProperty('alpha', alpha));
2122	}
2123	}
2124
2125	/// A composited layer that applies a shader to its children.
2126	///
2127	/// The shader is only applied inside the given [maskRect]. The shader itself
2128	/// uses the top left of the [maskRect] as its origin.
2129	///
2130	/// The [maskRect] does not affect the positions of any child layers.
2131	class ShaderMaskLayer extends ContainerLayer {
2132	/// Creates a shader mask layer.
2133	///
2134	/// The [shader], [maskRect], and [blendMode] properties must be non-null
2135	/// before the compositing phase of the pipeline.
2136	ShaderMaskLayer({
2137	Shader? shader,
2138	Rect? maskRect,
2139	BlendMode? blendMode,
2140	}) : _shader = shader,
2141	_maskRect = maskRect,
2142	_blendMode = blendMode;
2143
2144	/// The shader to apply to the children.
2145	///
2146	/// The origin of the shader (e.g. of the coordinate system used by the `from`
2147	/// and `to` arguments to [ui.Gradient.linear]) is at the top left of the
2148	/// [maskRect].
2149	///
2150	/// The scene must be explicitly recomposited after this property is changed
2151	/// (as described at [Layer]).
2152	///
2153	/// See also:
2154	///
2155	/// [ui.Gradient] and [ui.ImageShader], two shader types that can be used.*
2156	Shader? get shader => _shader;
2157	Shader? _shader;
2158	set shader(Shader? value) {
2159	if (value != _shader) {
2160	_shader = value;
2161	markNeedsAddToScene();
2162	}
2163	}
2164
2165	/// The position and size of the shader.
2166	///
2167	/// The [shader] is only rendered inside this rectangle, using the top left of
2168	/// the rectangle as its origin.
2169	///
2170	/// The scene must be explicitly recomposited after this property is changed
2171	/// (as described at [Layer]).
2172	Rect? get maskRect => _maskRect;
2173	Rect? _maskRect;
2174	set maskRect(Rect? value) {
2175	if (value != _maskRect) {
2176	_maskRect = value;
2177	markNeedsAddToScene();
2178	}
2179	}
2180
2181	/// The blend mode to apply when blending the shader with the children.
2182	///
2183	/// The scene must be explicitly recomposited after this property is changed
2184	/// (as described at [Layer]).
2185	BlendMode? get blendMode => _blendMode;
2186	BlendMode? _blendMode;
2187	set blendMode(BlendMode? value) {
2188	if (value != _blendMode) {
2189	_blendMode = value;
2190	markNeedsAddToScene();
2191	}
2192	}
2193
2194	@override
2195	void addToScene(ui.SceneBuilder builder) {
2196	assert(shader != `null`);
2197	assert(maskRect != `null`);
2198	assert(blendMode != `null`);
2199	engineLayer = builder.pushShaderMask(
2200	shader!,
2201	maskRect! ,
2202	blendMode!,
2203	oldLayer: _engineLayer as ui.ShaderMaskEngineLayer?,
2204	);
2205	addChildrenToScene(builder);
2206	builder.pop();
2207	}
2208
2209	@override
2210	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
2211	super.debugFillProperties(properties);
2212	properties.add(DiagnosticsProperty<Shader>('shader', shader));
2213	properties.add(DiagnosticsProperty<Rect>('maskRect', maskRect));
2214	properties.add(EnumProperty<BlendMode>('blendMode', blendMode));
2215	}
2216	}
2217
2218	/// A composited layer that applies a filter to the existing contents of the scene.
2219	class BackdropFilterLayer extends ContainerLayer {
2220	/// Creates a backdrop filter layer.
2221	///
2222	/// The [filter] property must be non-null before the compositing phase of the
2223	/// pipeline.
2224	///
2225	/// The [blendMode] property defaults to [BlendMode.srcOver].
2226	BackdropFilterLayer({
2227	ui.ImageFilter? filter,
2228	BlendMode blendMode = BlendMode.srcOver,
2229	}) : _filter = filter,
2230	_blendMode = blendMode;
2231
2232	/// The filter to apply to the existing contents of the scene.
2233	///
2234	/// The scene must be explicitly recomposited after this property is changed
2235	/// (as described at [Layer]).
2236	ui.ImageFilter? get filter => _filter;
2237	ui.ImageFilter? _filter;
2238	set filter(ui.ImageFilter? value) {
2239	if (value != _filter) {
2240	_filter = value;
2241	markNeedsAddToScene();
2242	}
2243	}
2244
2245	/// The blend mode to use to apply the filtered background content onto the background
2246	/// surface.
2247	///
2248	/// The default value of this property is [BlendMode.srcOver].
2249	/// {@macro flutter.widgets.BackdropFilter.blendMode}
2250	///
2251	/// The scene must be explicitly recomposited after this property is changed
2252	/// (as described at [Layer]).
2253	BlendMode get blendMode => _blendMode;
2254	BlendMode _blendMode;
2255	set blendMode(BlendMode value) {
2256	if (value != _blendMode) {
2257	_blendMode = value;
2258	markNeedsAddToScene();
2259	}
2260	}
2261
2262	@override
2263	void addToScene(ui.SceneBuilder builder) {
2264	assert(filter != `null`);
2265	engineLayer = builder.pushBackdropFilter(
2266	filter!,
2267	blendMode: blendMode,
2268	oldLayer: _engineLayer as ui.BackdropFilterEngineLayer?,
2269	);
2270	addChildrenToScene(builder);
2271	builder.pop();
2272	}
2273
2274	@override
2275	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
2276	super.debugFillProperties(properties);
2277	properties.add(DiagnosticsProperty<ui.ImageFilter>('filter', filter));
2278	properties.add(EnumProperty<BlendMode>('blendMode', blendMode));
2279	}
2280	}
2281
2282	/// An object that a [LeaderLayer] can register with.
2283	///
2284	/// An instance of this class should be provided as the [LeaderLayer.link] and
2285	/// the [FollowerLayer.link] properties to cause the [FollowerLayer] to follow
2286	/// the [LeaderLayer].
2287	///
2288	/// See also:
2289	///
2290	/// [CompositedTransformTarget], the widget that creates a [LeaderLayer].*
2291	/// [CompositedTransformFollower], the widget that creates a [FollowerLayer].*
2292	/// [RenderLeaderLayer] and [RenderFollowerLayer], the corresponding*
2293	/// render objects.
2294	class LayerLink {
2295	/// The [LeaderLayer] connected to this link.
2296	LeaderLayer? get leader => _leader;
2297	LeaderLayer? _leader;
2298
2299	void _registerLeader(LeaderLayer leader) {
2300	assert(_leader != leader);
2301	assert((){
2302	if (_leader != `null`) {
2303	_debugPreviousLeaders ??= <LeaderLayer>{};
2304	_debugScheduleLeadersCleanUpCheck();
2305	return _debugPreviousLeaders!.add(_leader!);
2306	}
2307	return `true`;
2308	}());
2309	_leader = leader;
2310	}
2311
2312	void _unregisterLeader(LeaderLayer leader) {
2313	if (_leader == leader) {
2314	_leader = `null`;
2315	} else {
2316	assert(_debugPreviousLeaders!.remove(leader));
2317	}
2318	}
2319
2320	/// Stores the previous leaders that were replaced by the current [_leader]
2321	/// in the current frame.
2322	///
2323	/// These leaders need to give up their leaderships of this link by the end of
2324	/// the current frame.
2325	Set<LeaderLayer>? _debugPreviousLeaders;
2326	bool _debugLeaderCheckScheduled = `false`;
2327
2328	/// Schedules the check as post frame callback to make sure the
2329	/// [_debugPreviousLeaders] is empty.
2330	void _debugScheduleLeadersCleanUpCheck() {
2331	assert(_debugPreviousLeaders != `null`);
2332	assert(() {
2333	if (_debugLeaderCheckScheduled) {
2334	return `true`;
2335	}
2336	_debugLeaderCheckScheduled = `true`;
2337	SchedulerBinding.instance.addPostFrameCallback((Duration timeStamp) {
2338	_debugLeaderCheckScheduled = `false`;
2339	assert(_debugPreviousLeaders!.isEmpty);
2340	}, debugLabel: 'LayerLink.leadersCleanUpCheck');
2341	return `true`;
2342	}());
2343	}
2344
2345	/// The total size of the content of the connected [LeaderLayer].
2346	///
2347	/// Generally this should be set by the [RenderObject] that paints on the
2348	/// registered [LeaderLayer] (for instance a [RenderLeaderLayer] that shares
2349	/// this link with its followers). This size may be outdated before and during
2350	/// layout.
2351	Size? leaderSize;
2352
2353	@override
2354	String toString({ DiagnosticLevel minLevel = DiagnosticLevel.info }) {
2355	return '${describeIdentity(this)}(${ _leader != `null` ? "<linked>" : "<dangling>" })';
2356	}
2357	}
2358
2359	/// A composited layer that can be followed by a [FollowerLayer].
2360	///
2361	/// This layer collapses the accumulated offset into a transform and passes
2362	/// [Offset.zero] to its child layers in the [addToScene]/[addChildrenToScene]
2363	/// methods, so that [applyTransform] will work reliably.
2364	class LeaderLayer extends ContainerLayer {
2365	/// Creates a leader layer.
2366	///
2367	/// The [link] property must not have been provided to any other [LeaderLayer]
2368	/// layers that are [attached] to the layer tree at the same time.
2369	///
2370	/// The [offset] property must be non-null before the compositing phase of the
2371	/// pipeline.
2372	LeaderLayer({ required LayerLink link, Offset offset = Offset.zero }) : _link = link, _offset = offset;
2373
2374	/// The object with which this layer should register.
2375	///
2376	/// The link will be established when this layer is [attach]ed, and will be
2377	/// cleared when this layer is [detach]ed.
2378	LayerLink get link => _link;
2379	LayerLink _link;
2380	set link(LayerLink value) {
2381	if (_link == value) {
2382	return;
2383	}
2384	if (attached) {
2385	_link._unregisterLeader(this);
2386	value._registerLeader(this);
2387	}
2388	_link = value;
2389	}
2390
2391	/// Offset from parent in the parent's coordinate system.
2392	///
2393	/// The scene must be explicitly recomposited after this property is changed
2394	/// (as described at [Layer]).
2395	///
2396	/// The [offset] property must be non-null before the compositing phase of the
2397	/// pipeline.
2398	Offset get offset => _offset;
2399	Offset _offset;
2400	set offset(Offset value) {
2401	if (value == _offset) {
2402	return;
2403	}
2404	_offset = value;
2405	if (!alwaysNeedsAddToScene) {
2406	markNeedsAddToScene();
2407	}
2408	}
2409
2410	@override
2411	void attach(Object owner) {
2412	super.attach(owner);
2413	_link._registerLeader(this);
2414	}
2415
2416	@override
2417	void detach() {
2418	_link._unregisterLeader(this);
2419	super.detach();
2420	}
2421
2422	@override
2423	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
2424	return super.findAnnotations<S>(result, localPosition - offset, onlyFirst: onlyFirst);
2425	}
2426
2427	@override
2428	void addToScene(ui.SceneBuilder builder) {
2429	if (offset != Offset.zero) {
2430	engineLayer = builder.pushTransform(
2431	Matrix4.translationValues(offset.dx, offset.dy, `0.0`).storage,
2432	oldLayer: _engineLayer as ui.TransformEngineLayer?,
2433	);
2434	} else {
2435	engineLayer = `null`;
2436	}
2437	addChildrenToScene(builder);
2438	if (offset != Offset.zero) {
2439	builder.pop();
2440	}
2441	}
2442
2443	/// Applies the transform that would be applied when compositing the given
2444	/// child to the given matrix.
2445	///
2446	/// See [ContainerLayer.applyTransform] for details.
2447	///
2448	/// The `child` argument may be null, as the same transform is applied to all
2449	/// children.
2450	@override
2451	void applyTransform(Layer? child, Matrix4 transform) {
2452	if (offset != Offset.zero) {
2453	transform.translate(offset.dx, offset.dy);
2454	}
2455	}
2456
2457	@override
2458	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
2459	super.debugFillProperties(properties);
2460	properties.add(DiagnosticsProperty<Offset>('offset', offset));
2461	properties.add(DiagnosticsProperty<LayerLink>('link', link));
2462	}
2463	}
2464
2465	/// A composited layer that applies a transformation matrix to its children such
2466	/// that they are positioned to match a [LeaderLayer].
2467	///
2468	/// If any of the ancestors of this layer have a degenerate matrix (e.g. scaling
2469	/// by zero), then the [FollowerLayer] will not be able to transform its child
2470	/// to the coordinate space of the [LeaderLayer].
2471	///
2472	/// A [linkedOffset] property can be provided to further offset the child layer
2473	/// from the leader layer, for example if the child is to follow the linked
2474	/// layer at a distance rather than directly overlapping it.
2475	class FollowerLayer extends ContainerLayer {
2476	/// Creates a follower layer.
2477	///
2478	/// The [unlinkedOffset], [linkedOffset], and [showWhenUnlinked] properties
2479	/// must be non-null before the compositing phase of the pipeline.
2480	FollowerLayer({
2481	required this.link,
2482	this.showWhenUnlinked = `true`,
2483	this.unlinkedOffset = Offset.zero,
2484	this.linkedOffset = Offset.zero,
2485	});
2486
2487	/// The link to the [LeaderLayer].
2488	///
2489	/// The same object should be provided to a [LeaderLayer] that is earlier in
2490	/// the layer tree. When this layer is composited, it will apply a transform
2491	/// that moves its children to match the position of the [LeaderLayer].
2492	LayerLink link;
2493
2494	/// Whether to show the layer's contents when the [link] does not point to a
2495	/// [LeaderLayer].
2496	///
2497	/// When the layer is linked, children layers are positioned such that they
2498	/// have the same global position as the linked [LeaderLayer].
2499	///
2500	/// When the layer is not linked, then: if [showWhenUnlinked] is true,
2501	/// children are positioned as if the [FollowerLayer] was a [ContainerLayer];
2502	/// if it is false, then children are hidden.
2503	///
2504	/// The [showWhenUnlinked] property must be non-null before the compositing
2505	/// phase of the pipeline.
2506	bool? showWhenUnlinked;
2507
2508	/// Offset from parent in the parent's coordinate system, used when the layer
2509	/// is not linked to a [LeaderLayer].
2510	///
2511	/// The scene must be explicitly recomposited after this property is changed
2512	/// (as described at [Layer]).
2513	///
2514	/// The [unlinkedOffset] property must be non-null before the compositing
2515	/// phase of the pipeline.
2516	///
2517	/// See also:
2518	///
2519	/// [linkedOffset], for when the layers are linked.*
2520	Offset? unlinkedOffset;
2521
2522	/// Offset from the origin of the leader layer to the origin of the child
2523	/// layers, used when the layer is linked to a [LeaderLayer].
2524	///
2525	/// The scene must be explicitly recomposited after this property is changed
2526	/// (as described at [Layer]).
2527	///
2528	/// The [linkedOffset] property must be non-null before the compositing phase
2529	/// of the pipeline.
2530	///
2531	/// See also:
2532	///
2533	/// [unlinkedOffset], for when the layer is not linked.*
2534	Offset? linkedOffset;
2535
2536	Offset? _lastOffset;
2537	Matrix4? _lastTransform;
2538	Matrix4? _invertedTransform;
2539	bool _inverseDirty = `true`;
2540
2541	Offset? _transformOffset(Offset localPosition) {
2542	if (_inverseDirty) {
2543	_invertedTransform = Matrix4.tryInvert(getLastTransform()!);
2544	_inverseDirty = `false`;
2545	}
2546	if (_invertedTransform == `null`) {
2547	return `null`;
2548	}
2549	final Vector4 vector = Vector4(localPosition.dx, localPosition.dy, `0.0`, `1.0`);
2550	final Vector4 result = _invertedTransform!.transform(vector);
2551	return Offset(result[`0`] - linkedOffset!.dx, result[`1`] - linkedOffset!.dy);
2552	}
2553
2554	@override
2555	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
2556	if (link.leader == `null`) {
2557	if (showWhenUnlinked!) {
2558	return super.findAnnotations(result, localPosition - unlinkedOffset!, onlyFirst: onlyFirst);
2559	}
2560	return `false`;
2561	}
2562	final Offset? transformedOffset = _transformOffset(localPosition);
2563	if (transformedOffset == `null`) {
2564	return `false`;
2565	}
2566	return super.findAnnotations<S>(result, transformedOffset, onlyFirst: onlyFirst);
2567	}
2568
2569	/// The transform that was used during the last composition phase.
2570	///
2571	/// If the [link] was not linked to a [LeaderLayer], or if this layer has
2572	/// a degenerate matrix applied, then this will be null.
2573	///
2574	/// This method returns a new [Matrix4] instance each time it is invoked.
2575	Matrix4? getLastTransform() {
2576	if (_lastTransform == `null`) {
2577	return `null`;
2578	}
2579	final Matrix4 result = Matrix4.translationValues(-_lastOffset!.dx, -_lastOffset!.dy, `0.0`);
2580	result.multiply(_lastTransform!);
2581	return result;
2582	}
2583
2584	/// Call [applyTransform] for each layer in the provided list.
2585	///
2586	/// The list is in reverse order (deepest first). The first layer will be
2587	/// treated as the child of the second, and so forth. The first layer in the
2588	/// list won't have [applyTransform] called on it. The first layer may be
2589	/// null.
2590	static Matrix4 _collectTransformForLayerChain(List<ContainerLayer?> layers) {
2591	// Initialize our result matrix.
2592	final Matrix4 result = Matrix4.identity();
2593	// Apply each layer to the matrix in turn, starting from the last layer,
2594	// and providing the previous layer as the child.
2595	for (int index = layers.length - `1`; index > `0`; index -= `1`) {
2596	layers[index]?.applyTransform(layers[index - `1`], result);
2597	}
2598	return result;
2599	}
2600
2601	/// Find the common ancestor of two layers [a] and [b] by searching towards
2602	/// the root of the tree, and append each ancestor of [a] or [b] visited along
2603	/// the path to [ancestorsA] and [ancestorsB] respectively.
2604	///
2605	/// Returns null if [a] [b] do not share a common ancestor, in which case the
2606	/// results in [ancestorsA] and [ancestorsB] are undefined.
2607	static Layer? _pathsToCommonAncestor(
2608	Layer? a,
2609	Layer? b,
2610	List<ContainerLayer?> ancestorsA,
2611	List<ContainerLayer?> ancestorsB,
2612	) {
2613	// No common ancestor found.
2614	if (a == `null` \|\| b == `null`) {
2615	return `null`;
2616	}
2617
2618	if (identical(a, b)) {
2619	return a;
2620	}
2621
2622	if (a.depth < b.depth) {
2623	ancestorsB.add(b.parent);
2624	return _pathsToCommonAncestor(a, b.parent, ancestorsA, ancestorsB);
2625	} else if (a.depth > b.depth) {
2626	ancestorsA.add(a.parent);
2627	return _pathsToCommonAncestor(a.parent, b, ancestorsA, ancestorsB);
2628	}
2629
2630	ancestorsA.add(a.parent);
2631	ancestorsB.add(b.parent);
2632	return _pathsToCommonAncestor(a.parent, b.parent, ancestorsA, ancestorsB);
2633	}
2634
2635	bool _debugCheckLeaderBeforeFollower(
2636	List<ContainerLayer> leaderToCommonAncestor,
2637	List<ContainerLayer> followerToCommonAncestor,
2638	) {
2639	if (followerToCommonAncestor.length <= `1`) {
2640	// Follower is the common ancestor, ergo the leader must come AFTER the follower.
2641	return `false`;
2642	}
2643	if (leaderToCommonAncestor.length <= `1`) {
2644	// Leader is the common ancestor, ergo the leader must come BEFORE the follower.
2645	return `true`;
2646	}
2647
2648	// Common ancestor is neither the leader nor the follower.
2649	final ContainerLayer leaderSubtreeBelowAncestor = leaderToCommonAncestor[leaderToCommonAncestor.length - `2`];
2650	final ContainerLayer followerSubtreeBelowAncestor = followerToCommonAncestor[followerToCommonAncestor.length - `2`];
2651
2652	Layer? sibling = leaderSubtreeBelowAncestor;
2653	while (sibling != `null`) {
2654	if (sibling == followerSubtreeBelowAncestor) {
2655	return `true`;
2656	}
2657	sibling = sibling.nextSibling;
2658	}
2659	// The follower subtree didn't come after the leader subtree.
2660	return `false`;
2661	}
2662
2663	/// Populate [_lastTransform] given the current state of the tree.
2664	void _establishTransform() {
2665	_lastTransform = `null`;
2666	final LeaderLayer? leader = link.leader;
2667	// Check to see if we are linked.
2668	if (leader == `null`) {
2669	return;
2670	}
2671	// If we're linked, check the link is valid.
2672	assert(
2673	leader.owner == owner,
2674	'Linked LeaderLayer anchor is not in the same layer tree as the FollowerLayer.',
2675	);
2676
2677	// Stores [leader, ..., commonAncestor] after calling _pathsToCommonAncestor.
2678	final List<ContainerLayer> forwardLayers = <ContainerLayer>[leader];
2679	// Stores [this (follower), ..., commonAncestor] after calling
2680	// _pathsToCommonAncestor.
2681	final List<ContainerLayer> inverseLayers = <ContainerLayer>[this];
2682
2683	final Layer? ancestor = _pathsToCommonAncestor(
2684	leader, this,
2685	forwardLayers, inverseLayers,
2686	);
2687	assert(
2688	ancestor != `null`,
2689	'LeaderLayer and FollowerLayer do not have a common ancestor.',
2690	);
2691	assert(
2692	_debugCheckLeaderBeforeFollower(forwardLayers, inverseLayers),
2693	'LeaderLayer anchor must come before FollowerLayer in paint order, but the reverse was true.',
2694	);
2695
2696	final Matrix4 forwardTransform = _collectTransformForLayerChain(forwardLayers);
2697	// Further transforms the coordinate system to a hypothetical child (null)
2698	// of the leader layer, to account for the leader's additional paint offset
2699	// and layer offset (LeaderLayer.offset).
2700	leader.applyTransform(`null`, forwardTransform);
2701	forwardTransform.translate(linkedOffset!.dx, linkedOffset!.dy);
2702
2703	final Matrix4 inverseTransform = _collectTransformForLayerChain(inverseLayers);
2704
2705	if (inverseTransform.invert() == `0.0`) {
2706	// We are in a degenerate transform, so there's not much we can do.
2707	return;
2708	}
2709	// Combine the matrices and store the result.
2710	inverseTransform.multiply(forwardTransform);
2711	_lastTransform = inverseTransform;
2712	_inverseDirty = `true`;
2713	}
2714
2715	/// {@template flutter.rendering.FollowerLayer.alwaysNeedsAddToScene}
2716	/// This disables retained rendering.
2717	///
2718	/// A [FollowerLayer] copies changes from a [LeaderLayer] that could be anywhere
2719	/// in the Layer tree, and that leader layer could change without notifying the
2720	/// follower layer. Therefore we have to always call a follower layer's
2721	/// [addToScene]. In order to call follower layer's [addToScene], leader layer's
2722	/// [addToScene] must be called first so leader layer must also be considered
2723	/// as [alwaysNeedsAddToScene].
2724	/// {@endtemplate}
2725	@override
2726	bool get alwaysNeedsAddToScene => `true`;
2727
2728	@override
2729	void addToScene(ui.SceneBuilder builder) {
2730	assert(showWhenUnlinked != `null`);
2731	if (link.leader == `null` && !showWhenUnlinked!) {
2732	_lastTransform = `null`;
2733	_lastOffset = `null`;
2734	_inverseDirty = `true`;
2735	engineLayer = `null`;
2736	return;
2737	}
2738	_establishTransform();
2739	if (_lastTransform != `null`) {
2740	_lastOffset = unlinkedOffset;
2741	engineLayer = builder.pushTransform(
2742	_lastTransform!.storage,
2743	oldLayer: _engineLayer as ui.TransformEngineLayer?,
2744	);
2745	addChildrenToScene(builder);
2746	builder.pop();
2747	} else {
2748	_lastOffset = `null`;
2749	final Matrix4 matrix = Matrix4.translationValues(unlinkedOffset!.dx, unlinkedOffset!.dy, `.0`);
2750	engineLayer = builder.pushTransform(
2751	matrix.storage,
2752	oldLayer: _engineLayer as ui.TransformEngineLayer?,
2753	);
2754	addChildrenToScene(builder);
2755	builder.pop();
2756	}
2757	_inverseDirty = `true`;
2758	}
2759
2760	@override
2761	void applyTransform(Layer? child, Matrix4 transform) {
2762	assert(child != `null`);
2763	if (_lastTransform != `null`) {
2764	transform.multiply(_lastTransform!);
2765	} else {
2766	transform.multiply(Matrix4.translationValues(unlinkedOffset!.dx, unlinkedOffset!.dy, `0`));
2767	}
2768	}
2769
2770	@override
2771	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
2772	super.debugFillProperties(properties);
2773	properties.add(DiagnosticsProperty<LayerLink>('link', link));
2774	properties.add(TransformProperty('transform', getLastTransform(), defaultValue: `null`));
2775	}
2776	}
2777
2778	/// A composited layer which annotates its children with a value. Pushing this
2779	/// layer to the tree is the common way of adding an annotation.
2780	///
2781	/// An annotation is an optional object of any type that, when attached with a
2782	/// layer, can be retrieved using [Layer.find] or [Layer.findAllAnnotations]
2783	/// with a position. The search process is done recursively, controlled by a
2784	/// concept of being opaque to a type of annotation, explained in the document
2785	/// of [Layer.findAnnotations].
2786	///
2787	/// When an annotation search arrives, this layer defers the same search to each
2788	/// of this layer's children, respecting their opacity. Then it adds this
2789	/// layer's annotation if all of the following restrictions are met:
2790	///
2791	/// {@template flutter.rendering.AnnotatedRegionLayer.restrictions}
2792	/// The target type must be identical to the annotated type `T`.*
2793	/// If [size] is provided, the target position must be contained within the*
2794	/// rectangle formed by [size] and [offset].
2795	/// {@endtemplate}
2796	///
2797	/// This layer is opaque to a type of annotation if any child is also opaque, or
2798	/// if [opaque] is true and the layer's annotation is added.
2799	class AnnotatedRegionLayer<T extends Object> extends ContainerLayer {
2800	/// Creates a new layer that annotates its children with [value].
2801	AnnotatedRegionLayer(
2802	this.value, {
2803	this.size,
2804	Offset? offset,
2805	this.opaque = `false`,
2806	}) : offset = offset ?? Offset.zero;
2807
2808	/// The annotated object, which is added to the result if all restrictions are
2809	/// met.
2810	final T value;
2811
2812	/// The size of the annotated object.
2813	///
2814	/// If [size] is provided, then the annotation is found only if the target
2815	/// position is contained by the rectangle formed by [size] and [offset].
2816	/// Otherwise no such restriction is applied, and clipping can only be done by
2817	/// the ancestor layers.
2818	final Size? size;
2819
2820	/// The position of the annotated object.
2821	///
2822	/// The [offset] defaults to [Offset.zero] if not provided, and is ignored if
2823	/// [size] is not set.
2824	///
2825	/// The [offset] only offsets the clipping rectangle, and does not affect
2826	/// how the painting or annotation search is propagated to its children.
2827	final Offset offset;
2828
2829	/// Whether the annotation of this layer should be opaque during an annotation
2830	/// search of type `T`, preventing siblings visually behind it from being
2831	/// searched.
2832	///
2833	/// If [opaque] is true, and this layer does add its annotation [value],
2834	/// then the layer will always be opaque during the search.
2835	///
2836	/// If [opaque] is false, or if this layer does not add its annotation,
2837	/// then the opacity of this layer will be the one returned by the children,
2838	/// meaning that it will be opaque if any child is opaque.
2839	///
2840	/// The [opaque] defaults to false.
2841	///
2842	/// The [opaque] is effectively useless during [Layer.find] (more
2843	/// specifically, [Layer.findAnnotations] with `onlyFirst: true`), since the
2844	/// search process then skips the remaining tree after finding the first
2845	/// annotation.
2846	///
2847	/// See also:
2848	///
2849	/// [Layer.findAnnotations], which explains the concept of being opaque*
2850	/// to a type of annotation as the return value.
2851	/// [HitTestBehavior], which controls similar logic when hit-testing in the*
2852	/// render tree.
2853	final bool opaque;
2854
2855	/// Searches the subtree for annotations of type `S` at the location
2856	/// `localPosition`, then adds the annotation [value] if applicable.
2857	///
2858	/// This method always searches its children, and if any child returns `true`,
2859	/// the remaining children are skipped. Regardless of what the children
2860	/// return, this method then adds this layer's annotation if all of the
2861	/// following restrictions are met:
2862	///
2863	/// {@macro flutter.rendering.AnnotatedRegionLayer.restrictions}
2864	///
2865	/// This search process respects `onlyFirst`, meaning that when `onlyFirst` is
2866	/// true, the search will stop when it finds the first annotation from the
2867	/// children, and the layer's own annotation is checked only when none is
2868	/// given by the children.
2869	///
2870	/// The return value is true if any child returns `true`, or if [opaque] is
2871	/// true and the layer's annotation is added.
2872	///
2873	/// For explanation of layer annotations, parameters and return value, refer
2874	/// to [Layer.findAnnotations].
2875	@override
2876	bool findAnnotations<S extends Object>(AnnotationResult<S> result, Offset localPosition, { required bool onlyFirst }) {
2877	bool isAbsorbed = super.findAnnotations(result, localPosition, onlyFirst: onlyFirst);
2878	if (result.entries.isNotEmpty && onlyFirst) {
2879	return isAbsorbed;
2880	}
2881	if (size != `null` && !(offset & size!).contains(localPosition)) {
2882	return isAbsorbed;
2883	}
2884	if (T == S) {
2885	isAbsorbed = isAbsorbed \|\| opaque;
2886	final Object untypedValue = value;
2887	final S typedValue = untypedValue as S;
2888	result.add(AnnotationEntry<S>(
2889	annotation: typedValue,
2890	localPosition: localPosition - offset,
2891	));
2892	}
2893	return isAbsorbed;
2894	}
2895
2896	@override
2897	void debugFillProperties(DiagnosticPropertiesBuilder properties) {
2898	super.debugFillProperties(properties);
2899	properties.add(DiagnosticsProperty<T>('value', value));
2900	properties.add(DiagnosticsProperty<Size>('size', size, defaultValue: `null`));
2901	properties.add(DiagnosticsProperty<Offset>('offset', offset, defaultValue: `null`));
2902	properties.add(DiagnosticsProperty<bool>('opaque', opaque, defaultValue: `false`));
2903	}
2904	}
2905