Sevencat.ImageFacade.SkiaSharp
0.5.0
dotnet add package Sevencat.ImageFacade.SkiaSharp --version 0.5.0
NuGet\Install-Package Sevencat.ImageFacade.SkiaSharp -Version 0.5.0
<PackageReference Include="Sevencat.ImageFacade.SkiaSharp" Version="0.5.0" />
<PackageVersion Include="Sevencat.ImageFacade.SkiaSharp" Version="0.5.0" />
<PackageReference Include="Sevencat.ImageFacade.SkiaSharp" />
paket add Sevencat.ImageFacade.SkiaSharp --version 0.5.0
#r "nuget: Sevencat.ImageFacade.SkiaSharp, 0.5.0"
#:package Sevencat.ImageFacade.SkiaSharp@0.5.0
#addin nuget:?package=Sevencat.ImageFacade.SkiaSharp&version=0.5.0
#tool nuget:?package=Sevencat.ImageFacade.SkiaSharp&version=0.5.0
<div align="center">
ImageFacade
一套与后端无关的图像处理 API。换一行构造代码,就能在 SkiaSharp / OpenCvSharp / ImageSharp / 纯托管软渲染之间切换,其余代码一个字都不用改。
<p> <a href="https://www.nuget.org/packages/Sevencat.ImageFacade"><img alt="NuGet" src="https://img.shields.io/nuget/v/Sevencat.ImageFacade?label=nuget"></a> <a href="https://www.nuget.org/packages/Sevencat.ImageFacade"><img alt="Downloads" src="https://img.shields.io/nuget/dt/Sevencat.ImageFacade"></a> <img alt=".NET" src="https://img.shields.io/badge/.NET-net8.0%20%7C%20net10.0-512BD4"> <img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue"> <img alt="Tests" src="https://img.shields.io/badge/tests-256%20passed-brightgreen"> <img alt="Backends" src="https://img.shields.io/badge/backends-4-9cf"> </p>
<p> <a href="https://www.nuget.org/packages/Sevencat.ImageFacade">Sevencat.ImageFacade</a> · <a href="https://www.nuget.org/packages/Sevencat.ImageFacade.SdcbSimdCodecs">SdcbSimdCodecs</a> · <a href="https://www.nuget.org/packages/Sevencat.ImageFacade.SkiaSharp">SkiaSharp</a> · <a href="https://www.nuget.org/packages/Sevencat.ImageFacade.ImageSharp">ImageSharp</a> · <a href="https://www.nuget.org/packages/Sevencat.ImageFacade.ImageSharp2">ImageSharp2</a> · <a href="https://www.nuget.org/packages/Sevencat.ImageFacade.OpenCvSharp">OpenCvSharp</a> · <a href="https://www.nuget.org/packages/Sevencat.ImageFacade.OpenCvSharp5">OpenCvSharp5</a> </p>
</div>
为什么
图像处理的库很多,但它们的 API 互不兼容:换一个后端,Resize、画笔、文字排版、像素布局全都要重写一遍。项目一旦因为许可证、平台、部署形态(容器 / AOT / 无原生依赖)不得不换库,改动面通常是整个业务层。
ImageFacade 把这层差异收在 IImageBackend 后面:
- 调用方只依赖一个门面:
ImageEngine+FacadeImage。 - 后端互不兜底:支持的能力原生执行,不支持的直接抛
FeatureNotSupportedException(带后端名与能力名)。没有隐藏的性能悬崖,也没有"看起来一样其实不一样"的输出。 - 六个工程覆盖三个主版本组合:SkiaSharp 4、OpenCvSharp 4/5、ImageSharp 2/3,一份源码,不复制实现。
- 中文开箱可用:核心包内置文泉驿微米黑,容器 / CI / NativeAOT 环境下不需要准备任何字体。
特性
| 绘制 | 点、线、折线、矩形、椭圆、多边形,描边与填充;虚线;半透明叠加 |
| 文字 | 字号 / 颜色 / 字体;左中右对齐;MaxWidth 自动换行;MeasureText 与绘制使用同一套排版 |
| 缩放 | Stretch / Max / Min / Crop / Pad / BoxPad 六种模式,一次性完成"缩放 + 补边 / 裁切" |
| 像素互操作 | Bgra32 / Bgr24 / Rgb24 / Gray8 直接进出,支持任意 stride,不强制行连续 |
| 原生句柄 | OpenCV 后端可拿底层 Mat:SharedMat() 共享、SubMat() 取 ROI 视图、CloneMat() 深拷贝(内部是 BGRA,见下文边界说明) |
| 检测流水线 | letterbox + 坐标反算、NCHW/NHWC 张量化、池化缓冲、NMS、检测框与标签绘制 |
| 加载 | Load(path) 走只读内存映射,不再 File.ReadAllBytes 出等长数组;文件长度在映射前就校验 |
| 一行加载 / 保存 | 设置一次 ImageEngine.Default 后 ImageLoader.LoadJpg("in.jpg") 直接加载,img.SaveJpg("out.png") 直接保存——不用手写格式,见 一行加载 / 保存 |
| 半透明检测 | 加载时顺手查一次"图里真有半透明像素吗"(HasTransparency);可关掉、也可自己按需重算;图本来就不透明时不需要任何额外操作,保存时不会重复扫描,JPEG / BMP 编码还能省掉合成背景 |
| 异步 | 加载 / 保存 / 编码有 Async 版本;绘制保持同步(微秒级,包一层 Task 只会更慢) |
| AOT | 核心与软后端声明 IsAotCompatible,无反射、无动态代码生成 |
安装
七个包都已发布到 nuget.org,当前版本 0.5.0。
<PackageReference Include="Sevencat.ImageFacade" Version="0.5.0" />
<PackageReference Include="Sevencat.ImageFacade.SkiaSharp" Version="0.5.0" />
后端包已带上对应三方库的依赖,不需要重复声明 SkiaSharp / OpenCvSharp4 / SixLabors.ImageSharp。
版本与兼容
每个包独立发版,不强制"七个包同进同退"(0.5.0 是当前七个包统一的基线,此前的软后端曾单独走 0.1.x):
| 包 | 版本线 |
|---|---|
Sevencat.ImageFacade(核心) |
独立;patch / minor 只做加法,不破坏已发布的公开 API |
| 各后端(SkiaSharp / ImageSharp / ImageSharp2 / OpenCvSharp / OpenCvSharp5 / SdcbSimdCodecs) | 各自独立,可以只升其中一个 |
三条约定:
- 后端依赖核心只用下界:nuspec 里写的是
Sevencat.ImageFacade >= X.Y.Z,不是精确版本。 - 核心前向兼容时,后端不用重发:核心只做"加 API / 修 bug"的兼容改动时,把它升到更高的
X.Y.Z+n,现有后端包照常工作;只有核心做了不兼容改动(升主版本)才需要后端重新发版对齐。 - 只升后端也安全:后端只用到核心的旧 API,升级某个后端不会连累核心。
各包的实际版本以 nuget 页面为准;本文安装示例里的 Version="0.5.0" 是当前统一基线的取值。
| 包 | 后端类 | 三方库 | 说明 |
|---|---|---|---|
Sevencat.ImageFacade |
— | 无 | 核心:契约 + 路由 + 排版 + 内置字体 + Pipeline |
Sevencat.ImageFacade.SdcbSimdCodecs |
SoftwareBackend |
Sdcb.SimdCodecs.Abstractions 2.0 |
纯托管,无原生依赖,仅 net10.0;编解码按需接入,见下 |
Sevencat.ImageFacade.SkiaSharp |
SkiaBackend |
SkiaSharp 3.119.1 |
编译目标 3.x,可提升到 4.x(4.x 兼容 3.x) |
Sevencat.ImageFacade.ImageSharp |
ImageSharpBackend |
ImageSharp 3.1 |
纯托管,格式最全 |
Sevencat.ImageFacade.ImageSharp2 |
ImageSharpBackend |
ImageSharp 2.1 |
同上,2.x 分支 |
Sevencat.ImageFacade.OpenCvSharp |
OpenCvBackend |
OpenCvSharp4 4.13 |
内部 BGRA,API 层统一 RGBA |
Sevencat.ImageFacade.OpenCvSharp5 |
OpenCvBackend |
OpenCvSharp5 5.0 |
同上,5.x 分支 |
无后缀 = 当前主版本;带数字 = 指定的另一主版本。同一进程只能绑定一个三方库主版本,所以 Sevencat.ImageFacade.ImageSharp / ...ImageSharp2 只能二选一。
原生库按 RID 由应用侧引用,适配包不钉死 RID:
<PackageReference Include="SkiaSharp.NativeAssets.Win32" Version="3.119.1" />
<RuntimeIdentifier>win-x64</RuntimeIdentifier>
<PackageReference Include="OpenCvSharp4.runtime.win" Version="4.13.0.20261107" />
软后端:编解码按需接入
Sevencat.ImageFacade.SdcbSimdCodecs 不内置任何编解码器——它只带 Sdcb.SimdCodecs.Abstractions(编解码抽象)和自绘渲染层。要读写什么格式,就引哪几个 Sdcb.SimdCodecs.Xxx 包,然后在启动时注册一次。
这样设计是因为格式是可选项:只存 PNG 的服务不该把 WebP / TIFF / JPEG 2000 的代码一起扛进包和内存。注册表是进程级静态的,启动时填一次,之后所有 SoftwareBackend 实例共享。
| 需要 | 引哪个包 |
|---|---|
| PNG | Sdcb.SimdCodecs.Png |
| JPEG | Sdcb.SimdCodecs.Jpeg |
| BMP | Sdcb.SimdCodecs.Bmp |
| GIF | Sdcb.SimdCodecs.Gif |
| WebP | Sdcb.SimdCodecs.Webp |
| TIFF | Sdcb.SimdCodecs.Tiff |
| ICO / CUR | Sdcb.SimdCodecs.Ico |
| QOI / Netpbm | Sdcb.SimdCodecs.Qoi / Sdcb.SimdCodecs.Pnm |
| JPEG 2000 / JBIG2(PDF 场景) | Sdcb.SimdCodecs.Jpeg2000 / Sdcb.SimdCodecs.Jbig2 |
| HEIF / HEIC(手机照片) | Sdcb.SimdCodecs.Heif,HEVC 有专利,需自行评估后再用 |
初始化:在 Program.cs 开头或 [ModuleInitializer] 里注册一次(ImageFormat 是门面的 ImageFacade.ImageFormat):
using ImageFacade.Backends;
using Sdcb.SimdCodecs.Bmp;
using Sdcb.SimdCodecs.Jpeg;
using Sdcb.SimdCodecs.Png;
// 一次注册 = 解码器 + 编码器;第三个参数把门面的 EncodeRequest 映射成该格式的选项
ImageBackendBase.RegisterCodec(
ImageFormat.Png,
PngImageDecoder.Registration,
PngImageEncoder.Registration);
ImageBackendBase.RegisterCodec(
ImageFormat.Jpeg,
JpegImageDecoder.Registration,
JpegImageEncoder.Registration,
request => new JpegEncodeOptions { Quality = Math.Clamp(request.Quality, 1, 100) });
ImageBackendBase.RegisterCodec(
ImageFormat.Bmp,
BmpImageDecoder.Registration,
BmpImageEncoder.Registration,
_ => new BmpEncodeOptions());
要点:
- 只注册需要的:
RegisterDecoder/RegisterEncoder可以只注册一半(例如服务只产出 JPEG、不读图)。 - 没注册的格式:
CanDecode/CanEncode返回false,Load/Save抛FeatureNotSupportedException;绘制、Resize、文字与编解码无关,照常可用——完全不注册也能当纯渲染后端。 - 别把两个
ImageFormat一起using:门面的是ImageFacade.ImageFormat,Sdcb.SimdCodecs.Abstractions里也有一个同名的,冲突时用别名。 - 注册是幂等且线程安全的,但请在启动阶段做一次,别放进请求路径。
- AOT 不受影响:注册表就是普通静态字典,没有反射。
背后的编解码库:Sdcb.SimdCodecs
软后端的编解码全部来自 Sdcb.SimdCodecs(MIT)。选它是因为它同时满足了"快""准""零原生依赖"三件在容器 / AOT 场景里很难兼得的事:
- 纯托管、零原生依赖:Windows / Linux / macOS、NativeAOT、browser-wasm 都能跑,同一份输入在所有目标上输出一致——这对"软后端 = 确定性回退基准"很关键,不会因为换了台机器或镜像,同一张图的字节就变了。
- SIMD 加速,但不是只有 SIMD:AVX2 / SSE / AdvSimd 三条路径 + 标量回退,老 CPU 也能正确跑。
- 速度和原生库同级:JPEG 解码 0.82× libjpeg-turbo、PNG 解码 0.88× libpng、WebP 解码 0.53–0.88× libwebp(同机单线程,低于 1.00× 表示更快)。
- 结果是精确的:WebP 解码与 libwebp 逐字节一致,PNG 与无损 JPEG 2000 位精确;不会出现"换库后图看起来一样、像素对不上"。
- 低分配:可以直接解码进你自己的缓冲区,任意像素布局与任意行 stride(
ImageBackendBase走的正是这条路径),JPEG 解码 0 托管分配。
30 秒上手
using ImageFacade;
using ImageFacade.SkiaSharp;
using var engine = new ImageEngine(new SkiaBackend());
using var image = engine.Load("in.jpg", new LoadOptions { AutoOrient = true });
image.Resize(new ResizeOptions
{
Width = 800, Height = 600,
Mode = ResizeMode.Max,
Sampler = Sampler.Lanczos3,
})
.DrawLine(new PointF(20, 20), new PointF(300, 20), Rgba32.Red, width: 3)
.DrawText("你好 ImageFacade", new PointF(40, 240), new TextStyle
{
Font = FontRef.BuiltIn,
Size = 36,
Color = Rgba32.FromHex(0x1A1A1A),
MaxWidth = 720,
Align = TextAlign.Left,
});
image.Save("out.png", new SaveOptions { CompressionLevel = 6 });
换后端只改一行:
// using ImageFacade.OpenCvSharp; / using ImageFacade.SdcbSimdCodecs;
using var engine = new ImageEngine(new OpenCvBackend());
using var engine = new ImageEngine(new SoftwareBackend()); // 纯托管,无原生依赖(编解码要先注册,见上)
只画不存:核心自带光栅(new ImageEngine())
主包除了抽象,还带一套自绘光栅器。不引任何后端包也能建图、画字画形状、把像素交给 UI:
using var engine = new ImageEngine(); // 只有光栅,没有编解码
using FacadeImage image = engine.Create(1280, 720, Rgba32.Black);
image.DrawText("帧率 59.9", new PointF(16, 16), new TextStyle
{
Font = FontRef.BuiltIn,
Size = 24,
Color = Rgba32.White,
});
image.CopyPixelsTo(fb.Address, fb.RowBytes, PixelFormat.Bgra32); // 写进 Avalonia WriteableBitmap
它的绘制能力与软后端完全相同(SoftwareBackend 的建图、绘制、测量就是转发给同一个光栅器),区别只在编解码:
| 能力 | new ImageEngine() |
new ImageEngine(new SoftwareBackend()) |
|---|---|---|
Create / 绘制 / Resize / 文字 / FromPixels / ImportPixels / CopyPixelsTo |
✓ | ✓ |
CanDecode / CanEncode |
全 false |
按注册 |
Load / Save / Encode |
抛 FeatureNotSupportedException |
已注册的格式可用 |
逐帧刷新:复用同一张图,别每帧 FromPixels
FromPixels 每次都会新建一帧并租一整幅缓冲。尺寸不变时(视频播放、摄像头、UI 自绘),建一次图、之后每帧用 ImportPixels 覆盖更划算:
using var engine = new ImageEngine();
FacadeImage? canvas = null;
void Compose(ReadOnlySpan<byte> frame, int width, int height, ILockedFramebuffer fb)
{
if (canvas is null || canvas.Width != width || canvas.Height != height)
{
canvas?.Dispose();
canvas = engine.Create(width, height, Rgba32.Black); // 只在尺寸变化时重建
}
canvas.ImportPixels(frame, width * 4); // 整幅覆盖,上一帧内容不保留
canvas.DrawText("帧率 59.9", new PointF(16, 16), hudStyle);
canvas.CopyPixelsTo(fb.Address, fb.RowBytes, PixelFormat.Bgra32);
}
ImportPixels 与 FromPixels 的导入部分语义一致(直通 RGBA32 进、内部存预乘),省掉的只是每帧新建帧与租还缓冲;直通 → 预乘那一次转换省不掉。导入会作废 HasTransparency 的缓存结论,之后 DetectTransparency() 会按新像素重算。
画完要保存:换后端,不是给引擎加能力
FacadeImage 在构造时就把 ImageEngine 绑定死了,之后无法改绑;ImageBackendBase.RegisterCodec 注册的是 ImageBackendBase 的进程级静态表,只有它的派生类(软后端)会读,核心光栅不参与。所以先 new ImageEngine() 再注册 PNG 是存不了的。
直接换成软后端引擎即可,绘制零损失(using 与注册写法见上文 软后端:编解码按需接入):
ImageBackendBase.RegisterCodec(ImageFormat.Png, PngImageDecoder.Registration, PngImageEncoder.Registration);
using var engine = new ImageEngine(new SoftwareBackend()); // 画图能力同上,额外带编解码
using FacadeImage image = engine.Create(1280, 720, Rgba32.Black);
image.DrawText(...);
image.Save("out.png");
如果两个引擎都已经在手上(轻量引擎画、带编解码的引擎存),搬一次像素即可:
byte[] pixels = image.CopyPixels(); // 直通 RGBA32,stride = width * 4
using var saver = new ImageEngine(new SoftwareBackend());
using FacadeImage toSave = saver.FromPixels(pixels, image.Width, image.Height, image.Width * 4);
toSave.Save("out.png");
代价是两次全帧拷贝 + 两次遍历(导出一次、重建时直通→预乘一次);偶尔保存无所谓,频繁保存请从一开始就用 SoftwareBackend。
换成 Skia 也能存
Skia 后端自带编解码,不需要注册,可编码 PNG / JPEG / WebP(解码还多 BMP / GIF / ICO):
using var engine = new ImageEngine(new SkiaBackend());
using FacadeImage image = engine.Create(1920, 1080, Rgba32.Black);
image.DrawText(...);
image.Save("out.jpg", new SaveOptions { Quality = 85 }); // 或 SavePng / EncodeWebP
同样不能"用核心光栅画、让 Skia 存"——跨引擎还是要走上面那段搬像素。要原生绘制与原生编码一体,就整个引擎都换成 SkiaBackend。
一行加载 / 保存(推荐入口)
日常用图不要手写格式:启动时把引擎赋给 ImageEngine.Default 一次,之后加载用 ImageLoader.LoadXxx、保存 / 编码用 img.SaveXxx / img.EncodeXxx,格式写进方法名里:
// 程序启动时设置一次(门面不做任何自动探测,不设置就抛 InvalidOperationException)
ImageEngine.Default = new ImageEngine(new SkiaBackend());
// 加载:格式写在方法名里,不用构造 LoadOptions / SaveOptions
using var img = ImageLoader.LoadJpg("in.jpg");
// 保存 / 编码:同样不用手写 SaveOptions.Format
img.SaveJpg("out.jpg", 85); // 有损质量 85
img.SavePng("out.png"); // 无损
byte[] webp = img.EncodeWebP(75); // 拿字节
// 异步一样是一行
using var png = await ImageLoader.LoadPngAsync("in.png", cancellationToken: token);
await img.SavePngAsync("out.png", cancellationToken: token);
三条约定:
ImageLoader全部走ImageEngine.Default,与engine.Load(...)是同一个引擎、同一套校验(尺寸上限、内存映射、HasTransparency检测);没有 Default 就抛InvalidOperationException,消息里告诉你怎么赋值。多引擎并存时仍用engine.Load,ImageLoader只是单引擎程序的便捷入口。- 加载按内容嗅探,不认扩展名:
LoadJpg/LoadPng这些名字是为了调用处可读,文件实际是什么格式就按什么格式解——扩展名写错了照样能加载。 - 保存格式由方法名定死:
SaveJpg永远出 JPEG(不需要目标路径扩展名是.jpg),SavePng永远出 PNG;错误语义(半截文件删除、ImageSaveFailedException、FeatureNotSupportedException)与Save/Encode完全一致。
支持的格式:JPEG(LoadJpg / SaveJpg)、PNG、WebP、BMP、GIF、TIFF、ICO、QOI、PNM,每种都有 path / Stream / byte[] 三个入参方向和对应的 Async / Encode 版本。当然,后端得支持该格式(能力矩阵见下文),不支持时照抛 FeatureNotSupportedException。
截图
同一段代码,四个后端(software / skia / imagesharp / opencv):
| 文字排版 | 检测流水线 |
|---|---|
| 水印叠加 | 基础绘制 |
|---|---|
| OpenCV Mat 互操作 |
|---|
以上图片全部由 samples/ImageFacade.Samples 生成(dotnet run 输出到 docs/images/),可以直接改代码看效果。检测流水线那张里的虚线框是 NMS 抑制掉的候选框,实线是保留的。
Resize 六模式
上图(顶部那张)就是同一张 800×300 源图跑六种模式的结果:
| 模式 | 行为 | 输出尺寸 |
|---|---|---|
Stretch |
直接拉伸,不保持比例 | 目标尺寸 |
Max |
等比缩放到完全放进目标框 | 缩放后尺寸 |
Min |
等比缩放到覆盖目标框 | 缩放后尺寸 |
Crop |
等比铺满后居中裁切 | 目标尺寸 |
Pad |
等比放进后补边 | 目标尺寸 |
BoxPad |
同 Pad,但只缩小不放大(源图比目标框小时原尺寸居中补边) |
目标尺寸 |
Max / Min 的命名沿用 .NET 与 SixLabors 的习惯:Max 是"最大尺寸不超过目标框"。
检测流水线
ImageFacade.Pipeline 在核心包内,不依赖任何推理库:它只负责"把帧变成模型输入"和"把模型输出画回帧",中间跑什么模型由你决定。
using ImageFacade;
using ImageFacade.Pipeline;
// 1) letterbox:源图不变,返回新图 + 反算几何
using FacadeImage padded = frame.Apply(640, 640, out LetterboxInfo info);
// 1280x720 -> 640x640:info.Scale = 0.5,info.PadTop = 140
// 2) 张量化:NCHW + RGB + 归一到 0..1,写入池化缓冲
var options = new TensorOptions { Width = 640, Height = 640 };
using TensorBuffer tensor = TensorBuffer.Rent(640 * 640 * 3);
frame.ToTensor(options, tensor.Span, out _);
// tensor.Memory 可直接交给 onnxruntime
// 3) 假设模型返回了模型坐标下的框
Span<Detection> detections = /* 从模型输出解码 */;
// 4) NMS:原地抑制,返回保留数量
int kept = Nms.Suppress(detections, iouThreshold: 0.45f);
// 5) 反算回源图坐标,再画到**源帧**上
var onSource = new Detection[kept];
for (int i = 0; i < kept; i++)
{
Detection detection = detections[i];
onSource[i] = new Detection(info.ToSource(detection.Box), detection.Label, detection.Score)
{
ClassId = detection.ClassId,
};
}
frame.DrawDetections(onSource);
要点:
Apply不改源图,所以画框可以直接画在源帧上,坐标不用二次换算。LetterboxInfo.ToSource是唯一的反算入口;手写(x - pad) / scale容易把顺序写反。- 张量缓冲用
TensorBuffer.Rent池化:640×640×3 是 4.9 MB,每帧新分配会直接进 LOH。 Nms.Suppress原地重排,有效段是detections[..kept],结果与输入顺序无关;Nms.Select返回原数组下标。DrawDetections只是默认排版,标签宽度走MeasureText,与当前后端自洽;要别的排版就自己循环DrawRectangle+FillRectangle+DrawText。DetectionStyle.LabelBackground默认是半透明的(0,0,0,160):四个后端都能画,OpenCV 走的是「包围盒覆盖率层 + 逐像素混合」,代价是每个半透明形状一块小缓冲。
视频帧:原生内存进出
// 指针来自 ffmpeg 的 avFrame->data[0] 与 linesize[0](或相机缓冲),不先转 RGBA。
IntPtr pixels = frameDataPtr;
int stride = linesize;
using var frame = engine.FromPixels(pixels, width, height, stride, PixelFormat.Bgr24);
frame.DrawRectangle(new RectF(100, 80, 220, 160), Rgba32.Lime, width: 2);
// 直接写进 Avalonia 的 WriteableBitmap 锁帧内存
frame.CopyPixelsTo(fb.Address, fb.RowBytes, PixelFormat.Bgra32);
stride 由调用方给出,按行处理、不要求连续;格式缺省是 Rgba32,Bgr24 / Bgra32 / Rgb24 / Gray8 需显式指定。
关于通道顺序:门面层没有"这个图是 RGB 还是 BGR"的概念,
Rgba32、PixelFormat.Rgba32(默认)、GetPixel、CopyPixels全是 RGBA 语义。后端内部怎么存是它自己的事——OpenCV 用CV_8UC4(BGRA),Skia 用Rgba8888 Premul,都与调用方无关。唯一要显式声明顺序的地方是
FromPixels(..., PixelFormat.Bgr24)这类入参:你告诉门面源缓冲是什么格式,它负责转换。反过来CopyPixels(PixelFormat.Bgr24)也一样。代价是 OpenCV 后端不做零拷贝包装(BGRA↔RGBA 必须逐行换通道),
FromPixels会拷贝一次;Skia / 软后端才能直接接管外部缓冲。OpenCV 为什么必须保持 BGRA、拿Mat出去后哪些函数要自己换通道,见下文 OpenCV 内部是 BGRA:哪些函数转、哪些要你自己处理。
像素出入只有一条路
校验在门面做一次,后端只负责"按 stride 逐行搬运"。
FromPixels/CopyPixelsTo的尺寸、bytesPerPixel、stride下界、缓冲区长度((height-1)*stride + rowBytes,long计算防溢出)全部由门面统一校验;后端ImportPixels/TryCopyPixels拿到的一定是"已验证过"的参数。- 输入不是
Rgba32时,门面先用PixelConverter归一成规范 RGBA32(stride = width * 4),再交给后端——所以每个后端只需要实现一种像素布局,不用为 BGR / BGRA / Gray 各写一套分支。 - OpenCV 后端因此只有一份
SwapRedBlue(RGBA32 ↔ BGRA):通道交换是对合运算,导出与导入共用同一份实现,不会出现"两个方向各写一遍、只修了其中一个"的情况,也天然覆盖Mat.step > cols*4的对齐填充和外部缓冲的非紧凑 stride。
OpenCV 内部是 BGRA:哪些函数转、哪些要你自己处理
先记住这句话:OpenCV 后端的帧内部就是一块
CV_8UC4、字节序为 B/G/R/A 的Mat。这是四个后端里唯一的例外,而且是刻意的:
Cv2.ImDecode/Cv2.ImEncode只认 BGR / BGRA,内部若改存 RGBA,每次打开和保存都要多一次全图转换;现在的代价只落在FromPixels/CopyPixelsTo这一对边界上(它们本来就要按 stride 逐行搬运,顺带换通道)。所以不要试图把它"统一"成 RGBA。但要注意,这不是说调用方也要跟着用 BGRA——只要走门面 API,看到的永远是 RGBA 语义。边界只在"直接拿
Mat"的那一刻出现。
| 后端 | 内部像素布局 | 说明 |
|---|---|---|
| Skia | Rgba8888 + Premul |
原生 RGBA |
| ImageSharp | Image<Rgba32> |
原生 RGBA |
| 软后端 | 预乘 Rgba32 |
原生 RGBA |
| OpenCV | CV_8UC4 BGRA |
唯一例外,因为 OpenCV 编解码只认 BGR/BGRA |
一句话记忆:过门面 API = RGBA 语义;直接摸 Mat = BGRA 字节序。
门面已经替你转了(按 RGBA 写,不用管 BGRA)
| 你用 | 门面做了什么 | 你要做什么 |
|---|---|---|
GetPixel(x, y) |
读 BGRA 后换回 R/G/B | 无 |
CopyPixelsTo(buf, stride) / CopyPixels()(默认 Rgba32) |
逐行 BGRA → RGBA | 无 |
CopyPixelsTo(..., PixelFormat.Bgra32) |
先转 RGBA,再按声明格式写成 BGRA | 无(按声明的格式读) |
FromPixels(span / ptr, ..., 默认 Rgba32) |
RGBA → BGRA 写进 Mat |
无 |
FromPixels(..., PixelFormat.Bgr24 / Bgra32 / Rgb24 / Gray8) |
核心先归一成规范 RGBA32,后端再换通道 | 无(只要格式声明对) |
AcquirePixels() / PixelLease.Pixels |
交给你的是规范 RGBA32,回写时再换回 BGRA | 无 |
DrawLine / FillRectangle / DrawText / Clear 的 Rgba32 参数 |
后端 ToScalar 内部组装成 B/G/R/A 的 Scalar |
无 |
Save / Encode / Load / Decode |
后端内部 ImEncode / ImDecode 直接吃 BGRA |
无 |
Resize / 六种模式 / DrawDetections / Apply |
与通道顺序无关 | 无 |
摸到 Mat 之后要你自己处理
SharedMat() / SubMat() / CloneMat() 交出来的是原始 BGRA Mat,门面不再做任何转换:
| 你调用的 OpenCV API | 它期待的顺序 | 是否需要处理 |
|---|---|---|
Cv2.Rectangle / Line / Circle / Ellipse / FillPoly 的颜色 |
Scalar 即 B,G,R,A |
要:红色是 new Scalar(0, 0, 255, 255),不是 (255, 0, 0, 255) |
Cv2.ImWrite / ImEncode |
BGRA | 不用,正好对 |
Cv2.CvtColor(..., BGR2Gray / BGRA2BGR / BGR2RGB) |
BGR 系列 | 不用,Mat 就是 BGRA |
Cv2.CvtColor(..., RGB2Gray / RGBA2BGR / RGBA2RGB) |
期望 RGBA | 要:先 BGRA2RGBA 或用 BGR 系列 |
| DNN / onnxruntime 的 NCHW 输入 | 看模型(多为 BGR 或 RGB) | 要:CvtColor(BGRA2BGR) 或 BGRA2RGB |
Mat.At<Vec4b>(y, x)、直接读 Mat.Data |
字节序 B,G,R,A | 要:Item0=B, Item1=G, Item2=R, Item3=A |
自己 new Mat(或从别处解码来的)贴回图片 |
目标区域是 BGRA | 要:手头是 RGBA 时先 CvtColor(RGBA2BGRA),否则红蓝对调 |
wrap: true 零拷贝 |
只有 RGBA 能和规范像素对齐 | OpenCV 不做包装,FromPixels 一定拷贝一次 |
另外两点:
Mat.Type()只有CV_8UC4,OpenCV 本身不区分 RGBA / BGRA,顺序纯靠约定——所以门面内部换通道、外部按 BGRA 用,两条路都必须心里有数。SharedMat/SubMat返回的Mat归门面所有:不要Dispose、不要跨线程、图片释放后不要再碰。
OpenCV Mat 互操作
把上面那块 BGRA Mat 交给 Cv2、DNN 或标定代码,不必绕 CopyPixels 转一趟缓冲:
using ImageFacade.OpenCvSharp;
using OpenCvSharp;
Mat shared = image.SharedMat(); // 后端保存的 Mat,不复制
// 注意 Scalar 是 BGRA 顺序:这个画出来是红色
Cv2.Rectangle(shared, new Rect(10, 10, 100, 60), new Scalar(0, 0, 255, 255), 3);
using Mat roi = image.SubMat(100, 40, 200, 120); // ROI 视图,共享像素
Cv2.GaussianBlur(roi, roi, new Size(5, 5), 0); // 只影响这 200x120
using Mat copy = image.CloneMat(); // 深拷贝,改它不影响原图
| 方法 | 内存 | 用途 |
|---|---|---|
SharedMat() |
共享 | 把整帧交给 OpenCV(Cv2.*、DNN 输入、ImWrite) |
SubMat(x, y, w, h) / SubMat(Rect) |
共享 | 只处理一块区域;写进去就是写原图 |
CloneMat() |
复制 | 要一份能随便改、能脱离图片生命周期的副本 |
- 通道顺序是 BGRA(
Scalar的 v0/v1/v2 = B/G/R,v3 = alpha,不写 v3 会画成透明)——完整的"哪些函数门面转了、哪些要自己处理"见上一节的两张表。 SharedMat/SubMat返回的Mat归门面所有:不要Dispose、不要跨线程、图片释放后不要再碰;CloneMat的副本归调用方,自己using。- 只有
OpenCvBackend的帧能这样拿,其他后端调用抛InvalidOperationException;与后端无关的像素级互操作用CopyPixels/AcquirePixels。
后端能力矩阵
✓ 原生支持;✗ 不支持,调用时抛 FeatureNotSupportedException(消息含后端名与能力名)。
| 能力 | Skia | ImageSharp | OpenCV | 软后端 |
|---|---|---|---|---|
| Resize / 六种模式 | ✓ | ✓ | ✓ | ✓ |
| 点 / 线 / 折线 / 矩形 / 椭圆 / 多边形 | ✓ | ✓ | ✓ | ✓ |
半透明形状(color.A < 255) |
✓ | ✓ | ✓ | ✓ |
虚线(StrokeStyle.DashPattern) |
✓ | ✓ | ✓ | ✓ |
| 文字(含中文) | ✓ | ✓ | ✓ | ✓ |
| 半透明文字 | ✓ | ✓ | ✓ | ✓ |
| 解码格式 | PNG/JPEG/BMP/GIF/WebP/ICO | PNG/JPEG/BMP/GIF/WebP/TIFF | PNG/JPEG/BMP/WebP | 按注册(Sdcb 格式包) |
| 编码格式 | PNG/JPEG/WebP | PNG/JPEG/BMP/GIF/WebP/TIFF | PNG/JPEG/BMP/WebP | 按注册(Sdcb 格式包) |
| NativeAOT | 已声明兼容 | 未声明 | 不支持 | 已声明兼容 |
| 原生依赖 | SkiaSharp RID 包 | 无 | OpenCV RID 包 | 无 |
OpenCV 的 drawing 函数是覆盖写像素,没有混合模式——所以半透明绘制不能直接交给 Fill/Draw/Line。后端的做法是先把形状画到一块和形状包围盒一样大的 8 位全 0 层上(AA 边缘自然留下 0~255 的覆盖率),再按覆盖率把颜色逐像素混进目标;不透明形状仍直接画,不多付一分钱。这条路径和半透明文字共用同一套混合公式,所以四个后端的观感一致。代价是每个半透明形状一块包围盒大小的单通道缓冲,不是全图临时层。
虚线同样是几何方案:OpenCV 的 Line/Polylines 只有实线,后端按核心那套切分规则(DashPattern 的线宽倍数、DashOffset、奇数图案重复两遍,与其它后端同一份实现)先把轮廓切成若干实线段,再逐段 Polylines。矩形按四个角、椭圆按周长约 2 px 一个点折线化后切分。端帽仍是 OpenCV 的平头(和实线描边一致,OpenCV 没有圆头/方头)。两条路径可以叠加:半透明虚线会先切段、画在覆盖率层上,再整体混合。
OpenCV 解码后会把输入统一成 8 位 BGRA:灰度、灰度+alpha、无 alpha 的图都补成 4 通道(缺 alpha 补 255),16 位 PNG 按 1/257 归一(65535 → 255,直接截断会饱和成一片白)。这样"每像素固定 4 字节"的约定对所有输入都成立。
跨后端不保证逐像素一致:抗锯齿、字体栅格化、缩放核的实现各不相同。需要确定性输出时把软后端当主后端。
主包还自带一套光栅器(new ImageEngine()),绘制能力与"软后端"那一列相同,但不含任何编解码:CanDecode / CanEncode 全 false,Load / Save 抛 FeatureNotSupportedException。需要保存时换 SoftwareBackend(注册格式)或 SkiaBackend(自带编解码),见 只画不存:核心自带光栅。
实测:半透明与虚线的开销
上图由 OpenCvSharp 5 后端直接画出:半透明填充矩形(A=140)、椭圆(A=120)、三层三角形(A=90),半透明虚线框(A=170)、描边椭圆(A=200),以及一条 A=128 的粗线。灰白条纹底是用来验证颜色真的混合进去了——如果是覆盖,条纹会在形状里断掉。
1000×600 画布上的实测(.NET 10.0.1 / win-x64 / 32 逻辑核;绑单核 + 高优先级,8 轮预热 + 40 轮取最快值。单位是一整轮毫秒,越小越好):
| 场景(每轮次数) | OpenCV5 | 软后端 | SkiaSharp | 软 / Skia |
|---|---|---|---|---|
| 实线 200 条(对照) | 8.15 | 4.70 | 0.69 | 6.8× |
| 虚线 200 条 | 43.16 | 28.95 | 11.32 | 2.6× |
| 虚线折线 50 条(每条 40 点) | 213.70 | 377.18 | 129.00 | 2.9× |
| 实线折线 50 条(每条 40 点) | 48.16 | 118.88 | 94.30 | 1.3× |
| 矩形描边 50 个(对照) | 2.25 | 6.68 | 0.67 | 10× |
| 矩形虚线描边 50 个 | 10.09 | 8.81 | 3.33 | 2.6× |
| 矩形填充 50 个(不透明,对照) | 0.56 | 0.62 | 0.28 | 2.2× |
| 半透明矩形填充 50 个(200×150,A=128) | 12.88 | 4.33 | 1.78 | 2.4× |
| 半透明椭圆填充 50 个(200×150,A=128) | 11.13 | 14.02 | 2.76 | 5.1× |
| 半透明三角形填充 50 个(A=128) | 7.44 | 9.14 | 1.69 | 5.4× |
| 半透明大矩形 20 个(500×400,A=128) | 34.07 | 2.03 | 4.73 | 0.4× |
怎么读这张表:
- 取最快值而不是中位数:宿主上并行编译/IDE 抢核会把中位数和 P90 拉到真实值的几倍,只有多轮最小值可复现。同一份二进制连跑三次,最快值的偏差在 3% 以内。
- 虚线不再是软后端的短板:
虚线 200 条比 OpenCV 快 1.5 倍(28.9 vs 43.2),矩形虚线描边也反超(8.8 vs 10.1)。OpenCV 没有 dash 图案,每条轮廓都要按弧长切段再逐段Polylines,还要为切段分配数组。 - 软后端仍慢的两处:
矩形描边(6.7ms vs Skia 0.67ms)和半透明椭圆 / 三角形——前者是 50 个形状 50 次绘制调用,每次都要租缓冲、清覆盖率层,固定开销占主导;后者每一行都带着抗锯齿边缘像素,走不到"整行覆盖率恒为 255"的快路径,只能走通用混合内核。 - 半透明大块填充软后端最快:
半透明大矩形2.0ms,比 OpenCV 快 17 倍、比 Skia 快 2.3 倍——核心光栅按行扫覆盖率、整行恒 255 时源项是常量,每像素只剩一次dst * (255-a) / 255。 - 虚线折线是唯一被 OpenCV 压制的场景(377 vs 214):每条折线 40 个点、图案 4/4,一轮下来要生成约 11.7 万个独立的虚线段轮廓,代价几乎全在"每段一个轮廓"上(几何构建 ~94ms、托管分配 280MB)。
- 选择建议:视频叠加层里大量半透明色块,用 Skia 或软后端;已有 OpenCV Mat 管线、半透明只是少量标注框/遮罩时,OpenCV 后端完全够用;要跨平台确定性输出,软后端仍是基准。
软后端光栅器:把每行 O(n²) 变成 O(n)
上面的软后端数字是改过光栅器之后的。改之前斜线、折线类场景慢得离谱(实线折线 50 条 276ms、虚线折线 50 条 527ms),原因不在抗锯齿也不在混合,而在扫描线的交点处理:
| 问题 | 改法 | 效果 |
|---|---|---|
| 每行重新遍历活动边表、收集交点,再用插入排序排一遍;折线每行有几十个交点,插入排序退化成 O(n²) | 活动边表按 x 就地排序。相邻扫描线之间 x 的顺序几乎不变,插入排序接近 O(n),排完直接顺序取用,不再单独收集/排序交点 | 实线折线 276 → 119ms,虚线 200 条 105 → 29ms |
| 退表用"和末尾交换再删",把活动边表的顺序打散,正好废掉上面的 O(n) 前提 | 改成保序压缩退表 | 同上 |
List.Sort 不稳定,同一个起始行的边每次运行顺序不同;多条边交于同一点(miter 尖端)时环绕数可能收不到 0,整段被丢掉 |
按 (起始行, 建边序号) 排,并列顺序确定 |
顺带修掉一个 1 像素的 AA 缺陷,见下 |
| 每行按包围盒全宽清零、量化、混合 | 记录每行实际用到的列区间(CoverageBuffer.SetRowSpan),只处理这一段 |
细长形状不再按包围盒面积付费 |
像素输出与改动前逐字节一致,唯一例外是 1 个像素:矩形描边 的 miter 尖角处,几条边交于同一个 x,旧顺序让环绕数收在 +2(没归零),最后一段 [x, 1.5] 被丢掉,那个像素只拿到半个覆盖率。新顺序环绕数正常归零,覆盖率回到几何上正确的 1.0——即旧结果是缺陷,新结果是修复。
中文与字体
- 核心内置文泉驿微米黑(
FontRef.BuiltIn),没有系统字体也能画中文;容器 / CI / AOT 场景不需要额外准备字体。 - 系统字体族(
FontRef.Family(...))只有 Skia 与 ImageSharp 支持;OpenCV 与软后端没有系统字体管理器,会退回内置字体。 - 自备字体:
Font.Load*拿到实例后塞进TextStyle.FontFace,可跨多次绘制复用。 FontRef.FromData(...)/FontRef.FromFile(...)在 Skia 后端按引用缓存(同一FontRef只解析一次), 且不会长期占用字体文件句柄——注册后文件可以照常替换或删除。
解码尺寸上限(防解压炸弹)
Load / LoadAsync 默认拒绝超过 1 亿像素(约 400 MB RGBA)的图像:一个 20 KB 的 PNG 声明
30000×30000 时,不会先分配 3.6 GB 再报错。
// 默认:超过 1 亿像素抛 ImageSizeLimitExceededException
using var image = engine.Load(untrustedBytes);
// 允许更大的可信输入(0 = 不限制)
using var big = engine.Load(path, new LoadOptions { MaxPixels = 0 });
- 校验在门面做,四个后端一视同仁:能读到头部(PNG / JPEG / BMP / GIF / WebP / TIFF / QOI / PNM) 就在解码前拒绝;读不到头部时才退化为解码后兜底。
ImageSizeLimitExceededException.Width/Height/MaxPixels给出当时的数值; 它和"图损坏"是两类异常,方便映射成 413 与 400。ImageEngine.Create/FromPixels不受这个上限约束——那里的尺寸来自你的代码,不是外部输入。- 只限像素数:像素少但字节多的输入(高熵图片、被刻意放大的文件)由下面的字节上限管。
编码字节上限(流式加载)
Load(Stream) / LoadAsync(Stream) 读入的是压缩后的字节,这层有独立的开关
LoadOptions.MaxEncodedBytes。默认 0 = 不限制,保持与旧版本一致——现有调用方不会因为升级
突然开始抛异常。
// 只允许读入 8 MB 的编码数据;超出立刻停止读取并抛异常,不会把整个文件吞进内存
using var image = engine.Load(httpStream, new LoadOptions { MaxEncodedBytes = 8 * 1024 * 1024 });
- 累计读到的字节数超过上限就停手(缓冲最多长到"上限 + 1"),异常里的
MaxEncodedBytes/EncodedBytes给出上限与已读字节数;Width/Height/MaxPixels为 0。 - 可寻址流会先按
Length快速拒绝;这个值不可信(网络流常常乱报),所以读循环里仍然累计校验。 Load(path)/LoadAsync(path)走只读内存映射,长度在建立映射之前就知道,所以同样按这个上限先拒后读; 空文件抛ArgumentException,超过单块缓冲上限(约 2 GB,span 长度是int)也抛ImageSizeLimitExceededException。- 已经拿到完整字节的
Load(ReadOnlySpan<byte>)/Load(ReadOnlyMemory<byte>)不受它约束—— 内存都已经分配过了,拦不住也没有意义。 - 与
MaxPixels是两个独立维度,各自挡一类输入,互不影响。
半透明像素(HasTransparency)
Metadata.HasAlpha 只是解码器声明的通道能力位——不透明 PNG 同样带 alpha 通道。要知道"图里到底有没有
alpha < 255 的像素",看 Metadata.HasTransparency(bool?,null = 不知道):
using var image = engine.Load(bytes); // 加载时顺手查一次(默认开)
bool? translucent = image.Metadata.HasTransparency;
// 关掉自动检测:省掉那一次全图扫描,代价是加载后为 null
using var lazy = engine.Load(bytes, new LoadOptions { DetectTransparency = false });
// 之后自己按需重算:有结论直接返回,force: true 无视缓存重扫
bool? now = lazy.DetectTransparency();
- 三态:
true有半透明像素、false确定全不透明、null不知道。null不是false,两个方向的判断都要留兜底分支。 - 图本来就不透明的话,你不需要做任何多余操作:加载时最多扫一次(没有 alpha 通道的输入连这一次都省了),
结论缓存起来反复用,之后的
Save/Encode不会为了确认 alpha 再扫一遍——存 PNG 直接编码, 存 JPEG / BMP 还能省掉合成背景色。详见下文 图本来就不透明:什么都不用做。 - 没有 alpha 通道的输入(JPEG)加载时直接定
false,一个字节都不扫。 - 绘制会让结论失效(置回
null,但不会因此扫全图);Clear(color)直接等于color.A < 255;Resize的Stretch原样继承结论,Pad/BoxPad只在真的补了半透明边时才变true。 需要准确答案时再调一次DetectTransparency()。 - 检测怎么走、慢不慢、有哪些坑,见文末 半透明像素:判断依据、性能与注意事项。
出错时
| 情况 | 异常 |
|---|---|
| 参数非法 | ArgumentException / ArgumentOutOfRangeException |
| 后端不支持该能力 | FeatureNotSupportedException(含后端名、能力名、替代建议) |
图像超过 LoadOptions.MaxPixels |
ImageSizeLimitExceededException |
流读入超过 LoadOptions.MaxEncodedBytes |
ImageSizeLimitExceededException(Width / Height 为 0) |
| 保存到文件失败 | ImageSaveFailedException(含 Path、FileDeleted,半截文件已删除) |
| 三方库内部失败 | ImageBackendException(保留 InnerException,含后端名) |
| 原生库缺失 | ImageBackendException(含安装提示,不是裸 DllNotFoundException) |
Save(path) 失败时会删除目标文件
Save / SaveAsync 直接写目标路径(不做"临时文件 + 改名")。失败时会把写了一半的文件删掉,
并抛 ImageSaveFailedException,消息里明确写着"已删除写了一半的目标文件"。
try
{
image.Save("out.jpg");
}
catch (ImageSaveFailedException ex)
{
// ex.Path 目标路径
// ex.FileDeleted true = 半截文件已删掉;false = 删除也失败,可能残留
// ex.InnerException 真正的失败原因
}
代价:目标路径原有的文件在保存开始时就被截断,失败后不会恢复。
需要保留原件就自己先备份,或改用 Encode() 拿字节后自行落盘。
路由只有两档:后端 Try* 返回 true 就原生执行,返回 false 就抛错。没有跨后端自动回退,行为在调用点可见。
构建与测试
dotnet build ImageFacade.slnx
dotnet test ImageFacade.slnx # win-x64
dotnet pack ImageFacade.slnx -c Release -o artifacts/packages
- 测试按主版本拆分工程(同一进程只能绑一个三方库版本),OpenCV 测试工程需
RuntimeIdentifier=win-x64。 - v1 只在 win-x64 验收;Linux/macOS 只保证核心与纯托管后端可编译。
- CI 见
.github/workflows/ci.yml:Windows + .NET 10,跑 build → test → pack。
示例:Avalonia 播放器(SimdSkia + FFmpeg.AutoGen)
samples/ImageFacade.AvaloniaDemo 是一条端到端链路:FFmpeg.AutoGen 解出裸帧 → ImageFacade 在帧上叠时间和 fps → 写进 Avalonia 的 WriteableBitmap;窗口用 SimdSkia.Avalonia.Desktop 渲染,全程不引 SkiaSharp。播放本身一帧都不编解码;只有「保存图片」按钮额外引了 ImageFacade.SdcbSimdCodecs + Sdcb.SimdCodecs.Png(不想引的话见 保存一帧 的 B 方案)。
# 1. 原生库:FFmpeg.AutoGen 只是绑定,DLL 由运行环境提供。
# 把 ffmpeg 的 bin 目录里 avcodec / avformat / avutil / swscale 等 DLL 放到程序目录,
# 或设置 FFMPEG_HOME 指向该 bin 目录。
$env:FFMPEG_HOME = 'C:\ffmpeg\bin'
# 2. 构建并运行,点「打开视频…」选一个本地文件
dotnet run --project samples/ImageFacade.AvaloniaDemo
# 3. 直接带一个文件启动,省掉文件对话框
dotnet run --project samples/ImageFacade.AvaloniaDemo -- --open D:\clips\demo.mp4
# 4. 无图形会话时自检解码 + HUD 合成(结果写进输出目录的 decode-check.log,退出码表示成败)
dotnet run --project samples/ImageFacade.AvaloniaDemo -- --decode-check D:\clips\demo.mp4
上图是点「播放 RTMP 流」后截的窗口:那个按钮直接打开 rtmp://liteavapp.qcloud.com/live/liteavdemoplayerstreamid(腾讯云直播的公开 demo 源)。网络源和本地文件走同一条解码路径,唯一的多余设置是给 avformat_open_input 传 rw_timeout(5 秒),否则服务器不可达时解码线程会卡在 av_read_frame 里退不出来。
- 界面在
MainWindow.axaml,逻辑在MainWindow.axaml.cs。 - 后台解码线程按 PTS 节流产出直通 RGBA32 帧,UI 线程用
DispatcherTimer取最新帧写入WriteableBitmap;分辨率变化时重建位图。 - HUD 在
FrameComposer里用核心光栅完成:画布按尺寸建一次,之后每帧ImportPixels→FillRectangle/DrawText→CopyPixelsTo(framebuffer.Address, framebuffer.RowBytes, Rgba32),直接写进WriteableBitmap的像素内存。 - 窗口底部显示当前尺寸与播放时间。
- 根容器必须给一个不透明的
Background。这跟渲染后端无关:Avalonia 12.1.5 在「窗口背景不透明 + 根 Panel 的Background为null或Transparent」时,Button这类带模板的控件会整块不绘制(官方 Skia 后端同样复现),TextBlock、Border不受影响。给个不透明色即可,Transparent不管用。
一帧的旅程:FFmpeg → ImageFacade → SimdSkia
整条链路只有一次像素格式转换(sws_scale)和一次跨线程交接(换引用),中间不经过任何 Bitmap / SKBitmap / byte[] 的额外拷贝:
FFmpeg 解码线程(VideoPlayer.Run) UI 线程(DispatcherTimer,15 ms)
───────────────────────────────── ──────────────────────────────
av_read_frame → packet
→ avcodec_send_packet / receive_frame
→ AVFrame(yuv420p / nv12 …)
→ sws_scale → 直通 RGBA32
→ 帧池 byte[](4 块,首帧按分辨率建满)
│
│ _pending 换引用(不拷贝)
└────────── TryTakeFrame ──────────────► WriteableBitmap.Lock()
→ ILockedFramebuffer.Address
→ ImportPixels(直通 → 内部预乘)
→ FillRectangle + DrawText(HUD)
→ CopyPixelsTo(Address)(写回位图)
→ InvalidateVisual()
◄────── ReturnFrame ────── (缓冲还给池)
| 步骤 | 谁在做 | 每帧的代价 |
|---|---|---|
解码 + sws_scale 成 RGBA |
FFmpeg 原生库 | 一次整帧转换,写进池里的缓冲 |
交接 byte[] |
VideoPlayer |
换引用,0 拷贝 |
Lock() 拿位图内存 |
Avalonia / SimdSkia | 0 拷贝,直接给出像素地址 |
ImportPixels |
ImageFacade 光栅 | 一次直通 → 预乘转换(同一块内存) |
| HUD(矩形 + 两行字) | ImageFacade 光栅 | 微秒级 |
CopyPixelsTo(Address) |
ImageFacade 光栅 | 一次预乘 → 直通写回位图 |
| 上屏 | SimdSkia | 位图提交为纹理(后端内部) |
两个关键点:
- 缓冲归谁、什么时候建:帧池 4 块在首帧一次建满,UI 来不及取时旧帧直接丢弃(
RentBuffer返回null),池不会增长,也不会堆积延迟。 - 画布与位图都只建一次:分辨率变化才重建。
ImportPixels/CopyPixelsTo都在覆盖同一块内存,所以每帧没有new。
保存一帧:两条路,选一条
「保存图片」按钮取的是当前这一帧 FacadeImage(视频画面 + HUD 都在上面),有两种存法:
A. Sdcb 软后端(demo 里用的这条)——渲染和保存共用一个 SoftwareBackend 引擎:
// 启动时注册一次 PNG
ImageBackendBase.RegisterCodec(ImageFormat.Png, PngImageDecoder.Registration, PngImageEncoder.Registration);
using var engine = new ImageEngine(new SoftwareBackend());
FacadeImage canvas = engine.Create(width, height, Rgba32.Black);
// …每帧 ImportPixels + 画 HUD…
canvas.SavePng("frame.png"); // 直接编码,不需要中转缓冲
SoftwareBackend 的绘制 / 像素读写由 ImageBackendBase 直接转给核心光栅,和 new ImageEngine() 是同一份实现;编解码则挂在这个后端上。所以画布自己就能存,不必"核心光栅画、另一个引擎存"那样搬一次像素。编码时内部只从 PixelBufferPool(4 MiB 上限)租一次缓冲,960×720(2.7 MB)能命中复用。
B. Avalonia 主包自带的编码器——一个编解码包都不引:WriteableBitmap 已经是画好 HUD 的那一帧,直接交给 Avalonia 写盘即可(MainWindow.SaveFrameWithAvalonia,demo 里保留作示例、默认不调用)。
| A. Sdcb 软后端 | B. Avalonia Bitmap.Save |
|
|---|---|---|
| 额外依赖 | ImageFacade.SdcbSimdCodecs + Sdcb.SimdCodecs.Png |
无 |
| 数据来源 | FacadeImage 像素 |
WriteableBitmap 像素 |
| 可控项 | SaveOptions(压缩级别 / 元数据),可换 JPEG / WebP / BMP… |
只有后端默认值 |
| 不注册 codec 时 | Load / Save 抛 FeatureNotSupportedException |
照常可用 |
两种存法写出来的都是 960×720、含 HUD 的 PNG(同一个画面分别约 420 KB / 400 KB,压缩实现不同略有差异)。
命令行也能直接走这条路径(窗口摆到屏幕外,不抢前台):
dotnet run --project samples/ImageFacade.AvaloniaDemo -- --open D:\clips\demo.mp4 --save-frame D:\out\frame.png
# --shot D:\out\ui.png 则连窗口一起截(RenderTargetBitmap),用于验证界面
内存:链路侧零分配,曲线是窄幅锯齿
播放过程中不会反复分配大内存。 整条链路只有三处持有像素,每处都只建一次:
| 环节 | 创建时机 | 之后每帧做什么 |
|---|---|---|
解码帧池(4 块 byte[]) |
首帧按分辨率一次建满 | 取帧 / 归还只换引用,不 new、不复制 |
| ImageFacade 画布 | 分辨率变化时 Create |
ImportPixels 覆盖同一块内存,HUD 画在上面 |
WriteableBitmap |
分辨率变化时 new |
Lock() 后由 CopyPixelsTo 直接写进去 |
这三处就是每帧会走过的全部路径,全都是复用。960×720、约 30 fps 连跑 35 秒(--mem 每 2 秒采一行):
| 指标 | 采样区间 |
|---|---|
| fps | 29.4 ~ 30.7 |
| 托管堆 | 69.7 ~ 89.9 MB |
| LOH | 56.1 ~ 69.3 MB |
| 工作集 | 247 ~ 261 MB |
曲线是窄幅锯齿而不是台阶:GC 一过就落回基线,35 秒里没有任何单向爬升,也没有"越播越慢"。把 VideoView.InvalidateVisual() 临时注释掉再跑,分配速率掉到 0.9 MB/s、LOH 恒定 44.2 MB——说明解码、合成、写位图这一侧已经零分配,剩下的波动只来自 SimdSkia 把位图提交成纹理(约 2.4 MB/帧)。
SimdSkia 在这条链路里的好处很直接:
- 没有原生对象要管:不需要
SKBitmap/SKSurface/SKImage,也不需要Switch到 UI 线程做SKCanvas.DrawBitmap;一整帧的托管表示就是那张WriteableBitmap,不再有第二份"显示用"的缓冲。 - 没有原生 DLL:不引
SkiaSharp/SkiaSharp.NativeAssets.*,纯托管,dotnet publish出来就是全部,部署与 AOT 都省事。 - 波动可预期:链路上的分配是 0,渲染侧的量级固定,所以内存曲线稳定在几十 MB 的窄带里,不随时长增长。
如果连每帧那次纹理提交也想省掉,把 UseSimdSkiaDesktop() 换成官方的 UsePlatformDetect() 即可:解码、HUD 合成、写位图一行都不用改,官方 Skia 后端直接复用位图内存。早期用同一份代码对照测过(960×720、60 秒):托管堆 12.5 MB 恒定、LOH 10.5 MB(就是那 4 块帧池)、分配 0.2 MB/s、GC 1 次;而 SimdSkia 这条路上托管堆在 70~90 MB 来回、分配约 70 MB/s(就是上面那次 35 秒采样)。差别全在绘制路径——要零原生依赖 + AOT 选 SimdSkia,要极致的托管内存曲线选官方后端,这正是把渲染后端做成可替换的意义。
还能再省一次拷贝。 现在每帧要搬两遍全帧:帧池 → 画布(ImportPixels)、画布 → WriteableBitmap(CopyPixelsTo)。第一遍其实是白搬的:如果让画布直接落在帧池那块内存上(一张图只创建一次,之后每帧只是同一块内存换了内容),HUD 就画在解码输出上,最后只剩 CopyPixelsTo 这一趟。960×720 一帧 2.6 MB,15 fps 下等于少搬约 39 MB/s。
这条路眼下还没接通:ImageEngine.FromPixels(ptr, ..., wrap: true) 需要后端实现 TryWrapPixels 才真正零拷贝,而现有后端(软光栅 / Skia / ImageSharp / OpenCV)一律返回 false(内部是预乘或 BGRA,接不了直通 RGBA),现在调它只会退化成一次导入,白忙。要真省掉这趟搬运,得先让软光栅的画布支持零拷贝接管。
项目结构
src/
ImageFacade/ # 核心:契约 + 路由 + 排版 + 内置字体 + Pipeline
ImageFacade.SdcbSimdCodecs/ # 软后端:ImgProcSharp 渲染层 + 可插拔编解码(只引 Abstractions)
ImageFacade.SkiaSharp/ # SkiaSharp 3.119(编译目标,兼容 4.x)
ImageFacade.ImageSharp/ # ImageSharp 3.x + Drawing 2.x
ImageFacade.ImageSharp2/ # ImageSharp 2.x + Drawing 1.x(链接上一份源码)
ImageFacade.OpenCvSharp/ # OpenCvSharp4
ImageFacade.OpenCvSharp5/ # OpenCvSharp5(链接上一份源码)
tests/ # 一后端一测试工程,共享测试源码
samples/ImageFacade.Samples/ # 示例 + README 截图生成器
samples/ImageFacade.AvaloniaDemo/ # Avalonia + SimdSkia + FFmpeg.AutoGen 播放器
docs/images/ # 截图
半透明像素:判断依据、性能与注意事项
"这张图带不带 alpha 通道"和"这张图里到底有没有半透明像素"是两件事,混用会得到方向相反的错:
| 含义 | 例子 | |
|---|---|---|
Metadata.HasAlpha |
解码器声明的通道能力位 | 不透明 PNG(RGBA,但 α 全是 255)为 true |
Metadata.HasTransparency |
图里真的存在 α < 255 的像素 | 同一张图是 false |
决定"能不能直接按不透明编码""要不要先把图合成到背景色"的,永远是后者。
图本来就不透明:什么都不用做
大多数真实输入(相机 JPEG、屏幕截图、视频帧、自己合成的图)都是全不透明的。这种情况不需要写任何额外代码, 也不需要"声明一下我是透明的还是不透明的"——门面加载时就顺手把答案定下来了:
| 你的输入 | 加载时发生什么 | 之后还会不会再扫 |
|---|---|---|
| 没有 alpha 通道(JPEG / BMP / 三通道 PNG) | HasAlpha == false,直接定 HasTransparency = false,一个字节都不扫,连后端都不问 |
不会 |
| 有 alpha 通道但 α 全是 255(不透明 PNG / WebP / GIF) | 在后端自己那块内存上零拷贝扫一遍(1080p ≈ 0.2–0.4 ms、零分配),结论缓存为 false |
不会(除非你显式要求) |
所以整个生命周期里,这个特性对你的图最多只花加载时那一次只读扫描,此后每次 Save / Encode 都只是
"读一下缓存的 bool",不会为了判断 alpha 再扫第二遍:
- 存 PNG / WebP(带 alpha 的格式):
PrepareForEncode直接把原帧交给后端,不合成、不扫像素(alpha 提示字段照样传下去,但没人拿它做决定); - 存 JPEG / BMP(不带 alpha 的格式):靠缓存走快路径,跳过"建临时帧 + 整图拷贝 + 逐像素合成背景",
比不知道时更快;软后端还会把
AssumeOpaque = true一路带到Canvas.CopyToStraight, 连"导出对齐像素时顺手判一次透明"的那次扫描也一起省掉(Skia / ImageSharp / OpenCV 直接交给原生编码器,本来就不扫); - 反复保存同一张图 100 次:0 次额外扫描,第 2 次起和"没有这个特性"的开销完全一样。
唯一会再扫一次的情形只有一个:你自己调 DetectTransparency()(因为绘制过导致缓存变 null,或者传了 force: true)。
不调就一直用缓存值,缺省路径上没有任何隐藏的重扫。
结论从哪来
AlphaProbe.TryDetect 按顺序试两条路,都不通就返回 null,绝不猜:
问后端(
IImageBackend.TryGetTransparency,默认接口方法返回false)。四个内置后端都在自己已经持有的缓冲上 零拷贝扫一遍,门面一个像素都不用搬:后端 怎么答 答不上来的条件 Skia SKBitmap.GetPixels()直接读 premultiplied 像素的 alpha 字节位图不是 Rgba8888/ 像素指针为空ImageSharp DangerousTryGetSinglePixelMemory扫Rgba32像素被拆成多段内存(罕见) OpenCV Mat.Data+Step()按行扫Mat不是CV_8UC4软后端 Canvas.IsFullyOpaque()— 答不上来就落到第 2 条,结果一样对,只是慢一点。
借像素视图(
TryAcquirePixels):ImageSharp / OpenCV 是零拷贝,Skia / 软后端会拷一份整图再扫—— 所以那两个后端才自己去实现第 1 条,正常走不到这里。
加载收尾(ImageEngine.FinishLoad)在 LoadOptions.DetectTransparency(默认 true)打开时调一次;
HasAlpha == false 的输入直接定 false,连后端都不问——这就是"平台已经做好了,什么都不用做"的那种情形。
之后由 FacadeImage.DetectTransparency(bool force = false) 按需重算:有结论直接返回,force: true 无视缓存。
结论什么时候失效
| 操作 | HasTransparency 变成 |
为什么 |
|---|---|---|
Load(检测开) |
true / false |
解码后扫一次 |
Load(DetectTransparency = false) |
null |
没查 |
Create(background) |
背景色 A < 255 |
来源已知 |
FromPixels(...) |
null |
你看得见的字节,门面不替你假设 |
Clear(color) |
color.A < 255 |
整张图一个颜色 |
| 任意绘制(点 / 线 / 矩形 / 文字 / 贴图…) | null |
可能刚画进去半透明颜色或抗锯齿边 |
Resize 的 Stretch |
原值 | 重采样权重和为 1,既不凭空产生也不消掉 alpha |
Resize 的 Pad / BoxPad / Crop |
原值 false 且真的补了半透明边 → true,否则原值 |
只有补边能引入透明像素 |
绘制本身不顺手扫全图:一次 DrawLine 多花 0.3 ms 是不能接受的,这笔账留给真正需要答案的那次调用。
读到 null 时可以不管(它本身就是有效答案),也可以调一次 DetectTransparency()。
性能影响
量级参考(单核、顺序访存、x64;用来判断"要不要在意",不是基准报告):
| 场景 | 额外开销 |
|---|---|
| 后端直接回答(四个内置后端的常态) | 一遍全图只读扫描、零分配;1080p ≈ 0.2–0.4 ms,4K ≈ 1–1.5 ms |
退到 TryAcquirePixels 且该后端零拷贝(ImageSharp / OpenCV) |
同上,多一次 span 的借还,可忽略 |
退到 TryAcquirePixels 且该后端要拷贝(Skia / 软后端,正常不会发生) |
一次整图拷贝 + 扫描,1080p ≈ 1–2 ms 和一次 8 MB 分配 |
| 无 alpha 通道的输入(JPEG、BMP;Skia / OpenCV / 软后端还能识别三通道 PNG) | 0,连后端都不问 |
| 已知全不透明时的 JPEG / BMP 编码 | 省掉"新建合成帧 + 整图拷贝 + 逐像素合成",1080p ≈ 数 ms 加一次 8 MB 缓冲租借 |
| 已知全不透明时的 PNG / WebP 编码 | 0,直接编码,不查 alpha |
| 同一张图重复保存(任意格式) | 0,只用加载时那一次结论,不存在"保存时再确认一遍" |
DetectTransparency(force: true) |
同第一行,每次调用都重扫 |
参照系:1080p 解码本身在毫秒到十几毫秒,一次扫描是它的几个百分点;扫描是纯读,比一次同尺寸 memcpy 还便宜
(不用写、不用分配)。而 JPEG / BMP 编码那边省下来的是"拷贝 + 混合 + 分配",通常比扫描本身更贵。
什么时候值得关掉:
- 只读尺寸 / 元数据、批量出缩略图的流水线(图马上被缩放或丢弃,答案没人看);
- 服务端处理 4K 以上的大图,每张多 1 ms 攒起来能看见;
- 明确知道输入全不透明(相机 JPEG、屏幕截图、自己刚合成过的图)。
关掉后唯一的功能代价是 JPEG / BMP 编码省不掉"合成背景色"那一段:输出字节完全一样,只是慢了;
其它行为不受影响(null 是合法状态,谁都不会把它当 false 用)。
注意事项
- 三态,别当布尔用。
null不是false:== true(确定有透明)和== false(确定全不透明)是两个独立结论, 写成if (HasTransparency != false)会把"不知道"归到"有透明"那一类。 - 别用
HasAlpha顶替。带通道的图绝大多数是全不透明的;反过来HasAlpha == false时HasTransparency必定为false(加载期直接短路,手动重算也只会得到false)。 - 缓存会跨操作失效。别把加载时读到的
bool存起来、隔几次绘制再用——那时它已经是null或别的值了。 force: true每次都全图重扫,包括后端那条零拷贝路径。不要放进循环、不要每次Save前都调: 编码前的AssumeOpaque会自动用上缓存,不需要你催。- 探测不出来会反复试。后端既答不上来、
TryAcquirePixels也不可用(自定义后端没实现,或你根本关掉了像素访问)时,DetectTransparency()返回null且不写缓存,每次调用都要重试一遍;高频路径上请自己缓存结果或直接关掉检测。 - 手动改像素门面不知道。
AcquirePixels()写回、SharedMat()直接改Mat,都不会让结论失效; 用这类后门改完图,先DetectTransparency(force: true)再拿结论。 FacadeImage不是线程安全的。DetectTransparency会写ImageMetadata,同一张图别并发调用; 多线程各处理一张用Fork出来的副本。- 和 EXIF 方向无关。旋转 / 翻转不改变"是否存在 α < 255 的像素",
AutoOrient开与不开结论一致。 - 探测本身无副作用。不改像素、不改
IsZeroCopy、不留引用:TryAcquirePixels借来的 lease 扫完就还, 也不影响"零拷贝 / 共享内存"那条链路的语义。
文档
| 文件 | 内容 |
|---|---|
| plan.md | 设计、公开 API、SPI、里程碑、验收标准、性能目标 |
| planv2.md | 三批加固:解码尺寸上限、PixelLease 幂等、像素搬运优化、Save 失败语义、NMS/张量化热路径(含实测数据与剩余清单) |
| misc.md | 决策记录、许可证矩阵、逐库的坑、测试策略、已否决方案、落地记录(§Z) |
| THIRD-PARTY-NOTICES.txt | 第三方组件与许可证清单 |
许可证
本仓库以 Apache License 2.0 发布,全文见 LICENSE。
第三方组件见 THIRD-PARTY-NOTICES.txt。其中两条必须注意:
- SixLabors.ImageSharp 自 2.0 起是 Six Labors Split License(不是 Apache-2.0)。本仓库只做
PackageReference,但一旦引用Sevencat.ImageFacade.ImageSharp/Sevencat.ImageFacade.ImageSharp2,你的项目就直接依赖它。请自行确认授权条件;不适用时改用 Skia 或软后端。 - 文泉驿微米黑 随核心程序集以嵌入资源分发,采用 Apache-2.0 / GPLv3 双许可 + 字体嵌入例外,本仓库走 Apache-2.0 分支。声明见 licenses/LICENSE-WenQuanYiMicroHei.txt。
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Sevencat.ImageFacade (>= 0.5.0)
- SkiaSharp (>= 3.119.1)
-
net8.0
- Sevencat.ImageFacade (>= 0.5.0)
- SkiaSharp (>= 3.119.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.