stb_image_write.h实战教程：5分钟掌握图像保存技巧

你还在为图像保存代码复杂而烦恼？是否觉得集成图像导出功能需要引入庞大的库？本文将带你5分钟掌握stb_image_write.h的使用方法，用不到20行代码实现专业级图像保存功能。读完本文你将学会：

• 单文件集成图像导出能力
• 支持PNG/JPG/BMP/TGA/HDR五种格式
• 垂直翻转、压缩等级等高级设置
• 内存管理与错误处理最佳实践

为什么选择stb_image_write.h？

stb_image_write.h是stb系列单文件库的重要成员（项目地址：gh_mirrors/st/stb），它具有以下优势：

特性	传统库（如libpng）	stb_image_write.h
文件数量	数十个文件	1个文件
编译依赖	需要链接外部库	无任何依赖
代码量	数万行	~1000行核心代码
许可证	GPL/复杂协议	公共领域（无版权限制）
功能	全面但复杂	够用且简洁

官方文档：stb_image_write.h
测试用例参考：tests/image_write_test.c

快速上手：3步实现图像保存

第一步：引入头文件

创建C/C++文件，添加以下代码：

#define STB_IMAGE_WRITE_IMPLEMENTATION
#include "stb_image_write.h"

⚠️ 注意：STB_IMAGE_WRITE_IMPLEMENTATION宏必须只定义一次，通常放在你项目中唯一的C/C++文件里。

第二步：准备图像数据

假设我们要保存一个6x5的红色"F"形状图像（测试用例中的经典图案）：

// 创建6x5的RGB图像数据（宽x高x3通道）
unsigned char img[6*5*3];
int i, j;
for (j=0; j<5; j++) {
    for (i=0; i<6; i++) {
        int idx = (j*6 + i)*3;
        // 红色前景，蓝色背景
        int is_red = (i==1 && j<4) || (j==0 && i>1 && i<5) || (j==2 && i>1 && i<4);
        img[idx+0] = is_red ? 255 : 0;   // R通道
        img[idx+1] = 0;                  // G通道
        img[idx+2] = is_red ? 0 : 255;   // B通道
    }
}

第三步：调用保存函数

一行代码保存为PNG格式：

// 参数：文件名、宽度、高度、通道数、数据、行跨度
stbi_write_png("output.png", 6, 5, 3, img, 6*3);

支持的图像格式全解析

stb_image_write.h提供5种格式的保存函数，参数各有特点：

1. PNG格式（推荐用于无损保存）

// 压缩等级(0-9)：默认8，等级越高文件越小但速度越慢
stbi_write_png_compression_level = 6;
stbi_write_png("image.png", 6, 5, 3, img, 6*3);

行跨度(stride)参数：当图像数据有内存对齐或边缘填充时使用，通常设为宽度*通道数

2. JPG格式（适合照片类图像）

// 质量参数(1-100)：85为视觉与文件大小的平衡点
stbi_write_jpg("image.jpg", 6, 5, 3, img, 85);

3. BMP格式（Windows兼容，无压缩）

// BMP会自动将单色/YA格式扩展为RGB
stbi_write_bmp("image.bmp", 6, 5, 3, img);

4. TGA格式（游戏开发常用）

// 启用RLE压缩（默认开启）
stbi_write_tga_with_rle = 1;
stbi_write_tga("image.tga", 6, 5, 3, img);

5. HDR格式（高动态范围图像）

// 需要浮点数据输入（范围不受限）
float hdr_data[6*5*3];
// ... 填充浮点RGB数据 ...
stbi_write_hdr("image.hdr", 6, 5, 3, hdr_data);

高级技巧：提升图像质量与性能

垂直翻转图像

解决OpenGL/DirectX坐标系差异：

stbi_flip_vertically_on_write(1);  // 开启垂直翻转
stbi_write_png("flipped.png", 6, 5, 3, img, 6*3);
stbi_flip_vertically_on_write(0);  // 恢复默认

效果对比：
原始图像：
翻转后图像：

自定义压缩等级

PNG格式压缩控制：

stbi_write_png_compression_level = 4;  // 0=最快, 9=最小（默认8）

内存数据直接保存

配合stb_image.h实现图像加载->处理->保存流水线：

// 伪代码示例
unsigned char *img = stbi_load("input.jpg", &w, &h, &c, 3);
// ... 图像处理 ...
stbi_write_png("output.png", w, h, 3, img, w*3);
stbi_image_free(img);  // 释放stbi_load分配的内存

常见问题解决方案

Q：保存失败返回0怎么办？

A：检查：

1. 路径是否可写（推荐使用绝对路径调试）
2. 图像宽高是否为正数
3. 通道数是否合法（1/2/3/4）

Q：如何处理内存受限环境？

A：使用自定义内存分配器：

#define STBIW_MALLOC(size) my_malloc(size)
#define STBIW_FREE(ptr) my_free(ptr)
#include "stb_image_write.h"

Q：能否在WebAssembly环境使用？

A：可以！配合Emscripten的文件系统API：

// 编译：emcc -s FORCE_FILESYSTEM=1
stbi_write_png("/output.png", w, h, c, data, w*c);

总结与扩展学习

通过本文，你已掌握stb_image_write.h的核心用法。这个仅100KB的文件能帮你：

• 快速原型开发
• 嵌入式系统图像导出
• 游戏截图功能
• 数据可视化输出

点赞👍+收藏⭐+关注，获取更多stb系列教程！
下期预告：《stb_truetype.h：10行代码实现字体渲染》

完整示例代码

#define STB_IMAGE_WRITE_IMPLEMENTATION
#include "stb_image_write.h"
#include <stdlib.h>

int main() {
    // 创建6x5测试图像
    unsigned char img[6*5*3];
    int i,j,idx;
    for(j=0;j<5;j++) for(i=0;i<6;i++) {
        idx = (j*6 + i)*3;
        int is_red = (i==1 && j<4) || (j==0 && i>1 && i<5) || (j==2 && i>1 && i<4);
        img[idx] = is_red ? 255 : 0;
        img[idx+1] = 0;
        img[idx+2] = is_red ? 0 : 255;
    }

    // 保存为多种格式
    stbi_write_png("f_out.png",6,5,3,img,6*3);
    stbi_write_jpg("f_out.jpg",6,5,3,img,90);
    stbi_write_bmp("f_out.bmp",6,5,3,img);
    
    return 0;
}

完整测试项目：tests/image_write_test.c
更多stb库：stb系列文档