企业官网建设流程全解析

• 图像处理

libvips 的 API 参考将一组贯穿整个库的基础数据类型与辅助工具归入 "Basic" 一节（见 doc/libvips-basic.md）：它们不是图像处理算子，而是 libvips 全部操作、图像元数据与语言绑定所依赖的"地基"——包括引用计数的内存块VipsArea、由其派生的VipsBlob/VipsRefString/VipsArrayInt/VipsArrayDouble/VipsArrayImage/VipsSaveString等容器类型、基础别名VipsPel、若干回调函数类型，以及一批用于在GValue与这些容器之间搬运数据的辅助函数。读完本文，你将掌握这些类型的内存管理契约（谁 ref、谁 unref）、各自的适用场景（字符串、二进制、数值数组、图像数组），以及如何在 C 代码和语言绑定中安全地读写它们。

一、从索引页到源码：Basic 一节的完整构成

doc/libvips-basic.md是 libvips API 文档中 "Operator index > By section > Basic" 的入口页，它把该节内容划分为五类：

这些声明集中在两个头文件中：libvips/include/vips/type.h（各 GType 的定义与函数原型）与 libvips/include/vips/basic.h（VipsPel、回调类型、弃用宏），实现则位于 libvips/iofuncs/type.c（约 2000 行，文件头注释明确写着 "array type: unlike GArray, this has fixed length, tracks a GType for elements, and has a per-element free function"）。所有的类型注册统一由vips__meta_init_types()（type.c）在vips_init()时完成。

二、地基：引用计数的内存块 VipsArea

VipsArea是 Basic 一节中最核心的结构，注释称其为 "A ref-counted area of memory. Can hold arrays of things as well"（type.h）。它在裸指针之上增加了引用计数、可选长度、可选元素类型信息和一个可自定义的释放函数：

typedef struct _VipsArea { void *data; /* 数据指针 */ size_t length; /* 字节长度，0 表示未知 */ int n; /* 若表示数组，元素个数 = length / sizeof(元素) */ int count; /* 引用计数 */ GMutex lock; /* 保护 count 的锁 */ VipsCallbackFn free_fn; /* 自定义释放函数，如 ICC profile 需要特制的 free */ void *client; /* 客户端数据，VipsArea 自身不使用 */ GType type; /* 若持有数组，元素的 GType */ size_t sizeof_type; /* 若持有数组，元素的 sizeof */ } VipsArea;

2.1 生命周期：new / copy / unref

• vips_area_new(free_fn, data)：创建一块引用计数为 1 的区域，data的所有权随free_fn转移。实现中count初始化为 1、锁被初始化（type.c），因此文档注释特别提醒："Initial count == 1, soArea.unrefafter attaching somewhere"，即把 area 挂载到某个对象上后必须自己 unref 一次。
• vips_area_copy(area)：在锁内把count += 1并返回同一个指针，是浅拷贝语义的引用计数增加（type.c）。
• vips_area_unref(area)：count -= 1，减到 0 时先调用free_fn(data, area)释放数据，再清理锁并释放 area 本身（type.c）。若开启了泄漏检查（vips__leak），每个 area 还会登记在全局链表vips_area_all上，配合vips__type_leak()可报告存活数量、引用计数与字节数——这是 libvips 自检内存泄漏的机制之一。

2.2 数组化：new_array 与 new_array_object

• vips_area_new_array(GType type, size_t sizeof_type, int n)：分配n * sizeof_type字节并挂上vips_area_free_cb（即g_free），同时填充n、length、type、sizeof_type四个字段（type.c）。返回值"transfer full"，用完必须 unref。
• vips_area_new_array_object(int n)：持有GObject *数组的特殊版本。它额外多分配一个NULL结尾元素（注释说明这是为vips_image_pipeline_array等函数准备的），释放时通过vips_area_free_array_object对每个元素调用g_object_unref（type.c）。VipsArrayImage就是建立在它之上。

2.3 取数据：vips_area_get_data

vips_area_get_data(area, &length, &n, &type, &sizeof_type)一次性返回数据指针，并可选择性地带回长度、元素个数、元素 GType 与元素大小（全部参数均可为 NULL，type.c）。返回值不增加引用（transfer none），调用方不得释放。

三、七种容器类型：选型与用法

Basic 一节定义了七个 boxed 结构，其中除VipsSaveString外，其余六个都是把VipsArea作为首成员（VipsRefString、VipsBlob、VipsArrayInt、VipsArrayDouble、VipsArrayImage的声明都是typedef struct _VipsXxx { VipsArea area; } VipsXxx;），因此它们与VipsArea之间可安全互转：VIPS_AREA(X)宏就是一次强转（type.h）。

3.1 VipsRefString：引用计数的不可变字符串

用于在图像元数据中保存字符串（type.c）。特点：

