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

Package | starling.textures
Class | public class TextureAtlas
Inheritance | TextureAtlas Object

A texture atlas is a collection of many smaller textures in one big image. This class is used to access textures from such an atlas.

Using a texture atlas for your textures solves two problems:

- Whenever you switch between textures, the batching of image objects is disrupted.
- Any Stage3D texture has to have side lengths that are powers of two. Starling hides this limitation from you, but at the cost of additional graphics memory.

By using a texture atlas, you avoid both texture switches and the power-of-two limitation. All textures are within one big "super-texture", and Starling takes care that the correct part of this texture is displayed.

There are several ways to create a texture atlas. One is to use the atlas generator script that is bundled with Starling's sibling, the Sparrow framework. It was only tested in Mac OS X, though. A great multi-platform alternative is the commercial tool Texture Packer.

Whatever tool you use, Starling expects the following file format:

             <TextureAtlas imagePath='atlas.png'>
               <SubTexture name='texture_1' x='0'  y='0' width='50' height='50'/>
               <SubTexture name='texture_2' x='50' y='0' width='20' height='30'/>
             </TextureAtlas>

If your images have transparent areas at their edges, you can make use of the `frame` property of the Texture class. Trim the texture by removing the transparent edges and specify the original texture size like this:

             <SubTexture name='trimmed' x='0' y='0' height='10' width='10'
                 frameX='-10' frameY='-10' frameWidth='30' frameHeight='30'/>

Public Properties

| Property | Defined By
--- | --- | ---
|  | texture : Texture [read-only] The base texture that makes up the atlas. | TextureAtlas

Public Methods

| Method | Defined By
--- | --- | ---
|  | TextureAtlas(texture:Texture, atlasXml:XML = null) Create a texture atlas from a texture by parsing the regions from an XML file. | TextureAtlas
|  | addRegion(name:String, region:Rectangle, frame:Rectangle = null):void Adds a named region for a subtexture (described by rectangle with coordinates in pixels) with an optional frame. | TextureAtlas
|  | dispose():void Disposes the atlas texture. | TextureAtlas
|  | getFrame(name:String):Rectangle Returns the frame rectangle of a specific region, or null if that region has no frame. | TextureAtlas
|  | getNames(prefix:String, result:Vector.<String> = null):Vector.<String> Returns all texture names that start with a certain string, sorted alphabetically. | TextureAtlas
|  | getRegion(name:String):Rectangle Returns the region rectangle associated with a specific name. | TextureAtlas
|  | getTexture(name:String):Texture Retrieves a subtexture by name. | TextureAtlas
|  | getTextures(prefix:String, result:Vector.<Texture> = null):Vector.<Texture> Returns all textures that start with a certain string, sorted alphabetically (especially useful for "MovieClip"). | TextureAtlas
|  | removeRegion(name:String):void Removes a region with a certain name. | TextureAtlas

Protected Methods

| Method | Defined By
--- | --- | ---
|  | parseAtlasXml(atlasXml:XML):void This function is called by the constructor and will parse an XML in Starling's default atlas file format. | TextureAtlas

Property Detail

texture | property

`texture:Texture` [read-only]

The base texture that makes up the atlas.

Implementation
`public function get texture():Texture`
Constructor Detail

TextureAtlas | () | Constructor

`public function TextureAtlas(texture:Texture, atlasXml:XML = null)`

Create a texture atlas from a texture by parsing the regions from an XML file.

Parameters

| `texture:Texture`
| `atlasXml:XML` (default = `null`)``

Method Detail

addRegion | () | method

`public function addRegion(name:String, region:Rectangle, frame:Rectangle = null):void`

Adds a named region for a subtexture (described by rectangle with coordinates in pixels) with an optional frame.

Parameters

| `name:String`
| `region:Rectangle`
| `frame:Rectangle` (default = `null`)``

dispose | () | method |

`public function dispose():void`

Disposes the atlas texture.

getFrame | () | method |

`public function getFrame(name:String):Rectangle`

Returns the frame rectangle of a specific region, or `null` if that region has no frame.

Parameters

| `name:String`

Returns

| `Rectangle`

getNames | () | method |

`public function getNames(prefix:String, result:Vector.<String> = null):Vector.<String>`

Returns all texture names that start with a certain string, sorted alphabetically.

Parameters

| `prefix:String`
| `result:Vector.<String>` (default = `null`)``

Returns

| `Vector.<String>`

getRegion | () | method |

`public function getRegion(name:String):Rectangle`

Returns the region rectangle associated with a specific name.

Parameters

| `name:String`

Returns

| `Rectangle`

getTexture | () | method |

`public function getTexture(name:String):Texture`

Retrieves a subtexture by name. Returns `null` if it is not found.

Parameters

| `name:String`

Returns

| `Texture`

getTextures | () | method |

`public function getTextures(prefix:String, result:Vector.<Texture> = null):Vector.<Texture>`

Returns all textures that start with a certain string, sorted alphabetically (especially useful for "MovieClip").

Parameters

| `prefix:String`
| `result:Vector.<Texture>` (default = `null`)``

Returns

| `Vector.<Texture>`

parseAtlasXml | () | method |

`protected function parseAtlasXml(atlasXml:XML):void`

This function is called by the constructor and will parse an XML in Starling's default atlas file format. Override this method to create custom parsing logic (e.g. to support a different file format).

Parameters

| `atlasXml:XML`

removeRegion | () | method |

`public function removeRegion(name:String):void`

Removes a region with a certain name.

Parameters

| `name:String`

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