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.
*
*/
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.)
*
*/
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 function definition:
* * function(texture:Texture, error:ErrorEvent):void;
* * The second parameter is optional and typically null.
*
*/
static fromBitmap(bitmap: Bitmap, generateMipMaps?: boolean, optimizeForRenderToTexture?: boolean, scale?: number, format?: Context3DTextureFormat, forcePotTexture?: boolean, async?: (arg0: 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 function definition:
* * function(texture:Texture, error:ErrorEvent):void;
* * The second parameter is optional and typically null.
*
*/
static fromBitmapData(data: BitmapData, generateMipMaps?: boolean, optimizeForRenderToTexture?: boolean, scale?: number, format?: Context3DTextureFormat, forcePotTexture?: boolean, async?: (arg0: 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 function 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.
*
*/
static fromAtfData(data: ByteArray, scale?: number, useMipMaps?: boolean, async?: (arg0: 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'.
*
*/
static fromNetStream(stream: NetStream, scale?: number, onComplete?: (arg0: Texture) => void): Texture;
/**
* Creates a texture with a certain size and color.
* *
* * @param width in points; number of pixels depends on scale parameter
* * @param height in points; number of pixels depends on scale parameter
* * @param color the RGB color the texture will be filled up
* * @param alpha the alpha value that will be used for every pixel
* * @param optimizeForRenderToTexture indicates if this texture will be used as render target
* * @param scale if you omit this parameter, 'Starling.contentScaleFactor' will be used.
* * @param format the context3D texture format to use. Pass one of the packed or
* * compressed formats to save memory.
* * @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".
*
*/
static fromColor(width: number, height: number, color?: number, alpha?: number, optimizeForRenderToTexture?: boolean, scale?: number, format?: string, forcePotTexture?: boolean): 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()").
* *
* * @param width in points; number of pixels depends on scale parameter
* * @param height in points; number of pixels depends on scale parameter
* * @param premultipliedAlpha 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".
* * @param mipMapping 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.
* * @param optimizeForRenderToTexture indicates if this texture will be used as render target
* * @param scale if you omit this parameter, 'Starling.contentScaleFactor' will be used.
* * @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".
*
*/
static empty(width: number, height: number, premultipliedAlpha?: boolean, mipMapping?: boolean, optimizeForRenderToTexture?: boolean, scale?: number, format?: string, forcePotTexture?: boolean): 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.
* *
* * @param texture The texture you want to create a SubTexture from.
* * @param region The region of the parent texture that the SubTexture will show
* * (in points).
* * @param frame If the texture was trimmed, the frame rectangle can be used to restore
* * the trimmed area.
* * @param rotated If true, the SubTexture will show the parent region rotated by
* * 90 degrees (CCW).
* * @param scaleModifier The scale factor of the new texture will be calculated by
* * multiplying the parent texture's scale factor with this value.
*
*/
static fromTexture(texture: Texture, region?: Rectangle, frame?: Rectangle, rotated?: boolean, scaleModifier?: number): Texture;
/**
* Returns the maximum size constraint (for both width and height) for uncompressed
* * textures in the current Context3D profile.
*/
static get maxSize(): number;
static getMaxSize(textureFormat?: Context3DTextureFormat): number;
/**
* Indicates if it should be attempted to upload bitmaps asynchronously when the async 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.
* */ static get asyncBitmapUploadEnabled(): boolean; static set asyncBitmapUploadEnabled(value: boolean) /** * 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. */ dispose(): 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 aframe,
* * 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.
*
*/
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.
*
*/
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.
*/
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.
*/
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.
*/
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!)
*/
getTexCoords(vertexData: VertexData, vertexID: number, attrName?: string, out?: Point): Point;
/**
* The texture frame if it has one (see class description), otherwise null.
* * CAUTION: not a copy, but the actual object! Do not modify!
*/ get frame(): Rectangle; /** * The height of the texture in points, taking into account the frame rectangle * * (if there is one). */ get frameWidth(): number; /** * The width of the texture in points, taking into account the frame rectangle * * (if there is one). */ get frameHeight(): number; /** * The width of the texture in points. */ get width(): number; /** * The height of the texture in points. */ get height(): number; /** * The width of the texture in pixels (without scale adjustment). */ get nativeWidth(): number; /** * The height of the texture in pixels (without scale adjustment). */ get nativeHeight(): number; /** * The scale factor, which influences width and height properties. */ get scale(): number; /** * The Stage3D texture object the texture is based on. */ get base(): TextureBase; /** * The concrete texture the texture is based on. */ get root(): ConcreteTexture; /** * TheContext3DTextureFormat of the underlying texture data.
*/
get format(): Context3DTextureFormat;
/**
* Indicates if the texture contains mip maps.
*/
get mipMapping(): boolean;
/**
* Indicates if the alpha values are premultiplied into the RGB values.
*/
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!
*/ 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!
*/ get transformationMatrixToRoot(): Matrix; } } export default starling.textures.Texture;