Difference between revisions of "love.graphics.newImage"

m (→‎Function)
(Created page)
Line 1: Line 1:
−
Creates a new [[Image]] from a filepath, [[FileData]], an [[ImageData]], or a [[CompressedImageData]], and optionally generates or specifies mipmaps for the image.
+
{{newin|[[0.11.0]]|110|type=function}}
 +
Creates a new [[TextureType|cubemap]] [[Image]].
 
{{newobjectnotice}}
 
{{newobjectnotice}}
−
== Function ==
+
 
−
=== Synopsis ===
+
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">
 
<source lang="lua">
−
image = love.graphics.newImage( filename )
+
  +y
 +
-x +z +x -z
 +
  -y
 
</source>
 
</source>
−
=== Arguments ===
+
or:
−
{{param|string|filename|The filepath to the image file.}}
 
−
=== Returns ===
 
−
{{param|Image|image|An Image object which can be drawn on screen.}}
 
−
 
 
−
== Function ==
 
−
=== Synopsis ===
 
 
<source lang="lua">
 
<source lang="lua">
−
image = love.graphics.newImage( imageData )
+
+x
 +
-x
 +
+y
 +
-y
 +
+z
 +
-z
 
</source>
 
</source>
−
=== Arguments ===
+
or:
−
{{param|ImageData|imageData|An ImageData object. The Image will use this ImageData to reload itself when [[love.window.setMode]] is called.}}
 
−
=== Returns ===
 
−
{{param|Image|image|An Image object which can be drawn on screen.}}
 
−
 
 
−
== Function ==
 
−
{{newin|[[0.9.0]]|090|type=variant}}
 
−
=== Synopsis ===
 
 
<source lang="lua">
 
<source lang="lua">
−
image = love.graphics.newImage( compressedImageData )
+
+x -x +y -y +z -z
 
</source>
 
</source>
−
=== Arguments ===
 
−
{{param|CompressedImageData|compressedImageData|A CompressedImageData object. The Image will use this CompressedImageData to reload itself when [[love.window.setMode]] is called.}}
 
−
=== Returns ===
 
−
{{param|Image|image|An Image object which can be drawn on screen.}}
 
  
 
== Function ==
 
== Function ==
−
{{newin|[[0.10.0]]|100|type=variant}}
+
Creates a cubemap Image given a single image file containing multiple cube faces.
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
image = love.graphics.newImage( filename, flags )
+
image = love.graphics.newCubeImage( filename, settings )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
−
{{param|string|filename|The filepath to the image file (or a [[FileData]] or [[ImageData]] or [[CompressedImageData]] object).}}
+
{{param|string|filename|The filepath to a cubemap image file (or a [[File]], [[FileData]], or [[ImageData]]).}}}
−
{{param|table|flags|A table containing the following fields:}}
+
{{param|table|settings (nil)|Optional table of settings to configure the cubemap image, containing the following fields:}}
−
{{subparam|boolean|linear (false)|True if the image's pixels should be interpreted as being linear RGB rather than sRGB-encoded, if [[love.graphics.isGammaCorrect|gamma-correct rendering]] is enabled. Has no effect otherwise.}}
+
{{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 or table|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]]). If this value is a table, it should contain a list of other filenames of images of the same format that have progressively half-sized dimensions, all the way down to 1x1. Those images will be used as this Image's mipmap levels.}}
+
{{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|A new Image object which can be drawn on screen.}}
+
{{param|Image|image|An cubemap Image object.}}
  
 
== Function ==
 
== Function ==
−
{{newinoldin|[[0.9.1]]|091|[[0.10.0]]|100|type=variant}}
+
Creates a cubemap Image given a different image file for each cube face.
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
image = love.graphics.newImage( filename, format )
+
image = love.graphics.newCubeImage( faces, settings )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
−
{{param|string|filename|The filepath to the image file (or a [[FileData]] or [[ImageData]] or [[CompressedImageData]] object.)}}
+
{{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|TextureFormat|format|The format to interpret the image's data as.}}
+
{{param|table|settings (nil)|Optional table of settings to configure the cubemap image, containing the following fields:}}
 +
{{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 Image object which can be drawn on screen.}}
+
{{param|Image|image|An cubemap Image object.}}
  
 
== See Also ==
 
== See Also ==
Line 64: Line 69:
 
[[Category:Functions]]
 
[[Category:Functions]]
 
[[Sub-Category::Object Creation| ]]
 
[[Sub-Category::Object Creation| ]]
−
{{#set:Description=Creates a new [[Image]].}}
+
{{#set:Description=Creates a new [[TextureType|cubemap]] [[Image]].}}
−
{{#set:Since=000}}
 
 
== Other Languages ==
 
== Other Languages ==
−
{{i18n|love.graphics.newImage}}
+
{{i18n|love.graphics.newCubeImage}}

Revision as of 16:04, 25 March 2018

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

Creates a new cubemap Image.

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!  



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 CubeImage or samplerCube type (instead of Image or sampler2D). The Texel(CubeImage image, vec3 direction) 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: 

   +y
+z +x -z
   -y
   -x

or: 

   +y
-x +z +x -z
   -y

or: 

+x
-x
+y
-y
+z
-z

or: 

+x -x +y -y +z -z

Function

Creates a cubemap Image given a single image file containing multiple cube faces.

Synopsis

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

Arguments

string filename
The filepath to a cubemap image file (or a File, FileData, or ImageData).}
table settings (nil)
Optional table of settings to configure the cubemap image, containing the following fields:
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 compressed texture format.
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.

Returns

Image image
An cubemap Image object.

Function

Creates a cubemap Image given a different image file for each cube face.

Synopsis

image = love.graphics.newCubeImage( faces, settings )

Arguments

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.
table settings (nil)
Optional table of settings to configure the cubemap image, containing the following fields:
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 compressed texture format.
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.

Returns

Image image
An cubemap Image object.

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 "http://www.love2d.org/w/index.php?title=love.graphics.newImage&oldid=21193"