Difference between revisions of "love.graphics.print"

(Add note about color mode)
m (Fixed formatting+improved example. Added more related links.)
 
(28 intermediate revisions by 14 users not shown)
Line 1: Line 1:
 
Draws text on screen. If no [[Font]] is set, one will be created and set (once) if needed.
 
Draws text on screen. If no [[Font]] is set, one will be created and set (once) if needed.
  
−
As of LOVE 0.7.1, when using translation and scaling functions while drawing text, this function assumes the scale occurs first.  If you don't script with this in mind, the text won't be in the right position, or possibly even on screen.
+
As of LOVE [[0.7.1]], when using translation and scaling functions while drawing text, this function assumes the scale occurs first.  If you don't script with this in mind, the text won't be in the right position, or possibly even on screen.
  
−
Drawing uses the current color, but only if the [[ColorMode]] is "modulate" (which is the default). If your text is displayed as white, it is probably because the color mode is "replace" (which is useful when drawing sprites). Change the color model to "modulate" before drawing.
+
[[love.graphics.print]] and [[love.graphics.printf]] both support UTF-8 encoding. You'll also need a proper [[Font]] for special characters.
  
 +
In versions prior to [[11.0]], color and byte component values were within the range of 0 to 255 instead of 0 to 1.
 +
 +
{{notice|Text may appear blurry if it's rendered at non-integer pixel locations.}}
 
== Function ==
 
== Function ==
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
love.graphics.print( text, x, y, r, sx, sy )
+
love.graphics.print( text, x, y, r, sx, sy, ox, oy, kx, ky )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
 
{{param|string|text|The text to draw.}}
 
{{param|string|text|The text to draw.}}
−
{{param|number|x|The position to draw the object (x-axis).}}
+
{{param|number|x (0)|The position to draw the object (x-axis).}}
−
{{param|number|y|The position to draw the object (y-axis).}}
+
{{param|number|y (0)|The position to draw the object (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).}}
 
{{param|number|sy (sx)|Scale factor (y-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|[[11.0]]|110|type=variant}}
 +
=== Synopsis ===
 +
<source lang="lua">
 +
love.graphics.print( text, font, x, y, r, sx, sy, ox, oy, kx, ky )
 +
</source>
 +
=== Arguments ===
 +
{{param|string|text|The text to draw.}}
 +
{{param|Font|font|The Font object to use.}}
 +
{{param|number|x (0)|The position of the text on the x-axis.}}
 +
{{param|number|y (0)|The position of the text on the y-axis.}}
 +
{{param|number|angle (0)|The orientation of the text in radians.}}
 +
{{param|number|sx (1)|Scale factor on the x-axis.}}
 +
{{param|number|sy (sx)|Scale factor on the y-axis.}}
 +
{{param|number|ox (0)|Origin offset on the x-axis.}}
 +
{{param|number|oy (0)|Origin offset on the y-axis.}}
 +
{{param|number|kx (0)|Shearing / skew factor on the x-axis.}}
 +
{{param|number|ky (0)|Shearing / skew factor on the y-axis.}}
 +
=== Returns ===
 +
Nothing.
 +
 +
== Function ==
 +
{{newin|[[0.10.0]]|100|type=variant}}
 +
=== Synopsis ===
 +
<source lang="lua">
 +
love.graphics.print( coloredtext, x, y, angle, sx, sy, ox, oy, kx, ky )
 +
</source>
 +
=== Arguments ===
 +
{{param|table|coloredtext|A table containing colors and strings to add to the object, in the form of <code>{color1, string1, color2, string2, ...}</code>.}}
 +
{{subparam|table|color1|A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of <code>{red, green, blue, alpha}</code>.}}
 +
{{subparam|string|string1|A string of text which has a color specified by the previous color.}}
 +
{{subparam|table|color2|A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of <code>{red, green, blue, alpha}</code>.}}
 +
{{subparam|string|string2|A string of text which has a color specified by the previous color.}}
 +
{{subparam|tables and strings|...|Additional colors and strings.}}
 +
{{param|number|x (0)|The position of the text on the x-axis.}}
 +
{{param|number|y (0)|The position of the text on the y-axis.}}
 +
{{param|number|angle (0)|The orientation of the text in radians.}}
 +
{{param|number|sx (1)|Scale factor on the x-axis.}}
 +
{{param|number|sy (sx)|Scale factor on the y-axis.}}
 +
{{param|number|ox (0)|Origin offset on the x-axis.}}
 +
{{param|number|oy (0)|Origin offset on the y-axis.}}
 +
{{param|number|kx (0)|Shearing / skew factor on the x-axis.}}
 +
{{param|number|ky (0)|Shearing / skew factor on the y-axis.}}
 +
=== Returns ===
 +
Nothing.
 +
=== Notes ===
 +
The color set by [[love.graphics.setColor]] will be combined (multiplied) with the colors of the text.
 +
 +
== Function ==
 +
{{newin|[[11.0]]|110|type=variant}}
 +
=== Synopsis ===
 +
<source lang="lua">
 +
love.graphics.print( coloredtext, font, x, y, angle, sx, sy, ox, oy, kx, ky )
 +
</source>
 +
=== Arguments ===
 +
{{param|table|coloredtext|A table containing colors and strings to add to the object, in the form of <code>{color1, string1, color2, string2, ...}</code>.}}
 +
{{subparam|table|color1|A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of <code>{red, green, blue, alpha}</code>.}}
 +
{{subparam|string|string1|A string of text which has a color specified by the previous color.}}
 +
{{subparam|table|color2|A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of <code>{red, green, blue, alpha}</code>.}}
 +
{{subparam|string|string2|A string of text which has a color specified by the previous color.}}
 +
{{subparam|tables and strings|...|Additional colors and strings.}}
 +
{{param|Font|font|The Font object to use.}}
 +
{{param|number|x (0)|The position of the text on the x-axis.}}
 +
{{param|number|y (0)|The position of the text on the y-axis.}}
 +
{{param|number|angle (0)|The orientation of the text in radians.}}
 +
{{param|number|sx (1)|Scale factor on the x-axis.}}
 +
{{param|number|sy (sx)|Scale factor on the y-axis.}}
 +
{{param|number|ox (0)|Origin offset on the x-axis.}}
 +
{{param|number|oy (0)|Origin offset on the y-axis.}}
 +
{{param|number|kx (0)|Shearing / skew factor on the x-axis.}}
 +
{{param|number|ky (0)|Shearing / skew factor on the y-axis.}}
 +
=== Returns ===
 +
Nothing.
 +
=== Notes ===
 +
The color set by [[love.graphics.setColor]] will be combined (multiplied) with the colors of the text.
 +
 +
== Function ==
 +
{{newin|[[11.0]]|110|type=variant}}
 +
=== Synopsis ===
 +
<source lang="lua">
 +
love.graphics.print( text, transform )
 +
</source>
 +
=== Arguments ===
 +
{{param|string|text|The text to draw.}}
 +
{{param|Transform|transform|Transformation object.}}
 
=== Returns ===
 
=== Returns ===
 
Nothing.
 
Nothing.
 +
 +
== Function ==
 +
{{newin|[[11.0]]|110|type=variant}}
 +
=== Synopsis ===
 +
<source lang="lua">
 +
love.graphics.print( text, font, transform )
 +
</source>
 +
=== Arguments ===
 +
{{param|string|text|The text to draw.}}
 +
{{param|Font|font|The Font object to use.}}
 +
{{param|Transform|transform|Transformation object.}}
 +
=== Returns ===
 +
Nothing.
 +
 +
== Function ==
 +
{{newin|[[11.0]]|110|type=variant}}
 +
=== Synopsis ===
 +
<source lang="lua">
 +
love.graphics.print( coloredtext, transform )
 +
</source>
 +
=== Arguments ===
 +
{{param|table|coloredtext|A table containing colors and strings to add to the object, in the form of <code>{color1, string1, color2, string2, ...}</code>.}}
 +
{{subparam|table|color1|A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of <code>{red, green, blue, alpha}</code>.}}
 +
{{subparam|string|string1|A string of text which has a color specified by the previous color.}}
 +
{{subparam|table|color2|A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of <code>{red, green, blue, alpha}</code>.}}
 +
{{subparam|string|string2|A string of text which has a color specified by the previous color.}}
 +
{{subparam|tables and strings|...|Additional colors and strings.}}
 +
{{param|Transform|transform|Transformation object.}}
 +
=== Returns ===
 +
Nothing.
 +
=== Notes ===
 +
The color set by [[love.graphics.setColor]] will be combined (multiplied) with the colors of the text.
 +
 +
== Function ==
 +
{{newin|[[11.0]]|110|type=variant}}
 +
=== Synopsis ===
 +
<source lang="lua">
 +
love.graphics.print( coloredtext, font, transform )
 +
</source>
 +
=== Arguments ===
 +
{{param|table|coloredtext|A table containing colors and strings to add to the object, in the form of <code>{color1, string1, color2, string2, ...}</code>.}}
 +
{{subparam|table|color1|A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of <code>{red, green, blue, alpha}</code>.}}
 +
{{subparam|string|string1|A string of text which has a color specified by the previous color.}}
 +
{{subparam|table|color2|A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of <code>{red, green, blue, alpha}</code>.}}
 +
{{subparam|string|string2|A string of text which has a color specified by the previous color.}}
 +
{{subparam|tables and strings|...|Additional colors and strings.}}
 +
{{param|Font|font|The Font object to use.}}
 +
{{param|Transform|transform|Transformation object.}}
 +
=== Returns ===
 +
Nothing.
 +
=== Notes ===
 +
The color set by [[love.graphics.setColor]] will be combined (multiplied) with the colors of the text.
 +
 
== Examples ==
 
== Examples ==
 
=== A lame example ===
 
=== A lame example ===
 
<source lang="lua">
 
<source lang="lua">
 
function love.draw()
 
function love.draw()
 +
    love.graphics.setColor(0, 1, 0, 1)
 
     love.graphics.print("This is a pretty lame example.", 10, 200)
 
     love.graphics.print("This is a pretty lame example.", 10, 200)
 +
    love.graphics.setColor(1, 0, 0, 1)
 
     love.graphics.print("This lame example is twice as big.", 10, 250, 0, 2, 2)
 
     love.graphics.print("This lame example is twice as big.", 10, 250, 0, 2, 2)
 +
    love.graphics.setColor(0, 0, 1, 1)
 
     love.graphics.print("This example is lamely vertical.", 300, 30, math.pi/2)
 
     love.graphics.print("This example is lamely vertical.", 300, 30, math.pi/2)
 
end
 
end
 
</source>
 
</source>
 +
 +
=== Draw centered text ===
 +
<source lang="lua">
 +
function drawCenteredText(rectX, rectY, rectWidth, rectHeight, text)
 +
local font      = love.graphics.getFont()
 +
local textWidth  = font:getWidth(text)
 +
local textHeight = font:getHeight()
 +
love.graphics.print(text, rectX+rectWidth/2, rectY+rectHeight/2, 0, 1, 1, textWidth/2, textHeight/2)
 +
end
 +
 +
function love.draw()
 +
local x, y = 100, 60
 +
local w, h = 400, 40
 +
love.graphics.rectangle("line", x, y, w, h)
 +
drawCenteredText(x, y, w, h, "I print my LÖVE")
 +
end
 +
</source>
 +
 
== Notes ==
 
== Notes ==
−
love.graphics.print stops at the first '\0' (null) character. This can bite you if you are appending keystrokes to form your string, as some of those are multi-byte unicode characters which will likely contain null bytes.
+
In version 0.8.0 and older, love.graphics.print stops at the first '\0' (null) character. This can bite you if you are appending keystrokes to form your string, as some of those are multi-byte unicode characters which will likely contain null bytes.
 
== See Also ==
 
== See Also ==
 
* [[parent::love.graphics]]
 
* [[parent::love.graphics]]
 +
* [[love.graphics.printf]]
 +
* [[Font]]
 +
* [[love.graphics.newFont]]
 +
* [[love.graphics.setFont]]
 +
* [[love.graphics.getFont]]
 +
 
[[Category:Functions]]
 
[[Category:Functions]]
 +
[[Sub-Category::Drawing| ]]
 
{{#set:Description=Draws text on screen. If no Font is set, one will be created and set (once) if needed.}}
 
{{#set:Description=Draws text on screen. If no Font is set, one will be created and set (once) if needed.}}
 
{{#set:Since=000}}
 
{{#set:Since=000}}
 +
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|love.graphics.print}}
 
{{i18n|love.graphics.print}}

Latest revision as of 00:02, 11 August 2021

Draws text on screen. If no Font is set, one will be created and set (once) if needed.

As of LOVE 0.7.1, when using translation and scaling functions while drawing text, this function assumes the scale occurs first. If you don't script with this in mind, the text won't be in the right position, or possibly even on screen.

love.graphics.print and love.graphics.printf both support UTF-8 encoding. You'll also need a proper Font for special characters.

In versions prior to 11.0, color and byte component values were within the range of 0 to 255 instead of 0 to 1.

O.png Text may appear blurry if it's rendered at non-integer pixel locations.  


Function

Synopsis

love.graphics.print( text, x, y, r, sx, sy, ox, oy, kx, ky )

Arguments

string text
The text to draw.
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 11.0
This variant is not supported in earlier versions.

Synopsis

love.graphics.print( text, font, x, y, r, sx, sy, ox, oy, kx, ky )

Arguments

string text
The text to draw.
Font font
The Font object to use.
number x (0)
The position of the text on the x-axis.
number y (0)
The position of the text on the y-axis.
number angle (0)
The orientation of the text in radians.
number sx (1)
Scale factor on the x-axis.
number sy (sx)
Scale factor on the y-axis.
number ox (0)
Origin offset on the x-axis.
number oy (0)
Origin offset on the y-axis.
number kx (0)
Shearing / skew factor on the x-axis.
number ky (0)
Shearing / skew factor on the y-axis.

Returns

Nothing.

Function

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

Synopsis

love.graphics.print( coloredtext, x, y, angle, sx, sy, ox, oy, kx, ky )

Arguments

table coloredtext
A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
table color1
A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
string string1
A string of text which has a color specified by the previous color.
table color2
A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
string string2
A string of text which has a color specified by the previous color.
tables and strings ...
Additional colors and strings.
number x (0)
The position of the text on the x-axis.
number y (0)
The position of the text on the y-axis.
number angle (0)
The orientation of the text in radians.
number sx (1)
Scale factor on the x-axis.
number sy (sx)
Scale factor on the y-axis.
number ox (0)
Origin offset on the x-axis.
number oy (0)
Origin offset on the y-axis.
number kx (0)
Shearing / skew factor on the x-axis.
number ky (0)
Shearing / skew factor on the y-axis.

Returns

Nothing.

Notes

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text.

Function

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

Synopsis

love.graphics.print( coloredtext, font, x, y, angle, sx, sy, ox, oy, kx, ky )

Arguments

table coloredtext
A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
table color1
A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
string string1
A string of text which has a color specified by the previous color.
table color2
A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
string string2
A string of text which has a color specified by the previous color.
tables and strings ...
Additional colors and strings.
Font font
The Font object to use.
number x (0)
The position of the text on the x-axis.
number y (0)
The position of the text on the y-axis.
number angle (0)
The orientation of the text in radians.
number sx (1)
Scale factor on the x-axis.
number sy (sx)
Scale factor on the y-axis.
number ox (0)
Origin offset on the x-axis.
number oy (0)
Origin offset on the y-axis.
number kx (0)
Shearing / skew factor on the x-axis.
number ky (0)
Shearing / skew factor on the y-axis.

Returns

Nothing.

Notes

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text.

Function

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

Synopsis

love.graphics.print( text, transform )

Arguments

string text
The text to draw.
Transform transform
Transformation object.

Returns

Nothing.

Function

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

Synopsis

love.graphics.print( text, font, transform )

Arguments

string text
The text to draw.
Font font
The Font object to use.
Transform transform
Transformation object.

Returns

Nothing.

Function

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

Synopsis

love.graphics.print( coloredtext, transform )

Arguments

table coloredtext
A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
table color1
A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
string string1
A string of text which has a color specified by the previous color.
table color2
A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
string string2
A string of text which has a color specified by the previous color.
tables and strings ...
Additional colors and strings.
Transform transform
Transformation object.

Returns

Nothing.

Notes

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text.

Function

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

Synopsis

love.graphics.print( coloredtext, font, transform )

Arguments

table coloredtext
A table containing colors and strings to add to the object, in the form of {color1, string1, color2, string2, ...}.
table color1
A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
string string1
A string of text which has a color specified by the previous color.
table color2
A table containing red, green, blue, and optional alpha components to use as a color for the next string in the table, in the form of {red, green, blue, alpha}.
string string2
A string of text which has a color specified by the previous color.
tables and strings ...
Additional colors and strings.
Font font
The Font object to use.
Transform transform
Transformation object.

Returns

Nothing.

Notes

The color set by love.graphics.setColor will be combined (multiplied) with the colors of the text.

Examples

A lame example

function love.draw()
    love.graphics.setColor(0, 1, 0, 1)
    love.graphics.print("This is a pretty lame example.", 10, 200)
    love.graphics.setColor(1, 0, 0, 1)
    love.graphics.print("This lame example is twice as big.", 10, 250, 0, 2, 2)
    love.graphics.setColor(0, 0, 1, 1)
    love.graphics.print("This example is lamely vertical.", 300, 30, math.pi/2)
end

Draw centered text

function drawCenteredText(rectX, rectY, rectWidth, rectHeight, text)
	local font       = love.graphics.getFont()
	local textWidth  = font:getWidth(text)
	local textHeight = font:getHeight()
	love.graphics.print(text, rectX+rectWidth/2, rectY+rectHeight/2, 0, 1, 1, textWidth/2, textHeight/2)
end

function love.draw()
	local x, y = 100, 60
	local w, h = 400, 40
	love.graphics.rectangle("line", x, y, w, h)
	drawCenteredText(x, y, w, h, "I print my LÖVE")
end

Notes

In version 0.8.0 and older, love.graphics.print stops at the first '\0' (null) character. This can bite you if you are appending keystrokes to form your string, as some of those are multi-byte unicode characters which will likely contain null bytes.

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.print&oldid=26881"