display.capture()

Type Function
Library display.*
Return value DisplayObject
Revision Current Public Release (2015.2731)
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:

  • Save the returned capture image to file via the display.save() function. Note that you can't use the display.save() function in Android "applicationSuspend" and "applicationExit" events because there are no OpenGL textures in memory to save.
  • Display the image saved to file via display.newImageRect(), using the captured object's bounds.

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, for example when main.lua is executed to initialize the app, you must call display.capture() within a timer.performWithDelay() call. A delay of at least 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 capture.

options (optional)

Table. A table of options for the capture — see the next section for details.

Options Reference

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 entire object/group is captured, even parts which are not visible on screen. If omitted, the capture will be constrained to the screen bounds.

Syntax (Legacy)

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

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

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.

Example

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 )

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