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, the most probably candidate for this job is the Image class.

Creating a texture

The Texture class is abstract, i.e. you cannot create instance of this class through its constructor. Instead, it offers a variety of factory methods, like fromBitmapData or fromEmbeddedAsset.

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.

Beginning with AIR 17, you can use Starling textures to show video content (if the current platform supports it; see "SystemUtil.supportsVideoTexture"). The two factory methods "fromCamera" and "fromNetStream" allow you to make use of this feature.

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, mipmapping is disabled by default.

Texture Frame

The frame property of a texture allows you to let a texture appear inside the bounds of an image, leaving a transparent border 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.

Context Loss

When the current rendering context is lost (which can happen on all platforms, but is especially common on Android and Windows), all texture data is destroyed. However, Starling will try to restore the textures. To do that, it will keep the bitmap and ATF data in memory - at the price of increased RAM consumption. You can optimize this behavior, though, by restoring the texture directly from its source, like in this example:

      var texture:Texture = Texture.fromBitmap(new EmbeddedBitmap());
      texture.root.onRestore = function():void
      {
          texture.root.uploadFromBitmap(new EmbeddedBitmap());
      };

The onRestore-method will be called when the context was lost and the texture has been recreated (but is still empty). If you use the "AssetManager" class to manage your textures, this will be done automatically.

See also

starling.display.Image
starling.utils.AssetManager
starling.utils.SystemUtil
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 if it has one (see class description), otherwise null.
Texture
  frameHeight : Number
[read-only] The width of the texture in points, taking into account the frame rectangle (if there is one).
Texture
  frameWidth : Number
[read-only] The height of the texture in points, taking into account the frame rectangle (if there is one).
Texture
  height : Number
[read-only] The height of the texture in points.
Texture
  maxSize : int
[static] [read-only] Returns the maximum size constraint (for both width and height) for textures in the current Context3D profile.
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
  root : ConcreteTexture
[read-only] The concrete texture the texture is based on.
Texture
  scale : Number
[read-only] The scale factor, which influences width and height properties.
Texture
  transformationMatrix : Matrix
[read-only] The matrix that is used to transform the texture coordinates into the coordinate space of the parent texture, if there is one.
Texture
  transformationMatrixToRoot : Matrix
[read-only] The matrix that is used to transform the texture coordinates into the coordinate space of the root texture, if this instance is not the root.
Texture
  width : Number
[read-only] The width of the texture in points.
Texture
Public Methods
 MethodDefined By
  
dispose():void
Disposes the underlying texture data.
Texture
  
empty(width:Number, height:Number, premultipliedAlpha:Boolean = true, mipMapping:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, forcePotTexture:Boolean = false):Texture
[static] Creates an empty texture of a certain size.
Texture
  
fromAtfData(data:ByteArray, scale:Number = 1, useMipMaps:Boolean = true, async:Function = null, premultipliedAlpha:Boolean = false):Texture
[static] Creates a texture from ATF data (Adobe Texture Compression).
Texture
  
fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture
[static] Creates a texture object from a bitmap.
Texture
  
