| Package | starling.textures |
| Class | public class Texture |
| Inheritance | Texture  Object |
| Subclasses | ConcreteTexture, SubTexture |
A texture stores the information that represents an image. It cannot be added to the display list directly; instead it has to be mapped onto a display object. In Starling, that display object is the class "Image".
Texture FormatsSince textures can be created from a "BitmapData" object, Starling supports any bitmap format that is supported by Flash. And since you can render any Flash display object into a BitmapData object, you can use this to display non-Starling content in Starling - e.g. Shape objects.
Starling also supports ATF textures (Adobe Texture Format), which is a container for compressed texture formats that can be rendered very efficiently by the GPU. Refer to the Flash documentation for more information about this format.
Mip MappingMipMaps are scaled down versions of a texture. When an image is displayed smaller than its natural size, the GPU may display the mip maps instead of the original texture. This reduces aliasing and accelerates rendering. It does, however, also need additional memory; for that reason, you can choose if you want to create them or not.
Texture FrameThe frame property of a texture allows you let a texture appear inside the bounds of an image, leaving a transparent space around the texture. The frame rectangle is specified in the coordinate system of the texture (not the image):
var frame:Rectangle = new Rectangle(-10, -10, 30, 30);
var texture:Texture = Texture.fromTexture(anotherTexture, null, frame);
var image:Image = new Image(texture);This code would create an image with a size of 30x30, with the texture placed at
x=10, y=10 within that image (assuming that 'anotherTexture' has a width and
height of 10 pixels, it would appear in the middle of the image).
The texture atlas makes use of this feature, as it allows to crop transparent edges of a texture and making up for the changed size by specifying the original texture frame. Tools like TexturePacker use this to optimize the atlas.
Texture CoordinatesIf, on the other hand, you want to show only a part of the texture in an image (i.e. to crop the the texture), you can either create a subtexture (with the method 'Texture.fromTexture()' and specifying a rectangle for the region), or you can manipulate the texture coordinates of the image object. The method 'image.setTexCoords' allows you to do that.
Context LossWhen the current rendering context is lost (which can happen e.g. on Android and Windows), all texture data is lost. If you have activated "Starling.handleLostContext", however, Starling will try to restore the textures. To do that, it will keep the bitmap and ATF data in memory - at the price of increased RAM consumption. To save memory, however, you can restore a texture directly from its source (e.g. an embedded asset):
var texture:Texture = Texture.fromBitmap(new EmbeddedBitmap());
texture.root.onRestore = function():void
{
texture.root.uploadFromBitmap(new EmbeddedBitmap());
};The "onRestore"-method will be called when the context was lost and the texture has been recreated (but is still empty). If you use the "AssetManager" class to manage your textures, this will be done automatically.
See also
| Property | Defined By | ||
|---|---|---|---|
| base : TextureBase [read-only] The Stage3D texture object the texture is based on. | Texture | ||
| format : String [read-only] The Context3DTextureFormat of the underlying texture data. | Texture | ||
| frame : Rectangle [read-only] The texture frame if it has one (see class description), otherwise null. | Texture | ||
| height : Number [read-only] The height of the texture in points. | Texture | ||
| mipMapping : Boolean [read-only] Indicates if the texture contains mip maps. | Texture | ||
| nativeHeight : Number [read-only] The height of the texture in pixels (without scale adjustment). | Texture | ||
| nativeWidth : Number [read-only] The width of the texture in pixels (without scale adjustment). | Texture | ||
| premultipliedAlpha : Boolean [read-only] Indicates if the alpha values are premultiplied into the RGB values. | Texture | ||
| repeat : Boolean [read-only] Indicates if the texture should repeat like a wallpaper or stretch the outermost pixels. | Texture | ||
| root : ConcreteTexture [read-only] The concrete texture the texture is based on. | Texture | ||
| scale : Number [read-only] The scale factor, which influences width and height properties. | Texture | ||
| width : Number [read-only] The width of the texture in points. | Texture | ||
| Method | Defined By | ||
|---|---|---|---|
adjustTexCoords(texCoords:Vector.<Number>, startIndex:int = 0, stride:int = 0, count:int = -1):void Converts texture coordinates into the format required for rendering. | Texture | ||
adjustVertexData(vertexData:VertexData, vertexID:int, count:int):void Converts texture coordinates and vertex positions of raw vertex data into the format
required for rendering. | Texture | ||
dispose():void Disposes the underlying texture data. | Texture | ||
empty(width:Number, height:Number, premultipliedAlpha:Boolean = true, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, repeat:Boolean = false):Texture [static] Creates an empty texture of a certain size. | Texture | ||
fromAtfData(data:ByteArray, scale:Number = 1, useMipMaps:Boolean = true, async:Function = null, repeat:Boolean = false):Texture [static] Creates a texture from the compressed ATF format. | Texture | ||
fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, repeat:Boolean = false):Texture [static] Creates a texture object from a bitmap. | Texture | ||
fromBitmapData(data:BitmapData, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, repeat:Boolean = false):Texture [static] Creates a texture object from bitmap data. | Texture | ||
fromColor(width:Number, height:Number, color:uint = 0xffffffff, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra):Texture [static] Creates a texture with a certain size and color. | Texture | ||
[static] Creates a texture object from any of the supported data types, using the specified
options. | Texture | ||
fromEmbeddedAsset(assetClass:Class, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, repeat:Boolean = false):Texture [static] Creates a texture object from an embedded asset class. | Texture | ||
fromTexture(texture:Texture, region:Rectangle = null, frame:Rectangle = null, rotated:Boolean = false):Texture [static] Creates a texture that contains a region (in pixels) of another texture. | Texture | ||
| base | property |
base:TextureBase [read-only] The Stage3D texture object the texture is based on.
public function get base():TextureBase| format | property |
format:String [read-only] The Context3DTextureFormat of the underlying texture data.
public function get format():String| frame | property |
frame:Rectangle [read-only] The texture frame if it has one (see class description), otherwise null.
Only SubTextures can have a frame.
CAUTION: not a copy, but the actual object! Do not modify!
public function get frame():Rectangle| height | property |
height:Number [read-only] The height of the texture in points.
public function get height():Number| mipMapping | property |
mipMapping:Boolean [read-only] Indicates if the texture contains mip maps.
public function get mipMapping():Boolean| nativeHeight | property |
nativeHeight:Number [read-only] The height of the texture in pixels (without scale adjustment).
public function get nativeHeight():Number| nativeWidth | property |
nativeWidth:Number [read-only] The width of the texture in pixels (without scale adjustment).
public function get nativeWidth():Number| premultipliedAlpha | property |
premultipliedAlpha:Boolean [read-only] Indicates if the alpha values are premultiplied into the RGB values.
public function get premultipliedAlpha():Boolean| repeat | property |
repeat:Boolean [read-only] Indicates if the texture should repeat like a wallpaper or stretch the outermost pixels. Note: this only works in textures with sidelengths that are powers of two and that are not loaded from a texture atlas (i.e. no subtextures).
The default value is false.
public function get repeat():Boolean| root | property |
root:ConcreteTexture [read-only] The concrete texture the texture is based on.
public function get root():ConcreteTexture| scale | property |
scale:Number [read-only] The scale factor, which influences width and height properties.
public function get scale():Number| width | property |
width:Number [read-only] The width of the texture in points.
public function get width():Number| adjustTexCoords | () | method |
public function adjustTexCoords(texCoords:Vector.<Number>, startIndex:int = 0, stride:int = 0, count:int = -1):void Converts texture coordinates into the format required for rendering. While the texture
coordinates of an image always use the range [0, 1], the actual
coordinates could be different: you might be working with a SubTexture. This method
adjusts the coordinates accordingly.
Parameters
texCoords:Vector.<Number> — a vector containing UV coordinates (optionally, among other data).
U and V coordinates always have to come in pairs. The vector is
modified in place.
| |
startIndex:int (default = 0) | |
stride:int (default = 0) | |
count:int (default = -1) |
| adjustVertexData | () | method |
public function adjustVertexData(vertexData:VertexData, vertexID:int, count:int):void Converts texture coordinates and vertex positions of raw vertex data into the format
required for rendering. While the texture coordinates of an image always use the
range [0, 1], the actual coordinates could be different: you
might be working with a SubTexture or a texture frame. This method
adjusts the texture and vertex coordinates accordingly.
Parameters
vertexData:VertexData | |
vertexID:int | |
count:int |
| dispose | () | method |
public function dispose():voidDisposes the underlying texture data. Note that not all textures need to be disposed: SubTextures (created with 'Texture.fromTexture') just reference other textures and and do not take up resources themselves; this is also true for textures from an atlas.
| empty | () | method |
public static function empty(width:Number, height:Number, premultipliedAlpha:Boolean = true, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, repeat:Boolean = false):TextureCreates an empty texture of a certain size. Beware that the texture can only be used after you either upload some color data ("texture.root.upload...") or clear the texture ("texture.root.clear()").
Parameters
width:Number — in points; number of pixels depends on scale parameter
| |
height:Number — in points; number of pixels depends on scale parameter
| |
premultipliedAlpha:Boolean (default = true) | |
mipMapping:Boolean (default = true) | |
optimizeForRenderToTexture:Boolean (default = false) | |
scale:Number (default = -1) | |
format:String (default = bgra) | |
repeat:Boolean (default = false) |
Texture |
| fromAtfData | () | method |
public static function fromAtfData(data:ByteArray, scale:Number = 1, useMipMaps:Boolean = true, async:Function = null, repeat:Boolean = false):Texture Creates a texture from the compressed ATF format. If you don't want to use any embedded
mipmaps, you can disable them by setting "useMipMaps" to false.
Beware: you must not dispose 'data' if Starling should handle a lost device context;
alternatively, you can handle restoration yourself via "texture.root.onRestore".
If the 'async' parameter contains a callback function, the texture is decoded
asynchronously. It can only be used when the callback has been executed. This is the
expected function definition: function(texture:Texture):void;
Parameters
data:ByteArray | |
scale:Number (default = 1) | |
useMipMaps:Boolean (default = true) | |
async:Function (default = null) | |
repeat:Boolean (default = false) |
Texture |
| fromBitmap | () | method |
public static function fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, repeat:Boolean = false):TextureCreates a texture object from a bitmap. Beware: you must not dispose the bitmap's data if Starling should handle a lost device context alternatively, you can handle restoration yourself via "texture.root.onRestore".
Parameters
bitmap:Bitmap — the texture will be created with the bitmap data of this object.
| |
generateMipMaps:Boolean (default = true) | |
optimizeForRenderToTexture:Boolean (default = false) | |
scale:Number (default = 1) | |
format:String (default = bgra) | |
repeat:Boolean (default = false) |
Texture |
| fromBitmapData | () | method |
public static function fromBitmapData(data:BitmapData, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, repeat:Boolean = false):TextureCreates a texture object from bitmap data. Beware: you must not dispose 'data' if Starling should handle a lost device context; alternatively, you can handle restoration yourself via "texture.root.onRestore".
Parameters
data:BitmapData — the texture will be created with the bitmap data of this object.
| |
generateMipMaps:Boolean (default = true) | |
optimizeForRenderToTexture:Boolean (default = false) | |
scale:Number (default = 1) | |
format:String (default = bgra) | |
repeat:Boolean (default = false) |
Texture |
| fromColor | () | method |
public static function fromColor(width:Number, height:Number, color:uint = 0xffffffff, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra):TextureCreates a texture with a certain size and color.
Parameters
width:Number — in points; number of pixels depends on scale parameter
| |
height:Number — in points; number of pixels depends on scale parameter
| |
color:uint (default = 0xffffffff) | |
optimizeForRenderToTexture:Boolean (default = false) | |
scale:Number (default = -1) | |
format:String (default = bgra) |
Texture |
| fromData | () | method |
public static function fromData(data:Object, options:TextureOptions = null):TextureCreates a texture object from any of the supported data types, using the specified options.
Parameters
data:Object — Either an embedded asset class, a Bitmap, BitmapData, or a ByteArray
with ATF data.
| |
options:TextureOptions (default = null) |
Texture |
| fromEmbeddedAsset | () | method |
public static function fromEmbeddedAsset(assetClass:Class, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, repeat:Boolean = false):TextureCreates a texture object from an embedded asset class. Textures created with this method will be restored directly from the asset class in case of a context loss, which guarantees a very economic memory usage.
Parameters
assetClass:Class — must contain either a Bitmap or a ByteArray with ATF data.
| |
mipMapping:Boolean (default = true) | |
optimizeForRenderToTexture:Boolean (default = false) | |
scale:Number (default = 1) | |
format:String (default = bgra) | |
repeat:Boolean (default = false) |
Texture |
| fromTexture | () | method |
public static function fromTexture(texture:Texture, region:Rectangle = null, frame:Rectangle = null, rotated:Boolean = false):TextureCreates a texture that contains a region (in pixels) of another texture. The new texture will reference the base texture; no data is duplicated.
Parameters
texture:Texture | |
region:Rectangle (default = null) | |
frame:Rectangle (default = null) | |
rotated:Boolean (default = false) |
Texture |