starling-framework

import TextureOptions from "./TextureOptions"; import ConcreteTexture from "./ConcreteTexture"; import VertexData from "../rendering/VertexData"; import ByteArray from "openfl/utils/ByteArray"; import NetStream from "openfl/net/NetStream"; import Rectangle from "openfl/geom/Rectangle"; import Point from "openfl/geom/Point"; import Matrix from "openfl/geom/Matrix"; import TextureBase from "openfl/display3D/textures/TextureBase"; import Context3DTextureFormat from "openfl/display3D/Context3DTextureFormat"; import BitmapData from "openfl/display/BitmapData"; import Bitmap from "openfl/display/Bitmap"; declare namespace starling.textures { /** * 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 <code>Image</code> class. * * * * Creating a texture * * * * The <code>Texture</code> class is abstract, i.e. you cannot create instance of this * * class through its constructor. Instead, it offers a variety of factory methods, like * * <code>fromBitmapData</code> or <code>fromEmbeddedAsset</code>. * * * * Texture Formats * * * * 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): * * * * <listing> * * var frame:Rectangle = new Rectangle(-10, -10, 30, 30); * * var texture:Texture = Texture.fromTexture(anotherTexture, null, frame); * * var image:Image = new Image(texture);</listing> * * * * This code would create an image with a size of 30x30, with the texture placed at * * <code>x=10, y=10</code> 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 <a href="http://www.texturepacker.com/">TexturePacker</a> 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 <code>image.setTexCoords</code> * * allows you to do that. * * * * Context Loss * * * * 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: * * * * <listing> * * var texture:Texture = Texture.fromBitmap(new EmbeddedBitmap()); * * texture.root.onRestore = function():void * * { * * texture.root.uploadFromBitmap(new EmbeddedBitmap()); * * };</listing> * * * * The <code>onRestore</code>-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 starling.display.Image * * @see starling.utils.AssetManager * * @see starling.utils.SystemUtil * * @see TextureAtlas * */ export class Texture { /** * @private */ protected constructor(); /** * Creates a texture from any of the supported data types, using the specified options. * * * * @param data Either an embedded asset class, a Bitmap, BitmapData, or a ByteArray * * with ATF data. * * @param options Specifies options about the texture settings, e.g. the scale factor. * * If left empty, the default options will be used. * */ static fromData(data: any, options?: TextureOptions): Texture; /** * Creates a texture from a <code>TextureBase</code> 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: * * <code>function(texture:Texture, error:ErrorEvent):void;</code> * * The second parameter is optional and typically <code>null</code>. * */ 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: * * <code>function(texture:Texture, error:ErrorEvent):void;</code> * * The second parameter is optional and typically <code>null</code>. * */ 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: * * <code>function(texture:Texture):void;</code> * * @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 <code>ns.play()</code> is called only after creating the texture, and * * outside the <code>onComplete</code>-callback. It's recommended to always make the * * calls in this order; otherwise, playback won't start on some platforms. * * * * <listing> * * 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);</listing> * * * * @param stream the NetStream from which the video data is streamed. Beware that 'play' * * should be called only after the method returns, and outside the * * <code>onComplete</code> 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 <code>async</code> 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 a <code>frame</code>, * * 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 <code>null</code>. * * 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; /** * The <code>Context3DTextureFormat</code> 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;