Difference between revisions of "love.graphics.draw"

Latest revision as of 07:40, 7 October 2023

Draws a Drawable object (an Image, Canvas, SpriteBatch, ParticleSystem, Mesh, Text object, or Video) on the screen with optional rotation, scaling and shearing.

Objects are drawn relative to their local coordinate system. The origin is by default located at the top left corner of Image and Canvas objects. All scaling, shearing, and rotation arguments transform the object relative to that point.

It's possible to rotate an object about, for example, its center by offsetting the origin to the center. Angles must be given in radians for rotation. One can also use negative scaling factors to flip the object about its origin.

Note that the offsets are applied before rotation, scaling, or shearing; scaling and shearing are applied before rotation.

The right and bottom edges of the object are shifted at an angle defined by the shearing factors.

When using the default shader anything drawn with this function will be tinted according to the currently selected color. Set it to pure white to preserve the object's original colors.

Function

Synopsis

love.graphics.draw( drawable, x, y, r, sx, sy, ox, oy, kx, ky )

Arguments

Drawable drawable: A drawable object.
number x (0): The position to draw the object (x-axis).
number y (0): The position to draw the object (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).

Available since LÖVE 0.8.0

number kx (0): Shearing factor (x-axis).
number ky (0): Shearing factor (y-axis).

Returns

Nothing.

Function

Available since LÖVE 0.9.0

It has replaced love.graphics.drawq.

Synopsis

love.graphics.draw( texture, quad, x, y, r, sx, sy, ox, oy, kx, ky )

Arguments