fromBitmapData(data:BitmapData, generateMipMaps:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture
[static] Creates a texture object from bitmap data.
Texture
  
fromCamera(camera:Camera, scale:Number = 1, onComplete:Function = null):Texture
[static] Creates a video texture from a camera.
Texture
  
fromColor(width:Number, height:Number, color:uint = 0xffffff, alpha:Number = 1.0, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, forcePotTexture:Boolean = false):Texture
[static] Creates a texture with a certain size and color.
Texture
  
fromData(data:Object, options:TextureOptions = null):Texture
[static] Creates a texture from any of the supported data types, using the specified options.
Texture
  
fromEmbeddedAsset(assetClass:Class, mipMapping:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture
[static] Creates a texture object from an embedded asset class.
Texture
  
fromNetStream(stream:NetStream, scale:Number = 1, onComplete:Function = null):Texture
[static] Creates a video texture from a NetStream.
Texture
  
fromTexture(texture:Texture, region:Rectangle = null, frame:Rectangle = null, rotated:Boolean = false, scaleModifier:Number = 1.0):Texture
[static] Creates a texture that contains a region (in pixels) of another texture.
Texture
  
fromTextureBase(base:TextureBase, width:int, height:int, options:TextureOptions = null):ConcreteTexture
[static] Creates a texture from a TextureBase object.
Texture
  
getTexCoords(vertexData:VertexData, vertexID:int, attrName:String = texCoords, out:Point = null):Point
Reads a pair of texture coordinates from the given VertexData instance and transforms them into the current texture's coordinate system.
Texture
  
globalToLocal(u:Number, v:Number, out:Point = null):Point
Transforms the given texture coordinates from the root texture's coordinate system to the local coordinate system.
Texture
  
localToGlobal(u:Number, v:Number, out:Point = null):Point
Transforms the given texture coordinates from the local coordinate system into the root texture's coordinate system.
Texture
  
setTexCoords(vertexData:VertexData, vertexID:int, attrName:String, u:Number, v:Number):void
Writes the given texture coordinates to a VertexData instance after transforming them into the root texture's coordinate system.
Texture
  
setupTextureCoordinates(vertexData:VertexData, vertexID:int = 0, attrName:String = texCoords):void
Sets up a VertexData instance with the correct texture coordinates for 4 vertices so that the texture is mapped to the complete quad.
Texture
  
setupVertexPositions(vertexData:VertexData, vertexID:int = 0, attrName:String = position, bounds:Rectangle = null):void
Sets up a VertexData instance with the correct positions for 4 vertices so that the texture can be mapped onto it unscaled.
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 if it has one (see class description), otherwise null.

CAUTION: not a copy, but the actual object! Do not modify!


Implementation
    public function get frame():Rectangle
frameHeightproperty 
frameHeight:Number  [read-only]

The width of the texture in points, taking into account the frame rectangle (if there is one).


Implementation
    public function get frameHeight():Number
frameWidthproperty 
frameWidth:Number  [read-only]

The height of the texture in points, taking into account the frame rectangle (if there is one).


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

The height of the texture in points.


Implementation
    public function get height():Number
maxSizeproperty 
maxSize:int  [read-only]

Returns the maximum size constraint (for both width and height) for textures in the current Context3D profile.


Implementation
    public static function get maxSize():int
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
rootproperty 
root:ConcreteTexture  [read-only]

The concrete 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
transformationMatrixproperty 
transformationMatrix:Matrix  [read-only]

The matrix that is used to transform the texture coordinates into the coordinate space of the parent texture, if there is one.

The default value is null

CAUTION: not a copy, but the actual object! Never modify this matrix!

.


Implementation
    public function get transformationMatrix():Matrix
transformationMatrixToRootproperty 
transformationMatrixToRoot:Matrix  [read-only]

The matrix that is used to transform the texture coordinates into the coordinate space of the root texture, if this instance is not the root.

The default value is null

CAUTION: not a copy, but the actual object! Never modify this matrix!

.


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

The width of the texture in points.


Implementation
    public function get width():Number
Method Detail
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:Number, height:Number, premultipliedAlpha:Boolean = true, mipMapping:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, forcePotTexture:Boolean = false):Texture

Creates an empty texture of a certain size. Beware that the texture can only be used after you either upload some color data ("texture.root.upload...") or clear the texture ("texture.root.clear()").

Parameters

width:Number — in points; number of pixels depends on scale parameter
 
height:Number — in points; number of pixels depends on scale parameter
 
premultipliedAlpha:Boolean (default = true) — the PMA format you will use the texture with. If you will use the texture for bitmap data, use "true"; for ATF data, use "false".
 
mipMapping:Boolean (default = false) — indicates if mipmaps should be used for this texture. When you upload bitmap data, this decides if mipmaps will be created; when you upload ATF data, this decides if mipmaps inside the ATF file will be displayed.
 
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.
 
format:String (default = bgra) — the context3D texture format to use. Pass one of the packed or compressed formats to save memory (at the price of reduced image quality).
 
forcePotTexture:Boolean (default = false) — indicates if the underlying Stage3D texture should be created as the power-of-two based "Texture" class instead of the more memory efficient "RectangleTexture".

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

Creates a texture from ATF data (Adobe Texture Compression). Beware: you must not dispose 'data' if Starling should handle a lost device context; alternatively, you can handle restoration yourself via "texture.root.onRestore".

Parameters

data:ByteArray — the raw data from an ATF file.
 
scale:Number (default = 1) — the scale factor of the created texture. This affects the reported width and height of the texture object.
 
useMipMaps:Boolean (default = true) — If the ATF data contains mipmaps, this parameter controls if they are used; if it does not, this parameter has no effect.
 
async:Function (default = null) — If you pass a callback function, the texture will be decoded asynchronously, which allows a smooth framerate even during the loading process. However, don't use the texture before the callback has been executed. This is the expected function definition: function(texture:Texture):void;
 
premultipliedAlpha:Boolean (default = false) — Indicates if the ATF data contains pixels in PMA format. This is "false" for most ATF files, but can be customized in some tools.

Returns
Texture
fromBitmap()method 
public static function fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture

Creates a texture object from a bitmap. Beware: you must not dispose the bitmap's data if Starling should handle a lost device context alternatively, you can handle restoration yourself via "texture.root.onRestore".

Parameters

bitmap:Bitmap — the texture will be created with the bitmap data of this object.
 
generateMipMaps:Boolean (default = false) — indicates if mipMaps will be created.
 
optimizeForRenderToTexture:Boolean (default = false) — indicates if this texture will be used as render target
 
scale:Number (default = 1) — the scale factor of the created texture. This affects the reported width and height of the texture object.
 
format:String (default = bgra) — the context3D texture format to use. Pass one of the packed or compressed formats to save memory (at the price of reduced image quality).
 
forcePotTexture:Boolean (default = false) — indicates if the underlying Stage3D texture should be created as the power-of-two based "Texture" class instead of the more memory efficient "RectangleTexture".

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

Creates a texture object from bitmap data. Beware: you must not dispose 'data' if Starling should handle a lost device context; alternatively, you can handle restoration yourself via "texture.root.onRestore".

Parameters

data:BitmapData — the bitmap data to upload to the texture.
 
generateMipMaps:Boolean (default = false) — indicates if mipMaps will be created.
 
optimizeForRenderToTexture:Boolean (default = false) — indicates if this texture will be used as render target
 
scale:Number (default = 1) — the scale factor of the created texture. This affects the reported width and height of the texture object.
 
format:String (default = bgra) — the context3D texture format to use. Pass one of the packed or compressed formats to save memory (at the price of reduced image quality).
 
forcePotTexture:Boolean (default = false) — indicates if the underlying Stage3D texture should be created as the power-of-two based "Texture" class instead of the more memory efficient "RectangleTexture".

Returns
Texture
fromCamera()method 
public static function fromCamera(camera:Camera, scale:Number = 1, onComplete:Function = null):Texture

Creates a video texture from a camera. Beware that the texture must not be used before the 'onComplete' callback has been executed; until then, it will have a size of zero pixels.

Here is a minimal sample showing how to display a camera video:

          var camera:Camera = Camera.getCamera();
          var texture:Texture = Texture.fromCamera(camera, 1, function():void
          {
              addChild(new Image(texture));
          });

Parameters

camera:Camera — the camera from which the video data is streamed.
 
scale:Number (default = 1) — the scale factor of the created texture. This affects the reported width and height of the texture object.
 
onComplete:Function (default = null) — will be executed when the texture is ready. May contain a parameter of type 'Texture'.

Returns
Texture
fromColor()method 
public static function fromColor(width:Number, height:Number, color:uint = 0xffffff, alpha:Number = 1.0, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, forcePotTexture:Boolean = false):Texture

Creates a texture with a certain size and color.

Parameters

width:Number — in points; number of pixels depends on scale parameter
 
height:Number — in points; number of pixels depends on scale parameter
 
color:uint (default = 0xffffff) — the RGB color the texture will be filled up
 
alpha:Number (default = 1.0) — the alpha value that will be used for every pixel
 
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.
 
format:String (default = bgra) — the context3D texture format to use. Pass one of the packed or compressed formats to save memory.
 
forcePotTexture:Boolean (default = false) — indicates if the underlying Stage3D texture should be created as the power-of-two based "Texture" class instead of the more memory efficient "RectangleTexture".

Returns
Texture
fromData()method 
public static function fromData(data:Object, options:TextureOptions = null):Texture

Creates a texture from any of the supported data types, using the specified options.

Parameters

data:Object — Either an embedded asset class, a Bitmap, BitmapData, or a ByteArray with ATF data.
 
options:TextureOptions (default = null) — Specifies options about the texture settings, e.g. the scale factor. If left empty, the default options will be used.

Returns
Texture
fromEmbeddedAsset()method 
public static function fromEmbeddedAsset(assetClass:Class, mipMapping:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture

Creates a texture object from an embedded asset class. Textures created with this method will be restored directly from the asset class in case of a context loss, which guarantees a very economic memory usage.

Parameters

assetClass:Class — must contain either a Bitmap or a ByteArray with ATF data.
 
mipMapping:Boolean (default = false) — for Bitmaps, indicates if mipMaps will be created; for ATF data, indicates if the contained mipMaps will be used.
 
optimizeForRenderToTexture:Boolean (default = false) — indicates if this texture will be used as render target.
 
scale:Number (default = 1) — the scale factor of the created texture.
 
format:String (default = bgra) — the context3D texture format to use. Ignored for ATF data.
 
forcePotTexture:Boolean (default = false) — indicates if the underlying Stage3D texture should be created as the power-of-two based "Texture" class instead of the more memory efficient "RectangleTexture". (Only applicable to bitmaps; ATF textures are always POT-textures, anyway.)

Returns
Texture
fromNetStream()method 
public static function fromNetStream(stream:NetStream, scale:Number = 1, onComplete:Function = null):Texture

Creates a video texture from a NetStream.

Below, you'll find a minimal sample showing how to stream a video from a file. Note that ns.play() is called only after creating the texture, and outside the onComplete-callback. It's recommended to always make the calls in this order; otherwise, playback won't start on some platforms.

          var nc:NetConnection = new NetConnection();
          nc.connect(null);
          
          var ns:NetStream = new NetStream(nc);
          var texture:Texture = Texture.fromNetStream(ns, 1, function():void
          {
              addChild(new Image(texture));
          });
          
          var file:File = File.applicationDirectory.resolvePath("bugs-bunny.m4v");
          ns.play(file.url);

Parameters

stream:NetStream — the NetStream from which the video data is streamed. Beware that 'play' should be called only after the method returns, and outside the onComplete callback.
 
scale:Number (default = 1) — the scale factor of the created texture. This affects the reported width and height of the texture object.
 
onComplete:Function (default = null) — will be executed when the texture is ready. Contains a parameter of type 'Texture'.

Returns
Texture
fromTexture()method 
public static function fromTexture(texture:Texture, region:Rectangle = null, frame:Rectangle = null, rotated:Boolean = false, scaleModifier:Number = 1.0):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 — The texture you want to create a SubTexture from.
 
region:Rectangle (default = null) — The region of the parent texture that the SubTexture will show (in points).
 
frame:Rectangle (default = null) — If the texture was trimmed, the frame rectangle can be used to restore the trimmed area.
 
rotated:Boolean (default = false) — If true, the SubTexture will show the parent region rotated by 90 degrees (CCW).
 
scaleModifier:Number (default = 1.0) — The scale factor of the new texture will be calculated by multiplying the parent texture's scale factor with this value.

Returns
Texture
fromTextureBase()method 
public static function fromTextureBase(base:TextureBase, width:int, height:int, options:TextureOptions = null):ConcreteTexture

Creates a texture from a TextureBase object.

Parameters

base:TextureBase — a Stage3D texture object created through the current context.
 
width:int — the width of the texture in pixels (not points!).
 
height:int — the height of the texture in pixels (not points!).
 
options:TextureOptions (default = null) — specifies options about the texture settings, e.g. the scale factor. If left empty, the default options will be used. Note that not all options are supported by all texture types.

Returns
ConcreteTexture
getTexCoords()method 
public function getTexCoords(vertexData:VertexData, vertexID:int, attrName:String = texCoords, out:Point = null):Point

Reads a pair of texture coordinates from the given VertexData instance and transforms them into the current texture's coordinate system. (Remember, the VertexData instance will always contain the coordinates in the root texture's coordinate system!)

Parameters

vertexData:VertexData
 
vertexID:int
 
attrName:String (default = texCoords)
 
out:Point (default = null)

Returns
Point
globalToLocal()method 
public function globalToLocal(u:Number, v:Number, out:Point = null):Point

Transforms the given texture coordinates from the root texture's coordinate system to the local coordinate system.

Parameters

u:Number
 
v:Number
 
out:Point (default = null)

Returns
Point
localToGlobal()method 
public function localToGlobal(u:Number, v:Number, out:Point = null):Point

Transforms the given texture coordinates from the local coordinate system into the root texture's coordinate system.

Parameters

u:Number
 
v:Number
 
out:Point (default = null)

Returns
Point
setTexCoords()method 
public function setTexCoords(vertexData:VertexData, vertexID:int, attrName:String, u:Number, v:Number):void

Writes the given texture coordinates to a VertexData instance after transforming them into the root texture's coordinate system. That way, the texture coordinates can be used directly to sample the texture in the fragment shader.

Parameters

vertexData:VertexData
 
vertexID:int
 
attrName:String
 
u:Number
 
v:Number

setupTextureCoordinates()method 
public function setupTextureCoordinates(vertexData:VertexData, vertexID:int = 0, attrName:String = texCoords):void

Sets up a VertexData instance with the correct texture coordinates for 4 vertices so that the texture is mapped to the complete quad.

Parameters

vertexData:VertexData — the vertex data to which the texture coordinates will be written.
 
vertexID:int (default = 0) — the start position within the VertexData instance.
 
attrName:String (default = texCoords) — the attribute name referencing the vertex positions.

setupVertexPositions()method 
public function setupVertexPositions(vertexData:VertexData, vertexID:int = 0, attrName:String = position, bounds:Rectangle = null):void

Sets up a VertexData instance with the correct positions for 4 vertices so that the texture can be mapped onto it unscaled. If the texture has a frame, the vertices will be offset accordingly.

Parameters

vertexData:VertexData — the VertexData instance to which the positions will be written.
 
vertexID:int (default = 0) — the start position within the VertexData instance.
 
attrName:String (default = position) — the attribute name referencing the vertex positions.
 
bounds:Rectangle (default = null) — useful only for textures with a frame. This will position the vertices at the correct position within the given bounds, distorted appropriately.