libpag PAGViewer 桌面预览器完全指南：基于 Qt 6 的 PAG 动画查看与编辑工具

本指南围绕 libpag 仓库中的 viewer/README.md 展开，系统讲解 PAGViewer 的功能定位、环境要求、macOS/Windows 双平台构建流程、命令行用法与源码结构。读完本文，你将掌握如何在 CLion 中从零构建 PAGViewer，理解其渲染、编辑、性能分析与自动更新等核心模块的实现路径，并能直接用它打开 .pag 与 .pagx 文件进行实时预览与调试。

PAGViewer 是什么

PAGViewer 是 libpag 官方仓库自带的跨平台桌面预览与编辑应用，使用 Qt 6 编写界面、以 libpag 渲染引擎为底层驱动，覆盖 macOS 与 Windows 两大桌面平台。它既是一个动画预览器，也是一个面向动画调试的轻量编辑工具：开发者、设计师可以将 PAG 文件拖入窗口，实时查看动画播放效果，检查图层树、修改文本内容、替换图片，并借助性能分析数据定位渲染瓶颈。

从入口代码 viewer/src/main.cpp 可以看到，应用启动后同时向 QML 注册了 PAGView、PAGXView 两类渲染视图组件（分别面向 .pag 与 .pagx 文件），并通过 pag::InitUpdater() 启动自动更新模块——这决定了 PAGViewer 是一个"渲染 + 编辑 + 分析 + 更新"的一体化工具。

核心功能一览

PAGViewer 的官方功能清单包含六项，每项都能在仓库源码中找到对应实现：

• PAG 动画文件实时预览：核心渲染链路位于 viewer/src/rendering/pag/PAGView.cpp，它创建 GPUDrawable 作为绘制目标，通过 PAGSurface::MakeFrom(drawable) 与 PAGPlayer::setSurface() 建立渲染管线，并将渲染任务交给独立渲染线程 RenderThread 执行，避免阻塞 QML 主线程。
• 图层树查看与属性编辑：由 viewer/src/editing 目录实现，其中 PAGTreeViewModel 负责图层树的数据模型，PAGEditAttributeModel 负责属性编辑，serialize/PAGTree.cpp 与 PAGTreeNode.cpp 完成树节点的序列化组织。
• 文本图层内容编辑：对应 editing/PAGTextLayerModel.cpp，通过编辑模型将 QML 侧的文本输入同步回 PAG 文本图层。
• PAG 文件内图片替换：对应 editing/PAGImageLayerModel.cpp 与 PAGImageProvider.cpp，支持对图片图层执行素材替换，可用于验证同一动画替换不同贴图后的效果。
• 性能分析与 profiling：对应 viewer/src/profiling 目录。PAGRunTimeDataModel（见 PAGRunTimeDataModel.h）会记录每帧的渲染耗时（renderTime）、上屏耗时（presentTime）与图片解码耗时（imageDecodeTime），并以图表数据模型（PAGChartDataModel）、文件信息模型（PAGFileInfoModel）和节点统计模型（PAGNodeStatsModel）的形式呈现。
• 自动更新支持：macOS 使用 Sparkle、Windows 使用 WinSparkle，实现代码位于 viewer/src/platform（PAGUpdater.mm / PAGUpdater.cpp），构建产物中会一并打包 Sparkle.framework 或 WinSparkle.dll。

此外，从源码结构看，PAGViewer 还内置了音频播放（viewer/src/audio）、视频导出（viewer/src/video）与 PNG/APNG 序列导出（viewer/src/task/export）等能力，是围绕 PAG 调试场景的完整工具链。

环境要求

构建与运行 PAGViewer 需要满足以下前提条件：

项目	要求
Qt 版本	Qt 6.2.0+（官方推荐 Qt 6.8.1），必须为 64 位
IDE	CLion（依赖其 CMake 集成与 Run Configuration 管理）
操作系统	macOS 12.0+ 或 Windows 10+（64 位）
前置依赖	已成功构建 libpag 库（见 主 README 的构建指南）

