Module write

Utilities for writing images to files and memory.

The (single-frame) image writers come from Sean Barrett's stb.

Jon Olick's GIF and MPEG writers are used to save GIFs and MPEGs, respectively.

The Bytes type—specified below—may be any object that implements ByteReader, including strings.

(The comments that follow were adapted from stb_image_write.h.)

This is a library for writing images to files or memory.

The PNG output is not optimal; it is 20-50% larger than the file written by a decent optimizing implementation. This library is designed for source code compactness and simplicity, not optimal image file size or run-time performance.

USAGE:

There are four functions for single-frame images, one per file format:

ok = impack.write.bmp(filename, w, h, comp, data)
ok = impack.write.hdr(filename, w, h, comp, data)
ok = impack.write.png(filename, w, h, comp, data, opts)
ok = impack.write.tga(filename, w, h, comp, data)

Each function returns true to indicate success and false for failure.

(This module also provides gif and mpeg writers.)

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. data points to the first byte of the top-left-most pixel. For PNG, opts.stride_in_bytes is the distance in bytes from the first byte of a row of pixels to the first byte of the next row of pixels.

PNG creates output files with the same number of components as the input. The BMP format expands Y to RGB in the file format and does not output alpha.

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.)

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.

TGAs are written with RLE compression. (This could be made optional down the road.)

From stb's project page:

This software is dual-licensed to the public domain and under the following license: you are granted a perpetual, irrevocable license to copy, modify, publish, and distribute this file as you see fit.

Jon Olick's GIF and MPEG writers are likewise public domain.

Functions

bmp (filename[, baseDir=system.DocumentsDirectory], w, h, comp, data, opts)
Save an image as a BMP file.

Parameters:

  • filename string Name of file.
  • baseDir Directory to which the file will be added, as per system.pathForFile. (default system.DocumentsDirectory)
  • w uint Width of data, in pixels...
  • h uint ...and height.
  • comp uint Number of components per pixel.
  • data Bytes The image data, cf. the summary above.

    If data is insufficient, it will be padded with 0 bytes.

  • opts optional table Currently unused.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
bmp_to_memory (w, h, comp, data, opts)
Variant of bmp that saves the image as a stream of bytes.

Parameters:

  • w uint Width of data, in pixels...
  • h uint ...and height.
  • comp uint Number of components per pixel.
  • data Bytes As per bmp.
  • opts optional table Write options. Currently, only as_userdata is available, cf. the note for the return value. (Support for blobs is planned and would be exposed via opts.)

Returns:

    Bytes On success, data encoded as a BMP, byte-compatible with the contents of an undecoded file. This can be reloaded via image.load_from_memory.

    If opts.as_userdata was true, the data is returned as a userdata that implements ByteReader, rather than being converted to a more friendly string. Under some circumstances, this might be worth doing for performance reasons.

Or

  1. nil, meaning failure.
  2. string Error message.
gif (filename[, baseDir=system.DocumentsDirectory], w, h, frames, opts)
Saves a series of images as a GIF.

Parameters:

  • filename string Name of file.
  • baseDir Directory to which the file will be added, as per system.pathForFile. (default system.DocumentsDirectory)
  • w uint Width of each frame, in pixels...
  • h uint ...and height.
  • frames {image.GifFrame,...} GIF frames, with image data in RGBA form.

    If a given frame's image is insufficient, it will be padded with 0 bytes. An absent delay (or one with value 0) indicates that the frame has no delay.

    A has_local_palette field may also be added to a given frame. If true, the frame will have its own palette and use that in lieu of the GIF-wide one.

    Alternatively, the array may contain Bytes entries. These are interpreted like frames with said bytes as their image field, without delay or local palette.

  • opts optional table

    Save options, which include:

    • append: NYI As with mpeg.
    • repeat: Number of times the animation should repeat. By default, 0 (repeat forever).
    • palette_depth: Palette depth d, from 1 to 8 (the default); the palette will have 2d - 1 colors.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
gif_to_memory (w, h, frames, opts)
Variant of gif that saves the images as a stream of bytes.

Parameters:

Returns:

    Bytes On success, data encoded as a GIF, byte-compatible with the contents of an undecoded file. This can be reloaded via image.xload_from_memory. (At the moment, this is always a string.)

Or

  1. nil, meaning failure.
  2. string Error message.
hdr (filename[, baseDir=system.DocumentsDirectory], w, h, comp, data, opts)
Saves an image as a Radiance RGBE HDR file.

