Native bindings to stb_image.h from the stb library
Primarily of interest to game developers and other people who can avoid problematic images and only need the trivial interface. Supported formats:
- JPEG baseline & progressive (12 bpc/arithmetic not supported, same as stock IJG lib
- PNG 1/2/4/8/16-bit-per-channel
- TGA (not sure what subset, if a subset)
- BMP non-1bpp, non-RLE
- PSD (composited view only, no extra channels, 8/16 bit-per-channel)
- GIF (*desired_channels always reports as 4-channel)
- HDR (radiance rgbE format)
- PIC (Softimage PIC)
- PNM (PPM and PGM binary only)
Animated GIF still needs a proper API, but here's one way to do it.
- decode from memory
- decode from arbitrary I/O callbacks
- SIMD acceleration on x86/x64 (SSE2) and ARM (NEON)
- no 12-bit-per-channel JPEG
- no JPEGs with arithmetic coding
- GIF always returns *channels_in_file=4
Basic usage (see HDR discussion below for HDR usage):
unsigned char *data = stbi_load(filename, &x, &y, &n, 0);
// ... process data if not NULL ...
// ... x = width, y = height, n = # 8-bit components per pixel ...
// ... replace '0' with '1'..'4' to force that many components per pixel
// ... but 'n' will always be the number that it would have been if you said 0
HDR image support
stb_image now supports loading HDR images in general, and currently the Radiance .HDR file format, although the support is provided generically. You
can still load any file through the existing interface; if you attempt to load an HDR file, it will be automatically remapped to LDR, assuming gamma
2.2 and an arbitrary scale factor defaulting to 1; both of these constants can be reconfigured through this interface:
(note, do not use inverse constants; stbi_image will invert them appropriately).
Additionally, there is a new, parallel interface for loading files as (linear) floats to preserve the full dynamic range:
float *data = stbi_loadf(filename, &x, &y, &n, 0);
If you load LDR images through this interface, those images will be promoted to floating point values, run through the inverse of constants
corresponding to the above:
Finally, given a filename (or an open file or memory block) containing image data, you can query for the "most appropriate" interface to use (that is,
whether the image is HDR or not), using:
iPhone PNG support
By default we convert iphone-formatted PNGs back to RGB, even though they are internally encoded differently. You can disable this conversion by
#stbi_convert_iphone_png_to_rgb(0), in which case you will always just get the native iphone "format" through (which is BGR stored in RGB).
#stbi_set_unpremultiply_on_load(1) as well to force a divide per pixel to remove any premultiplied alpha *only* if the image file explicitly says
there's premultiplied data (currently only happens in iPhone images, and only if iPhone convert-to-rgb processing is on).