• vips_ref_string_new(str)：内部用g_utf8_make_valid强制字符串为合法 UTF-8，并把长度缓存到area->length；注释明确"Strings must be valid utf-8; use blob for binary data"。
• vips_ref_string_get(refstr, &length)：返回内部 C 字符串指针（transfer none）。
• 它注册了与G_TYPE_STRING、VIPS_TYPE_SAVE_STRING之间的双向 GValue 变换函数，因此元数据里的字符串可以被自由地读到普通 GString 中。
• 相比普通 GValue 字符串，refstring 在图像之间复制时只复制引用计数指针，开销小得多（见vips_value_set_ref_string的注释）。

3.2 VipsBlob：带长度的二进制块

用于 ICC profile、EXIF 等二进制数据（type.c）：

• vips_blob_new(free_fn, data, length)：像Area.new一样接管data，但额外追踪length；若不想转移所有权，传NULL的free_fn。
• vips_blob_copy(data, length)：内部g_malloc+memcpy一份拷贝，对难以写回调的语言绑定更友好（"Useful for bindings which struggle with callbacks"）。
• vips_blob_get(blob, &length)：取数据指针与长度。
• vips_blob_set(blob, free_fn, data, length)：先释放旧数据再挂新数据，用于"先创建空 blob 后填充"的场景。
• Blob 是可迁移的：保存到 VIPS 文件时会被编码为 XML 内的 base64 字符串（transform_blob_save_string/transform_save_string_blob用g_base64_encode/g_base64_decode实现），复制时同样是复制引用计数指针。

3.3 VipsArrayInt / VipsArrayDouble：数值数组参数

libvips 大量操作的参数是"一个数组"，例如vips_linear的 a/b 向量。两个类型的 API 完全对称（type.c）：

• vips_array_int_new(array, n)/vips_array_double_new(array, n)：拷贝入数组，transfer full。
• vips_array_int_newv(n, ...)/vips_array_double_newv(n, ...)：变参版本，从参数列表逐个取值填入。
• vips_array_int_get(array, &n)/vips_array_double_get(array, &n)：取回指针与元素个数，内部g_assert(area->type == G_TYPE_INT/G_TYPE_DOUBLE)校验元素类型，然后通过VIPS_ARRAY_ADDR(array, 0)返回首元素地址。
• 它们注册了大量 GValue 变换：与G_TYPE_STRING双向（字符串用\t;,作分隔符、经vips_break_token分词解析）、与VIPS_TYPE_SAVE_STRING双向、与G_TYPE_INT/G_TYPE_DOUBLE单项（把标量扩成单元素数组）、VIPS_TYPE_ARRAY_INT与VIPS_TYPE_ARRAY_DOUBLE互相转换。这也是为什么 CLI 与 Python 绑定里能用"1 2 3"这样的字符串直接给数组参数赋值。

3.4 VipsArrayImage：图像数组

用于把多个图像一次性传给操作（如拼接类算子），是VipsArea+ 对象数组的组合（type.c，声明在 image.h）：

• vips_array_image_new(VipsImage **array, int n)/vips_array_image_newv(int n, ...)：对每个元素执行g_object_ref，数组释放时自动 unref（"The images will all be reffed by this function. They will be automatically unreffed for you by Area.unref"），同样追加NULL结尾元素。
• vips_array_image_new_from_string(string, access)：按空白/换行分隔的文件名列表逐个vips_image_new_from_file加载，任一失败则整体回滚（unref 已建数组并返回 NULL）。
• vips_array_image_empty()与vips_array_image_append(array, image)：为不方便传对象数组的语言绑定提供"空数组 + 逐次追加"的替代路径。
• vips_array_image_get(array, &n)：取回VipsImage **与个数，同样有g_assert(area->type == VIPS_TYPE_IMAGE)校验。

3.5 VipsSaveString：写入文件头的字符串

VipsSaveString是为"把元数据字段保存到 VIPS 文件 XML 头"而设计的新字符串类型（type.c）。它本身只是{ char *s; }的 boxed 类型（copy 用g_strdup，free 用g_free），关键在于注册了与G_TYPE_INT、G_TYPE_DOUBLE、G_TYPE_FLOAT之间的双向变换：整数/浮点字段在保存到文件头时先转成字符串（double/float 用g_ascii_dtostr保证与 locale 无关），读回时再解析还原。这就是 VIPS 文件头能以文本形式持久化数值元数据的底层机制。

四、基础别名与回调类型

VipsPel（"picture element"，像素元素）被定义为unsigned char，源码注释提醒："Cast this to whatever the associatedVipsBandFormatsays to get the value"（basic.h）。它遍布图像像素与VIPS_ARRAY_ADDR的指针运算中——例如VIPS_ARRAY_ADDR宏就是用(VipsPel *) data + sizeof_type * i计算第 i 个元素的地址（type.h）。

四个回调类型都定义在 basic.h：

此外basic.h还定义了VipsPrecision枚举（INTEGER/FLOAT/APPROXIMATE）以及VIPS_API（_VIPS_PUBLIC extern）导出宏。

