Packagestarling.textures
Classpublic class RenderTexture
InheritanceRenderTexture Inheritance SubTexture Inheritance Texture Inheritance 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.

Persistence

Persistent render textures (see the 'persistent' flag in the constructor) are more expensive, because they might have to use two render buffers internally. Disable this parameter if you don't need that.

On modern hardware, you can make use of the static 'optimizePersistentBuffers' property to overcome the need for double buffering. Use this feature with care, though!



Public Properties
 PropertyDefined By
  base : TextureBase
[override] [read-only] The Stage3D texture object the texture is based on.
RenderTexture
 Inheritedclipping : Rectangle
[read-only] The clipping rectangle, which is the region provided on initialization scaled into [0.0, 1.0].
SubTexture
 Inheritedformat : String
[override] [read-only] The Context3DTextureFormat of the underlying texture data.
SubTexture
 Inheritedframe : Rectangle
[override] [read-only] The texture frame if it has one (see class description), otherwise null.
SubTexture
 Inheritedheight : 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
 InheritedmaxSize : int
[static] [read-only] Returns the maximum size constraint (for both width and height) for textures in the current Context3D profile.
Texture
 InheritedmipMapping : Boolean
[override] [read-only] Indicates if the texture contains mip maps.
SubTexture
 InheritednativeHeight : Number
[override] [read-only] The height of the texture in pixels (without scale adjustment).
SubTexture
 InheritednativeWidth : Number
[override] [read-only] The width of the texture in pixels (without scale adjustment).
SubTexture
  optimizePersistentBuffers : Boolean = false
[static] Indicates if new persistent textures should use a single render buffer instead of the default double buffering approach.
RenderTexture
 InheritedownsParent : Boolean
[read-only] Indicates if the parent texture is disposed when this object is disposed.
SubTexture
 Inheritedparent : Texture
[read-only] The texture which the SubTexture is based on.
SubTexture
 InheritedpremultipliedAlpha : Boolean
[override] [read-only] Indicates if the alpha values are premultiplied into the RGB values.
SubTexture
 Inheritedregion : Rectangle
[read-only] The region of the parent texture that the SubTexture is showing (in points).
SubTexture
 Inheritedrepeat : Boolean
[override] [read-only] Indicates if the texture should repeat like a wallpaper or stretch the outermost pixels.
SubTexture
  root : ConcreteTexture
[override] [read-only] The concrete texture the texture is based on.
RenderTexture
 Inheritedrotated : Boolean
[read-only] If true, the SubTexture will show the parent region rotated by 90 degrees (CCW).
SubTexture
 Inheritedscale : Number
[override] [read-only] The scale factor, which influences width and height properties.
SubTexture
 InheritedtransformationMatrix : Matrix
[read-only] The matrix that is used to transform the texture coordinates into the coordinate space of the parent texture (used internally by the "adjust..."-methods).
SubTexture
 Inheritedwidth : Number
[override] [read-only] The width of the texture in points.
SubTexture
Public Methods
 MethodDefined By
  
RenderTexture(width:int, height:int, persistent:Boolean = true, scale:Number = -1, format:String = bgra, repeat:Boolean = false)
Creates a new RenderTexture with a certain size (in points).
RenderTexture
 Inherited
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
 Inherited
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(rgb:uint = 0, alpha:Number = 0.0):void
Clears the render texture with a certain color and alpha value.
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
 Inherited
empty(width:Number, height:Number, premultipliedAlpha:Boolean = true, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, repeat:Boolean = false):Texture
[static] Creates an empty texture of a certain size.
Texture
 Inherited
fromAtfData(data:ByteArray, scale:Number = 1, useMipMaps:Boolean = true, async:Function = null, repeat:Boolean = false):Texture
[static] Creates a texture from the compressed ATF format.
Texture
 Inherited
fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, repeat:Boolean = false):Texture
[static] Creates a texture object from a bitmap.
Texture
 Inherited
fromBitmapData(data:BitmapData, generateMipMaps:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, repeat:Boolean = false):Texture
[static] Creates a texture object from bitmap data.
Texture
 Inherited
fromCamera(camera:Camera, scale:Number = 1, onComplete:Function = null):Texture
[static] Creates a video texture from a camera.
Texture
 Inherited
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
 Inherited
fromData(data:Object, options:TextureOptions = null):Texture
[static] Creates a texture object from any of the supported data types, using the specified options.
Texture
 Inherited
fromEmbeddedAsset(assetClass:Class, mipMapping:Boolean = true, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, repeat:Boolean = false):Texture
[static] Creates a texture object from an embedded asset class.
Texture
 Inherited
fromNetStream(stream:NetStream, scale:Number = 1, onComplete:Function = null):Texture
[static] Creates a video texture from a NetStream.
Texture
 Inherited
fromTexture(texture:Texture, region:Rectangle = null, frame:Rectangle = null, rotated:Boolean = false):Texture
[static] Creates a texture that contains a region (in pixels) of another texture.
Texture
Property Detail
baseproperty
base:TextureBase  [read-only] [override]

The Stage3D texture object the texture is based on.


Implementation
    public function get base():TextureBase
isPersistentproperty 
isPersistent:Boolean  [read-only]

Indicates if the texture is persistent over multiple draw calls.


Implementation
    public function get isPersistent():Boolean
optimizePersistentBuffersproperty 
public static var optimizePersistentBuffers:Boolean = false

Indicates if new persistent textures should use a single render buffer instead of the default double buffering approach. That's faster and requires less memory, but is not supported on all hardware.

You can safely enable this property on all iOS and Desktop systems. On Android, it's recommended to enable it only on reasonably modern hardware, e.g. only when at least one of the 'Standard' profiles is supported.

Beware: this feature requires at least Flash/AIR version 15.

The default value is false.

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

The concrete 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, format:String = bgra, repeat:Boolean = false)

Creates a new RenderTexture with a certain size (in points). 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.

Beware that persistence requires an additional texture buffer (i.e. the required memory is doubled). You can avoid that via 'optimizePersistentBuffers', though.

Parameters
width:int
 
height:int
 
persistent:Boolean (default = true)
 
scale:Number (default = -1)
 
format:String (default = bgra)
 
repeat:Boolean (default = false)
Method Detail
clear()method
public function clear(rgb:uint = 0, alpha:Number = 0.0):void

Clears the render texture with a certain color and alpha value. Call without any arguments to restore full transparency.

Parameters

rgb:uint (default = 0)
 
alpha:Number (default = 0.0)

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) — Only supported beginning with AIR 13, and only on Desktop. Values range from 0 (no antialiasing) to 4 (best quality).

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. Note that the 'antiAliasing' setting provided here overrides those provided in individual 'draw' calls.

Parameters

drawingBlock:Function — a callback with the form:
function():void;
 
antiAliasing:int (default = 0) — Only supported beginning with AIR 13, and only on Desktop. Values range from 0 (no antialiasing) to 4 (best quality).