Load a dds (Direct Draw Surface) file from disk. This format is different from the other supported formats because it is a package of image files with associated metadata. The first return value is the content of the dds file, which can consist of more than one image. The second is a string indicating the kind of file that was opened, of which there are 3 possibilities.
If the kind is SIMPLE, then the dds file was a simple 2D texture so the content is a table containing the mipmaps (in descending order of size). If the kind is CUBE, then the table contains 6 sides of this cube, e.g. in the field px is the positive x side, nx is the negative x side, and similarly for the y and z axes. Such textures are typically used for 360 degree panoramas. Finally, if the kind is VOLUME, then this is a 3D texture. The content is a table of volume mipmaps, each of which is a table containing all the single images that comprise the volume, one slice at a time.
BC1-5 are supported, as well as the basic raw formats.
Save a cubemap dds (Direct Draw Surface) file to disk. This behaves much like dds_save_simple() except all sides of the cube must be supplied.
Save a simple dds (Direct Draw Surface) file to disk. This will save a 2D texture, there are 2 other functions for saving cube maps and volume maps. The available formats are R5G6B5, R8G8B8, A8R8G8B8, A2R10G10B10, A1R5G5B5, R8, R16, G16R16, A8R8, A4R4, A16R16, R3G3B2, A4R4G4B4, BC1, BC2, BC3, BC4, BC5, R16F, G16R16F R16G16B16A16F, R32F, G32FR32F, and R32G32B32A32F. You must give an array of mipmaps to this function. If you only want to save the top mipmap then use a single element array. You can also use the mipmaps() function to generate mipmaps for you.
Note that the supplied images must have the right number of channels/alpha for the chosen format. Don't forget that BC1 has an alpha channel. To add a 100% alpha channel to an RGB image, use the img.xyzF swizzle.
Save a volume dds (Direct Draw Surface) file to disk. This behaves much like dds_save_simple() except each mipmap is a table of slices (images), thus the input is an array of arrays of images. If you do not want images, give a singleton array containing the array of the slices in your volume. You can also use volume_mipmaps() to generate the array of arrays from an array of images.
Open a gif file. While the regular open() call supports gifs, this function additionally supports reading the various frames from animated gifs. Returned are 3 values, the first is the number of loops (0 to 56636 inclusive, 0 meaning infinite looping). The second is an array of images, one for each frame, and the final value is a table of delays (in seconds).
Save a gif file. While gifs can be saved with the save() method of an image, this call allows saving many frames to create an animated gif. Specifying 0 loops means infinite looping. The images must all be the same size and have 3 channels (with optional alpha). Giving a single delay means the same delay is used for all frames, or an array can be used to give a different delay for each frame. In either case, the delays are in seconds, must be given in multiples of 0.01, and values less than 0.02 are not well-supported by browsers..
Load an image file from disk. The file extension is used to determine the format. The extension 'sfi' is a special raw format. This can be used to save and restore images in LuaImg's internal representation, which is 4 bytes per pixel per channel. All other formats are loaded with libfreeimage.
There are 6 functions for converting between the various combinations of RGB, HSV, and HSL. HSV is distinguished from HSL because in HSL, 100% brightness is white (i.e. it desaturates), whereas in HSV it retains saturation.
Return a vector value of the given dimensionality, all of whose elements are the given value.
Compute the cross product of the given vectors.
Compute the dot product of the given vectors.
Invert a quaternion.
Normalise the vector or quaternion (return a value that has length 1 but is otherwise equivalent).
Return the number of seconds since reboot. Useful for benchmarking.
Interpolate between two quaternions.
Convert to a vector value, the number of arguments determines the number of dimensions of the vector.
Convert to a vector4 value. The arguments can be either numbers or other vectors of any size as long as the total number of elements is 2. There are similar functions vec2 and vec3 for creating vectors of other sizes.
Generate a separated Gaussian convolution kernel. This is an nx1 image containing that row of Pascal's triangle, normalised so it all sums to 1.
Interpolate between two colours / images. T can be number, vector2/3/4, or Image. If lerping images, they must be compatible.
Create a new image of the specificed size, with the specified number of colour channels. If channels<4, one can also add an alpha channel. Alpha channels behave differently than regular channels. The init parameter can be either a single colour (for a solid image), an array of colours of size W*H, or a function that provides the colour at each pixel.
Takes an image, and creates an array of scaled versions of the image, where each successive image is half the size of the previous one in both dimensions. This is mainly useful for the dds_save family of functions. The available filters are the same as for the image:scale() method.
Takes a volume (an array of images), and creates an array of scaled versions of the volume, where each successive volume is half the size of the previous one in all 3 dimensions. This is mainly useful for the dds_save_volume function. The volume must have power of 2 size in all dimensions, and is filtered with a BOX filter.
Create a new image containing the rendered line of text. The image is automatically sized to fit the text. Bitmap or scalable fonts can be used, and are specified as a path e.g. to the ttf or the pcf.gz file. The font size can be chosen (width and height). Optionally, a 2x2 matrix can be supplied, which defines an affine transformation on the rendered text (rotation, scale, skew). If given, this is applied after the scaling due to the font size. The returned grey scale image has the text rendered, antialiased, in white, on a black background. Combine this call with other features of luaimg to achieve drop shadows, colour, etc.
Similar to the text() function but renders a single character (codepoint) of text (provided as a UTF8 string). The size of the returned image includes spacing around the letter that is appropriate for collating this character with others from the same font and size to form paragraphs of text. The text() call always removes blank pixels around the text so is not suitable for this purpose. Kerning information is not provided.
A 2d rectangular grid of pixels. Pixels are represented in single precision floating point. The image can have 1,2,3, or 4 colour channels. If an image has less than 4 channels, it is allowed to additionally have an alpha channel (alpha channels have special behaviours when composing images).
Images can be combined by arithmetic (+,-,*,/,^). The .. operator combines images according to alpha blending (i.e. regular blend mode in Photoshop/Gimp). Other blend modes are available via the mathematical operators. You can therefore mask images using the multiplication operator, add using the add operator, etc (see examples above).
Individual pixel values of an image can be accessed using the function call syntax, e.g. img(10,20). Other functionality is exposed via specific methods on images. Images can be swizzled to extract specific channels. If a swizzle's last character is a capital letter, this creates an alpha channel. E.g. img.yX will yield a greyscale image with alpha channel. The value channel is the old green channel and the alpha channel is the old red channel. The two special swizzle characters f (full) and e (empty) create a channel containing 1 or 0, respectively.
The number of channels in the image (including alpha).
The number of channels in the image (not including alpha).
Whether or not the last channel is an alpha channel.
The number of pixels in a column of the image.
The width x height.
The width and height as a single value.
The number of pixels in a row of the image.
The returned image is the absolute value of this image, i.e. negative pixel channel values are made positive.
The returned image's pixels are forced within the given range (inclusive).
Create a new image identical to this one. This is useful if you then modify it with set, drawImage, etc.
Perform a convolution operation on this image, using the given kernel, to yield a new image. The kernel must have a single channel and have an odd width and height. The wrapx and wrapy control the behaviour at the edge of the image and default to false. When not wrapping, the effect is to 'clamp' the lookups at the pixel border.
Perform a convolution operation on this image, using the given separable kernel, to yield a new image. The kernel must have a single channel, an odd width, and a height of 1. The kernel is used to first convolve horizontally, and then vertically. This is often more efficient than creating a square kernel and doing a single convolution operation. The wrapx and wrapy control the behaviour at the edge of the image and default to false. When not wrapping, the effect is to 'clamp' the lookups at the pixel border.
Create a new image of the given size that is initialised to a copied version of this image, or the background colour if the pixel is not within the bounds of this image. If no background colour is given, the image is wrapped (repeated).
As the crop method, except the location is fixed to the center.
Assign a given colour to a single pixel coordinate.
Draw another image on top of this image, in the position given. Both images must have the same number of non-alpha channels. The image being drawn on top must have an alpha channel but this image need not. The two boolean parameters cause the other image to wrap around this image if it is drawn at the edges. This is useful when creating wrappable textures. The wrap parameters both default to false.
The same as drawImage but draws the image centered at the given location instead of with its bottom left corner at that location.
Draw a line between two points.
Create a new image identical to this one but inverted on the Y axis.
Execute the given closure once for each pixel of the image.
Gamma encode/decode the given image. Use a value of n > 1 to decode (usually 2.2) and 1/n to encode.
Create a new image with the given number of channels, the same size as this image, initialised by executing the function provided to map each pixel from this image into the new image. The function is called with two params: the pixel from the existing image, and the coordinate being set (like make).
The returned image is the max of the two given images (they must be compatible). The max of two pixels is the max of each of their channels. This is sometimes called 'lighten only'. It is also allowed to give a single colour value in place of the other image.
The average difference between pixels in two compatible images.
The returned image is the min of the two given images (they must be compatible). The min of two pixels is the min of each of their channels. This is sometimes called 'darken only'. It is also allowed to give a single colour value in place of the other image.
Create a new image identical to this one but inverted on the X axis.
Return a new image where the sum of all the positive pixel channels is 1, and the sum of all the negative pixel channels is -1. This is useful for normalising kernels for convolutions, so that the overall brightness of the image is unchanged during the convolution.
Reduce the colour fidelity of the image and also optionally dither it. The available dither options are 'NONE', 'FLOYD_STEINBERG', and 'FLOYD_STEINBERG_LINEAR'. FLOYD_STEINBERG assumes the image is in gamma space and temporarily converts the non-alpha channels to linear to do the dithering (you probably want this). FLOYD_STEINBERG_LINEAR just does the dithering without that temporary conversion. The number of colours is given as a vector with the same number of elements as the image has channels. E.g. to reduce an RGB image to R5G6G5, use vec(32, 64, 32). To use only 100% or 0% in each channel, use vec(2, 2, 2).
Compute a single value from this image in a generic fashion. The computed value has the same number of channels as the image. The given function is called for each pixel. It is provided with the old running total, the current pixel value, and the current pixel position. It is expected to return the new running total.
Subtract one image from the other. Square every pixel channel value, average them all, and square root the result. This is a common method for objectively measuring the difference between two compatible images. The resulting value is a colour, but you can use the # operator to reduce this to a single value, e.g. #img:rms(other).
Create a new image the same as this one but rotated by the given angle (degrees). The resulting image will have larger area if the angle is not a multiple of 90.
Write the contents of the file to disk, guessing the format from the file extension.
Create a new image the same as this one but a different size. The available filter methods are BOX, BILINEAR, BSPLINE, BICUBIC, CATMULLROM, and LANCZOS3.
Just like scale(), except the new size is given as a multiple of the old size.