Package | starling.textures |
Class | public class RenderTexture |
Inheritance | RenderTexture ![]() ![]() ![]() |
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.
PersistencePersistent 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!
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 [override] [read-only] The texture frame if it has one (see class description), otherwise null. | SubTexture | |
![]() | 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 | |
optimizePersistentBuffers : Boolean = false [static] Indicates if new persistent textures should use a single render buffer instead of
the default double buffering approach. | RenderTexture | ||
![]() | 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 | |
![]() | repeat : 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 | ||
![]() | 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 [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 | |
![]() | 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, repeat:Boolean = false) Creates a new RenderTexture with a certain size (in points). | 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(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 | ||
![]() | 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 | |
![]() | 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 | |
![]() | 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 | |
![]() | 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 | |
![]() | 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 = 0xffffffff, optimizeForRenderToTexture:Boolean = false, scale:Number = -1, format:String = bgra):Texture [static] Creates a texture with a certain size and color. | Texture | |
![]() | [static] Creates a texture object from any of the supported data types, using the specified
options. | Texture | |
![]() | 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 | |
![]() | 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):Texture [static] Creates a texture that contains a region (in pixels) of another texture. | Texture |
base | property |
base: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
optimizePersistentBuffers | property |
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
.
root | property |
root:ConcreteTexture
[read-only] [override] The concrete texture the texture is based on.
public function get root():ConcreteTexture
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.
Parameterswidth:int | |
height:int | |
persistent:Boolean (default = true )
| |
scale:Number (default = -1 )
| |
format:String (default = bgra )
| |
repeat:Boolean (default = false )
|
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). |