Difference between revisions of "love.graphics.drawInstanced"

m
m
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
{{newin|[[0.11.0]]|110|type=function}}
+
{{newin|[[11.0]]|110|type=function}}
−
 
 
 
Draws many instances of a [[Mesh]] with a single draw call, using hardware geometry instancing.
 
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 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.
+
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.
 
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.
Line 15: Line 14:
 
{{param|Mesh|mesh|The mesh to render.}}
 
{{param|Mesh|mesh|The mesh to render.}}
 
{{param|number|instancecount|The number of instances to render.}}
 
{{param|number|instancecount|The number of instances to render.}}
−
{{param|number|x (0)|The position to draw the object (x-axis).}}
+
{{param|number|x (0)|The position to draw the instances (x-axis).}}
−
{{param|number|y (0)|The position to draw the object (y-axis).}}
+
{{param|number|y (0)|The position to draw the instances (y-axis).}}
 
{{param|number|r (0)|Orientation (radians).}}
 
{{param|number|r (0)|Orientation (radians).}}
 
{{param|number|sx (1)|Scale factor (x-axis).}}
 
{{param|number|sx (1)|Scale factor (x-axis).}}
Line 38: Line 37:
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
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 ==
 
== See Also ==
Line 44: Line 92:
 
* [[Mesh:attachAttribute]]
 
* [[Mesh:attachAttribute]]
 
* [[love.graphics.newShader]]
 
* [[love.graphics.newShader]]
 +
* [[GraphicsFeature]]
 
[[Category:Functions]]
 
[[Category:Functions]]
 
[[Sub-Category::Drawing| ]]
 
[[Sub-Category::Drawing| ]]

Latest revision as of 21:38, 4 October 2019

Available since LÖVE 11.0
This function is not supported in earlier versions.

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 per-instance vertex attributes or the love_InstanceID GLSL 3 vertex 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

love.graphics.drawInstanced( mesh, instancecount, x, y, r, sx, sy, ox, oy, kx, ky )

Arguments

Mesh mesh
The mesh to render.
number instancecount
The number of instances to render.
number x (0)
The position to draw the instances (x-axis).
number y (0)
The position to draw the instances (y-axis).
number r (0)
Orientation (radians).
number sx (1)
Scale factor (x-axis).
number sy (sx)
Scale factor (y-axis).
number ox (0)
Origin offset (x-axis).
number oy (0)
Origin offset (y-axis).
number kx (0)
Shearing factor (x-axis).
number ky (0)
Shearing factor (y-axis).

Returns

Nothing.

Function

Synopsis

love.graphics.drawInstanced( mesh, instancecount, transform )

Arguments

Mesh mesh
The mesh to render.
number instancecount
The number of instances to render.
Transform transform
A transform object.

Returns

Nothing.

Examples

Use vertex attribute instancing to draw many triangles in a single draw call

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

See Also


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

Retrieved from "https://love2d.org./w/index.php?title=love.graphics.drawInstanced&oldid=23644"