compositor

package
v0.1.48 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 27, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package compositor provides a Layer Tree for retained-mode rendering.

STATUS: NOT IN PRODUCTION PIPELINE. This package is fully implemented and tested but not connected to desktop.draw(). The production pipeline uses per-boundary GPU textures (Phase 7) which bypasses the Layer Tree for simpler direct texture caching + blit. This package is retained as infrastructure for future optimizations: animated transforms on cached textures, opacity blending layers, clip masking without re-recording.

Each [RepaintBoundary] widget creates a [PictureLayer] that owns a scene.Scene display list. The Compositor assembles all layers into a composed scene by REFERENCE (not copy), so when a child layer is re-recorded, the parent automatically sees fresh content.

This is the Flutter rendering/layer.dart pattern:

  • ContainerLayer: has children, no own content
  • [OffsetLayer]: ContainerLayer + translation offset
  • [PictureLayer]: owns a scene.Scene, leaf node
  • [ClipRectLayer]: ContainerLayer + clip rectangle
  • [OpacityLayer]: ContainerLayer + alpha blending

See: ADR-007 Phase 5 (docs/dev/architecture/ADR-007-RETAINED-MODE-COMPOSITOR.md) Task: TASK-UI-OPT-005-compositor-integration (backlog — connect or remove)

ADR-007 Phase 5 | Flutter rendering/layer.dart

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ClipRectLayerImpl 

type ClipRectLayerImpl struct {
	// contains filtered or unexported fields
}

ClipRectLayerImpl is a container layer with a clip rectangle.

Flutter equivalent: ClipRectLayer. Used by ScrollView to clip content to the viewport bounds.

func NewClipRectLayer 

func NewClipRectLayer(clip geometry.Rect) *ClipRectLayerImpl

NewClipRectLayer creates a new ClipRectLayer with the given clip bounds.

func (*ClipRectLayerImpl) Append 

func (l *ClipRectLayerImpl) Append(child Layer)

func (*ClipRectLayerImpl) Children 

func (c *ClipRectLayerImpl) Children() []Layer

func (*ClipRectLayerImpl) ClipRect 

func (l *ClipRectLayerImpl) ClipRect() geometry.Rect

func (*ClipRectLayerImpl) Remove 

func (c *ClipRectLayerImpl) Remove(child Layer)

func (*ClipRectLayerImpl) RemoveAll 

func (c *ClipRectLayerImpl) RemoveAll()

func (*ClipRectLayerImpl) SetClipRect 

func (l *ClipRectLayerImpl) SetClipRect(r geometry.Rect)

type Compositor 

type Compositor struct {
	// contains filtered or unexported fields
}

Compositor assembles a layer tree into a composed scene.Scene by walking layers and appending their content by REFERENCE (AppendWithTranslation), not by copying the entire encoding into a flat scene.

NOT IN PRODUCTION PIPELINE: the production render loop (desktop.draw) uses direct per-boundary GPU textures instead. Compositor is retained for future use with animated transforms and opacity layers.

Flutter equivalent: SceneBuilder in compositeFrame().

func New 

func New() *Compositor

New creates a new Compositor.

func (*Compositor) Compose 

func (c *Compositor) Compose(root Layer) *scene.Scene

Compose walks the layer tree rooted at root and builds a composed scene.Scene by appending each PictureLayer's scene at its accumulated offset. The composed scene is returned for rendering.

This is called every frame. The cost is O(layers), not O(draw_commands). For 10 boundaries: 10 AppendWithTranslation calls. The actual scene data is not re-recorded — only references are assembled.

Flutter equivalent: compositeFrame() → SceneBuilder.addRetained().

func (*Compositor) ComposedScene 

func (c *Compositor) ComposedScene() *scene.Scene

ComposedScene returns the last composed scene without re-composing. Returns nil if Compose has not been called.

type ContainerLayer 

type ContainerLayer interface {
	Layer

	// Children returns the ordered list of child layers.
	Children() []Layer

	// Append adds a child layer to the end of the children list.
	Append(child Layer)

	// Remove removes a child layer from the children list.
	Remove(child Layer)

	// RemoveAll removes all child layers.
	RemoveAll()
}

ContainerLayer is a layer that contains child layers.

