Microsoft.UI.Reactor.Advanced 0.1.0-preview.5

Microsoft.UI.Reactor.Advanced

Optional Reactor components with heavier native and graphics dependencies — starting with a Win2D canvas family for immediate-mode drawing inside a Reactor element tree.

About

Microsoft.UI.Reactor.Advanced extends Microsoft.UI.Reactor with components that pull in larger native or graphics stacks. Its first surface is a Win2D canvas family (manual, animated, and virtual) that lets you draw with CanvasDrawingSession directly from a declarative Reactor component.

This package is intentionally separate from the core framework so that apps which don't need Win2D keep their trim/AOT closure and native payload isolated.

How to Use

Install the package alongside Microsoft.UI.Reactor:

dotnet add package Microsoft.UI.Reactor.Advanced

Drop a Win2D canvas into any component. The onDraw callback runs on the UI thread with a CanvasDrawingSession; pass a redrawKey to trigger invalidation when your state changes:

using Microsoft.UI.Reactor;
using Microsoft.UI.Reactor.Core;
using Windows.UI;
using static Microsoft.UI.Reactor.Factories;          // core DSL
using static Microsoft.UI.Reactor.Advanced.Factories; // Win2D DSL

internal sealed class CanvasDemo : Component
{
    public override Element Render()
    {
        var (radius, setRadius) = UseState(40f);

        return VStack(12,
            Win2DCanvas(
                onDraw: (session, args) =>
                {
                    session.Clear(Colors.Black);
                    session.FillCircle(120, 120, radius, Colors.DeepSkyBlue);
                },
                redrawKey: radius),
            Button("Grow", () => setRadius(radius + 10f))
        ).Padding(24);
    }
}

When radius changes, the new redrawKey tells Reactor to invalidate the canvas and redraw.

Key Features

• Win2DCanvas — manual-invalidate canvas (CanvasControl); redraws when its redrawKey changes.
• Win2DAnimatedCanvas — game-loop canvas (CanvasAnimatedControl) whose update and draw callbacks run on the Win2D game thread.
• Win2DVirtualCanvas — virtualized canvas (CanvasVirtualControl) for very large drawing surfaces.
• Async resource creation — overloads accept an onCreateResources callback tracked by Win2D for loading bitmaps and other device resources.
• Isolated native payload — keeps Win2D out of the core framework's trim/AOT closure.

Main Types

• Win2DCanvas(...) — factory for a manual-invalidate Win2D canvas.
• Win2DAnimatedCanvas(...) — factory for an animated game-loop canvas.
• Win2DVirtualCanvas(...) — factory for a virtualized canvas.
• Win2DCanvasElement — immutable element produced by Win2DCanvas.

Best Practices

• Drive redraws with redrawKey. Pass the state that affects the drawing (or a composite of it) as redrawKey. The canvas only invalidates when the key changes, so avoid allocating a new key object on every render when nothing changed.
• Create device resources in onCreateResources, not onDraw. Load bitmaps and other GPU resources in the resource callback so they survive device-lost events; the onDraw callback should stay allocation-free and fast.
• Mind the thread for animated canvases. Win2DAnimatedCanvas invokes onUpdate/onDraw on the Win2D game thread, not the UI thread. Don't touch Reactor component state directly from those callbacks — pass data in through drawState and marshal back with a threadSafe: true state setter if you need to update the UI.
• Keep Win2D optional. Reference this package only from the projects that need it so apps that don't draw keep a smaller trim/AOT closure and native payload.

Additional Documentation

• Win2D canvas guide
• Samples
• Win2D documentation

Related Packages

• Microsoft.UI.Reactor — the core declarative WinUI 3 framework (required).
• Microsoft.UI.Reactor.Devtools — optional developer-loop devtools host.
• Microsoft.UI.Reactor.ProjectTemplates — dotnet new templates.

Feedback & Contributing

Microsoft.UI.Reactor.Advanced is part of the open-source Reactor project. File issues, ask questions, and contribute on GitHub. See CONTRIBUTING.md to get started.

Support Policy

This package is currently released as a preview and is provided under the MIT License. APIs may change between preview releases.