Conforms to CC3Object
Declared in CC3RenderSurfaces.h

Overview

A CC3RenderSurface is a surface on which rendering or drawing can occur.

Tasks

Properties

colorAttachment

The surface attachment to which color data is rendered.

@property (nonatomic, retain) id<CC3RenderSurfaceAttachment> colorAttachment

Discussion

To save memory, attachments can be shared between surfaces of the same size, if the contents of the attachment are only required for the duration of the rendering to each surface.

Declared In

CC3RenderSurfaces.h

depthAttachment

The surface attachment to which depth data is rendered.

@property (nonatomic, retain) id<CC3RenderSurfaceAttachment> depthAttachment

Discussion

To save memory, attachments can be shared between surfaces of the same size, if the contents of the attachment are only required for the duration of the rendering to each surface. For instance, the same depth attachment might be used when rendering to several different color attachments of different surfaces.

Declared In

CC3RenderSurfaces.h

isFullCoverage

Returns whether this surface section covers the entire renderable area of a view.

@property (nonatomic, readonly) BOOL isFullCoverage

Declared In

CC3RenderSurfaces.h

isOnScreen

Returns whether this surface is an on-screen surface.

@property (nonatomic, assign) BOOL isOnScreen

Discussion

The initial value of this property is NO. For instances that represent on-screen framebuffers, set this property to YES.

Declared In

CC3RenderSurfaces.h

size

Returns the size of this surface in pixels.

@property (nonatomic, assign) CC3IntSize size

Declared In

CC3RenderSurfaces.h

stencilAttachment

The surface attachment to which stencil data is rendered.

@property (nonatomic, retain) id<CC3RenderSurfaceAttachment> stencilAttachment

Discussion

To save memory, attachments can be shared between surfaces of the same size, if the contents of the attachment are only required for the duration of the rendering to each surface.

Declared In

CC3RenderSurfaces.h

viewport

Returns a viewport suitable for rendering to this surface.

@property (nonatomic, readonly) CC3Viewport viewport

Declared In

CC3RenderSurfaces.h

Instance Methods

activate

Activates this surface in the GL engine.

- (void)activate

Discussion

Subsequent GL activity will be rendered to this surface.

Declared In

CC3RenderSurfaces.h

clearColorAndDepthContent

Clears the color and depth content of this surface, activating this surface and enabling color and depth writing if needed.

- (void)clearColorAndDepthContent

Declared In

CC3RenderSurfaces.h

clearColorContent

Clears the color content of this surface, activating this surface and enabling color writing if needed.

- (void)clearColorContent

Declared In

CC3RenderSurfaces.h

clearDepthContent

Clears the depth content of this surface, activating this surface and enabling depth writing if needed.

- (void)clearDepthContent

Declared In

CC3RenderSurfaces.h

clearStencilContent

Clears the stencil content of this surface, activating this surface and enabling stencil writing if needed.

- (void)clearStencilContent

Declared In

CC3RenderSurfaces.h

createCGImage

Returns a newly created CGImageRef from the contents of this surface. The size of the returned image will be the same as the size of this surface.

- (CGImageRef)createCGImage

Discussion

You are responsible for releasing the returned image by calling the CGImageRelease function.

Declared In

CC3RenderSurfaces.h

createCGImageFrom:

Returns a newly created CGImageRef from the contents of this surface that are contained within the specified rectangle. The size of the returned image will be the same as the size of the rectangle.

- (CGImageRef)createCGImageFrom:(CC3Viewport)rect

Discussion

You are responsible for releasing the returned image by calling the CGImageRelease function.

Declared In

CC3RenderSurfaces.h

readColorContentFrom:into:

Reads the content of the range of pixels defined by the specified rectangle from the color attachment of this surface, into the specified array, which must be large enough to accommodate the number of pixels covered by the specified rectangle.

- (void)readColorContentFrom:(CC3Viewport)rect into:(ccColor4B *)colorArray

Discussion

Content is written to the specified array left to right across each row, starting at the row at the bottom of the image, and ending at the row at the top of the image. The pixel content is packed tightly into the specified array, with no gaps left at the end of each row. The last pixel of one row is immediately followed by the first pixel of the next row.

This surface does not have to be the active surface to invoke this method. If this surface is not the active surface, it will temporarily be made active, and when pixel reading has finished, the currently active surface will be restored. This allows color to be read from one surface while rendering to another surface.

Not all surfaces have readable color content. In particular, content cannot be read from some system framebuffers.

This method should be used with care, since it involves making a synchronous call to query the state of the GL engine. This method will not return until the GL engine has executed all previous drawing commands in the pipeline. Excessive use of this method will reduce GL throughput and performance.

Declared In

CC3RenderSurfaces.h

replaceColorPixels:withContent:

If the colorAttachment of this surface supports pixel replacement, replaces a portion of the content of the color attachment by writing the specified array of pixels into the specified rectangular area within the attachment, The specified content replaces the pixel data within the specified rectangle. The specified content array must be large enough to contain content for the number of pixels in the specified rectangle.

- (void)replaceColorPixels:(CC3Viewport)rect withContent:(ccColor4B *)colorArray

Discussion

Not all color attachments support pixel replacement. In particular, pixel replacement is available only for color attachments whose content is provided by an underlying texture. If the color attachment does not support pixel replacement, this method will do nothing.

Content is read from the specified array left to right across each row of pixels within the specified image rectangle, starting at the row at the bottom of the rectangle, and ending at the row at the top of the rectangle.

Within the specified array, the pixel content should be packed tightly, with no gaps left at the end of each row. The last pixel of one row should immediately be followed by the first pixel of the next row.

The pixels in the specified array are in standard 32-bit RGBA. If the format of the underlying storage does not match this format, the specified array will be converted to the format of the underlying storage before being inserted. Be aware that this conversion will reduce the performance of this method. For maximum performance, match the format of the underlying storage to the 32-bit RGBA format of the specified array. However, keep in mind that the 32-bit RGBA format consumes more memory than most other formats, so if performance is of lesser concern, you may choose to minimize the memory requirements of this texture by choosing a more memory efficient storage format.

Declared In

CC3RenderSurfaces.h