vips-rs

此包提供对 libvips 的绑定。

文档

libvips 的绑定。

使用方法

[dependencies]
vips-sys = "*"

1. 创建一个 VipsInstance。
2. 进行你的工作。

   extern crate vips;
   use vips::*;
   
   fn main() {
       let instance = VipsInstance::new("app_test", true);
       let img = VipsImage::new_from_file("kodim01.png").unwrap();
       let img = img.thumbnail(123, 234, VipsSize::VIPS_SIZE_FORCE);
       img.write_to_file("kodim01_123x234.png").unwrap();
   }
   

3. 在 VipsInstance 被销毁后，你不能实例化另一个。

注意

• API 不完整。
• 如果你找不到需要的接口，可以直接使用 vips-sys。

设计待办事项

• varargs 的简单接口。
• 将 _buf 方法添加到 &[u8] 作为 trait 吗？

libvips 的工作原理

• https://jcupitt.github.io/libvips/API/current/How-it-works.md.html

术语

• band: 通道
• image: 文件图像 / 内存（RGB）图像 / 等。你不能直接访问像素。
• region: 图像的子区域。实际上是从图像中读取像素。
• 部分图像：一个为矩形区域生成像素的函数

初始化/关闭生命周期

libvips 要求用户在开始时调用 vips_init()，在结束时调用 vips_shutdown()。

vips_shutdown 确保异步操作完成并释放所有资源。可选地，它会报告任何内存泄漏。

绑定提供 VipsInstance 用于 RAII。vips 的一个特殊行为是在调用 vips_shutdown 后，你不应该再次调用 vips_init。为了防止用户这样做，你可以在程序的整个生命周期中仅创建一次 VipsInstance 实例。当你第二次调用 VipsInstance::new（即使第一个实例已销毁），你会得到 Result::Err。

内存管理

libvips 使用 gobject。ffi 层后面的内存由 gobject 的垃圾收集器管理。如果你的 VipsImage 拥有 rust 内存，它会在 gobject 被销毁时注册解除分配回调。

{
    let img2 = {
        // creates new vips::VipsImage that points to the first vips_sys::VipsImage
        let img1 = VipsImage::from_memory(vec);
        // creates new vips::VipsImage that points to the second vips_sys::VipsImage
        img1.some_operation()
    };
    // img1 is destroyed. calls g_object_unref(first vips_sys::VipsImage).
    // the first vips_sys::VipsImage is destroyed
    // because referenced by the cond vips_sys::VipsImage,
}
// img2 is destroyed.
// the second vips_sys::VipsImage is destroyed.
// the first vips_sys::VipsImage is destroyed.
// gobject callbacks the rust deallocator, and vec is destroyed in rust side. 

拥有 vs 借用

VipsImage 根据其创建方式拥有或借用其像素数据。

VipsImage::new_memory、VipsImage::from_file 或 VipsImage::from_memory 拥有数据。 VipsImage::from_memory_reference 借用像素数据。

如果您使用对您的数据的引用创建一个 VipsImage，并对图像应用操作以获取另一个 VipsImage，则您的像素数据需要比第二个 VipsImage 活得更久。然而，第一个 VipsImage 不需要比第二个活得更久。

您可以在 /tests 中找到关于哪些可行和哪些不可行的信息。

没有原地操作

Vips 操作对输入图像没有副作用。

内存与缓冲区

您可以在 API 名称中找到这些词汇。例如，有 vips_image_new_from_memory 和 vips_image_new_from_buffer。它们并不相同。

• 内存是一个简单的（例如 RGB）数组
• 缓冲区是格式化的（jpeg、png 等）内存数据

某些操作直接在缓冲区上工作。例如，jpeg 缓冲区在解码过程中可以被缩小。