Package org.lwjgl.stb

Class 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 is w pixels wide and h pixels tall. The *data pointer points to the first byte of the top-left-most pixel.

    • Field Detail

      • stbi_write_png_compression_level

        Returns the address of the global variable stbi_write_png_compression_level.

      • stbi_write_force_png_filter

        Returns the address of the global variable stbi_write_force_png_filter.

      • stbi_zlib_compress

        Returns the address of the global variable stbi_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 variable stbi_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 path
        w - the image width, in pixels
        h - the image height, in pixels
        comp - the number of channels in each pixel
        data - the image data
        stride_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 path
        w - the image width, in pixels
        h - the image height, in pixels
        comp - the number of channels in each pixel
        data - 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 with write_tga_with_rle.

        Parameters:
        filename - the image file path
        w - the image width, in pixels
        h - the image height, in pixels
        comp - the number of channels in each pixel
        data - 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 path
        w - the image width, in pixels
        h - the image height, in pixels
        comp - the number of channels in each pixel
        data - 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 path
        w - the image width, in pixels
        h - the image height, in pixels
        comp - the number of channels in each pixel
        data - the image data
        quality - 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 of write_png.
        Parameters:
        func - the callback function
        context - a context that will be passed to func
        w - the image width, in pixels
        h - the image height, in pixels
        comp - the number of channels in each pixel
        data - the image data
        stride_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 of write_bmp.
        Parameters:
        func - the callback function
        context - a context that will be passed to func
        w - the image width, in pixels
        h - the image height, in pixels
        comp - the number of channels in each pixel
        data - 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 of write_tga.
        Parameters:
        func - the callback function
        context - a context that will be passed to func
        w - the image width, in pixels
        h - the image height, in pixels
        comp - the number of channels in each pixel
        data - 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 of write_hdr.
        Parameters:
        func - the callback function
        context - a context that will be passed to func
        w - the image width, in pixels
        h - the image height, in pixels
        comp - the number of channels in each pixel
        data - 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 of write_jpg.
        Parameters:
        func - the callback function
        context - a context that will be passed to func
        w - the image width, in pixels
        h - the image height, in pixels
        comp - the number of channels in each pixel
        data - the image data
        quality - 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

      • 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

      • 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