display.loadRemoteImage( )

This a convenience method, similar to network.download(), which returns a display object containing the image, as well as saving the image to file.

Syntax: 

object = display.loadRemoteImage( url, method, listener [, params], destFilename [, baseDir] [, x, y] )

Example: 


The following example downloads a remote image to a local file copy, and then displays it on the screen at (50, 50) after a short alpha transition:

local function networkListener( event )
        if ( event.isError ) then
                print ( "Network error - download failed" )
        else
                event.target.alpha = 0
                transition.to( event.target, { alpha = 1.0 } )
        end
        
        print ( "RESPONSE: " .. event.response )
end
 
display.loadRemoteImage( "http://developer.anscamobile.com/demo/hello.png", "GET", networkListener, "helloCopy.png", system.TemporaryDirectory, 50, 50 )

Parameters: 

url
String: The HTTP request URL.

method
String: The HTTP method; valid values are "GET" (the default) or "POST".

listener
Function: The listener function invoked when the HTTP operation has completed. It is passed an event object that contains the following properties:

  • event.response
    A string containing the destination filename. This is useful if you're writing a general event handler for a variety of file downloads.
  • event.target
    The new display object created after the image is downloaded.
  • event.isError
    A boolean value: true in the case of a network error, false otherwise.

params
Table: An optional table that specifies custom HTTP headers or body to include in the request. To specify custom headers, attach a headers table that specifies header values with string keys. To specify a custom body message, attach a body property to this table whose string value is the HTTP body.

  • params.headers
  • A table specifying header values with string keys.

  • params.body
  • A string containing the HTTP body.

destFilename
String: The name of the file to which the HTTP response will be saved.

baseDir
String: The folder path to which the file will be saved.

x
The x position of the newly created display object; default is 0.

y
The y position of the newly created display object; default is 0.

Returns: 

Nothing is returned from calling this method. The listener callback will contain the Display Object value (event.target) if the download was successful.

Supported on:
Mac OS X: 
Build 2011.268
Windows: 
--
iOS: 
Build 2011.268
Android: 
Build 2011.336
Remarks: 

Image Guidelines
Images should not contain an embedded ICC profile. Use "Save for Web" when exporting images to be used on the device.

To avoid images from using too much texture memory, make sure the image is between 72 and 170 DPI.

Be aware of the gamma and color differences between your development system (Mac and Windows machines) and the device. For best results color calibrate the display used for creating the images.

graphics.newMask( )

Creates a bit mask from an image file. The image is converted internally to grayscale; black values are then masked, while white values are not.

The white pixels of the bit mask allow the covered image to be visible. Black pixels hide (mask) the covered image. The area outside of the mask is filled with black pixels which mask off the area outside the bit mask image.

Note: Bit Mask Requirements
1. The mask image width and height must be multiples of 4.
2. The mask image must have a black border around the mask that is 3 or more pixels.

Syntax: 

local mask = graphics.newMask( filename [, baseDir] )

Example: 

This sample code uses images from the Graphics/Flashlight sample in the Corona SDK. It applies a mask to the image and then scales the mask to twice its original size.

-- Create and position image to be masked
local image = display.newImageRect( "image.png", 768, 1024 )
image:translate( display.contentCenterX, display.contentCenterY )
 
-- Create mask and apply to image
local mask = graphics.newMask( "circlemask.png" )
image:setMask( mask )
 
-- Transform mask
image.maskScaleX, image.maskScaleY = 2,2

Here is an example of how to add a bit mask to a display group. It uses the assets from the X-Ray sample code.
local g = display.newGroup()
 
local bar = display.newImage( g, "paper_bkg.png" ) -- create and add to group
 
local mask = graphics.newMask("circlemask.png")
 
g:setMask(mask)
 
-- Center the mask over the Display Group
g:setReferencePoint( display.CenterReferencePoint )
g.maskX = g.x
g.maskY = g.y

Parameters: 

filename
String: The name of the image file to create the mask from.

baseDir
String: Specifies the directory path that contains the mask image.

Returns: 

Userdata
A mask object that can be applied to any display object using object:setMask()

