{{newin|[[11.0]]|110|type=function}}
Creates a new [[TextureType|array]] [[Image]].
{{notice|Not all system supports array image. Use [[love.graphics.getTextureTypes]] to check!}}
{{newobjectnotice}}

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 <code>ArrayImage</code> or <code>sampler2DArray</code> type (instead of <code>Image</code> or <code>sampler2D</code>). The <code>Texel(ArrayImage image, vec3 texturecoord)</code> 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 ===
<source lang="lua">
image = love.graphics.newArrayImage( slices, settings )
</source>
=== Arguments ===
{{param|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.}}
{{param|table|settings (nil)|Optional table of settings to configure the array image, containing the following fields:}}
{{subparam|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 [[PixelFormat|compressed texture]] format.}}
{{subparam|boolean|linear (false)|True to treat the image's pixels as linear instead of sRGB, when [[love.graphics.isGammaCorrect|gamma correct rendering]] is enabled. Most images are authored as sRGB.}}
{{subparam|number|dpiscale (1)|The DPI scale to use when drawing the array image and calling [[Texture:getWidth|getWidth]]/[[Texture:getHeight|getHeight]].}}
=== Returns ===
{{param|Image|image|An Array Image object.}}

== Notes ==
Illustration of how an array image works: [http://codeflow.org/entries/2010/dec/09/minecraft-like-rendering-experiments-in-opengl-4/illustrations/textures.jpg]

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 [[love.graphics.newShader|void effect()]] variant must be used in the pixel shader, and MainTex must be declared as an ArrayImage or sampler2DArray like so: <code>uniform ArrayImage MainTex;</code>.

== Examples ==
=== Draw multiple layers of an Array Image ===
<source lang="lua">
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
</source>

=== Use a custom shader with love.graphics.drawLayer ===
<source lang="lua">
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
</source>

== See Also ==
* [[parent::love.graphics]]
* [[Constructs::Image]]
* [[TextureType]]
[[Category:Functions]]
[[Sub-Category::Object Creation| ]]
{{#set:Description=Creates a new [[TextureType|array]] [[Image]].}}
== Other Languages ==
{{i18n|love.graphics.newArrayImage}}