CCRenderTexture Class Reference

Inherits from CCNode : CCResponder : NSObject
Declared in CCRenderTexture.h

Overview

CCRenderTexture is a generic render target. To render things into it, simply create a render texture node, call begin on it, call visit on any Cocos2D scene or branch of the node tree to render it onto the render texture, then call end.

For convenience, render texture has a sprite property with the results, so you can just add the render texture to your scene and treat it like any other CCNode.

There are also functions for saving the render texture to disk in PNG or JPG format.

Creating a Render Texture

+ renderTextureWithWidth:height:pixelFormat:depthStencilFormat:

initializes a RenderTexture object with width and height in Points and a pixel format( only RGB and RGBA formats are valid ) and depthStencil format

+ (instancetype)renderTextureWithWidth:(int)w height:(int)h pixelFormat:(CCTexturePixelFormat)format depthStencilFormat:(GLuint)depthStencilFormat

Parameters

w

Width of render target.
h

Height of render target.
format

Pixel format of render target.
depthStencilFormat

Stencil format of render target.

Return Value

An initialized CCRenderTarget object.

See Also

Declared In

CCRenderTexture.h

+ renderTextureWithWidth:height:pixelFormat:

Creates a RenderTexture object with width and height in Points and a pixel format, only RGB and RGBA formats are valid

+ (instancetype)renderTextureWithWidth:(int)w height:(int)h pixelFormat:(CCTexturePixelFormat)format

Parameters

w

Width of render target.
h

Height of render target.
format

Pixel format of render target.

Return Value

An initialized CCRenderTarget object.

See Also

Declared In

CCRenderTexture.h

+ renderTextureWithWidth:height:

Creates a RenderTexture object with width and height in Points, pixel format is RGBA8888

+ (instancetype)renderTextureWithWidth:(int)w height:(int)h

Parameters

w

Width of render target.
h

Height of render target.

Return Value

An initialized CCRenderTarget object.

Declared In

CCRenderTexture.h

– initWithWidth:height:pixelFormat:

Initializes a RenderTexture object with width and height in Points and a pixel format, only RGB and RGBA formats are valid

- (id)initWithWidth:(int)w height:(int)h pixelFormat:(CCTexturePixelFormat)format

Parameters

w

Width of render target.
h

Height of render target.
format

Pixel format of render target.

Return Value

An initialized CCRenderTarget object.

See Also

Declared In

CCRenderTexture.h

– initWithWidth:height:pixelFormat:depthStencilFormat:

Initializes a RenderTexture object with width and height in Points and a pixel format( only RGB and RGBA formats are valid ) and depthStencil format

- (id)initWithWidth:(int)w height:(int)h pixelFormat:(CCTexturePixelFormat)format depthStencilFormat:(GLuint)depthStencilFormat

Parameters

w

Width of render target.
h

Height of render target.
format

Pixel format of render target.
depthStencilFormat

Stencil format of render target.

Return Value

An initialized CCRenderTarget object.

See Also

Declared In

CCRenderTexture.h

Begin and End Drawing

– begin

Starts rendering to the texture whitout clearing the texture first.

- (CCRenderer *)begin

Return Value

A CCRenderer instance used for drawing.

Declared In

CCRenderTexture.h

– beginWithClear:g:b:a:

Starts rendering to the texture while clearing the texture first. This is more efficient then calling clear and begin separately.

- (CCRenderer *)beginWithClear:(float)r g:(float)g b:(float)b a:(float)a

Parameters

r

Red color.
g

Green color.
b

Blue color.
a

Alpha.

Return Value

A CCRenderer instance used for drawing.

Declared In

CCRenderTexture.h

– beginWithClear:g:b:a:depth:

Starts rendering to the texture while clearing the texture first. This is more efficient then calling clear and begin separately.

- (CCRenderer *)beginWithClear:(float)r g:(float)g b:(float)b a:(float)a depth:(float)depthValue

Parameters

r

Red color.
g

Green color.
b

Blue color.
a

Alpha.
depthValue

Depth value.

Return Value

A CCRenderer instance used for drawing.

Declared In

CCRenderTexture.h

– beginWithClear:g:b:a:depth:stencil:

Starts rendering to the texture while clearing the texture first. This is more efficient then calling clear and begin separately.

- (CCRenderer *)beginWithClear:(float)r g:(float)g b:(float)b a:(float)a depth:(float)depthValue stencil:(int)stencilValue

Parameters

r

Red color.
g

Green color.
b

Blue color.
a

Alpha.
depthValue

Depth value.
stencilValue

Stencil value.

Return Value

A CCRenderer instance used for drawing.

Declared In

CCRenderTexture.h

– end

