graphics.newTexture()

Type Function
Library graphics.*
Return value TextureResource
Revision 2017.3113
Keywords textures, performance optimization, texture memory, images
See also graphics.releaseTextures()
texture:releaseSelf()
Texture Loading/Management (guide)
TextureResource

Overview

Creates a TextureResource object which allows you to access and manage textures. This can be used to pre-load a texture/image and prevent it from being disposed when there is no display object using it.

After the TextureResource object is created, you can use it in texture-related instances by specifying the filename and baseDir properties.

Important

There are several important nuances you should understand before using TextureResource objects — see the next section for details.

Gotchas

Syntax

graphics.newTexture( params )
params (required)

Table. Table containing the required parameters for the TextureResource object — see the next section for details.

Parameter Reference

type (required)

String. The type of the texture to be created. Depending on this value, other key-value parameters will be taken into account (inspect carefully below).

  • "image" — Creates a TextureResource object of type TextureResourceBitmap. Objects of this type are used to pre-load and cache textures based on real images within the project's file system.
local imageTexture = graphics.newTexture( { type="image", filename="icon.png", baseDir=system.ResourceDirectory } )
  • "canvas" — Creates a TextureResource object of type TextureResourceCanvas. This texture resource is an in-memory texture which can be modified by rendering display objects to it.
local canvasTexture = graphics.newTexture( { type="canvas", width=128, height=128 } )
filename (required)

String. Only applies when type is "image". Indicates the name of the image file to load, relative to baseDir (system.ResourceDirectory by default).

baseDir (optional)

Constant. Only applies when type is "image". Specifies the base directory where filename is located. Options include system.ResourceDirectory, system.DocumentsDirectory, system.ApplicationSupportDirectory, system.TemporaryDirectory and system.CachesDirectory. Default is system.ResourceDirectory.

width (required)

Number. Only applies when type is "canvas". Specifies the width in which objects can be rendered within a TextureResourceCanvas.

height (required)

Number. Only applies when type is "canvas". Specifies the height in which objects can be rendered within a TextureResourceCanvas.

pixelWidth (optional)

Number. Only applies when type is "canvas". Specifies the horizontal pixel dimensions of the texture that the canvas resource is rendered to.

pixelHeight (optional)

Number. Only applies when type is "canvas". Specifies the vertical pixel dimensions of the texture that the canvas resource is rendered to.

Examples

Pre-loading Images
-- Create "TextureResource" object of type "TextureResourceBitmap"
local backgroundTexture = graphics.newTexture( { type="image", filename="background.png" } )

-- Create display object with the pre-loaded texture
local background = display.newImageRect(
    backgroundTexture.filename,  -- "filename" property required
    backgroundTexture.baseDir,   -- "baseDir" property required
    display.contentWidth,
    display.contentHeight
)
background.x = display.contentCenterX
background.y = display.contentCenterY

-- If you no longer need the texture, release it to prevent memory leaks
backgroundTexture:releaseSelf()

-- Alternatively, release all texture objects of a specific type
graphics.releaseTextures( { type="image" } )
Render to Canvas Resource
local tex = graphics.newTexture( { type="canvas", width=128, height=128 } )

-- Create display object with texture as contents
local rect = display.newImageRect(
    tex.filename,  -- "filename" property required
    tex.baseDir,   -- "baseDir" property required
    display.contentWidth,
    display.contentHeight
)
rect.x = display.contentCenterX
rect.y = display.contentCenterY

-- Create a circle and draw/render it to the texture
local circ = display.newCircle( 0, 0, 64 )
circ:setFillColor( { type="gradient", color1={0,0.2,1}, color2={0.8,0.8,0.8}, direction="down" } )
tex:draw( circ )

-- Schedule texture objects to be rendered to texture before next frame
tex:invalidate()