Package	starling.textures
Class	public class RenderTexture
Inheritance	RenderTexture SubTexture Texture 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.

      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.

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.

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