ImageDisplay（现控件事实对照）

www 工作副本 · M5（Arden · 2026-10-21 Asia/Shanghai）
文档对照：mvdocs controls overview 仍在线。本页为现宿主事实对照，不是规格权威——规格权威见 image-display.md（目标 API / TC-DISP）。
M5-10（Alive 已拍）：MVP 只认 Controls 轨（Vyntek.Controls / 规格 ImageDisplay）；本页 Skia / Avalonia / FrameImageSource 不双开，记为后续可选宿主（对照保留，非 MVP 并列交付）。与骨架接通属 Rhett 非拦债若需。
实现边界：bindings tip 769d997。MVP 轨是 Vyntek.Controls（Share/OpenRead、预算、投影 TryGet、Unload/Remount；无真实渲染）。本页下文 Skia/FrameImageSource 仍是历史可选宿主事实。
关联：implementation · 规格 image-display · csharp-binding · 预览 http://127.0.0.1:8792

可选宿主说明（非 MVP）：下列 Vyntek.Host.ImageDisplay / Skia 面为历史现宿主事实，不是 MVP 交付轨；MVP 以 Vyntek.Controls 规格 ImageDisplay 为准（见 M5-10）。

Vyntek.Host.ImageDisplay 是基于 Skia 的机器视觉图片显示表面。 包名为 Vyntek.Host。首版支持 Gray8 原始帧和静态栅格图片； 静态图片按亮度转换为 Gray8，暂不提供彩色或 16 位灰度显示。

注册与显示Copy Anchor Link

在现有 UseVyntek 配置中调用：

using Vyntek.Controls;
using Vyntek.Desktop.Controls;
using Vyntek;

builder.UseDesktopControls();
builder.UseMachineVisionImageDisplay();
builder.UseImageLoading(options =>
{
    // 示例 16384×4000 超过框架默认的 6400 万像素限制，应用显式配置。
    options.MaxImagePixelCount = 100_000_000;
    options.MaxDecodedImageBytes = 512L * 1024 * 1024;
});

UseMachineVisionImageDisplay() 只注册控件主题；应用图片服务由第一阶段的 UseDesktopControls() 或 UseImageLoading() 配置。控件注册可以放入 Deferred， 但图片服务及其预算配置必须保留在第一阶段。

<vision:ImageDisplay xmlns:vision="urn:avanti-toolkit/machine-vision"
                    Source="D:\Images\sample.png" />

Source 使用现有 ImageSource 契约，静态来源经过应用的 IImageLoader；帧流使用 FrameImageSource。 普通静态图片控件不消费帧流，收到该来源时返回明确的 UnsupportedFormat 错误。 本控件不接收 SVG 或 BorrowedImageSource；静态栅格必须通过编码来源进入受校验的解码管线。

连续帧Copy Anchor Link

先在 UI 线程把 FrameImageSource 赋给已挂载显示控件，再由单个生产者提交：

var source = new FrameImageSource("Camera 1");
viewer.Source = source;

// 生产者线程：owner 是相机适配器交出的 IMemoryOwner<byte>。
using var frame = new ImageFrame(frameId, width, height, stride, owner);
FramePresentation drawn = await source.SubmitAsync(frame, cancellationToken);

SubmitAsync 返回时该帧已完成至少一次可见视口绘制，随后才提交下一帧。它不确认显示器物理扫描输出。 帧号须严格递增；宽高为正、步长至少等于宽度，缓冲区至少为 stride * height 字节。

提交前调用方拥有缓冲区；接收成功后所有权转交显示控件，调用方不得写入。返回后也不能自行复用， 必须等待租约的 Dispose 归还。失败发生在接收前时仍由调用方释放；接收后取消不提前释放正在渲染的缓冲区。 无法转移相机缓冲区时使用 SubmitCopyAsync，复制期间源内存必须稳定。

同一来源只允许一个显示控件与一个串行生产者。冻结、隐藏和最小化会向生产者施加背压；换源、卸载及关闭取消等待。 采集适配器必须真正等待提交；不能暂停的相机由宿主提供可靠录制，不能通过额外无限队列模拟无遗漏。

查看与扩展接口Copy Anchor Link

滚轮以鼠标为中心缩放，中键或空格＋左键拖动。Escape 或失去捕获取消交互。 首次输入适应窗口，后续帧保留视口；图片较小时居中，较大时限制平移使视口不越过图片边缘。

覆盖层几何使用原图坐标，控制柄与命中范围可使用屏幕单位，工具可在冻结帧上交互。 当前不提供这些形状的编辑、撤销、旋转、翻转或多视口联动。

更多见实现与生命周期、变更记录及模块边界。

www 工作副本 · M5 · tip 3ef0cb0 · 2026-10-21 Asia/Shanghai