Module image

Utilities for loading images.

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

Animated GIF support builds upon STB, using urraka's xload.

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

Functions that begin with (WIP) describe work in progress. These features are not considered stable, but give a reasonable idea of what to expect.

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

QUICK NOTES:

Primarily of interest to game developers and other people who can avoid problematic images and only need the trivial interface

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)

(WIP) The formats listed for SpotImage are available as well.

Animated GIF (via xload)

  • decode from memory
  • SIMD acceleration on x86/x64 (SSE2) and ARM (NEON)

DOCUMENTATION

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

local data, x, y, comp = impack.image.load(filename, 0)
-- ... process data if not nil ...
-- ... x = width, y = height, comp = # 8-bit components per pixel ...
-- ... replace '0' with '1'..'4' to force that many components per pixel
-- ... but comp will always be the number that it would have been if you said 0
data = nil -- or allow to go out of scope

Standard parameters and results:

x        -- image width in pixels
y        -- image height in pixels
comp     -- # of image components in image file
req_comp -- if non-zero, # of image components requested in result

The return value from an image loader is a string containing the pixel data, or nil on an allocation failure or if the image is corrupt or invalid. The pixel data consists of y scanlines of x pixels, 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 if req_comp is non-zero (and present), or comp otherwise. If req_comp is non-zero, comp has the number of components that would have been output otherwise. E.g. if you set req_comp to 4, you will always get RGBA output, but you can check comp to 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, alpha

If image loading fails for any reason, the return value will be nil, along with an extremely brief explanation of why the load failed.

Paletted PNG, BMP, GIF, and PIC images are automatically depalettized.

Philosophy:

stb libraries are designed with the following priorities:

1. easy to use
2. easy to maintain
3. good performance

Sometimes I let "good performance" creep up in priority over "easy to maintain", and for best performance I may provide less-easy-to-use APIs that give higher performance, in addition to the easy to use ones. Nevertheless, it's important to keep in mind that from the standpoint of you, a client of this library, all you care about is #1 and #3, and stb libraries do not emphasize #3 above all.

Some secondary priorities arise directly from the first two, some of which make more explicit reasons why performance can't be emphasized.

  • Portable ("ease of use")
  • Small footprint ("easy to maintain")
  • No dependencies ("ease of use")

SIMD support:

The JPEG decoder will try to automatically use SIMD kernels on x86 when supported by the compiler. SSE2 will automatically be used when available based on a run-time test; if not, the generic C versions are used as a fall-back. Likewise, on ARM targets, NEON will be used when available.

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:

impack.image.hdr_to_ldr_gamma(2.2)
impack.image.hdr_to_ldr_scale(1.0)

(Note, do not use inverse constants; the appropriate inversion will be applied internally.)

Additionally, there is a new, parallel interface for loading files as (linear) floats to preserve the full dynamic range:

local data, x, y, n = impack.image.loadf(filename)

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:

impack.image.ldr_to_hdr_scale(1.0)
impack.image.ldr_to_hdr_gamma(2.2)

Finally, given a filename 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:

impack.image.is_hdr(filename)

iPhone PNG support:

By default we convert iPhone-formatted PNGs back to RGB, even though they are internally encoded differently.

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.

Functions

hdr_to_ldr_gamma (gamma)
Assign the (global) high → low-dynamic-range gamma mapping.

Parameters:

  • gamma number Gamma mapping.

See also:

hdr_to_ldr_scale (scale)
Assign the (global) high → low-dynamic-range scale factor.

Parameters:

  • scale number Scale factor.

See also:

info (filename[, baseDir=system.ResourceDirectory])
Get image dimensions and component count without fully decoding.

Parameters:

  • filename string Name of file to query.
  • baseDir Directory to search, as per system.pathForFile. (default system.ResourceDirectory)

Returns:

  1. true, indicating success.
  2. uint Width of image data...
  3. uint ...and height.
  4. uint Number of components per pixel.

