Implementation:Tencent Ncnn Stb Image
| Knowledge Sources | |
|---|---|
| Domains | Image Processing, Third Party Library |
| Last Updated | 2026-02-09 19:00 GMT |
Overview
Vendored copy of Sean Barrett's stb_image v2.28, a public-domain single-header C library for loading images from files or memory in multiple formats (JPEG, PNG, BMP, TGA, PSD, GIF, HDR, PIC, PNM).
Description
This is a third-party single-header library (8362 lines) included in the ncnn source tree as a vendored dependency. It provides stbi_load and related functions that decode compressed image data into raw pixel arrays.
The library supports SIMD acceleration via SSE2 (x86) and NEON (ARM). ncnn includes it with STB_IMAGE_IMPLEMENTATION defined in simpleocv.cpp to generate the actual implementation code, with format restrictions applied via defines:
- STBI_ONLY_JPEG -- include JPEG decoder
- STBI_ONLY_PNG -- include PNG decoder
- STBI_ONLY_BMP -- include BMP decoder
- STBI_ONLY_PNM -- include PNM decoder
These restrictions reduce code size by excluding decoders for TGA, PSD, GIF, HDR, and PIC formats that ncnn does not need. The STBI_NO_THREAD_LOCALS define is also set to avoid thread-local storage issues. ARM NEON is enabled via STBI_NEON when __ARM_NEON is defined.
Key capabilities include:
- JPEG: Baseline and progressive (12 bpc/arithmetic not supported)
- PNG: 1/2/4/8/16-bit-per-channel
- BMP: Non-1bpp, non-RLE
- PNM: PPM and PGM binary only
- Decoding from files, memory buffers, or arbitrary I/O callbacks
Usage
This library is not used directly by ncnn users. It is the image decoding backend for ncnn's simpleocv module, which wraps it with an OpenCV-compatible API. If you need to load images in an ncnn application, use cv::imread() from simpleocv or Mat::from_pixels() rather than calling stbi_load directly.
Code Reference
Source Location
- Repository: Tencent_Ncnn
- File: src/stb_image.h
- Original: nothings/stb - stb_image.h
Signature
// Load image from file
stbi_uc* stbi_load(char const *filename, int *x, int *y,
int *channels_in_file, int desired_channels);
// Load image from memory buffer
stbi_uc* stbi_load_from_memory(stbi_uc const *buffer, int len,
int *x, int *y, int *channels_in_file, int desired_channels);
// Load image from FILE pointer
stbi_uc* stbi_load_from_file(FILE *f, int *x, int *y,
int *channels_in_file, int desired_channels);
// Load image from I/O callbacks
stbi_uc* stbi_load_from_callbacks(stbi_io_callbacks const *clbk, void *user,
int *x, int *y, int *channels_in_file, int desired_channels);
// Query image info without decoding
int stbi_info(char const *filename, int *x, int *y, int *comp);
int stbi_info_from_memory(stbi_uc const *buffer, int len,
int *x, int *y, int *comp);
// Free decoded pixel data
void stbi_image_free(void *retval_from_stbi_load);
// Get error description
const char* stbi_failure_reason(void);
Import
// Only include with implementation define in ONE .cpp file
#define STB_IMAGE_IMPLEMENTATION
#include "stb_image.h"
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| filename | char const* | For stbi_load | Path to image file |
| buffer | stbi_uc const* | For from_memory | Pointer to encoded image data in memory |
| len | int | For from_memory | Length of the memory buffer in bytes |
| desired_channels | int | No | Requested number of output channels (0=same as file, 1=gray, 3=RGB, 4=RGBA) |
Outputs
| Name | Type | Description |
|---|---|---|
| return (stbi_load) | stbi_uc* | Pointer to decoded pixel data; NULL on failure. Must be freed with stbi_image_free() |
| *x | int | Width of the decoded image in pixels |
| *y | int | Height of the decoded image in pixels |
| *channels_in_file | int | Number of channels in the source image file |
Usage Examples
How ncnn Uses stb_image (inside simpleocv.cpp)
#define STB_IMAGE_IMPLEMENTATION
#define STBI_NO_THREAD_LOCALS
#define STBI_ONLY_JPEG
#define STBI_ONLY_PNG
#define STBI_ONLY_BMP
#define STBI_ONLY_PNM
#if __ARM_NEON
#define STBI_NEON
#endif
#include "stb_image.h"
// Inside cv::imread():
int w, h, c;
unsigned char* pixeldata = stbi_load(path.c_str(), &w, &h, &c, desired_channels);
if (!pixeldata) {
return Mat();
}
// ... copy to cv::Mat and swap RGB to BGR ...
stbi_image_free(pixeldata);