display.capture()

Type Function
Library display.*
Return value DisplayObject
Revision Release 2024.3703
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.

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

Note

This capture function will only capture what is rendered in OpenGL. It will not capture native display objects such as text input boxes/fields, web popups, ads, etc.

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, if you include the saveToPhotoLibrary option with a value of true, you must set the following permission in the build.settings file:

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

iOS

On iOS, if you include the saveToPhotoLibrary option with a value of true, you must include the following keys/descriptions in the plist table of build.settings. When the system prompts the user to allow access, the associated description is displayed as part of the alert. Note that these descriptions can be customized to your preference and they can even be localized (guide).

settings =
{
    iphone =
    {
        plist =
        {
            NSPhotoLibraryUsageDescription = "This app would like to access the photo library.",
            NSPhotoLibraryAddUsageDescription = "This app would like to add the photo library.",
        },
    },
}

macOS

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

Note that if you plan to submit your application to the Mac App Store, it will be sandboxed. This means that special entitlements for read/write files in the Pictures folder must be requested. To do this, simply add an entitlements entry within the settings → osx table of build.settings as indicated below. For further details, see Apple's documentation.

settings = 
{
    osx = {
        entitlements = {
            ["com.apple.security.assets.pictures.read-write"] = true,
        },
    },
}

Windows

Saves screen capture images as PNG files to the user's My Pictures directory under a subdirectory named after the Corona app. For the Corona Simulator, this directory will be My Pictures\Corona Simulator. For Corona-built desktop apps, this directory will be My Pictures\<AppName>.

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 and iOS devices, this also necessitates the requirements outlined in Gotchas.

captureOffscreenArea (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. For legacy compatibility purposes, the deprecated isFullResolution option name can be used with the same effect.

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 and iOS devices, this also necessitates the requirements outlined 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, captureOffscreenArea=true } )

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

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