Class STBImageWrite
- java.lang.Object
-
- org.lwjgl.stb.STBImageWrite
-
public class STBImageWrite extends java.lang.Object
Native bindings to stb_image_write.h from the stb library.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 isw
pixels wide andh
pixels tall. The*data
pointer points to the first byte of the top-left-most pixel.
-
-
Field Summary
Fields Modifier and Type Field Description static java.nio.IntBuffer
stbi_write_force_png_filter
Returns the address of the global variablestbi_write_force_png_filter
.static java.nio.IntBuffer
stbi_write_png_compression_level
Returns the address of the global variablestbi_write_png_compression_level
.static java.nio.IntBuffer
stbi_write_tga_with_rle
Returns the address of the global variablestbi_write_tga_with_rle
.static org.lwjgl.PointerBuffer
stbi_zlib_compress
Returns the address of the global variablestbi_zlib_compress
.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static 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(java.lang.CharSequence filename, int w, int h, int comp, java.nio.ByteBuffer data)
Writes a BMP image file.static boolean
stbi_write_bmp(java.nio.ByteBuffer filename, int w, int h, int comp, java.nio.ByteBuffer data)
Writes a BMP image file.static boolean
stbi_write_bmp_to_func(STBIWriteCallbackI func, long context, int w, int h, int comp, java.nio.ByteBuffer data)
Callback version ofwrite_bmp
.static boolean
stbi_write_hdr(java.lang.CharSequence filename, int w, int h, int comp, float[] data)
Array version of:write_hdr
static boolean
stbi_write_hdr(java.lang.CharSequence filename, int w, int h, int comp, java.nio.FloatBuffer data)
Writes an HDR image file.static boolean
stbi_write_hdr(java.nio.ByteBuffer filename, int w, int h, int comp, float[] data)
Array version of:write_hdr
static boolean
stbi_write_hdr(java.nio.ByteBuffer filename, int w, int h, int comp, java.nio.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, java.nio.FloatBuffer data)
Callback version ofwrite_hdr
.static boolean
stbi_write_jpg(java.lang.CharSequence filename, int w, int h, int comp, java.nio.ByteBuffer data, int quality)
Writes a JPEG image file.static boolean
stbi_write_jpg(java.nio.ByteBuffer filename, int w, int h, int comp, java.nio.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, java.nio.ByteBuffer data, int quality)
Callback version ofwrite_jpg
.static boolean
stbi_write_png(java.lang.CharSequence filename, int w, int h, int comp, java.nio.ByteBuffer data, int stride_in_bytes)
Writes a PNR image file.static boolean
stbi_write_png(java.nio.ByteBuffer filename, int w, int h, int comp, java.nio.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, java.nio.ByteBuffer data, int stride_in_bytes)
Callback version ofwrite_png
.static boolean
stbi_write_tga(java.lang.CharSequence filename, int w, int h, int comp, java.nio.ByteBuffer data)
Writes a TGA image file.static boolean
stbi_write_tga(java.nio.ByteBuffer filename, int w, int h, int comp, java.nio.ByteBuffer data)
Writes a TGA image file.static boolean
stbi_write_tga_to_func(STBIWriteCallbackI func, long context, int w, int h, int comp, java.nio.ByteBuffer data)
Callback version ofwrite_tga
.
-
-
-
Field Detail
-
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 Detail
-
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(java.nio.ByteBuffer filename, int w, int h, int comp, java.nio.ByteBuffer data, int stride_in_bytes) public static boolean stbi_write_png(java.lang.CharSequence filename, int w, int h, int comp, java.nio.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
public static boolean stbi_write_bmp(java.nio.ByteBuffer filename, int w, int h, int comp, java.nio.ByteBuffer data) public static boolean stbi_write_bmp(java.lang.CharSequence filename, int w, int h, int comp, java.nio.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
public static boolean stbi_write_tga(java.nio.ByteBuffer filename, int w, int h, int comp, java.nio.ByteBuffer data) public static boolean stbi_write_tga(java.lang.CharSequence filename, int w, int h, int comp, java.nio.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
public static boolean stbi_write_hdr(java.nio.ByteBuffer filename, int w, int h, int comp, java.nio.FloatBuffer data) public static boolean stbi_write_hdr(java.lang.CharSequence filename, int w, int h, int comp, java.nio.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(java.nio.ByteBuffer filename, int w, int h, int comp, java.nio.ByteBuffer data, int quality) public static boolean stbi_write_jpg(java.lang.CharSequence filename, int w, int h, int comp, java.nio.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, java.nio.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, java.nio.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, java.nio.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, java.nio.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, java.nio.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
public static boolean stbi_write_hdr(java.nio.ByteBuffer filename, int w, int h, int comp, float[] data) public static boolean stbi_write_hdr(java.lang.CharSequence filename, int w, int h, int comp, float[] data)
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
-
-