GODPAPER | All Packages | All Classes | Index | Frames No Frames |
Texture

Package | starling.textures
Class | public class Texture
Inheritance | Texture 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.

Context Loss

When the current rendering context is lost (which can happen e.g. on Android and Windows), all texture data is lost. If you have activated "Starling.handleLostContext", 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. To save memory, however, you can restore a texture directly from its source (e.g. an embedded asset):

          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
TextureAtlas

Public Properties

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

| Method | Defined By
--- | --- | ---
|  | adjustTexCoords(texCoords:Vector.<Number>, startIndex:int = 0, stride:int = 0, count:int = -1):void Converts texture coordinates into the format required for rendering. | Texture
|  | 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:Number, height:Number, premultipliedAlpha:Boolean = true, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra):Texture [static] Creates an empty texture of a certain size. | Texture
|  | fromAtfData(data:ByteArray, scale:Number = 1, useMipMaps:Boolean = true, async:Function = null):Texture [static] Creates a texture from the compressed ATF format. | Texture
|  | fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra):Texture [static] Creates a texture object from a bitmap. | Texture
|  | fromBitmapData(data:BitmapData, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra):Texture [static] Creates a texture object from bitmap data. | Texture
|  | fromColor(width:Number, height:Number, color:uint = 0xffffffff, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra):Texture [static] Creates a texture with a certain size and color. | Texture
|  | fromEmbeddedAsset(assetClass:Class, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra):Texture [static] Creates a texture object from an embedded asset class. | 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

base | property

`base:TextureBase` [read-only]

The Stage3D texture object the texture is based on.

Implementation
`public function get base():TextureBase`

format | property |

`format:String` [read-only]

The `Context3DTextureFormat` of the underlying texture data.

Implementation
`public function get format():String`

frame | property |

`frame:Rectangle` [read-only]

The texture frame (see class description).

Implementation
`public function get frame():Rectangle`

height | property |

`height:Number` [read-only]

The height of the texture in points.

Implementation
`public function get height():Number`

mipMapping | property |

`mipMapping:Boolean` [read-only]

Indicates if the texture contains mip maps.

Implementation
`public function get mipMapping():Boolean`

nativeHeight | property |

`nativeHeight:Number` [read-only]

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

Implementation
`public function get nativeHeight():Number`

nativeWidth | property |

`nativeWidth:Number` [read-only]

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

Implementation
`public function get nativeWidth():Number`

premultipliedAlpha | property |

`premultipliedAlpha:Boolean` [read-only]

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

Implementation
`public function get premultipliedAlpha():Boolean`

repeat | property |

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

root | property |

`root:ConcreteTexture` [read-only]

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

Implementation
`public function get root():ConcreteTexture`

scale | property |

`scale:Number` [read-only]

The scale factor, which influences width and height properties.

Implementation
`public function get scale():Number`

width | property |

`width:Number` [read-only]

The width of the texture in points.

Implementation
`public function get width():Number`
Method Detail

adjustTexCoords | () | method

`public function adjustTexCoords(texCoords:Vector.<Number>, startIndex:int = 0, stride:int = 0, count:int = -1):void`

Converts texture coordinates into the format required for rendering. While the texture coordinates of an image always use the range `[0, 1]`, the actual coordinates could be different: you might be working with a SubTexture. This method adjusts the coordinates accordingly.

Parameters

| `texCoords:Vector.<Number>` — a vector containing UV coordinates (optionally, among other data). U and V coordinates always have to come in pairs. The vector is modified in place.
| `startIndex:int` (default = `0`)`` — the index of the first U coordinate in the vector.
| `stride:int` (default = `0`)`` — the distance (in vector elements) of consecutive UV pairs.
| `count:int` (default = `-1`)`` — the number of UV pairs that should be adjusted, or "-1" for all of them.

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. While the texture coordinates of an image always use the range `[0, 1]`, the actual coordinates could be different: you might be working with a SubTexture or a texture frame. This method adjusts the texture and vertex coordinates accordingly.

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:Number, height:Number, premultipliedAlpha:Boolean = true, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra):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 = `true`)`` — 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).

Returns

| `Texture`

fromAtfData | () | method |

`public static function fromAtfData(data:ByteArray, scale:Number = 1, useMipMaps:Boolean = true, async: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; alternatively, you can handle restoration yourself via "texture.root.onRestore".

If the 'async' parameter contains a callback function, the texture is decoded asynchronously. It can only be used when 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`)``
| `async:Function` (default = `null`)``

Returns

| `Texture`

fromBitmap | () | method |

`public static function fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra):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 = `true`)`` — 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).

Returns

| `Texture`

fromBitmapData | () | method |

`public static function fromBitmapData(data:BitmapData, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra):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 texture will be created with the bitmap data of this object.
| `generateMipMaps:Boolean` (default = `true`)`` — 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).

Returns

| `Texture`

fromColor | () | method |

`public static function fromColor(width:Number, height:Number, color:uint = 0xffffffff, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra):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 = `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.
| `format:String` (default = `bgra`)`` — the context3D texture format to use. Pass one of the packed or compressed formats to save memory.

Returns

| `Texture`

fromEmbeddedAsset | () | method |

`public static function fromEmbeddedAsset(assetClass:Class, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra):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 = `true`)`` — 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.

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`

Thu Jan 16 2014, 01:11 PM +08:00