Texture texture: A Texture (Image or Canvas) to texture the Quad with.
Quad quad: The Quad to draw on screen.
number x: The position to draw the object (x-axis).
number y: The position to draw the object (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

Available since LÖVE 11.0

This variant is not supported in earlier versions.

Synopsis

love.graphics.draw( drawable, transform )

Arguments

Drawable drawable: A drawable object.
Transform transform: Transformation object.

Returns

Nothing.

Function

Available since LÖVE 11.0

This variant is not supported in earlier versions.

Synopsis

love.graphics.draw( texture, quad, transform )

Arguments

Texture texture: A Texture (Image or Canvas) to texture the Quad with.
Quad quad: The Quad to draw on screen.
Transform transform: Transformation object.

Returns

Nothing.

Examples

Draw an image (the Hamster Ball) at 100 by 100 pixels

function love.load()
	hamster = love.graphics.newImage("hamster.png")
end
function love.draw()
	love.graphics.draw(hamster, 100,100)
end

Draw an image (the Hamster Ball) from the center at 100 by 100 pixels, rotating over time

function love.load()
	hamster = love.graphics.newImage("hamster.png")
end
function love.draw()
	local width  = hamster:getWidth()
	local height = hamster:getHeight()
	local angle  = love.timer.getTime() * 2*math.pi / 2.5 -- Rotate one turn per 2.5 seconds.
	love.graphics.draw(hamster, 100,100, angle, 1,1, width/2, height/2)
end

Available since LÖVE 0.9.0

This functionality is not supported in earlier versions.

Draw the top half of an image (the Hamster Ball) at 100 by 100 pixels.

function love.load()
	hamster      = love.graphics.newImage("hamster.png")
	local width  = hamster:getWidth()
	local height = hamster:getHeight()
	quad         = love.graphics.newQuad(0,0, width,height/2, width,height)
end
function love.draw()
	love.graphics.draw(hamster,quad, 100,100)
end

Draw the flying rocket directed to the mouse pointer

function love.load()
	local image = love.graphics.newImage ('rocket.png')
	Rocket ={x=200,y=200,angle=0,image=image,ox=image:getWidth()/2,oy=image:getHeight()/2}
end
function love.update(dt)
	local mx, my = love.mouse.getPosition()
	local dx, dy = mx-Rocket.x, my-Rocket.y
	Rocket.angle = math.atan2 (dy, dx)
	Rocket.x = Rocket.x + dt*dx
	Rocket.y = Rocket.y + dt*dy
end
function love.draw()
	love.graphics.draw (Rocket.image, Rocket.x, Rocket.y, Rocket.angle, 1, 1, Rocket.ox, Rocket.oy)
end

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

@@ Line 1: / Line 1: @@
-Draws objects on screen. Drawable objects are [[Image|loaded images]], but may be other kinds of [[Drawable]] objects, such as a [[ParticleSystem]].
+Draws a [[Drawable]] object (an [[Image]], [[Canvas]], [[SpriteBatch]], [[ParticleSystem]], [[Mesh]], [[Text]] object, or [[Video]]) on the screen with optional rotation, scaling and shearing.
-In addition to simple drawing, the draw() function can rotate and scale the object at the same time, as well as offset the image (for example, to center the image at the chosen coordinates).
+Objects are drawn relative to their local coordinate system. The origin is by default located at the top left corner of [[Image]] and [[Canvas]] objects. All scaling, shearing, and rotation arguments transform the object relative to that point.
-love.graphics.draw() anchors from the top left corner by default.
+It's possible to rotate an object about, for example, its center by offsetting the origin to the center. Angles must be given in radians for rotation. One can also use negative scaling factors to flip the object about its origin.
-You can specify a negative value for sx or sy to flip the drawable horizontally or vertically.
+Note that the offsets are applied before rotation, scaling, or shearing; scaling and shearing are applied before rotation.
-The pivotal point is (x, y) on the screen and (ox, oy) in the internal coordinate system of the drawable object, before rotation and scaling. The object is scaled by (sx, sy), then rotated by r around the pivotal point.
+The right and bottom edges of the object are shifted at an angle defined by the shearing factors.
-The default [[ColorMode]] blends the current drawing color into the image, so you will often want to invoke [[love.graphics.setColorMode]]("replace") before drawing images, to ensure that the drawn image matches the source image file.
+When using the default shader anything drawn with this function will be tinted according to the currently selected color. Set it to pure white to preserve the object's original colors.
-The origin offset values are most often used to shift the images up and left by half of its height and width, so that (effectively) the specified x and y coordinates are where the center of the image will end up.
 == Function ==
-{{newin|[[0.8.0]]|type=variant}}
 === Synopsis ===
 <source lang="lua">
@@ Line 20: / Line 18: @@
 === Arguments ===
 {{param|Drawable|drawable|A drawable object.}}
+{{param|number|x (0)|The position to draw the object (x-axis).}}
+{{param|number|y (0)|The position to draw the object (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).}}
+{{New feature|0.8.0|
+{{param|number|kx (0)|Shearing factor (x-axis).}}
+{{param|number|ky (0)|Shearing factor (y-axis).}}
+|080}}
+=== Returns ===
+Nothing.
+== Function ==
+{{newin|[[0.9.0]]|090|type=variant|text=It has replaced [[love.graphics.drawq]]}}
+=== Synopsis ===
+<source lang="lua">
+love.graphics.draw( texture, quad, x, y, r, sx, sy, ox, oy, kx, ky )
+</source>
+=== Arguments ===
+{{param|Texture|texture|A [[Texture]] ([[Image]] or [[Canvas]]) to texture the [[Quad]] with.}}
+{{param|Quad|quad|The Quad to draw on screen.}}
 {{param|number|x|The position to draw the object (x-axis).}}
 {{param|number|y|The position to draw the object (y-axis).}}
 {{param|number|r (0)|Orientation (radians).}}
-{{param|number|sx (1)|Scale factor (x-axis). Can be negative.}}
+{{param|number|sx (1)|Scale factor (x-axis).}}
-{{param|number|sy (sx)|Scale factor (y-axis). Can be negative.}}
+{{param|number|sy (sx)|Scale factor (y-axis).}}
-{{param|number|ox (0)|Origin offset (x-axis). (A value of 20 would effectively move your drawable object 20 pixels to the left.)}}
+{{param|number|ox (0)|Origin offset (x-axis).}}
-{{param|number|oy (0)|Origin offset (y-axis). (A value of 20 would effectively move your drawable object 20 pixels up.)}}
+{{param|number|oy (0)|Origin offset (y-axis).}}
-{{param|number|kx|The shearing factor (x-axis).}}
+{{param|number|kx (0)|Shearing factor (x-axis).}}
-{{param|number|ky|The shearing factor (y-axis).}}
+{{param|number|ky (0)|Shearing factor (y-axis).}}
 === Returns ===
 Nothing.
 == Function ==
-{{oldin|[[0.7.2]]|type=variant}}
+{{newin|[[11.0]]|110|type=variant}}
 === Synopsis ===
 <source lang="lua">
-love.graphics.draw( drawable, x, y, r, sx, sy, ox, oy )
+love.graphics.draw( drawable, transform )
 </source>
 === Arguments ===
 {{param|Drawable|drawable|A drawable object.}}
-{{param|number|x|The position to draw the object (x-axis).}}
+{{param|Transform|transform|Transformation object.}}
-{{param|number|y|The position to draw the object (y-axis).}}
+=== Returns ===
-{{param|number|r (0)|Orientation (radians).}}
+Nothing.
-{{param|number|sx (1)|Scale factor (x-axis). Can be negative.}}
-{{param|number|sy (sx)|Scale factor (y-axis). Can be negative.}}
+== Function ==
-{{param|number|ox (0)|Origin offset (x-axis). (A value of 20 would effectively move your drawable object 20 pixels to the left.)}}
+{{newin|[[11.0]]|110|type=variant}}
-{{param|number|oy (0)|Origin offset (y-axis). (A value of 20 would effectively move your drawable object 20 pixels up.)}}
+=== Synopsis ===
+<source lang="lua">
+love.graphics.draw( texture, quad, transform )
+</source>
+=== Arguments ===
+{{param|Texture|texture|A [[Texture]] ([[Image]] or [[Canvas]]) to texture the [[Quad]] with.}}
+{{param|Quad|quad|The Quad to draw on screen.}}
+{{param|Transform|transform|Transformation object.}}
 === Returns ===
 Nothing.
 == Examples ==
-=== Draw an image (the [https://love2d.org/w/images/c/c3/Resource-HamsterBall.png Hamster Ball]) at 100 by 100 pixels ===
+=== Draw an image (the [[:File:Resource-HamsterBall.png|Hamster Ball]]) at 100 by 100 pixels ===
+<source lang="lua">
+function love.load()
+	hamster = love.graphics.newImage("hamster.png")
+end
+function love.draw()
+	love.graphics.draw(hamster, 100,100)
+end
+</source>
+=== Draw an image (the [[:File:Resource-HamsterBall.png|Hamster Ball]]) from the center at 100 by 100 pixels, rotating over time ===
 <source lang="lua">
 function love.load()
-   hamster = love.graphics.newImage("hamster.png")
+	hamster = love.graphics.newImage("hamster.png")
 end
 function love.draw()
-   love.graphics.draw(hamster, 100, 100)
+	local width  = hamster:getWidth()
+	local height = hamster:getHeight()
+	local angle  = love.timer.getTime() * 2*math.pi / 2.5 -- Rotate one turn per 2.5 seconds.
+	love.graphics.draw(hamster, 100,100, angle, 1,1, width/2, height/2)
 end
 </source>
-=== Draw an image (the [https://love2d.org/w/images/c/c3/Resource-HamsterBall.png Hamster Ball]) from the center at 100 by 100 pixels, rotated by 90 degrees ===
+----
+{{newin|[[0.9.0]]|090|type=functionality}}
+=== Draw the top half of an image (the [[:File:Resource-HamsterBall.png|Hamster Ball]]) at 100 by 100 pixels. ===
 <source lang="lua">
 function love.load()
-   hamster = love.graphics.newImage("hamster.png")
+	hamster      = love.graphics.newImage("hamster.png")
-   width = hamster:getWidth()
+	local width  = hamster:getWidth()
-   height = hamster:getHeight()
+	local height = hamster:getHeight()
+	quad         = love.graphics.newQuad(0,0, width,height/2, width,height)
 end
 function love.draw()
-   love.graphics.draw(hamster, 100, 100, math.rad(90), 1, 1, width / 2, height / 2)
+	love.graphics.draw(hamster,quad, 100,100)
+end
+</source>
+=== Draw the flying [[:File:rocket.png|rocket]] directed to the mouse pointer ===
+<source lang="lua">
+function love.load()
+	local image = love.graphics.newImage ('rocket.png')
+	Rocket ={x=200,y=200,angle=0,image=image,ox=image:getWidth()/2,oy=image:getHeight()/2}
+end
+function love.update(dt)
+	local mx, my = love.mouse.getPosition()
+	local dx, dy = mx-Rocket.x, my-Rocket.y
+	Rocket.angle = math.atan2 (dy, dx)
+	Rocket.x = Rocket.x + dt*dx
+	Rocket.y = Rocket.y + dt*dy
+end
+function love.draw()
+	love.graphics.draw (Rocket.image, Rocket.x, Rocket.y, Rocket.angle, 1, 1, Rocket.ox, Rocket.oy)
 end
 </source>
 == See Also ==
+* [[love.graphics.drawInstanced]]
+* [[love.graphics.drawLayer]]
 * [[parent::love.graphics]]
 [[Category:Functions]]
+[[Sub-Category::Drawing| ]]
 {{#set:Description=Draws objects on screen.}}
 {{#set:Since=000}}
 == Other Languages ==
 {{i18n|love.graphics.draw}}

Views

Difference between revisions of "love.graphics.draw"

Latest revision as of 07:40, 7 October 2023

Contents

Function

Synopsis

Arguments

Returns

Function

Synopsis

Arguments

Returns

Function

Synopsis

Arguments

Returns

Function

Synopsis

Arguments

Returns

Examples

Draw an image (the Hamster Ball) at 100 by 100 pixels

Draw an image (the Hamster Ball) from the center at 100 by 100 pixels, rotating over time

Draw the top half of an image (the Hamster Ball) at 100 by 100 pixels.

Draw the flying rocket directed to the mouse pointer

See Also

Other Languages

Personal tools

Search

documentation

Navigation

wiki navigation

Tools