SkiaSharp 1.53.1 API 变更深度解析:SKColorTable 索引色支持与图像滤镜演进
SkiaSharp 1.53.1 API 变更深度解析:SKColorTable 索引色支持与图像滤镜演进
SkiaSharp 是基于 Google Skia 图形库的 .NET 跨平台 2D 绘图 API。在 1.53.1 版本中,核心程序集 SkiaSharp.dll 围绕 Index8 索引色(palette 调色板)图像解码 引入了一组重要 API:新增 SKColorTable 类型,并为 SKBitmap、SKCodec 补齐了颜色表相关的构造、属性与方法重载;同时将图像滤镜 CreateDownSample 正式重命名为 CreateDropShadow,并补充了 SKCodecOptions 与 SKRectI 的便捷默认值。本文以官方 API diff 文档(documentation/docfx/releases/1.53.1/SkiaSharp/SkiaSharp.md)为骨架,结合仓库源码逐项解读这些变更,帮助你在升级后正确使用索引色位图解码与阴影滤镜。
一、1.53.1 变更总览
本次 SkiaSharp.dll 的公开 API 变更共涉及 6 个类型,可用下表快速定位:
| 类型 | 变更性质 | 核心内容 |
|---|---|---|
SKBitmap |
扩展 | 新增带 SKColorTable 的构造函数、ColorTable 属性、GetIndex8Color(x, y) 方法 |
SKCodec |
扩展 | 新增 6 个支持颜色表输出的 GetPixels 重载 |
SKCodecOptions |
扩展 | 新增 2 个构造函数与静态字段 Default |
SKImageFilter |
破坏性 | 移除 CreateDownSample,新增 CreateDropShadow |
SKRectI |
扩展 | 新增静态字段 Empty |
SKColorTable |
全新类型 | 新增索引颜色表封装类,继承 SKObject 并实现 IDisposable |
其中,SKColorTable 的引入是本次变更的主线:它让 SkiaSharp 第一次可以在托管侧完整表达 Index8 颜色索引位图(每个像素存储 8 位索引,通过颜色表映射为真实颜色),并支持在解码 PNG/GIF 等调色板格式时直接输出索引数据。
二、全新类型 SKColorTable:索引位图的数据基石
SKColorTable 是本版本全新加入的类型,完整签名如下(摘自官方 diff 文档):
public class SKColorTable : SkiaSharp.SKObject, System.IDisposable {
// 构造函数
public SKColorTable ();
public SKColorTable (SKColor[] colors);
public SKColorTable (int count);
public SKColorTable (SKColor[] colors, int count);
// 字段
public static const int MaxLength;
// 属性
public SKColor[] Colors { get; }
public int Count { get; }
// 方法
protected override void Dispose (bool disposing);
public IntPtr ReadColors ();
}
2.1 构造方式与典型用途
SKColorTable():创建空颜色表,随后可通过后续操作填充。SKColorTable(SKColor[] colors):用现有颜色数组初始化整张表。SKColorTable(int count):按指定条目数预分配颜色表。SKColorTable(SKColor[] colors, int count):从颜色数组中取前count项初始化。
颜色表本质上是一个 颜色查找表(Look-Up Table),其中每个索引值(0~255)对应一个 SKColor。对于 Index8 位图,像素缓冲区里保存的不是 ARGB 值而是索引,渲染或读取像素颜色时必须经过这张表换算。
2.2 与长度约束相关的实现证据
diff 文档中声明了 public static const int MaxLength。虽然 diff 文档未直接给出数值,但从仓库中同族 API 的约束可以推断其量级:SKMaskFilter.CreateTable 要求表长度恰为 256(见 binding/SkiaSharp/SKMaskFilter.cs 中 TableMaxLength = 256 的校验),SKColorFilter.CreateTable 系列同样以 256 为硬性上限(见 binding/SkiaSharp/SKColorFilter.cs)。结合 Skia 原生层颜色表的设计(8 位索引对应 256 个条目),可以推断 SKColorTable.MaxLength 同样为 256,即一张索引颜色表最多承载 256 种颜色。
2.3 ReadColors 与内存访问
ReadColors() 返回 IntPtr,指向颜色表的原生内存布局;Colors 属性则提供托管侧的 SKColor[] 视图,Count 表示当前条目数。在需要把颜色表交给原生层(如 SKCodec.GetPixels 的 IntPtr colorTable 重载)时,ReadColors() 是低开销的直通通道。
三、SKBitmap:Index8 位图的全链路支持
SKBitmap 新增了三个成员,构成"创建 → 读取 → 查询"的完整闭环:
// 新增构造函数:以图像信息 + 颜色表创建位图
public SKBitmap (SKImageInfo info, SKColorTable ctable);
// 新增属性:获取位图关联的颜色表
public SKColor ColorTable { get; } // 注意:diff 文档中属性类型为 SKColorTable
// 新增方法:直接读取 (x, y) 处像素经颜色表映射后的颜色
public SKColor GetIndex8Color (int x, int y);
3.1 构造函数与颜色类型的约束
SKBitmap(SKImageInfo info, SKColorTable ctable) 允许在创建位图时一并指定颜色表,这意味着 info.ColorType 应为 SKColorType.Index8。这一约束在源码中留有明确注释——binding/SkiaSharp/SKBitmap.cs 定义了:
private const string UnsupportedColorTypeMessage =
"Setting the ColorTable is only supported for bitmaps with ColorTypes of Index8.";
即:只有 ColorType 为 Index8 的位图才允许设置颜色表,对非索引色位图设置颜色表会触发该错误提示。这一点对升级后的使用尤为重要:不要试图给 Rgba8888 等常规位图附加颜色表。
3.2 GetIndex8Color:索引像素的便捷读色
GetIndex8Color(int x, int y) 返回坐标处像素经颜色表换算后的 SKColor。在 Index8 位图中,GetPixel(x, y) 这类通用读色方法需要先查表;而 GetIndex8Color 封装了"取索引 → 查颜色表 → 返回颜色"的完整过程,避免调用方自行维护索引到颜色的映射逻辑。测试目录中已有针对 Index8 位图数据保持的用例(见 tests/Tests/SkiaSharp/SKBitmapTest.cs 的 CopyIndex8ToPlatformPreservesData、OverwriteIndex8ToPlatformPreservesData),验证了索引位图在平台间拷贝/覆盖时数据完整性的行为。
四、SKCodec:颜色表解码重载家族
为了让调色板格式(PNG、GIF 等)在解码时能直接产出索引像素与颜色表,SKCodec 一口气新增了 6 个 GetPixels 重载:
public SKCodecResult GetPixels (SKImageInfo info, IntPtr pixels, SKColorTable colorTable, ref int colorTableCount);
public SKCodecResult GetPixels (SKImageInfo info, IntPtr pixels, IntPtr colorTable, ref int colorTableCount);
public SKCodecResult GetPixels (SKImageInfo info, IntPtr pixels, SKCodecOptions options, SKColorTable colorTable, ref int colorTableCount);
public SKCodecResult GetPixels (SKImageInfo info, IntPtr pixels, SKCodecOptions options, IntPtr colorTable, ref int colorTableCount);
public SKCodecResult GetPixels (SKImageInfo info, IntPtr pixels, int rowBytes, SKCodecOptions options, SKColorTable colorTable, ref int colorTableCount);
public SKCodecResult GetPixels (SKImageInfo info, IntPtr pixels, int rowBytes, SKCodecOptions options, IntPtr colorTable, ref int colorTableCount);
4.1 参数语义
info/pixels/rowBytes:目标图像信息、输出像素缓冲指针与每行字节数(stride),语义与既有GetPixels重载一致(参见 binding/SkiaSharp/SKCodec.cs 中现有重载的实现)。colorTable:既可以是托管对象SKColorTable,也可以是原生IntPtr指针(配合ReadColors()使用)。colorTableCount:以ref传入传出。传入时表示颜色表缓冲可容纳的条目数,解码后传出实际写入的颜色条目数——这是索引解码场景特有的"缓冲容量协商"模式。调用前应确保颜色表缓冲足够大(上限参考SKColorTable.MaxLength),解码成功后据此截取有效颜色。
4.2 与既有解码链路的关系
仓库中既有的 GetPixels 实现(如 binding/SkiaSharp/SKCodec.cs)在调用 SkiaApi.sk_codec_get_pixels 前会构造 SKCodecOptionsInternal,把 ZeroInitialized、Subset、FrameIndex、PriorFrame 等选项映射为原生结构。新增的颜色表重载是在这条链路基础上叠加颜色表输出通道:当解码源为调色板格式且目标 ColorType 为 Index8 时,解码器将索引像素写入 pixels,同时把颜色表写入 colorTable 并更新 colorTableCount。
五、SKCodecOptions:便捷构造与默认值
SKCodecOptions 新增了两个构造函数和一个静态默认值字段:
public SKCodecOptions (SKZeroInitialized zeroInitialized);
public SKCodecOptions (SKZeroInitialized zeroInitialized, SKRectI subset);
public static SKCodecOptions Default;
5.1 Default 的实际语义
从仓库实现看(binding/SkiaSharp/Definitions.cs),Default 的取值是:
static SKCodecOptions ()
{
Default = new SKCodecOptions (SKZeroInitialized.No);
}
即 默认选项 = 非零初始化 + 无 subset 子区域。这与 SKZeroInitialized 枚举的语义一致:No 表示目标像素内存不是零初始化的,解码器需要完整写入所有像素;Yes 则表示内存已清零,解码器可跳过部分写入以优化性能。默认情况下安全地选择 No,避免调用方遗漏初始化导致脏数据。
5.2 各构造参数的作用
SKZeroInitialized:告知解码器目标缓冲区是否已预清零,直接影响解码器能否做写入优化。SKRectI subset:指定只解码原图的一个子矩形区域,输出缓冲只需覆盖该区域(HasSubset为true时底层才会传递 subset 指针,参见 binding/SkiaSharp/SKCodec.cs)。
这两个新构造函数补全了此前只能通过属性逐个赋值的繁琐路径,配合 Default 字段,让 GetPixels 调用可以写成:
var result = codec.GetPixels (
info, pixels, info.RowBytes,
SKCodecOptions.Default,
colorTable, ref colorTableCount);
六、SKImageFilter:CreateDownSample 正式更名 CreateDropShadow
这是本次 diff 中唯一的破坏性变更:
// 已移除
public static SKImageFilter CreateDownSample (
float dx, float dy, float sigmaX, float sigmaY, SKColor color,
SKDropShadowImageFilterShadowMode shadowMode,
SKImageFilter input, SKImageFilter.CropRect cropRect);
// 新增(参数完全对齐)
public static SKImageFilter CreateDropShadow (
float dx, float dy, float sigmaX, float sigmaY, SKColor color,
SKDropShadowImageFilterShadowMode shadowMode,
SKImageFilter input, SKImageFilter.CropRect cropRect);
6.1 重命名而非新增能力
对比两组签名可见:参数列表完全一致,仅是方法名从 CreateDownSample 变更为 CreateDropShadow。这次更名是为了与 Skia 原生 API(SkDropShadowImageFilter)及业界通用术语对齐——CreateDownSample 这个历史命名存在歧义("降采样"与"投影"语义毫不相关),而实际功能是创建投影(drop shadow) 图像滤镜。
6.2 参数含义与当前源码实现
各参数含义:
dx/dy:阴影相对源图像的水平、垂直偏移量。sigmaX/sigmaY:高斯模糊在 X、Y 方向的标准差,控制阴影边缘的柔和程度。color:阴影颜色。shadowMode:阴影模式(SKDropShadowImageFilterShadowMode)。input:输入滤镜,null时使用源图像本身。cropRect:输出处理限制矩形。
当前仓库源码中,CreateDropShadow 提供 5 参数、6 参数(含 input)、7 参数(含 cropRect)三层便捷重载,最终统一调用底层 SkiaApi.sk_imagefilter_new_drop_shadow(见 binding/SkiaSharp/SKImageFilter.cs):
public static SKImageFilter CreateDropShadow (
float dx, float dy, float sigmaX, float sigmaY,
SKColor color, SKImageFilter? input, SKRect cropRect) =>
CreateDropShadow (dx, dy, sigmaX, sigmaY, color, input, &cropRect);
private static SKImageFilter CreateDropShadow (
float dx, float dy, float sigmaX, float sigmaY, SKColor color,
SKImageFilter? input, SKRect* cropRect)
{
var filter = GetObject (SkiaApi.sk_imagefilter_new_drop_shadow (
dx, dy, sigmaX, sigmaY, (uint)color,
input?.Handle ?? IntPtr.Zero, cropRect));
GC.KeepAlive (input);
return filter;
}
与之配套的还有 CreateDropShadowOnly(只绘制阴影、不叠加源图像,调用 sk_imagefilter_new_drop_shadow_only),适用于需要单独提取阴影图层的场景。
6.3 升级迁移要点
如果你在旧版本代码中使用了 CreateDownSample,升级 1.53.1 后编译将直接报错(方法已移除)。迁移方式很简单:将调用处的 CreateDownSample 一字不改地替换为 CreateDropShadow 即可,因为参数与语义完全对齐。这是纯机械式重命名,不涉及行为变化。
七、SKRectI.Empty:与 SKRect 对齐的空白矩形常量
SKRectI 新增了静态字段:
public static SKRectI Empty;
在 binding/SkiaSharp/MathTypes.cs 中,Empty 被声明为 public static readonly SKRectI Empty,表示一个坐标全为 0 的"空矩形"。它的用途主要是:
- 作为"无子区域"的哨兵值,与
SKCodecOptions.Subset的可空语义配合; - 与既有
IsEmpty判断(this == Empty,见 binding/SkiaSharp/MathTypes.cs)构成完整的判空能力,让SKRectI与早已提供Empty的SKRect、SKSize等类型保持一致的 API 习惯。
八、升级与使用建议
综合本次 diff,升级到 1.53.1 时建议按以下清单检查代码:
- 全局搜索
CreateDownSample:替换为CreateDropShadow,这是本次唯一的编译期破坏点。 - 如需解码调色板格式为索引位图:使用
new SKBitmap(info, colorTable)创建位图,配合SKCodec.GetPixels的颜色表重载;注意info.ColorType必须是Index8,且颜色表缓冲按ref colorTableCount的容量协商方式使用。 - 读取索引位图像素颜色:优先使用
SKBitmap.GetIndex8Color(x, y),避免手动维护索引 → 颜色映射。 - 构造解码选项:优先使用
SKCodecOptions.Default或新增的两个构造函数,仅在需要子区域解码或已知缓冲已清零时,再显式指定subset与SKZeroInitialized.Yes。 - 矩形判空:可用
SKRectI.Empty作为统一哨兵,并配合IsEmpty属性。
九、总结
SkiaSharp 1.53.1 的 API 变更主题明确:为 Index8 索引色位图补齐从"颜色表对象"(SKColorTable)、"位图创建与读色"(SKBitmap)到"调色板解码"(SKCodec + SKCodecOptions)的完整托管链路,同时以一次纯重命名(CreateDownSample → CreateDropShadow)消除了图像滤镜 API 的命名歧义。对于处理 GIF、8 位 PNG 等调色板格式的开发者,这些 API 让索引解码可以完全在托管层完成,无需手动拆解像素字节;对于所有升级用户,只需留意唯一的破坏性更名即可平滑迁移。完整的逐项变更清单,可随时查阅官方 diff 文档 documentation/docfx/releases/1.53.1/SkiaSharp/SkiaSharp.md。