lovr.graphics.newTexture

Edit

Creates a new Texture. Image filenames or Image objects can be used to provide the initial pixel data and the dimensions, format, and type. Alternatively, dimensions can be provided, which will create an empty texture.

texture = lovr.graphics.newTexture(filename, options)
texture = lovr.graphics.newTexture(width, height, options)
texture = lovr.graphics.newTexture(width, height, layers, options)
texture = lovr.graphics.newTexture(image, options)
texture = lovr.graphics.newTexture(images, options)
texture = lovr.graphics.newTexture(blob, options)

Arguments

Name	Type	Default	Description
filename	string		The filename of an image to load.
options	table		Texture options.
.type	TextureType		The type of the texture.
.format	TextureFormat	'rgba8'	The format of the texture (ignored when images are provided).
.linear	boolean	false	Whether the texture is in linear color space instead of sRGB. Linear textures should be used for non-color data, like normal maps.
.samples	number	1	The number of samples in the texture, used for multisample antialiasing. Currently must be 1 or 4. Ignored when images are provided.
.mipmaps	*	true	The number of mipmap levels in the texture, or a boolean. If true, a full mipmap chain will be created. If false, the texture will only have a single mipmap.
.usage	table		A list of `TextureUsage` indicating how the texture will be used.
.label	string		A label for the Texture that will show up in debugging tools.

Returns

Name	Type	Description
texture	Texture	The new Texture.

Arguments

Name	Type	Default	Description
width	number		The width of the Texture, in pixels.
height	number		The height of the Texture, in pixels.
options	table		Texture options.
.type	TextureType		The type of the texture.
.format	TextureFormat	'rgba8'	The format of the texture (ignored when images are provided).
.linear	boolean	false	Whether the texture is in linear color space instead of sRGB. Linear textures should be used for non-color data, like normal maps.
.samples	number	1	The number of samples in the texture, used for multisample antialiasing. Currently must be 1 or 4. Ignored when images are provided.
.mipmaps	*	true	The number of mipmap levels in the texture, or a boolean. If true, a full mipmap chain will be created. If false, the texture will only have a single mipmap.
.usage	table		A list of `TextureUsage` indicating how the texture will be used.
.label	string		A label for the Texture that will show up in debugging tools.

Returns

Name	Type	Description
texture	Texture	The new Texture.

Arguments

Name	Type	Default	Description
width	number		The width of the Texture, in pixels.
height	number		The height of the Texture, in pixels.
layers	number		The number of layers in the Texture.
options	table		Texture options.
.type	TextureType		The type of the texture.
.format	TextureFormat	'rgba8'	The format of the texture (ignored when images are provided).
.linear	boolean	false	Whether the texture is in linear color space instead of sRGB. Linear textures should be used for non-color data, like normal maps.
.samples	number	1	The number of samples in the texture, used for multisample antialiasing. Currently must be 1 or 4. Ignored when images are provided.
.mipmaps	*	true	The number of mipmap levels in the texture, or a boolean. If true, a full mipmap chain will be created. If false, the texture will only have a single mipmap.
.usage	table		A list of `TextureUsage` indicating how the texture will be used.
.label	string		A label for the Texture that will show up in debugging tools.

Returns

Name	Type	Description
texture	Texture	The new Texture.

Arguments

Name	Type	Default	Description
image	string		An Image object holding pixel data to load into the Texture.
options	table		Texture options.
.type	TextureType		The type of the texture.
.format	TextureFormat	'rgba8'	The format of the texture (ignored when images are provided).
.linear	boolean	false	Whether the texture is in linear color space instead of sRGB. Linear textures should be used for non-color data, like normal maps.
.samples	number	1	The number of samples in the texture, used for multisample antialiasing. Currently must be 1 or 4. Ignored when images are provided.
.mipmaps	*	true	The number of mipmap levels in the texture, or a boolean. If true, a full mipmap chain will be created. If false, the texture will only have a single mipmap.
.usage	table		A list of `TextureUsage` indicating how the texture will be used.
.label	string		A label for the Texture that will show up in debugging tools.

Returns

Name	Type	Description
texture	Texture	The new Texture.

Arguments

Name	Type	Default	Description
images	table		A table of filenames or Images to load into the Texture.
options	table		Texture options.
.type	TextureType		The type of the texture.
.format	TextureFormat	'rgba8'	The format of the texture (ignored when images are provided).
.linear	boolean	false	Whether the texture is in linear color space instead of sRGB. Linear textures should be used for non-color data, like normal maps.
.samples	number	1	The number of samples in the texture, used for multisample antialiasing. Currently must be 1 or 4. Ignored when images are provided.
.mipmaps	*	true	The number of mipmap levels in the texture, or a boolean. If true, a full mipmap chain will be created. If false, the texture will only have a single mipmap.
.usage	table		A list of `TextureUsage` indicating how the texture will be used.
.label	string		A label for the Texture that will show up in debugging tools.

Returns

Name	Type	Description
texture	Texture	The new Texture.

Arguments

Name	Type	Default	Description
blob	Blob		A Blob object holding pixel data to load into the Texture.
options	table		Texture options.
.type	TextureType		The type of the texture.
.format	TextureFormat	'rgba8'	The format of the texture (ignored when images are provided).
.linear	boolean	false	Whether the texture is in linear color space instead of sRGB. Linear textures should be used for non-color data, like normal maps.
.samples	number	1	The number of samples in the texture, used for multisample antialiasing. Currently must be 1 or 4. Ignored when images are provided.
.mipmaps	*	true	The number of mipmap levels in the texture, or a boolean. If true, a full mipmap chain will be created. If false, the texture will only have a single mipmap.
.usage	table		A list of `TextureUsage` indicating how the texture will be used.
.label	string		A label for the Texture that will show up in debugging tools.

Returns

Name	Type	Description
texture	Texture	The new Texture.

Notes

If no type is provided in the options table, LÖVR will guess the TextureType of the Texture based on the number of layers:

If there's only 1 layer, the type will be 2d.
If there are 6 images provided, the type will be cube.
Otherwise, the type will be array.

Note that an Image can contain multiple layers and mipmaps. When a single Image is provided, its layer count will be used as the Texture's layer count.

If multiple Images are used to initialize the Texture, they must all have a single layer, and their dimensions, format, and mipmap counts must match.

When providing cubemap images in a table, they can be in one of the following forms:

{ 'px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png' }
{ right = 'px.png', left = 'nx.png', top = 'py.png', bottom = 'ny.png', back = 'pz.png', front = 'nz.png' }
{ px = 'px.png', nx = 'nx.png', py = 'py.png', ny = 'ny.png', pz = 'pz.png', nz = 'nz.png' }

(Where 'p' stands for positive and 'n' stands for negative).

If no usage is provided in the options table, LÖVR will guess the TextureUsage of the Texture. The sample usage is always included, but if the texture was created without any images then the texture will have the render usage as well.

The supported image formats are png, jpg, hdr, dds, ktx1, ktx2, and astc.

If image data is provided, mipmaps will be generated for any missing mipmap levels.

Guides

Examples

Modules

Objects

Callbacks

Functions

Types

lovr.graphics.newTexture

Arguments

Returns

Arguments

Returns

Arguments

Returns

Arguments

Returns

Arguments

Returns

Arguments

Returns

Notes

See also