Class STBImageWrite
ABOUT
This header file is a library for writing images to C stdio.
The PNG output is not optimal; it is 20-50% larger than the file written by a decent optimizing implementation; though providing a custom zlib compress
function (see zlib_compress
) can mitigate that. This library is designed for source code compactness and simplicity, not optimal image
file size or run-time performance.
USAGE
There are five functions, one for each image file format:
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_hdr(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 float *data, int quality);
void stbi_flip_vertically_on_write(int flag); // flag is non-zero to flip data vertically
There are also five equivalent functions that use an arbitrary write function. You are expected to open/close your file-equivalent before and after calling these:
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_hdr_to_func(stbi_write_func *func, void *context, int w, int h, int comp, const float *data);
int stbi_write_jpg_to_func(stbi_write_func *func, void *context, int x, int y, int comp, const void *data, int quality);
where the callback is:
void stbi_write_func(void *context, void *data, int size);
You can configure it with these global variables:
int stbi_write_tga_with_rle; // defaults to true; set to 0 to disable RLE
int stbi_write_png_compression_level; // defaults to 8; set to higher for more compression
int stbi_write_force_png_filter; // defaults to -1; set to 0..5 to force a filter mode
The functions create an image file defined by the parameters. The image is a rectangle of pixels stored from left-to-right, top-to-bottom. Each pixel
contains comp
channels of data stored interleaved with 8-bits per channel, in the following order: 1=Y, 2=YA, 3=RGB, 4=RGBA. (Y is monochrome
color.) The rectangle is w
pixels wide and h
pixels tall. The *data
pointer points to the first byte of the top-left-most
pixel.
-
Field Summary
Modifier and TypeFieldDescriptionstatic final IntBuffer
Returns the address of the global variablestbi_write_force_png_filter
.static final IntBuffer
Returns the address of the global variablestbi_write_png_compression_level
.static final IntBuffer
Returns the address of the global variablestbi_write_tga_with_rle
.static final PointerBuffer
Returns the address of the global variablestbi_zlib_compress
. -
Method Summary
Modifier and TypeMethodDescriptionstatic void
nstbi_flip_vertically_on_write
(int flip_boolean) Unsafe version of:flip_vertically_on_write
static int
nstbi_write_bmp
(long filename, int w, int h, int comp, long data) Unsafe version of:write_bmp
static int
nstbi_write_bmp_to_func
(long func, long context, int w, int h, int comp, long data) Unsafe version of:write_bmp_to_func
static int
nstbi_write_hdr
(long filename, int w, int h, int comp, float[] data) Array version of:nstbi_write_hdr(long, int, int, int, long)
static int
nstbi_write_hdr
(long filename, int w, int h, int comp, long data) Unsafe version of:write_hdr
static int
nstbi_write_hdr_to_func
(long func, long context, int w, int h, int comp, float[] data) Array version of:nstbi_write_hdr_to_func(long, long, int, int, int, long)
static int
nstbi_write_hdr_to_func
(long func, long context, int w, int h, int comp, long data) Unsafe version of:write_hdr_to_func
static int
nstbi_write_jpg
(long filename, int w, int h, int comp, long data, int quality) Unsafe version of:write_jpg
static int
nstbi_write_jpg_to_func
(long func, long context, int w, int h, int comp, long data, int quality) Unsafe version of:write_jpg_to_func
static int
nstbi_write_png
(long filename, int w, int h, int comp, long data, int stride_in_bytes) Unsafe version of:write_png
static int
nstbi_write_png_to_func
(long func, long context, int w, int h, int comp, long data, int stride_in_bytes) Unsafe version of:write_png_to_func
static int
nstbi_write_tga
(long filename, int w, int h, int comp, long data) Unsafe version of:write_tga
static int
nstbi_write_tga_to_func
(long func, long context, int w, int h, int comp, long data) Unsafe version of:write_tga_to_func
static void
stbi_flip_vertically_on_write
(boolean flip_boolean) Configures if the written image should flipped vertically.static boolean
stbi_write_bmp
(CharSequence filename, int w, int h, int comp, ByteBuffer data) Writes a BMP image file.static boolean
stbi_write_bmp
(ByteBuffer filename, int w, int h, int comp, ByteBuffer data) Writes a BMP image file.static boolean
stbi_write_bmp_to_func
(STBIWriteCallbackI func, long context, int w, int h, int comp, ByteBuffer data) Callback version ofwrite_bmp
.static boolean
stbi_write_hdr
(CharSequence filename, int w, int h, int comp, float[] data) Array version of:write_hdr
static boolean
stbi_write_hdr
(CharSequence filename, int w, int h, int comp, FloatBuffer data) Writes an HDR image file.static boolean
stbi_write_hdr
(ByteBuffer filename, int w, int h, int comp, float[] data) Array version of:write_hdr
static boolean
stbi_write_hdr
(ByteBuffer filename, int w, int h, int comp, FloatBuffer data) Writes an HDR image file.static boolean
stbi_write_hdr_to_func
(STBIWriteCallbackI func, long context, int w, int h, int comp, float[] data) Array version of:write_hdr_to_func
static boolean
stbi_write_hdr_to_func
(STBIWriteCallbackI func, long context, int w, int h, int comp, FloatBuffer data) Callback version ofwrite_hdr
.static boolean
stbi_write_jpg
(CharSequence filename, int w, int h, int comp, ByteBuffer data, int quality) Writes a JPEG image file.static boolean
stbi_write_jpg
(ByteBuffer filename, int w, int h, int comp, ByteBuffer data, int quality) Writes a JPEG image file.static int
stbi_write_jpg_to_func
(STBIWriteCallbackI func, long context, int w, int h, int comp, ByteBuffer data, int quality) Callback version ofwrite_jpg
.static boolean
stbi_write_png
(CharSequence filename, int w, int h, int comp, ByteBuffer data, int stride_in_bytes) Writes a PNR image file.static boolean
stbi_write_png
(ByteBuffer filename, int w, int h, int comp, ByteBuffer data, int stride_in_bytes) Writes a PNR image file.static boolean
stbi_write_png_to_func
(STBIWriteCallbackI func, long context, int w, int h, int comp, ByteBuffer data, int stride_in_bytes) Callback version ofwrite_png
.static boolean
stbi_write_tga
(CharSequence filename, int w, int h, int comp, ByteBuffer data) Writes a TGA image file.static boolean
stbi_write_tga
(ByteBuffer filename, int w, int h, int comp, ByteBuffer data) Writes a TGA image file.static boolean
stbi_write_tga_to_func
(STBIWriteCallbackI func, long context, int w, int h, int comp, ByteBuffer data) Callback version ofwrite_tga
.
-
Field Details
-
stbi_write_png_compression_level
Returns the address of the global variablestbi_write_png_compression_level
. -
stbi_write_force_png_filter
Returns the address of the global variablestbi_write_force_png_filter
. -
stbi_zlib_compress
Returns the address of the global variablestbi_zlib_compress
.The address of an
STBIZlibCompress
instance may be set to this variable, in order to override the Zlib compression implementation. -
stbi_write_tga_with_rle
Returns the address of the global variablestbi_write_tga_with_rle
.
-
-
Method Details
-
nstbi_write_png
public static int nstbi_write_png(long filename, int w, int h, int comp, long data, int stride_in_bytes) Unsafe version of:write_png
-
stbi_write_png
public static boolean stbi_write_png(ByteBuffer filename, int w, int h, int comp, ByteBuffer data, int stride_in_bytes) Writes a PNR image file.PNG creates output files with the same number of components as the input.
PNG supports writing rectangles of data even when the bytes storing rows of data are not consecutive in memory (e.g. sub-rectangles of a larger image), by supplying the stride between the beginning of adjacent rows. The other formats do not. (Thus you cannot write a native-format BMP through the BMP writer, both because it is in BGR order and because it may have padding at the end of the line.)
PNG allows you to set the deflate compression level by setting the global variable
write_png_compression_level
(it defaults to 8).- Parameters:
filename
- the image file pathw
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image datastride_in_bytes
- the distance in bytes from the first byte of a row of pixels to the first byte of the next row of pixels- Returns:
- 1 on success, 0 on failure
-
stbi_write_png
public static boolean stbi_write_png(CharSequence filename, int w, int h, int comp, ByteBuffer data, int stride_in_bytes) Writes a PNR image file.PNG creates output files with the same number of components as the input.
PNG supports writing rectangles of data even when the bytes storing rows of data are not consecutive in memory (e.g. sub-rectangles of a larger image), by supplying the stride between the beginning of adjacent rows. The other formats do not. (Thus you cannot write a native-format BMP through the BMP writer, both because it is in BGR order and because it may have padding at the end of the line.)
PNG allows you to set the deflate compression level by setting the global variable
write_png_compression_level
(it defaults to 8).- Parameters:
filename
- the image file pathw
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image datastride_in_bytes
- the distance in bytes from the first byte of a row of pixels to the first byte of the next row of pixels- Returns:
- 1 on success, 0 on failure
-
nstbi_write_bmp
public static int nstbi_write_bmp(long filename, int w, int h, int comp, long data) Unsafe version of:write_bmp
-
stbi_write_bmp
Writes a BMP image file.The BMP format expands Y to RGB in the file format and does not output alpha.
- Parameters:
filename
- the image file pathw
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image data- Returns:
- 1 on success, 0 on failure
-
stbi_write_bmp
public static boolean stbi_write_bmp(CharSequence filename, int w, int h, int comp, ByteBuffer data) Writes a BMP image file.The BMP format expands Y to RGB in the file format and does not output alpha.
- Parameters:
filename
- the image file pathw
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image data- Returns:
- 1 on success, 0 on failure
-
nstbi_write_tga
public static int nstbi_write_tga(long filename, int w, int h, int comp, long data) Unsafe version of:write_tga
-
stbi_write_tga
Writes a TGA image file.TGA supports RLE or non-RLE compressed data. To use non-RLE-compressed data, set the global variable
stbi_write_tga_with_rle
to 0. The variable can be accessed withwrite_tga_with_rle
.- Parameters:
filename
- the image file pathw
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image data- Returns:
- 1 on success, 0 on failure
-
stbi_write_tga
public static boolean stbi_write_tga(CharSequence filename, int w, int h, int comp, ByteBuffer data) Writes a TGA image file.TGA supports RLE or non-RLE compressed data. To use non-RLE-compressed data, set the global variable
stbi_write_tga_with_rle
to 0. The variable can be accessed withwrite_tga_with_rle
.- Parameters:
filename
- the image file pathw
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image data- Returns:
- 1 on success, 0 on failure
-
nstbi_write_hdr
public static int nstbi_write_hdr(long filename, int w, int h, int comp, long data) Unsafe version of:write_hdr
-
stbi_write_hdr
Writes an HDR image file.HDR expects linear float data. Since the format is always 32-bit rgb(e) data, alpha (if provided) is discarded, and for monochrome data it is replicated across all three channels.
- Parameters:
filename
- the image file pathw
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image data- Returns:
- 1 on success, 0 on failure
-
stbi_write_hdr
public static boolean stbi_write_hdr(CharSequence filename, int w, int h, int comp, FloatBuffer data) Writes an HDR image file.HDR expects linear float data. Since the format is always 32-bit rgb(e) data, alpha (if provided) is discarded, and for monochrome data it is replicated across all three channels.
- Parameters:
filename
- the image file pathw
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image data- Returns:
- 1 on success, 0 on failure
-
nstbi_write_jpg
public static int nstbi_write_jpg(long filename, int w, int h, int comp, long data, int quality) Unsafe version of:write_jpg
-
stbi_write_jpg
public static boolean stbi_write_jpg(ByteBuffer filename, int w, int h, int comp, ByteBuffer data, int quality) Writes a JPEG image file.JPEG does ignore alpha channels in input data; quality is between 1 and 100. Higher quality looks better but results in a bigger image. JPEG baseline (no JPEG progressive).
- Parameters:
filename
- the image file pathw
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image dataquality
- the compression quality- Returns:
- 1 on success, 0 on failure
-
stbi_write_jpg
public static boolean stbi_write_jpg(CharSequence filename, int w, int h, int comp, ByteBuffer data, int quality) Writes a JPEG image file.JPEG does ignore alpha channels in input data; quality is between 1 and 100. Higher quality looks better but results in a bigger image. JPEG baseline (no JPEG progressive).
- Parameters:
filename
- the image file pathw
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image dataquality
- the compression quality- Returns:
- 1 on success, 0 on failure
-
nstbi_write_png_to_func
public static int nstbi_write_png_to_func(long func, long context, int w, int h, int comp, long data, int stride_in_bytes) Unsafe version of:write_png_to_func
-
stbi_write_png_to_func
public static boolean stbi_write_png_to_func(STBIWriteCallbackI func, long context, int w, int h, int comp, ByteBuffer data, int stride_in_bytes) Callback version ofwrite_png
.- Parameters:
func
- the callback functioncontext
- a context that will be passed tofunc
w
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image datastride_in_bytes
- the distance in bytes from the first byte of a row of pixels to the first byte of the next row of pixels- Returns:
- 1 on success, 0 on failure
-
nstbi_write_bmp_to_func
public static int nstbi_write_bmp_to_func(long func, long context, int w, int h, int comp, long data) Unsafe version of:write_bmp_to_func
-
stbi_write_bmp_to_func
public static boolean stbi_write_bmp_to_func(STBIWriteCallbackI func, long context, int w, int h, int comp, ByteBuffer data) Callback version ofwrite_bmp
.- Parameters:
func
- the callback functioncontext
- a context that will be passed tofunc
w
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image data- Returns:
- 1 on success, 0 on failure
-
nstbi_write_tga_to_func
public static int nstbi_write_tga_to_func(long func, long context, int w, int h, int comp, long data) Unsafe version of:write_tga_to_func
-
stbi_write_tga_to_func
public static boolean stbi_write_tga_to_func(STBIWriteCallbackI func, long context, int w, int h, int comp, ByteBuffer data) Callback version ofwrite_tga
.- Parameters:
func
- the callback functioncontext
- a context that will be passed tofunc
w
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image data- Returns:
- 1 on success, 0 on failure
-
nstbi_write_hdr_to_func
public static int nstbi_write_hdr_to_func(long func, long context, int w, int h, int comp, long data) Unsafe version of:write_hdr_to_func
-
stbi_write_hdr_to_func
public static boolean stbi_write_hdr_to_func(STBIWriteCallbackI func, long context, int w, int h, int comp, FloatBuffer data) Callback version ofwrite_hdr
.- Parameters:
func
- the callback functioncontext
- a context that will be passed tofunc
w
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image data- Returns:
- 1 on success, 0 on failure
-
nstbi_write_jpg_to_func
public static int nstbi_write_jpg_to_func(long func, long context, int w, int h, int comp, long data, int quality) Unsafe version of:write_jpg_to_func
-
stbi_write_jpg_to_func
public static int stbi_write_jpg_to_func(STBIWriteCallbackI func, long context, int w, int h, int comp, ByteBuffer data, int quality) Callback version ofwrite_jpg
.- Parameters:
func
- the callback functioncontext
- a context that will be passed tofunc
w
- the image width, in pixelsh
- the image height, in pixelscomp
- the number of channels in each pixeldata
- the image dataquality
- the compression quality- Returns:
- 1 on success, 0 on failure
-
nstbi_flip_vertically_on_write
public static void nstbi_flip_vertically_on_write(int flip_boolean) Unsafe version of:flip_vertically_on_write
-
stbi_flip_vertically_on_write
public static void stbi_flip_vertically_on_write(boolean flip_boolean) Configures if the written image should flipped vertically.- Parameters:
flip_boolean
- true to flip data vertically
-
nstbi_write_hdr
public static int nstbi_write_hdr(long filename, int w, int h, int comp, float[] data) Array version of:nstbi_write_hdr(long, int, int, int, long)
-
stbi_write_hdr
Array version of:write_hdr
-
stbi_write_hdr
Array version of:write_hdr
-
nstbi_write_hdr_to_func
public static int nstbi_write_hdr_to_func(long func, long context, int w, int h, int comp, float[] data) Array version of:nstbi_write_hdr_to_func(long, long, int, int, int, long)
-
stbi_write_hdr_to_func
public static boolean stbi_write_hdr_to_func(STBIWriteCallbackI func, long context, int w, int h, int comp, float[] data) Array version of:write_hdr_to_func
-