display.newSnapshot()

Type Function
Library display.*
Return value SnapshotObject
Revision Release 2024.3703
Keywords snapshot
See also Snapshots (guide)

Overview

Snapshot objects let you capture a group of display objects and render them into a flattened image. The image is defined by objects that are added to the snapshot's group property.

Learn more about snapshots in the Snapshots guide.

Gotchas

Android

When an app is suspended, the Android OS removes all OpenGL textures from memory. When the app is resumed, Corona must reload all images, but the capture image no longer exists in memory. If you need to restore a snapshot image in Android, one solution is to save the returned capture image to file via the display.save() function. Note that this should be done immediately, not during the "applicationSuspend" or "applicationExit" system events (at those times, there will be no OpenGL textures in memory to save).

Syntax

display.newSnapshot( [parent,] w, h )
parent (optional)

GroupObject. An optional display group in which to insert the snapshot.

w / h (required)

Number. Width and height of the snapshot.

Example

local snapshot = display.newSnapshot( 200, 200 )

math.randomseed( 0 )

-- Add fish to the screen
for i=1,4 do
    local fish = display.newImage( "fish.small.red.png" )

    -- move to random position in a 200x200 region in the middle of the screen
    fish:translate( math.random( -100, 100 ), math.random( -100, 100 ) )

    -- insert fish into snapshot
    snapshot.group:insert( fish )
end

snapshot:translate( halfW, halfH )  -- Center snapshot
snapshot:invalidate()               -- Invalidate snapshot
snapshot.alpha = 0.5                -- Apply to flattened image