display.save()

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

Overview

Renders the display object referenced by first argument into a JPEG or PNG image and saves it as a new file. The display object must currently be in the display hierarchy or no image will be saved. If the object is a display group, all children are also rendered. The object to be saved must be on the screen and fully within the screen boundaries.

When content scaling is enabled, display.save() saves the image in the device's native resolution. For instance, if this method is used to save a 100×200 pixel display object, it may have more actual pixels when saved on a device with higher resolution.

Gotchas

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

local function saveWithDelay()
    display.save( group, "group.jpg" )
end

timer.performWithDelay( 100, saveWithDelay )

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. You can't use the display.save() function in Android applicationSuspend and applicationExit events because there are no OpenGL textures in memory to save.

Syntax

display.save( 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:

filename (required)

String. Name of the file to save as a JPEG or PNG.

baseDir (optional)

Constant. One of the following values (system.DocumentsDirectory is the default):

  • system.DocumentsDirectory
  • system.TemporaryDirectory
  • system.CachesDirectory
backgroundColor (optional)

Table. Table array with the background clear color to use. The table format can be one of the following:

{ gray } { gray, alpha } { red, green, blue } { red, green, blue, alpha }

Gray, alpha, red, green, and blue are values in the range of 0 to 1.

isFullResolution (optional)

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

jpegQuality (optional)

Number. A value between 0 and 1. The quality of the jpeg image that is saved. No affect on png. Only works on devices, not on simulators.

Syntax (Legacy)

display.save( displayObject, filename [, baseDir] )
displayObject (required)

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

filename (required)

String. Name of the file to save as a JPEG or PNG.

baseDir (optional)

Constant. One of the following values (system.DocumentsDirectory is the default):

  • system.DocumentsDirectory
  • system.TemporaryDirectory
  • system.CachesDirectory

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 )

display.save( group, { filename="entireGroup.png", baseDir=system.DocumentsDirectory, isFullResolution=true, backgroundColor={0, 0, 0, 0} } )
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 )

local baseDir = system.DocumentsDirectory
display.save( group, "entireGroup.png", baseDir )