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
5import 'package:flutter/rendering.dart';
6import 'framework.dart';
7
8/// A rectangle upon which a backend texture is mapped.
9///
10/// Backend textures are images that can be applied (mapped) to an area of the
11/// Flutter view. They are created, managed, and updated using a
12/// platform-specific texture registry. This is typically done by a plugin
13/// that integrates with host platform video player, camera, or OpenGL APIs,
14/// or similar image sources.
15///
16/// A texture widget refers to its backend texture using an integer ID. Texture
17/// IDs are obtained from the texture registry and are scoped to the Flutter
18/// view. Texture IDs may be reused after deregistration, at the discretion
19/// of the registry. The use of texture IDs currently unknown to the registry
20/// will silently result in a blank rectangle.
21///
22/// Texture widgets are repainted autonomously as dictated by the backend (e.g.
23/// on arrival of a video frame). Such repainting generally does not involve
24/// executing Dart code.
25///
26/// The size of the rectangle is determined by its parent widget, and the
27/// texture is automatically scaled to fit.
28///
29/// See also:
30///
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.
35class Texture extends LeafRenderObjectWidget {
36 /// Creates a widget backed by the texture identified by [textureId], and use
37 /// [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 /// The identity of the backend texture.
46 final int textureId;
47
48 /// When true the texture will not be updated with new frames.
49 final bool freeze;
50
51 /// {@template flutter.widgets.Texture.filterQuality}
52 /// The quality of sampling the texture and rendering it on screen.
53 ///
54 /// When the texture is scaled, a default [FilterQuality.low] is used for a higher quality but slower
55 /// interpolation (typically bilinear). It can be changed to [FilterQuality.none] for a lower quality but
56 /// faster interpolation (typically nearest-neighbor). See also [FilterQuality.medium] and
57 /// [FilterQuality.high] for more options.
58 /// {@endtemplate}
59 final FilterQuality filterQuality;
60
61 @override
62 TextureBox createRenderObject(BuildContext context) =>
63 TextureBox(textureId: textureId, freeze: freeze, filterQuality: filterQuality);
64
65 @override
66 void updateRenderObject(BuildContext context, TextureBox renderObject) {
67 renderObject.textureId = textureId;
68 renderObject.freeze = freeze;
69 renderObject.filterQuality = filterQuality;
70 }
71}
72