display.newImage()

Type Function
Library display.*
Return value DisplayObject
Revision Release 2024.3703
Keywords images, objects, display object, graphics
See also display.newImageRect()
display.loadRemoteImage()
Display Objects (guide)
Image Sheets (guide)

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

Image File

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

GroupObject. An optional display group in which to insert the image object.

filename (required)

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

baseDir (optional)

Constant. Specifies the base directory where filename is located. Options include system.ResourceDirectory, system.DocumentsDirectory, system.ApplicationSupportDirectory, system.TemporaryDirectory and system.CachesDirectory. Default is system.ResourceDirectory.

x (optional)

Number. The x coordinate of the image.

y (optional)

Number. The y coordinate of the image.

Image Sheet

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

GroupObject. An optional display group in which to insert the image object.

imageSheet (required)

ImageSheet. Reference to an image sheet object created with graphics.newImageSheet(). This is only required if you intend to create an object from an image sheet.

frameIndex (required)

Number. Represents the frame index number within the ImageSheet to create the object from. This is only required if imageSheet is specified.

x (optional)

Number. The x coordinate of the image.

y (optional)

Number. The y coordinate of the image.

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

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