SumatraPDF 内置 MuPDF 的 I/O 层完全指南:fz_buffer、fz_stream、过滤器与档案系统的原理与实战
SumatraPDF 内置 MuPDF 的 I/O 层完全指南:fz_buffer、fz_stream、过滤器与档案系统的原理与实战
导读
本文深入讲解当前仓库 ext/mupdf 子模块中 MuPDF 的 Fitz I/O 层——即 ext/mupdf/docs/reference/c/fitz/io.md 所描述的 Buffers & Streams 体系。这套 API 是 SumatraPDF 读取、解析与渲染 PDF、EPUB、CBZ、CHM 等文档的底层数据管道:fz_buffer 负责内存数据的持有与构建,fz_stream 负责从文件、内存等来源读取字节流,各类 filter 过滤器对数据流进行压缩/加密/编码解码,输出流与 Zip 档案系统则支撑文档导出与打包。读完本文,你将掌握 MuPDF I/O 层的完整 API 地图、过滤链的搭建方法,以及缓冲区所有权、引用计数等关键实践细节。
概述:为什么 PDF 引擎需要一套独立的 I/O 层
PDF 文件内部的数据组织极其复杂:正文对象可能被 Flate 压缩、ASCII Hex 编码,图像可能使用 DCT(JPEG)、LZW、CCITT Fax 等十余种算法压缩,页面内容还可能被加密。MuPDF(Fitz)的设计哲学是:所有数据源都抽象为可随机访问的字节流(stream),所有解码/解压/解密能力都抽象为可任意串联的过滤器(filter),内存中的临时数据统一用 buffer 表示。这样 PDF 解析器只需描述"底层流 -> 过滤器链 -> 最终字节"的管道,而不必关心数据到底来自磁盘文件还是内存。
在 SumatraPDF 中,这套 API 被直接用于文档加载、指纹计算与导出。例如 src/EngineMupdf.cpp 中:
- FzStreamFingerprint 用
fz_seek/fz_tell/fz_read_all把整个文件读入 buffer,再交给 MD5 计算文件指纹; - FzExtractStreamData 通过
fz_read_all提取流内容; - src/EngineMupdf.cpp 用
fz_open_directory把目录当作档案打开(用于 CBZ/EPUB 等基于目录的场景); - src/EngineMupdf.cpp 用
fz_new_output_with_buffer把输出写到内存 buffer 中(用于导出/保存场景)。
因此,理解本文的 API 就是理解 SumatraPDF 数据链路的地基。以下所有原型均来自头文件 include/mupdf/fitz/buffer.h、include/mupdf/fitz/stream.h、include/mupdf/fitz/output.h、include/mupdf/fitz/filter.h 与 include/mupdf/fitz/archive.h。
fz_buffer:通用的内存字节容器
fz_buffer 是 MuPDF 表示"任意一块数据"的核心结构,官方文档称之为"generic chunks of data"。它本质上是对一块动态分配内存的包装:
typedef struct {
int refs; // 引用计数
unsigned char *data; // 数据指针
size_t cap, len; // cap=容量,len=当前长度
int unused_bits; // 位写入时最后字节中未使用的位数
int shared; // 是否共享外部数据(不可修改)
} fz_buffer;
注意:头文件明确注明该结构的内部字段属于实现细节、可能变更,使用者应优先通过访问函数操作 buffer,不要直接读写
data/len。
fz_buffer 是引用计数对象,必须成对使用 keep/drop 管理生命周期:
fz_buffer *fz_keep_buffer(fz_context *ctx, fz_buffer *buf);
void fz_drop_buffer(fz_context *ctx, fz_buffer *buf);
fz_keep_buffer 永不抛异常并返回同一指针;fz_drop_buffer 在引用计数归零时销毁 buffer。这是 MuPDF 全局的内存管理约定,后文所有对象(stream、output、archive)都遵循同一模式。
创建缓冲区的四种方式
| 创建函数 | 数据所有权 | 典型场景 |
|---|---|---|
fz_new_buffer(ctx, capacity) |
空缓冲区,自带初始容量 | 预分配后逐步 append |
fz_new_buffer_from_shared_data(ctx, data, size) |
不持有,只引用外部指针 | 包装只读的静态数据,零拷贝 |
fz_new_buffer_from_copied_data(ctx, data, size) |
持有(内部复制一份) | 外部数据生命周期不可控时 |
fz_new_buffer_from_base64(ctx, data, size) |
持有(BASE64 解码结果) | 解析内嵌 BASE64 数据 |
fz_new_buffer_from_shared_data 是最"零成本"的创建方式,但使用条件极其严格:底层数据指针在 buffer 存活期间不得改变或消失,且因为是共享数据,对它的写操作(append、resize)可能导致错误行为。如果外部数据只是临时存在,应改用 fz_new_buffer_from_copied_data。
逐步构建数据:append 系列
很多场景下数据是逐块拼出来的(比如组装 PDF 对象、拼接文本),此时使用 append 系列函数,buffer 会自动扩容:
void fz_append_data(fz_context *ctx, fz_buffer *buf, const void *data, size_t len);
void fz_append_string(fz_context *ctx, fz_buffer *buf, const char *string);
void fz_append_byte(fz_context *ctx, fz_buffer *buf, int byte);
void fz_append_rune(fz_context *ctx, fz_buffer *buf, int rune); // UTF-8 编码写入一个码点
void fz_append_int16_be(fz_context *ctx, fz_buffer *buf, int x);
void fz_append_int16_le(fz_context *ctx, fz_buffer *buf, int x);
void fz_append_int32_be(fz_context *ctx, fz_buffer *buf, int x);
void fz_append_int32_le(fz_context *ctx, fz_buffer *buf, int x);
void fz_append_printf(fz_context *ctx, fz_buffer *buffer, const char *fmt, ...);
void fz_append_vprintf(fz_context *ctx, fz_buffer *buffer, const char *fmt, va_list args);
数值 append 函数同时提供大端(_be)与小端(_le)两种字节序,方便直接按目标文件格式写入。fz_append_printf 使用 MuPDF 自定义的格式化器(见下文输出流一节)。
位级写入
当需要按位构建数据(例如编码压缩流头部)时,buffer 支持位写入,其内部用 unused_bits 字段跟踪最后字节中已用/未用的位数:
void fz_append_bits(fz_context *ctx, fz_buffer *buf, int value, int count);
void fz_append_bits_pad(fz_context *ctx, fz_buffer *buf);
fz_append_bits:把value的低count位写入缓冲区;fz_append_bits_pad:写入足够的零位使数据对齐到字节边界。
官方文档特别说明:缓冲区长度始终覆盖其中的所有位,包括最后一个字节里未被使用的位(这些位恒为零)。对应实现位于 source/fitz/buffer.c(fz_append_bits 定义于约 L464,fz_append_bits_pad 于约 L526)。
将 buffer 当作 C 字符串使用
const char *fz_string_from_buffer(fz_context *ctx, fz_buffer *buf);
该函数保证在数据末尾补一个 \0 并返回首字节指针。返回的指针是借用的:buffer 一旦再次被修改(可能 realloc 或释放内部存储),该指针即失效,因此只能短期使用。此外 fz_terminate_buffer 也可以显式补零(该零字节不计入 fz_buffer_storage 返回的长度),而 fz_trim_buffer/fz_grow_buffer/fz_resize_buffer 等容量调整操作都可能使此前取得的字符串指针失效。
与文件互转
fz_buffer *fz_read_file(fz_context *ctx, const char *filename);
void fz_save_buffer(fz_context *ctx, fz_buffer *buf, const char *filename);
fz_read_file 把整个文件读入 buffer;fz_save_buffer 把 buffer 内容写入文件。这是最便捷的"读入内存 -> 处理 -> 写回磁盘"组合。
其他常用操作(源自 buffer.h)
fz_buffer_storage(ctx, buf, &datap):取出内部数据指针与当前长度;fz_buffer_extract(ctx, buf, &data):转移所有权,调用后数据归调用方(需用fz_free释放),buffer 被清空;FzStreamFingerprint 正是先fz_buffer_extract再对数据做 MD5,最后fz_free;fz_clone_buffer/fz_slice_buffer:复制 / 按起止区间切片;fz_clear_buffer:清空内容但保留已分配存储以便复用;fz_append_buffer:把另一个 buffer 的内容追加到当前 buffer;fz_md5_buffer:直接对 buffer 内容计算 MD5 摘要;fz_append_base64/fz_append_base64_buffer:以 BASE64 编码追加数据,newline参数控制是否周期性换行;fz_append_pdf_string:按 PDF 语法加引号与转义后追加字符串(写 PDF 时常用)。
fz_stream:可随机访问的字节输入流
fz_stream 是"可双向 seek 的缓冲读取器"抽象,同样使用引用计数(fz_keep_stream / fz_drop_stream)。结构体内部维护了读指针 rp/写指针 wp、当前位缓冲 bits/avail、EOF 标志、当前位置 pos 以及三个函数指针 next/seek/drop——这决定了任何自定义数据源都可以通过实现这三个回调接入 MuPDF。
三种打开方式
fz_stream *fz_open_file(fz_context *ctx, const char *filename);
fz_stream *fz_open_memory(fz_context *ctx, const unsigned char *data, size_t len);
fz_stream *fz_open_buffer(fz_context *ctx, fz_buffer *buf);
fz_open_file:从文件读取。非 Windows 平台文件名按fopen(2)语义;Windows 平台要求 UTF-8 编码以支持非 ASCII 路径(另有仅 Windows 可用的宽字符版本fz_open_file_w)。fz_open_memory:从内存指针读取,不转移数据所有权,数据须在流存活期间有效。fz_open_buffer:从 buffer 读取,内部自行持有 buffer 引用。
另有两个实用变体:fz_open_file_autodelete(关闭时删除文件)与 fz_try_open_file(打不开时返回 NULL 而非抛异常)。
基本读写操作
int64_t fz_tell(fz_context *ctx, fz_stream *stm); // 当前位置
void fz_seek(fz_context *ctx, fz_stream *stm, int64_t offset, int whence); // whence: SEEK_SET/SEEK_CUR/SEEK_END
size_t fz_read(fz_context *ctx, fz_stream *stm, unsigned char *data, size_t len);
size_t fz_skip(fz_context *ctx, fz_stream *stm, size_t len);
fz_buffer *fz_read_all(fz_context *ctx, fz_stream *stm, size_t initial); // 把剩余数据读成 buffer
char *fz_read_line(fz_context *ctx, fz_stream *stm, char *buf, size_t n); // 类似 fgets()
int fz_read_byte(fz_context *ctx, fz_stream *stm); // 返回 -1 表示 EOF
int fz_peek_byte(fz_context *ctx, fz_stream *stm); // 预读一个字节但不消费
int fz_is_eof(fz_context *ctx, fz_stream *stm);
fz_seek/fz_tell 是流式读取的基础:SumatraPDF 的 FzStreamFingerprint 就通过 fz_seek(stm, 0, 2) 跳到文件尾、fz_tell 得到总长、再 fz_seek(stm, 0, 0) 回到开头,随后 fz_read_all(stm, fileLen) 整读。fz_read_all 的 initial 参数是建议的初始 buffer 大小(已知文件大小时传入可避免重复扩容)。
整数与二进制读取
流可以按整数为单位读取二进制数据,默认大端(big endian),同时提供小端版本:
uint16_t fz_read_uint16(ctx, stm); uint16_t fz_read_uint16_le(ctx, stm);
uint32_t fz_read_uint24(ctx, stm); uint32_t fz_read_uint24_le(ctx, stm);
uint32_t fz_read_uint32(ctx, stm); uint32_t fz_read_uint32_le(ctx, stm);
uint64_t fz_read_uint64(ctx, stm); uint64_t fz_read_uint64_le(ctx, stm);
int16_t fz_read_int16(ctx, stm); int16_t fz_read_int16_le(ctx, stm);
int32_t fz_read_int32(ctx, stm); int32_t fz_read_int32_le(ctx, stm);
int64_t fz_read_int64(ctx, stm); int64_t fz_read_int64_le(ctx, stm);
读到 EOF 会抛异常(见 stream.h 注释)。另有用 fz_read_string(读定长并以 \0 结尾的字符串)、fz_read_rune(读 UTF-8 码点)、fz_read_utf16_le/be(读 UTF-16 码点)、fz_read_float_le/float 以及 fz_skip_string/fz_skip_space 等辅助函数。
位流读取
unsigned int fz_read_bits(fz_context *ctx, fz_stream *stm, int n); // 高位优先(MSB first)
unsigned int fz_read_rbits(fz_context *ctx, fz_stream *stm, int n); // 低位优先(LSB first)
void fz_sync_bits(fz_context *ctx, fz_stream *stm); // 回到字节边界
int fz_is_eof_bits(fz_context *ctx, fz_stream *stm); // 位读取模式下的 EOF 判断
位读取由 stream 内部的 bits/avail 字段支撑,n 取值范围为 1 到 8*sizeof(int)。fz_read_bits 与 fz_read_rbits 的区别在于位打包顺序(MSB-first vs LSB-first),对应不同格式规范;fz_sync_bits 在读完位后必须调用以丢弃残留的位缓冲、恢复字节对齐。
从流读取并复用:leecher
fz_open_leecher(ctx, chain, buf) 是一个很有用的工具:它包装一条链,把所有读过的数据同时追加到指定 buffer 中("窃听"数据流)。这在需要"边解析边保留原始数据"的场景(如解密后的 PDF 对象既要被解析又要被保存)非常方便。
Filters:可串联的解码/解压/解密过滤链
Filter 是 MuPDF I/O 层最具威力的部分:fz_stream 之间可以无限串联,形成处理管道。原始数据经第一层流读出,被过滤器逐个变换,最终到达解析器。
基础过滤器
fz_stream *fz_open_null_filter(ctx, chain, len, offset); // 从 chain 中读取指定范围
fz_stream *fz_open_arc4(ctx, chain, key, keylen); // RC4 解密
fz_stream *fz_open_aesd(ctx, chain, key, keylen); // AES 解密
fz_stream *fz_open_a85d(ctx, chain); // ASCII85 解码
fz_stream *fz_open_ahxd(ctx, chain); // ASCII Hex 解码
fz_stream *fz_open_rld(ctx, chain); // Run Length 解码
fz_stream *fz_open_flated(ctx, chain, window_bits); // zlib/Deflate 解压(inflate)
fz_open_null_filter 读取 chain 中从 offset 起共 len 字节的数据(用于限定子流范围);fz_open_flated 的 window_bits 通常为 15,传负数 -n 表示按 n 位窗口解压且数据无 zlib 头(raw deflate)。
PDF 专用图像过滤器
| 过滤器 | 对应 PDF 滤镜 | 关键参数 |
|---|---|---|
fz_open_dctd |
DCTDecode(JPEG) | color_transform(-1 默认 / 0 关闭 / 1 开启 YUV-RGB、YCCK-CMYK 转换)、invert_cmyk(1 用于非 PDF 内嵌的 Photoshop CMYK)、l2factor(解码降采样的 log2,0 为全尺寸)、jpegtables(可选 JPEG 表流,可为 NULL) |
fz_open_faxd |
CCITTFaxDecode | k(默认 0)、end_of_line(默认 0)、encoded_byte_align(默认 0)、columns(默认 1728)、rows(0 表示未知)、end_of_block(默认 1)、black_is_1(极性,默认 0) |
fz_open_lzwd |
LZWDecode | early_change(默认 1)、min_bits(默认 9)、reverse_bits(默认 0,兼容 GIF/老式 TIFF 时置 1)、old_tiff(默认 0,老式 TIFF 清码处理) |
fz_open_predict |
Predictor(PNG/TIFF 预测器) | predictor(1=复制、2=TIFF、其他=内联 PNG 预测器)、columns(像素宽度)、colors(分量数)、bpc(每分量位数,通常 8) |
这些过滤器在 include/mupdf/fitz/filter.h 中有详细参数注释(含各自默认值),对应的实现分散在 source/fitz/filter-dct.c、source/fitz/filter-fax.c、source/fitz/filter-lzw.c、source/fitz/filter-flate.c、source/fitz/filter-predict.c 等文件中。
扩展过滤器
头文件中还提供了一批其他解码器,按需选用:
fz_open_jbig2d(ctx, chain, globals, embedded):JBIG2 解压,globals由fz_load_jbig2_globals从 buffer 创建;fz_open_brotlid(ctx, chain):Brotli 解压;fz_open_libarchived(ctx, chain):libarchive 通用解压(未编译 libarchive 时会抛异常);fz_open_range_filter(ctx, chain, ranges, nranges):按多个范围拼接读取;fz_open_endstream_filter(ctx, chain, len, offset):PDF 子流读取,并在指定长度后寻找endstream标记;fz_open_concat(ctx, max, pad):把多条流拼接成一条(配合fz_concat_push_drop逐条压入);fz_open_sgilog16/24/32、fz_open_thunder:TIFF 的 SGI LogLuv 与 Thunderscan 特殊解码。
链式调用示例
fz_stream *stm = fz_open_file(ctx, "compressed.bin");
stm = fz_open_ahxd(ctx, stm); // 先做 ASCII Hex 解码
stm = fz_open_flated(ctx, stm, 15); // 再 inflate
// 现在从 stm 读到的是解压后的原始字节
fz_buffer *data = fz_read_all(ctx, stm, 0);
fz_drop_stream(ctx, stm);
这正是 PDF 中 [ASCIIHexDecode FlateDecode] 过滤器数组的解析方式:过滤器数组按从内到外的顺序逐层包装,最终读出的即是原始内容流。
Output Streams:输出流与数据写出
fz_output 把数据写到某个"汇"(sink),通常是磁盘文件或内存 buffer,同样可以串联过滤器实现压缩、加密、编码。
close 与 drop 的语义(重点)
void fz_close_output(fz_context *ctx, fz_output *out);
void fz_drop_output(fz_context *ctx, fz_output *out);
由于写出的数据可能被缓冲在 writer 内部,必须区分"关闭"与"释放":
fz_close_output:冲刷缓冲并写入结束标记(如压缩流的尾部标记),写操作成功结束后必须调用;fz_drop_output:仅释放内存,不冲刷。
若写入过程发生错误,直接 fz_drop_output 即可——反正数据没写完,正常的 close 已无意义。drop 之前必须先 close(成功写入的场景)。
创建输出流
fz_output *fz_new_output_with_path(ctx, filename, append); // 写文件;append 非 0 表示追加
fz_output *fz_new_output_with_buffer(ctx, fz_buffer *buf); // 追加写入 buffer
fz_output *fz_new_output(ctx, buffer_size, state,
void (*write)(ctx, state, data, n),
void (*close)(ctx, state),
void (*drop)(ctx, state)); // 自定义数据汇
fz_new_output 允许通过回调实现任意自定义 sink:write 负责写入、close 负责冲刷收尾(可为 NULL)、drop 负责释放 state。输出对象内部带缓冲(bp/wp/ep 指针),buffer_size 即缓冲大小。
另外还有面向标准输出的 fz_stdout(ctx)、fz_stderr(ctx),以及 Windows 下的 fz_stdods(ctx)(OutputDebugString)。
写出操作
void fz_seek_output(ctx, out, off, whence); // 定位(并非所有输出类型支持)
int64_t fz_tell_output(ctx, out); // 当前写位置
void fz_write_data(ctx, out, data, size);
void fz_write_string(ctx, out, s); // 不写结尾 \0
void fz_write_byte(ctx, out, x);
void fz_write_rune(ctx, out, rune); // UTF-8 写出一个码点
void fz_write_int16_be/le(ctx, out, x);
void fz_write_int32_be/le(ctx, out, x);
void fz_write_printf(ctx, out, fmt, ...); // 自定义格式化
void fz_write_vprintf(ctx, out, fmt, ap);
void fz_write_base64(ctx, out, data, size, newline); // newline 控制是否周期性换行
MuPDF 自定义的 printf 格式化器(fz_format_string/fz_vsnprintf/fz_snprintf/fz_asprintf,见 output.h)支持 %c %d %s %u %x %X、零填充(%02d)、千位分隔符(%'d/%,d/%_d)、%g 最短无损表示、%C(UTF-8 码点)、%M/%R/%P(矩阵/矩形/点)、%q/%((C/PDF 转义字符串)、%l{d,u,x,X}(int64)、%z{d,u,x,X}(size_t)等扩展格式。
输出端过滤器链
fz_output *fz_new_arc4_output(ctx, chain, key, keylen); // RC4 加密
fz_output *fz_new_ascii85_output(ctx, chain); // ASCII85 编码
fz_output *fz_new_asciihex_output(ctx, chain); // ASCII Hex 编码
fz_output *fz_new_deflate_output(ctx, chain, effort, no_header); // Deflate 压缩
fz_output *fz_new_rle_output(ctx, chain); // Run Length 编码
重要约定:这些过滤器不接管(take ownership)chain,所有权仍归调用方,调用方必须保证 chain 存活到返回的 fz_output 被 drop 为止。官方文档给出了一个非常实用的串联写法:先写文件头 -> 创建压缩过滤流 -> 向过滤流写数据(数据被压缩)-> 关闭过滤流 -> 继续向原始流写后续数据。典型的多层组合是"ASCII Hex 编码 + Deflate 压缩 + RC4 加密"写到 buffer 输出。
输出端同样支持位级写入:fz_write_bits(ctx, out, data, num_bits) 与 fz_write_bits_sync(ctx, out)(写位后对齐字节)。fz_flush_output 可手动冲刷未写数据;fz_write_stream(ctx, out, in) 直接把一条输入流的内容复制到输出。
File Archives:档案(归档)抽象
fz_archive 把"包含多个文件的集合"统一抽象为只读档案,典型实现包括 Zip 文件、磁盘目录、tar 文件,以及通过 libarchive 支持的其他格式。
打开档案
int fz_is_directory(fz_context *ctx, const char *path);
fz_archive *fz_open_directory(ctx, path); // 把目录当作档案
fz_archive *fz_open_archive(ctx, filename); // 按签名自动识别 zip/tar 等
fz_archive *fz_open_archive_with_stream(ctx, file); // 用流打开
fz_open_directory把磁盘目录当档案读(SumatraPDF 在 src/EngineMupdf.cpp 即以此打开目录型文档源);fz_open_archive依据档案头签名自动判断类型;- 另有
fz_try_open_archive_with_stream(无法识别时返回 NULL 而非抛错)、fz_open_zip_archive/fz_open_tar_archive/fz_open_libarchive_archive/fz_open_cfb_archive等按格式明确打开的函数,以及对应的_with_stream变体。
档案操作
void fz_drop_archive(ctx, arch); // 释放(引用计数)
int fz_count_archive_entries(ctx, arch); // 条目总数
const char *fz_list_archive_entry(ctx, arch, idx); // 取第 idx 个条目名
int fz_has_archive_entry(ctx, arch, name); // 是否存在该条目(精确匹配)
fz_stream *fz_open_archive_entry(ctx, arch, name); // 以流打开条目
fz_buffer *fz_read_archive_entry(ctx, arch, name); // 整读条目为 buffer
注意:目录型档案无法计数和枚举(fz_count_archive_entries/fz_list_archive_entry 可能抛异常),但支持 fz_has_archive_entry 精确判断。条目名必须精确匹配。另提供不抛异常的 fz_try_open_archive_entry 与 fz_try_read_archive_entry(找不到时返回 NULL)。fz_archive_format 可查询档案格式字符串;fz_keep_archive 增加引用。
fz_archive 结构体内是一组函数指针(count_entries/list_entry/has_entry/read_entry/open_entry),因此新档案格式可以通过实现这些回调接入,这正是其可扩展性的来源。头文件还提供了 fz_new_tree_archive(内存中的命名 buffer 集合,配合 fz_tree_archive_add_buffer/fz_tree_archive_add_data)与 fz_new_multi_archive + fz_mount_multi_archive(把多个档案按路径前缀挂载合并成一个逻辑档案)等高级能力。
创建 Zip 档案
typedef struct { internal } fz_zip_writer;
fz_zip_writer *fz_new_zip_writer(ctx, filename); // 写入文件
fz_zip_writer *fz_new_zip_writer_with_output(ctx, out); // 写入输出流(接管所有权!)
void fz_write_zip_entry(ctx, zip, name, buf, compress); // 写入一个条目,compress 控制是否压缩
void fz_close_zip_writer(ctx, zip); // 关闭并冲刷(可能抛异常)
void fz_drop_zip_writer(ctx, zip); // 释放(永不抛异常)
fz_new_zip_writer_with_output 一旦调用,out 的所有权立即转移给 zip writer,调用方此后不得再 drop 该输出,即使函数抛异常也一样。这与输入端过滤器"不接管 chain"的约定形成鲜明对比,使用时务必区分。
实战小结:内存与资源管理要点
基于上述 API 与 MuPDF 的约定,在实际使用(包括在 SumatraPDF 中扩展引擎)时需要注意:
- 引用计数成对出现:buffer/stream/archive 都有 keep/drop 对。
fz_keep_*返回同一指针且不抛异常,fz_drop_*归零即销毁。 - close 先于 drop(输出流):写操作成功结束后先
fz_close_output再fz_drop_output;写失败直接 drop。 - 所有权要看清:
fz_new_buffer_from_shared_data不持有外部数据,外部指针必须存活于 buffer 生命周期内;fz_new_buffer_from_copied_data持有副本;fz_buffer_extract转移数据所有权(之后用fz_free释放);- 输出端过滤链不接管 chain,调用方维护其生命周期;
fz_new_zip_writer_with_output接管 out 所有权。
- 异常语义:多数创建/读取函数失败时抛异常(用
fz_try/fz_catch捕获,如 src/EngineMupdf.cpp 的做法),而非返回 NULL;fz_try_*系列则返回 NULL。drop 系列永不抛异常。 - 位流读取后必须
fz_sync_bits:避免残留位缓冲干扰后续字节读取;写位后使用fz_write_bits_sync对齐。 - Windows 文件路径用 UTF-8:
fz_open_file/fz_new_output_with_path等接口在 Windows 上以 UTF-8 编码路径传递,以支持非 ASCII 文件名。
延伸阅读
- 本文主题官方文档:ext/mupdf/docs/reference/c/fitz/io.md
- 核心头文件:include/mupdf/fitz/buffer.h、include/mupdf/fitz/stream.h、include/mupdf/fitz/output.h、include/mupdf/fitz/filter.h、include/mupdf/fitz/archive.h
- 实现源码:source/fitz/buffer.c、source/fitz/filter-flate.c、source/fitz/filter-dct.c、source/fitz/filter-fax.c、source/fitz/filter-lzw.c、source/fitz/filter-predict.c、source/fitz/archive.c
- SumatraPDF 中的实际使用:src/EngineMupdf.cpp(
fz_read_all、fz_seek/fz_tell指纹计算于 L840-L867,fz_open_directory于 L4488,fz_new_output_with_buffer于 L10184) - MuPDF C API 总览:ext/mupdf/docs/reference/c/fitz/api-overview.md