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 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, mipmapping is disabled by default.
* * Texture Frame * *The 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):
* *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.
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:
* *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.
TextureBase object.
*
* @param base a Stage3D texture object created through the current context.
* @param width the width of the texture in pixels (not points!).
* @param height the height of the texture in pixels (not points!).
* @param options 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.
*/
public static fromTextureBase(base:TextureBase, width:number, height:number,
options?:TextureOptions):ConcreteTexture;
/** 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.
*
* @param assetClass must contain either a Bitmap or a ByteArray with ATF data.
* @param mipMapping for Bitmaps, indicates if mipMaps will be created;
* for ATF data, indicates if the contained mipMaps will be used.
* @param optimizeForRenderToTexture indicates if this texture will be used as
* render target.
* @param scale the scale factor of the created texture.
* @param format the context3D texture format to use. Ignored for ATF data.
* @param forcePotTexture 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.)
*/
public static fromEmbeddedAsset(assetClass:any, mipMapping?:boolean,
optimizeForRenderToTexture?:boolean,
scale?:number, format?:Context3DTextureFormat,
forcePotTexture?:boolean):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 (except if you handle restoration yourself via "texture.root.onRestore").
*
* @param bitmap the texture will be created with the bitmap data of this object.
* @param generateMipMaps indicates if mipMaps will be created.
* @param optimizeForRenderToTexture indicates if this texture will be used as
* render target
* @param scale the scale factor of the created texture. This affects the reported
* width and height of the texture object.
* @param format the context3D texture format to use. Pass one of the packed or
* compressed formats to save memory (at the price of reduced image
* quality).
* @param forcePotTexture indicates if the underlying Stage3D texture should be created
* as the power-of-two based "Texture" class instead of the more memory
* efficient "RectangleTexture".
* @param async If you pass a callback function, the texture will be uploaded
* asynchronously, which allows smooth rendering even during the
* loading process. However, don't use the texture before the callback
* has been executed. This is the expected definition:
* function(texture:Texture, error:ErrorEvent):void;
* The second parameter is optional and typically null.
*/
public static fromBitmap(bitmap:Bitmap, generateMipMaps?:boolean,
optimizeForRenderToTexture?:boolean,
scale?:number, format?:Context3DTextureFormat,
forcePotTexture?:boolean,
async?:(Texture)=>void):Texture;
/** Creates a texture object from bitmap data.
* Beware: you must not dispose 'data' if Starling should handle a lost device context
* (except if you handle restoration yourself via "texture.root.onRestore").
*
* @param data the bitmap data to upload to the texture.
* @param generateMipMaps indicates if mipMaps will be created.
* @param optimizeForRenderToTexture indicates if this texture will be used as
* render target
* @param scale the scale factor of the created texture. This affects the reported
* width and height of the texture object.
* @param format the context3D texture format to use. Pass one of the packed or
* compressed formats to save memory (at the price of reduced image
* quality).
* @param forcePotTexture indicates if the underlying Stage3D texture should be created
* as the power-of-two based "Texture" class instead of the more memory
* efficient "RectangleTexture".
* @param async If you pass a callback function, the texture will be uploaded
* asynchronously, which allows smooth rendering even during the
* loading process. However, don't use the texture before the callback
* has been executed. This is the expected definition:
* function(texture:Texture, error:ErrorEvent):void;
* The second parameter is optional and typically null.
*/
public static fromBitmapData(data:BitmapData, generateMipMaps?:boolean,
optimizeForRenderToTexture?:boolean,
scale?:number, format?:Context3DTextureFormat,
forcePotTexture?:boolean,
async?:(Texture)=>void):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".
*
* @param data the raw data from an ATF file.
* @param scale the scale factor of the created texture. This affects the reported
* width and height of the texture object.
* @param useMipMaps If the ATF data contains mipmaps, this parameter controls if they
* are used; if it does not, this parameter has no effect.
* @param async 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 definition:
* function(texture:Texture):void;
* @param premultipliedAlpha Indicates if the ATF data contains pixels in PMA format.
* This is "false" for most ATF files, but can be customized in some
* tools.
*/
public static fromAtfData(data:ByteArray, scale?:number, useMipMaps?:boolean,
async?:(Texture)=>void, premultipliedAlpha?:boolean):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.
onComplete callback.
* @param scale the scale factor of the created texture. This affects the reported
* width and height of the texture object.
* @param onComplete will be executed when the texture is ready. Contains a parameter
* of type 'Texture'.
*/
public static fromNetStream(stream:NetStream, scale?:number,
onComplete?:(Texture)=>void):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:
* *frame,
* the vertices will be offset accordingly.
*
* @param vertexData the VertexData instance to which the positions will be written.
* @param vertexID the start position within the VertexData instance.
* @param attrName the attribute name referencing the vertex positions.
* @param bounds useful only for textures with a frame. This will position the
* vertices at the correct position within the given bounds,
* distorted appropriately.
*/
public setupVertexPositions(vertexData:VertexData, vertexID?:number,
attrName?:string,
bounds?:Rectangle):void;
/** Sets up a VertexData instance with the correct texture coordinates for
* 4 vertices so that the texture is mapped to the complete quad.
*
* @param vertexData the vertex data to which the texture coordinates will be written.
* @param vertexID the start position within the VertexData instance.
* @param attrName the attribute name referencing the vertex positions.
*/
public setupTextureCoordinates(vertexData:VertexData, vertexID?:number,
attrName?:string):void;
/** Transforms the given texture coordinates from the local coordinate system
* into the root texture's coordinate system. */
public localToGlobal(u:number, v:number, out?:Point):Point;
/** Transforms the given texture coordinates from the root texture's coordinate system
* to the local coordinate system. */
public globalToLocal(u:number, v:number, out?:Point):Point;
/** 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. */
public setTexCoords(vertexData:VertexData, vertexID:number, attrName:string,
u:number, v:number):void;
/** 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!) */
public getTexCoords(vertexData:VertexData, vertexID:number,
attrName?:string, out?:Point):Point;
// properties
/** The texture frame if it has one (see class description), otherwise null.
* CAUTION: not a copy, but the actual object! Do not modify!
*/ public readonly frame:Rectangle; protected get_frame():Rectangle; /** The height of the texture in points, taking into account the frame rectangle * (if there is one). */ public readonly frameWidth:number; protected get_frameWidth():number; /** The width of the texture in points, taking into account the frame rectangle * (if there is one). */ public readonly frameHeight:number; protected get_frameHeight():number; /** The width of the texture in points. */ public readonly width:number; protected get_width():number; /** The height of the texture in points. */ public readonly height:number; protected get_height():number; /** The width of the texture in pixels (without scale adjustment). */ public readonly nativeWidth:number; protected get_nativeWidth():number; /** The height of the texture in pixels (without scale adjustment). */ public readonly nativeHeight:number; protected get_nativeHeight():number; /** The scale factor, which influences width and height properties. */ public readonly scale:number; protected get_scale():number; /** The Stage3D texture object the texture is based on. */ public readonly base:TextureBase; protected get_base():TextureBase; /** The concrete texture the texture is based on. */ public readonly root:ConcreteTexture; protected get_root():ConcreteTexture; /** TheContext3DTextureFormat of the underlying texture data. */
public readonly format:Context3DTextureFormat;
protected get_format():Context3DTextureFormat;
/** Indicates if the texture contains mip maps. */
public readonly mipMapping:boolean;
protected get_mipMapping():boolean;
/** Indicates if the alpha values are premultiplied into the RGB values. */
public readonly premultipliedAlpha:boolean;
protected get_premultipliedAlpha():boolean;
/** The matrix that is used to transform the texture coordinates into the coordinate
* space of the parent texture, if there is one. @default null
*
* CAUTION: not a copy, but the actual object! Never modify this matrix!
*/ public readonly transformationMatrix:Matrix; protected get_transformationMatrix():Matrix; /** 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. @default null * *CAUTION: not a copy, but the actual object! Never modify this matrix!
*/ public readonly transformationMatrixToRoot:Matrix; protected get_transformationMatrixToRoot():Matrix; /** Returns the maximum size constraint (for both width and height) for uncompressed * textures in the current Context3D profile. */ public static readonly maxSize:number; protected static get_maxSize():number; public static getMaxSize(textureFormat?:Context3DTextureFormat):number; /** Indicates if it should be attempted to upload bitmaps asynchronously when theasync parameter
* is supplied to supported methods. Since this feature is still not 100% reliable in AIR 26 (especially on
* Android), it defaults to 'false' for now.
*
* If the feature is disabled or not available in the current AIR/Flash runtime, the async callback will * still be executed; however, the upload itself will be made synchronously.
*/ public static asyncBitmapUploadEnabled:boolean; protected static get_asyncBitmapUploadEnabled():boolean; protected static set_asyncBitmapUploadEnabled(value:boolean):boolean; } } export default starling.textures.Texture;