Implementation:Tencent Ncnn Stb Image Write

Knowledge Sources	Tencent_Ncnn
Domains	Image Processing, Third Party Library
Last Updated	2026-02-09 19:00 GMT

Overview

Vendored copy of Sean Barrett's stb_image_write v1.16, a public-domain single-header C library for writing images to files or memory buffers in PNG, BMP, TGA, JPEG, and HDR formats.

Description

This is a third-party single-header library (1724 lines) included in the ncnn source tree as a vendored dependency. It provides functions for encoding raw pixel data into compressed image formats and writing them to files or memory.

The library supports five output formats:

PNG -- with configurable compression level (stbi_write_png_compression_level, default 8)
BMP -- expands grayscale to RGB, no alpha output
TGA -- supports RLE compression (stbi_write_tga_with_rle, default enabled)
JPEG -- baseline only, configurable quality 1-100, ignores alpha channels
HDR -- Radiance rgbE format, expects linear float data

ncnn includes it with STB_IMAGE_WRITE_IMPLEMENTATION defined in simpleocv.cpp to generate the actual implementation code. Each function accepts raw pixel data with width, height, and component count, and returns 0 on failure or non-zero on success.

Both file-based and callback-based variants are provided. The callback interface (stbi_write_func) allows writing to arbitrary destinations (memory buffers, network streams, etc.).

Usage

This library is not used directly by ncnn users. It is the image encoding backend for ncnn's simpleocv module. If you need to save images in an ncnn application, use cv::imwrite() from simpleocv rather than calling stbi_write functions directly.

Code Reference

Source Location

Repository: Tencent_Ncnn
File: src/stb_image_write.h
Original: nothings/stb - stb_image_write.h

Signature

// Write to file
int stbi_write_png(char const *filename, int w, int h, int comp,
    const void *data, int stride_in_bytes);
int stbi_write_bmp(char const *filename, int w, int h, int comp,
    const void *data);
int stbi_write_tga(char const *filename, int w, int h, int comp,
    const void *data);
int stbi_write_jpg(char const *filename, int w, int h, int comp,
    const void *data, int quality);
int stbi_write_hdr(char const *filename, int w, int h, int comp,
    const float *data);

// Write to callback
int stbi_write_png_to_func(stbi_write_func *func, void *context,
    int w, int h, int comp, const void *data, int stride_in_bytes);
int stbi_write_bmp_to_func(stbi_write_func *func, void *context,
    int w, int h, int comp, const void *data);
int stbi_write_tga_to_func(stbi_write_func *func, void *context,
    int w, int h, int comp, const void *data);
int stbi_write_jpg_to_func(stbi_write_func *func, void *context,
    int x, int y, int comp, const void *data, int quality);
int stbi_write_hdr_to_func(stbi_write_func *func, void *context,
    int w, int h, int comp, const float *data);

// Vertical flip control
void stbi_flip_vertically_on_write(int flag);

// Callback type
typedef void stbi_write_func(void *context, void *data, int size);

Import

// Only include with implementation define in ONE .cpp file
#define STB_IMAGE_WRITE_IMPLEMENTATION
#include "stb_image_write.h"

I/O Contract

Inputs

Name	Type	Required	Description
filename	char const*	For file variants	Output file path
w	int	Yes	Image width in pixels
h	int	Yes	Image height in pixels
comp	int	Yes	Number of channels (1=Y, 2=YA, 3=RGB, 4=RGBA)
data	const void*	Yes	Pointer to raw pixel data (left-to-right, top-to-bottom)
stride_in_bytes	int	For PNG	Distance in bytes between the start of adjacent rows
quality	int	For JPEG	JPEG quality 1-100 (higher = better quality, larger file)
func	stbi_write_func*	For callback variants	User-provided write callback function
context	void*	For callback variants	User context passed to the write callback

Outputs

Name	Type	Description
return value	int	0 on failure, non-zero on success

Usage Examples

How ncnn Uses stb_image_write (inside simpleocv.cpp)

#define STB_IMAGE_WRITE_IMPLEMENTATION
#include "stb_image_write.h"

// Inside cv::imwrite():
// (after BGR-to-RGB conversion)
if (ext == "png") {
    stbi_write_png(path.c_str(), m.cols, m.rows, m.channels(),
        m.data, m.cols * m.channels());
} else if (ext == "jpg") {
    stbi_write_jpg(path.c_str(), m.cols, m.rows, m.channels(),
        m.data, quality);
} else if (ext == "bmp") {
    stbi_write_bmp(path.c_str(), m.cols, m.rows, m.channels(),
        m.data);
}

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment