libvips 的 demand-driven 执行模型

libvips 不是逐行读入、逐行处理的传统图像库。它是一个 需求驱动（demand-driven）的执行引擎——你对图像的操作只在真正有人要读取像素时才一起执行。这个设计既是 libvips 速度的来源，也是一些常见误解的原因。

构建了 Pipeline，但什么也没发生

以下代码：

image, err := vips.NewImageFromFile("input.jpg")
if err != nil {
    return err
}
defer image.Close()

if err := image.Resize(0.5, vips.KernelLanczos3); err != nil {
    return err
}
if err := image.GaussianBlur(3.0); err != nil {
    return err
}

文件加载器通常会先读取足以识别格式和元数据的内容，后续调用再构建处理图（Pipeline）：input.jpg → Load → Resize(0.5) → GaussianBlur(3.0) → (等待需求)。此时并未完整计算并保存最终像素；导出或写入会从下游向上游请求所需区域。

需求从哪里来

以下情况触发实际求值：

触发动作	说明
ExportJpeg() / ExportWebp() 等	编码器逐行读取结果
SaveToWriter() / TranscodeStream()	写入目标时逐块请求像素
另一个图像从当前图像读取（composite、join）	下游操作触发上游求值

顺序缓存（Line Cache）

libvips 不会一次性缓存整个图像。它会维护一个行 buffer 缓存——处理当前请求区域所需的那一小组行。

这意味着：

• 如果你按从上到下的顺序读取（sequential），libvips 只需要保持很少的行在内存中。
• 如果你需要随机访问（例如 90° 旋转需要先读取最后一行），libvips 可能不得不缓存整个输入——或报 out of order read 错误。

Sequential 与 Random Access

libvips 支持两种访问模式：

模式	行为	内存峰值
Random（默认）	可以任意顺序读取任何区域	缓存输入所需区域
Sequential	只能从上到下读取一次	主要由图像宽度、操作窗口和编解码器缓冲决定

Sequential 模式需要显式启用（access="sequential" 或 [access=sequential] 选项），并且限制你能做的操作——旋转、垂直翻转等需要非顺序读取的操作会失败。

为什么操作顺序影响内存

// 业务允许在低分辨率上模糊时，可以先缩小。
if err := image.Resize(0.1, vips.KernelLanczos3); err != nil {
    return err
}
if err := image.GaussianBlur(5.0); err != nil {
    return err
}

// 如果业务要求先在原始分辨率上模糊，顺序不能交换，代价也会更高。

先缩小再处理意味着后续所有操作只处理缩小的像素。这个原则与任何图像库一致，但在 libvips 中尤为重要，因为它在这里决定了整个 Pipeline 的实际计算量。

常见误解

• 误解 1: “vips.Startup() 在加载图片。” 不，它只初始化 libvips 运行时。
• 误解 2: “图像是在 Close() 前被处理的。” 处理在导出时按需发生；Close 只是释放图像引用。
• 误解 3: “每个操作都会生成一张完整中间图。” libvips 通常按区域串联求值；是否需要实体化取决于操作的访问模式。
• 误解 4: “需求驱动意味着延迟。” 恰恰相反——需求驱动让你的程序只计算实际需要的像素，避免不必要的工作。

风险提示

• Out of Order Read: 对 sequential 图像做随机访问操作会报错。
• Cache Miss 惩罚: 在大图上的随机访问比顺序访问慢得多。
• 不同 binding 默认值不同: govips 默认 random；sharp sequentialRead 可配置；pyvips access 可配置。

下一步

了解 Sequential 与 Random Access 的详细影响和决策点。

来源

• libvips How libvips works
• govips v2.19.0 README Streaming I/O section
• libvips 源码 conversion/sequential.c