Options
All
  • Public
  • Public/Protected
  • All
Menu

Class RenderTexture

A RenderTexture is a any texture onto which you can draw any display object.

After creating a render texture, just call the draw method to render an object directly onto the texture. The object will be drawn onto the texture at its current position, adhering its current rotation, scale and alpha properties.

Drawing is done very efficiently, as it is happening directly in graphics memory. After you have drawn objects onto the texture, the performance will be just like that of a normal texture — no matter how many objects you have drawn.

If you draw lots of objects at once, it is recommended to bundle the drawing calls in a block via the drawBundled method, like shown below. That will speed it up immensely, allowing you to draw hundreds of objects very quickly.

<pre>

renderTexture.drawBundled(function():void { for (i?:number; i<numDrawings; ++i) { image.rotation = (2 * Math.PI / numDrawings) * i; renderTexture.draw(image); } });

To erase parts of a render texture, you can use any display object like a "rubber" by setting its blending mode to BlendMode.ERASE. To wipe it completely clean, use the clear method.

Persistence

Older devices may require double buffering to support persistent render textures. Thus, you should disable the persistent parameter in the constructor if you only need to make one draw operation on the texture. The static useDoubleBuffering property allows you to customize if new textures will be created with or without double buffering.

Context Loss

Unfortunately, render textures are wiped clean when the render context is lost. This means that you need to manually recreate all their contents in such a case. One way to do that is by using the root.onRestore callback, like here:

