engineLayer property Null safety

EngineLayer? engineLayer
protected">@protectedvisibleForTesting">@visibleForTesting

Stores the engine layer created for this layer in order to reuse engine resources across frames for better app performance.

This value may be passed to ui.SceneBuilder.addRetained to communicate to the engine that nothing in this layer or any of its descendants changed. The native engine could, for example, reuse the texture rendered in a previous frame. The web engine could, for example, reuse the HTML DOM nodes created for a previous frame.

This value may be passed as oldLayer argument to a "push" method to communicate to the engine that a layer is updating a previously rendered layer. The web engine could, for example, update the properties of previously rendered HTML DOM nodes rather than creating new nodes.

Implementation

@protected
@visibleForTesting
ui.EngineLayer? get engineLayer => _engineLayer;
void engineLayer=(EngineLayer? value)
protected">@protectedvisibleForTesting">@visibleForTesting

Sets the engine layer used to render this layer.

Typically this field is set to the value returned by addToScene, which in turn returns the engine layer produced by one of ui.SceneBuilder's "push" methods, such as ui.SceneBuilder.pushOpacity.

Implementation

@protected
@visibleForTesting
set engineLayer(ui.EngineLayer? value) {
  assert(!_debugMutationsLocked);
  assert(!_debugDisposed);

  _engineLayer?.dispose();
  _engineLayer = value;
  if (!alwaysNeedsAddToScene) {
    // The parent must construct a new engine layer to add this layer to, and
    // so we mark it as needing [addToScene].
    //
    // This is designed to handle two situations:
    //
    // 1. When rendering the complete layer tree as normal. In this case we
    // call child `addToScene` methods first, then we call `set engineLayer`
    // for the parent. The children will call `markNeedsAddToScene` on the
    // parent to signal that they produced new engine layers and therefore
    // the parent needs to update. In this case, the parent is already adding
    // itself to the scene via [addToScene], and so after it's done, its
    // `set engineLayer` is called and it clears the `_needsAddToScene` flag.
    //
    // 2. When rendering an interior layer (e.g. `OffsetLayer.toImage`). In
    // this case we call `addToScene` for one of the children but not the
    // parent, i.e. we produce new engine layers for children but not for the
    // parent. Here the children will mark the parent as needing
    // `addToScene`, but the parent does not clear the flag until some future
    // frame decides to render it, at which point the parent knows that it
    // cannot retain its engine layer and will call `addToScene` again.
    if (parent != null && !parent!.alwaysNeedsAddToScene) {
      parent!.markNeedsAddToScene();
    }
  }
}