Supported on:
Mac OS X: 
Build 2011.268
Windows: 
Build 2011.288
iOS: 
Build 2011.268
Android: 
Build 2011.288
Remarks: 

Prior to build 2011.510, masking an image does not affect the touch (or tap) area so touch events will happen for areas of the image that is masked off. If you need touch events to happen only on the masked portion of the object, you will need to create a "hidden" object that tracks the position and size of the masked object and set this as the touch target. The hidden object can be a newRect or newCircle with the alpha property set to 0.0 (so it doesn't show).

Starting with build 2011.510, only the masked portion of the object is affected by touch/tap. Note, however, that the touch sensitive area still corresponds to the mask image shape and is therefore always rectangular, regardless of the actual image! This masking can be disabled with the object.isHitTestMasked property; see the Flashlight sample project.

media.show( )

Opens a platform-specific interface to the device's camera or photo library. This function is asynchronous, i.e. it returns immediately so the calling code will continue to execute until the end of its scope; after that, the application will be suspended until the session is complete. By default, the image object is added to the top of the current stage. A listener is required to handle the returned display object (image).

Syntax: 

media.show( mediaSource, listener )

Example: 

local onComplete = function(event)
   local photo = event.target
   print( "photo w,h = " .. photo.width .. "," .. photo.height )
end
if media.hasSource( media.Camera ) then
   media.show( media.Camera, onComplete )
else
   native.showAlert( "Corona", "This device does not have a camera.", { "OK" } )
end

Parameters: 

mediaSource
Can be one of the following:

  • media.PhotoLibrary
  • media.Camera
  • media.SavedPhotosAlbum

listener can be either a function listener or a table listener. If a table, it must have a completion method. The event dispatched to the listener will be a completion event with the following additional property: event.target is a display image object based on the imageSource parameter. The property will be nil if the user canceled the camera or photo selection.

Returns: 

Nothing. "event.target" in the Listener function will contain the Display Image object.

Supported on:
Mac OS X: 
Corona SDK 2.0
Windows: 
--
iOS: 
Corona SDK 2.0
Android: 
Build 2011.622
Remarks: 

On the Corona Simulator and Xcode Simulator, there is no camera so the API will open a finder window and allow the user to select an image file to substitute as the camera.

Note: This API (Camera and PhotoLibrary) is not support on Android devices in the current release build (591). Camera and PhotoLibrary support was added to Android starting with build 622.

display.save( )

Renders the display object referenced by displayObject into a JPEG image and saves it in filename. The display object must currently be in the display hierarchy; otherwise no image is saved. If the display object is a group object, then all children are rendered. The object to be saved must be on the screen and fully within the screen boundary.

Syntax: 

display.save( displayObject, filename [, baseDirectory] )

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 g = display.newGroup()
 
g:insert(myObject1)
g:insert(myObject2)
 
local baseDir = system.DocumentsDirectory
display.save( g, "entireGroup.jpg", baseDir )

Parameters: 

displayObject
object: Name of display object to save.

filename
string: Name of the file to save the JPEG.

baseDirectory
system path: Optional. Can be either system.DocumentsDirectory (the default) or system.TemporaryDirectory.

Returns: 

Nothing.

Supported on:
Mac OS X: 
Corona SDK 1.0
Windows: 
Build 2011.484
iOS: 
Corona SDK 1.0
Android: 
Build 2011.591
Remarks: 

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

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

Note2: display.save uses the openGL buffer viewport for saving the specified Display Object. When using the Simulator, the size of the saved image will be smaller than expected if the simulator "skin" is not displayed full size. This generally occurs when the simulator skin is displayed on a smaller monitor (e.g., 13") or when Zoomed Out. When the skin is displayed full size, the saved image will match that of the simulated device.

display.captureScreen( )

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

Supported on:
Mac OS X: 
Corona SDK 1.0
Windows: 
Build 2011.484
iOS: 
Corona SDK 1.0
Android: 
Build 2011.591
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".

display.newImageRect()

Automatically substitute higher-resolution assets on higher-resolution devices. The actual image chosen will depend on the current content scale determined by Corona, which is the ratio between the current screen and the base content dimensions defined in config.lua. Based on this scale, Corona uses the imageSuffix table (also defined in config.lua), which lists the suffixes for the same family of images, to find the best match from the image choices available.

Syntax: 

object = display.newImageRect( [parentGroup,] filename [, baseDirectory] width, height )

Example: 

local myDynamicImage = display.newImageRect( "baseImage.png", 100, 100 ) 

Parameters: 

parentGroup
object: display group in which to insert the image.

filename
string: Filename of the image.

baseDirectory
path: Path to load the image data from filename. Default is system.ResourceDirectory. See system.pathForFile for valid values of baseDirectory).

width
number: the content width of the image, which is the width in the reference screen of the content.

height
number: the content height of the image, which is the height in the reference screen of the content.

Returns: 

display object

Supported on:
Mac OS X: 
Corona SDK 1.0
Windows: 
Corona SDK 2.0
iOS: 
Corona SDK 1.0
Android: 
Corona SDK 2.0
Remarks: 

All loaded images are cached. To save texture memory the image in the cache memory is used when it detects an image with the same file name is displayed. This means that loading the same image multiple times doesn't increase the amount of texture memory used on the device.

A negative side-effect to the image caching is the comparison is based on the file name and not the file content. This means if an image file is displayed and then deleted from the directory, any file loaded after that with the same file name will still display the previous cached image. Use a different file name to avoid this problem.

Image Guidelines
Images should not contain an embedded ICC profile. Use "Save for Web" when exporting images to be used on the device.

To avoid images from using too much texture memory, make sure the image is between 72 and 170 DPI.

Be aware of the gamma and color differences between your development system (Mac and Windows machines) and the device. For best results color calibrate the display used for creating the images.

You should NOT use progressive JPGs since they will take much longer to load than non-progressive JPGs.

display.newImage( )

Displays an image on the screen from a file.

Note: display.newImageRect should be used to load images when Dynamic Scaling is enabled, instead of display.newImage.

Beginning with build 2011.612, tinting can be added using object:setFillColor.

Syntax: 

object = display.newImage(filename [,baseDirectory] [,left,top])
object = display.newImage([parentGroup,] filename [,baseDirectory] [,left,top] [,isFullResolution])

Example: 

myImage = display.newImage( "image.png" )

Parameters: 

filename
string: Filename of the image.

baseDirectory
path: Path to load the image data from filename. Default is system.ResourceDirectory. See system.pathForFile for valid values of baseDirectory). Note: This is type "userdata" and not a string value.

