用途
本技能用于在 Microsoft.UI.Reactor.Advanced 中添加即时模式 Win2D 绘图。完整指南见 docs/guide/win2d-canvas.md,性能示例见 samples/apps/particle-storm/。
选择画布
根据工作负载选择画布:
- 静态或数据驱动绘制、状态更新后变化:使用 Win2DCanvas.Of(onDraw, redrawKey)。采用手动失效;对绘制回调读取的每个值传入变化的 RedrawKey。
- 游戏循环、物理、粒子、可视化器、稳定 FPS:使用 Win2DAnimatedCanvas.Of(onUpdate, onDraw, drawState, isPaused)。Win2D 拥有 tick,并在游戏线程上调用 update/draw。
- 大型可滚动或平铺表面:使用 Win2DVirtualCanvas.Of(onRegionDraw, contentSize)。仅绘制失效的可见区域;通过更改 InvalidateRegions 更新图块。
线程速查表
- Win2DCanvas.OnDraw:UI 线程。可安全读取由渲染捕获的 Reactor 状态。
- Win2DAnimatedCanvas.OnUpdate / .OnDraw:Win2D 游戏线程。不要触碰 WinUI 控件。使用线程安全数据或 UseState(threadSafe: true) 进行 UI 交接。
- Win2DVirtualCanvas.OnRegionDraw:UI 线程。将工作限制在失效区域内。
- UseCanvasResources 工厂:工作线程/游戏线程。创建设备资源并返回可释放/可重建对象。
将 UseDrawState 的 Ref.Current 视为易失字段。重新读取它,并使引用的对象对任何跨线程修改安全。调试版本会添加一个哨兵,将可能由动画回调引起的 WinUI 线程亲和性异常附加到 docs/guide/win2d-canvas.md#threading。
引用图模型
元素引用是响应式单元格。.Ref(cell) 将挂载的 FrameworkElement 写入单元格,并在卸载时写入 null。引用属性(TeachingTip.Target、.LabeledBy、.DescribedBy、.FlowsTo、.FlowsFrom、.XYFocus* 以及自定义描述符 .Reference / .ReferenceList)订阅这些单元格,而不是采样 .Current。
解析是单向且基于推送的:单元格在提交期间将脏引用边入队,然后 Reactor 在树稳定后刷新脏集。允许循环,因为每个属性槽都是单向边。列表引用保留作者声明顺序并省略未解析目标。高级作者应对常规控件使用 descriptor.Reference,仅将 binding.Reference 用作手写处理程序的桥接。
钩子与配方
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 是设备丢失的配方:从提供的 CanvasDevice 分配,仅在返回的 ref 非 null 时绘制,并让钩子在 CanvasDevice.DeviceLost 后释放/重建。
性能验证
Particle Storm 示例(samples/apps/particle-storm/)是标准模式:纯 Reactor chrome 控件参数;Win2DAnimatedCanvas 渲染热粒子路径;UseDrawState 持有粒子缓冲区;UseCanvasResources 拥有精灵和其他设备资源。
限制
具体收费、价格、平台、效果或额外使用步骤暂未提供。