GODPAPER | All Packages | All Classes | Index | Frames No Frames |
RenderTexture

Package | starling.textures
Class | public class RenderTexture
Inheritance | RenderTexture SubTexture Texture Object

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

After creating a render texture, just call the `drawObject` 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.

          renderTexture.drawBundled(function():void
          {
             for (var i:int=0; 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".

Beware that render textures can't be restored when the Starling's render context is lost.

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | base : TextureBase [override] [read-only] The Stage3D texture object the texture is based on. | RenderTexture
|  | clipping : Rectangle [read-only] The clipping rectangle, which is the region provided on initialization scaled into [0.0, 1.0]. | SubTexture
|  | format : String [override] [read-only] The Context3DTextureFormat of the underlying texture data. | SubTexture
|  | frame : Rectangle [read-only] The texture frame (see class description). | Texture
|  | height : Number [override] [read-only] The height of the texture in points. | SubTexture
|  | isPersistent : Boolean [read-only] Indicates if the texture is persistent over multiple draw calls. | RenderTexture
|  | mipMapping : Boolean [override] [read-only] Indicates if the texture contains mip maps. | SubTexture
|  | nativeHeight : Number [override] [read-only] The height of the texture in pixels (without scale adjustment). | SubTexture
|  | nativeWidth : Number [override] [read-only] The width of the texture in pixels (without scale adjustment). | SubTexture
|  | ownsParent : Boolean [read-only] Indicates if the parent texture is disposed when this object is disposed. | SubTexture
|  | parent : Texture [read-only] The texture which the subtexture is based on. | SubTexture
|  | premultipliedAlpha : Boolean [override] [read-only] Indicates if the alpha values are premultiplied into the RGB values. | SubTexture
|  | repeat : Boolean Indicates if the texture should repeat like a wallpaper or stretch the outermost pixels. | Texture
|  | root : ConcreteTexture [override] [read-only] The concrete (power-of-two) texture the texture is based on. | RenderTexture
|  | scale : Number [override] [read-only] The scale factor, which influences width and height properties. | SubTexture
|  | width : Number [override] [read-only] The width of the texture in points. | SubTexture

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | RenderTexture(width:int, height:int, persistent:Boolean = true, scale:Number = -1) Creates a new RenderTexture with a certain size. | RenderTexture
|  | adjustTexCoords(texCoords:Vector.<Number>, startIndex:int = 0, stride:int = 0, count:int = -1):void [override] Converts texture coordinates into the format required for rendering. | SubTexture
|  | adjustVertexData(vertexData:VertexData, vertexID:int, count:int):void [override] Converts texture coordinates and vertex positions of raw vertex data into the format required for rendering. | SubTexture
|  | clear():void Clears the texture (restoring full transparency). | RenderTexture
|  | dispose():void [override] Disposes the parent texture if this texture owns it. | RenderTexture
|  | draw(object:DisplayObject, matrix:Matrix = null, alpha:Number = 1.0, antiAliasing:int = 0):void Draws an object into the texture. | RenderTexture
|  | drawBundled(drawingBlock:Function, antiAliasing:int = 0):void Bundles several calls to draw together in a block. | RenderTexture
|  | empty(width:Number, height:Number, premultipliedAlpha:Boolean = true, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra):Texture [static] Creates an empty texture of a certain size. | Texture
|  | fromAtfData(data:ByteArray, scale:Number = 1, useMipMaps:Boolean = true, async:Function = null):Texture [static] Creates a texture from the compressed ATF format. | Texture
|  | fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra):Texture [static] Creates a texture object from a bitmap. | Texture
|  | fromBitmapData(data:BitmapData, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra):Texture [static] Creates a texture object from bitmap data. | Texture
|  | fromColor(width:Number, height:Number, color:uint = 0xffffffff, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra):Texture [static] Creates a texture with a certain size and color. | Texture
|  | fromEmbeddedAsset(assetClass:Class, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra):Texture [static] Creates a texture object from an embedded asset class. | Texture
|  | fromTexture(texture:Texture, region:Rectangle = null, frame:Rectangle = null):Texture [static] Creates a texture that contains a region (in pixels) of another texture. | Texture

Property Detail

base | property

`base:TextureBase` [read-only] [override]

The Stage3D texture object the texture is based on.

Implementation
`public function get base():TextureBase`

isPersistent | property |

`isPersistent:Boolean` [read-only]

Indicates if the texture is persistent over multiple draw calls.

Implementation
`public function get isPersistent():Boolean`

root | property |

`root:ConcreteTexture` [read-only] [override]

The concrete (power-of-two) texture the texture is based on.

Implementation
`public function get root():ConcreteTexture`
Constructor Detail

RenderTexture | () | Constructor

`public function RenderTexture(width:int, height:int, persistent:Boolean = true, scale:Number = -1)`

Creates a new RenderTexture with a certain size. If the texture is persistent, the contents of the texture 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. Persistancy doubles the required graphics memory! Thus, if you need the texture only for one draw (or drawBundled) call, you should deactivate it.

Parameters

| `width:int`
| `height:int`
| `persistent:Boolean` (default = `true`)``
| `scale:Number` (default = `-1`)``

Method Detail

clear | () | method

`public function clear():void`

Clears the texture (restoring full transparency).

dispose | () | method |

`override public function dispose():void`

Disposes the parent texture if this texture owns it.

draw | () | method |

`public function draw(object:DisplayObject, matrix:Matrix = null, alpha:Number = 1.0, antiAliasing:int = 0):void`

Draws an object into the texture. Note that any filters on the object will currently be ignored.

Parameters

| `object:DisplayObject` — The object to draw.
| `matrix:Matrix` (default = `null`)`` — 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.
| `alpha:Number` (default = `1.0`)`` — The object's alpha value will be multiplied with this value.
| `antiAliasing:int` (default = `0`)`` — This parameter is currently ignored by Stage3D.

drawBundled | () | method |

`public function drawBundled(drawingBlock:Function, antiAliasing:int = 0):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.

Parameters

| `drawingBlock:Function`
| `antiAliasing:int` (default = `0`)``

Thu Jan 16 2014, 01:11 PM +08:00