display.captureScreen( )

Description:

Captures the contents of the screen and returns it as an image object positioned so that the top-left of the screen is at the origin.

Note1: Calling this method displays the captured image on the screen on top of all other display objects. Use object:removeSelf() to remove this object from the screen.

Note2: Screen capture only works for openGL content and not for any of the native display objects.

Syntax:

object = display.captureScreen( saveToAlbum )

Example:

display.setStatusBar( display.HiddenStatusBar ) 
 
-- Fill the screen with a green rectangle
local rect = display.newRect(0, 0, display.contentWidth, display.contentHeight)
rect:setFillColor(0, 255, 0) 
 
-- Draw a circle on the screen
local circle = display.newCircle(155, 100, 36)
circle:setFillColor(255, 0, 0) 
 
-- Capture the screen
local screenCap = display.captureScreen( true )
 
-- Remove the objects from the screen
rect:removeSelf()
circle:removeSelf()
 
-- Scale the screen capture, now on the screen, to half it's size
screenCap:scale(.5,.5)
 
-- Alert the user to look in the library (device) 
-- or on the desktop (simulator) for the screen capture
local alert = native.showAlert( "Success", "Screen Capture Saved to Library", { "OK" } )

Parameters:

saveToAlbum
boolean: If true, then it adds the image to your device’s Photo album (jpeg file); on the simulator, it saves to the desktop (png file). (For Android devices, you must set the permission level as shown in the remarks section below.)

Returns:

image object

Remarks:

Higher resolution image saved to jpeg file in build #299.

