addRetained method Null safety

void addRetained(
  1. EngineLayer retainedLayer
)

Add a retained engine layer subtree from previous frames.

All the engine layers that are in the subtree of the retained layer will be automatically appended to the current engine layer tree.

Therefore, when implementing a subclass of the Layer concept defined in the rendering layer of Flutter's framework, once this is called, there's no need to call Layer.addToScene for its children layers.

Passing a layer to addRetained or as oldLayer argument to a push method counts as usage. A layer can be used no more than once in a scene. For example, it may not be passed simultaneously to two push methods, or to a push method and to addRetained.

When a layer is passed to addRetained all descendant layers are also considered as used in this scene. The same single-usage restriction applies to descendants.

When a layer is passed as an oldLayer argument to a push method, it may no longer be used in subsequent frames. If you would like to continue reusing the resources associated with the layer, store the layer object returned by the push method and use that in the next frame instead of the original object.

Implementation

void addRetained(EngineLayer retainedLayer) {
  assert(retainedLayer is _EngineLayerWrapper);
  assert(() {
    final _EngineLayerWrapper layer = retainedLayer as _EngineLayerWrapper;

    assert(layer._nativeLayer != null);

    void recursivelyCheckChildrenUsedOnce(_EngineLayerWrapper parentLayer) {
      _debugCheckUsedOnce(parentLayer, 'retained layer');
      parentLayer._debugCheckNotUsedAsOldLayer();

      final List<_EngineLayerWrapper>? children = parentLayer._debugChildren;
      if (children == null || children.isEmpty) {
        return;
      }
      children.forEach(recursivelyCheckChildrenUsedOnce);
    }

    recursivelyCheckChildrenUsedOnce(layer);

    return true;
  }());

  final _EngineLayerWrapper wrapper = retainedLayer as _EngineLayerWrapper;
  _addRetained(wrapper._nativeLayer!);
}