Type Function Library display.* Return value DisplayObject Revision 2017.3060 Keywords images, objects, display object, graphics See also display.newImageRect() display.loadRemoteImage() Display Objects (guide) Image Sheets (guide)
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.
display.newImage( [parent,] filename [, baseDir] [, x, y] )
GroupObject. An optional display group in which to insert the image object.
String. The name of the image file to load, relative to baseDir (or system.ResourceDirectory by default).
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.
Numbers. The x and y coordinates of the image.
display.newImage( [parent,] imageSheet, frameIndex [, x, y] )
GroupObject. An optional display group in which to insert the image object.
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.
Number. Represents the frame index number within the ImageSheet to create the object from. This is only required if imageSheet is specified.
Numbers. The x and y coordinates of the image.
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.
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
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.
(Inherits properties from ShapeObject and display.newRect())
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
-- 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 )