Inherits from CC3Identifiable : NSObject
Conforms to CC3RenderSurface
Declared in CC3RenderSurfaces.h

Overview

CC3SurfaceSection is a surface that is a section of another underlying base surface.

As a surface, the surface section uses the attachments of the base surface, and all rendering activities performed on the surface section will be passed along to the base surface.

The size of the surface section can be set to a value different from the size of the base surface, and rendering to the surface section will be restricted to this size on the base surface. In addition, a surface section supports a origin property. The combination of the origin and size properties constrains all rendering activity to a rectangle somewhere on the base surface, as described by the viewport property of the surface section.

Tasks

Properties

baseSurface

The base surface of which this surface is a part.

@property (nonatomic, retain) id<CC3RenderSurface> baseSurface

Discussion

Activating this surface activates the base surface, and all rendering occurs on the base surface, within the viewport defined by the viewport of this surface.

If the size property of this surface has not been set when this property is set, the size property of this instance will be set to that of the base surface. However, once set, the size property is not changed if this property is changed. This allows the base surface to be changed, while retaining a defined viewport through the size and origin properties.

Declared In

CC3RenderSurfaces.h

colorAttachment

The surface attachment to which color data is rendered.

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

Discussion

Returns the value of the same property on the baseSurface. Setting the value of this property has no effect.

Declared In

CC3RenderSurfaces.h

depthAttachment

The surface attachment to which depth data is rendered.

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

Discussion

Returns the value of the same property on the baseSurface. Setting the value of this property has no effect.

Declared In

CC3RenderSurfaces.h

isFullCoverage

Returns whether this surface section covers the entire base surface.

@property (nonatomic, readonly) BOOL isFullCoverage

Discussion

Returns YES if the same property on the base surface returns YES, the origin property is zero, and the size property of this section is equal to the size property of the base surface.

Declared In

CC3RenderSurfaces.h

isOnScreen

Returns whether this surface is an on-screen surface.

@property (nonatomic, assign) BOOL isOnScreen

Discussion

Returns the value of the same property on the baseSurface. Setting the value of this property has no effect.

Declared In

CC3RenderSurfaces.h

origin

The origin of this surface section, relative to the base surface.

@property (nonatomic, assign) CC3IntPoint origin

Discussion

Changing the value of this property changes the value returned by the viewport property, which causes rendering to occur only within the section of the base surface defined by the viewport property.

The initial value of this property is zero.

Declared In

CC3RenderSurfaces.h

size

The size of this surface in pixels.

@property (nonatomic, assign) CC3IntSize size

Discussion

Changing the value of this property does not affect the size of any attachments. Instead, changing the value of this property changes the value returned by the viewport property, which causes rendering to occur only within the section of the base surface defined by the viewport property.

The initial value of this property is the size of the base surface at the time the baseSurface property is set for the first time.

Declared In

CC3RenderSurfaces.h

stencilAttachment

The surface attachment to which stencil data is rendered.

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

Discussion

Returns the value of the same property on the baseSurface. Setting the value of this property has no effect.

Declared In

CC3RenderSurfaces.h

viewport

Returns a viewport whose origin is at the point specified by the origin property, and whose width and height match the size property.

@property (nonatomic, readonly) CC3Viewport viewport

Discussion

Initially, this property will return a viewport that covers the entire baseSurface. Changing the origin and size properties of this instance will change the value returned by this property.

Declared In

CC3RenderSurfaces.h

Class Methods

surfaceOnSurface:

Allocates and initializes an instance as a section of the specified surface.

+ (instancetype)surfaceOnSurface:(id<CC3RenderSurface>)baseSurface

Discussion

The initial size of the returned instance will be set to that of the specified surface.

Declared In

CC3RenderSurfaces.h

Instance Methods

activate

Activates this surface in the GL engine.

- (void)activate

Discussion

If the isFullCoverage property returns NO, this method applies a scissor function to the GL engine, so that subsequent GL activity while this surface is active will be constrained to the viewport of this surface.

Declared In

CC3RenderSurfaces.h

clearColorAndDepthContent

Clears the color and depth content of the base surface, within the bounds of the viewport of this instance.

- (void)clearColorAndDepthContent

Declared In

CC3RenderSurfaces.h

clearColorContent

Clears the color content of the base surface, within the bounds of the viewport of this instance.

- (void)clearColorContent

Declared In

CC3RenderSurfaces.h

clearDepthContent

Clears the depth content of the base surface, within the bounds of the viewport of this instance.

- (void)clearDepthContent

Declared In

CC3RenderSurfaces.h

clearStencilContent

Clears the stencil content of the base surface, within the bounds of the viewport of this instance.

- (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

The rectangle is first offset by the origin of this surface section.

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

Declared In

CC3RenderSurfaces.h

initOnSurface:

Initializes this instance as a section of the specified surface.

- (instancetype)initOnSurface:(id<CC3RenderSurface>)baseSurface

Discussion

The initial size of this instance will be set to that of the specified surface.

Declared In

CC3RenderSurfaces.h

readColorContentFrom:into:

Reads the content of the range of pixels defined by the specified rectangle from the color attachment of the base 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

The rectangle is first offset by the origin of this surface section.

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 the base 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

The rectangle is first offset by the origin of this surface section.

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