Flutter equivalent: ContainerLayer (rendering/layer.dart). Used as base for OffsetLayer, ClipRectLayer, OpacityLayer.

type ExternalTextureLayer added in v0.1.48 

type ExternalTextureLayer struct {
	// contains filtered or unexported fields
}

ExternalTextureLayer holds a GPU texture provided by an external renderer (3D viewport, video player, custom shader). Unlike PictureLayerImpl which replays a recorded scene, ExternalTextureLayer composites a pre-rendered texture directly.

This is the Flutter Texture widget pattern: an external producer renders into an offscreen texture, and the compositor blits it at the layer's position during composition. The texture is owned externally (by the viewport widget) and must remain valid until the layer is removed from the tree.

Enterprise references:

  • Flutter: TextureLayer (rendering/layer.dart)
  • Android: TextureView (android.view.TextureView)
  • Chrome: TextureLayer (cc/layers/texture_layer.h)

func NewExternalTextureLayer added in v0.1.48 

func NewExternalTextureLayer(texture gpucontext.TextureView, width, height int, screenX, screenY float64) *ExternalTextureLayer

NewExternalTextureLayer creates a new ExternalTextureLayer with the given texture, dimensions, and screen position. The texture must remain valid for the lifetime of this layer.

func (*ExternalTextureLayer) ClearNeedsCompositing added in v0.1.48 

func (l *ExternalTextureLayer) ClearNeedsCompositing()

func (*ExternalTextureLayer) Height added in v0.1.48 

func (l *ExternalTextureLayer) Height() int

Height returns the texture height in logical pixels.

func (*ExternalTextureLayer) MarkNeedsCompositing added in v0.1.48 

func (l *ExternalTextureLayer) MarkNeedsCompositing()

func (*ExternalTextureLayer) NeedsCompositing added in v0.1.48 

func (l *ExternalTextureLayer) NeedsCompositing() bool

func (*ExternalTextureLayer) Offset added in v0.1.48 

func (l *ExternalTextureLayer) Offset() geometry.Point

func (*ExternalTextureLayer) Parent added in v0.1.48 

func (l *ExternalTextureLayer) Parent() ContainerLayer

func (*ExternalTextureLayer) SetOffset added in v0.1.48 

func (l *ExternalTextureLayer) SetOffset(o geometry.Point)

func (*ExternalTextureLayer) SetParent added in v0.1.48 

func (l *ExternalTextureLayer) SetParent(p ContainerLayer)

func (*ExternalTextureLayer) SetSize added in v0.1.48 

func (l *ExternalTextureLayer) SetSize(w, h int)

SetSize updates the texture dimensions. Marks the layer as needing re-composition.

func (*ExternalTextureLayer) SetTexture added in v0.1.48 

func (l *ExternalTextureLayer) SetTexture(tv gpucontext.TextureView)

SetTexture updates the external GPU texture view. Marks the layer as needing re-composition.

func (*ExternalTextureLayer) Texture added in v0.1.48 

func (l *ExternalTextureLayer) Texture() gpucontext.TextureView

Texture returns the external GPU texture view.

func (*ExternalTextureLayer) Width added in v0.1.48 

func (l *ExternalTextureLayer) Width() int

Width returns the texture width in logical pixels.

func (*ExternalTextureLayer) X added in v0.1.48 

func (l *ExternalTextureLayer) X() float64

X returns the screen-space X position for texture blitting.

func (*ExternalTextureLayer) Y added in v0.1.48 

func (l *ExternalTextureLayer) Y() float64

Y returns the screen-space Y position for texture blitting.

type Layer 

type Layer interface {
	// Parent returns the parent layer, or nil for the root.
	Parent() ContainerLayer

	// SetParent sets the parent layer. Called by ContainerLayer.Append/Remove.
	SetParent(parent ContainerLayer)

	// Offset returns this layer's translation offset relative to parent.
	Offset() geometry.Point

	// SetOffset sets the translation offset. When offset changes on an
	// OffsetLayer, no re-record is needed — the compositor applies the
	// new offset during composition (Flutter animated transform).
	SetOffset(offset geometry.Point)

	// NeedsCompositing reports whether this layer or any descendant
	// needs to be re-composited into the parent scene.
	NeedsCompositing() bool

	// MarkNeedsCompositing marks this layer as needing re-composition.
	MarkNeedsCompositing()

	// ClearNeedsCompositing resets the compositing flag after composition.
	ClearNeedsCompositing()
}

