TextureAtlas
public class
loom2d.textures.TextureAtlas
Description
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:
- There is always one texture active at a given moment. Whenever you change the active texture, a "texture-switch" has to be executed, and that switch takes time.
- Any Loom texture should 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'/>
API overview
Constructor
TextureAtlas
(
texture: Texture
,
atlasXml: XMLNode
= null
)
Create a texture atlas from a texture by parsing the regions from an XML file
Functions
Public functions
| 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 |
| bindToFile ( path: String ): Void |
Enable live reload for this atlas when this file changes |
| dispose (): Void |
Disposes the atlas texture |
| getFrame ( name: String ): Rectangle |
Returns the frame rectangle of a specific region, or |
| getNames ( prefix: String = , result: Vector.<String> = null ): Vector.<String> |
Returns all texture names that start with a certain string, sorted alphabetically |
| getRegion ( name: String ): Rectangle |
Returns the region rectangle associated with a specific name |
| getTexture ( name: String , ignoreFrame: Boolean = false ): Texture |
Retrieves a subtexture by name, with an option to ignore the texture frame data |
| getTextures ( prefix: String = , result: Vector.<Texture> = null , ignoreFrame: Boolean = false ): Vector.<Texture> |
Returns all textures that start with a certain string, sorted alphabetically, with an option to ignore the texture frame data (especially useful for "MovieClip") |
| removeRegion ( name: String ): Void |
Removes a region with a certain name |
Protected functions
Constructor
Functions
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 = null |
bindToFile ( path: String ): Void
Enable live reload for this atlas when this file changes.
Parameters
| path: String |
getFrame ( name: String ): Rectangle
Returns the frame rectangle of a specific region, or null if that region
has no frame.
Parameters
| name: String |
getFullTypeName
(): String
Inherited from Object
native
Gets the fully qualified type name of the Object. The fully qualified type name includes the package of the type.
Returns
| String | fully qualified type name of the Object. |
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> = null |
getRegion ( name: String ): Rectangle
Returns the region rectangle associated with a specific name.
Parameters
| name: String |
getTexture ( name: String , ignoreFrame: Boolean = false ): Texture
Retrieves a subtexture by name, with an option to ignore the texture frame data. Returns null if it is not found.
Parameters
| name: String | |
| ignoreFrame: Boolean = false |
getTextures ( prefix: String = , result: Vector.<Texture> = null , ignoreFrame: Boolean = false ): Vector.<Texture>
Returns all textures that start with a certain string, sorted alphabetically, with an option to ignore the texture frame data (especially useful for "MovieClip").
Parameters
| prefix: String = | |
| result: Vector.<Texture> = null | |
| ignoreFrame: Boolean = false |
getType
(): Type
Inherited from Object
native
Gets the Type that describes the Object.
Returns
| Type | The Type that describes the object. |