Or

    false, indicating failure.
info (params)
(WIP) Alternate overload of info.

Parameters:

  • params table Info parameters. This must include filename and may have a baseDir field, with meanings as in the other overload.

    If an is_absolute is present and true, filename is interpreted as an absolute path (any baseDir is ignored). On non-desktop platforms, this raises an error.

Returns:

    As per the other overload.
info_from_memory (image)
Memory-based variant of info.

Parameters:

  • image Bytes Undecoded image contents.

Returns:

  1. true, indicating success.
  2. uint Width of image data...
  3. uint ...and height.
  4. uint Number of components per pixel.

Or

    false, indicating failure.
is_hdr (filename[, baseDir=system.ResourceDirectory])
Check whether a file contains an HDR image.

Parameters:

  • filename string Name of file to query.
  • baseDir Directory to search, as per system.pathForFile. (default system.ResourceDirectory)

Returns:

    boolean Image contents are HDR data?
is_hdr (params)
(WIP) Alternate overload of is_hdr.

Parameters:

  • params table Query parameters. See the table overload of info for details.

Returns:

    As per the other overload.
is_hdr_from_memory (image)
Memory-based variant of is_hdr.

Parameters:

  • image Bytes Undecoded image contents.

Returns:

    boolean Image contents are HDR data?
ldr_to_hdr_gamma (gamma)
Assign the (global) low → high-dynamic-range gamma mapping.

Parameters:

  • gamma number Gamma mapping.

See also:

ldr_to_hdr_scale (scale)
Assign the (global) low → high-dynamic-range scale factor.

Parameters:

  • scale number Scale factor.

See also:

load (filename[, baseDir=system.ResourceDirectory], opts)
Loads an image into one-byte-per-component form. Refer to the summary above for further details.

Parameters:

  • filename string Name of file to load.
  • baseDir Directory to search, as per system.pathForFile. (default system.ResourceDirectory)
  • opts optional table

    Load options, which include:

    • as_userdata Affects how the image data is returned.
    • req_comp When present (and non-0), it should be an integer between 1 and 4, the loaded data will have as many components (adding or removing channels as needed).
    • is_absolute: (WIP) If true, filename is interpreted as being an absolute path (any baseDir is ignored). On non-desktop platforms, this raises an error.
    • blob: (WIP) If this is a blob and the decoded image data will fit, it is populated with said data. (TODO errors, etc.)
    • bypass_filtering: (WIP) WebP-specific: bypass filtering during decoding.
    • no_fancy_upsampling: (WIP) WebP-specific: forgo any fancy upsampling during decoding.
    • premultiply: (WIP) If true, alpha is premultiplied in the case of 4-component data.
    • x: (WIP) Horizontal offset into blob, if available...
    • y: (WIP) ...and vertical offset.

Returns:

  1. Bytes Image data.

    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. (N.B. This feature is in flux at the moment and subject to change.)

  2. uint Width of image data...
  3. uint ...and height.
  4. uint Number of (actual, not requested) components per pixel.

Or

  1. nil, indicating failure.
  2. string Error message.
load_from_memory (image, opts)
Memory-based variant of load.

Parameters:

  • image Bytes Undecoded image contents.
  • opts optional table As per load

Returns:

  1. Bytes Image data, as per load.
  2. uint Width of image data...
  3. uint ...and height.
  4. uint Number of (actual, not requested) components per pixel.

Or

  1. nil, indicating failure.
  2. string Error message.
loadf (filename[, baseDir=system.ResourceDirectory], opts)
Loads an image into floating-point form. Refer to the summary above for further details.

Parameters:

Returns:

  1. Bytes Image data, as per load.
  2. uint Width of image data...
  3. uint ...and height.
  4. uint Number of (actual, not requested) components per pixel.

Or

  1. nil, indicating failure.
  2. string Error message.
loadf_from_memory (image, opts)
Memory-based variant of loadf.

