compositor

package
v0.1.27 Latest Latest
Warning

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

 Go to latest Published: May 16, 2026 License: MIT Imports: 2 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 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.