SumatraPDF 内置 JPEG XL 解码器 jxldec 源码解析与集成指南

SumatraPDF 内置 JPEG XL 解码器 jxldec 源码解析与集成指南【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf导读本文围绕 ext/jxldec/README.md 展开系统讲解 SumatraPDF 仓库中内嵌的 JPEG XL 解码器 jxldec它是一份由上游项目以 amalgamation 方式打包、仅用于解码的纯 C 实现替代了原先的 libjxl highway skcms 组合。读完本文你将掌握 jxldec 的完整 C API上下文、签名嗅探、文档解析、帧渲染与一键解码、其在 SumatraPDF 中的实际集成方式src/JxlReader.cpp、构建配置premake5.lua以及如何按 ext/versions.txt 升级上游代码。jxldec 是什么一份只读、内存、纯 C的 JXL 解码器ext/jxldec/README.md 对 jxldec 的定位描述得非常精炼来源从 kjk/jxldec 上游仓库打包vendored而来形态只取上游dist/目录下的 amalgamation 产物——jxl.cjxl.h两个文件当前仓库中 ext/jxldec/jxl.c 约 1.5 万行ext/jxldec/jxl.h 约 200 行性质只读decode-only、内存in-memory调用方把整个文件一次性交给解码器、纯 Cplain C定位取代旧的 libjxl highway skcms 解码栈。从仓库证据看这一替换在 ext/versions.txt 中也有明确记录jxldec 条目下标注 Replaces libjxl highway skcms for JPEG XL decode并记录了上游 commit54c8f53001b5f82886a8d96526ad1b0281e7c89a。也就是说SumatraPDF 不再依赖 libjxl 庞大的 C 生态而是用这份轻量的单文件 C 解码器承担所有 .jxl 图片的解码工作。这一点与仓库中 heicdec、djvudec、chmdec 等amalgamated dist/.c dist/.h only的做法一脉相承是 SumatraPDF 精简第三方依赖的惯用策略。为什么选择 amalgamation 形态从 premake5.lua 的工程定义可以印证其设计取舍jxldec 被定义为一个独立的 C 静态库工程只编译ext/jxldec/jxl.c与ext/jxldec/jxl.h两个文件并把编译优化设为optimize Speed因为解码是 CPU 密集任务倾向于用体积换速度。单一源文件意味着无需引入 highway 的 SIMD 分派层和 skcms 的色彩管理模块构建系统只需要一条编译规则头文件依赖极简仅stddef.h、stdint.h便于审计与隔离第三方代码不会泄漏到主工程命名空间。核心 C API 详解jxldec 公共头文件 提供了完整、自洽的 API整体风格被作者标注为 jbig2dec/djvudec-flavored与仓库中 ext/djvudec 的接口风格类似。下面按功能域拆解。1. 上下文分配器与诊断回调所有解码操作都以jxl_ctx为根它是分配记账 日志输出 行为开关的载体typedef void *(*jxl_alloc_cb)(void *user, void *ctx, size_t size); typedef void (*jxl_free_cb)(void *user, void *ctx, void *ptr); typedef void (*jxl_error_cb)(void *user, jxl_severity sev, const char *msg); jxl_ctx *jxl_ctx_new(jxl_alloc_cb alloc, jxl_free_cb free_cb, jxl_error_cb error, void *user); void jxl_ctx_free(jxl_ctx *ctx);要点传入 NULL 分配器则退回默认malloc/free传入 NULL 错误回调则静默丢弃诊断信息ctx参数用于标识分配归属jxl_ctx结构体自身的引导分配/释放除外此时为 NULL调用方可以按上下文核算内存错误级别jxl_severity从JXLDEC_SEVERITY_DEBUG到JXLDEC_SEVERITY_FATAL共五档msg是已格式化、以 NUL 结尾的字符串jxl_request_abort(ctx)用于协作式取消递增当前上下文上的 abort epoch所有进行中的渲染会尽快退出且线程安全。2. 行为开关BGR、朝向与 sRGB 输出void jxl_ctx_set_bgr(jxl_ctx *ctx, int enable); void jxl_ctx_set_keep_orientation(jxl_ctx *ctx, int enable); void jxl_ctx_set_srgb_output(jxl_ctx *ctx, int enable);三个开关各有明确用途set_bgr开启后 4 分量输出JXLDEC_FORMAT_RGBA32按 B,G,R,A 字节序、3 分量JXLDEC_FORMAT_RGB24按 B,G,R 字节序写出但图像仍标记为 RGB24/RGBA32。这是为 Windows DIB 等以 BGR 为本机布局的目标省去一次通道重排swizzle。SumatraPDF 在 src/JxlReader.cpp 中正是靠它直接把像素拷入PixmapFormat::BGRA8set_keep_orientation默认情况下解码器会应用图像的 EXIF 风格朝向字段与 libjxl 的JxlDecoder行为一致返回正立图像此时宽高可能相对码流互换开启后返回码流原始朝向set_srgb_output把 xyb 编码、声明了线性传递函数的图像在输出端施加 sRGB 传递曲线避免线性光图像被当作 sRGB 直出时显得发暗、对比过强只处理 xyb 编码图像的传递函数primaries 不动且对保留原色彩空间存储的图像不做改动默认关闭以保持与djxl兼容输出。3. 签名嗅探区分裸码流与 ISOBMFF 容器typedef enum { JXLDEC_SIG_INVALID 0, /* 确定不是 JPEG XL */ JXLDEC_SIG_NOT_ENOUGH_BYTES 1, /* 字节不够无法判定 */ JXLDEC_SIG_CODESTREAM 2, /* 裸码流0xFF 0x0A 开头 */ JXLDEC_SIG_CONTAINER 3 /* ISOBMFF 容器JXL box 签名 */ } jxl_signature; jxl_signature jxl_signature_check(const uint8_t *data, size_t len);jxl_signature_check是一次廉价的头部嗅探不需要创建任何上下文即可调用。SumatraPDF 的 src/JxlReader.cpp 里jxl::HasSignature正是用它同时识别裸码流与容器两种形态。注意 JXL 容器格式以 0 字节开头见 src/base/Win.cpp 中JP2/JXL/TGA 等格式合法地以 0 字节开头的处理注释因此调用方在做字符串/二进制判断时不能简单跳过前导 0。4. 文档打开与元数据jxl_doc *jxl_doc_open(jxl_ctx *ctx, const uint8_t *data, size_t len); void jxl_doc_close(jxl_doc *doc);jxl_doc_open在一个内存缓冲区上打开 JPEG XL 文件只解析容器与图像头不解码像素缓冲区不会被拷贝调用方必须保证其存活到jxl_doc_close。打开失败返回 NULL诊断信息通过错误回调给出。元数据通过jxl_image_info一次性给出typedef struct { int width; /* 显示宽度已应用朝向 */ int height; /* 显示高度 */ int bits_per_sample; /* 颜色通道的名义位深 */ int exponent_bits; /* 0 表示浮点采样 */ int num_color_channels; /* 1灰度或 3彩色 */ int num_extra_channels; int alpha_bits; /* 0 表示无 alpha 通道 */ int alpha_premultiplied; int have_animation; int num_frames; /* 动画帧数静态图为 1 */ int orientation; /* 1..8EXIF 风格 */ int have_preview; int uses_original_profile; /* 1 表示非 xyb 编码 */ jxl_color_space color_space; /* RGB / GRAY / XYB / UNKNOWN */ int intrinsic_width; /* 推荐显示尺寸或等于宽高 */ int intrinsic_height; } jxl_image_info;配套查询接口还有jxl_doc_frame_count动画帧数静态图返回 1、jxl_doc_icc_profile返回原色彩空间的内嵌 ICC profile指针归文档所有、在jxl_doc_close前有效无 ICC 时返回 NULL此时色彩编码由jxl_image_info枚举。5. 帧渲染格式、几何与零拷贝输出格式由jxl_format枚举控制覆盖 8/16 位、灰度/彩色、带/不带 alpha 的九种组合JXLDEC_FORMAT_NATIVE 0, /* 按图像元数据自动选择 */ JXLDEC_FORMAT_GRAY8 1, /* 1 字节/像素 */ JXLDEC_FORMAT_GRAYA8 2, /* 2 字节/像素 */ JXLDEC_FORMAT_RGB24 3, /* 3 字节/像素可经 set_bgr 变 BGR */ JXLDEC_FORMAT_RGBA32 4, /* 4 字节/像素 */ JXLDEC_FORMAT_GRAY16 5, /* 2 字节/像素本机字节序 u16 */ JXLDEC_FORMAT_GRAYA16 6, /* 4 字节/像素 */ JXLDEC_FORMAT_RGB48 7, /* 6 字节/像素 */ JXLDEC_FORMAT_RGBA64 8 /* 8 字节/像素 */jxl_format_bpp(fmt)返回已解析非 NATIVE格式的每像素字节数。渲染结果封装在jxl_image中含width、height、format、stride、自顶向下的data通过jxl_frame_render(doc, frame_no, fmt)获取用jxl_image_destroy(ctx, img)释放。三条与渲染相关的细节值得注意动画帧必须按顺序解码解码器在文档上保留上一帧状态以支持混合blending请求第 N 帧时会按需解码 0..Njxl_frame_render_info可以不解码像素就给出某帧的几何与格式供调用方预分配缓冲区jxl_frame_render_into直接渲染进调用方提供的、stride字节/行的自顶向下缓冲区省去一次整帧拷贝缓冲区必须与jxl_frame_render_info报告的几何一致。动画时序信息由jxl_frame_info提供duration_ticks帧时长单位是动画 tick、tps_numerator/tps_denominator每秒 tick 数 分子/分母、is_last。6. 一键便捷 API针对最常见的解码一个 blob场景头文件提供了两个一次性封装jxl_image *jxl_decode(jxl_ctx *ctx, const uint8_t *data, size_t len, jxl_format fmt); int jxl_decode_size(jxl_ctx *ctx, const uint8_t *data, size_t len, int *width, int *height);jxl_decode解码文件第一帧到一个新分配的图像jxl_decode_size只查头部尺寸成功返回 0。SumatraPDF 中的集成实践图片加载链路JxlReadersrc/JxlReader.cpp 是 jxldec 与 SumatraPDF 图片管线的桥接层三个函数全部基于上述 API 实现HasSignature(Str d)调用jxl_signature_check判定JXLDEC_SIG_CODESTREAM或JXLDEC_SIG_CONTAINER即为 JXLsrc/JxlReader.cppPixmapFromData(Str d)创建默认上下文后依次执行jxl_ctx_set_bgr(ctx, 1)—— 直接输出 BGRA与PixmapFormat::BGRA8对齐省掉 swizzlesrc/JxlReader.cppjxl_ctx_set_srgb_output(ctx, 1)—— 解决线性光图像发暗问题注释明确指向 issue #5919见 src/JxlReader.cppjxl_decode(ctx, data, len, JXLDEC_FORMAT_RGBA32)解码首帧随后逐行memcpy到分配好的 Pixmapsrc/JxlReader.cppSizeFromData(Str d)通过jxl_decode_size只取宽高避免完整解码src/JxlReader.cpp。jxl::PixmapFromData被 src/ImageReader.cpp 的 JPEG/WebP/JXL/HEIC 专用解码分支调用在 src/ImageReader.cpp 的注释中明确写道 WebP / JXL / HEIC/AVIF via our dedicated decoders (not GDI/WIC)并在 src/ImageReader.cpp 的 Windows 路径下与 libjpeg-turboJPEG、libwebpWebP、heicdecHEIC/AVIF并列。此外TGA/JXL 等也走PixmapFromDataWin。PDF 嵌入链路JXL 转 PNGPDF 无法直接内嵌 JXL因此 SumatraPDF 在需要把 JXL 图片放进 PDF 时先解码再转换。相关证据分布在src/PdfCreator.cpp注释列出 WebP, JXL, HEIC, AVIF, TGA, … — convert to something PDF can storesrc/PdfTools.cpp同样说明 PDF 无法直接重包装的格式WebP/JXL/HEIC/AVIF/TGA走解码路径src/PngOptimizer.h指出 JXL 通过转 PNG 用于 Convert to PDF。也就是说jxldec 不只服务于打开查看 .jxl 图片还支撑了图片转 PDF 的中间解码步骤。性能基准bench_imagesrc/tools/bench_image.cpp 中的DecodeJxldec演示了最简单的使用范式建上下文 →jxl_decode(...RGBA32)→ 校验宽高 → 销毁图像与上下文。它是独立于 GUI 的基准工具可用于直接对比 jxldec 与其他解码器路径的吞吐。构建配置premake5.lua 中 jxldec 工程的完整定义如下-- jxldec: JPEG XL decoder amalgamation (replaces libjxl highway skcms). project jxldec static_intermediate_dirs() kind StaticLib language C optimized_conf() -- decode is CPU-bound; favor speed over size optimize Speed defines { _CRT_SECURE_NO_WARNINGS } disablewarnings { 4018, 4100, 4127, 4204, 4244, 4245, 4267, 4389, 4456, 4701, 4702, 4996 } files { ext/jxldec/jxl.c, ext/jxldec/jxl.h }要点纯 C 静态库只编译 amalgamation 两个文件optimize Speed解码是 CPU 密集任务用体积换速度一条disablewarnings清单压制第三方代码在 MSVC 下的大量告警主程序通过includedirs { ext/jxldec }引入头文件并通过links { jxldec }链接见 premake5.lua 等处的示例。升级上游代码的流程按 ext/jxldec/README.md 及 ext/versions.txt当前记录的上游 commit 为54c8f53001b5f82886a8d96526ad1b0281e7c89a打包日期 2026-08-11升级步骤为从上游 jxldec 仓库取出dist/jxl.c与dist/jxl.h覆盖 ext/jxldec/jxl.c 与 ext/jxldec/jxl.h在 ext/versions.txt 中更新 jxldec 条目的版本/commit 与日期保持依赖清单可追溯。由于工程只引用这两个文件升级不会牵动其他构建目标但若上游 API 有变需要同步核对 src/JxlReader.cpp 与 src/tools/bench_image.cpp 中的调用点。小结jxldec 体现了 SumatraPDF 对图像解码这类重型第三方依赖的一贯处理方式单文件 C amalgamation、只读内存 API、按需精确控制输出格式。以 ext/jxldec/jxl.h 为契约上层只需三步即可接入建上下文jxl_ctx_new→ 可选设置 BGR/sRGB 开关 → 调用jxl_decode或jxl_doc_openjxl_frame_render组合。对想在自己的 C/C 工程里快速获得 JXL 解码能力、又不想引入 libjxl 复杂依赖链的开发者而言这套 API 形态本身就是一份很好的参考样板。【免费下载链接】sumatrapdfSumatraPDF reader项目地址: https://gitcode.com/gh_mirrors/su/sumatrapdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考