使用 resvg 进行 PNG 栅格化

将生成的 SVG 矢量图转换为 PNG 格式，需要进行将其绘制为像素图像的栅格化处理。 为了避免对无头浏览器（如 Chromium）等重型组件或外部图像转换工具的依赖，console2svg 在发布的二进制文件中直接内置了基于 Rust 高性能 SVG 渲染器 resvg（在 SVG 规范还原度上表现卓越的 Rust 矢量图形库）的 C ABI 封装。 由此实现了无需启动外部进程的进程内调用，达成毫秒级的 PNG 栅格化性能。

为什么选择进程内嵌入而非外部命令

在操作系统中，通常存在诸如 rsvg-convert 或无头浏览器等现成的 SVG 转 PNG 命令行工具。 然而，console2svg 明确舍弃了将它们作为外部进程调用的方案，而是选择通过 C ABI 直接将其嵌入到当前进程内部。

最核心的原因在于：将操作系统字体目录扫描带来的巨大磁盘 I/O 开销严格限制在仅初次调用时发生。 要准确渲染 SVG 中的文本，渲染引擎必须完整遍历操作系统的字体存放目录（如 /usr/share/fonts、~/.fonts 以及 Windows/macOS 的系统字体文件夹），建立起系统中存在的所有字体家族的映射索引。 若通过 Process.Start 针对每一帧启动外部命令，每个帧都会派生一个独立的全新进程，每次都需要从磁盘重新扫描数千个字体文件，从而导致每帧累积数百毫秒的 I/O 延迟，且该开销会随总帧数成倍放大。

而采用进程内嵌入方案时，Rust 运行时可以通过其初始化机制 OnceLock<Arc<Database>>，将初次渲染时构建的系统字体数据库常驻缓存在进程内存中。 从第二帧开始的所有后续栅格化调用，都可以直接在内存中访问该字体缓存，使得磁盘扫描的 I/O 开销彻底降为零，即使在视频生成等涉及海量帧连续渲染的场景下，也能保持极高的吞吐性能。

此外，系统还允许在转换器自动探测流程中显式调用预热例程，从而在正式渲染开始前提前消除首帧的字体发现延迟。

进程内栅格化的执行流程

内置的原生库由负责解析 SVG 语法的 usvg、底层 2D 绘图引擎 tiny-skia 以及 resvg 本身构成。 其执行流程为：解析传入的 SVG 标记，将其绘制并展开为像素图（pixmap），随后将像素数据编码为 PNG 字节流并返回给调用方。

基于宽高比的输出尺寸约束

栅格化时的图像尺寸综合考量 SVG 自带的原始尺寸（如 viewBox 等固有属性）以及 CLI 指定的输出宽高参数进行计算。

当宽高均显式指定时，直接采用给定的具体数值；当仅指定了宽度或高度其中之一时，保持 SVG 原始纵横比自动计算另一维度；若两者均未指定，则直接采用 SVG 本身的尺寸作为像素大小。 计算出的最终尺寸在分配内存前会被严格限制（clamp）在 1 到 16,384 像素的区间内。 这有效避免了因 0 像素引发崩溃，或因误传参数导致在原生内存中分配极端庞大缓冲区的事故。

内存池租借与原生内存的安全释放

在 .NET 侧调用原生函数时，由 SVG 字符串转换而来的 UTF-8 字节数组会写入从 ArrayPool<byte> 租借的内存区域。 在将内存分配开销降至最低的同时，直接将该内存切片（span）传递给原生函数。

另一方面，原生侧生成的 PNG 字节数组其所有权属于 Rust 运行时。 .NET 侧的封装层从接收到的内存指针中将数据拷贝为托管的 byte[]，并在 finally 代码块中确保调用原生侧的释放函数（free）。 这种严密的边界设计使上层调用代码完全无需介入原生内存的生命周期管理。

优先检索内置的动态库资产

在加载原生动态库（.so、.dylib、.dll）时，console2svg 会在查找操作系统标准动态库检索路径之前，优先检索与自身可执行文件相邻的资源目录。

这一设计既能完美支持将动态库与主程序同目录打包的发布压缩包，又能兼容包管理器将原生资产安置在独立依赖目录中的布局规范。 即便是通过符号链接调用的场景，也能准确解析真实路径，避免受到当前工作目录的干扰。

显式指定与自动回退的严格区分

当图像转换引擎的判定模式（--svg-converter）为 auto 时，系统优先选用内置的 resvg。 若因平台环境受限导致 resvg 加载失败，系统会尝试自动回退到已安装的 rsvg-convert 或具备 SVG 解码能力的 ffmpeg。

然而，若用户显式指定了 --svg-converter resvg，一旦加载失败，系统绝不会擅自切换到其他引擎，而是立即作为错误终止执行。 这清晰地区分了自动探测时的容错便利性与显式指定时对渲染结果严格一致的可复现性要求。