[Feature] DrawingRecording

[Gillibald]

What does the pull request do?

Adds DrawingRecording: a retained draw list that is recorded once and replayed cheaply, optionally bound to a compositor so it animates without being re-recorded, and optionally hosted as a composition visual so it animates entirely on the render thread.

Avalonia has no cheap retained-drawing primitive today. DrawingGroup re-walks a managed object tree on every draw, and a RenderTargetBitmap is rasterized at a fixed resolution and stops being vector content. Anything that draws the same vector content repeatedly - an icon set, a symbol reused many times in one document, a vector image drawn at several sizes, an animated vector document - pays full re-emission on every frame, and there is no way to hand a recorded drawing to the compositor at all.

Alongside the recording primitive:

• DrawingRecordingBrush, a TileBrush that paints with an existing recording instead of re-recording a Drawing per compositor, the way DrawingBrush does.
• Composition brushes (CompositionSolidColorBrush, the composition gradient brushes) work inside a compositor-bound recording, so a recorded fill can be animated from the render thread.
• CompositionRecordingVisual, so a recording can be attached to a control as a child visual and animated server-side.

What drives it is SVG support: a document compiles once into a recording, replays shared sub-recordings at every use site, and animates paint through mutable brushes and structure through composition visuals. COLRv1 color-font rendering wants the same shape, a glyph's paint graph recorded once and replayed at every instance.

None of the API is specific to either. The recording primitive serves icon systems, chart and diagram renderers, and any control that draws the same vector content repeatedly.

What is the updated/expected behavior with this PR?

Record once and replay, with no re-emission per draw:

// Immutable: brushes and pens are snapshotted at record time.
var recording = DrawingRecording.Create(ctx =>
    ctx.DrawRectangle(Brushes.Crimson, null, new Rect(20, 20, 60, 60)));

context.DrawRecording(recording);                     // replay
context.DrawRecording(recording, Matrix.CreateScale(2, 2));   // replay transformed

Bind it to a compositor and mutable brushes animate without re-recording:

var brush = new SolidColorBrush(Colors.Red);
var recording = DrawingRecording.Create(compositor, ctx =>
    ctx.DrawEllipse(brush, null, bounds));

brush.Color = Colors.Blue;   // tracked; the recording is not rebuilt

Paint an area with a recording, tiled by the usual TileBrush properties:

var brush = new DrawingRecordingBrush(recording)
{
    TileMode = TileMode.FlipXY,
    DestinationRect = new RelativeRect(0, 0, 0.25, 0.25, RelativeUnit.Relative)
};

Host it as a composition visual and it animates on the render thread, with no per-frame UI-thread work:

var visual = compositor.CreateRecordingVisual();
visual.Recording = recording;                          // must share the compositor
ElementComposition.SetElementChildVisual(control, visual);

var spin = compositor.CreateScalarKeyFrameAnimation();
spin.InsertKeyFrame(0f, 0f);
spin.InsertKeyFrame(1f, (float)(Math.PI * 2));
spin.IterationBehavior = AnimationIterationBehavior.Forever;
visual.StartAnimation("RotationAngle", spin);