left
number: Optionally specify that the image's left corner.

top
number:Optionally specify that the image's top corner.

parentGroup
object: Insert the image to a group.

isFullResolution
boolean: To override autoscaling and show the image at its full-resolution, use the optional isFullResolution parameter. By default, it is false, but if you specify true, then the new image is loaded at its full resolution (maximum of 2048 x 2048). See Image Auto-scaling.

Returns: 

display object

Supported on:
Mac OS X: 
Corona SDK 1.0
Windows: 
Corona SDK 2.0
iOS: 
Corona SDK 1.0
Android: 
Corona SDK 2.0
Remarks: 

All loaded images are cached. To save texture memory the image in the cache memory is used when it detects an image with the same file name is displayed. This means that loading the same image multiple times doesn't increase the amount of texture memory used on the device.

A negative side-effect to the image caching is the comparison is based on the file name and not the file content. This means if an image file is displayed and then deleted from the directory, any file loaded after that with the same file name will still display the previous cached image. Use a different file name to avoid this problem.

Image Guidelines

  • Images should not contain an embedded ICC profile. Use "Save for Web" when exporting images to be used on the device.
  • To avoid images from using too much texture memory, make sure the image is between 72 and 170 DPI.
  • Be aware of the gamma and color differences between your development system (Mac and Windows machines) and the device. For best results color calibrate the display used for creating the images.
  • Grayscale images are not supported; images must currently be RGB.
  • Indexed PNG images are not supported.
  • The maximum full-resolution image supported is 2048 x 2048. This value may be less on older devices (e.g., iPhone 3G).
  • You should NOT use progressive JPGs since they will take much longer to load than non-progressive JPGs.