Difference between revisions of "love.graphics.newImage"

(Created page)
(→‎Load image if it exists)
 
(12 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
{{newin|[[0.11.0]]|110|type=function}}
+
Creates a new [[Image]] from a filepath, [[FileData]], an [[ImageData]], or a [[CompressedImageData]], and optionally generates or specifies mipmaps for the image.
−
Creates a new [[TextureType|cubemap]] [[Image]].
+
 
 +
Version [[11.0]] updated love.graphics.newImage to treat file names ending with "@2x", "@3x", etc. as a pixel density scale factor if none is explicitly supplied.
 
{{newobjectnotice}}
 
{{newobjectnotice}}
−
 
−
Cubemap images have 6 faces (sides) which represent a cube. They can't be rendered directly, they can only be used in [[Shader]] code (and sent to the shader via [[Shader:send]]).
 
−
 
−
To use a cubemap image in a Shader, it must be declared as a <code>CubeImage</code> or <code>samplerCube</code> type (instead of <code>Image</code> or <code>sampler2D</code>). The <code>Texel(CubeImage image, vec3 direction)</code> shader function must be used to get pixel colors from the cubemap. The vec3 argument is a normalized direction, rather than explicit texture coordinates.
 
−
 
−
Each face in a cubemap image must have square dimensions.
 
−
 
−
For variants of this function which accept a single image containing multiple cubemap faces, they must be laid out in one of the following forms in the image:
 
−
<source lang="lua">
 
−
  +y
 
−
+z +x -z
 
−
  -y
 
−
  -x
 
−
</source>
 
−
or:
 
−
<source lang="lua">
 
−
  +y
 
−
-x +z +x -z
 
−
  -y
 
−
</source>
 
−
or:
 
−
<source lang="lua">
 
−
+x
 
−
-x
 
−
+y
 
−
-y
 
−
+z
 
−
-z
 
−
</source>
 
−
or:
 
−
<source lang="lua">
 
−
+x -x +y -y +z -z
 
−
</source>
 
  
 
== Function ==
 
== Function ==
−
Creates a cubemap Image given a single image file containing multiple cube faces.
 
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
image = love.graphics.newCubeImage( filename, settings )
+
image = love.graphics.newImage( filename, settings )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
−
{{param|string|filename|The filepath to a cubemap image file (or a [[File]], [[FileData]], or [[ImageData]]).}}}
+
{{param|string|filename|The filepath to the image file (or a [[FileData]] or [[ImageData]] or [[CompressedImageData]] or [[ByteData]] object).}}
−
{{param|table|settings (nil)|Optional table of settings to configure the cubemap image, containing the following fields:}}
+
{{New feature|0.10.0|
−
{{subparam|boolean|mipmaps (false)|True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a [[PixelFormat|compressed texture]] format.}}
+
{{param|table|settings (nil)|Optional table of settings to configure the image, containing the following fields:}}
 +
{{subparam|boolean|mipmaps (false)|If true, mipmaps for the image will be automatically generated (or taken from the images's file if possible, if the image originated from a [[CompressedImageData]]).}}
 
{{subparam|boolean|linear (false)|True to treat the image's pixels as linear instead of sRGB, when [[love.graphics.isGammaCorrect|gamma correct rendering]] is enabled. Most images are authored as sRGB.}}
 
{{subparam|boolean|linear (false)|True to treat the image's pixels as linear instead of sRGB, when [[love.graphics.isGammaCorrect|gamma correct rendering]] is enabled. Most images are authored as sRGB.}}
 +
{{New feature|11.0|
 +
{{subparam|number|dpiscale (1)|The DPI scale to use when drawing the image and calling [[Texture:getWidth|getWidth]]/[[Texture:getHeight|getHeight]].}}
 +
|110}}
 +
|100}}
 
=== Returns ===
 
=== Returns ===
−
{{param|Image|image|An cubemap Image object.}}
+
{{param|Image|image|A new Image object which can be drawn on screen.}}
  
 
== Function ==
 
== Function ==
−
Creates a cubemap Image given a different image file for each cube face.
+
{{newinoldin|[[0.9.1]]|091|[[0.10.0]]|100|type=variant}}
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
image = love.graphics.newCubeImage( faces, settings )
+
image = love.graphics.newImage( filename, format )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
−
{{param|table|faces|A table containing 6 filepaths to images (or [[File]], [[FileData]], [[ImageData]], or [[CompressedImageData]] objects), in an array. Each face image must have the same dimensions. A table of tables can also be given, where each sub-table contains all mipmap levels for the cube face index of that sub-table.}}
+
{{param|string|filename|The filepath to the image file (or a [[FileData]] or [[ImageData]] or [[CompressedImageData]] object.)}}
−
{{param|table|settings (nil)|Optional table of settings to configure the cubemap image, containing the following fields:}}
+
{{param|TextureFormat|format|The format to interpret the image's data as.}}
−
{{subparam|boolean|mipmaps (false)|True to make the image use mipmaps, false to disable them. Mipmaps will be automatically generated if the image isn't a [[PixelFormat|compressed texture]] format.}}
 
−
{{subparam|boolean|linear (false)|True to treat the image's pixels as linear instead of sRGB, when [[love.graphics.isGammaCorrect|gamma correct rendering]] is enabled. Most images are authored as sRGB.}}
 
 
=== Returns ===
 
=== Returns ===
−
{{param|Image|image|An cubemap Image object.}}
+
{{param|Image|image|An Image object which can be drawn on screen.}}
 +
 
 +
== Examples ==
 +
=== Draw a bunny on the screen ===
 +
<source lang="lua">
 +
function love.load()
 +
bunny = love.graphics.newImage("MyBunny.png")
 +
end
 +
function love.draw()
 +
love.graphics.draw(bunny, 0, 0)
 +
end
 +
</source>
 +
 
 +
=== Load image if it exists ===
 +
<source lang="lua">
 +
function loadImage (path)
 +
local info = love.filesystem.getInfo( path )
 +
if info then
 +
return love.graphics.newImage( path )
 +
end
 +
end
 +
 
 +
image = loadImage ("graphics/image-1.png")
 +
</source>
  
 
== See Also ==
 
== See Also ==
 
* [[parent::love.graphics]]
 
* [[parent::love.graphics]]
 +
* [[love.graphics.draw]]
 +
* [[love.graphics.newQuad]]
 
* [[Constructs::Image]]
 
* [[Constructs::Image]]
 +
* [[love.image.newImageData]]
 
[[Category:Functions]]
 
[[Category:Functions]]
 
[[Sub-Category::Object Creation| ]]
 
[[Sub-Category::Object Creation| ]]
−
{{#set:Description=Creates a new [[TextureType|cubemap]] [[Image]].}}
+
{{#set:Description=Creates a new [[Image]].}}
 +
{{#set:Since=000}}
 +
 
 
== Other Languages ==
 
== Other Languages ==
−
{{i18n|love.graphics.newCubeImage}}
+
{{i18n|love.graphics.newImage}}

Latest revision as of 18:39, 17 May 2022

Creates a new Image from a filepath, FileData, an ImageData, or a CompressedImageData, and optionally generates or specifies mipmaps for the image.

Version 11.0 updated love.graphics.newImage to treat file names ending with "@2x", "@3x", etc. as a pixel density scale factor if none is explicitly supplied.

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

image = love.graphics.newImage( filename, settings )

Arguments

string filename
The filepath to the image file (or a FileData or ImageData or CompressedImageData or ByteData object).
Available since LÖVE 0.10.0
table settings (nil)
Optional table of settings to configure the image, containing the following fields:
boolean mipmaps (false)
If true, mipmaps for the image will be automatically generated (or taken from the images's file if possible, if the image originated from a CompressedImageData).
boolean linear (false)
True to treat the image's pixels as linear instead of sRGB, when gamma correct rendering is enabled. Most images are authored as sRGB.
Available since LÖVE 11.0
number dpiscale (1)
The DPI scale to use when drawing the image and calling getWidth/getHeight.

Returns

Image image
A new Image object which can be drawn on screen.

Function

Available since LÖVE 0.9.1 and removed in LÖVE 0.10.0
This variant is not supported in earlier or later versions.

Synopsis

image = love.graphics.newImage( filename, format )

Arguments

string filename
The filepath to the image file (or a FileData or ImageData or CompressedImageData object.)
TextureFormat format
The format to interpret the image's data as.

Returns

Image image
An Image object which can be drawn on screen.

Examples

Draw a bunny on the screen

function love.load()
	bunny = love.graphics.newImage("MyBunny.png")
end
function love.draw()
	love.graphics.draw(bunny, 0, 0)
end

Load image if it exists

function loadImage (path)
	local info = love.filesystem.getInfo( path )
	if info then
		return love.graphics.newImage( path )
	end
end

image = loadImage ("graphics/image-1.png")

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.newImage&oldid=27840"