Parameters:

  • image Bytes Undecoded image contents.
  • opts optional table As per loadf.

Returns:

  1. Bytes data Image data, as per loadf.
  2. uint Width of image data...
  3. uint ...and height.
  4. uint Number of (actual, not requested) components per pixel.

Or

  1. nil, indicating failure.
  2. string Error message.
load_image_object (name[, baseDir=system.ResourceDirectory])
(WIP) Load a Spot image from a file.

Parameters:

  • name string Name of file to load.
  • baseDir Directory to search, as per system.pathForFile. (default system.ResourceDirectory)

Returns:

    SpotImage On success, the new Spot image, cf. SpotImage.

Or

  1. nil, indicating an error.
  2. string Error message.
load_image_object (params)
(WIP) Alternate overload of load_image_object.

Parameters:

  • params table Load parameters. See the table overload of info for details.

Returns:

    As per the other overload.
load_image_object_from_memory (image)
(WIP) Load a Spot image from memory.

Parameters:

  • image Bytes Undecoded image contents.

Returns:

    SpotImage On success, the new Spot image, cf. SpotImage.

Or

  1. nil, indicating an error.
  2. string Error message.
new_color_hsla ([h=0[, s=0[, l=0[, a=1]]]])
(WIP) Create a new Spot color in HSLA form.

Parameters:

  • h number Hue component, typically between 0 and, inclusive... (default 0)
  • s number ...saturation component, ditto... (default 0)
  • l number ...lightness, ditto... (default 0)
  • a number ...and alpha, ditto. (default 1)

Returns:

    SpotColor On success, the new Spot color, cf. SpotColor.

Or

  1. nil, indicating an error.
  2. string Error message.
new_color_rgba ([r=0[, g=0[, b=0[, a=0]]]])
(WIP) Create a new Spot color in RGBA form.

Parameters:

  • r number Red component, between 0 and 255, inclusive... (default 0)
  • g number ...green component, ditto... (default 0)
  • b number ...blue, ditto... (default 0)
  • a number ...and alpha, ditto. (default 0)

Returns:

    SpotColor On success, the new Spot color, cf. SpotColor.

Or

  1. nil, indicating an error.
  2. string Error message.
new_image_object (w, h, d, filler)
(WIP) Create a new empty Spot image.

Parameters:

  • w uint Image width...
  • h uint ...height...
  • d uint ...and depth.
  • filler optional SpotColor Optional initial fill color.

Returns:

    SpotImage On success, the new Spot image, cf. SpotImage.

Or

  1. nil, indicating an error.
  2. string Error message.
xload (filename[, baseDir=system.ResourceDirectory])
Given a GIF, loads its frames (image data, delay to next frame) into an array. All frames are loaded as RGBA with the same width and height.

A single image buffer (with no delay info) is returned for non-GIF files and for GIFs that have one frame.

Parameters:

  • filename string Name of file to load.
  • baseDir Directory to search, as per system.pathForFile. (default system.ResourceDirectory)

Returns:

  1. {GifFrame,...} frames, where a frame is a table with two keys, image containing a string and delay a uint.
  2. uint Width common to all frames...
  3. uint ...and height.

Or

  1. string Image data, in the case there is only one frame or filename was not a GIF.
  2. uint Image width...
  3. uint ...and height.
  4. uint bpp Always 4.

Or

  1. nil, indicating failure.
  2. string Error message.
xload (params)
(WIP) Alternate overload of xload.

Parameters:

  • params table Load parameters. See the table overload of info for details.

Returns:

    As per the other overload.
xload_from_memory (image)
Variant of xload that loads from memory.

Parameters:

  • image Bytes Undecoded image contents

Returns:

    As per xload.

Tables

GifFrame
Represents a single frame in a GIF animation.

Fields:

  • image Bytes Frame data.
  • delay uint Delay, in milliseconds, for frame.
generated by LDoc 1.4.6 Last updated 2018-09-03 18:10:24