display.newImage()

Type Function
Library display.*
Return value DisplayObject
Revision Current Public Release (2014.2393)
Keywords images, objects, display object, graphics
See also display.newImageRect()
display.loadRemoteImage()
Image Sheets (Sprite Sheets)

Overview

Displays an image on the screen from a file (supports tinting via object:setFillColor)

Note that display.newImageRect() should be used instead to load images when dynamic 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] [,isFullResolution])

display.newImage( [parent,] imageSheet, frameIndex )
parent (optional)

GroupObject. Specify an optional display group in which to insert the image object. By default, uses the current stage (as returned from display.getCurrentStage()) if no parent is specified.

filename (required)

String. The name of the image file to load, relative to baseDir (or system.ResourceDirectory by default).

baseDir (optional)

Constant. Path to load the image from. Default is system.ResourceDirectory (project folder; same location as main.lua). See system.pathForFile() for valid values).

x / y (optional)

Numbers. The x and y coordinates of the image.

isFullResolution (optional)

Boolean. To override autoscaling and show the image at its full-resolution, set this value to true. 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).

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 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.

On Android, images are limited (downsized) to 2048×2048, even though the maximum texture memory size is higher on the device. The reason is most Android devices don't have enough heap memory to load the image. It's recommended that you don't load image files larger than 2048×2048.

There is a different 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. You can set the isFullResolution flag to true to load the full resolution on all 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

Properties

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

Example

Image File Usage
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
Image Sheet Usage
-- first, 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 resolution support

    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 )