Note: There is a problem with screen captures when the device orientation is different from the initial orientation. There is also a problem capturing the entire screen on iPad and iPhone4 devices when Dynamic Scaling (in config.lua) is enabled. [case #928]

If the saveToAlbum parameter is true, you must set the permission level in the build.settings file for Android devices.

1
2
3
4
5
6
7
settings =
{
   androidPermissions =
   {
       "android.permission.WRITE_EXTERNAL_STORAGE"
   },
}

Note: Doing a screen capture in landscape mode incorrectly captures the screen as a portrait. [case #928]

Windows build #518
- Saves screen capture image to Window's "My Pictures\Corona Simulator" directory if display.captureScreen(true) is called.
- Saves screen shots in PNG format.
- Automatically names files names to "Picture #.png", where # is set to a unique number in the directory.
- It never overwrites an existing image file.
- Saves up to 10,000 files. That is, it'll never go beyond "Picture 10000.png".

Supported on operating systems and platforms for build numbers shown:
  • Mac OS X:
    Corona SDK 1.0
  • Windows:
    Build 2011.484
  • iOS:
    Corona SDK 1.0
  • Android:
    Build 2011.591

Replies

paulallanharrington
User offline. Last seen 3 years 8 weeks ago. Offline
Joined: 14 Jan 2011

-The documentation states:

Parameters:

saveToAlbum
boolean: If true, then it adds the image to your device’s album (jpeg file); on the simulator, it saves to the desktop.

-Questions:

What does it do if you pass it false?

Will this function be expanded so that you can specify other locations (e.g. system.DocumentsDirectory or system.TemporaryDirectory) or is this function to be accomplished via display.save?

Sincerely,

Paul Allan Harrington
http://www.pahgroup.com

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

Calling display.captureScreen(false) causes it to not save the screen capture to file, but it will still return the capture image object and display the capture image onscreen. This is the equivalent of calling dislay.captureScreen() without an argument.

If you want to save a capture image file to another location, then you need to use the display.save() function.

See sample application "Storage\ScreenCaptureToFile" included with the Corona SDK to get a better idea on how this API works.

suyuen
User offline. Last seen 8 years 9 weeks ago. Offline
Joined: 28 May 2011

Hi! Would like to ask if there is a way to capture not only what is shown on screen, but rather the whole game stage area?

Is it possible? I'm not sure how to go about it at the moment. Any pointers would be appreciated! :)

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

Hello suyuen,

Unfortunately, there is no way to do this at the moment. Our display.save() and display.captureScreen() can only capture the pixels shown on the display. Capturing a display object that is outside of the display via the display.save() function will show black colors in the image. This is because we're using the capture function from OpenGL. While it is possible to render to an offscreen surface in OpenGL to work-around this limitation, unfortunately, this does not work on most Android devices based on our testing.

jwwtaker
User offline. Last seen 2 years 19 weeks ago. Offline
Joined: 28 Apr 2010

currently i'm trying to get a screenshot of what the user has done, which includes typing in text that is being rendered via newTextBox. the captureScreen(true) captures the background image and all objects on screen but the text the user has typed in is missing. Is there any way to get a screenshot that includes the users text?

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

jwwtaker,

display.captureScreen() will only capture what is rendered in OpenGL. It won't capture native fields such as TextBoxes. Nor will it capture any UI popups. I'm sorry, but there aren't any work-arounds for this.

jwwtaker
User offline. Last seen 2 years 19 weeks ago. Offline
Joined: 28 Apr 2010

is there any way to do a render of some sort on the text that would convert the text into something that could be captured, akin to photoshops flatten text method. it stops the field being editable anymore and turns it basically into a graphic. it's super important for a customer so any ideas for hack solution would be highly appreciated, thanks.

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

jwwtaker, assuming that you're talking about Android and not iOS...

If you just want to take a screen shot for feedback purposes, then you can use the Android SDK's "ddms" tool. This tool has the ability to take screenshots of what is actively displayed on the device connected to the computer via USB. See the following link for details...
http://developer.android.com/guide/developing/debugging/ddms.html

Galaxy Tabs have a secret screen capture feature which occurs when you hold down the back button until the device vibrates and then you press the power button.

Otherwise, I don't have any other work-around. We're not prepared to make major changes to our screen capture code... and honestly, I'm not sure what our options are for capturing the final frame buffer rendered on the device's screen including OpenGL and native fields (my Google search results indicate it involves rooting the device).

davidJames
User offline. Last seen 3 years 12 weeks ago. Offline
Joined: 9 Aug 2011

Question regarding the saveToAlbum feature. On my HTC Desire S, my captured images don't get stored into the default "Gallery" folder on my phone. Instead, they show up on my phone's SD card under the "/Pictures" folder. Also, it only saves one image and titles it "corona_image". On my iPhone I have no problems at all with this feature. I'm wondering if the default photo album location is different on every Android device? If so, is there a fix for this?

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

djtan42,

Regarding this function saving to the save image file instead of unique file names is a known issue that is already on our to-do list.

Regarding it saving to the Pictures folder, this is supposed to be the default folder for images on the SD card on Android. We actually request the photo directory from Android from the following API...
http://developer.android.com/sdk/api_diff/8/changes/android.os.Environment.html

koolou7
User offline. Last seen 7 years 41 weeks ago. Offline
Joined: 25 Apr 2011

Is there any api to make a gif format photo, and save it?

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

Corona cannot save image files to GIF. On iOS, I it saves screen captures as JPEGs and on Android it saves them as PNGs. Currently, you cannot control the image format that the file is saved as.

vanko
User offline. Last seen 6 years 49 weeks ago. Offline
Joined: 27 Jan 2011

I'm noticing the same issue where it saves to /pictures and only provides one name. I hope there's a workaround soon...

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

Everyone,

We've fixed display.captureScreen(true) on Android. It will no longer overwrite the last image file in the Photo Library and will instead always generate unique image file names using the following naming convention...
"<ApplicationName> Picture <Number>.png"

The above fix will be made available in the next daily build #672.

tmapps
User offline. Last seen 12 weeks 17 hours ago. Offline
Joined: 9 Feb 2011

Great news!!! Thanks!!

tmapps
User offline. Last seen 12 weeks 17 hours ago. Offline
Joined: 9 Feb 2011

Hi Joshua,
I've just tested this new feature on Android (naming convention) and it doesn't work.

Previous CoronaSDK release overwrote the image, but I think that this one doesn't make anything, the image isn't anywhere or I didn't find it.

I've tested it on:
- HTC Desire (gingerbread).
- HTC Wildfire S (gingerbread).
- Samsung Galaxy S (gingerbread).
- Samsung Galaxy S II (gingerbread).
- Sony Ericsson Xperia Neo (gingerbread).

The image capture didn't work in any of these devices.

In my tests, I've used captureScreen and displey.save too. No one works on these phones.

Could you help me with this?? In which directory should the image be stored?
Regards!!

tmapps
User offline. Last seen 12 weeks 17 hours ago. Offline
Joined: 9 Feb 2011

Hi again Joshua,
I've made another test with a Sony Ericsson Xperia Arc (gingerbread too).

I've obtained the same output: image is not saved anywhere :-(

Thanks!!

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

tmapps,

On Android, display.captureScreen(true) saves to the "Pictures" directory on external storage (typically the SD card) by default, but only if you set the WRITE_EXTERNAL_STORAGE permission in your build.settings file as mentioned in the Remarks section of this web page. This allows your screenshot to appear on the Android device's Gallery app. You can also view this image file using the Android SDK's ddms tool.

The display.save() function allows you to save an image file to a directory of your choosing, but only within the app's private directory branch (such as the system.DocumentsDirectory). However, these directories cannot be viewed by the Android SDK tools unless you root the Android device. This is by Google's design.

tmapps
User offline. Last seen 12 weeks 17 hours ago. Offline
Joined: 9 Feb 2011

Hi Joshua,
Thanks for your quick reply.

I've donwloaded the new last release of Corona and it works fine.

Thanks!

MagnoliaPower
User offline. Last seen 2 years 21 weeks ago. Offline
Joined: 8 Mar 2010

Hi,
is there a way to capture the native.webPopup ? I get a black square in place of the webView when I make captures.

Frédéric

Tom
User offline. Last seen 3 years 25 weeks ago. Offline
Joined: 13 Jul 2010

No, the screen capture only works for openGL content and not for any of the native display objects.

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

Frédéric,

Unfortunately no. This function is unable to capture any native objects. This is because it can only capture what is rendered in OpenGL... and native objects are rendered on top of the OpenGL surface.

MagnoliaPower
User offline. Last seen 2 years 21 weeks ago. Offline
Joined: 8 Mar 2010

Does it mean that text fields also ?

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

Correct. Text fields and text boxes are NOT captured. None of the "native" objects are captured.

doubleslashdesign
User offline. Last seen 20 weeks 6 days ago. Offline
Joined: 27 Nov 2010

just a note for people, the simulator is saving in my C:\Users\Larry\Pictures\Corona Simulator

folder - AWESOME :)

Larry
http://www.DoubleSlashDesign.com

Dr.Mabuse
User offline. Last seen 3 years 32 weeks ago. Offline
Joined: 22 Feb 2012

Don't know if it's possible, but it would be great if left, top, width and height parameters could be added to capture only part of the screen.

@RSCdev
User offline. Last seen 7 years 7 weeks ago. Offline
Joined: 6 Sep 2011

+1 for @Dr.Mabuse request as well.

Thanks,

Richards App Store
User offline. Last seen 12 weeks 2 days ago. Offline
Joined: 15 Dec 2011

I know this is the API documentation for display.captureScreen, however I have a question about a problem with display.capture, and it's probably related to this API. Should the transparency work on Kindle? This works properly on the simulator and on the Nook, but on the Kindle Fire the transparent background is being filled with Black. Is there a fix for this since it is only happening on Kindle?

Thanks!
Richards App Store

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

Richard,

This sounds like a premultiplied alpha bug that we need to take care of on our end. I suspect this same issue will occur on a Nook Tablet too, but should be okay on Nook Color. Would you mind filing a bug report on this please? You can do so via the "Report a Bug" link at the top of this web page. That way it will get on our to to-do list and we can notify you via e-mail when it is resolved.

In the meantime, you should be able to work-around this issue by using the display.save() function, save the image to a PNG file, and then load that image file via display.newImageRect(). This forces Corona to premultiply alpha when it loads the image. However, you will only want to implement this work-around on Android. Corona does not support saving images to PNG on iOS or Mac yet.

Richards App Store
User offline. Last seen 12 weeks 2 days ago. Offline
Joined: 15 Dec 2011

Ya definitely. I'll submit it right now. The work around I came up with instead was setting a mask around the circle so that the black didn't show up behind it, but I'm going to try out saving as a png too and see if that looks any better. Thanks for the quick response and solution idea!

Tyler

Joshua Quick
User offline. Last seen 1 year 32 weeks ago. Offline
Staff
Joined: 31 Jan 2011

Actually, I like your mask idea better. The problem with the work-around that I gave you is it involves writing to file, which is a slow operation. Especially on Android devices that have very slow IO, such as the infamous "Samsung Galaxy S". But it is simpler to implement.

Richards App Store
User offline. Last seen 12 weeks 2 days ago. Offline
Joined: 15 Dec 2011

Yeah you're right, it would be a slower process. And the way it is implemented with my game it would feel a little weird to load it because I spawn the character with extra objects that I want on it at the beginning of the level then use display.capture(its group) to capture it, so I'd have to find some time to preload it before then or else it would be an annoying load time. It was a little complicated to setup the mask at first because I thought I had to mess with the coordinates but I didn't at all, the blog on bitmap masks helps a ton with that.

Satheesh
User offline. Last seen 7 weeks 5 days ago. Offline
Joined: 25 May 2011

@Richards App Store
Hi, I have the same problem with display.capture in my Galaxy Tab.
Can you provide more details on how you got around this particular problem using masks?

I mean, for masking you'll need to have a mask file beforehand right?
I need to display.capture dynamic irregular objects... So I can't use masks to remove the black right?

Richards App Store
User offline. Last seen 12 weeks 2 days ago. Offline
Joined: 15 Dec 2011

@Satheesh
I was able to get around the black outside of the object by creating a mask file beforehand. In the game I did this for, there was a round ball character, and you could add items to him, such as a bandana, eyepatch, etc. and i needed to add all of the images together to form one image that I could control through physics, so I added them all to a group and display.capture them and then got the problem with the black filling the parts of the image that were supposed to be transparent, so I just used the precreated mask file to mask the background out.

Satheesh
User offline. Last seen 7 weeks 5 days ago. Offline
Joined: 25 May 2011

Ah well.. never mind then. I'll have to use the display.save I guess..
thanks for the reply anyway!

Richards App Store
User offline. Last seen 12 weeks 2 days ago. Offline
Joined: 15 Dec 2011

No problem! And sorry if my explanation was a little crappy, i was in a rush :P Good luck!