Layer is a node in the compositor layer tree.

Flutter equivalent: rendering/layer.dart Layer class. Each Layer has a parent and can be attached/detached from the tree.

type OffsetLayerImpl 

type OffsetLayerImpl struct {
	// contains filtered or unexported fields
}

OffsetLayerImpl is a container layer with a translation offset.

Flutter equivalent: OffsetLayer. Each RepaintBoundary creates one. The offset is the widget's screen position. When the widget moves (e.g., scroll), only the offset changes — no re-record needed.

func NewOffsetLayer 

func NewOffsetLayer(offset geometry.Point) *OffsetLayerImpl

NewOffsetLayer creates a new OffsetLayer at the given offset.

func (*OffsetLayerImpl) Append 

func (l *OffsetLayerImpl) Append(child Layer)

func (*OffsetLayerImpl) Children 

func (c *OffsetLayerImpl) Children() []Layer

func (*OffsetLayerImpl) Remove 

func (c *OffsetLayerImpl) Remove(child Layer)

func (*OffsetLayerImpl) RemoveAll 

func (c *OffsetLayerImpl) RemoveAll()

type OpacityLayerImpl 

type OpacityLayerImpl struct {
	// contains filtered or unexported fields
}

OpacityLayerImpl is a container layer with an opacity value.

Flutter equivalent: OpacityLayer. Changing opacity does NOT trigger re-record of children — compositor applies alpha.

func NewOpacityLayer 

func NewOpacityLayer(opacity float32) *OpacityLayerImpl

NewOpacityLayer creates a new OpacityLayer with the given alpha (0-1).

func (*OpacityLayerImpl) Append 

func (l *OpacityLayerImpl) Append(child Layer)

func (*OpacityLayerImpl) Children 

func (c *OpacityLayerImpl) Children() []Layer

func (*OpacityLayerImpl) Opacity 

func (l *OpacityLayerImpl) Opacity() float32

func (*OpacityLayerImpl) Remove 

func (c *OpacityLayerImpl) Remove(child Layer)

func (*OpacityLayerImpl) RemoveAll 

func (c *OpacityLayerImpl) RemoveAll()

func (*OpacityLayerImpl) SetOpacity 

func (l *OpacityLayerImpl) SetOpacity(a float32)

type PictureLayerImpl 

type PictureLayerImpl struct {
	// contains filtered or unexported fields
}

PictureLayerImpl owns a scene.Scene display list. Leaf node.

Flutter equivalent: PictureLayer. Contains the recorded draw commands from a RepaintBoundary's subtree.

Phase D fields (boundaryCacheKey, isRoot, width, height) link this layer to the per-boundary GPU texture cache in renderLoop. BuildLayerTree populates them; compositeTexturesFromTree reads them.

func NewPictureLayer 

func NewPictureLayer() *PictureLayerImpl

NewPictureLayer creates a new PictureLayer (initially dirty, no picture).

func (*PictureLayerImpl) BoundaryCacheKey added in v0.1.20 

func (l *PictureLayerImpl) BoundaryCacheKey() uint64

BoundaryCacheKey returns the unique ID linking this layer to the per-boundary GPU texture cache. Set by BuildLayerTree.

func (*PictureLayerImpl) ClearDirty 

func (l *PictureLayerImpl) ClearDirty()

func (*PictureLayerImpl) ClearNeedsCompositing 

func (l *PictureLayerImpl) ClearNeedsCompositing()

func (*PictureLayerImpl) HasPictureClip added in v0.1.20 

func (l *PictureLayerImpl) HasPictureClip() bool

HasPictureClip reports whether a compositor clip is set on this layer.

func (*PictureLayerImpl) IsDirty 

func (l *PictureLayerImpl) IsDirty() bool

func (*PictureLayerImpl) IsRoot added in v0.1.20 

func (l *PictureLayerImpl) IsRoot() bool

IsRoot reports whether this PictureLayer represents the root boundary. The root uses DrawGPUTextureBase (background), others use DrawGPUTexture.

