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. 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
      {
          var 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
      {
          var 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.]



Public Properties
 PropertyDefined By
 InheritedasyncBitmapUploadEnabled : Boolean
[static] Indicates if it should be attempted to upload bitmaps asynchronously when the async parameter is supplied to supported methods.
Texture
  base : TextureBase
[override] [read-only] The Stage3D texture object the texture is based on.
RenderTexture
 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
 InheritedframeHeight : Number
[read-only] The width of the texture in points, taking into account the frame rectangle (if there is one).
Texture
 InheritedframeWidth : Number
[read-only] The height of the texture in points, taking into account the frame rectangle (if there is one).
Texture
 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
 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
  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
[override] [read-only] The matrix that is used to transform the texture coordinates into the coordinate space of the parent texture, if there is one.
SubTexture
 InheritedtransformationMatrixToRoot : Matrix
[override] [read-only] 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.
SubTexture
  useDoubleBuffering : Boolean
[static] Indicates if new persistent textures should use double buffering.
RenderTexture
 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)
Creates a new RenderTexture with a certain size (in points).
RenderTexture
  
clear(color: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 = false, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, forcePotTexture: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, premultipliedAlpha:Boolean = false):Texture
[static] Creates a texture from ATF data (Adobe Texture Compression).
Texture
 Inherited
fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false, async:Function = null):Texture
[static] Creates a texture object from a bitmap.
Texture
 Inherited
fromBitmapData(data:BitmapData, generateMipMaps:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false, async:Function = null):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 = 0xffffff, alpha:Number = 1.0, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra, forcePotTexture:Boolean = false):Texture
[static] Creates a texture with a certain size and color.
Texture
 Inherited
fromData(data:Object, options:TextureOptions = null):Texture
[static] Creates a texture from any of the supported data types, using the specified options.
Texture
 Inherited
fromEmbeddedAsset(assetClass:Class, mipMapping:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture: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, scaleModifier:Number = 1.0):Texture
[static] Creates a texture that contains a region (in pixels) of another texture.
Texture
 Inherited
fromTextureBase(base:TextureBase, width:int, height:int, options:TextureOptions = null):ConcreteTexture
[static] Creates a texture from a TextureBase object.
Texture
 Inherited
getTexCoords(vertexData:VertexData, vertexID:int, attrName:String = texCoords, out:Point = null):Point
Reads a pair of texture coordinates from the given VertexData instance and transforms them into the current texture's coordinate system.
Texture
 Inherited
globalToLocal(u:Number, v:Number, out:Point = null):Point
Transforms the given texture coordinates from the root texture's coordinate system to the local coordinate system.
Texture
 Inherited
localToGlobal(u:Number, v:Number, out:Point = null):Point
Transforms the given texture coordinates from the local coordinate system into the root texture's coordinate system.
Texture
 Inherited
setTexCoords(vertexData:VertexData, vertexID:int, 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.
Texture
 Inherited
setupTextureCoordinates(vertexData:VertexData, vertexID:int = 0, attrName:String = texCoords):void
Sets up a VertexData instance with the correct texture coordinates for 4 vertices so that the texture is mapped to the complete quad.
Texture
 Inherited
setupVertexPositions(vertexData:VertexData, vertexID:int = 0, attrName:String = position, bounds:Rectangle = null):void
Sets up a VertexData instance with the correct positions for 4 vertices so that the texture can be mapped onto it unscaled.
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
rootproperty 
root:ConcreteTexture  [read-only] [override]

The concrete texture the texture is based on.


Implementation
    public function get root():ConcreteTexture
useDoubleBufferingproperty 
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.

The default value is true for "baseline" and "baselineConstrained", false otherwise.


Implementation
    public static function get useDoubleBuffering():Boolean
    public static function set useDoubleBuffering(value:Boolean):void
Constructor Detail
RenderTexture()Constructor
public function RenderTexture(width:int, height:int, persistent:Boolean = true, scale:Number = -1, format:String = bgra)

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:int
 
height:int
 
persistent:Boolean (default = true)
 
scale:Number (default = -1)
 
format:String (default = bgra)
Method Detail
clear()method
public function clear(color: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

color: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) — 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).

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