五、GValue 辅助函数：在绑定与元数据之间搬运数据

value_*系列函数（约 20 个）是 Basic 一节中数量最大的一类，作用是让这些容器类型可以放入 GLib 的GValue，从而进入 libvips 的 GObject 属性系统、操作参数系统与图像元数据存储。它们两两成对，约定如下：

• Area 类：vips_value_set_area(value, free_fn, data)建 area 并装箱（内部vips_area_new→g_value_set_boxed→ 立即vips_area_unref移交引用，type.c）；vips_value_get_area(value, &length)取回指针与长度。
• 字符串类：vips_value_set_save_string/vips_value_get_save_string/vips_value_set_save_stringf（printf 格式化写入，带G_GNUC_PRINTF(2, 3)检查）处理SAVE_STRING；vips_value_set_ref_string/vips_value_get_ref_string处理REF_STRING。两个 set 函数都会校验 UTF-8，非法时分别替换为占位符或经g_utf8_make_valid修正。
• Blob 类：vips_value_set_blob(value, free_fn, data, length)（自定义释放）与vips_value_set_blob_free(value, data, length)（直接用vips_area_free_cb，即g_free，绑定调用更省事）对称于vips_value_get_blob(value, &length)。
• 数组类：vips_value_set_array/vips_value_get_array是通用底座（需显式给出n、GType、sizeof_type，且"allocates memory but does not initialise the contents: get the pointer and write instead"）；其上是带类型的具体封装——array_int、array_double、array_image、array_object四对 set/get。其中vips_value_set_array_int/vips_value_set_array_double在数组指针非 NULL 时会用memcpy拷贝数据，vips_value_set_array_image与vips_value_set_array_object则只建空槽，元素需调用方逐个填VipsImage */GObject *。

这些函数构成了语言绑定的关键通道：例如 Python 里Vips.Image.linear(a, b)的a/b最终就是通过vips_value_set_array_double进入 GValue 的。

六、函数宏：弃用标记与带越界检查的数组寻址

• VIPS_DEPRECATED_FOR(f)与VIPS_DEPRECATED_MACRO_FOR(f)：弃用声明宏（basic.h）。若编译前定义VIPS_DISABLE_DEPRECATION_WARNINGS（必须在包含vips/vips.h之前定义），两者退化为纯VIPS_API；否则展开为 GLib 的G_DEPRECATED_FOR(f)/ 编译器#pragma GCC warning，提示调用方用f替换被弃用符号。
• VIPS_ARRAY_ADDR(X, I)（type.h）：按sizeof_type步长计算第I个元素地址。在VIPS_DEBUG下会先检查0 <= I < n，越界则向stderr打印含文件名、行号、越界值的诊断信息并返回 NULL——这正是vips_array_int_get/vips_array_double_get/vips_array_image_get内部取首元素地址所用的宏。

七、实战：基础类型在真实操作中的位置

这些类型并非纸上谈兵，它们在算子实现中被高频使用。仅举几例：

• 数值数组参数：vips_linear在 libvips/arithmetic/linear.c 中用VIPS_ARRAY(linear, n, double)分配 a/b 系数数组，并在 L453-L484 把操作参数声明为VIPS_TYPE_ARRAY_DOUBLE、用vips_array_double_new构造，随后通过VIPS_AREA()宏访问——VipsArrayDouble是"每波段一个系数"这类向量参数的官方载体。
• 像素值参数：vips_insert的背景色与vips_flood的 ink 色都经VIPS_ARRAY_ADDR取出后交给底层处理（见 libvips/conversion/insert.c、libvips/draw/draw_flood.c）。
• 图像数组参数：vips_array_image_new_array_object生成的VipsArrayImage是拼接/合并类操作接收多张输入的标准途径，NULL结尾元素专为vips_image_pipeline_array等内部管道函数预留。
• 元数据存储：VipsRefString与VipsBlob配合vips_value_set_ref_string/vips_value_set_blob构成图像元数据（如 ICC profile、EXIF、描述字符串）的存取通道；字符串走 UTF-8 校验的 refstring，二进制走带 base64 序列化的 blob。

八、总结

Basic 一节虽然不包含任何图像处理算法，却是 libvips 中最"底层"的公共基础设施：VipsArea以引用计数 + 自定义释放函数统一了内存所有权，VipsBlob/VipsRefString/VipsArrayInt/VipsArrayDouble/VipsArrayImage/VipsSaveString在其上分别解决了二进制块、不可变字符串、数值数组、图像数组与文件头字符串的存储与传递，value_*系列函数则把这一切接入 GLibGValue体系。理解它们的内存契约（初始引用计数为 1、挂载后须 unref、"transfer full/none" 语义、NULL结尾元素约定），是在 C 层开发 libvips 操作、编写语言绑定或调试元数据问题时不可或缺的基础。

• 图像处理