func (*PictureLayerImpl) IsScreenOriginValid added in v0.1.20 

func (l *PictureLayerImpl) IsScreenOriginValid() bool

IsScreenOriginValid reports whether ScreenOrigin was populated.

func (*PictureLayerImpl) MarkDirty 

func (l *PictureLayerImpl) MarkDirty()

func (*PictureLayerImpl) MarkNeedsCompositing 

func (l *PictureLayerImpl) MarkNeedsCompositing()

func (*PictureLayerImpl) NeedsCompositing 

func (l *PictureLayerImpl) NeedsCompositing() bool

func (*PictureLayerImpl) Offset 

func (l *PictureLayerImpl) Offset() geometry.Point

func (*PictureLayerImpl) Parent 

func (l *PictureLayerImpl) Parent() ContainerLayer

func (*PictureLayerImpl) Picture 

func (l *PictureLayerImpl) Picture() *scene.Scene

func (*PictureLayerImpl) PictureClipRect added in v0.1.20 

func (l *PictureLayerImpl) PictureClipRect() geometry.Rect

PictureClipRect returns the compositor clip rectangle for viewport culling.

func (*PictureLayerImpl) SceneVersion added in v0.1.20 

func (l *PictureLayerImpl) SceneVersion() uint64

SceneVersion returns the monotonic scene cache version from the source boundary widget. Used by renderBoundaryTexturesFromTree to detect fresh recordings without accessing the widget tree.

func (*PictureLayerImpl) ScreenOrigin added in v0.1.20 

func (l *PictureLayerImpl) ScreenOrigin() geometry.Point

ScreenOrigin returns the screen-space position for texture blitting.

func (*PictureLayerImpl) SetBoundaryCacheKey added in v0.1.20 

func (l *PictureLayerImpl) SetBoundaryCacheKey(k uint64)

SetBoundaryCacheKey stores the boundary's unique cache key.

func (*PictureLayerImpl) SetOffset 

func (l *PictureLayerImpl) SetOffset(o geometry.Point)

func (*PictureLayerImpl) SetParent 

func (l *PictureLayerImpl) SetParent(p ContainerLayer)

func (*PictureLayerImpl) SetPicture 

func (l *PictureLayerImpl) SetPicture(s *scene.Scene)

func (*PictureLayerImpl) SetPictureClipRect added in v0.1.20 

func (l *PictureLayerImpl) SetPictureClipRect(r geometry.Rect)

SetPictureClipRect stores the compositor clip from the boundary widget.

func (*PictureLayerImpl) SetRoot added in v0.1.20 

func (l *PictureLayerImpl) SetRoot(v bool)

SetRoot marks this layer as the root boundary.

func (*PictureLayerImpl) SetSceneVersion added in v0.1.20 

func (l *PictureLayerImpl) SetSceneVersion(v uint64)

SetSceneVersion stores the boundary widget's SceneCacheVersion.

func (*PictureLayerImpl) SetScreenOrigin added in v0.1.20 

func (l *PictureLayerImpl) SetScreenOrigin(p geometry.Point)

SetScreenOrigin stores the screen-space position from the boundary widget.

func (*PictureLayerImpl) SetSize added in v0.1.20 

func (l *PictureLayerImpl) SetSize(w, h int)

SetSize stores the boundary dimensions.

func (*PictureLayerImpl) Size added in v0.1.20 

func (l *PictureLayerImpl) Size() (int, int)

Size returns the boundary dimensions in logical pixels.

type PictureOwner 

type PictureOwner interface {
	// Picture returns the scene.Scene owned by this layer.
	// Returns nil if the layer has not been recorded yet.
	Picture() *scene.Scene

	// SetPicture stores a recorded scene. Called after recording a
	// RepaintBoundary's subtree via SceneCanvas.
	SetPicture(s *scene.Scene)

	// IsDirty reports whether the picture needs re-recording.
	IsDirty() bool

	// MarkDirty marks the picture as needing re-recording.
	MarkDirty()

	// ClearDirty resets the dirty flag after re-recording.
	ClearDirty()
}

PictureOwner is implemented by layers that own a scene.Scene (display list).

Flutter equivalent: PictureLayer.picture.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.