{{newin|[[11.0]]|110|type=function}}
Draws many instances of a [[Mesh]] with a single draw call, using hardware geometry instancing.

Each instance can have unique properties (positions, colors, etc.) but will not by default unless a custom [[Shader]] along with either [[Mesh:attachAttribute|per-instance vertex attributes]] or the <code>love_InstanceID</code> GLSL 3 vertex [[Shader Variables|shader variable]] is used, otherwise they will all render at the same position on top of each other.

Instancing is not supported by some older GPUs that are only capable of using OpenGL ES 2 or OpenGL 2. Use [[love.graphics.getSupported]] to check.

== Function ==
=== Synopsis ===
<source lang="lua">
love.graphics.drawInstanced( mesh, instancecount, x, y, r, sx, sy, ox, oy, kx, ky )
</source>
=== Arguments ===
{{param|Mesh|mesh|The mesh to render.}}
{{param|number|instancecount|The number of instances to render.}}
{{param|number|x (0)|The position to draw the instances (x-axis).}}
{{param|number|y (0)|The position to draw the instances (y-axis).}}
{{param|number|r (0)|Orientation (radians).}}
{{param|number|sx (1)|Scale factor (x-axis).}}
{{param|number|sy (sx)|Scale factor (y-axis).}}
{{param|number|ox (0)|Origin offset (x-axis).}}
{{param|number|oy (0)|Origin offset (y-axis).}}
{{param|number|kx (0)|Shearing factor (x-axis).}}
{{param|number|ky (0)|Shearing factor (y-axis).}}
=== Returns ===
Nothing.

== Function ==
=== Synopsis ===
<source lang="lua">
love.graphics.drawInstanced( mesh, instancecount, transform )
</source>
=== Arguments ===
{{param|Mesh|mesh|The mesh to render.}}
{{param|number|instancecount|The number of instances to render.}}
{{param|Transform|transform|A transform object.}}
=== Returns ===
Nothing.

== Examples ==
=== Use vertex attribute instancing to draw many triangles in a single draw call ===
<source lang="Lua">
-- A simple small triangle with the default position, texture coordinate, and color vertex attributes.
local vertices = {
	{0, 0,  0,0, 1.0,0.2,0.2,1.0},
	{20,0,  0,0, 0.2,1.0,0.2,1.0},
	{20,20, 0,0, 0.2,0.2,1.0,1.0},
}

local mesh = love.graphics.newMesh(vertices, "triangles", "static")

-- Unique positions for each instance that will be rendered.
local instancepositions = {}
for y=0, love.graphics.getHeight()-1, 30 do
	for x = 0, love.graphics.getWidth()-1, 30 do
		local pos = {x, y}
		table.insert(instancepositions, pos)
	end
end

-- Create a mesh containing the per-instance position data.
-- It won't be drawn directly, but it will be referenced by the triangle's mesh.
local instancemesh = love.graphics.newMesh({{"InstancePosition", "float", 2}}, instancepositions, nil, "static")

-- When the triangle's mesh is rendered, the vertex shader will pull in a different
-- value of the InstancePosition attribute for each instance, instead of for each vertex.
mesh:attachAttribute("InstancePosition", instancemesh, "perinstance")

-- Vertex shader which uses the InstancePosition vertex attribute.
local shader = love.graphics.newShader[[
attribute vec2 InstancePosition;

vec4 position(mat4 transform_projection, vec4 vertex_position)
{
	vertex_position.xy += InstancePosition;
	return transform_projection * vertex_position;
}
]]

function love.draw()
	love.graphics.setShader(shader)

	-- Draw the mesh many times in one draw call, using instancing.
	local instancecount = #instancepositions
	love.graphics.drawInstanced(mesh, instancecount, 0, 0)
end
</source>

== See Also ==
* [[parent::love.graphics]]
* [[Mesh]]
* [[Mesh:attachAttribute]]
* [[love.graphics.newShader]]
* [[GraphicsFeature]]
[[Category:Functions]]
[[Sub-Category::Drawing| ]]
{{#set:Description=Draws many instances of a [[Mesh]] with a single draw call, using hardware geometry instancing.}}
== Other Languages ==
{{i18n|love.graphics.drawInstanced}}