ExternalTexture class Assets and loading

A live TextureSource fed by a platform texture, so video, camera preview, and any other native producer can be sampled by scene materials.

Point it at the texture id a plugin registered with Flutter's texture registry and assign it to a material slot. The frame is captured through the same compositor path the Texture widget draws with, so whatever the platform hands over (an Android external OES texture, a biplanar NV12 buffer) arrives here as an ordinary RGBA texture that any material can sample.

final video = ExternalTexture(
  textureId: id,
  width: 1920,
  height: 1080,
);
material.baseColorTexture = video;
// ... later
video.dispose();

sampledTexture is null until the first capture completes, and the texture object is replaced on every capture, so read it through the TextureSource each frame rather than caching it. Listeners fire after each new frame is published.

Captures are driven by drawing rather than by a ticker, so a source nothing samples costs nothing, and a source sampled every frame keeps up on its own. They are throttled to one in flight, so a source producing frames faster than they can be captured skips ahead to the latest instead of queueing.

The capture is top-down (v of 0 is the top of the source), matching Texture2D.

Getting a texture id out of a plugin is not always possible. Some plugins render through a platform view instead and expose no id, and some keep the id private. Capture a WidgetTexture around the plugin's own preview widget in that case; it costs an extra layout and paint but works for any widget.

Platform support follows the engine's ability to resolve a texture id outside a live frame. Android works. The web has no platform textures at all. macOS and iOS currently capture an empty frame, because the engine resolves external textures for a snapshot without an Impeller context and falls back to a Skia path that is inactive under Impeller; a debug build warns when it sees this. Use a WidgetTexture around the plugin's preview widget where that matters.

Inheritance
Implemented types

Constructors

ExternalTexture({int? textureId, required int width, required int height, ExternalTextureUpdate update = ExternalTextureUpdate.everyFrame, ExternalTextureSampling sampling = const ExternalTextureSampling(), ColorFilter? colorFilter})
Creates a source capturing textureId at width x height pixels.

Properties

captureCount → int
Total completed captures, for diagnostics.
no setter
colorFilter ↔ ColorFilter?
Optional color filter applied to the captured texture (for example color inversion or channel swizzling).
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
hasListeners → bool
Whether any listeners are currently registered.
no setterinherited
height → int
The capture height in pixels.
no setter
lastCaptureDuration → Duration
Wall-clock duration of the last capture, for diagnostics.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sampledSampler → SamplerOptions
The sampler this source is bound with.
no setteroverride
sampledTexture → Texture?
The frame to sample this draw, kicking off the next capture when one is due. Capture is driven from here rather than from a ticker, so a source nothing samples costs nothing.
no setteroverride
sampling ↔ ExternalTextureSampling
Sampling options used when a material samples this source.
getter/setter pair
texture → Texture?
The most recent frame, or null before the first capture completes.
no setter
textureId ↔ int?
The platform texture id being captured, or null if none is set yet.
getter/setter pair
update ↔ ExternalTextureUpdate
When this source re-captures. See ExternalTextureUpdate.
getter/setter pair
width → int
The capture width in pixels.
no setter

Methods

addListener(VoidCallback listener) → void
Register a closure to be called when the object changes.
inherited
dispose() → void
Discards any resources used by the object.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Call all the registered listeners.
inherited
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
requestCapture() → void
Captures on the next draw that samples this source. The trigger for ExternalTextureUpdate.manual; under the other policies it skips ahead of the schedule.
resize(int width, int height) → void
Captures at a new size. Takes effect on the next capture.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited