TextureResourceCanvas

Overview

The object created by graphics.newTexture() when the specified type is "canvas". This texture resource is an in-memory texture which can be modified by rendering display objects to it. It is similar to a framebuffer object or a render target texture.

Properties

Methods

Gotchas

• All objects of this type are subject to manual texture management. In order to free them from memory, you must release them when they are no longer required.

• On Android, textures are released when the application is suspended. This causes them to be cleared and they will become invalid when the application is resumed. You can restore the contents of a texture by using texture:invalidate( "cache" ) (documentation) assuming the cache was not manipulated manually.

Example

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

-- Set background color to be applied if texture is cleared
tex:setBackground( 0, 0, 1 )

-- 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 )

-- Create a polygon and draw/render it to the texture
local poly = display.newPolygon( 0, 0, {0,-55,14,-18,52,-18,22,8,32,45,0,22,-32,45,-22,8,-52,-18,-14,-18} )
poly:setFillColor( 0.2, 1, 0.2 )
tex:draw( poly )

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

-- Function to restore texture on resume
local function onSystemEvent( event )
    if ( event.type == "applicationResume" ) then
        tex:invalidate( "cache" )
    end
end

-- Set up a system event listener
Runtime:addEventListener( "system", onSystemEvent )