Documentation
¶
Overview ¶
Package viewport3d provides a GPU-rendered viewport widget for 3D content, video playback, or custom shader output.
Viewport3D uses the Flutter Texture widget pattern: the widget owns an offscreen GPU texture, an external renderer (e.g., g3d.Renderer, a video decoder, a compute shader) draws into it, and the Layer Tree compositor blits it to the surface via [compositor.ExternalTextureLayer].
Usage ¶
The widget does NOT import any specific 3D engine or renderer. Instead, the OnRender functional option takes a callback that receives the texture view, device, and queue as opaque handles. The consumer type-asserts to concrete types (e.g., *wgpu.Device, *wgpu.TextureView) as needed.
vp := viewport3d.New(
viewport3d.Size(640, 480),
viewport3d.OnRender(func(tv gpucontext.TextureView) {
// Render 3D scene, video frame, or shader output into tv.
}),
)
Continuous vs On-Demand Rendering ¶
By default, the viewport renders on-demand (only when explicitly invalidated via Widget.Invalidate). Use Continuous(true) for content that changes every frame (animations, real-time 3D).
Enterprise References ¶
- Flutter: TextureLayer (rendering/layer.dart), Texture widget (widgets/texture.dart)
- Android: TextureView (android.view.TextureView), SurfaceTexture
- Chrome: TextureLayer (cc/layers/texture_layer.h)
Index ¶
- type Option
- type Widget
- func (w *Widget) Accessible() a11y.Accessible
- func (w *Widget) Children() []widget.Widget
- func (w *Widget) Draw(ctx widget.Context, _ widget.Canvas)
- func (w *Widget) Event(_ widget.Context, _ event.Event) bool
- func (w *Widget) Invalidate()
- func (w *Widget) IsContinuous() bool
- func (w *Widget) Layout(_ widget.Context, constraints geometry.Constraints) geometry.Size
- func (w *Widget) Mount(_ widget.Context)
- func (w *Widget) Release()
- func (w *Widget) SetContinuous(v bool)
- func (w *Widget) Texture() gpucontext.TextureView
- func (w *Widget) Unmount()
- func (w *Widget) ViewportSize() (width, height int)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*config)
Option configures a Viewport3D widget during construction.
func Continuous ¶
Continuous sets whether the viewport re-renders every frame (true) or only on-demand when explicitly invalidated (false, default).
Use Continuous(true) for real-time 3D scenes, video playback, or any content that changes every frame. Use the default (false) for static content that only updates in response to explicit signals.
func OnRender ¶
func OnRender(fn func(view gpucontext.TextureView)) Option
OnRender sets the callback invoked each time the viewport needs to render a new frame. The callback receives the offscreen texture view that the producer should render into.
The callback is invoked during the Draw phase. The texture dimensions match the configured Size. The producer is responsible for issuing GPU commands that write to the provided texture view.
type Widget ¶
type Widget struct {
widget.WidgetBase
// contains filtered or unexported fields
}
Widget provides a GPU-rendered viewport for 3D content, video, or custom shader output. Uses the Flutter Texture widget pattern: the widget owns an offscreen GPU texture, an external renderer draws into it, and the Layer Tree compositor blits it to the surface.
The widget is a RepaintBoundary for compositor isolation — re-rendering the 3D content does not invalidate sibling widgets.
Widget implements widget.Lifecycle for GPU resource cleanup on unmount.
func (*Widget) Accessible ¶
func (w *Widget) Accessible() a11y.Accessible
Accessible returns accessibility information for the viewport.
func (*Widget) Draw ¶
Draw renders the viewport content. On the first call, the GPU texture is allocated via the Context's widget.GPUTextureProvider. On subsequent calls, the OnRender callback is invoked only when the viewport is dirty or in continuous mode.
func (*Widget) Invalidate ¶
func (w *Widget) Invalidate()
Invalidate marks the viewport as needing a re-render on the next frame. Use this for on-demand rendering when the external content has changed.
func (*Widget) IsContinuous ¶
IsContinuous reports whether the viewport renders every frame.
func (*Widget) Release ¶
func (w *Widget) Release()
Release frees the GPU texture. Must be called when the widget is removed from the tree to prevent resource leaks. Called automatically by Unmount.
func (*Widget) SetContinuous ¶
SetContinuous changes the continuous rendering mode at runtime.
func (*Widget) Texture ¶
func (w *Widget) Texture() gpucontext.TextureView
Texture returns the offscreen GPU texture view. Returns a nil/zero-value TextureView if the texture has not been initialized yet (before first Draw).
func (*Widget) Unmount ¶
func (w *Widget) Unmount()
Unmount is called when the widget is removed from the tree (Lifecycle interface). Frees the GPU texture to prevent resource leaks.
func (*Widget) ViewportSize ¶
ViewportSize returns the configured viewport dimensions.
Source Files