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,
the most probably candidate for this job is the Image
class.
The Texture
class is abstract, i.e. you cannot create instance of this
class through its constructor. Instead, it offers a variety of factory methods, like
fromBitmapData
or fromEmbeddedAsset
.
Since 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.
Beginning with AIR 17, you can use Starling textures to show video content (if the current platform supports it; see "SystemUtil.supportsVideoTexture"). The two factory methods "fromCamera" and "fromNetStream" allow you to make use of this feature.
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, mipmapping is disabled by default.
Texture FrameThe frame property of a texture allows you to let a texture appear inside the bounds of an image, leaving a transparent border 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.
When the current rendering context is lost (which can happen on all platforms, but is especially common on Android and Windows), all texture data is destroyed. 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. You can optimize this behavior, though, by restoring the texture directly from its source, like in this example:
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 | ||
frameHeight : Number [read-only] The width of the texture in points, taking into account the frame rectangle
(if there is one). | Texture | ||
frameWidth : Number [read-only] The height of the texture in points, taking into account the frame rectangle
(if there is one). | Texture | ||
height : Number [read-only] The height of the texture in points. | Texture | ||
maxSize : int [static] [read-only] Returns the maximum size constraint (for both width and height) for textures in the
current Context3D profile. | 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 | ||
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 | ||
transformationMatrix : Matrix [read-only] The matrix that is used to transform the texture coordinates into the coordinate
space of the parent texture, if there is one. | Texture | ||
transformationMatrixToRoot : Matrix [read-only] The matrix that is used to transform the texture coordinates into the coordinate
space of the root texture, if this instance is not the root. | Texture | ||
width : Number [read-only] The width of the texture in points. | Texture |
Method | Defined By | ||
---|---|---|---|
dispose():void Disposes the underlying texture data. | Texture | ||
empty(width:Number, height:Number, premultipliedAlpha:Boolean = true, mipMapping:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, forcePotTexture: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, premultipliedAlpha:Boolean = false):Texture [static] Creates a texture from ATF data (Adobe Texture Compression). | Texture | ||
fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture [static] Creates a texture object from a bitmap. | Texture | ||
fromBitmapData(data:BitmapData, generateMipMaps:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture [static] Creates a texture object from bitmap data. | Texture | ||
fromCamera(camera:Camera, scale:Number = 1, onComplete:Function = null):Texture [static] Creates a video texture from a camera. | Texture | ||
fromColor(width:Number, height:Number, color:uint = 0xffffff, alpha:Number = 1.0, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, forcePotTexture:Boolean = false):Texture [static] Creates a texture with a certain size and color. | Texture | ||
[static] Creates a texture from any of the supported data types, using the specified options. | Texture | ||
fromEmbeddedAsset(assetClass:Class, mipMapping:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture [static] Creates a texture object from an embedded asset class. | Texture | ||
fromNetStream(stream:NetStream, scale:Number = 1, onComplete:Function = null):Texture [static] Creates a video texture from a NetStream. | Texture | ||
fromTexture(texture:Texture, region:Rectangle = null, frame:Rectangle = null, rotated:Boolean = false, scaleModifier:Number = 1.0):Texture [static] Creates a texture that contains a region (in pixels) of another texture. | Texture | ||
fromTextureBase(base:TextureBase, width:int, height:int, options:TextureOptions = null):ConcreteTexture [static] Creates a texture from a TextureBase object. | Texture | ||
getTexCoords(vertexData:VertexData, vertexID:int, attrName:String = texCoords, out:Point = null):Point Reads a pair of texture coordinates from the given VertexData instance and transforms
them into the current texture's coordinate system. | Texture | ||
globalToLocal(u:Number, v:Number, out:Point = null):Point Transforms the given texture coordinates from the root texture's coordinate system
to the local coordinate system. | Texture | ||
localToGlobal(u:Number, v:Number, out:Point = null):Point Transforms the given texture coordinates from the local coordinate system
into the root texture's coordinate system. | Texture | ||
setTexCoords(vertexData:VertexData, vertexID:int, attrName:String, u:Number, v:Number):void Writes the given texture coordinates to a VertexData instance after transforming
them into the root texture's coordinate system. | Texture | ||
setupTextureCoordinates(vertexData:VertexData, vertexID:int = 0, attrName:String = texCoords):void Sets up a VertexData instance with the correct texture coordinates for
4 vertices so that the texture is mapped to the complete quad. | Texture | ||
setupVertexPositions(vertexData:VertexData, vertexID:int = 0, attrName:String = position, bounds:Rectangle = null):void Sets up a VertexData instance with the correct positions for 4 vertices so that
the texture can be mapped onto it unscaled. | 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
.
CAUTION: not a copy, but the actual object! Do not modify!
public function get frame():Rectangle
frameHeight | property |
frameHeight:Number
[read-only] The width of the texture in points, taking into account the frame rectangle (if there is one).
public function get frameHeight():Number
frameWidth | property |
frameWidth:Number
[read-only] The height of the texture in points, taking into account the frame rectangle (if there is one).
public function get frameWidth():Number
height | property |
height:Number
[read-only] The height of the texture in points.
public function get height():Number
maxSize | property |
maxSize:int
[read-only] Returns the maximum size constraint (for both width and height) for textures in the current Context3D profile.
public static function get maxSize():int
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
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
transformationMatrix | property |
transformationMatrix:Matrix
[read-only] The matrix that is used to transform the texture coordinates into the coordinate space of the parent texture, if there is one.
The default value is CAUTION: not a copy, but the actual object! Never modify this matrix!null
.
public function get transformationMatrix():Matrix
transformationMatrixToRoot | property |
transformationMatrixToRoot:Matrix
[read-only] The matrix that is used to transform the texture coordinates into the coordinate space of the root texture, if this instance is not the root.
The default value is CAUTION: not a copy, but the actual object! Never modify this matrix!null
.
public function get transformationMatrixToRoot():Matrix
width | property |
width:Number
[read-only] The width of the texture in points.
public function get width():Number
dispose | () | method |
public function dispose():void
Disposes 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 = false, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, forcePotTexture:Boolean = false):Texture
Creates 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 ) — the PMA format you will use the texture with. If you will
use the texture for bitmap data, use "true"; for ATF data, use "false".
| |
mipMapping:Boolean (default = false ) — indicates if mipmaps should be used for this texture. When you upload
bitmap data, this decides if mipmaps will be created; when you upload ATF
data, this decides if mipmaps inside the ATF file will be displayed.
| |
optimizeForRenderToTexture:Boolean (default = false ) — indicates if this texture will be used as render target
| |
scale:Number (default = -1 ) — if you omit this parameter, 'Starling.contentScaleFactor' will be used.
| |
format:String (default = bgra ) — the context3D texture format to use. Pass one of the packed or
compressed formats to save memory (at the price of reduced image quality).
| |
forcePotTexture:Boolean (default = false ) — indicates if the underlying Stage3D texture should be created
as the power-of-two based "Texture" class instead of the more memory
efficient "RectangleTexture".
|
Texture |
fromAtfData | () | method |
public static function fromAtfData(data:ByteArray, scale:Number = 1, useMipMaps:Boolean = true, async:Function = null, premultipliedAlpha:Boolean = false):Texture
Creates a texture from ATF data (Adobe Texture Compression). 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:ByteArray — the raw data from an ATF file.
| |
scale:Number (default = 1 ) — the scale factor of the created texture. This affects the reported
width and height of the texture object.
| |
useMipMaps:Boolean (default = true ) — If the ATF data contains mipmaps, this parameter controls if they
are used; if it does not, this parameter has no effect.
| |
async:Function (default = null ) — If you pass a callback function, the texture will be decoded
asynchronously, which allows a smooth framerate even during the
loading process. However, don't use the texture before the callback
has been executed. This is the expected function definition:
function(texture:Texture):void;
| |
premultipliedAlpha:Boolean (default = false ) — Indicates if the ATF data contains pixels in PMA format.
This is "false" for most ATF files, but can be customized in some
tools.
|
Texture |
fromBitmap | () | method |
public static function fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture
Creates 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 = false ) — indicates if mipMaps will be created.
| |
optimizeForRenderToTexture:Boolean (default = false ) — indicates if this texture will be used as
render target
| |
scale:Number (default = 1 ) — the scale factor of the created texture. This affects the reported
width and height of the texture object.
| |
format:String (default = bgra ) — the context3D texture format to use. Pass one of the packed or
compressed formats to save memory (at the price of reduced image
quality).
| |
forcePotTexture:Boolean (default = false ) — indicates if the underlying Stage3D texture should be created
as the power-of-two based "Texture" class instead of the more memory
efficient "RectangleTexture".
|
Texture |
fromBitmapData | () | method |
public static function fromBitmapData(data:BitmapData, generateMipMaps:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture
Creates 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 bitmap data to upload to the texture.
| |
generateMipMaps:Boolean (default = false ) — indicates if mipMaps will be created.
| |
optimizeForRenderToTexture:Boolean (default = false ) — indicates if this texture will be used as
render target
| |
scale:Number (default = 1 ) — the scale factor of the created texture. This affects the reported
width and height of the texture object.
| |
format:String (default = bgra ) — the context3D texture format to use. Pass one of the packed or
compressed formats to save memory (at the price of reduced image
quality).
| |
forcePotTexture:Boolean (default = false ) — indicates if the underlying Stage3D texture should be created
as the power-of-two based "Texture" class instead of the more memory
efficient "RectangleTexture".
|
Texture |
fromCamera | () | method |
public static function fromCamera(camera:Camera, scale:Number = 1, onComplete:Function = null):Texture
Creates a video texture from a camera. Beware that the texture must not be used before the 'onComplete' callback has been executed; until then, it will have a size of zero pixels.
Here is a minimal sample showing how to display a camera video:
var camera:Camera = Camera.getCamera(); var texture:Texture = Texture.fromCamera(camera, 1, function():void { addChild(new Image(texture)); });
Parameters
camera:Camera — the camera from which the video data is streamed.
| |
scale:Number (default = 1 ) — the scale factor of the created texture. This affects the reported
width and height of the texture object.
| |
onComplete:Function (default = null ) — will be executed when the texture is ready. May contain a parameter
of type 'Texture'.
|
Texture |
fromColor | () | method |
public static function fromColor(width:Number, height:Number, color:uint = 0xffffff, alpha:Number = 1.0, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, forcePotTexture:Boolean = false):Texture
Creates 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 = 0xffffff ) — the RGB color the texture will be filled up
| |
alpha:Number (default = 1.0 ) — the alpha value that will be used for every pixel
| |
optimizeForRenderToTexture:Boolean (default = false ) — indicates if this texture will be used as render target
| |
scale:Number (default = -1 ) — if you omit this parameter, 'Starling.contentScaleFactor' will be used.
| |
format:String (default = bgra ) — the context3D texture format to use. Pass one of the packed or
compressed formats to save memory.
| |
forcePotTexture:Boolean (default = false ) — indicates if the underlying Stage3D texture should be created
as the power-of-two based "Texture" class instead of the more memory
efficient "RectangleTexture".
|
Texture |
fromData | () | method |
public static function fromData(data:Object, options:TextureOptions = null):Texture
Creates a texture 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 ) — Specifies options about the texture settings, e.g. the scale factor.
If left empty, the default options will be used.
|
Texture |
fromEmbeddedAsset | () | method |
public static function fromEmbeddedAsset(assetClass:Class, mipMapping:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture
Creates 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 = false ) — for Bitmaps, indicates if mipMaps will be created;
for ATF data, indicates if the contained mipMaps will be used.
| |
optimizeForRenderToTexture:Boolean (default = false ) — indicates if this texture will be used as
render target.
| |
scale:Number (default = 1 ) — the scale factor of the created texture.
| |
format:String (default = bgra ) — the context3D texture format to use. Ignored for ATF data.
| |
forcePotTexture:Boolean (default = false ) — indicates if the underlying Stage3D texture should be created
as the power-of-two based "Texture" class instead of the more memory
efficient "RectangleTexture". (Only applicable to bitmaps; ATF
textures are always POT-textures, anyway.)
|
Texture |
fromNetStream | () | method |
public static function fromNetStream(stream:NetStream, scale:Number = 1, onComplete:Function = null):Texture
Creates a video texture from a NetStream.
Below, you'll find a minimal sample showing how to stream a video from a file.
Note that ns.play()
is called only after creating the texture, and
outside the onComplete
-callback. It's recommended to always make the
calls in this order; otherwise, playback won't start on some platforms.
var nc:NetConnection = new NetConnection(); nc.connect(null); var ns:NetStream = new NetStream(nc); var texture:Texture = Texture.fromNetStream(ns, 1, function():void { addChild(new Image(texture)); }); var file:File = File.applicationDirectory.resolvePath("bugs-bunny.m4v"); ns.play(file.url);
Parameters
stream:NetStream — the NetStream from which the video data is streamed. Beware that 'play'
should be called only after the method returns, and outside the
onComplete callback.
| |
scale:Number (default = 1 ) — the scale factor of the created texture. This affects the reported
width and height of the texture object.
| |
onComplete:Function (default = null ) — will be executed when the texture is ready. Contains a parameter
of type 'Texture'.
|
Texture |
fromTexture | () | method |
public static function fromTexture(texture:Texture, region:Rectangle = null, frame:Rectangle = null, rotated:Boolean = false, scaleModifier:Number = 1.0):Texture
Creates 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 — The texture you want to create a SubTexture from.
| |
region:Rectangle (default = null ) — The region of the parent texture that the SubTexture will show
(in points).
| |
frame:Rectangle (default = null ) — If the texture was trimmed, the frame rectangle can be used to restore
the trimmed area.
| |
rotated:Boolean (default = false ) — If true, the SubTexture will show the parent region rotated by
90 degrees (CCW).
| |
scaleModifier:Number (default = 1.0 ) — The scale factor of the new texture will be calculated by
multiplying the parent texture's scale factor with this value.
|
Texture |
fromTextureBase | () | method |
public static function fromTextureBase(base:TextureBase, width:int, height:int, options:TextureOptions = null):ConcreteTexture
Creates a texture from a TextureBase
object.
Parameters
base:TextureBase — a Stage3D texture object created through the current context.
| |
width:int — the width of the texture in pixels (not points!).
| |
height:int — the height of the texture in pixels (not points!).
| |
options:TextureOptions (default = null ) — specifies options about the texture settings, e.g. the scale factor.
If left empty, the default options will be used. Note that not all
options are supported by all texture types.
|
ConcreteTexture |
getTexCoords | () | method |
public function getTexCoords(vertexData:VertexData, vertexID:int, attrName:String = texCoords, out:Point = null):Point
Reads a pair of texture coordinates from the given VertexData instance and transforms them into the current texture's coordinate system. (Remember, the VertexData instance will always contain the coordinates in the root texture's coordinate system!)
Parameters
vertexData:VertexData | |
vertexID:int | |
attrName:String (default = texCoords )
| |
out:Point (default = null )
|
Point |
globalToLocal | () | method |
public function globalToLocal(u:Number, v:Number, out:Point = null):Point
Transforms the given texture coordinates from the root texture's coordinate system to the local coordinate system.
Parameters
u:Number | |
v:Number | |
out:Point (default = null )
|
Point |
localToGlobal | () | method |
public function localToGlobal(u:Number, v:Number, out:Point = null):Point
Transforms the given texture coordinates from the local coordinate system into the root texture's coordinate system.
Parameters
u:Number | |
v:Number | |
out:Point (default = null )
|
Point |
setTexCoords | () | method |
public function setTexCoords(vertexData:VertexData, vertexID:int, attrName:String, u:Number, v:Number):void
Writes the given texture coordinates to a VertexData instance after transforming them into the root texture's coordinate system. That way, the texture coordinates can be used directly to sample the texture in the fragment shader.
Parameters
vertexData:VertexData | |
vertexID:int | |
attrName:String | |
u:Number | |
v:Number |
setupTextureCoordinates | () | method |
public function setupTextureCoordinates(vertexData:VertexData, vertexID:int = 0, attrName:String = texCoords):void
Sets up a VertexData instance with the correct texture coordinates for 4 vertices so that the texture is mapped to the complete quad.
Parameters
vertexData:VertexData — the vertex data to which the texture coordinates will be written.
| |
vertexID:int (default = 0 ) — the start position within the VertexData instance.
| |
attrName:String (default = texCoords ) — the attribute name referencing the vertex positions.
|
setupVertexPositions | () | method |
public function setupVertexPositions(vertexData:VertexData, vertexID:int = 0, attrName:String = position, bounds:Rectangle = null):void
Sets up a VertexData instance with the correct positions for 4 vertices so that
the texture can be mapped onto it unscaled. If the texture has a frame
,
the vertices will be offset accordingly.
Parameters
vertexData:VertexData — the VertexData instance to which the positions will be written.
| |
vertexID:int (default = 0 ) — the start position within the VertexData instance.
| |
attrName:String (default = position ) — the attribute name referencing the vertex positions.
| |
bounds:Rectangle (default = null ) — useful only for textures with a frame. This will position the
vertices at the correct position within the given bounds,
distorted appropriately.
|