Texture
Description
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 Loom, that display object is the class "Image".
Texture Formats
Loom uses stb_image to load images, which supports: JPEG, PNG, BMP, TGA, and PSD.
Mip Mapping
MipMaps 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 Frame
The 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 Coordinates
If, 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.
API overview
Constructor
Texture
()
@private
Attributes
Public attributes
| DownloadTempPostfix: String | static |
| assetPath: String |
read-only
Returns the path of the texture asset |
| asyncLoadComplete: TextureAsyncLoadCompleteDelegate |
For asynchonously loaded Textures, fired when the texture has completed loading its data |
| frame: Rectangle |
read-only
The texture frame (see class description) |
| frameReadOnly: Rectangle |
read-only
The texture frame as a read only temporary Rectangle The returned Rectangle is only valid between calls |
| height: Number |
read-only
The height of the texture in points |
| httpLoadFail: TextureHTTPFailDelegate |
For HTTP requested Textures, fired if the texture has failed to load |
| mFrame: Rectangle | |
| mipMapping: Boolean |
read-only
Indicates if the texture contains mip maps |
| nativeHeight: Number |
read-only
The height of the texture in pixels (without scale adjustment) |
| nativeID: Number | read-only |
| nativeWidth: Number |
read-only
The width of the texture in pixels (without scale adjustment) |
| premultipliedAlpha: Boolean |
read-only
Indicates if the alpha values are premultiplied into the RGB values |
| root: ConcreteTexture |
read-only
The concrete (power-of-two) texture the texture is based on |
| scale: Number |
read-only
The scale factor, which influences width and height properties |
| smoothing: Number |
Indicates if the texture do smooth filtering when it is scaled (BILINEAR) or just choose the nearest pixel (NONE) |
| update: TextureUpdateDelegate |
Fired when the texture's state has updated |
| width: Number |
read-only
The width of the texture in points |
| wrapU: Number |
Indicates if the texture should repeat like a wallpaper or stretch the outermost horizontal pixels |
| wrapV: Number |
Indicates if the texture should repeat like a wallpaper or stretch the outermost vertical pixels |
Protected attributes
Functions
Public functions
| adjustVertexData ( vertexData: VertexData , vertexID: Number , count: Number ): Void |
Converts texture coordinates and vertex positions of raw vertex data into the format required for rendering |
| cancelHTTPRequest (): Void |
Called to indicate that an HTTP texture load via fromHTTP() should be cancelled at the 1st possible opportunity |
| dispose (): Void |
Disposes the underlying texture data |
| empty ( width: Number , height: Number , premultipliedAlpha: Boolean = true , mipMapping: Boolean = true , optimizeForRenderToTexture: Boolean = false , scale: Number = , format: String = bgra , repeat: Boolean = false ): Texture |
static Creates an empty texture of a certain size |
| fromAsset ( path: String ): Texture |
static Blocking function that creates a texture object from a bitmap on disk |
| fromAssetAsync ( path: String , cb: TextureAsyncLoadCompleteDelegate , highPriority: Boolean = false ): Texture |
static Non-blocking function that creates a texture object from a bitmap file on disk |
| fromBytes ( bytes: ByteArray , uniqueName: String = null ): Texture |
static Creates a texture object from compressed image bytes |
| fromHTTP ( url: String , onSuccess: TextureAsyncLoadCompleteDelegate , onFailure: TextureHTTPFailDelegate , cacheOnDisk: Boolean = true , highPriority: Boolean = false , existingTexture: Texture = null ): Texture |
static Non-blocking function that creates a texture object from a remote bitmap file via HTTP |
| fromTexture ( texture: Texture , region: Rectangle = null , frame: Rectangle = null ): Texture |
static Creates a texture that contains a region (in pixels) of another texture |
| isTextureValid (): Boolean |
Checks the handle ID of the textureInfo to see if the texture is valid and ready for use |
| updateFromHTTP ( url: String , onSuccess: TextureAsyncLoadCompleteDelegate , onFailure: TextureHTTPFailDelegate , cacheOnDisk: Boolean = true , highPriority: Boolean = false ): Void |
Constructor
Texture ()
@private
Attributes
DownloadTempPostfix: String
static
asyncLoadComplete: TextureAsyncLoadCompleteDelegate
For asynchonously loaded Textures, fired when the texture has completed loading its data. Note that if texture.dispose() is called before the async load has completed, the texture will be destroyed and 'asyncLoadComplete' will NOT get called.
frameReadOnly: Rectangle
read-only
The texture frame as a read only temporary Rectangle The returned Rectangle is only valid between calls.
httpLoadFail: TextureHTTPFailDelegate
For HTTP requested Textures, fired if the texture has failed to load.
mFrame: Rectangle
nativeID: Number
read-only
premultipliedAlpha: Boolean
read-only
Indicates if the alpha values are premultiplied into the RGB values.
smoothing: Number
The default value is TextureSmoothing.BILINEAR
Indicates if the texture do smooth filtering when it is scaled (BILINEAR) or just choose the nearest pixel (NONE)
wrapU: Number
The default value is TextureWrap.CLAMP
Indicates if the texture should repeat like a wallpaper or stretch the outermost horizontal pixels. Note: this only works in textures with dimensions that are powers of two and that are not loaded from a texture atlas (i.e. no subtextures).
wrapV: Number
The default value is TextureWrap.CLAMP
Indicates if the texture should repeat like a wallpaper or stretch the outermost vertical pixels. Note: this only works in textures with dimensions that are powers of two and that are not loaded from a texture atlas (i.e. no subtextures).
Protected attributes
Functions
adjustVertexData ( vertexData: VertexData , vertexID: Number , count: Number ): Void
Converts texture coordinates and vertex positions of raw vertex data into the format required for rendering.
Parameters
| vertexData: VertexData | |
| vertexID: Number | |
| count: Number |
cancelHTTPRequest (): Void
Called to indicate that an HTTP texture load via fromHTTP() should be cancelled at the 1st possible opportunity. NOTE that this will also dipose the Texture returned by fromHTTP(), so consider it invalid after calling this.
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 ( width: Number , height: Number , premultipliedAlpha: Boolean = true , mipMapping: Boolean = true , optimizeForRenderToTexture: Boolean = false , scale: Number = , format: String = bgra , repeat: Boolean = false ): Texture
static
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()").
use the texture for bitmap data, use "true"; for ATF data, use "false".
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.
compressed formats to save memory (at the price of reduced image quality).
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 = true | the PMA format you will use the texture with. If you will |
| mipMapping: Boolean = true | indicates if mipmaps should be used for this texture. When you upload |
| optimizeForRenderToTexture: Boolean = false | indicates if this texture will be used as render target |
| scale: Number = | if you omit this parameter, 'Starling.contentScaleFactor' will be used. |
| format: String = bgra | the context3D texture format to use. Pass one of the packed or |
| repeat: Boolean = false | the repeat mode of the texture. Only useful for power-of-two textures. |
fromAsset ( path: String ): Texture
static
Blocking function that creates a texture object from a bitmap on disk.
Parameters
| path: String |
fromAssetAsync ( path: String , cb: TextureAsyncLoadCompleteDelegate , highPriority: Boolean = false ): Texture
static
Non-blocking function that creates a texture object from a bitmap file on disk.
Parameters
| path: String | |
| cb: TextureAsyncLoadCompleteDelegate | |
| highPriority: Boolean = false |
fromBytes ( bytes: ByteArray , uniqueName: String = null ): Texture
static
Creates a texture object from compressed image bytes. An optional unique name string can be supplied if you wish the resulting image to be cacheable, otherwise null can be specified.
The supported image types are JPEG (baseline), PNG (8-bit), TGA, BMP (non-1bpp, non-RLE), PSD (composited only), GIF, HDR (radiance rgbE), PIC (Softimage).
Parameters
| bytes: ByteArray | |
| uniqueName: String = null |
fromHTTP ( url: String , onSuccess: TextureAsyncLoadCompleteDelegate , onFailure: TextureHTTPFailDelegate , cacheOnDisk: Boolean = true , highPriority: Boolean = false , existingTexture: Texture = null ): Texture
static
Non-blocking function that creates a texture object from a remote bitmap file via HTTP.
Parameters
| url: String | |
| onSuccess: TextureAsyncLoadCompleteDelegate | |
| onFailure: TextureHTTPFailDelegate | |
| cacheOnDisk: Boolean = true | |
| highPriority: Boolean = false | |
| existingTexture: Texture = null |
fromTexture ( texture: Texture , region: Rectangle = null , frame: Rectangle = null ): Texture
static
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 | |
| region: Rectangle = null | |
| frame: Rectangle = null |
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. |
getType
(): Type
Inherited from Object
native
Gets the Type that describes the Object.
Returns
| Type | The Type that describes the object. |
getTypeName
(): String
Inherited from Object
native
Gets the type name of the Object.
Returns
| String | type name of the Object. |
isTextureValid (): Boolean
Checks the handle ID of the textureInfo to see if the texture is valid and ready for use.
toString
(): String
Inherited from Object
native
Returns a String that describes the Object. This can be overriden to provide extra details when printing objects using trace().
Returns
| String | String that described the Object. |
updateFromHTTP ( url: String , onSuccess: TextureAsyncLoadCompleteDelegate , onFailure: TextureHTTPFailDelegate , cacheOnDisk: Boolean = true , highPriority: Boolean = false ): Void
Parameters
| url: String | |
| onSuccess: TextureAsyncLoadCompleteDelegate | |
| onFailure: TextureHTTPFailDelegate | |
| cacheOnDisk: Boolean = true | |
| highPriority: Boolean = false |