Add backend texture support (eg video, camera) (#12525)

bin/internal/engine.version

-88cf09ffe664253e8835dbbef2c2243484f59cb4
+ce7202d73cfd183016ce69a2774827ffac82c59b

packages/flutter/lib/rendering.dart

@@ -60,6 +60,7 @@ export 'src/rendering/sliver_persistent_header.dart';
 export 'src/rendering/stack.dart';
 export 'src/rendering/table.dart';
 export 'src/rendering/table_border.dart';
+export 'src/rendering/texture.dart';
 export 'src/rendering/tweens.dart';
 export 'src/rendering/view.dart';
 export 'src/rendering/viewport.dart';

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

@@ -30,7 +30,7 @@ import 'debug.dart';
 /// See also:
 ///
 ///  * [RenderView.compositeFrame], which implements this recomposition protocol
-///    for painting [RenderObject] trees on the the display.
+///    for painting [RenderObject] trees on the display.
 abstract class Layer extends AbstractNode with DiagnosticableTreeMixin {
   /// This layer's parent in the layer tree.
   ///
@@ -128,7 +128,7 @@ class PictureLayer extends Layer {
 
   /// The picture recorded for this layer.
   ///
-  /// The picture's coodinate system matches this layer's coodinate system.
+  /// The picture's coordinate system matches this layer's coordinate system.
   ///
   /// The scene must be explicitly recomposited after this property is changed
   /// (as described at [Layer]).
@@ -167,6 +167,58 @@ class PictureLayer extends Layer {
   }
 }
 
+/// A composited layer that maps a backend texture to a rectangle.
+///
+/// Backend textures are images that can be applied (mapped) to an area of the
+/// Flutter view. They are created, managed, and updated using a
+/// platform-specific texture registry. This is typically done by a plugin
+/// that integrates with host platform video player, camera, or OpenGL APIs,
+/// or similar image sources.
+///
+/// A texture layer refers to its backend texture using an integer ID. Texture
+/// IDs are obtained from the texture registry and are scoped to the Flutter
+/// view. Texture IDs may be reused after deregistration, at the discretion
+/// of the registry. The use of texture IDs currently unknown to the registry
+/// will silently result in a blank rectangle.
+///
+/// Once inserted into the layer tree, texture layers are repainted autonomously
+/// as dictated by the backend (e.g. on arrival of a video frame). Such
+/// repainting generally does not involve executing Dart code.
+///
+/// Texture layers are always leaves in the layer tree.
+///
+/// See also:
+///
+/// * <https://docs.flutter.io/javadoc/io/flutter/view/TextureRegistry.html>
+///   for how to create and manage backend textures on Android.
+/// * <https://docs.flutter.io/objcdoc/Protocols/FlutterTextureRegistry.html>
+///   for how to create and manage backend textures on iOS.
+class TextureLayer extends Layer {
+  /// Creates a texture layer bounded by [rect] and with backend texture
+  /// identified by [textureId].
+  TextureLayer({
+    @required this.rect,
+    @required this.textureId,
+  }): assert(rect != null), assert(textureId != null);
+
+  /// Bounding rectangle of this layer.
+  final Rect rect;
+
+  /// The identity of the backend texture.
+  final int textureId;
+
+  @override
+  void addToScene(ui.SceneBuilder builder, Offset layerOffset) {
+    final Rect shiftedRect = rect.shift(layerOffset);
+    builder.addTexture(
+      textureId,
+      offset: shiftedRect.topLeft,
+      width: shiftedRect.width,
+      height: shiftedRect.height,
+    );
+  }
+}
+
 /// A layer that indicates to the compositor that it should display
 /// certain performance statistics within it.
 ///

packages/flutter/lib/src/rendering/texture.dart

+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/foundation.dart';
+import 'box.dart';
+import 'layer.dart';
+import 'object.dart';
+
+/// A rectangle upon which a backend texture is mapped.
+///
+/// Backend textures are images that can be applied (mapped) to an area of the
+/// Flutter view. They are created, managed, and updated using a
+/// platform-specific texture registry. This is typically done by a plugin
+/// that integrates with host platform video player, camera, or OpenGL APIs,
+/// or similar image sources.
+///
+/// A texture box refers to its backend texture using an integer ID. Texture
+/// IDs are obtained from the texture registry and are scoped to the Flutter
+/// view. Texture IDs may be reused after deregistration, at the discretion
+/// of the registry. The use of texture IDs currently unknown to the registry
+/// will silently result in a blank rectangle.
+///
+/// Texture boxes are repainted autonomously as dictated by the backend (e.g. on
+/// arrival of a video frame). Such repainting generally does not involve
+/// executing Dart code.
+///
+/// The size of the rectangle is determined by the parent, and the texture is
+/// automatically scaled to fit.
+///
+/// See also:
+///
+/// * <https://docs.flutter.io/javadoc/io/flutter/view/TextureRegistry.html>
+///   for how to create and manage backend textures on Android.
+/// * <https://docs.flutter.io/objcdoc/Protocols/FlutterTextureRegistry.html>
+///   for how to create and manage backend textures on iOS.
+class TextureBox extends RenderBox {
+  /// Creates a box backed by the texture identified by [textureId].
+  TextureBox({ @required int textureId }) : assert(textureId != null), _textureId = textureId;
+
+  /// The identity of the backend texture.
+  int get textureId => _textureId;
+  int _textureId;
+  set textureId(int value) {
+    assert(value != null);
+    if (value != _textureId) {
+      _textureId = value;
+      markNeedsPaint();
+    }
+  }
+
+  @override
+  bool get sizedByParent => true;
+
+  @override
+  bool get alwaysNeedsCompositing => true;
+
+  @override
+  bool get isRepaintBoundary => true;
+
+  @override
+  void performResize() {
+    size = constraints.biggest;
+  }
+
+  @override
+  bool hitTestSelf(Offset position) {
+    return true;
+  }
+
+  @override
+  void paint(PaintingContext context, Offset offset) {
+    if (_textureId == null)
+      return;
+    context.addLayer(new TextureLayer(
+      rect: new Rect.fromLTWH(offset.dx, offset.dy, size.width, size.height),
+      textureId: _textureId,
+    ));
+  }
+}

packages/flutter/lib/src/widgets/texture.dart

+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:flutter/rendering.dart';
+import 'package:flutter/foundation.dart';
+import 'framework.dart';
+
+/// A rectangle upon which a backend texture is mapped.
+///
+/// Backend textures are images that can be applied (mapped) to an area of the
+/// Flutter view. They are created, managed, and updated using a
+/// platform-specific texture registry. This is typically done by a plugin
+/// that integrates with host platform video player, camera, or OpenGL APIs,
+/// or similar image sources.
+///
+/// A texture widget refers to its backend texture using an integer ID. Texture
+/// IDs are obtained from the texture registry and are scoped to the Flutter
+/// view. Texture IDs may be reused after deregistration, at the discretion
+/// of the registry. The use of texture IDs currently unknown to the registry
+/// will silently result in a blank rectangle.
+///
+/// Texture widgets are repainted autonomously as dictated by the backend (e.g.
+/// on arrival of a video frame). Such repainting generally does not involve
+/// executing Dart code.
+///
+/// The size of the rectangle is determined by its parent widget, and the
+/// texture is automatically scaled to fit.
+///
+/// See also:
+///
+/// * <https://docs.flutter.io/javadoc/io/flutter/view/TextureRegistry.html>
+///   for how to create and manage backend textures on Android.
+/// * <https://docs.flutter.io/objcdoc/Protocols/FlutterTextureRegistry.html>
+///   for how to create and manage backend textures on iOS.
+class Texture extends LeafRenderObjectWidget {
+  /// Creates a widget backed by the texture identified by [textureId].
+  const Texture({ Key key, @required this.textureId }): assert(textureId != null), super(key: key);
+
+  /// The identity of the backend texture.
+  final int textureId;
+
+  @override
+  TextureBox createRenderObject(BuildContext context) => new TextureBox(textureId: textureId);
+
+  @override
+  void updateRenderObject(BuildContext context, TextureBox renderObject) {
+    renderObject.textureId = textureId;
+  }
+}

packages/flutter/lib/widgets.dart

@@ -87,6 +87,7 @@ export 'src/widgets/status_transitions.dart';
 export 'src/widgets/table.dart';
 export 'src/widgets/text.dart';
 export 'src/widgets/text_selection.dart';
+export 'src/widgets/texture.dart';
 export 'src/widgets/ticker_provider.dart';
 export 'src/widgets/title.dart';
 export 'src/widgets/transitions.dart';