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