Difference between revisions of "love.graphics.newSpriteBatch"

m (1 revision: Imported docs from potato.)
m (→‎Examples: Fixed variable name.)
 
(16 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
Creates a new [[SpriteBatch]] object.
 +
{{newobjectnotice}}
 +
== Function ==
 +
=== Synopsis ===
 +
<source lang="lua">
 +
spriteBatch = love.graphics.newSpriteBatch( image, maxsprites )
 +
</source>
 +
=== Arguments ===
 +
{{param|Image|image|The Image to use for the sprites.}}
 +
{{param|number|maxsprites (1000)|The maximum number of sprites that the SpriteBatch can contain at any given time. Since version [[11.0]], additional sprites added past this number will automatically grow the spritebatch.}}
 +
=== Returns ===
 +
{{param|SpriteBatch|spriteBatch|The new SpriteBatch.}}
 +
 +
== Function ==
 +
{{newin|[[0.8.0]]|080|type=variant}}
 +
=== Synopsis ===
 +
<source lang="lua">
 +
spriteBatch = love.graphics.newSpriteBatch( image, maxsprites, usage )
 +
</source>
 +
=== Arguments ===
 +
{{param|Image|image|The Image to use for the sprites.}}
 +
{{param|number|maxsprites (1000)|The maximum number of sprites that the SpriteBatch can contain at any given time. Since version [[11.0]], additional sprites added past this number will automatically grow the spritebatch.}}
 +
{{param|SpriteBatchUsage|usage ("dynamic")|The expected usage of the SpriteBatch. The specified usage mode affects the SpriteBatch's memory usage and performance.}}
  
 +
=== Returns ===
 +
{{param|SpriteBatch|spriteBatch|The new SpriteBatch.}}
  
 
== Function ==
 
== Function ==
 +
{{newin|[[0.9.1]]|091|type=variant}}
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
spriteBatch = love.graphics.newSpriteBatch( image, size )
+
spriteBatch = love.graphics.newSpriteBatch( texture, maxsprites, usage )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
−
{{param|Image|image|The Image to use for the sprites.}}
+
{{param|Texture|texture|The [[Image]] or [[Canvas]] to use for the sprites.}}
−
{{param|number|size|The max number of sprites.}}
+
{{param|number|maxsprites (1000)|The maximum number of sprites that the SpriteBatch can contain at any given time. Since version [[11.0]], additional sprites added past this number will automatically grow the spritebatch.}}
 +
{{param|SpriteBatchUsage|usage ("dynamic")|The expected usage of the SpriteBatch. The specified usage mode affects the SpriteBatch's memory usage and performance.}}
 
=== Returns ===
 
=== Returns ===
 
{{param|SpriteBatch|spriteBatch|The new SpriteBatch.}}
 
{{param|SpriteBatch|spriteBatch|The new SpriteBatch.}}
 +
 +
== Examples ==
 +
 +
This example uses this image for all the graphics:
 +
 +
[[File:spriteBatchExample.png]]
 +
 +
<source lang="lua">
 +
local entities = {}
 +
local spriteBatch, protagonist
 +
 +
function love.load()
 +
local image = love.graphics.newImage("spriteBatchExample.png")
 +
spriteBatch = love.graphics.newSpriteBatch(image)
 +
 +
local quadPlayer  = love.graphics.newQuad(0,  0,  32, 32, image:getDimensions())
 +
local quadTree    = love.graphics.newQuad(32, 0,  32, 32, image:getDimensions())
 +
local quadSign    = love.graphics.newQuad(0,  32, 32, 32, image:getDimensions())
 +
local quadDogHouse = love.graphics.newQuad(32, 32, 32, 32, image:getDimensions())
 +
 +
local windowWidth, windowHeight = love.graphics.getDimensions()
 +
 +
love.graphics.setBackgroundColor(.05, .15, .05)
 +
 +
-- Spawn lots of random things on an uneven grid.
 +
for baseY = 0, windowHeight, 30 do
 +
for baseX = 0, windowWidth, 40 do
 +
local quad = (
 +
love.math.random() < .10 and quadSign    or
 +
love.math.random() < .03 and quadDogHouse or
 +
quadTree
 +
)
 +
table.insert(entities, {
 +
quad  = quad,
 +
x      = baseX + math.random(-12, 12),
 +
y      = baseY + math.random(-8,  8 ),
 +
serial = #entities,
 +
})
 +
end
 +
end
 +
 +
-- Spawn protagonist.
 +
protagonist = {quad=quadPlayer, x=0, y=0, serial=#entities} -- We set the position in love.update().
 +
table.insert(entities, protagonist)
 +
end
 +
 +
function love.update(dt)
 +
local windowWidth, windowHeight = love.graphics.getDimensions()
 +
 +
-- Make the protagonist move around in a circle.
 +
local angle  = .4 * love.timer.getTime()
 +
protagonist.x = windowWidth/2  + .3*windowWidth  * math.cos(angle)
 +
protagonist.y = windowHeight/2 + .3*windowHeight * math.sin(angle)
 +
end
 +
 +
function love.draw()
 +
-- Sort entities by their Y position.
 +
table.sort(entities, function(entity1, entity2)
 +
if entity1.y ~= entity2.y then
 +
return entity1.y < entity2.y
 +
end
 +
return entity1.serial < entity2.serial -- If Y is the same, use the serial number as fallback.
 +
end)
 +
 +
-- Add entities to sprite batch for drawing.
 +
spriteBatch:clear()
 +
for _, entity in ipairs(entities) do
 +
spriteBatch:add(entity.quad, math.floor(entity.x), math.floor(entity.y))
 +
end
 +
 +
-- Finally, draw the sprite batch to the screen.
 +
love.graphics.draw(spriteBatch)
 +
end
 +
</source>
 +
 
== See Also ==
 
== See Also ==
 
* [[parent::love.graphics]]
 
* [[parent::love.graphics]]
 +
* [[Constructs::SpriteBatch]]
 
[[Category:Functions]]
 
[[Category:Functions]]
−
{{#set:Description=}}
+
{{#set:Description=Creates a new [[SpriteBatch]].}}
 +
{{#set:Since=000}}
 +
{{#set:Sub-Category=Object Creation}}
 +
== Other Languages ==
 +
{{i18n|love.graphics.newSpriteBatch}}

Latest revision as of 15:49, 25 April 2022

Creates a new SpriteBatch object.

O.png This function can be slow if it is called repeatedly, such as from love.update or love.draw. If you need to use a specific resource often, create it once and store it somewhere it can be reused!  



Function

Synopsis

spriteBatch = love.graphics.newSpriteBatch( image, maxsprites )

Arguments

Image image
The Image to use for the sprites.
number maxsprites (1000)
The maximum number of sprites that the SpriteBatch can contain at any given time. Since version 11.0, additional sprites added past this number will automatically grow the spritebatch.

Returns

SpriteBatch spriteBatch
The new SpriteBatch.

Function

Available since LÖVE 0.8.0
This variant is not supported in earlier versions.

Synopsis

spriteBatch = love.graphics.newSpriteBatch( image, maxsprites, usage )

Arguments

Image image
The Image to use for the sprites.
number maxsprites (1000)
The maximum number of sprites that the SpriteBatch can contain at any given time. Since version 11.0, additional sprites added past this number will automatically grow the spritebatch.
SpriteBatchUsage usage ("dynamic")
The expected usage of the SpriteBatch. The specified usage mode affects the SpriteBatch's memory usage and performance.

Returns

SpriteBatch spriteBatch
The new SpriteBatch.

Function

Available since LÖVE 0.9.1
This variant is not supported in earlier versions.

Synopsis

spriteBatch = love.graphics.newSpriteBatch( texture, maxsprites, usage )

Arguments

Texture texture
The Image or Canvas to use for the sprites.
number maxsprites (1000)
The maximum number of sprites that the SpriteBatch can contain at any given time. Since version 11.0, additional sprites added past this number will automatically grow the spritebatch.
SpriteBatchUsage usage ("dynamic")
The expected usage of the SpriteBatch. The specified usage mode affects the SpriteBatch's memory usage and performance.

Returns

SpriteBatch spriteBatch
The new SpriteBatch.

Examples

This example uses this image for all the graphics:

spriteBatchExample.png 

local entities = {}
local spriteBatch, protagonist

function love.load()
	local image = love.graphics.newImage("spriteBatchExample.png")
	spriteBatch = love.graphics.newSpriteBatch(image)

	local quadPlayer   = love.graphics.newQuad(0,  0,  32, 32, image:getDimensions())
	local quadTree     = love.graphics.newQuad(32, 0,  32, 32, image:getDimensions())
	local quadSign     = love.graphics.newQuad(0,  32, 32, 32, image:getDimensions())
	local quadDogHouse = love.graphics.newQuad(32, 32, 32, 32, image:getDimensions())

	local windowWidth, windowHeight = love.graphics.getDimensions()

	love.graphics.setBackgroundColor(.05, .15, .05)

	-- Spawn lots of random things on an uneven grid.
	for baseY = 0, windowHeight, 30 do
		for baseX = 0, windowWidth, 40 do
			local quad = (
				love.math.random() < .10 and quadSign     or
				love.math.random() < .03 and quadDogHouse or
				quadTree
			)
			table.insert(entities, {
				quad   = quad,
				x      = baseX + math.random(-12, 12),
				y      = baseY + math.random(-8,  8 ),
				serial = #entities,
			})
		end
	end

	-- Spawn protagonist.
	protagonist = {quad=quadPlayer, x=0, y=0, serial=#entities} -- We set the position in love.update().
	table.insert(entities, protagonist)
end

function love.update(dt)
	local windowWidth, windowHeight = love.graphics.getDimensions()

	-- Make the protagonist move around in a circle.
	local angle   = .4 * love.timer.getTime()
	protagonist.x = windowWidth/2  + .3*windowWidth  * math.cos(angle)
	protagonist.y = windowHeight/2 + .3*windowHeight * math.sin(angle)
end

function love.draw()
	-- Sort entities by their Y position.
	table.sort(entities, function(entity1, entity2)
		if entity1.y ~= entity2.y then
			return entity1.y < entity2.y
		end
		return entity1.serial < entity2.serial -- If Y is the same, use the serial number as fallback.
	end)

	-- Add entities to sprite batch for drawing.
	spriteBatch:clear()
	for _, entity in ipairs(entities) do
		spriteBatch:add(entity.quad, math.floor(entity.x), math.floor(entity.y))
	end

	-- Finally, draw the sprite batch to the screen.
	love.graphics.draw(spriteBatch)
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.newSpriteBatch&oldid=27764"