love.graphics.newArrayImage

Available since LÖVE 11.0
This function is not supported in earlier versions.

Creates a new array Image.

Not all system supports array image. Use love.graphics.getTextureTypes to check!

This function can be slow if it is called repeatedly, such as from love.update or love.draw. If you need to use a specific resource often, create it once and store it somewhere it can be reused!

An array image / array texture is a single object which contains multiple 'layers' or 'slices' of 2D sub-images. It can be thought of similarly to a texture atlas or sprite sheet, but it doesn't suffer from the same tile / quad bleeding artifacts that texture atlases do – although every sub-image must have the same dimensions.

A specific layer of an array image can be drawn with love.graphics.drawLayer / SpriteBatch:addLayer, or with the Quad variant of love.graphics.draw and Quad:setLayer, or via a custom Shader.

To use an array image in a Shader, it must be declared as a ArrayImage or sampler2DArray type (instead of Image or sampler2D). The Texel(ArrayImage image, vec3 texturecoord) shader function must be used to get pixel colors from a slice of the array image. The vec3 argument contains the texture coordinate in the first two components, and the 0-based slice index in the third component.

Function

Creates an array Image given a different image file for each slice of the resulting array image object.

Synopsis

image = love.graphics.newArrayImage( slices, settings )

Arguments

table slices

A table containing filepaths to images (or File, FileData, ImageData, or CompressedImageData objects), in an array. Each sub-image must have the same dimensions. A table of tables can also be given, where each sub-table contains all mipmap levels for the slice index of that sub-table.

table settings (nil)

Optional table of settings to configure the array image, containing the following fields:

boolean mipmaps (false): True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a compressed texture format.
boolean linear (false): True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.
number dpiscale (1): The DPI scale to use when drawing the array image and calling getWidth/getHeight.

Returns

Image image: An Array Image object.

Notes

Illustration of how an array image works: [1]

A DPI scale of 2 (double the normal pixel density) will result in the image taking up the same space on-screen as an image with half its pixel dimensions that has a DPI scale of 1. This allows for easily swapping out image assets that take the same space on-screen but have different pixel densities, which makes supporting high-dpi / retina resolution require less code logic.

In order to use an Array Texture or other non-2D texture types as the main texture in a custom Shader, the void effect() variant must be used in the pixel shader, and MainTex must be declared as an ArrayImage or sampler2DArray like so: uniform ArrayImage MainTex;.

Examples

Draw multiple layers of an Array Image

function love.load()
    local sprites = {"sprite1.png", "sprite2.png"}
    image = love.graphics.newArrayImage(sprites)
end
 
function love.draw()
    love.graphics.drawLayer(image, 1, 50, 50)
    love.graphics.drawLayer(image, 2, 250, 50)
end

Use a custom shader with love.graphics.drawLayer

shader = love.graphics.newShader[[
uniform ArrayImage MainTex;
 
void effect() {
    // Texel uses a third component of the texture coordinate for the layer index, when an Array Texture is passed in.
    // love sets up the texture coordinates to contain the layer index specified in love.graphics.drawLayer, when
    // rendering the Array Texture.
    love_PixelColor = Texel(MainTex, VaryingTexCoord.xyz) * VaryingColor;
}
]]
 
function love.load()
    local sprites = {"sprite1.png", "sprite2.png"}
    image = love.graphics.newArrayImage(sprites)
end
 
function love.draw()
    love.graphics.setShader(shader)
    love.graphics.drawLayer(image, 1, 50, 50)
    love.graphics.drawLayer(image, 2, 250, 50)
end