display.newImageRect()

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

Overview

Displays an image on the screen from a file. This image 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.

The difference between this function and display.newImage() is that display.newImageRect() automatically substitutes higher-resolution assets on higher-resolution devices, making this function ideal for displaying images across devices of varying resolutions. The actual image chosen will depend on the current content scale determined by Corona. This is based on the ratio between the current screen and the base content dimensions defined in config.lua. Based on this, Corona uses the imageSuffix table (also defined in config.lua) which lists the suffixes for the same family of images, and this function finds the best match from the image choices available. At any time, the chosen suffix is accessible via the read-only property display.imageSuffix. Please refer to the Project Configuration guide for more information.

Essentially, display.newImageRect() should always be used to load images when content scaling is enabled, and this function can be used in two ways:

  1. Use multiple image files designed for targeted devices and display the correct image based on the resolution/screen of each device.
  2. Resize high-resolution images to fit the existing content width and height. Since this only uses one high-resolution image, it uses more texture memory than method 1, but handles the case of sizing an image that will be used on multiple device resolutions.

Syntax

Image File

display.newImageRect( [parent,] filename, [baseDir,] width, height )
parent (optional)

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

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.

width (required)

Number. The content width of the image, which is the width within the reference screen of the content. When using trimmed frames that have been packed into an ImageSheet by programs like TexturePacker, specify the trimmed width, not the width of the original uncropped frame.

height (required)

Number. The content height of the image, which is the height within the reference screen of the content. When using trimmed frames that have been packed into an ImageSheet by programs like TexturePacker, specify the trimmed height, not the height of the original uncropped frame.

Image Sheet

display.newImageRect( [parent,] imageSheet, frameIndex, width, height )
parent (optional)

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

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.

width (required)

Number. The content width of the image, which is the width within the reference screen of the content. When using trimmed frames that have been packed into an ImageSheet by programs like TexturePacker, specify the trimmed width, not the width of the original uncropped frame.

height (required)

Number. The content height of the image, which is the height within the reference screen of the content. When using trimmed frames that have been packed into an ImageSheet by programs like TexturePacker, specify the trimmed height, not the height of the original uncropped frame.

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

Examples

Image File Usage
local image = display.newImageRect( "image.png", 100, 100 )
image.x = display.contentCenterX
image.y = display.contentCenterY

-- Hide the object
image.isVisible = false

-- Remove it
image:removeSelf()
image = 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 )

-- Create new image from the above image sheet
local obj = display.newImageRect( imageSheet, 1, 70, 41 )
obj.x, obj.y = 100, 100