single C file header library for Wuffs with a stb_image.h compatible API
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-04 22:17:04 -05:00
.gitattributes Add Wuffs license files and LF .gitattributes 2026-10-24 03:03:15 -04:00
LICENSE updated 2026-10-24 02:11:09 -04:00
LICENSE-WUFFS-APACHE Add Wuffs license files and LF .gitattributes 2026-10-24 03:03:15 -04:00
LICENSE-WUFFS-MIT Add Wuffs license files and LF .gitattributes 2026-10-24 03:03:15 -04:00
README.md Update link format in README.md 2026-10-24 12:02:02 -04:00
stb_image_wuffs.h new files 2026-10-24 02:11:01 -04:00
wuffs-v0.4.c latest upstream version, built locally - this includes the empty Huffman table fix (PR #208) 2026-11-04 22:17:04 -05:00

stb_image_wuffs

A single-header, near drop-in replacement for stb_image.h v2.30 that keeps stb_image's API and hands all decoding to Wuffs, a memory-safe (but still quite fast) image decoder library. The adapter itself parses no image data.

stb_image is a classic: one file, a tiny API, and it just works. This header keeps that API unchanged and lets Wuffs do the decoding.

Another similar take on an stb_image-style API for Wuffs adapter is rdh9616/stb-wuffs.

Why

This alternative implementation of the stb_image API is built on Wuffs, a library designed to be hardened against adversarial inputs: its decoders are written in a language that proves bounds and overflow safety at compile time, and they are fuzzed continuously. That makes it a good fit wherever images come from sources you don't control, such as files downloaded from the web or uploaded by users.

Joining two image APIs robustly is non-trivial in its own right. The adapter has to reproduce stb_image's behavior (channel counts and conversions, 16-bit and float output, vertical flip, FILE and callback I/O semantics, animated GIF output, failure reasons) on top of Wuffs' streaming decoders, while handling the quirks of both libraries. It's checked by a differential test against the real stb_image, sanitizer and thread-safety stress tests, and builds with MSVC, gcc, clang and tcc, 32-bit and 64-bit.

Use

#define STB_IMAGE_IMPLEMENTATION
#include "stb_image_wuffs.h"      // was: #include "stb_image.h"

int w, h, n;
unsigned char *px = stbi_load("photo.jpg", &w, &h, &n, 4);
// .. use the image data ..
stbi_image_free(px);

Put wuffs-v0.4.c next to the header (or #define STBI_WUFFS_SOURCE). Those two files are all you need.

Tested with wuffs-v0.4.c 0.4.0-alpha.12+4048.20261020, unmodified.

Speed

It's quite similar for .JPEG (0.77x-1.07x vs. stb_image.h), and for .PNG it's 1.4x-1.7x faster (Ryzen 9 9950X, gcc and clang).

Formats

stb_image stb_image_wuffs
PNG (incl. APNG frames), JPEG, GIF (inc. animated), BMP, TGA, binary PNM yes yes
WebP (still), QOI, ETC2 no yes
PSD, HDR, PIC yes no

The most interesting/useful still unsupported format is .HDR, which I hope to tackle next.

Documentation

See the comment block at the top of stb_image_wuffs.h: configuration macros, the (few) differences from stb_image and why, thread safety, the float conversion options, sRGB to linear conversion options, proper 16-bit/component image format conversion to floating point support, and the known Wuffs v0.4 limitations.

License

Wuffs (wuffs-v0.4.c): Apache-2.0 or MIT; see LICENSE-WUFFS-APACHE and LICENSE-WUFFS-MIT.

stb_image_wuffs.h: the adapter header file library uses the same license as stb_image: your choice of MIT (Copyright (c) 2017 Sean Barrett) or public domain (Unlicense); see the end of stb_image_wuffs.h. Importantly, stb_image_wuffs.h is derived from the original stb_image.h, so its dual license is unchanged, but the actual implementation is completely different. This means any bugs or issues in stb_image_wuffs.h have nothing to do with the original stb_image.h.

This project is independent and not affiliated with the Wuffs or stb authors.