Parameters:

  • filename string Name of file.
  • baseDir Directory to which the file will be added, as per system.pathForFile. (default system.DocumentsDirectory)
  • w uint Width of data, in pixels...
  • h uint ...and height.
  • comp uint Number of components per pixel.
  • data Bytes As per bmp, with the caveat that the memory consist of single-precision floats, rather than bytes, per component.
  • opts optional table Currently unused.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
hdr_to_memory (w, h, comp, data, opts)
Variant of hdr that saves the image as a stream of bytes.

This can be reloaded via image.loadf_from_memory.

Parameters:

  • w uint Width of data, in pixels...
  • h uint ...and height.
  • comp uint Number of components per pixel
  • data Bytes As per hdr.
  • opts optional table As per bmp_to_memory.

Returns:

    Bytes On success, as per bmp_to_memory, but in HDR form.

Or

  1. nil, meaning failure.
  2. string Error message.
mpeg (filename[, baseDir=system.DocumentsDirectory], w, h, frames, opts)
Saves a series of images as an MPEG.

Parameters:

  • filename string Name of file.
  • baseDir Directory to which the file will be added, as per system.pathForFile. (default system.DocumentsDirectory)
  • w uint Width of each frame, in pixels...
  • h uint ...and height.
  • frames {Bytes,...} MPEG frames, in RGBA form. If a given frame is insufficient, it will be padded with 0 bytes.
  • opts optional table

    Save options, which include:

    • append: (WIP) If true and the MPEG already exists, the video is extended with the new frames. The default is to make a new MPEG.

      When appending, w and h are ignored; the first frame's dimensions are used instead.
    • fps: The video's frames-per-second rate (default 30).

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
mpeg (filename[, baseDir=system.DocumentsDirectory], frames, opts)
Alternate overload. This is tailored toward appending frames, where the frame dimensions are ignored.

Parameters:

  • filename string Name of file.
  • baseDir As per the other overload. (default system.DocumentsDirectory)
  • frames {Bytes,...} As per the other overload.
  • opts optional table As per the other overload.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
mpeg_to_memory (w, h, frames, opts)
Variant of mpeg that saves the images as a stream of bytes.

Parameters:

  • w uint Width of each frame, in pixels...
  • h uint ...and height.
  • frames {Bytes,...} As per mpeg.
  • opts optional table As per mpeg.

Returns:

    Bytes On success, data encoded as an MPEG, byte-compatible with the contents of an undecoded file. (At the moment, this is always a string.)

Or

  1. nil, meaning failure.
  2. string Error message.
png (filename[, baseDir=system.DocumentsDirectory], w, h, comp, data, opts)
Saves an image as a PNG file.

Parameters:

  • filename string Name of file.
  • baseDir Directory to which the file will be added, as per system.pathForFile. (default system.DocumentsDirectory)
  • w uint Width of data, in pixels...
  • h uint ...and height.
  • comp uint Number of components per pixel
  • data Bytes As per bmp.
  • opts optional table Write options.

    Currently, only stride is available. If present (and non-0), this will be the stride in bytes, as described in the summary above.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
png_to_memory (w, h, comp, data, opts)
Variant of png that saves the image as a stream of bytes.

Parameters:

  • w uint Width of data, in pixels...
  • h uint ...and height.
  • comp uint Number of components per pixel
  • data Bytes As per png.
  • opts optional table As per the combined choices in bmp_to_memory and png.

Returns:

    Bytes On success, as per bmp_to_memory, but in PNG form.

Or

  1. nil, meaning failure.
  2. string Error message.
tga (filename[, baseDir=system.DocumentsDirectory], w, h, comp, data, opts)
Saves an image as a Truevision TGA file.

Parameters:

  • filename string Name of file.
  • baseDir Directory to which the file will be added, as per system.pathForFile. (default system.DocumentsDirectory)
  • w uint Width of data, in pixels...
  • h uint ...and height.
  • comp uint Number of components per pixel
  • data Bytes As per bmp.
  • opts optional table Currently unused.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
tga_to_memory (w, h, comp, data, opts)
Variant of tga that saves the image as a stream of bytes.

Parameters:

  • w uint Width of data, in pixels...
  • h uint ...and height.
  • comp uint Number of components per pixel
  • data Bytes As per tga.
  • opts optional table As per bmp_to_memory.

Returns:

    Bytes On success, as per bmp_to_memory, but in TGA form.

Or

  1. nil, meaning failure.
  2. string Error message.
generated by LDoc 1.4.6 Last updated 2018-09-03 18:10:24