Type Function Library graphics.* Return value TextureResource Revision 2017.3060 Keywords textures, performance optimization, texture memory, images See also graphics.releaseTextures() texture:releaseSelf() Texture Loading/Management (guide) TextureResource
Creates a TextureResource object which allows you to access and manage textures. This can be used to
After the TextureResource object is created, you can use it in
There are several important nuances you should understand before using TextureResource objects — see the next section for details.
TextureResource objects created with graphics.newTexture() will not be automatically disposed/released, even if there are no display objects using the texture. This can lead to memory leaks, so you should handle this task manually. Individually, texture resource objects can be disposed/released via texture:releaseSelf(), or in a wider scope, graphics.releaseTextures() can be used to release all texture objects sharing the same type property.
TextureResource objects have filename and baseDir properties which can be used to refer to the underlying texture. These "background.png" as the filename for the texture, do not attempt to use texture.filename as a reference to the same file in system.pathForFile(). Essentially, these properties refer to internal memory, not the file system.
If you don't need to maintain reference to a TextureResource object, it is recommended that you dispose/release it. If any display objects are currently using the released texture, they will not be corrupted — instead, they will hold on to the texture under the hood, and if/when they are removed, the texture will be automatically disposed.
Calling graphics.newTexture() multiple times with reference to the same file will not create unique TextureResource objects. Thus, if you call texture:releaseSelf() on any texture resource object, it will be disposed/removed from memory, and all other pointers to graphics.newTexture() which used the same file will become nil.
graphics.newTexture( params )
Table. Table containing the required parameters for the TextureResource object — see the next section for details.
String. The type of the texture to be created. Depending on this value, other
"image" — Creates a TextureResource object of type TextureResourceBitmap. Objects of this type are used to 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 local canvasTexture = graphics.newTexture( { type="canvas", width=128, height=128 } )
String. Only applies when type is "image". Indicates the name of the image file to load, relative to baseDir (system.ResourceDirectory by default).
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.
Number. Only applies when type is "canvas". Specifies the width in which objects can be rendered within a TextureResourceCanvas.
Number. Only applies when type is "canvas". Specifies the height in which objects can be rendered within a TextureResourceCanvas.
Number. Only applies when type is "canvas". Specifies the horizontal pixel dimensions of the texture that the canvas resource is rendered to.
Number. Only applies when type is "canvas". Specifies the vertical pixel dimensions of the texture that the canvas resource is rendered to.
-- 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" } )
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()