Mesh:setInstanceCount

Available since LÖVE 0.9.1

This function is not supported in earlier versions.

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.

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

Function

Synopsis

Mesh:setInstanceCount( count )

Arguments

number count

The number of individual instances of this Mesh that will be drawn with love.graphics.draw.

Returns

Nothing.

Notes

If 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

-- 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[[

// 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;
}

]]

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

See Also

• Mesh
• Mesh:getInstanceCount
• Shader Variables

Other Languages

Dansk – Deutsch – English – Español – Français – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Polski – Português – Română – Slovenský – Suomi – Svenska – Türkçe – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – ไทย – 日本語 – 正體中文 – 简体中文 – Tiếng Việt – 한국어
More info