display.capture()

Type Function
Library display.*
Return value DisplayObject
Revision Current Public Release (2014.2189)
Keywords screenshot, capture screen, save screen
See also display.save()
display.captureBounds()
display.captureScreen()

Overview

This function is the same as display.save(), but it returns a display object instead of saving to a file by default. You can optionally save the capture to the device's photo library, but this is not the default action — you must explicitly tell it to do so when calling the function.

display.capture() can be thought of as a hybrid between display.save() and display.captureScreen().

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 captured image in Android, one solution is as follows:

Note: You can't use the display.save() function in Android applicationSuspend and applicationExit events because there are no OpenGL textures in memory to save.

In addition, when saving to the photo album on Android, you must set the following permission in the build.settings file.

settings =
{
    android =
    {
        usesPermissions =
        {
            "android.permission.WRITE_EXTERNAL_STORAGE",
        },
    },
}

Mac

Saves screen capture images as JPEG files to the current user's desktop.

Windows

Saves screen capture images as PNG files to the My Pictures\Corona Simulator directory.

Capture on Launch

If you need to capture a display object on application launch (i.e. when main.lua is executed to initialize the app) you must call display.capture() within a timer.performWithDelay call. A delay of 100 milliseconds is recommended.

local myObject1 = display.newRect( 50, 50, 100, 150 )

local function captureWithDelay()
    local capture = display.capture( myObject1 )
end

timer.performWithDelay( 100, captureWithDelay )

Syntax

display.capture( displayObject, options )
displayObject (required)

DisplayObject. The variable that references the display object/group to save.

In this modern syntax, options is a table that accepts the following parameters:

saveToPhotoLibrary (optional)

Boolean. If true, then it adds the image to your device's photo album (PNG file). For Android devices, you must set the permission level as shown in Gotchas.

isFullResolution (optional)

Boolean. If true, the image is not cropped to the size of the screen of the device.

Syntax (Legacy)

display.capture( displayObject [, saveToPhotoLibrary ] )
displayObject (required)

DisplayObject. The variable that references the display object/group to save.

saveToPhotoLibrary (optional)

Boolean. If true, then it adds the image to your device's photo album (PNG file). For Android devices, you must set the permission level as shown in Gotchas.

Examples

Full Resolution
local myObject1 = display.newRect( 50, 50, 100, 150 ) -- Create a rectangle object
local myObject2 = display.newCircle( 100, 300, 50 )   -- Create a circle object

local group = display.newGroup()

group:insert( myObject1 )
group:insert( myObject2 )

-- save the entire group as a new display object
local combined = display.capture( group, { saveToPhotoLibrary=true, isFullResolution=true } )

-- position the new display object
combined.x, combined.y = 100, 100

-- remove it
combined:removeSelf()
combined = nil
Legacy Syntax
local myObject1 = display.newRect( 50, 50, 100, 150 ) -- Create a rectangle object
local myObject2 = display.newCircle( 100, 300, 50 )   -- Create a circle object

local group = display.newGroup()

group:insert( myObject1 )
group:insert( myObject2 )

-- save the entire group as a new display object
local combined = display.capture( group )

-- position the new display object
combined.x, combined.y = 100, 100

-- remove it
combined:removeSelf()
combined = nil