How was the solution implemented (if it's not obvious)?

Recording. DrawingRecording.Create(...) runs the caller's callback against RenderDataDrawingContext, a DrawingContext that records draw operations as nodes instead of rasterizing them. The immutable overload snapshots brushes, pens and effects at record time and rejects content it cannot snapshot; the compositor-bound overload registers mutable resources as composition resources instead, so later mutation is change-tracked. Nested recordings are referenced and ref-counted rather than copied, and DrawingRecordingOwnership lets a parent recording take over disposal of a child.

Replay and the client/server bounds split. Each node exposes both a client Bounds (UI thread, may read live mutable resources) and a ServerBounds (render thread, immutable data and server shadows only). That split is what lets an animated pen thickness keep the server-side bounds current without re-recording anything.

Composition brushes need no new invalidation mechanism. A recording's server render data already observes every server resource in its stream, and a recording visual already observes that render data, so a composition brush change repaints the visuals showing the recording exactly like a tracked mutable Media brush does. Immutable recordings keep rejecting composition brushes, since no immutable form of one exists; the exception now points at the compositor-bound Create overload.

Composition hosting. Compositor.CreateRecordingVisual() produces a CompositionRecordingVisual, which renders one compositor-bound recording behind its children. It serializes a reference to the recording's server render data rather than the draw items, and the server visual observes that render data instead of owning it. Combined with the animatable visual properties this moves retained content entirely onto the render thread. The internal Image-side hosting that lets an IImage render as a composition visual subtree ships as its own follow-up PR.

Checklist

• Added unit tests (if possible)?
• Added XML documentation to any related classes?
• Consider submitting a PR to https://github.com/AvaloniaUI/avalonia-docs with user documentation

Breaking changes

One, needing a core-team call given the API freeze:

1. CompositionVisual.ClipToBounds now defaults to false (was true), matching Visual.ClipToBounds and UWP composition semantics. The renderer sets it explicitly on element visuals every sync, so element visuals are unaffected. The old default combined with the (0,0) Size default gave every directly created visual an empty own-clip rect, which nulled its subtree bounds and made the render pass cull it and its children - a visual attached with ElementComposition.SetElementChildVisual never rendered unless Size was set explicitly.

Two smaller behavioral changes, both turning a failure into the useful result:

• BrushExtensions.ToImmutable handles scene brushes. Brush implements neither IMutableBrush nor IImmutableBrush, so the old body's (IImmutableBrush)brush cast threw InvalidCastException for VisualBrush and DrawingBrush. It now returns an immutable snapshot of the scene brush's current content, with tile-brush properties captured at call time, or Brushes.Transparent when the brush has no content.
• ElementComposition.SetElementChildVisual un-parents the previous child eagerly. The renderer sync that would reconcile children may never run again for that element - clearing the child visual from OnDetachedFromVisualTree runs before DetachFromCompositor discards the element's composition visual - and the stale parenting made any later attach throw.

No backend has to change: nothing is added to IDrawingContextImpl, and replay goes through the existing operations. (Backend interfaces are [Unstable] and not stable API, so this is a note about the work being self-contained, not about avoiding a break.)

Obsoletions / Deprecations

None.

Fixed issues

[avaloniaui-bot]

You can test this PR using the following package version. 12.2.999-cibuild0068786-alpha. (feed url: https://nuget-feed-all.avaloniaui.net/v3/index.json) [PRBUILDID]

[robloo]

Not to get hung up on the naming right away but DrawingRecording sounds like something completely different. A DrawingRecording sounds like it's recording events from the pointer to recreate an image drawn by the user. Not encapsulating the commands necessary to re-draw geometry and bitmaps. I understand they are conceptually similar but the nuance is important in naming here.

Why not something like:

1. DrawingTemplate or
2. DrawingStream ... (StreamDrawing would match StreamGeometry)
3. DrawingCommands even DrawingInstructions

[Gillibald]

Not to get hung up on the naming right away but DrawingRecording sounds like something completely different. A DrawingRecording sounds like it's recording events from the pointer to recreate an image drawn by the user. Not encapsulating the commands necessary to re-draw geometry and bitmaps. I understand they are conceptually similar but the nuance is important in naming here.

Why not something like:

1. DrawingTemplate or
2. DrawingStream ... (StreamDrawing would match StreamGeometry)
3. DrawingCommands even DrawingInstructions

We record a drawing, so I chose that name. Look at the family of classes that are related to that type: DrawingRecordingBrush, CompositionRecordingVisual, CreateRecordingVisual, DrawRecording, DrawingRecordingOwnership. Would your suggestion fit here? The term Drawing is already part of the framework.

[robloo]

I'll compare names when I have a chance. But it looks like this concept already exists in DirectX 11+ as well:

• https://learn.microsoft.com/en-us/windows/win32/api/d3d11/nn-d3d11-id3d11commandlist

DrawingCommands would be the closest .NET naming equivalent I think. This is also assuming a "drawing" encompasses vector geometries as well as bitmaps together. Otherwise "drawing" is overly general.

Anyway, I'll try to look at this more soon.