display.newImage()

Type Function
Library display.*
Return value DisplayObject
Revision Current Public Release (2014.2511)
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). 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] [,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

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