display.newImage()

Overview

Displays an image on the screen from a file (supports tinting via object:setFillColor). The local origin is at the center of the image and the anchor point is initialized to this local origin.

Note that display.newImageRect() should be used instead to load images when content scaling is enabled.

Image objects are the same as rectangle objects in which the object.fill property is set to be an image.

Syntax

display.newImage( [parent,] filename [, baseDir] [, x, y] )

display.newImage( [parent,] imageSheet, frameIndex [, x, y] )

Texture Sampling

By default, new image sheets will use a linear sampling filter, so that the image will look smooth when the actual rendered region is larger or smaller than the pixel dimensions of the loaded texture.

You can change the default texture filter by calling display.setDefault(). Once an image is loaded the first time, the same sampling filter will be applied for any subsequent loads of the same file. This is because textures are loaded once per file.

Gotchas

• 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 that 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. To avoid this problem, use a different file name.

• There is a difference between Mac/iOS and Windows/Android when displaying images with display.newImage(). If the image to be loaded exceeds the resolution of the device, it will be autoscaled to fit on Mac and iOS. On Windows and Android, it will load full resolution (up to the maximum texture size of the device). This can cause apps to display differently between the platforms. If you know the image size before loading, use display.newImageRect() instead — this API also handles loading the proper image resolution based on the device's resolution.

Image Guidelines

• Corona supports PNG and JPG format.
• Images should not contain an embedded ICC profile.
• Avoid progressive JPG files since they will take much longer to load.

Properties

(Inherits properties from ShapeObject and display.newRect())

Example

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

-- Position the image
myImage:translate( 100, 100 )

-- Tint the image red
myImage:setFillColor( 1, 0, 0 )

-- Hide the image
myImage.isVisible = false

-- Remove the image
myImage:removeSelf()
myImage = nil

-- Create the image sheet object
local options =
{
    -- The params below are required
    width = 70,
    height = 41,
    numFrames = 2,

    -- The params below are optional (used for dynamic image selection)
    sheetContentWidth = 70,  -- width of original 1x size of entire sheet
    sheetContentHeight = 82  -- height of original 1x size of entire sheet
}
local imageSheet = graphics.newImageSheet( "fishies.png", options )

local myImage = display.newImage( imageSheet, 1 )