display.captureBounds()

Type Function
Library display.*
Return value DisplayObject
Revision Release 2022.3683
Keywords screenshot, capture bounds, save bounds
See also display.save()
display.capture()
display.captureScreen()

Overview

Captures a portion of the screen and returns it as a new DisplayObject. You can specify what portion of the screen to capture by passing in rectangular bounds. You can optionally save the capture image as a file to the device's photo library.

Calling this method places the captured image on the screen in front of other display objects. Use object:removeSelf() to remove this object from the screen.

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 as 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 as 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.captureBounds() within a timer.performWithDelay() call. A delay of at least 100 milliseconds is recommended.

local function captureWithDelay()
    local screenBounds =
    {
        xMin = 0,
        xMax = 100,
        yMin = 0,
        yMax = 100,
    }
    local capture = display.captureBounds( screenBounds )
end

timer.performWithDelay( 100, captureWithDelay )

Syntax

display.captureBounds( screenBounds [, saveToPhotoLibrary] )
screenBounds (required)

Table. Specifies the portion of the screen to capture as a rectangle whose bounds are in content coordinates. This table must contain the following properties or else an error will occur.

local screenBounds =
{
    xMin = 0,
    xMax = 100,
    yMin = 0,
    yMax = 100
}

You can also pass in the bounds table returned by an object.contentBounds property, which will capture that object and everything behind it.

Note that this capture function can only capture what is displayed on screen. If the coordinates in this bounds table exceed the bounds of the screen, then the resulting capture image will be trimmed to the bounds of the screen. If the bounds table is completely outside of the screen, then this function will do nothing and return nil.

saveToPhotoLibrary (optional)

Boolean. If true, then it adds the image to your device's photo library. For Android and iOS devices, this also necessitates the requirements outlined in Gotchas.

Examples

Capture Bottom-Right Quadrant
-- Set up a bounds table for capturing the bottom-right quadrant of the screen
local screenBounds =
{
    xMin = display.contentWidth / 2,
    xMax = display.contentWidth,
    yMin = display.contentHeight / 2,
    yMax = display.contentHeight
}

-- Capture the bounds of the screen
local myCaptureImage = display.captureBounds( screenBounds )
Capture Display Object Bounds
-- Display a circle at the center of the screen
local myCircle = display.newCircle( 0, 0, 50 )
myCircle.x = display.contentWidth / 2
myCircle.y = display.contentHeight / 2

-- Capture the above circle object
local myCaptureImage = display.captureBounds( myCircle.contentBounds )
Write Capture to Photo Library
-- Capture the entire stage, minus the letterbox area
-- To save to the photo library, you must set the second argument to true
local myCaptureImage = display.captureBounds( display.currentStage.contentBounds, true )

-- Remove the returned capture image since we're only interested in saving to the photo library
-- Doing this immediately after the above function call prevents it from being drawn on screen
myCaptureImage:removeSelf()
myCaptureImage = nil