Packagestarling.textures
Classpublic class Texture
InheritanceTexture Inheritance Object
Subclasses ConcreteTexture, SubTexture

A texture stores the information that represents an image. It cannot be added to the display list directly; instead it has to be mapped onto a display object. In Starling, that display object is the class "Image".

Texture Formats

Since textures can be created from a "BitmapData" object, Starling supports any bitmap format that is supported by Flash. And since you can render any Flash display object into a BitmapData object, you can use this to display non-Starling content in Starling - e.g. Shape objects.

Starling also supports ATF textures (Adobe Texture Format), which is a container for compressed texture formats that can be rendered very efficiently by the GPU. Refer to the Flash documentation for more information about this format.

Mip Mapping

MipMaps are scaled down versions of a texture. When an image is displayed smaller than its natural size, the GPU may display the mip maps instead of the original texture. This reduces aliasing and accelerates rendering. It does, however, also need additional memory; for that reason, you can choose if you want to create them or not.

Texture Frame

The frame property of a texture allows you let a texture appear inside the bounds of an image, leaving a transparent space around the texture. The frame rectangle is specified in the coordinate system of the texture (not the image):

      var frame:Rectangle = new Rectangle(-10, -10, 30, 30); 
      var texture:Texture = Texture.fromTexture(anotherTexture, null, frame);
      var image:Image = new Image(texture);

This code would create an image with a size of 30x30, with the texture placed at x=10, y=10 within that image (assuming that 'anotherTexture' has a width and height of 10 pixels, it would appear in the middle of the image).

The texture atlas makes use of this feature, as it allows to crop transparent edges of a texture and making up for the changed size by specifying the original texture frame. Tools like TexturePacker use this to optimize the atlas.

Texture Coordinates

If, on the other hand, you want to show only a part of the texture in an image (i.e. to crop the the texture), you can either create a subtexture (with the method 'Texture.fromTexture()' and specifying a rectangle for the region), or you can manipulate the texture coordinates of the image object. The method 'image.setTexCoords' allows you to do that.

See also

starling.display.Image
TextureAtlas


Public Properties
 PropertyDefined By
  base : TextureBase
[read-only] The Stage3D texture object the texture is based on.
Texture
  format : String
[read-only] The Context3DTextureFormat of the underlying texture data.
Texture
  frame : Rectangle
[read-only] The texture frame (see class description).
Texture
  height : Number
[read-only] The height of the texture in points.
Texture
  mipMapping : Boolean
[read-only] Indicates if the texture contains mip maps.
Texture
  nativeHeight : Number
[read-only] The height of the texture in pixels (without scale adjustment).
Texture
  nativeWidth : Number
[read-only] The width of the texture in pixels (without scale adjustment).
Texture
  premultipliedAlpha : Boolean
[read-only] Indicates if the alpha values are premultiplied into the RGB values.
Texture
  repeat : Boolean
Indicates if the texture should repeat like a wallpaper or stretch the outermost pixels.
Texture
  root : ConcreteTexture
[read-only] The concrete (power-of-two) texture the texture is based on.
Texture
  scale : Number
[read-only] The scale factor, which influences width and height properties.
Texture
  width : Number
[read-only] The width of the texture in points.
Texture
Public Methods
 MethodDefined By
  
adjustVertexData(vertexData:VertexData, vertexID:int, count:int):void
Converts texture coordinates and vertex positions of raw vertex data into the format required for rendering.
Texture
  
dispose():void
Disposes the underlying texture data.
Texture
  
empty(width:int = 64, height:int = 64, premultipliedAlpha:Boolean = false, optimizeForRenderToTexture:Boolean = true, scale:Number = -1):Texture
[static] Creates an empty texture of a certain size.
Texture
  
fromAtfData(data:ByteArray, scale:Number = 1, useMipMaps:Boolean = true, loadAsync:Function = null):Texture
[static] Creates a texture from the compressed ATF format.
Texture
  
fromBitmap(data:Bitmap, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1):Texture
[static] Creates a texture object from a bitmap.
Texture
  
fromBitmapData(data:BitmapData, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1):Texture
[static] Creates a texture from bitmap data.
Texture
  
fromColor(width:int, height:int, color:uint = 0xffffffff, optimizeForRenderToTexture:Boolean = false, scale:Number = -1):Texture
[static] Creates a texture with a certain size and color.
Texture
  
fromTexture(texture:Texture, region:Rectangle = null, frame:Rectangle = null):Texture
[static] Creates a texture that contains a region (in pixels) of another texture.
Texture
Property Detail
baseproperty
base:TextureBase  [read-only]

The Stage3D texture object the texture is based on.


Implementation
    public function get base():TextureBase
formatproperty 
format:String  [read-only]

The Context3DTextureFormat of the underlying texture data.


Implementation
    public function get format():String
frameproperty 
frame:Rectangle  [read-only]

The texture frame (see class description).


Implementation
    public function get frame():Rectangle
heightproperty 
height:Number  [read-only]

The height of the texture in points.


Implementation
    public function get height():Number
mipMappingproperty 
mipMapping:Boolean  [read-only]

Indicates if the texture contains mip maps.


Implementation
    public function get mipMapping():Boolean
