Creating an image and adding it to the stage with Corona is very easy. To get started create a folder where you will be working. Create an image to use for the example. Something small since we’ll be testing in the iPhone simulator. For the example assume the stage will be 320px by 480px. Save your image into the folder where you will be working. My image was named square.png.
Next we need to create our Corona project. Create a plain text file and save it into your folder. Name this file main.lua.
Create an image on the screen
Add the following to the top of main.lua
local square = display.newImage("square.png")
Open main.lua with Corona. The simulator should appear and your image appears in the upper left corner.
Position an image with x and y
Try positioning your image on the stage. The display object holding the image is saved in the variable “square”. Set the x and y property of your image.
square.x = 160 square.y = 240
This should place the image in the center of the simulator. Assuming the width to 320 and height to be 480. The center would half of these numbers 160 and 240.
Notice the image appears in the exact center. This would mean that Corona considers registration point, or point of transformation, for the image to be in the center of the image.
Rotate an image with rotation
Test that out by rotating the image. Add the following line
square.rotation = 45
The square is still center and is rotated around it’s center.
Note! That means that the original position was not x = 0 and y = 0. Remember when the image was first placed it’s upper left corner was aligned with the upper left corner of the stage. If the x and y were 0, then the center of the image should have aligned with the upper left corner. Test it for yourself.
square.x = 0 square.y = 0
Test your work. Notice the center of the image is now in the upper left corner.
So, Corona positions objects initially setting their x and y to half the image height and width, to place the upper left corner of the image in the upper left of the stage.
Reference Point
The center of transformations for an object is called the reference point in Corona. You can position the reference point of an object using the xReference and yReference properties. Changing these values does not change the position of an object, instead it changes the center of transformation.
Think of the reference point as a pin holding your object to the stage. When you set the x and y it’s the pin that is placed at the new x and y coordinates. When the object rotates it rotates around the pin. By default the reference point is placed in the center. Imagine a pin stuck through the center of the object.
The reference point can be manipulated by changing the xReference and yReference. This is useful, since in some cases it will be more convenient to position or transform an object from the upper left corner or location other than the center.
Try it for yourself. Move the reference point to the upper left corner. In my example the image I used was 100px by 100px. By default xReference and yReference are 0 and 0. To move the reference point to the upper I’ll need to set the xReference and yReference to negative half the width and negative half the height, -50 and -50.
square.xReference = -50 square.yReference = -50
Change the x, y and rotation properties a few times each and test your project with each change. You’ll notice the image is transforming around a point in the upper left.
Alternately you can use the following method to set the reference point to the upper left corner of an object. Chnage object to the name of your object, square in my example.
object:setReferencePoint( display.TopLeftReferencePoint )
Removing images
It is important to remove objects when they are not in use. Bit map images take up large chunks of memory. Which, on mobile devices is a scarce resource.
To properly remove an object you need to remove it explicitly from it’s parent. This can be done in one of two ways.
image.parent:remove( image ) -- or -- image:removeSelf()
Sometimes this is not enough to free up memory used by the object. You also need to remove any references to the objects. These references are stored in variables. In the example above the variable square is assigned and holds a reference to a display object after this line:
local square = display.newImage("square.png")
After this line, square can be used reference the display object containing the image “square.png”. This variable also ensures that the memory used by the image”square.png” is not released.
To ensure that an object is released from memory when you are done with it you need to set the value of any variables referencing it to nil. The value nil is an empty, value think of it as no value. To remove square from the display and make sure it’s memory is freed you would want to do the following.
square.parent:removeSelf() square = nil