扩展库 / stb_image_write

stb_image_write

从 Buffer 编码 PNG、JPEG、BMP、TGA、HDR，或经 XRT 写入 UTF-8 文件路径。

像素上限 64 MiB，输出上限 128 MiB；编码结果超限报告范围错误，实际分配失败报告内存错误，不返回部分图片。XLang 入口拒绝 C 整数回绕及写盘路径内嵌 NUL；文件写出使用 XRT 原子替换，失败保留已有目标。2026-10-26 重建发布物后，Windows/Linux x64 默认包门禁通过严格 C、Linux ASan/UBSan、故障与限额边界，以及 PNG/JPEG/BMP/TGA/HDR 五格式 C/XLang JIT 与独立 EXE 文件逐字节对照。旧共享 AOT 缺符号不再复现；仅签收本包有界 Buffer 编码/写出范围。

API

2026-10-30：BMP 在分配输出前按 RGB 展开与四字节行对齐计算总长度，超 128 MiB 立即报范围错误；不会先分配、扫描源像素或修改已有文件。合法 BMP 一次预留输出容量，1×1 灰度编码的可注入分配点从 5 减至 2，这不是吞吐或峰值内存测量。1/2/3 通道生成 54 字节头的 24 位 BMP（双通道 alpha 不保留），4 通道生成 122 字节 V4 头并保留 alpha。

新增 C/XLang 内存布局范例 release/extlibs/stb_image_write/examples/bmp_layout.xl 与 bmp_layout_c.c，无素材、不写文件，断言三种布局并输出同一五行结果。原五格式文件对照保留；108 组头信息、8 个限额/文件保留场景、实际 OOM 与恢复通过。Windows 35 项完整门禁、Linux 原生 ASan/UBSan 和双平台各 8 份独立程序通过；实际生成的 4 个 C 原型及错误返回值负例通过。失败会限时结束并保留原始状态和现场。依赖解码包的 M3 风险仍在，不据本轮结果宣称整包无风险。

函数	用途
`encodePng / writePng`	PNG 编码；可指定每行字节步长
`encodeJpeg / writeJpeg`	JPEG 编码；质量 1 至 100
`encodeBmp / writeBmp`	BMP 编码
`encodeTga / writeTga`	TGA 编码
`encodeHdr / writeHdr`	HDR 编码；像素为 float32 通道

xlang

import stb_image
import stb_image_write
stb_image.StbImage image = stb_image.load("photo.png", 4)
Buffer png = stb_image_write.encodePng(image.pixels(),
    image.width(), image.height(), image.channels())

C

包含 include/stb_image_write_native.h。xstbiw_encode 返回调用方用 xrtBufferDestroy 释放的 xbuffer*；像素指针仅借用。详情见包内 README 与 C/XL 对照范例。

Linux 包级门禁 bash release/extlibs/stb_image_write/test/check.sh 同次验证 C ASan/UBSan、XLang 参数与路径边界、64 MiB 输入下的编码输出限额及 C/XLang 范例一致性，并构建运行中央与双语范例独立 EXE。C/XLang 范例可显式指定素材路径；依赖包 stb_image 的私有构造器访问控制修复仍需单独完成。

Windows 可从仓库根目录运行 powershell -NoProfile -ExecutionPolicy Bypass -File release/extlibs/stb_image_write/test/check.ps1，联合验证严格 GCC、C/XLang 边界、输出限额专项与双语范例。