SkiaSharp 1.57.0 API 差异解析：SKEncodedImageFormat 统一与破坏性变更迁移指南

图形学图像处理跨平台【免费下载链接】SkiaSharpSkiaSharp is a cross-platform 2D graphics API for .NET platforms based on Googles Skia Graphics Library. It provides a comprehensive 2D API that can be used across mobile, server and desktop models to render images.项目地址https://gitcode.com/gh_mirrors/sk/SkiaSharp点击查看免费下载本文基于仓库中的 1.57.0 版本 SkiaSharp.dll API diff 撰写对照 1.57.0 发布说明 逐条解读该版本全部 API 变更程序集版本从 1.56.0.0 升至 1.57.0.0并结合 binding/SkiaSharp 目录下的实际源码给出每个变更项的实现证据与迁移示例帮助你在升级包版本时快速定位破坏性变更、完成编码格式枚举的统一迁移并了解新增的编码、像素读取与 XPS 文档能力。版本主题编码格式对齐Encoded-format alignment1.57.0 发布说明 将本版本的主题概括为 Encoded-format alignment统一编码图像格式枚举并移除若干过期的 GPU 与图像处理辅助 API。具体而言SKCodec.EncodedFormat从返回SKEncodedFormat改为返回共享的SKEncodedImageFormat整个 API 从此共用同一个编码格式枚举SKImageEncodeFormat的值重新编号删除Unknown 0其余值整体前移一位移除GRPixelConfig.Index8与SKImage.ToTextureImage(GRContext)两个与 Skia 底层能力对齐后不再支持的 API。完整的差异清单分布在仓库三个文档中文档内容SkiaSharp.md完整 API diff新增 变更 删除SkiaSharp.breaking.md仅破坏性变更removed/modified1.57.0 索引页各程序集 diff 的导航入口下文按核心重构 → 破坏性变更 → 新增 API的顺序逐条展开。核心变更编码格式枚举的统一新增 SKEncodedImageFormat删除 SKEncodedFormat1.57.0 引入了新的顶层枚举SKEncodedImageFormat并删除了旧的SKEncodedFormat类型。API diff 中记录的新枚举定义如下[Serializable] public enum SKEncodedImageFormat { Astc 9, Bmp 0, Dng 10, Gif 1, Ico 2, Jpeg 3, Ktx 8, Pkm 7, Png 4, Wbmp 5, Webp 6, }该枚举在当前仓库的生成代码 SKEncodedImageFormat.generated.cs 中对应 Skia C API 的sk_encoded_image_format_t每个值都标注了对应的原生常量如BMP_SK_ENCODED_FORMAT 0说明它直接镜像 Skia 的格式编号体系。值得注意的是从生成代码结构看后续版本还扩充了Heif 11、Avif 12、Jpegxl 13等值——也就是说统一后的枚举成为后续新格式HEIF/AVIF/JPEG XL落地的唯一入口。这一设计的意义在于解码侧SKCodec.EncodedFormat与编码侧SKImage.Encode、SKBitmap.Encode、SKPixmap.Encode从此使用同一套类型消除了此前SKEncodedFormat/SKImageEncodeFormat两个并行枚举重复维护的问题。SKImageEncodeFormat 值重新编号API diff 明确记录了旧枚举SKImageEncodeFormat的字段值整体前移一位-Unknown 0 // 删除 -Bmp 1 Bmp 0 -Gif 2 Gif 1 -Ico 3 Ico 2 -Jpeg 4 Jpeg 3 -Png 5 Png 4 -Wbmp 6 Wbmp 5 -Webp 7 Webp 6发布说明 对此给出了明确的升级警告需要按新枚举值重新编译已持久化的整数值例如序列化存储的编码格式编号与新编号不兼容。如果你的项目中曾用(int)SKImageEncodeFormat.Png之类方式把格式编号写入库或配置文件升级后这些整数值会整体错位需要逐一检查。SKCodec.EncodedFormat 返回类型变更-public SKEncodedFormat EncodedFormat { get; } public SKEncodedImageFormat EncodedFormat { get; }迁移时只需把引用SKCodec.EncodedFormat的类型从SKEncodedFormat换成SKEncodedImageFormat由于新旧枚举在重叠部分采用相同的名称Bmp、Png、Jpeg等大多数switch/判断在改名后可以继续工作但case中写死整数值的分支必须核对。破坏性变更清单与迁移建议以下条目摘自 SkiaSharp.breaking.md每一条都给出了迁移方向。GRPixelConfig.Index8 被移除// 1.56.0 中存在 Index8 2, // 1.57.0 中替换为 Gray8 2,发布说明 解释其原因是与 Skia 移除 GPU 对索引色indexed colour支持保持一致。迁移方式很直接GPU 纹理配置中的GRPixelConfig.Index8改用GRPixelConfig.Gray8编号保持为 2语义从索引色变为8 位灰度。若你无法再使用索引色纹理需要用灰度或查找表替代的渲染路径需要重新评估。SKImage.ToTextureImage(GRContext) 被移除// 1.57.0 起不可用 public SKImage ToTextureImage (GRContext context);发布说明给出的替代方案是改用GRContext相关的SKImage工厂方法直接创建 GPU 后备图像而不是从 CPU 图像转换过去。SKMaskFilter 的浮雕与阴影工厂方法被移除// 三个方法在 1.57.0 中全部删除 public static SKMaskFilter CreateEmboss (float blurSigma, SKPoint3 direction, float ambient, float specular); public static SKMaskFilter CreateEmboss (float blurSigma, float directionX, float directionY, float directionZ, float ambient, float specular); public static SKMaskFilter CreateShadow (float occluderHeight, SKPoint3 lightPos, float lightRadius, float ambientAlpha, float spotAlpha, SKShadowMaskFilterShadowFlags flags);与此同时SKShadowMaskFilterShadowFlags类型也被整体删除。这两个效果在 Skia 上游已被淘汰替代做法是用SKImageFilter的模糊/颜色矩阵组合模拟浮雕效果或用自绘阴影绘制半透明模糊形状替代CreateShadow。SKWStream.NewLine 签名变更-public void NewLine (); public bool NewLine ();方法从无返回改为返回是否写入成功。现有调用点编译不报错多出的返回值可丢弃但依赖必然换行的逻辑现在应当检查返回值。当前仓库 SKStream.cs 中的实现印证了这一点/// summaryWrite a newline character to the stream, if one was not already written./summary public bool NewLine () { var result SkiaApi.sk_wstream_newline (Handle); GC.KeepAlive (this); return result; }文档注释同时说明了一个实用细节若流中最后一个字符已是换行符该方法不会重复写入。被整体删除的类型SKEncodedFormat由SKEncodedImageFormat取代SKShadowMaskFilterShadowFlags随SKMaskFilter.CreateShadow一并删除新增 API 与源码印证以下新增成员均收录于 SkiaSharp.md并结合当前仓库源码说明其实现位置与用法。SKBitmapPeekPixels / NotifyPixelsChanged / Encode(SKWStream)public bool Encode (SKWStream dst, SKEncodedImageFormat format, int quality); public void NotifyPixelsChanged (); public bool PeekPixels (SKPixmap pixmap);在 SKBitmap.cs 中可以看到实现细节PeekPixels (SKPixmap pixmap)调用sk_bitmap_peek_pixels成功时会把pixmap.pixelSource指回 bitmap 本身以维持生命周期关联返回false表示无法直接访问像素数据例如像素位于 GPU 上。配套的无参PeekPixels ()在失败时返回nullNotifyPixelsChanged ()调用sk_bitmap_notify_pixels_changed用于在绕过 bitmap 接口直接改写像素缓冲之后通知下游如画布、GPU 纹理缓存缓存失效——这是与PeekPixels/PeekPixels(SKPixmap)配套的低层工作流Encode (SKWStream dst, SKEncodedImageFormat format, int quality)提供了直接写入任意SKWStream的编码入口签名与SKImage/SKPixmap的流编码方法一致。典型用法无锁读取像素 直接编码到流using var bitmap new SKBitmap (256, 256, true); using var canvas new SKCanvas (bitmap); // ... 在 canvas 上绘制 ... // 无需 LockPixels尝试直接窥视像素 using var pixmap bitmap.PeekPixels (); if (pixmap ! null) { // 注意bitmap 一旦再次变化pixmap 立即失效 } // 编码到内存流 using var dst new SKDynamicMemoryWStream (); bitmap.Encode (dst, SKEncodedImageFormat.Png, 90); using var data dst.DetachAsData ();SKCanvas.DrawSurfacepublic void DrawSurface (SKSurface surface, float x, float y, SKPaint paint);让SKCanvas可以把另一张SKSurface当作可绘制内容直接贴到指定位置。当前仓库 SKCanvas.cs 中已扩展出多个重载SKPoint版本、带SKSamplingOptions的版本drawSurface内部委托给核心实现。这个 API 为离屏合成提供了比DrawImageGetImage()更直接的通道可以先画进目标 surface再在顶层画布上组合。SKData.Create(int / ulong)public static SKData Create (int size); public static SKData Create (ulong size);新增两个按字节数创建未初始化 SKData的工厂。当前仓库 SKData.cs 中Create (int size)与Create (ulong size)并存后者覆盖超出int范围的大缓冲场景。典型用途是先创建固定大小的SKData再经由其指针写入数据例如解码前的缓冲区、编码输出的暂存区。SKDocument.CreateXps(..., float dpi)public static SKDocument CreateXps (SKWStream stream, float dpi); public static SKDocument CreateXps (string path, float dpi);XPS 文档创建新增了对 DPI 的控制。当前仓库 SKDocument.cs 中可见完整的重载家族无参版本默认使用DefaultRasterDpi带float dpi的版本允许自定义光栅化分辨率后续版本又进一步扩展出接受SKDocumentXpsOptions的选项结构体见 SKDocumentXpsOptions.generated.cs。使用方式// 输出到文件指定 300 DPI using var doc SKDocument.CreateXps (report.xps, 300f); using var page doc.BeginPage (new SKSize (612, 792)); using var canvas page.GetCanvas (); canvas.DrawColor (SKColors.White); doc.EndPage ();SKDynamicMemoryWStream流拷贝与卸载为 SKDatapublic void CopyTo (SKWStream dst); public void CopyTo (IntPtr data); public SKData DetachAsData ();当前仓库 SKStream.cs 中SKDynamicMemoryWStream位于SKWStream体系内DetachAsData的实现第 909 行附近表明它会接管底层内存并返回SKData此后原流不可再使用——这就是上文Encode示例中using var data dst.DetachAsData ();的语义零拷贝地把整个内存流转为SKData比CopyTo更省一次内存复制。CopyTo (IntPtr data)则支持把流内容直接写进调用方提供的原生缓冲。SKPixmap.Encodepublic SKData Encode (SKEncodedImageFormat encoder, int quality); public bool Encode (SKWStream dst, SKEncodedImageFormat encoder, int quality); public static bool Encode (SKWStream dst, SKPixmap src, SKEncodedImageFormat encoder, int quality);SKPixmap此前没有编码能力1.57.0 补齐了这一环拿到像素块后可不经过SKBitmap/SKImage中间对象直接编码。当前仓库 SKPixmap.cs 中这些方法已进一步扩展出Stream重载和 WebP/JPEG/PNG 各格式专用选项SKWebpEncoderOptions、SKJpegEncoderOptions、SKPngEncoderOptions而早期版本的基础实现正是通过内部SKDynamicMemoryWStreamDetachAsData完成的——与上面SKDynamicMemoryWStream的新增成员形成闭环。SKSurfaceSurfaceProps 与像素读取public SKSurfaceProps SurfaceProps { get; } public void Draw (SKCanvas canvas, float x, float y, SKPaint paint); public SKPixmap PeekPixels (); public bool PeekPixels (SKPixmap pixmap); public bool ReadPixels (SKImageInfo dstInfo, IntPtr dstPixels, int dstRowBytes, int srcX, int srcY);这组 API 让SKSurface与SKBitmap的像素访问能力对齐PeekPixels系列尝试零拷贝读取ReadPixels则支持带源偏移(srcX, srcY)的拷贝式读取实现位于 SKSurface.csDraw与SKCanvas.DrawSurface互为镜像SurfaceProps属性暴露该 surface 的字体/像素几何配置。SKCodecFrameInfo.FullyRecievedpublic bool FullyRecieved { get; set; }针对多帧解码如 GIF的帧信息新增布尔属性用于区分数据是否已完整接收属性名保留了 Skia 上游的拼写Recieved。当前仓库 SKCodecFrameInfo.generated.cs 中该属性仍然存在。SKImageEncode 方法迁移- [Obsolete (Use Encode(SKEncodedImageFormat, int) instead.)] - public SKData Encode (SKImageEncodeFormat format, int quality); public SKData Encode (SKEncodedImageFormat format, int quality);旧签名1.56.0 已标记[Obsolete]被彻底移除新签名采用统一的SKEncodedImageFormat。当前仓库 SKImage.cs 中的Encode (SKEncodedImageFormat format, int quality)即此方法的现存形态。变更总览表类型变更影响GRPixelConfigIndex8改为Gray8值均为 2破坏性索引色纹理配置需改灰度方案SKBitmap新增Encode(SKWStream, …)、NotifyPixelsChanged()、PeekPixels(SKPixmap)新增SKCanvas新增DrawSurface(SKSurface, float, float, SKPaint)新增SKCodecEncodedFormat返回类型改为SKEncodedImageFormat破坏性需改类型引用SKCodecFrameInfo新增FullyRecieved新增SKData新增Create(int)、Create(ulong)新增SKDocument新增CreateXps(SKWStream/string, float dpi)新增SKDynamicMemoryWStream新增CopyTo(SKWStream)、CopyTo(IntPtr)、DetachAsData()新增SKImageToTextureImage(GRContext)移除Encode改用SKEncodedImageFormat破坏性SKImageEncodeFormat删除Unknown 0其余值前移一位破坏性持久化整数值不兼容SKMaskFilter移除CreateEmboss×2、CreateShadow破坏性需用替代方案实现效果SKPixmap新增三个Encode重载新增SKSurface新增SurfaceProps、Draw、PeekPixels×2、ReadPixels新增SKWStreamNewLine()由void改为bool轻微调用点建议检查返回值SKEncodedFormat类型删除破坏性SKShadowMaskFilterShadowFlags类型删除破坏性SKEncodedImageFormat新类型Bmp…Dng 共 11 个值新增统一枚举升级实操清单全局替换类型名把工程中的SKEncodedFormat全部替换为SKEncodedImageFormat编译错误会精确指出所有残留点SKEncodedFormat类型已删除无法静默通过。审计持久化的格式编号搜索代码中所有(int)转换、序列化字段和配置文件里写死的编码格式整数值——SKImageEncodeFormat重编号后旧整数在新枚举中会指向错误的格式例如旧值5原来是Png新编号下5是Wbmp。处理 GPU 索引色GRPixelConfig.Index8改为Gray8并确认渲染路径不依赖调色板。移除对已删 API 的调用SKImage.ToTextureImage(GRContext)、SKMaskFilter.CreateEmboss/CreateShadow需要按上文方案改写。利用新增能力优化热路径像素窥视PeekPixels替代频繁的LockPixels/UnlockPixelsSKPixmap.Encode跳过中间对象DetachAsData零拷贝收割内存流。以文档核对差异升级前可对照 完整 diff 与 仅破坏项 diff 逐项自查确保没有遗漏。附注如何阅读后续版本1.57.0 索引页 还列出了SkiaSharp.Views.Android、SkiaSharp.Views.Desktop、SkiaSharp.Views.Mac、SkiaSharp.Views.UWP、SkiaSharp.Views.WPF、SkiaSharp.Views.iOS、SkiaSharp.Views.tvOS与SkiaSharp.Views.Forms各程序集的 diff 文档升级时若使用了视图封装层建议一并查阅对应文件。需要说明的是当前仓库源码binding/SkiaSharp反映的是 1.57.0 之后的演进结果SKEncodedImageFormat已扩充出Heif、Avif、Jpegxl等值SKDocument.CreateXps支持SKDocumentXpsOptionsSKPixmap.Encode增加了各格式编码器选项。本文以 1.57.0 的 diff 文档为基准陈述变更事实源码引用仅用于印证实现脉络两版之间的细微差异请以对应版本的文档为准。赞分享图形学图像处理跨平台【免费下载链接】SkiaSharpSkiaSharp is a cross-platform 2D graphics API for .NET platforms based on Googles Skia Graphics Library. It provides a comprehensive 2D API that can be used across mobile, server and desktop models to render images.项目地址https://gitcode.com/gh_mirrors/sk/SkiaSharp点击查看免费下载相关推荐SkiaSharp 1.57.0 破坏性变更全解析API 移除、枚举重排与迁移指南SkiaSharp 1.57.0 破坏性变更全解析API 移除、枚举重排与迁移指南 本文围绕 SkiaSharp 1.57.0 与 1.56.0 之间的 AP图形学图像处理跨平台SkiaSharp 1.55.0 破坏性变更详解API Diff 与升级迁移指南SkiaSharp 1.55.0 破坏性变更详解API Diff 与升级迁移指南 本文基于 SkiaSharp 官方发布说明中的 1.55.0 SkiaSha图形学图像处理跨平台SkiaSharp 1.53.1 破坏性变更解析SKImageFilter.CreateDownSample 移除与 CreateDropShadow 迁移指南SkiaSharp 1.53.1 破坏性变更解析SKImageFilter.CreateDownSample 移除与 CreateDropShadow 迁移指图形学图像处理跨平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考