从 viewer/CMakeLists.txt 可确认 Qt 版本硬性约束：CMake 会从 CMAKE_PREFIX_PATH 中解析 Qt 主版本号，当 QT_VERSION_MAJOR >= 6 且系统指针宽度为 32 位时直接 FATAL_ERROR 终止构建（Qt 6 起不再支持 32 位构建）。同时工程要求 Qt 组件包含 Core Widgets OpenGL Qml Quick QuickControls2 Multimedia 等，并依赖 lupdate/lrelease 工具生成翻译资源。

构建步骤

macOS 构建

1. 准备 libpag 库：按 主 README 构建指南 完成 libpag 的编译。PAGViewer 并不会直接链接预先编译好的动态库，而是通过 add_custom_target(pag ...) 调用根目录的 build_pag 脚本，以静态库形式（PAG_BUILD_SHARED OFF、PAG_BUILD_FRAMEWORK OFF）自动编译出 libpag.a 并链接进 PAGViewer。
2. 打开工程：在 CLion 中打开 viewer 文件夹。
3. 配置 Qt 路径：首次 CMake 刷新时，会在工程目录自动生成 QTCMAKE.cfg 文件。将其中的 Qt 路径修改为本地实际安装路径：

   set(CMAKE_PREFIX_PATH /Users/[username]/Qt/6.6.1/macos/lib/cmake)
   

   该文件在 CMakeLists.txt 中由 file(WRITE ...) 自动写入，仅当 CMAKE_PREFIX_PATH 未定义时才会生成并被 include() 加载。
4. 构建并运行：选择 PAGViewer target，点击 Build 与 Run 即可。

构建完成后，CMake 的 POST_BUILD 阶段会自动执行 dsymutil 提取 dSYM 符号、拷贝 libffmovie.dylib 与 Sparkle.framework 到 app 包内，并调用 macdeployqt 将 Qt 运行库与 QML 目录（-qmldir=assets/qml）一并部署进 PAGViewer.app。

Windows 构建

