| Package | starling.textures |
| Class | public class RenderTexture |
| Inheritance | RenderTexture  SubTexture Texture 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.
PersistenceOlder 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.
| Property | Defined By | ||
|---|---|---|---|
| base : TextureBase [override] [read-only] The Stage3D texture object the texture is based on. | RenderTexture | ||
 | format : String [override] [read-only] The Context3DTextureFormat of the underlying texture data. | SubTexture | |
| frame : Rectangle [override] [read-only] The texture frame if it has one (see class description), otherwise null. | SubTexture | |
| frameHeight : Number [read-only] The width of the texture in points, taking into account the frame rectangle
(if there is one). | Texture | |
| frameWidth : Number [read-only] The height of the texture in points, taking into account the frame rectangle
(if there is one). | 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 | ||
| maxSize : int [static] [read-only] Returns the maximum size constraint (for both width and height) for textures in the
current Context3D profile. | Texture | |
| 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 | |
| region : 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 | ||
| rotated : Boolean [read-only] If true, the SubTexture will show the parent region rotated by 90 degrees (CCW). | SubTexture | |
| scale : Number [override] [read-only] The scale factor, which influences width and height properties. | SubTexture | |
| transformationMatrix : 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 | |
| transformationMatrixToRoot : 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 | ||
| width : Number [override] [read-only] The width of the texture in points. | SubTexture | |
| Method | Defined 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 | ||
| 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 | |
| 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 | |
| fromBitmap(bitmap:Bitmap, generateMipMaps:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture [static] Creates a texture object from a bitmap. | Texture | |
| fromBitmapData(data:BitmapData, generateMipMaps:Boolean = false, optimizeForRenderToTexture:Boolean = false, scale:Number = 1, format:String = bgra, forcePotTexture:Boolean = false):Texture [static] Creates a texture object from bitmap data. | Texture | |
| fromCamera(camera:Camera, scale:Number = 1, onComplete:Function = null):Texture [static] Creates a video texture from a camera. | Texture | |
| 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 | |
| [static] Creates a texture from any of the supported data types, using the specified options. | Texture | |
| 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 | |
| fromNetStream(stream:NetStream, scale:Number = 1, onComplete:Function = null):Texture [static] Creates a video texture from a NetStream. | Texture | |
| 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 | |
| fromTextureBase(base:TextureBase, width:int, height:int, options:TextureOptions = null):ConcreteTexture [static] Creates a texture from a TextureBase object. | Texture | |
| 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 | |
| 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 | |
| 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 | |
| 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 | |
| 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 | |
| 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 | |
| base | property |
Hide Inherited Public Properties
Show Inherited Public Propertiesbase:TextureBase [read-only] [override] The Stage3D texture object the texture is based on.
public function get base():TextureBase| isPersistent | property |
isPersistent:Boolean [read-only] Indicates if the texture is persistent over multiple draw calls.
public function get isPersistent():Boolean| root | property |
root:ConcreteTexture [read-only] [override] The concrete texture the texture is based on.
public function get root():ConcreteTexture| useDoubleBuffering | property |
useDoubleBuffering:BooleanIndicates 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.
public static function get useDoubleBuffering():Boolean public static function set useDoubleBuffering(value:Boolean):void| 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.
width:int | |
height:int | |
persistent:Boolean (default = true) | |
scale:Number (default = -1) | |
format:String (default = bgra) |
| clear | () | method |
public function clear(color:uint = 0, alpha:Number = 0.0):voidClears 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():voidDisposes 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):voidDraws 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) | |
alpha:Number (default = 1.0) | |
antiAliasing:int (default = 0) |
| 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) |