texture.dart 2.91 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30
// 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 '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:
///
31
///  * [TextureRegistry](/javadoc/io/flutter/view/TextureRegistry.html)
32
///    for how to create and manage backend textures on Android.
33
///  * [TextureRegistry Protocol](/ios-embedder/protocol_flutter_texture_registry-p.html)
34
///    for how to create and manage backend textures on iOS.
35
class Texture extends LeafRenderObjectWidget {
36 37
  /// Creates a widget backed by the texture identified by [textureId], and use
  /// [filterQuality] to set texture's [FilterQuality].
38
  const Texture({
39
    super.key,
40
    required this.textureId,
41
    this.freeze = false,
42
    this.filterQuality = FilterQuality.low,
43
  });
44 45 46 47

  /// The identity of the backend texture.
  final int textureId;

48 49 50
  /// When true the texture will not be updated with new frames.
  final bool freeze;

51
  /// {@template flutter.widgets.Texture.filterQuality}
52 53 54 55 56 57 58 59 60
  /// The quality of sampling the texture and rendering it on screen.
  ///
  /// When the texture is scaled, a default [FilterQuality.low] is used for a higher quality but slower
  /// interpolation (typically bilinear). It can be changed to [FilterQuality.none] for a lower quality but
  /// faster interpolation (typically nearest-neighbor). See also [FilterQuality.medium] and
  /// [FilterQuality.high] for more options.
  /// {@endtemplate}
  final FilterQuality filterQuality;

61
  @override
62
  TextureBox createRenderObject(BuildContext context) => TextureBox(textureId: textureId, freeze: freeze, filterQuality: filterQuality);
63 64 65 66

  @override
  void updateRenderObject(BuildContext context, TextureBox renderObject) {
    renderObject.textureId = textureId;
67
    renderObject.freeze = freeze;
68
    renderObject.filterQuality = filterQuality;
69 70
  }
}