display.save()

Type Function
Library display.*
Return value none
Revision Current Public Release (2014.2189)
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 dynamic 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 (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 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
isFullResolution (optional)

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

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 } )
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 )