Available since LÖVE 11.0 |
This function is not supported in earlier versions. |
![]() |
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.
Creates an array Image given a different image file for each slice of the resulting array image object.
image = love.graphics.newArrayImage( slices, settings )
table slices
table settings (nil)
boolean mipmaps (false)
boolean linear (false)
number dpiscale (1)
Image image
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;
.
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
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