| 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, data:* = null) Create a texture atlas from a texture and atlas data. | 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 | ||
addSubTexture(name:String, subTexture:SubTexture):void Adds a named region for an instance of SubTexture or an instance of its sub-classes. | 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 | ||
removeRegions(prefix:String):void Removes all regions with names that start with the given prefix. | TextureAtlas | ||
| Method | Defined By | ||
|---|---|---|---|
parseAtlasData(data:*):void Parses the data that's passed as second argument to the constructor. | TextureAtlas | ||
parseAtlasXml(atlasXml:XML):void This function is called by 'parseAtlasData' for XML data. | 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, data:* = null)Create a texture atlas from a texture and atlas data. The second argument typically points to an XML file.
Parameterstexture:Texture | |
data:* (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) |
| addSubTexture | () | method |
public function addSubTexture(name:String, subTexture:SubTexture):voidAdds a named region for an instance of SubTexture or an instance of its sub-classes.
Parameters
name:String | |
subTexture:SubTexture |
| 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> |
| parseAtlasData | () | method |
protected function parseAtlasData(data:*):voidParses the data that's passed as second argument to the constructor. Override this method to add support for additional file formats.
Parameters
data:* |
| parseAtlasXml | () | method |
protected function parseAtlasXml(atlasXml:XML):voidThis function is called by 'parseAtlasData' for XML data. It will parse an XML in Starling's default atlas file format. Override this method to create custom parsing logic (e.g. to support additional attributes).
Parameters
atlasXml:XML |
| removeRegion | () | method |
public function removeRegion(name:String):voidRemoves a region with a certain name.
Parameters
name:String |
| removeRegions | () | method |
public function removeRegions(prefix:String):voidRemoves all regions with names that start with the given prefix. If no arguments are given, all regions will be removed.
Parameters
prefix:String |