starling.display.Image

Package	starling.display
Class	public class Image
Inheritance	Image Quad Mesh DisplayObject EventDispatcher Object
Subclasses	MovieClip

An Image is a quad with a texture mapped onto it.

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 aspect ratio. 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

starling.textures.Texture
Quad

Public Properties

Hide Inherited Public Properties

Show Inherited Public Properties

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

	Property	Defined By
		indexData : IndexData [read-only] The index data describing how the vertices are interconnected.	Mesh
		vertexData : VertexData [read-only] The vertex data describing all vertices of the mesh.	Mesh

Public Methods

Hide Inherited Public Methods

Show Inherited Public Methods

	Method		Defined By
		Image(texture:Texture) 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
		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
		fromPolygon(polygon:Polygon, style:MeshStyle = null):Mesh [static] Creates a mesh from the specified polygon.	Mesh
		fromTexture(texture:Texture):Quad [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
		render(painter:Painter):void [override] Renders the display object with the help of a painter object.	Mesh
		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
		setStyle(meshStyle:MeshStyle = null, mergeWithPredecessor:Boolean = true):void 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

	Method	Defined By
		setupVertices():void Sets up vertex- and index-data according to the current settings.	Quad

Summary	Defined By
added	Dispatched when an object is added to a parent.	DisplayObject
addedToStage	Dispatched when an object is connected to the stage (directly or indirectly).	DisplayObject
enterFrame	Dispatched once every frame on every object that is connected to the stage.	DisplayObject
keyDown	Dispatched when a key on the keyboard is pressed.	DisplayObject
keyUp	Dispatched when a key on the keyboard is released.	DisplayObject
removed	Dispatched when an object is removed from its parent.	DisplayObject
removedFromStage	Dispatched when an object is removed from the stage and won't be rendered any longer.	DisplayObject
touch	Dispatched when an object is touched.	DisplayObject

Property Detail

scale9Grid

property

scale9Grid:Rectangle

The 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 aspect ratio; the other regions will stretch accordingly (horizontally, vertically, or both) to fill the complete area.

Notes:

Assigning a Scale9 rectangle will change the number of vertices to a maximum of 16 (less if possible) and all vertices will be colored like vertex 0 (the top left vertex).
An image can have either a scale9Grid or a tileGrid, but not both. Assigning one will delete the other.
Changes will only be applied on assignment. To force an update, simply call image.scale9Grid = image.scale9Grid.
Assignment causes an implicit call to readjustSize(), and the same will happen when the texture is changed afterwards.

The default value is null.

Implementation
public function get scale9Grid():Rectangle
public function set scale9Grid(value:Rectangle):void

tileGrid

property

tileGrid:Rectangle

The 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:

Assigning a tile rectangle will change the number of vertices to whatever is required by the grid. New vertices will be colored just like vertex 0 (the top left vertex).
An image can have either a scale9Grid or a tileGrid, but not both. Assigning one will delete the other.
Changes will only be applied on assignment. To force an update, simply call image.tileGrid = image.tileGrid.

The default value is null.

Implementation
public function get tileGrid():Rectangle
public function set tileGrid(value:Rectangle):void

Constructor Detail

Image

()

Constructor

public function Image(texture:Texture)

Creates an image with a texture mapped onto it.

Parameters

texture:Texture

Fri Sep 23 2016, 10:31 AM +02:00

Starling Framework Reference (v2.1)	All Packages \| All Classes \| Index \| Frames No Frames
Image	Properties \| Methods \| Events