mupdf-gl 完全指南：MuPDF 的 FreeGLUT 图形化文档查看器

• 图形学
• 图像处理

mupdf-gl 是 MuPDF 仓库中基于 OpenGL + FreeGLUT 的跨平台 GUI 查看器，可显示 PDF、XPS、CBZ、EPUB/FB2 文档以及 SVG 等常见图片格式。本篇以官方文档 docs/tools/mupdf-gl.md 为主体，逐条覆盖其命令行选项、操作示例、鼠标与键盘绑定，并结合 platform/gl/gl-main.c 等源码补充默认值、启动流程、历史记录机制等文档未展开的实现细节，帮助读者从“会用”深入到“知其所以然”。

一、mupdf-gl 在项目中的定位

从 Makefile 可以看到，mupdf-gl是条件构建目标：只有当HAVE_GLUT=yes时才会编译platform/gl/*.c下的所有源文件（gl-main.c、gl-app.h、gl-input.c、gl-ui.c 等），链接libmupdf、第三方库与libmupdf-glut静态库。若系统已有 FreeGLUT，可设USE_SYSTEM_GLUT=yes，否则使用仓库自带的 thirdparty/freeglut；Windows 下则通过 platform/win32/mupdf-gl.vcxproj 构建，入口为WinMain。

它与同为查看器的mupdf-x11（仅 Linux X11）不同，mupdf-gl 依赖 OpenGL 管线渲染页面位图，是 Windows、macOS（通过 glut 回调）和 Linux 上的通用图形界面。

二、命令行选项全表

官方文档给出的调用形式为：

mupdf-gl [options] document [page]

其中page是初始页码（源码中解析为anchor，见 gl-main.c）。下表完整继承文档所列选项，并用源码核对出的默认值补充了“默认值/实现”一栏：

文档未列出、但源码实际支持的选项

main()中的 getopt 字符串为"p:r:IW:H:S:U:XJb:A:B:C:T:Y:R:c:vf"（gl-main.c），usage()帮助文本还列出了以下文档未记载的选项，实际使用时同样有效：

• -b box：使用指定页面 box 渲染，可取 MediaBox、CropBox、BleedBox、TrimBox、ArtBox（fz_box_type_from_string）；
• -R options：启用 reflow 模式（阅读模式），并设置文本抽取选项，示例mupdf-gl -R dehyphenate,preserve-images book.epub；
• -T tracefile：将交互操作记录为 JavaScript 风格的跟踪脚本（源码中trace_action输出如page.update()、doc.loadPage(n)等语句，可配合mutool run复现）；
• -f：以全屏模式启动；
• -v：输出版本号后退出；
• --external-access：允许文档访问其所在目录中的外部资源（用于本地资源引用的 EPUB 等）。

三、常用示例

文档给出的两个基础用法：

# 不带参数启动：弹出文件浏览器窗口 mupdf-gl # 以反色模式打开指定文件的第 10 页 mupdf-gl -I mupdf_explored.pdf 10

结合上表的补充示例（均可直接复制运行）：

# 使用广色域 ICC 配置、150 DPI 缩放打开 PDF mupdf-gl -c display-p3.icc -r 150 report.pdf # 打开 EPUB：宽 900pt、字号 20pt，并应用用户样式 mupdf-gl -W 900 -S 20 -U user.css -X book.epub # 色调模式（米色纸张感）：黑 303030、白 FFFFF0，再叠加反色 mupdf-gl -C FFFFF0 -I scan.pdf

启动时的缩放细节值得一知：main()在加载文档后会检查页面纹理尺寸是否超出可用屏幕（GLUT_SCREEN_WIDTH/HEIGHT减去边框预留SCREEN_FURNITURE_W/H），若超出则按比例缩小currentzoom，保证初始窗口不被页面撑破（gl-main.c）。

四、鼠标绑定

文档明确两个鼠标行为：

• 中键（滚轮按钮）：平移（pan）文档视图；
• 右键：框选区域并将所选文本复制到剪贴板。

这一行为与源码中的help_dialog_text帮助文本完全一致（gl-main.c）。

五、键盘绑定

文档说明多个快捷键支持“数字参数前缀”，例如输入150z可将缩放设为 150 DPI。数字参数在 gl-input.c 的按键处理中暂存、待命令键触发时生效。完整绑定表如下（前部分来自文档，带 * 的条目补充自源码帮助文本 gl-main.c）：

关于放大/缩小的一个实现细节：+/-并非按固定步长缩放，而是沿着一个预定义的 DPI 序列取上/下一档（gl-main.c）：

static const int zoom_list[] = { 6, 12, 24, 36, 48, 60, 72, 84, 96, 108, 120, 144, 168, 192, 228, 264, 300, 350, 400, 450, 500, 550, 600 };

因此连续按+会以非线性的档位递增，最低 6 DPI、最高 600 DPI。

六、源码纵深：启动流程、搜索与持久化

6.1 启动主流程

从main()的结构看（gl-main.c），mupdf-gl 的启动顺序是：

1. glutInit后按 getopt 解析全部选项；
2. ui_init_dpi(scale)依屏幕 DPI 计算 UI 网格尺寸，随后currentzoom *= ui.scale；
3. fz_register_document_handlers(ctx)注册所有格式 handler（这也是它能同时打开 PDF/XPS/CBZ/EPUB/SVG 的原因）；
4. 若给了-c则读取 ICC 文件构造 colorspace，否则用 DeviceRGB；
5. 带文件名启动时：load_document()→ 若给了-R则reflow_document()（把 EPUB 等转为 reflow 文档）→load_page()；不带文件名时则初始化“打开文档”对话框，由fz_recognize_document过滤可识别文件（gl-main.c）；
6. 进入glutMainLoop()事件循环；退出时在cleanup()中先save_history()、再尝试save_accelerator()（页面缓存文件）。

6.2 文本搜索

/、?、n、N背后的搜索状态集中在 gl-main.c：搜索默认选项为FZ_SEARCH_IGNORE_CASE（忽略大小写），命中的 quad 最多缓存 5000 个（fz_quad search_hit_quads[5000]），并在屏幕上以高亮显示。

6.3 阅读历史与页面缓存

• 阅读位置：m/t/T与[number] m/t操作的history、future、marks数组（各 256/256/10 条）会被序列化为 JSON 持久化到~/.mupdf.history，可被环境变量MUPDF_HISTORY、XDG_CACHE_HOME覆盖（gl-main.c）。下次打开同一文件时自动恢复current位置与书签。
• 页面缓存（accelerator）：fz_save_accelerator将渲染页写入 XDG 缓存目录（如~/.cache/mupdf/，文件名由绝对路径转义而来，见convert_to_accelerator），仅对支持该机制的文档类型生效（fz_document_supports_accelerator），可显著加快二次打开速度。
• 外部链接：点击指向外部 URL 的链接时，只放行file://、http(s)://、mailto:前缀，经确认对话框后调用系统浏览器（Linux 用BROWSER环境变量或xdg-open，macOS 用open，Windows 用ShellExecuteA，见 gl-main.c）。

6.4 修改与保存

S保存与退出/重载时的确认逻辑：若pdf_has_unsaved_changes为真，会弹出含 Save/Discard/Cancel 的对话框（quit_dialog/reload_dialog），避免批注丢失；窗口标题中文件名后加*表示存在未保存修改（update_title）。

七、小结与使用建议

• mupdf-gl 是“一个二进制开遍格式”的通用查看器：命令行选项覆盖加密文档（-p）、色彩管理（-c/-B/-C/-I）、EPUB 版式（-W/-H/-S/-U/-X）与 PDF 表单 JS（-J）；
• 文档未记载但源码确实支持的-R（reflow 阅读模式）、-T（操作跟踪脚本）、-f（全屏）值得在实际部署中利用，尤其是-T生成的 JS 可直接用mutool run做回归验证；
• 阅读历史与页面缓存都落在用户目录，清理~/.mupdf.history与~/.cache/mupdf即可重置状态；
• 所有键盘绑定均可在运行中按F1随时查看，源码帮助文本 gl-main.c 是键位最全的权威清单。

• 图形学
• 图像处理