Class STBImage
- java.lang.Object
-
- org.lwjgl.stb.STBImage
-
public class STBImage extends java.lang.ObjectNative bindings to stb_image.h from the stb library.Quick notes
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-bit-per-channel (16 bpc not supported)
- 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 (*comp 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.
Features:
- decode from memory
or through FILE (define STBI_NO_STDIO to remove code) - decode from arbitrary I/O callbacks
- SIMD acceleration on x86/x64 (SSE2) and ARM (NEON)
Limitations:
- no 16-bit-per-channel PNG
- no 12-bit-per-channel JPEG
- no JPEGs with arithmetic coding
- no 1-bit BMP
- GIF always returns *comp=4
Basic usage (see HDR discussion below for HDR usage):
int x,y,n; 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 stbi_image_free(data)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:
stbi_hdr_to_ldr_gamma(2.2f); stbi_hdr_to_ldr_scale(1.0f);(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:
stbi_ldr_to_hdr_scale(1.0f); stbi_ldr_to_hdr_gamma(2.2f);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:
stbi_is_hdr(char *filename);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 calling
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).Call
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).
-
-
Field Summary
Fields Modifier and Type Field and Description static intSTBI_defaultDefault component count, used as an argument toreq_comp.static intSTBI_grey
STBI_grey_alpha
STBI_rgb
STBI_rgb_alphaComponent count.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method and Description static voidstbi_convert_iphone_png_to_rgb(int flag_true_if_should_convert)Indicate whether we should process iPhone images back to canonical format, or just pass them through "as-is".static java.lang.Stringstbi_failure_reason()Returns a brief reason for failure.static voidstbi_hdr_to_ldr_gamma(float gamma)Changes the gamma value used when converting HDR images to LDR.static voidstbi_hdr_to_ldr_scale(float scale)Changes the scale factor used when converting HDR images to LDR.static voidstbi_image_free(java.nio.ByteBuffer retval_from_stbi_load)Frees a loaded imagestatic voidstbi_image_free(float[] retval_from_stbi_load)float[] version of:image_freestatic voidstbi_image_free(java.nio.FloatBuffer retval_from_stbi_load)FloatBuffer version of:image_freestatic intstbi_info_from_callbacks(STBIIOCallbacks clbk, long user, int[] x, int[] y, int[] comp)Array version of:info_from_callbacksstatic intstbi_info_from_callbacks(STBIIOCallbacks clbk, long user, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp)Callback version ofinfo.static intstbi_info_from_memory(java.nio.ByteBuffer buffer, int[] x, int[] y, int[] comp)Array version of:info_from_memorystatic intstbi_info_from_memory(java.nio.ByteBuffer buffer, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp)In-memory version ofinfo.static intstbi_info(java.nio.ByteBuffer filename, int[] x, int[] y, int[] comp)Array version of:infostatic intstbi_info(java.nio.ByteBuffer filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp)Returns image dimensions & components without fully decoding the image.static intstbi_info(java.lang.CharSequence filename, int[] x, int[] y, int[] comp)Array version of:infostatic intstbi_info(java.lang.CharSequence filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp)Returns image dimensions & components without fully decoding the image.static intstbi_is_hdr_from_callbacks(STBIIOCallbacks clbk, long user)Callback version ofis_hdr.static intstbi_is_hdr_from_memory(java.nio.ByteBuffer buffer)In-memory version ofis_hdr.static intstbi_is_hdr(java.nio.ByteBuffer filename)Checks if the specified file contains an HDR image.static intstbi_is_hdr(java.lang.CharSequence filename)Checks if the specified file contains an HDR image.static voidstbi_ldr_to_hdr_gamma(float gamma)Changes the gamma value used when converting LDR images to HDR.static voidstbi_ldr_to_hdr_scale(float scale)Changes the gamma value used when converting LDR images to HDR.static java.nio.ByteBufferstbi_load_from_callbacks(STBIIOCallbacks clbk, long user, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Callback version ofload.static java.nio.ByteBufferstbi_load_from_memory(java.nio.ByteBuffer buffer, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)In-memory version ofload.static java.nio.ByteBufferstbi_load(java.nio.ByteBuffer filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Loads an image from the specified file.static java.nio.ByteBufferstbi_load(java.lang.CharSequence filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Loads an image from the specified file.static java.nio.FloatBufferstbi_loadf_from_callbacks(STBIIOCallbacks clbk, long user, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Floating-point version ofload_from_callbacks.static java.nio.FloatBufferstbi_loadf_from_memory(java.nio.ByteBuffer buffer, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Floating-point version ofload_from_memory.static java.nio.FloatBufferstbi_loadf(java.nio.ByteBuffer filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Floating-point version ofload.static java.nio.FloatBufferstbi_loadf(java.lang.CharSequence filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Floating-point version ofload.static voidstbi_set_flip_vertically_on_load(int flag_true_if_should_flip)Flips the image vertically, so the first pixel in the output array is the bottom left.static voidstbi_set_unpremultiply_on_load(int flag_true_if_should_unpremultiply)For image formats that explicitly notate that they have premultiplied alpha, we just return the colors as stored in the file.static intstbi_zlib_decode_buffer(java.nio.ByteBuffer obuffer, java.nio.ByteBuffer ibuffer)ZLIB client - used by PNG, available for other purposesstatic java.nio.ByteBufferstbi_zlib_decode_malloc_guesssize_headerflag(java.nio.ByteBuffer buffer, int initial_size, int parse_header)ZLIB client - used by PNG, available for other purposesstatic java.nio.ByteBufferstbi_zlib_decode_malloc_guesssize(java.nio.ByteBuffer buffer, int initial_size)ZLIB client - used by PNG, available for other purposesstatic java.nio.ByteBufferstbi_zlib_decode_malloc(java.nio.ByteBuffer buffer)ZLIB client - used by PNG, available for other purposesstatic intstbi_zlib_decode_noheader_buffer(java.nio.ByteBuffer obuffer, java.nio.ByteBuffer ibuffer)ZLIB client - used by PNG, available for other purposesstatic java.nio.ByteBufferstbi_zlib_decode_noheader_malloc(java.nio.ByteBuffer buffer)ZLIB client - used by PNG, available for other purposes
-
-
-
Field Detail
-
STBI_default
public static final int STBI_default
Default component count, used as an argument toreq_comp.- See Also:
- Constant Field Values
-
STBI_grey
public static final int STBI_grey
Component count.- See Also:
- Constant Field Values
-
STBI_grey_alpha
public static final int STBI_grey_alpha
Component count.- See Also:
- Constant Field Values
-
STBI_rgb
public static final int STBI_rgb
Component count.- See Also:
- Constant Field Values
-
STBI_rgb_alpha
public static final int STBI_rgb_alpha
Component count.- See Also:
- Constant Field Values
-
-
Method Detail
-
stbi_load
public static java.nio.ByteBuffer stbi_load(java.nio.ByteBuffer filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Loads an image from the specified file.The return value from an image loader is an
'unsigned char *'which points to the pixel data, orNULLon an allocation failure or if the image is corrupt or invalid. The pixel data consists of*yscanlines of*xpixels, with each pixel consisting of N interleaved 8-bit components; the first pixel pointed to is top-left-most in the image. There is no padding between image scanlines or between pixels, regardless of format. The number of components N is'req_comp'ifreq_compis non-zero, or*compotherwise. Ifreq_compis non-zero,*comphas the number of components that would have been output otherwise. E.g. if you setreq_compto 4, you will always get RGBA output, but you can check*compto see if it's trivially opaque because e.g. there were only 3 channels in the source image.An output image with N components has the following components interleaved in this order in each pixel:
N=#comp components 1 grey 2 grey, alpha 3 red, green, blue 4 red, green, blue, alphaIf image loading fails for any reason, the return value will be
NULL, and*x,*y,*compwill be unchanged. The functionfailure_reasoncan be queried for an extremely brief, end-user unfriendly explanation of why the load failed.Paletted PNG, BMP, GIF, and PIC images are automatically depalettized.
- Parameters:
filename- the file namex- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in imagereq_comp- 0 or 1..4 to force that many components per pixel. One of:0 1 2 3 4
-
stbi_load
public static java.nio.ByteBuffer stbi_load(java.lang.CharSequence filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Loads an image from the specified file.The return value from an image loader is an
'unsigned char *'which points to the pixel data, orNULLon an allocation failure or if the image is corrupt or invalid. The pixel data consists of*yscanlines of*xpixels, with each pixel consisting of N interleaved 8-bit components; the first pixel pointed to is top-left-most in the image. There is no padding between image scanlines or between pixels, regardless of format. The number of components N is'req_comp'ifreq_compis non-zero, or*compotherwise. Ifreq_compis non-zero,*comphas the number of components that would have been output otherwise. E.g. if you setreq_compto 4, you will always get RGBA output, but you can check*compto see if it's trivially opaque because e.g. there were only 3 channels in the source image.An output image with N components has the following components interleaved in this order in each pixel:
N=#comp components 1 grey 2 grey, alpha 3 red, green, blue 4 red, green, blue, alphaIf image loading fails for any reason, the return value will be
NULL, and*x,*y,*compwill be unchanged. The functionfailure_reasoncan be queried for an extremely brief, end-user unfriendly explanation of why the load failed.Paletted PNG, BMP, GIF, and PIC images are automatically depalettized.
- Parameters:
filename- the file namex- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in imagereq_comp- 0 or 1..4 to force that many components per pixel. One of:0 1 2 3 4
-
stbi_load_from_memory
public static java.nio.ByteBuffer stbi_load_from_memory(java.nio.ByteBuffer buffer, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)In-memory version ofload.- Parameters:
buffer- the buffer from which to load the image datax- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in imagereq_comp- 0 or 1..4 to force that many components per pixel. One of:0 1 2 3 4
-
stbi_load_from_callbacks
public static java.nio.ByteBuffer stbi_load_from_callbacks(STBIIOCallbacks clbk, long user, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)
Callback version ofload.I/O callbacks allow you to read from arbitrary sources, like packaged files or some other source. Data read from callbacks are processed through a small internal buffer (currently 128 bytes) to try to reduce overhead.
The three functions you must define are "read" (reads some bytes of data), "skip" (skips some bytes of data), "eof" (reports if the stream is at the end).
- Parameters:
clbk- anSTBIIOCallbacksstructuser- a pointer to user datax- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in imagereq_comp- 0 or 1..4 to force that many components per pixel. One of:0 1 2 3 4
-
stbi_loadf
public static java.nio.FloatBuffer stbi_loadf(java.nio.ByteBuffer filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Floating-point version ofload.- Parameters:
filename- the file namex- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in imagereq_comp- 0 or 1..4 to force that many components per pixel. One of:0 1 2 3 4
-
stbi_loadf
public static java.nio.FloatBuffer stbi_loadf(java.lang.CharSequence filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Floating-point version ofload.- Parameters:
filename- the file namex- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in imagereq_comp- 0 or 1..4 to force that many components per pixel. One of:0 1 2 3 4
-
stbi_loadf_from_memory
public static java.nio.FloatBuffer stbi_loadf_from_memory(java.nio.ByteBuffer buffer, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)Floating-point version ofload_from_memory.- Parameters:
buffer- the buffer from which to load the image datax- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in imagereq_comp- 0 or 1..4 to force that many components per pixel. One of:0 1 2 3 4
-
stbi_loadf_from_callbacks
public static java.nio.FloatBuffer stbi_loadf_from_callbacks(STBIIOCallbacks clbk, long user, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp, int req_comp)
Floating-point version ofload_from_callbacks.- Parameters:
clbk- anSTBIIOCallbacksstructuser- a pointer to user datax- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in imagereq_comp- 0 or 1..4 to force that many components per pixel. One of:0 1 2 3 4
-
stbi_hdr_to_ldr_gamma
public static void stbi_hdr_to_ldr_gamma(float gamma)
Changes the gamma value used when converting HDR images to LDR. The default value is 2.2f- Parameters:
gamma- the gamma value
-
stbi_hdr_to_ldr_scale
public static void stbi_hdr_to_ldr_scale(float scale)
Changes the scale factor used when converting HDR images to LDR. The default value is 1.0f- Parameters:
scale- the scale factor
-
stbi_ldr_to_hdr_gamma
public static void stbi_ldr_to_hdr_gamma(float gamma)
Changes the gamma value used when converting LDR images to HDR. The default value is 2.2f- Parameters:
gamma- the gamma value
-
stbi_ldr_to_hdr_scale
public static void stbi_ldr_to_hdr_scale(float scale)
Changes the gamma value used when converting LDR images to HDR. The default value is 2.2f- Parameters:
scale- the scale factor
-
stbi_is_hdr
public static int stbi_is_hdr(java.nio.ByteBuffer filename)
Checks if the specified file contains an HDR image.- Parameters:
filename- the file name- Returns:
- 1 if the image is HDR, 0 otherwise
-
stbi_is_hdr
public static int stbi_is_hdr(java.lang.CharSequence filename)
Checks if the specified file contains an HDR image.- Parameters:
filename- the file name- Returns:
- 1 if the image is HDR, 0 otherwise
-
stbi_is_hdr_from_memory
public static int stbi_is_hdr_from_memory(java.nio.ByteBuffer buffer)
In-memory version ofis_hdr.- Parameters:
buffer- the buffer from which to read the image data
-
stbi_is_hdr_from_callbacks
public static int stbi_is_hdr_from_callbacks(STBIIOCallbacks clbk, long user)
Callback version ofis_hdr.- Parameters:
clbk- anSTBIIOCallbacksstructuser- a pointer to user data
-
stbi_failure_reason
public static java.lang.String stbi_failure_reason()
Returns a brief reason for failure.
-
stbi_image_free
public static void stbi_image_free(java.nio.ByteBuffer retval_from_stbi_load)
Frees a loaded image- Parameters:
retval_from_stbi_load- an stb image
-
stbi_image_free
public static void stbi_image_free(java.nio.FloatBuffer retval_from_stbi_load)
FloatBuffer version of:image_free
-
stbi_info
public static int stbi_info(java.nio.ByteBuffer filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp)Returns image dimensions & components without fully decoding the image.- Parameters:
filename- the file namex- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in image- Returns:
- 1 on success, 0 on failure
-
stbi_info
public static int stbi_info(java.lang.CharSequence filename, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp)Returns image dimensions & components without fully decoding the image.- Parameters:
filename- the file namex- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in image- Returns:
- 1 on success, 0 on failure
-
stbi_info_from_memory
public static int stbi_info_from_memory(java.nio.ByteBuffer buffer, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp)In-memory version ofinfo.- Parameters:
buffer- the buffer from which to read the image datax- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in image
-
stbi_info_from_callbacks
public static int stbi_info_from_callbacks(STBIIOCallbacks clbk, long user, java.nio.IntBuffer x, java.nio.IntBuffer y, java.nio.IntBuffer comp)
Callback version ofinfo.- Parameters:
clbk- anSTBIIOCallbacksstructuser- a pointer to user datax- outputs the image width in pixelsy- outputs the image height in pixelscomp- outputs number of components in image
-
stbi_set_unpremultiply_on_load
public static void stbi_set_unpremultiply_on_load(int flag_true_if_should_unpremultiply)
For image formats that explicitly notate that they have premultiplied alpha, we just return the colors as stored in the file. Set this flag to force unpremultiplication. Results are undefined if the unpremultiply overflows.- Parameters:
flag_true_if_should_unpremultiply- the unpremultiply flag
-
stbi_convert_iphone_png_to_rgb
public static void stbi_convert_iphone_png_to_rgb(int flag_true_if_should_convert)
Indicate whether we should process iPhone images back to canonical format, or just pass them through "as-is".- Parameters:
flag_true_if_should_convert- the convert iPhone PNG to RGB flag
-
stbi_set_flip_vertically_on_load
public static void stbi_set_flip_vertically_on_load(int flag_true_if_should_flip)
Flips the image vertically, so the first pixel in the output array is the bottom left.- Parameters:
flag_true_if_should_flip- the flip vertically on load flag
-
stbi_zlib_decode_malloc_guesssize
public static java.nio.ByteBuffer stbi_zlib_decode_malloc_guesssize(java.nio.ByteBuffer buffer, int initial_size)ZLIB client - used by PNG, available for other purposes- Parameters:
buffer-initial_size-
-
stbi_zlib_decode_malloc_guesssize_headerflag
public static java.nio.ByteBuffer stbi_zlib_decode_malloc_guesssize_headerflag(java.nio.ByteBuffer buffer, int initial_size, int parse_header)ZLIB client - used by PNG, available for other purposes- Parameters:
buffer-initial_size-parse_header-
-
stbi_zlib_decode_malloc
public static java.nio.ByteBuffer stbi_zlib_decode_malloc(java.nio.ByteBuffer buffer)
ZLIB client - used by PNG, available for other purposes- Parameters:
buffer-
-
stbi_zlib_decode_buffer
public static int stbi_zlib_decode_buffer(java.nio.ByteBuffer obuffer, java.nio.ByteBuffer ibuffer)ZLIB client - used by PNG, available for other purposes- Parameters:
obuffer-ibuffer-
-
stbi_zlib_decode_noheader_malloc
public static java.nio.ByteBuffer stbi_zlib_decode_noheader_malloc(java.nio.ByteBuffer buffer)
ZLIB client - used by PNG, available for other purposes- Parameters:
buffer-
-
stbi_zlib_decode_noheader_buffer
public static int stbi_zlib_decode_noheader_buffer(java.nio.ByteBuffer obuffer, java.nio.ByteBuffer ibuffer)ZLIB client - used by PNG, available for other purposes- Parameters:
obuffer-ibuffer-
-
stbi_image_free
public static void stbi_image_free(float[] retval_from_stbi_load)
float[] version of:image_free
-
stbi_info
public static int stbi_info(java.nio.ByteBuffer filename, int[] x, int[] y, int[] comp)Array version of:info
-
stbi_info
public static int stbi_info(java.lang.CharSequence filename, int[] x, int[] y, int[] comp)Array version of:info
-
stbi_info_from_memory
public static int stbi_info_from_memory(java.nio.ByteBuffer buffer, int[] x, int[] y, int[] comp)Array version of:info_from_memory
-
stbi_info_from_callbacks
public static int stbi_info_from_callbacks(STBIIOCallbacks clbk, long user, int[] x, int[] y, int[] comp)
Array version of:info_from_callbacks
-
-