graphics.newOutline()

Type Function
Library graphics.*
Return value Table
Revision Release 2024.3703
Keywords outline, physics, body, graphics
See also Physics Bodies (guide)
Image Sheets (guide)
physics.addBody()

Overview

This function produces the outline of the shape obtained from an image file or a frame within an ImageSheet. A shape is recognized by the image's non-transparent alpha value. Generally, simpler images produce better outlines.

The returned value is a table of x and y coordinates in content space that can be used as the outline for the physics.addBody() function

Syntax

Image File

graphics.newOutline( coarsenessInTexels, imageFileName [, baseDir] )
coarsenessInTexels (required)

Number. The coarseness in texels. Higher values produce lower resolution outlines. Lower values produce larger outlines that can hurt performance.

imageFile (required)

String. The file name of the image to trace.

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

Image Sheet Frame

graphics.newOutline( coarsenessInTexels, imageSheet, frameIndex )
coarsenessInTexels (required)

Number. The coarseness in texels. Higher values produce lower resolution outlines. Lower values produce larger outlines that can hurt performance.

imageSheet (required)

ImageSheet. Reference to an image sheet object created with graphics.newImageSheet().

frameIndex (required)

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

Examples

Image File
local imageFile = "star.png"

local imageOutline = graphics.newOutline( 2, imageFile )
local image = display.newImage( imageFile )

physics.addBody( image, { outline=imageOutline, bounce=0.5, friction=0.1 } )
Image Sheet Frame
local options =
{
    width = 64,
    height = 64,
    numFrames = 12,
    sheetContentWidth = 256,  -- width of original 1x size of entire sheet
    sheetContentHeight = 192  -- height of original 1x size of entire sheet
}
local letterSheet = graphics.newImageSheet( "first_12_letters_of_the_alphabet.png", options )

local frameIndex = 9

local letterOutline = graphics.newOutline( 2, letterSheet, frameIndex )

local letterImage = display.newImageRect( letterSheet, frameIndex, 64, 64 )

physics.addBody( letterImage, { outline=letterOutline, bounce=0.5, friction=0.1 } )