Class SpotImage

Wrapper over Spot's image class.

Spot images implement the ByteReader protocol. By default they send RGBA image data, but the raw floating-point data may be used instead, cf. SpotImage:set_reader_mode.

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

NOTE Spot image support is still experimental.

(The comments that follow were adapted from Spot's README.)

  • Spot is a compact and embeddable pixel / image library.
  • Spot supports both RGBA / HSLA pixel types.
  • Spot provides both pixel and image algebra for pixel / image manipulation.
  • Spot loads WEBP, JPG, progressive JPG, PNG, TGA, DDS DXT1/2/3/4/5, BMP, PSD, GIF, PVR2/3 (ETC1/PVRTC), KTX (ETC1/PVRTC), PKM (ETC1), HDR, PIC, PNM (PPM/PGM), CRN, PUG, FLIF, CCZ, EXR and vectorial SVG files.
  • Spot saves WEBP, JPG, PNG, TGA, BMP, DDS, PVR3 (PVRTC), KTX (ETC1), PKM (ETC1), CCZ and PUG files.

(N.B. ETC and FLIF are disabled on iOS until some issues are resolved.)

Licenses

  • spot (ZLIB license).
  • crn2dds by r-lyeh, SpartanJ and Evan Parker (Public Domain).
  • crnlib, by Rich Geldreich (ZLIB license).
  • DDS writer by Jonathan Dummer (Public Domain).
  • etc1utils by Google Inc (Apache 2.0 license).
  • etcpak by Bartosz Taudul (BSD-3 license).
  • flif by Jon Sneyers and Pieter Wuille (Apache 2.0 license).
  • jpge by Rich Geldreich (Public Domain).
  • libwebp by Google Inc (BSD license).
  • lodepng by Lode Vandevenne (ZLIB license).
  • nanosvg by Mikko Mononen (ZLIB license).
  • pngrim alpha bleeding algorithm by F-Genesis (Public Domain).
  • pug (Public Domain).
  • pvrtccompressor by Jeffrey Lim (BSD-3 license).
  • rg_etc1 by Rich Geldreich (ZLIB license).
  • soil2 by Martin Lucas Golini and Jonathan Dummer (Public Domain).
  • stb_image by Sean Barrett (Public Domain).
  • tinyexr by Syoyo Fujita (BSD3 license).
  • unifont (ZLIB license).

Metamethods

SpotImage:__add ()
Metamethod.

The right-hand argument must be a SpotColor, and is added to each pixel.

Any errors are propagated.

Returns:

    SpotImage The post-addition image.
SpotImage:__div ()
Metamethod.

The right-hand argument must be a SpotColor, and each pixel is divided by it.

Any errors are propagated.

Returns:

    SpotImage The post-division image.
SpotImage:__mul ()
Metamethod.

The right-hand argument must be a SpotColor, and each pixel is multiplied by it.

Any errors are propagated.

Returns:

    SpotImage The post-multiplication image.
SpotImage:__sub ()
Metamethod.

The right-hand argument must be a SpotColor, and is subtracted from each pixel.

Any errors are propagated.

Returns:

    SpotImage The post-subtraction image.

Methods

SpotImage:add_mutate (color)
Modify this image by adding a color to each pixel.

Parameters:

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:blank ()
Create a new image with this image's pixels run through a blank filter.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:bleed ()
Create a new image with this image's pixels run through a bleed filter.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:checkered ()
Create a new image with this image's pixels run through a checker filter.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:clamp ()
Create a new image with all pixels' color components clamped to [0, 1].

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:copy (x, y, w, h)
Copy a region of this image, given an offset and optional size.

Parameters:

  • x uint Horizontal offset of region, ≥ 1...
  • y uint ...and vertical offset, ≥ 1.
  • w optional uint Width of new image... (If absent, the rest of the width, given x.)
  • h optional uint ...and height. (If absent, the rest of the height, given y.)

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:crop (l, r, t, b)
Copy a region of this image, given the edge offsets.

Parameters:

  • l uint Left-hand edge, ≥ 1...
  • r uint ...and right-hand edge, between l and the width, inclusive.
  • t uint Top edge, ≥ 1...
  • b uint ...and bottom edge, between t and the height, inclusive.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:div_mutate (color)
Modify this image by dividing each pixel by a color.

Parameters:

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error mesage.
SpotImage:encode (format, opts)
Save this image out to memory, in the requested format.

Parameters:

  • format string One of "PNG", "JPG", "PUG", "WEBP", "KTX", "PVR", "CCZ", or "PKM", corresponding to the encoding format.
  • opts optional table

    Encoding options, which include:

    • channels: Number of channels in the output, an integer from 1 to 4 (by default, 4). At the moment, this only applies to the PNG format.
    • quality: A value between 1 and 100 (by default, 90) that describes the requested encoding quality. This is available to all formats except PNG.

Returns:

    string On success, the encoded image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:flip_h ()
Create a new image with all this image's pixels' rows flipped.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:flip_w ()
Create a new image with all this image's pixels' columns flipped.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:get (x)
Get a color from the first row of this image.

Parameters:

  • x uint Horizontal offset, from 1 to the width.

Returns:

    SpotColor On success, a copy of the color.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:get (x, y)
Get a color from this image.

Parameters:

  • x uint Horizontal offset, from 1 to the width...
  • y uint ...and vertical offset, from 1 to the height.

Returns:

    SpotColor On success, a copy of the color.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:get (x, y, z)
Get a color from this image, allowing for depth.

Parameters:

  • x uint Horizontal offset, from 1 to the width...
  • y uint ...vertical offset, from 1 to the height...
  • z uint ...and depth-wise offset, from 1 to the depth.

Returns:

    SpotColor On success, a copy of the color.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:getf (x)
Get a color from the first row of this image, using normalized coordinates.

Parameters:

  • x number Horizontal offset, in [0, 1].

Returns:

    SpotColor On success, a copy of the color.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:getf (x, y)
Get a color from this image, using normalized coordinates.

Parameters:

  • x uint Horizontal offset, in [0, 1]...
  • y uint ...and vertical offset, ditto.

Returns:

    SpotColor On success, a copy of the color.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:getf (x, y, z)
Get a color from this image, using normalized coordinates and allowing for depth.

Parameters:

  • x uint Horizontal offset, in [0, 1]...
  • y uint ...and vertical offset, ditto...
  • z number ...and depth-wise offset, ditto.

Returns:

    SpotColor On success, a copy of the color.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:glow ()
Create a new image with this image's pixels run through a glow filter.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:load ([baseDir=system.ResourceDirectory], filename)
Populate this image from an image file.

Parameters:

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

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:load (params)
(WIP) Alternate method overload.

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.
SpotImage:load_from_memory (bytes)
Populate this image from an in-memory image.

Parameters:

  • bytes Bytes Undecoded image contents.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:load_hdr (filename[, baseDir=system.ResourceDirectory])
Populate this image from an HDR image file.

Parameters:

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

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:load_hdr (params)
(WIP) Alternate method overload.

Parameters:

Returns:

    As per the other overload.
SpotImage:load_hdr_from_memory (bytes)
Populate this image from an in-memory HDR image.

Parameters:

  • bytes Bytes Undecoded image contents.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:loaded ()
Did the most recent load operation succeed?

Returns:

    boolean Load was successful?
SpotImage:mul_mutate (color)
Modify this image by multiplying each pixel by a color.

Parameters:

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error mesage.
SpotImage:paste (x, y, image)
Paste an image (or part of one, if too large) into this image at an offset.

Parameters:

  • x uint Horizontal offset , ≥ 1...
  • y uint ...and vertical offset, ≥ 1.
  • image SpotImage Image to add.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:premultiply ()
(WIP) Create a new image with alpha premultiplied into all this image's pixel colors.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.

See also:

SpotImage:premultiply_mutate ()
(WIP) Modify this image by premultiplying alpha into all pixels.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error mesage.

See also:

SpotImage:rgba ()
Get the image contents in RGBA byte form.

Returns:

    string The image as bytes.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:rotate_left ()
Create a new image with this image's contents rotated left 90°.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:rotate_right ()
Create a new image with this image's contents rotated right 90°.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:save (filename[, baseDir=system.DocumentsDirectory], opts)
Save this image to a file.

Parameters:

  • filename string Name of file.
  • baseDir (WIP) Directory in which to save, as per system.pathForFile. (default system.DocumentsDirectory)
  • opts optional table Save options.

    In addition to the choices available in SpotImage:encode, a format may be provided with any of "BMP", "DDS", "TGA", "PNG", "JPG", "PUG", "WEBP", "KTX", "PVR", "CCZ", or "PKM", to explicitly save in the given format (by default, the method expects one of these as filename's extension).

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:set (x, color)
Set a color in the first row of this image.

Parameters:

  • x uint Horizontal offset, from 1 to the width.
  • color SpotColor Color to assign.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:set (x, y, color)
Set a color in this image.

Parameters:

  • x uint Horizontal offset, from 1 to the width...
  • y uint ...and vertical offset, from 1 to the height.
  • color SpotColor Color to assign.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:set (x, y, z, color)
Set a color in this image, allowing for depth.

Parameters:

  • x uint Horizontal offset, from 1 to the width...
  • y uint ...vertical offset, from 1 to the height.
  • z uint ...and depth-wise offset, from 1 to the depth.
  • color SpotColor Color to assign.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:setf (x, color)
Set a color in the first row of this image, using normalized coordinates.

Parameters:

  • x number Horizontal offset, in [0, 1].
  • color SpotColor Color to assign.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:setf (x, y, color)
Set a color in this image, using normalized coordinates.

Parameters:

  • x number Horizontal offset, in [0, 1]...
  • y number ...and vertical offset, ditto.
  • color SpotColor Color to assign.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:setf (x, y, z, color)
Set a color in this image, using normalized coordinates and allowing for depth.

Parameters:

  • x number Horizontal offset, in [0, 1]...
  • y number ...and vertical offset, ditto.
  • z number ...and depth-wise offset, ditto.
  • color SpotColor Color to assign.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error message.
SpotImage:set_reader_mode (mode)
Set the mode used when bytes are read from the image, cf. the summary above.

Parameters:

  • mode If this is "raw", the image will expose its bytes directly, in floating-point form.

    Otherwise, something like result = image:rgba() is performed, with result used instead. This is the default behavior.

See also:

SpotImage:sub_mutate (color)
Modify this image by subtracting a color from each pixel.

Parameters:

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error mesage.
SpotImage:to_hsla ()
Create a clone of this image with components in HSLA form.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:to_rbga ()
Create a clone of this image with components in RGBA form.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.
SpotImage:unpremultiply ()
(WIP) Create a new image with alpha un-premultiplied from all this image's pixel colors.

Returns:

    SpotImage New image.

Or

  1. nil, meaning failure.
  2. string Error message.

See also:

SpotImage:unpremultiply_mutate ()
(WIP) Modify this image by un-premultiplying alpha from all pixels.

Returns:

    true, indicating success.

Or

  1. false, meaning failure.
  2. string Error mesage.

See also:

generated by LDoc 1.4.6 Last updated 2018-09-03 18:10:24