View source for Mesh:setInstanceCount

{{newin|[[0.9.1]]|091|type=function}}
Sets how many individual instances of this Mesh will be drawn at once. This will make use of graphics hardware to draw many copies of the Mesh far more efficiently than is possible by calling [[love.graphics.draw]] in a loop in Lua code.

{{notice|Currently, the only way to have different properties (position, color, ...) for each unique instance of the Mesh is to have a [[Shader|vertex shader]] which makes use of the built-in variable [[Shader Variables|love_InstanceID]]. Because of this, instanced drawing of Meshes is a fairly advanced technique.}}

== Function ==
=== Synopsis ===
<source lang="lua">
Mesh:setInstanceCount( count )
</source>
=== Arguments ===
{{param|number|count|The number of individual instances of this Mesh that will be drawn with [[love.graphics.draw]].}}
=== Returns ===
Nothing.

== Notes ==
If [[GraphicsFeature|love.graphics.isSupported("instancing")]] returns true, drawing tens or hundreds of thousands of instances at once will probably have very little performance impact. When it returns false this functionality will still work but it will use a slower fallback, in which case it's best to stick to instance counts of a couple thousand or lower.

== Examples ==
=== draw 1000 triangles in different positions with a single draw call, using Mesh instancing ===
<source lang="lua">
-- Create our mesh. It's just a single triangle.
local vertices = {
    {0, 0,  0,0},
    {10,0,  0,0},
    {5, 5,  0,0},
}
mesh = love.graphics.newMesh(vertices, nil, "triangles")

-- Set its instance count to 1000 when drawing it.
mesh:setInstanceCount(1000)

-- Create a vertex shader which will modify the triangle's position based on the current instance being drawn.
shader = love.graphics.newShader[[
</source><source lang="glsl">
// This is the standard function prototype for a vertex shader.
vec4 position(mat4 transform_projection, vec4 vertex_pos)
{
    // Add to the position based on the current Instance ID. Note that it's an integer variable.
    vertex_pos.x += mod(float(love_InstanceID) * 20.0, 800.0);
    vertex_pos.y += float(love_InstanceID * 20 / 800) * 20.0;

    // Do the standard transformation to return the modified vertex position in normalized screen-space.
    return transform_projection * vertex_pos;
}
</source><source lang="lua">
]]

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

    -- Draw the triangle mesh 1000 times with a single call to love.graphics.draw.
    love.graphics.draw(mesh, 0, 0)

    love.graphics.setShader()
end
</source>

== See Also ==
* [[parent::Mesh]]
* [[Mesh:getInstanceCount]]
* [[Shader Variables]]
[[Category:Functions]]
{{#set:Description=Sets how many instances of this Mesh will be drawn at once.}}
== Other Languages ==
{{i18n|Mesh:setInstanceCount}}