| Package | starling.textures |
| Class | public class TextureAtlas |
| Inheritance | TextureAtlas  Object |
Using a texture atlas for your textures solves two problems:
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'/>
Some atlas generators can optionally rotate individual textures to optimize the texture
distribution. This is supported via the boolean attribute "rotated". If it is set to
true for a certain subtexture, this means that the texture on the atlas
has been rotated by 90 degrees, clockwise. Starling will undo that rotation by rotating
it counter-clockwise.
In this case, the positional coordinates (x, y, width, height)
are expected to point at the subtexture as it is present on the atlas (in its rotated
form), while the "frame" properties must describe the texture in its upright form.
| Property | Defined By | ||
|---|---|---|---|
| texture : Texture [read-only] The base texture that makes up the atlas. | TextureAtlas | ||
| 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, rotated:Boolean = false):void Adds a named region for a SubTexture (described by rectangle with coordinates in
points) 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, out: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, or null
if no region with that name has been registered. | TextureAtlas | ||
getRotation(name:String):Boolean If true, the specified region in the atlas is rotated by 90 degrees (clockwise). | TextureAtlas | ||
getTexture(name:String):Texture Retrieves a SubTexture by name. | TextureAtlas | ||
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 | ||
| 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 | ||
| texture | property |
texture:Texture [read-only] The base texture that makes up the atlas.
public function get texture():Texture| 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.
Parameterstexture:Texture | |
atlasXml:XML (default = null) |
| addRegion | () | method |
public function addRegion(name:String, region:Rectangle, frame:Rectangle = null, rotated:Boolean = false):voidAdds a named region for a SubTexture (described by rectangle with coordinates in points) with an optional frame.
Parameters
name:String | |
region:Rectangle | |
frame:Rectangle (default = null) | |
rotated:Boolean (default = false) |
| dispose | () | method |
public function dispose():voidDisposes 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 |
Rectangle |
| getNames | () | method |
public function getNames(prefix:String, out:Vector.<String> = null):Vector.<String>Returns all texture names that start with a certain string, sorted alphabetically.
Parameters
prefix:String | |
out:Vector.<String> (default = null) |
Vector.<String> |
| getRegion | () | method |
public function getRegion(name:String):Rectangle Returns the region rectangle associated with a specific name, or null
if no region with that name has been registered.
Parameters
name:String |
Rectangle |
| getRotation | () | method |
public function getRotation(name:String):BooleanIf true, the specified region in the atlas is rotated by 90 degrees (clockwise). The SubTexture is thus rotated counter-clockwise to cancel out that transformation.
Parameters
name:String |
Boolean |
| getTexture | () | method |
public function getTexture(name:String):Texture Retrieves a SubTexture by name. Returns null if it is not found.
Parameters
name:String |
Texture |
| getTextures | () | method |
public function getTextures(prefix:String, out:Vector.<Texture> = null):Vector.<Texture>Returns all textures that start with a certain string, sorted alphabetically (especially useful for "MovieClip").
Parameters
prefix:String | |
out:Vector.<Texture> (default = null) |
Vector.<Texture> |
| parseAtlasXml | () | method |
protected function parseAtlasXml(atlasXml:XML):voidThis 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):voidRemoves a region with a certain name.
Parameters
name:String |