Packagestarling.textures
Classpublic class TextureAtlas
InheritanceTextureAtlas Inheritance 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:

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>
Texture Frame

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'/>
Texture Rotation

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.


Public Properties
 PropertyDefined By
  texture : Texture
[read-only] The base texture that makes up the atlas.
TextureAtlas
Public Methods
 MethodDefined 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
  
getTextures(prefix:String, out: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
 MethodDefined 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
Property Detail
textureproperty
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, data:* = null)

Create a texture atlas from a texture and atlas data. The second argument typically points to an XML file.

Parameters
texture:Texture
 
data:* (default = null)
Method Detail
addRegion()method
public function 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.

Parameters

name:String
 
region:Rectangle
 
frame:Rectangle (default = null)
 
rotated:Boolean (default = false)

addSubTexture()method 
public function addSubTexture(name:String, subTexture:SubTexture):void

Adds 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():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, 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)

Returns
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

Returns
Rectangle
getRotation()method 
public function getRotation(name:String):Boolean

If 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

Returns
Boolean
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, 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)

Returns
Vector.<Texture>
parseAtlasData()method 
protected function parseAtlasData(data:*):void

Parses 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):void

This 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):void

Removes a region with a certain name.

Parameters

name:String





Mon Jun 11 2018, 02:16 PM +02:00