1. 准备环境：按 主 README 构建指南 安装 VS2019 所需组件，并在 CLion 的 ToolChain 设置中选择 Visual Studio，架构选择 amd64。
2. 打开工程：在 CLion 中打开 viewer 文件夹。
3. 配置 Qt 路径：修改自动生成的 QTCMAKE.cfg，指向本机 Qt 6 安装路径（注意使用 MSVC 2019 64 位变体）：

   set(CMAKE_PREFIX_PATH C:/Qt/Qt6.2.0/6.2.0/msvc2019_64/lib/cmake
   

   （原文档示例路径中的括号不完整，实际应为 C:/Qt/Qt6.2.0/6.2.0/msvc2019_64/lib/cmake。）
4. 配置运行环境变量：在 CLion 的 PAGViewer target 运行配置中，将 Qt 的 DLL 目录加入 Environment Variables：

   PATH=C:\Qt\Qt6.2.0\6.2.0\msvc2019_64\bin
   

5. 构建并运行：选择 PAGViewer target 执行 Build 与 Run。

Windows 构建链同样在 POST_BUILD 阶段调用 windeployqt 部署 Qt 运行库，并拷贝 WinSparkle.dll 与 ffmovie.dll 到输出目录。MSVC 编译下工程默认开启 /utf-8 编码与 Release 符号（PDB）生成，便于崩溃定位。

小贴士：若自定义了 libpag 源码路径，可在 CMake 中通过 -DPAG_PATH=... 覆盖默认的 ../ 取值，构建系统会将该路径下的 build_pag 脚本作为 libpag 编译入口。

命令行参数

PAGViewer 支持以命令行方式打开文件与切换渲染模式：

PAGViewer [options] [file]

Options:
  -cpu    Force software rendering (disable GPU acceleration)

Arguments:
  file    Path to a PAG file to open on startup

参数的实际解析逻辑位于 viewer/src/main.cpp：

• -cpu：大小写不敏感匹配，命中后调用 QApplication::setAttribute(Qt::AA_UseSoftwareOpenGL) 强制走软件 OpenGL 渲染，适用于无 GPU 或需要排查 GPU 相关问题的环境；
• file：非 -cpu 参数即被当作文件路径，最终通过 app.openFile(...) 打开。openFile 会根据扩展名判断文件类型——.pagx 后缀的走 PAGX 渲染视图，其余按 .pag 处理（见 viewer/src/PAGViewer.cpp）；
• 应用还会监听 macOS 的 QEvent::FileOpen 事件，支持在 Finder 中双击关联文件唤起打开，实现文件关联打开能力。

启动渲染时应用会主动设置 OpenGL 3.2 Core Profile 的 QSurfaceFormat、切换 QML 场景图到 OpenGL 后端，并注册 Helvetica Neue, PingFang SC 等系统字体作为 PAG 文本回退字体（PAGFont::SetFallbackFontNames），保证中文字体场景下的显示正确性。

项目结构解析

viewer/
├── src/                    # 源码
│   ├── audio/              # 音频播放（模型、解码、渲染与音画同步）
│   ├── editing/            # 图层树与属性编辑（含 rttr 反射序列化）
│   ├── maintenance/        # 更新检查与插件安装管理
│   ├── platform/           # 平台相关代码（mac/win 的更新器、窗口辅助、插件安装）
│   ├── profiling/          # 性能分析（帧耗时、图表、节点统计模型）
│   ├── rendering/          # PAG/PAGX 渲染集成（视图、渲染线程、窗口管理）
│   ├── task/               # 后台任务（PNG/APNG 导出、性能基准与 profiling）
│   ├── utils/              # 工具函数（文件、字符串、音频、APNG 组装）
│   └── video/              # 视频导出（解复用与视频合成）
├── assets/                 # 资源
│   ├── qml/                # QML UI 文件（23 个 .qml 界面定义）
│   ├── images/             # 图标与应用图标
│   └── translation/        # i18n 翻译文件（.ts/.qm）
├── package/                # 构建与打包脚本（模板、打包脚本、签名脚本）
└── vendor/                 # 第三方依赖（由 DEPS 声明）

各模块与 README 描述一致，可从 viewer/src 目录树直接核对。其中值得重点关注的是：

• rendering 层：PAGView 继承自 ContentView，通过 RenderThread 独立线程执行 PAGRenderer，并在 updatePaintNode() 中基于 tgfx::Clock 计算播放进度、驱动帧刷新；音频同步逻辑（PAGView.cpp）通过 MaxAudioLeadThreshold/MinAudioLagThreshold 阈值进行音画校正。
• editing 层：PAGFileSerializer 负责文件序列化，配合 RTTR 反射自动注册（CMake 中调用 RttrAutoRegister 工具从 include/pag 生成 PAGRttr.hpp），实现了图层属性的通用读写。
• 维护与更新：PAGCheckUpdateModel 结合平台更新器（Sparkle/WinSparkle）实现自动升级，PluginInstallerModel 提供插件安装能力。

第三方依赖与版本

PAGViewer 的第三方依赖由 viewer/DEPS 声明，包括 H264 编码工具（H264EncoderTools）、macOS 的 DMG 打包工具 create-dmg、用于自动注册反射的 RttrAutoRegister 工具等。构建时 sync_deps.sh 会同步这些依赖，而 vendor/ 目录下则放置了 Sparkle、WinSparkle、sonic（音频变速）与 ffmovie（视频处理）等运行时库。

许可证

PAGViewer 遵循 Apache License 2.0 开源协议，完整条款见 LICENSE.txt。其核心依赖 libpag 渲染引擎同样位于本仓库根目录，可通过 主 README 进一步了解引擎的整体构建与跨平台支持情况。