reactor-advanced
Reactor.Advanced Win2D canvases — choosing Win2DCanvas, Win2DAnimatedCanvas, or Win2DVirtualCanvas; using UseDrawState, UseCanvasResources, UseDrawCommand; and following threading/device-loss rules.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 896
- Forks
- 67
01 前言 Front Matter
- name
- reactor-advanced
- description
- Reactor.Advanced Win2D canvases — choosing Win2DCanvas, Win2DAnimatedCanvas, or Win2DVirtualCanvas; using UseDrawState, UseCanvasResources, UseDrawCommand; and following threading/device-loss rules.
03 SKILL.md 正文
Reactor Advanced
Use this skill when adding immediate-mode Win2D drawing through Microsoft.UI.Reactor.Advanced. The full guide is docs/guide/win2d-canvas.md; the performance sample is samples/apps/particle-storm/.
Pick the right canvas
| Workload | Use | Why |
|---|---|---|
| Static or data-driven drawing that changes after state updates | Win2DCanvas.Of(onDraw, redrawKey) |
Manual invalidation; pass a changing RedrawKey for every value the draw callback reads. |
| Game loop, physics, particles, visualizers, steady FPS | Win2DAnimatedCanvas.Of(onUpdate, onDraw, drawState, isPaused) |
Win2D owns the tick and calls update/draw on the game thread. |
| Huge scrollable or tiled surfaces | Win2DVirtualCanvas.Of(onRegionDraw, contentSize) |
Draws only invalidated visible regions; update tiles by changing InvalidateRegions. |
Threading cheat sheet
| Callback | Thread | Rule |
|---|---|---|
Win2DCanvas.OnDraw |
UI thread | Safe to read Reactor state captured by render. |
Win2DAnimatedCanvas.OnUpdate / .OnDraw |
Win2D game thread | Do not touch WinUI controls. Use thread-safe data or UseState(threadSafe: true) for UI handoff. |
Win2DVirtualCanvas.OnRegionDraw |
UI thread | Keep work bounded to the invalidated region. |
UseCanvasResources factory |
Worker/game thread | Create device resources and return a disposable/recreatable object. |
Treat Ref.Current from UseDrawState like a volatile field. Re-read it and make the referenced object safe for any cross-thread mutation. Debug builds add a sentinel that appends docs/guide/win2d-canvas.md#threading to likely WinUI thread-affinity exceptions from animated callbacks.
Reference graph model
Element refs are reactive cells. .Ref(cell) writes the mounted
FrameworkElement into the cell and writes null on unmount.
Reference properties (TeachingTip.Target, .LabeledBy, .DescribedBy,
.FlowsTo, .FlowsFrom, .XYFocus*, and custom descriptor
.Reference / .ReferenceList) subscribe to those cells instead of
sampling .Current.
Resolution is one-way and push-based: cells enqueue dirty reference
edges during commit, then Reactor flushes the dirty set after the tree is
stable. Cycles are allowed because each property slot is a one-way edge.
List references preserve author declaration order and omit unresolved
targets. Advanced authors should use descriptor.Reference for regular
controls and binding.Reference only as the bridge for hand-coded
handlers.
Hooks and recipes
var state = ctx.UseDrawState(() => new ParticleField(20_000));
var sprite = ctx.UseCanvasResources<CanvasBitmap>(async device =>
await CanvasBitmap.LoadAsync(device, "Assets/particle.png"));
var draw = ctx.UseDrawCommand(model, static (session, args, m) =>
m.Render(session), deps: [model.Version]);
UseCanvasResources is the device-loss recipe: allocate from the supplied CanvasDevice, draw only when the returned ref is non-null, and let the hook dispose/recreate after CanvasDevice.DeviceLost.
Performance proof
The Particle Storm sample (samples/apps/particle-storm/) is the canonical pattern: pure Reactor chrome controls parameters; Win2DAnimatedCanvas renders the hot particle path; UseDrawState holds the particle buffers; UseCanvasResources owns sprites and other device resources.
04 同仓库更多 Skills
Charting
暂无简介
reactor-wrapping
Turn ANY WinUI control — a vendor/third-party control, your own custom Control, or a Windows Community Toolkit one — into a first-class declarative Reactor element with the [GenerateReactorWrapper] source generator, zero hand-written wrapper code. Covers auto-inference (props, content, two-way pairs, panel/items children, events), the [Wrap*] annotation cheat-sheet, imperative-lifecycle controls, diagnostics, and when to fall back to a hand-written ControlDescriptor.
reactor-windowing
Reactor top-level windowing cookbook: WindowSpec, OpenWindow, draggable windows, borderless/tool windows, placement persistence, taskbar visibility, z-order, aspect ratio, SizeToContent, displays, taskbar integration, and owner-window file/folder pickers.
reactor-recipes
Paste-ready single-file Reactor recipes indexed by intent — list with add/delete/toggle, sidebar navigation between pages, form with validation + submit gating, async fetch with loading/error/data states, themed Win11 card surface. Use a recipe instead of synthesizing from prose: copy, adjust, ship.
reactor-navigation
Reactor navigation — `UseNavigation` hook, `NavigationHost` renderer, `NavigationView` sidebar, `TabView` tabs, route params, stack operations, page lifecycle, deep linking, transitions, caching. Use when building multi-page apps or wiring sidebar/tab navigation.
reactor-input
Reactor input — gestures (`OnPan`, `OnPinch`, `OnRotate`), pointer events, drag-and-drop (`OnDragStarting`), focus management (`UseElementFocus`, `UseFocus`, `UseFocusTrap`). Use when implementing direct manipulation or custom focus behavior.