Ends rendering and allows you to use the texture, ie save it or using it in a sprite.

- (void)end

Declared In

CCRenderTexture.h

Clearing the Render Texture

– clear:g:b:a:

Clears the texture with a color

- (void)clear:(float)r g:(float)g b:(float)b a:(float)a

Parameters

r

Red color.
g

Green color.
b

Blue color.
a

Alpha.

Declared In

CCRenderTexture.h

– clearDepth:

Clears the texture with a specified depth value.

- (void)clearDepth:(float)depthValue

Parameters

depthValue

Depth value.

Declared In

CCRenderTexture.h

– clearStencil:

Clears the texture with a specified stencil value.

- (void)clearStencil:(int)stencilValue

Parameters

stencilValue

Stencil value.

Declared In

CCRenderTexture.h

  clearFlags

Valid flags:

@property (nonatomic, readwrite) GLbitfield clearFlags

Discussion

  • GL_COLOR_BUFFER_BIT
  • GL_DEPTH_BUFFER_BIT
  • GL_STENCIL_BUFFER_BIT

The flags can be combined with bitwise OR. Only valid when autoDraw is YES.

Declared In

CCRenderTexture.h

  clearColor

Clear color value. Valid only when autoDraw is YES.

@property (nonatomic, strong) CCColor *clearColor

See Also

Declared In

CCRenderTexture.h

  clearDepth

Value for clearDepth. Valid only when autoDraw is YES.

@property (nonatomic, readwrite) GLclampf clearDepth

Declared In

CCRenderTexture.h

  clearStencil

Value for clear Stencil. Valid only when autoDraw is YES

@property (nonatomic, readwrite) GLint clearStencil

Declared In

CCRenderTexture.h

Render Texture Drawing Properties

  autoDraw

When enabled, it will render its children into the texture automatically. Disabled by default for compatiblity reasons.

@property (nonatomic, readwrite) BOOL autoDraw

Discussion

Note: Will default to YES in a future version of Cocos2D.

Declared In

CCRenderTexture.h

  projection

Projection matrix used by render texture.

@property (nonatomic, readwrite) GLKMatrix4 projection

Declared In

CCRenderTexture.h

Accessing the Sprite and Texture

  sprite

The CCSprite that is used for rendering.

@property (nonatomic, readwrite, strong) CCSprite *sprite

Discussion

Note: A subtle change introduced in v3.1.1 is that this sprite is rendered explicitly and is no longer a child of the render texture.

See Also

Declared In

CCRenderTexture.h

  texture

The render texture’s (and its sprite’s) texture.

@property (nonatomic, readonly) CCTexture *texture

See Also

Declared In

CCRenderTexture.h

  contentScale

The render texture’s content scale factor.

@property (nonatomic, readwrite) float contentScale

Declared In

CCRenderTexture.h

Converting Render Texture To Image

– newCGImage

Creates a new CGImage from with the texture’s data.

- (CGImageRef)newCGImage

Discussion

Note: Caller is responsible for releasing the CGImageRef by calling CGImageRelease(imageRef) on the returned CG image.

Declared In

CCRenderTexture.h

– getUIImage

Returns a UIImage created from the texture.

- (UIImage *)getUIImage

Declared In

CCRenderTexture.h

Saving Texture Contents to a File

– saveToFile:

Saves the texture into a file using JPEG format. The file will be saved in the Documents folder.

- (BOOL)saveToFile:(NSString *)name

Parameters

name

Filename to save image to.

Return Value

YES if the operation is successful.

Declared In

CCRenderTexture.h

– saveToFile:format:

Saves the texture into a file. The format could be JPG or PNG depending on the format. The file will be saved in the Documents folder.

- (BOOL)saveToFile:(NSString *)name format:(CCRenderTextureImageFormat)format

Parameters

name

Filename to save image to.
format

File format, see CCRenderTextureImageFormat.

Return Value

YES if the operation is successful.

See Also

Declared In

CCRenderTexture.h

– saveToFilePath:

Saves the texture into a file using JPEG format.

- (BOOL)saveToFilePath:(NSString *)filePath

Parameters

filePath

File path to save image to.

Return Value

YES if the operation was successful.

Availability

Available only on iOS.

Declared In

CCRenderTexture.h

– saveToFilePath:format:

Saves the texture into a file. The format could be JPG or PNG depending on the format.

- (BOOL)saveToFilePath:(NSString *)filePath format:(CCRenderTextureImageFormat)format

Parameters

filePath

File path to save image to.
format

File format, see CCRenderTextureImageFormat.

Return Value

YES if the operation was successful.

Availability

Available only on iOS.

See Also

Declared In

CCRenderTexture.h