| Package | starling.display |
| Class | public class Image |
| Inheritance | Image  Quad Mesh DisplayObject EventDispatcher Object |
| Subclasses | MovieClip |
Typically, the Image class will act as an equivalent of Flash's Bitmap class. Instead of BitmapData, Starling uses textures to represent the pixels of an image. To display a texture, you have to map it onto a quad - and that's what the Image class is for.
While the base class Quad already supports textures, the Image
class adds some additional functionality.
First of all, it provides a convenient constructor that will automatically synchronize the size of the image with the displayed texture.
Furthermore, it adds support for a "Scale9" grid. This splits up the image into nine regions, the corners of which will always maintain their original size. The center region stretches in both directions to fill the remaining space; the side regions will stretch accordingly in either horizontal or vertical direction.
Finally, you can repeat a texture horizontally and vertically within the image's region,
just like the tiles of a wallpaper. Use the tileGrid property to do that.
See also
| Property | Defined By | ||
|---|---|---|---|
 | alpha : Number The opacity of the object. | DisplayObject | |
| base : DisplayObject [read-only] The topmost object in the display tree the object is part of. | DisplayObject | |
| blendMode : String The blend mode determines how the object is blended with the objects underneath. | DisplayObject | |
| bounds : Rectangle [read-only] The bounds of the object relative to the local coordinates of the parent. | DisplayObject | |
| color : uint Changes the color of all vertices to the same value. | Mesh | |
| defaultStyle : Class [static] The default style used for meshes if no specific style is provided. | Mesh | |
| defaultStyleFactory : Function [static] A factory method that is used to create the 'MeshStyle' for a mesh if no specific
style is provided. | Mesh | |
| filter : FragmentFilter The filter that is attached to the display object. | DisplayObject | |
| height : Number The height of the object in pixels. | DisplayObject | |
| is3D : Boolean [read-only] Indicates if this object or any of its parents is a 'Sprite3D' object. | DisplayObject | |
| mask : DisplayObject The display object that acts as a mask for the current object. | DisplayObject | |
| maskInverted : Boolean Indicates if the masked region of this object is set to be inverted. | DisplayObject | |
| name : String The name of the display object (default: null). | DisplayObject | |
| numIndices : int [read-only] The total number of indices referencing vertices. | Mesh | |
| numTriangles : int [read-only] The total number of triangles in this mesh. | Mesh | |
| numVertices : int [read-only] The total number of vertices in the mesh. | Mesh | |
| parent : DisplayObjectContainer [read-only] The display object container that contains this display object. | DisplayObject | |
| pivotX : Number The x coordinate of the object's origin in its own coordinate space (default: 0). | DisplayObject | |
| pivotY : Number The y coordinate of the object's origin in its own coordinate space (default: 0). | DisplayObject | |
| pixelSnapping : Boolean Controls whether or not the instance snaps to the nearest pixel. | Mesh | |
| requiresRedraw : Boolean [read-only] Indicates if the object needs to be redrawn in the upcoming frame, i.e. | DisplayObject | |
| root : DisplayObject [read-only] The root object the display object is connected to (i.e. | DisplayObject | |
| rotation : Number The rotation of the object in radians. | DisplayObject | |
| scale : Number Sets both 'scaleX' and 'scaleY' to the same value. | DisplayObject | |
| scale9Grid : Rectangle The current scaling grid that is in effect. | Image | ||
| scaleX : Number The horizontal scale factor. | DisplayObject | |
| scaleY : Number The vertical scale factor. | DisplayObject | |
| skewX : Number The horizontal skew angle in radians. | DisplayObject | |
| skewY : Number The vertical skew angle in radians. | DisplayObject | |
| stage : Stage [read-only] The stage the display object is connected to, or null if it is not connected
to the stage. | DisplayObject | |
| style : MeshStyle The style that is used to render the mesh. | Mesh | |
| texture : Texture [override] The texture that is mapped to the quad (or null, if there is none). | Quad | |
| textureRepeat : Boolean Indicates if pixels at the edges will be repeated or clamped. | Mesh | |
| textureSmoothing : String The smoothing filter that is used for the texture. | Mesh | |
| tileGrid : Rectangle The current tiling grid that is in effect. | Image | ||
| touchable : Boolean Indicates if this object (and its children) will receive touch events. | DisplayObject | |
| transformationMatrix : Matrix The transformation matrix of the object relative to its parent. | DisplayObject | |
| transformationMatrix3D : Matrix3D [read-only] The 3D transformation matrix of the object relative to its parent. | DisplayObject | |
| useHandCursor : Boolean Indicates if the mouse cursor should transform into a hand while it's over the sprite. | DisplayObject | |
| vertexFormat : VertexDataFormat [read-only] The format used to store the vertices. | Mesh | |
| visible : Boolean The visibility of the object. | DisplayObject | |
| width : Number The width of the object in pixels. | DisplayObject | |
| x : Number The x coordinate of the object relative to the local coordinates of the parent. | DisplayObject | |
| y : Number The y coordinate of the object relative to the local coordinates of the parent. | DisplayObject | |
| Method | Defined By | ||
|---|---|---|---|
Creates an image with a texture mapped onto it. | Image | ||
| addEventListener(type:String, listener:Function):void [override] Registers an event listener at a certain object. | DisplayObject | |
| alignPivot(horizontalAlign:String = center, verticalAlign:String = center):void Moves the pivot point to a certain position within the local coordinate system
of the object. | DisplayObject | |
automateSetupForTexture(texture:Texture, onAssign:Function, onRelease:Function = null):void [static] Injects code that is called by all instances whenever the given texture is assigned or replaced. | Image | ||
bindPivotPointToTexture(texture:Texture, pivotX:Number, pivotY:Number):void [static] Binds the given pivot point to the given texture so that any image which displays the texture will
automatically use the pivot point. | Image | ||
bindScale9GridToTexture(texture:Texture, scale9Grid:Rectangle):void [static] Binds the given scaling grid to the given texture so that any image which displays the texture will
automatically use the grid. | Image | ||
| [static] Creates a new instance of the current default MeshStyle. | Mesh | |
| dispatchEvent(event:Event):void Dispatches an event to all objects that have registered listeners for its type. | EventDispatcher | |
| dispatchEventWith(type:String, bubbles:Boolean = false, data:Object = null):void Dispatches an event with the given parameters to all objects that have registered
listeners for the given type. | EventDispatcher | |
| dispose():void [override] Disposes all resources of the display object. | Mesh | |
| drawToBitmapData(out:BitmapData = null, color:uint = 0x0, alpha:Number = 0.0):BitmapData Draws the object into a BitmapData object. | DisplayObject | |
| [static] Creates a mesh from the specified polygon. | Mesh | |
| [static] Creates a quad from the given texture. | Quad | |
| getBounds(targetSpace:DisplayObject, out:Rectangle = null):Rectangle [override] Returns a rectangle that completely encloses the object as it appears in another
coordinate system. | Quad | |
| getTexCoords(vertexID:int, out:Point = null):Point Returns the texture coordinates of the vertex at the specified index. | Mesh | |
| getTransformationMatrix(targetSpace:DisplayObject, out:Matrix = null):Matrix Creates a matrix that represents the transformation from the local coordinate system
to another. | DisplayObject | |
| getTransformationMatrix3D(targetSpace:DisplayObject, out:Matrix3D = null):Matrix3D Creates a matrix that represents the transformation from the local coordinate system
to another. | DisplayObject | |
| getVertexAlpha(vertexID:int):Number Returns the alpha value of the vertex at the specified index. | Mesh | |
| getVertexColor(vertexID:int):uint Returns the RGB color of the vertex at the specified index. | Mesh | |
| getVertexPosition(vertexID:int, out:Point = null):Point The position of the vertex at the specified index, in the mesh's local coordinate
system. | Mesh | |
| globalToLocal(globalPoint:Point, out:Point = null):Point Transforms a point from global (stage) coordinates to the local coordinate system. | DisplayObject | |
| globalToLocal3D(globalPoint:Point, out:Vector3D = null):Vector3D Transforms a point from global (stage) coordinates to the 3D local coordinate system. | DisplayObject | |
| hasEventListener(type:String, listener:Function = null):Boolean If called with one argument, figures out if there are any listeners registered for
the given event type. | EventDispatcher | |
| hitTest(localPoint:Point):DisplayObject [override] Returns the object that is found topmost beneath a point in local coordinates, or nil
if the test fails. | Quad | |
| hitTestMask(localPoint:Point):Boolean Checks if a certain point is inside the display object's mask. | DisplayObject | |
| local3DToGlobal(localPoint:Vector3D, out:Point = null):Point Transforms a 3D point from the local coordinate system to global (stage) coordinates. | DisplayObject | |
| localToGlobal(localPoint:Point, out:Point = null):Point Transforms a point from the local coordinate system to global (stage) coordinates. | DisplayObject | |
| readjustSize(width:Number = -1, height:Number = -1):void Readjusts the dimensions of the quad. | Quad | |
| removeEventListener(type:String, listener:Function):void [override] Removes an event listener from the object. | DisplayObject | |
| removeEventListeners(type:String = null):void [override] Removes all event listeners with a certain type, or all of them if type is null. | DisplayObject | |
| removeFromParent(dispose:Boolean = false):void Removes the object from its parent, if it has one, and optionally disposes it. | DisplayObject | |
removeSetupForTexture(texture:Texture, onAssign:Function, onRelease:Function = null):void [static] Removes specific setup functions for the given texture. | Image | ||
| [override] Renders the display object with the help of a painter object. | Mesh | |
resetSetupForTexture(texture:Texture):void [static] Removes all custom setup functions for the given texture, including those created via
'bindScale9GridToTexture' and 'bindPivotPointToTexture'. | Image | ||
| setIndexDataChanged():void This method is called whenever the mesh's index data was changed. | Mesh | |
| setRequiresRedraw():void Forces the object to be redrawn in the next frame. | DisplayObject | |
| Sets the style that is used to render the mesh. | Mesh | |
| setTexCoords(vertexID:int, u:Number, v:Number):void Sets the texture coordinates of the vertex at the specified index to the given values. | Mesh | |
| setVertexAlpha(vertexID:int, alpha:Number):void Sets the alpha value of the vertex at the specified index to a certain value. | Mesh | |
| setVertexColor(vertexID:int, color:uint):void Sets the RGB color of the vertex at the specified index to a certain value. | Mesh | |
| setVertexDataChanged():void This method is called whenever the mesh's vertex data was changed. | Mesh | |
| setVertexPosition(vertexID:int, x:Number, y:Number):void | Mesh | |
| scale9Grid | property |
Hide Inherited Public Properties
Show Inherited Public Propertiesscale9Grid:RectangleThe current scaling grid that is in effect. If set to null, the image is scaled just like any other display object; assigning a rectangle will divide the image into a grid of nine regions, based on the center rectangle. The four corners of this grid will always maintain their original size; the other regions will stretch (horizontally, vertically, or both) to fill the complete area.
Notes:
scale9Grid or a tileGrid, but
not both. Assigning one will delete the other.image.scale9Grid = image.scale9Grid.readjustSize(),
and the same will happen when the texture is changed afterwards. The default value is null.
public function get scale9Grid():Rectangle public function set scale9Grid(value:Rectangle):void| tileGrid | property |
tileGrid:RectangleThe current tiling grid that is in effect. If set to null, the image is scaled just like any other display object; assigning a rectangle will divide the image into a grid displaying the current texture in each and every cell. The assigned rectangle points to the bounds of one cell; all other elements will be calculated accordingly. A zero or negative value for the rectangle's width or height will be replaced with the actual texture size. Thus, you can make a 2x2 grid simply like this:
var image:Image = new Image(texture);
image.tileGrid = new Rectangle();
image.scale = 2;Notes:
scale9Grid or a tileGrid, but
not both. Assigning one will delete the other.image.tileGrid = image.tileGrid. The default value is null.
public function get tileGrid():Rectangle public function set tileGrid(value:Rectangle):void| Image | () | Constructor |
public function Image(texture:Texture)Creates an image with a texture mapped onto it.
Parameterstexture:Texture |
| automateSetupForTexture | () | method |
public static function automateSetupForTexture(texture:Texture, onAssign:Function, onRelease:Function = null):voidInjects code that is called by all instances whenever the given texture is assigned or replaced. The new functions will be executed after any existing ones.
Parameters
texture:Texture — Assignment of this texture instance will lead to the following callback(s) being executed.
| |
onAssign:Function — Called when the texture is assigned. Receives one parameter of type 'Image'.
| |
onRelease:Function (default = null) |
| bindPivotPointToTexture | () | method |
public static function bindPivotPointToTexture(texture:Texture, pivotX:Number, pivotY:Number):voidBinds the given pivot point to the given texture so that any image which displays the texture will automatically use the pivot point.
Parameters
texture:Texture | |
pivotX:Number | |
pivotY:Number |
| bindScale9GridToTexture | () | method |
public static function bindScale9GridToTexture(texture:Texture, scale9Grid:Rectangle):voidBinds the given scaling grid to the given texture so that any image which displays the texture will automatically use the grid.
Parameters
texture:Texture | |
scale9Grid:Rectangle |
| removeSetupForTexture | () | method |
public static function removeSetupForTexture(texture:Texture, onAssign:Function, onRelease:Function = null):voidRemoves specific setup functions for the given texture.
Parameters
texture:Texture | |
onAssign:Function | |
onRelease:Function (default = null) |
| resetSetupForTexture | () | method |
public static function resetSetupForTexture(texture:Texture):voidRemoves all custom setup functions for the given texture, including those created via 'bindScale9GridToTexture' and 'bindPivotPointToTexture'.
Parameters
texture:Texture |