SuperAPI AI 工具集

reactor-advanced

编程与开发

查看项目

更新于 10-16 10:33

技能介绍

用途

本技能用于在 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 拥有精灵和其他设备资源。

限制

具体收费、价格、平台、效果或额外使用步骤暂未提供。