nativeHeightproperty 
nativeHeight:Number  [read-only]

The height of the texture in pixels (without scale adjustment).


Implementation
    public function get nativeHeight():Number
nativeWidthproperty 
nativeWidth:Number  [read-only]

The width of the texture in pixels (without scale adjustment).


Implementation
    public function get nativeWidth():Number
premultipliedAlphaproperty 
premultipliedAlpha:Boolean  [read-only]

Indicates if the alpha values are premultiplied into the RGB values.


Implementation
    public function get premultipliedAlpha():Boolean
repeatproperty 
repeat:Boolean

Indicates if the texture should repeat like a wallpaper or stretch the outermost pixels. Note: this only works in textures with sidelengths that are powers of two and that are not loaded from a texture atlas (i.e. no subtextures).

The default value is false.


Implementation
    public function get repeat():Boolean
    public function set repeat(value:Boolean):void
rootproperty 
root:ConcreteTexture  [read-only]

The concrete (power-of-two) texture the texture is based on.


Implementation
    public function get root():ConcreteTexture
scaleproperty 
scale:Number  [read-only]

The scale factor, which influences width and height properties.


Implementation
    public function get scale():Number
widthproperty 
width:Number  [read-only]

The width of the texture in points.


Implementation
    public function get width():Number
Method Detail
adjustVertexData()method
public function adjustVertexData(vertexData:VertexData, vertexID:int, count:int):void

Converts texture coordinates and vertex positions of raw vertex data into the format required for rendering.

Parameters

vertexData:VertexData
 
vertexID:int
 
count:int

dispose()method 
public function dispose():void

Disposes the underlying texture data. Note that not all textures need to be disposed: SubTextures (created with 'Texture.fromTexture') just reference other textures and and do not take up resources themselves; this is also true for textures from an atlas.

empty()method 
public static function empty(width:int = 64, height:int = 64, premultipliedAlpha:Boolean = false, optimizeForRenderToTexture:Boolean = true, scale:Number = -1):Texture

Creates an empty texture of a certain size. Useful mainly for render textures. Beware that the texture can only be used after you either upload some color data or clear the texture while it is an active render target.

Parameters

width:int (default = 64) — in points; number of pixels depends on scale parameter
 
height:int (default = 64) — in points; number of pixels depends on scale parameter
 
premultipliedAlpha:Boolean (default = false) — the PMA format you will use the texture with
 
optimizeForRenderToTexture:Boolean (default = true) — indicates if this texture will be used as render target
 
scale:Number (default = -1) — if you omit this parameter, 'Starling.contentScaleFactor' will be used.

Returns
Texture
fromAtfData()method 
public static function fromAtfData(data:ByteArray, scale:Number = 1, useMipMaps:Boolean = true, loadAsync:Function = null):Texture

Creates a texture from the compressed ATF format. If you don't want to use any embedded mipmaps, you can disable them by setting "useMipMaps" to false. Beware: you must not dispose 'data' if Starling should handle a lost device context.

If you pass a function for the 'loadAsync' parameter, the method will return immediately, while the texture will be created asynchronously. It can be used as soon as the callback has been executed. This is the expected function definition: function(texture:Texture):void;

Parameters

data:ByteArray
 
scale:Number (default = 1)
 
useMipMaps:Boolean (default = true)
 
loadAsync:Function (default = null)

Returns
Texture
fromBitmap()method 
public static function fromBitmap(data:Bitmap, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1):Texture

Creates a texture object from a bitmap. Beware: you must not dispose 'data' if Starling should handle a lost device context.

Parameters

data:Bitmap
 
generateMipMaps:Boolean (default = true)
 
optimizeForRenderToTexture:Boolean (default = false)
 
scale:Number (default = 1)

Returns
Texture
fromBitmapData()method 
public static function fromBitmapData(data:BitmapData, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1):Texture

Creates a texture from bitmap data. Beware: you must not dispose 'data' if Starling should handle a lost device context.

Parameters

data:BitmapData
 
generateMipMaps:Boolean (default = true)
 
optimizeForRenderToTexture:Boolean (default = false)
 
scale:Number (default = 1)

Returns
Texture
fromColor()method 
public static function fromColor(width:int, height:int, color:uint = 0xffffffff, optimizeForRenderToTexture:Boolean = false, scale:Number = -1):Texture

Creates a texture with a certain size and color.

Parameters

width:int — in points; number of pixels depends on scale parameter
 
height:int — in points; number of pixels depends on scale parameter
 
color:uint (default = 0xffffffff) — expected in ARGB format (inlude alpha!)
 
optimizeForRenderToTexture:Boolean (default = false) — indicates if this texture will be used as render target
 
scale:Number (default = -1) — if you omit this parameter, 'Starling.contentScaleFactor' will be used.

Returns
Texture
fromTexture()method 
public static function fromTexture(texture:Texture, region:Rectangle = null, frame:Rectangle = null):Texture

Creates a texture that contains a region (in pixels) of another texture. The new texture will reference the base texture; no data is duplicated.

Parameters

texture:Texture
 
region:Rectangle (default = null)
 
frame:Rectangle (default = null)

Returns
Texture