RenderTexture
public class
loom2d.textures.RenderTexture
Description
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!
API overview
Constructor
RenderTexture
(
width: Number
,
height: Number
,
persistent: Boolean
= true
,
scale: Number
=
,
format: String
= bgra
,
repeat: Boolean
= false
)
Creates a new RenderTexture with a certain size (in points)
Attributes
Public attributes
| isPersistent: Boolean |
read-only
Indicates if the texture is persistent over multiple draw calls |
| optimizePersistentBuffers: Boolean |
static
Indicates if new persistent textures should use a single render buffer instead of the default double buffering approach |
Protected attributes
Functions
Public functions
| clear ( rgb: Number = 0 , alpha: Number = 0.0 ): Void |
Clears the render texture with a certain color and alpha value |
| draw ( object: DisplayObject , matrix: Matrix = null , alpha: Number = 1.0 ): Void |
Draws an object into the texture |
| drawBundled ( drawingBlock: Function ): Void |
Bundles several calls to draw together in a block |
| drawBundledLock (): Void |
For finer control over bundled drawing |
| drawBundledUnlock (): Void |
For finer control over bundled drawing |
Constructor
RenderTexture ( width: Number , height: Number , persistent: Boolean = true , scale: Number = , 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.
Attributes
asyncLoadComplete: TextureAsyncLoadCompleteDelegate
Inherited from Texture
For asynchonously loaded Textures, fired when the texture has completed loading its data. Note that if texture.dispose() is called before the async load has completed, the texture will be destroyed and 'asyncLoadComplete' will NOT get called.
clipping: Rectangle
Inherited from SubTexture
read-only
The clipping rectangle, which is the region provided on initialization scaled into [0.0, 1.0].
format: String
Inherited from SubTexture
read-only
frameReadOnly: Rectangle
Inherited from Texture
read-only
The texture frame as a read only temporary Rectangle The returned Rectangle is only valid between calls.
httpLoadFail: TextureHTTPFailDelegate
Inherited from Texture
For HTTP requested Textures, fired if the texture has failed to load.
nativeHeight: Number
Inherited from Texture
read-only
The height of the texture in pixels (without scale adjustment).
nativeWidth: Number
Inherited from Texture
read-only
The width of the texture in pixels (without scale adjustment).
optimizePersistentBuffers: Boolean
The default value is true
static
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.
// TODO: fix this if needed
ownsParent: Boolean
Inherited from SubTexture
read-only
Indicates if the parent texture is disposed when this object is disposed.
premultipliedAlpha: Boolean
Inherited from Texture
read-only
Indicates if the alpha values are premultiplied into the RGB values.
root: ConcreteTexture
Inherited from Texture
read-only
The concrete (power-of-two) texture the texture is based on.
scale: Number
Inherited from Texture
read-only
The scale factor, which influences width and height properties.
smoothing: Number
Inherited from Texture
The default value is TextureSmoothing.BILINEAR
Indicates if the texture do smooth filtering when it is scaled (BILINEAR) or just choose the nearest pixel (NONE)
wrapU: Number
Inherited from Texture
The default value is TextureWrap.CLAMP
Indicates if the texture should repeat like a wallpaper or stretch the outermost horizontal pixels. Note: this only works in textures with dimensions that are powers of two and that are not loaded from a texture atlas (i.e. no subtextures).
wrapV: Number
Inherited from Texture
The default value is TextureWrap.CLAMP
Indicates if the texture should repeat like a wallpaper or stretch the outermost vertical pixels. Note: this only works in textures with dimensions that are powers of two and that are not loaded from a texture atlas (i.e. no subtextures).
Protected attributes
Constants
PMA: Boolean
Functions
adjustVertexData
(
vertexData: VertexData
,
vertexID: Number
,
count: Number
): Void
Inherited from Texture
Converts texture coordinates and vertex positions of raw vertex data into the format required for rendering.
Parameters
| vertexData: VertexData | |
| vertexID: Number | |
| count: Number |
cancelHTTPRequest
(): Void
Inherited from Texture
Called to indicate that an HTTP texture load via fromHTTP() should be cancelled at the 1st possible opportunity. NOTE that this will also dipose the Texture returned by fromHTTP(), so consider it invalid after calling this.
clear ( rgb: Number = 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: Number = 0 | |
| alpha: Number = 0.0 |
dispose
(): Void
Inherited from Texture
Disposes the underlying texture data. Note that not all textures need to be disposed: SubTextures (created with 'Texture.fromTexture') just reference other textures and and do not take up resources themselves; this is also true for textures from an atlas.
draw ( object: DisplayObject , matrix: Matrix = null , alpha: Number = 1.0 ): Void
Draws an object into the texture. Note that any filters on the object will currently be ignored.
properties for position, scale, and rotation. If it is not null, the object will be drawn in the orientation depicted by the matrix.
Parameters
| object: DisplayObject | The object to draw. |
| matrix: Matrix = null | If 'matrix' is null, the object will be drawn adhering its |
| alpha: Number = 1.0 | The object's alpha value will be multiplied with this value. |
drawBundled ( drawingBlock: Function ): 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.
Parameters
| drawingBlock: Function |
a callback with the form: function():void; |
drawBundledLock (): Void
For finer control over bundled drawing. Locks the texture so that any future draw calls will render to the texture. Call drawBundledUnlock when you are done drawing to switch back to regular rendering. drawBundled uses this function internally.
drawBundledUnlock (): Void
For finer control over bundled drawing. Unlocks the texture and allows for regular rendering to resume. Call drawBundledLock before calling this function to first lock the texture. drawBundled uses this function internally.
empty
(
width: Number
,
height: Number
,
premultipliedAlpha: Boolean
= true
,
mipMapping: Boolean
= true
,
optimizeForRenderToTexture: Boolean
= false
,
scale: Number
=
,
format: String
= bgra
,
repeat: Boolean
= false
): Texture
Inherited from Texture
static
Creates an empty texture of a certain size. Beware that the texture can only be used after you either upload some color data ("texture.root.upload...") or clear the texture ("texture.root.clear()").
use the texture for bitmap data, use "true"; for ATF data, use "false".
bitmap data, this decides if mipmaps will be created; when you upload ATF data, this decides if mipmaps inside the ATF file will be displayed.
compressed formats to save memory (at the price of reduced image quality).
Parameters
| width: Number | in points; number of pixels depends on scale parameter |
| height: Number | in points; number of pixels depends on scale parameter |
| premultipliedAlpha: Boolean = true | the PMA format you will use the texture with. If you will |
| mipMapping: Boolean = true | indicates if mipmaps should be used for this texture. When you upload |
| optimizeForRenderToTexture: Boolean = false | indicates if this texture will be used as render target |
| scale: Number = | if you omit this parameter, 'Starling.contentScaleFactor' will be used. |
| format: String = bgra | the context3D texture format to use. Pass one of the packed or |
| repeat: Boolean = false | the repeat mode of the texture. Only useful for power-of-two textures. |
fromAsset
(
path: String
): Texture
Inherited from Texture
static
Blocking function that creates a texture object from a bitmap on disk.
Parameters
| path: String |
fromAssetAsync
(
path: String
,
cb: TextureAsyncLoadCompleteDelegate
,
highPriority: Boolean
= false
): Texture
Inherited from Texture
static
Non-blocking function that creates a texture object from a bitmap file on disk.
Parameters
| path: String | |
| cb: TextureAsyncLoadCompleteDelegate | |
| highPriority: Boolean = false |
fromBytes
(
bytes: ByteArray
,
uniqueName: String
= null
): Texture
Inherited from Texture
static
Creates a texture object from compressed image bytes. An optional unique name string can be supplied if you wish the resulting image to be cacheable, otherwise null can be specified.
The supported image types are JPEG (baseline), PNG (8-bit), TGA, BMP (non-1bpp, non-RLE), PSD (composited only), GIF, HDR (radiance rgbE), PIC (Softimage).
Parameters
| bytes: ByteArray | |
| uniqueName: String = null |
fromHTTP
(
url: String
,
onSuccess: TextureAsyncLoadCompleteDelegate
,
onFailure: TextureHTTPFailDelegate
,
cacheOnDisk: Boolean
= true
,
highPriority: Boolean
= false
,
existingTexture: Texture
= null
): Texture
Inherited from Texture
static
Non-blocking function that creates a texture object from a remote bitmap file via HTTP.
Parameters
| url: String | |
| onSuccess: TextureAsyncLoadCompleteDelegate | |
| onFailure: TextureHTTPFailDelegate | |
| cacheOnDisk: Boolean = true | |
| highPriority: Boolean = false | |
| existingTexture: Texture = null |
fromTexture
(
texture: Texture
,
region: Rectangle
= null
,
frame: Rectangle
= null
): Texture
Inherited from Texture
static
Creates a texture that contains a region (in pixels) of another texture. The new texture will reference the base texture; no data is duplicated.
Parameters
| texture: Texture | |
| region: Rectangle = null | |
| frame: Rectangle = null |
getFullTypeName
(): String
Inherited from Object
native
Gets the fully qualified type name of the Object. The fully qualified type name includes the package of the type.
Returns
| String | fully qualified type name of the Object. |
getType
(): Type
Inherited from Object
native
Gets the Type that describes the Object.
Returns
| Type | The Type that describes the object. |
getTypeName
(): String
Inherited from Object
native
Gets the type name of the Object.
Returns
| String | type name of the Object. |
isTextureValid
(): Boolean
Inherited from Texture
Checks the handle ID of the textureInfo to see if the texture is valid and ready for use.
toString
(): String
Inherited from Object
native
Returns a String that describes the Object. This can be overriden to provide extra details when printing objects using trace().
Returns
| String | String that described the Object. |
updateFrameAndClipping
(
region: Rectangle
,
frame: Rectangle
): Void
Inherited from SubTexture
Called by TextureAtlas to update SubTexture state. Be careful!
Parameters
| region: Rectangle | |
| frame: Rectangle |
updateFromHTTP
(
url: String
,
onSuccess: TextureAsyncLoadCompleteDelegate
,
onFailure: TextureHTTPFailDelegate
,
cacheOnDisk: Boolean
= true
,
highPriority: Boolean
= false
): Void
Inherited from Texture
Parameters
| url: String | |
| onSuccess: TextureAsyncLoadCompleteDelegate | |
| onFailure: TextureHTTPFailDelegate | |
| cacheOnDisk: Boolean = true | |
| highPriority: Boolean = false |