Package org.lwjgl.stb

Class STBImageWrite

java.lang.Object
org.lwjgl.stb.STBImageWrite

public class STBImageWrite extends 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 Details

    • stbi_write_png_compression_level

      public static final IntBuffer stbi_write_png_compression_level
      Returns the address of the global variable stbi_write_png_compression_level.
    • stbi_write_force_png_filter

      public static final IntBuffer stbi_write_force_png_filter
      Returns the address of the global variable stbi_write_force_png_filter.
    • stbi_zlib_compress

      public static final PointerBuffer 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

      public static final IntBuffer stbi_write_tga_with_rle
      Returns the address of the global variable stbi_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 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
    • 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 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(ByteBuffer 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 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
    • 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 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(ByteBuffer 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 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
    • 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 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(ByteBuffer 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 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
    • 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 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(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 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
    • 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 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, 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, 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, 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, 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, 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
    • nstbi_write_hdr

      public static int nstbi_write_hdr(long filename, int w, int h, int comp, float[] data)
    • stbi_write_hdr

      public static boolean stbi_write_hdr(ByteBuffer filename, int w, int h, int comp, float[] data)
      Array version of: write_hdr
    • stbi_write_hdr

      public static boolean stbi_write_hdr(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)
    • 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