renderTexture.root.onRestore = function():void { quad:Quad = new Quad(100, 100, 0xff00ff); renderTexture.clear(); // required on texture restoration renderTexture.draw(quad); });

For example, a drawing app would need to store information about all draw operations when they occur, and then recreate them inside onRestore on a context loss (preferably using drawBundled instead).

However, there is one problem: when that callback is executed, it's very likely that not all of your textures are already available, since they need to be restored, too (and that might take a while). You probably loaded your textures with the "AssetManager". In that case, you can listen to its TEXTURES_RESTORED event instead:

assetManager.addEventListener(Event.TEXTURES_RESTORED, function():void { brush:Image = new Image(assetManager.getTexture("brush")); renderTexture.draw(brush); });

[Note that this time, there is no need to call clear, because that's the default behavior of onRestore, anyway — and we didn't modify that.]

Hierarchy

Index

Constructors

constructor

  • new RenderTexture(width: number, height: number, persistent?: boolean, scale?: number, format?: string): RenderTexture
  • Creates a new RenderTexture with a certain size (in points). If the texture is persistent, its contents remains intact after each draw call, allowing you to use the texture just like a canvas. If it is not, it will be cleared before each draw call.

    Non-persistent textures can be used more efficiently on older devices; on modern hardware, it does not make a difference. For more information, have a look at the documentation of the useDoubleBuffering property.

    Parameters

    • width: number
    • height: number
    • Optional persistent: boolean
    • Optional scale: number
    • Optional format: string

    Returns RenderTexture

Properties

base

base: TextureBase

The Stage3D texture object the texture is based on.

format

format: Context3DTextureFormat

The Context3DTextureFormat of the underlying texture data.

frame

frame: Rectangle

The texture frame if it has one (see class description), otherwise null.

CAUTION: not a copy, but the actual object! Do not modify!

frameHeight

frameHeight: number

The width of the texture in points, taking into account the frame rectangle (if there is one).

frameWidth

frameWidth: number

The height of the texture in points, taking into account the frame rectangle (if there is one).

height

height: number

The height of the texture in points.

isPersistent

isPersistent: boolean

Indicates if the texture is persistent over multiple draw calls.

mipMapping

mipMapping: boolean

Indicates if the texture contains mip maps.

nativeHeight

nativeHeight: number

The height of the texture in pixels (without scale adjustment).

nativeWidth

nativeWidth: number

The width of the texture in pixels (without scale adjustment).

ownsParent

ownsParent: boolean

Indicates if the parent texture is disposed when this object is disposed.

parent

parent: Texture

The texture which the SubTexture is based on.

premultipliedAlpha

premultipliedAlpha: boolean

Indicates if the alpha values are premultiplied into the RGB values.

region

region: Rectangle

The region of the parent texture that the SubTexture is showing (in points).

CAUTION: not a copy, but the actual object! Do not modify!

root

The concrete texture the texture is based on.

rotated

rotated: boolean

If true, the SubTexture will show the parent region rotated by 90 degrees (CCW).

scale

scale: number

The scale factor, which influences width and height properties.

transformationMatrix

transformationMatrix: Matrix

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!

transformationMatrixToRoot

transformationMatrixToRoot: 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!

width

width: number

The width of the texture in points.

Static asyncBitmapUploadEnabled

asyncBitmapUploadEnabled: boolean

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 maxSize

maxSize: number

Returns the maximum size constraint (for both width and height) for uncompressed textures in the current Context3D profile.

Static useDoubleBuffering

useDoubleBuffering: boolean

Indicates if new persistent textures should use double buffering. Single buffering is faster and requires less memory, but is not supported on all hardware.

By default, applications running with the profile "baseline" or "baselineConstrained" will use double buffering; all others use just a single buffer. You can override this behavior, though, by assigning a different value at runtime.

@default true for "baseline" and "baselineConstrained", false otherwise

Methods

clear

  • clear(color?: number, alpha?: number): void
  • Clears the render texture with a certain color and alpha value. Call without any arguments to restore full transparency.

    Parameters

    • Optional color: number
    • Optional alpha: number

    Returns void

dispose

  • dispose(): void

draw

  • draw(object: DisplayObject, matrix?: Matrix, alpha?: number, antiAliasing?: number, cameraPos?: Vector3D): void
  • Draws an object into the texture.

    @param object The object to draw. @param matrix If 'matrix' is null, the object will be drawn adhering its properties for position, scale, and rotation. If it is not null, the object will be drawn in the orientation depicted by the matrix. @param alpha The object's alpha value will be multiplied with this value. @param antiAliasing Values range from 0 (no antialiasing) to 4 (best quality). Beginning with AIR 22, this feature is supported on all platforms (except for software rendering mode). @param cameraPos When drawing a 3D object, you can optionally pass in a custom camera position. If left empty, the camera will be placed with its default settings (centered over the texture, fov = 1.0).

    Parameters

    • object: DisplayObject
    • Optional matrix: Matrix
    • Optional alpha: number
    • Optional antiAliasing: number
    • Optional cameraPos: Vector3D

    Returns void

drawBundled

  • drawBundled(drawingBlock: function, antiAliasing?: number, cameraPos?: Vector3D): void
  • Bundles several calls to draw together in a block. This avoids buffer switches and allows you to draw multiple objects into a non-persistent texture. Note that the 'antiAliasing' setting provided here overrides those provided in individual 'draw' calls.

    @param drawingBlock a callback with the form:

    function():void;
    @param antiAliasing Values range from 0 (no antialiasing) to 4 (best quality). Beginning with AIR 22, this feature is supported on all platforms (except for software rendering mode). @param cameraPos When drawing a 3D object, you can optionally pass in a custom camera position. If left empty, the camera will be placed with its default settings (centered over the texture, fov = 1.0).

    Parameters

    • drawingBlock: function
        • (): void
        • Returns void

    • Optional antiAliasing: number
    • Optional cameraPos: Vector3D

    Returns void

getTexCoords

  • getTexCoords(vertexData: VertexData, vertexID: number, attrName?: string, out?: Point): 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: number
    • Optional attrName: string
    • Optional out: Point

    Returns Point

Protected get_base

  • get_base(): TextureBase

Protected get_format

  • get_format(): Context3DTextureFormat

Protected get_frame

  • get_frame(): Rectangle

Protected get_frameHeight

  • get_frameHeight(): number

Protected get_frameWidth

  • get_frameWidth(): number

Protected get_height

  • get_height(): number

Protected get_isPersistent

  • get_isPersistent(): boolean

Protected get_mipMapping

  • get_mipMapping(): boolean

Protected get_nativeHeight

  • get_nativeHeight(): number

Protected get_nativeWidth

  • get_nativeWidth(): number

Protected get_ownsParent

  • get_ownsParent(): boolean

Protected get_parent

Protected get_premultipliedAlpha

  • get_premultipliedAlpha(): boolean

Protected get_region

  • get_region(): Rectangle

Protected get_root

Protected get_rotated

  • get_rotated(): boolean

Protected get_scale

  • get_scale(): number

Protected get_transformationMatrix

  • get_transformationMatrix(): Matrix

Protected get_transformationMatrixToRoot

  • get_transformationMatrixToRoot(): Matrix

Protected get_width

  • get_width(): number

globalToLocal

  • globalToLocal(u: number, v: number, out?: Point): Point

localToGlobal

  • localToGlobal(u: number, v: number, out?: Point): Point

setTexCoords

  • setTexCoords(vertexData: VertexData, vertexID: number, 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: number
    • attrName: string
    • u: number
    • v: number

    Returns void

setupTextureCoordinates

  • setupTextureCoordinates(vertexData: VertexData, vertexID?: number, attrName?: string): 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.

    Parameters

    • vertexData: VertexData
    • Optional vertexID: number
    • Optional attrName: string

    Returns void

setupVertexPositions

  • setupVertexPositions(vertexData: VertexData, vertexID?: number, attrName?: string, bounds?: Rectangle): 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.

    @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.

    Parameters

    • vertexData: VertexData
    • Optional vertexID: number
    • Optional attrName: string
    • Optional bounds: Rectangle

    Returns void

Static empty

  • empty(width: number, height: number, premultipliedAlpha?: boolean, mipMapping?: boolean, 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".

    Parameters

    • width: number
    • height: number
    • Optional premultipliedAlpha: boolean
    • Optional mipMapping: boolean
    • Optional optimizeForRenderToTexture: boolean
    • Optional scale: number
    • Optional format: string
    • Optional forcePotTexture: boolean

    Returns Texture

Static fromAtfData

  • fromAtfData(data: ByteArray, scale?: number, useMipMaps?: boolean, async?: function, premultipliedAlpha?: boolean): 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.

    Parameters

    • data: ByteArray
    • Optional scale: number
    • Optional useMipMaps: boolean
    • Optional async: function
        • (Texture: any): void
        • Parameters

          • Texture: any

          Returns void

    • Optional premultipliedAlpha: boolean

    Returns Texture

Static fromBitmap

  • fromBitmap(bitmap: Bitmap, generateMipMaps?: boolean, optimizeForRenderToTexture?: boolean, scale?: number, format?: Context3DTextureFormat, forcePotTexture?: boolean, async?: function): 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.

    Parameters

    • bitmap: Bitmap
    • Optional generateMipMaps: boolean
    • Optional optimizeForRenderToTexture: boolean
    • Optional scale: number
    • Optional format: Context3DTextureFormat
    • Optional forcePotTexture: boolean
    • Optional async: function
        • (Texture: any): void
        • Parameters

          • Texture: any

          Returns void

    Returns Texture

Static fromBitmapData

  • fromBitmapData(data: BitmapData, generateMipMaps?: boolean, optimizeForRenderToTexture?: boolean, scale?: number, format?: Context3DTextureFormat, forcePotTexture?: boolean, async?: function): 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.

    Parameters

    • data: BitmapData
    • Optional generateMipMaps: boolean
    • Optional optimizeForRenderToTexture: boolean
    • Optional scale: number
    • Optional format: Context3DTextureFormat
    • Optional forcePotTexture: boolean
    • Optional async: function
        • (Texture: any): void
        • Parameters

          • Texture: any

          Returns void

    Returns Texture

Static fromColor

  • fromColor(width: number, height: number, color?: number, alpha?: number, optimizeForRenderToTexture?: boolean, scale?: number, format?: string, forcePotTexture?: boolean): 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".

    Parameters

    • width: number
    • height: number
    • Optional color: number
    • Optional alpha: number
    • Optional optimizeForRenderToTexture: boolean
    • Optional scale: number
    • Optional format: string
    • Optional forcePotTexture: boolean

    Returns Texture

Static fromData

  • 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.

    Parameters

    Returns Texture

Static fromEmbeddedAsset

  • fromEmbeddedAsset(assetClass: any, mipMapping?: boolean, optimizeForRenderToTexture?: boolean, scale?: number, format?: Context3DTextureFormat, forcePotTexture?: boolean): 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.

    @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.)

    Parameters

    • assetClass: any
    • Optional mipMapping: boolean
    • Optional optimizeForRenderToTexture: boolean
    • Optional scale: number
    • Optional format: Context3DTextureFormat
    • Optional forcePotTexture: boolean

    Returns Texture

Static fromNetStream

  • fromNetStream(stream: NetStream, scale?: number, onComplete?: function): 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.

    nc:NetConnection = new NetConnection(); nc.connect(null); ns:NetStream = new NetStream(nc); texture:Texture = Texture.fromNetStream(ns, 1, function():void { addChild(new Image(texture)); }); file:File = File.applicationDirectory.resolvePath("bugs-bunny.m4v"); ns.play(file.url);

    @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 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'.

    Parameters

    • stream: NetStream
    • Optional scale: number
    • Optional onComplete: function
        • (Texture: any): void
        • Parameters

          • Texture: any

          Returns void

    Returns Texture

Static fromTexture

  • fromTexture(texture: Texture, region?: Rectangle, frame?: Rectangle, rotated?: boolean, scaleModifier?: number): 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.

    Parameters

    • texture: Texture
    • Optional region: Rectangle
    • Optional frame: Rectangle
    • Optional rotated: boolean
    • Optional scaleModifier: number

    Returns Texture

Static fromTextureBase

  • Creates a texture from a 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.

    Parameters

    • base: TextureBase
    • width: number
    • height: number
    • Optional options: TextureOptions

    Returns ConcreteTexture

Static getMaxSize

  • getMaxSize(textureFormat?: Context3DTextureFormat): number

Static Protected get_asyncBitmapUploadEnabled

  • get_asyncBitmapUploadEnabled(): boolean

Static Protected get_maxSize

  • get_maxSize(): number

Static Protected get_useDoubleBuffering

  • get_useDoubleBuffering(): boolean

Static Protected set_asyncBitmapUploadEnabled

  • set_asyncBitmapUploadEnabled(value: boolean): boolean

Static Protected set_useDoubleBuffering

  • set_useDoubleBuffering(value: boolean): boolean

Generated using TypeDoc