CC3GLFramebuffer Class Reference

#import <CC3RenderSurfaces.h>

Inheritance diagram for CC3GLFramebuffer:

Instance Methods
(instancetype)	- init
(instancetype)	- initAsColorTextureIsOpaque:
(instancetype)	- initAsColorTextureIsOpaque:withDepthAttachment:
(instancetype)	- initAsColorTextureIsOpaque:withDepthFormat:
(instancetype)	- initAsColorTextureWithPixelFormat:withPixelType:withDepthAttachment:
(instancetype)	- initWithFramebufferID:
(void)	- validate
Instance Methods inherited from CC3Identifiable
(void)	- __deprecated
(id)	- copy
(id)	- copyAsClass:
(void)	- copyUserDataFrom:
(id)	- copyWithName:
(id)	- copyWithName:asClass:
(id)	- copyWithZone:withName:
(id)	- copyWithZone:withName:asClass:
(BOOL)	- deriveNameFrom:
(BOOL)	- deriveNameFrom:usingSuffix:
(NSString *)	- fullDescription
(id)	- initAtIndex:fromPODResource:
(void)	- initUserData
(id)	- initWithName:
(id)	- initWithTag:
(id)	- initWithTag:withName:
(GLuint)	- nextTag
(void)	- populateFrom:
Instance Methods inherited from <CC3RenderSurface>
(void)	- activate
(void)	- clearColorAndDepthContent
(void)	- clearColorContent
(void)	- clearDepthContent
(void)	- clearStencilContent
(CGImageRef)	- createCGImage
(CGImageRef)	- createCGImageFrom:
(void)	- readColorContentFrom:into:
(void)	- replaceColorPixels:withContent:
Instance Methods inherited from <CC3Object>
(id)	- asWeakReference
(id)	- resolveWeakReference

Class Methods
(instancetype)	+ colorTextureSurfaceIsOpaque:
(instancetype)	+ colorTextureSurfaceIsOpaque:withDepthAttachment:
(instancetype)	+ colorTextureSurfaceIsOpaque:withDepthFormat:
(instancetype)	+ colorTextureSurfaceWithPixelFormat:withPixelType:withDepthAttachment:
(instancetype)	+ surface
(instancetype)	+ surfaceWithFramebufferID:
Class Methods inherited from CC3Identifiable
(GLint)	+ instanceCount
(void)	+ resetTagAllocation

Properties
id< CC3FramebufferAttachment >	colorAttachment
CC3Texture *	colorTexture
id< CC3FramebufferAttachment >	depthAttachment
CC3Texture *	depthTexture
GLuint	framebufferID
BOOL	isFullCoverage
BOOL	isManagingGL
BOOL	isOnScreen
BOOL	shouldBindGLAttachments
CC3IntSize	size
id< CC3FramebufferAttachment >	stencilAttachment
CC3Viewport	viewport
Properties inherited from CC3Identifiable
NSObject *sharedUserData	__deprecated
NSString *	name
NSString *	nameSuffix
GLint	podIndex
BOOL	shouldIncludeInDeepCopy
GLuint	tag
NSObject *	userData
Properties inherited from <CC3Cacheable>
NSString *	name
Properties inherited from <CC3RenderSurface>
id< CC3RenderSurfaceAttachment >	colorAttachment
id< CC3RenderSurfaceAttachment >	depthAttachment
BOOL	isFullCoverage
BOOL	isOnScreen
CC3IntSize	size
id< CC3RenderSurfaceAttachment >	stencilAttachment
CC3Viewport	viewport

Detailed Description

Represents an OpenGL framebuffer.

Framebuffers hold between one and three attachments. Each attachment represents a rendering buffer that holds a particular type of drawn content: color, depth, or stencil content. Typically, each of these attachments will be either a renderbuffer, a texture (to support rendering to a texture), or nil, indicating that that type of content is not being rendered.

Broadly speaking, there are two ways to instantiate an instance and manage the lifespan of the corresponding framebuffer in the GL engine, these are described as follows.

If you instantiate an instance without explicitly providing the ID of an existing OpenGL framebuffer, a framebuffer will automatically be created within the GL engine, as needed, and will automatically be deleted from the GL engine when the instance is deallocated.

To map to an existing OpenGL framebuffer, you can provide the value of the framebufferID property during instance instantiation. In this case, the instance will not delete the framebuffer from the GL engine when the instance is deallocated, and it is up to you to coordinate the lifespan of the instance and the GL framebuffer. Do not use the instance once you have deleted the framebuffer from the GL engine.

When creating an instance to map to an existing OpenGL framebuffer, the shouldBindGLAttachments property can be used to indicate whether or not attachments should be automatically bound to the framebuffer within the GL engine, as they are attached to an instance.

You should consider setting the name property of each instance, to distinguish them. The name will also appear in the debugger when capturing OpenGL frames. If you set the name before adding attachments, it will propagate to those attachments.

Method Documentation

+ (instancetype) colorTextureSurfaceIsOpaque:

(BOOL)

isOpaque

Allocates and initializes an instance, sets the colorTexture property to a new blank 2D texture, and sets the depthAttachment property to a new renderbuffer configured with the standard GL_DEPTH_COMPONENT16 depth format.

To define the shape of the surface, you should either set the size property of the returned instance, or add it to a CC3SurfaceManager instance.

The isOpaque parameter indicates whether or not the colorTexture should support transparency, by including or excluding an alpha component in each pixel. The colorTexture will support transparency if isOpaque is set to NO, otherwise the texture will not support transparency. Specifically, the pixelFormat / pixelType properties of the texture are configured as follows:

• GL_RGB / GL_UNSIGNED_SHORT_5_6_5 if isOpaque is YES.
• GL_RGBA / GL_UNSIGNED_BYTE if isOpaque is NO.

Note that, with these texture formats, a texture that supports transparency requires twice the memory space of an opaque texture.

The depthAttachment is used only during the rendering of content to the color texture. If you are creating many color texture surfaces of the same size, you can save memory by using the same depthAttachment for all such surfaces. In this case, consider using the colorTextureSurfaceIsOpaque:withDepthAttachment: method instead.

+ (instancetype) colorTextureSurfaceIsOpaque:		(BOOL)	isOpaque
withDepthAttachment:		(id< CC3FramebufferAttachment >)	depthAttachment

Allocates and initializes an instance, sets the colorTexture property to a new blank 2D texture, and sets the depthAttachment property to the specified depth attachment.

To define the shape of the surface, you should either set the size property of the returned instance, or add it to a CC3SurfaceManager instance.

The isOpaque parameter indicates whether or not the colorTexture should support transparency, by including or excluding an alpha component in each pixel. The colorTexture will support transparency if isOpaque is set to NO, otherwise the texture will not support transparency. Specifically, the pixelFormat / pixelType properties of the texture are configured as follows:

• GL_RGB / GL_UNSIGNED_SHORT_5_6_5 if isOpaque is YES.
• GL_RGBA / GL_UNSIGNED_BYTE if isOpaque is NO.

Note that, with these texture formats, a texture that supports transparency requires twice the memory space of an opaque texture.

The depthAttachment is used only during the rendering of content to the color texture. If you are creating many color texture surfaces of the same size, you can save memory by using the same depthAttachment for all such surfaces.

+ (instancetype) colorTextureSurfaceIsOpaque:		(BOOL)	isOpaque
withDepthFormat:		(GLenum)	depthFormat

Allocates and initializes an instance, sets the colorTexture property to a new blank 2D texture, and sets the depthAttachment property to a new renderbuffer configured with the specified depth format.

To define the shape of the surface, you should either set the size property of the returned instance, or add it to a CC3SurfaceManager instance.

The depthFormat argument may be one of the following values:

• GL_DEPTH_COMPONENT16
• GL_DEPTH_COMPONENT24
• GL_DEPTH24_STENCIL8

The isOpaque parameter indicates whether or not the colorTexture should support transparency, by including or excluding an alpha component in each pixel. The colorTexture will support transparency if isOpaque is set to NO, otherwise the texture will not support transparency. Specifically, the pixelFormat / pixelType properties of the texture are configured as follows:

• GL_RGB / GL_UNSIGNED_SHORT_5_6_5 if isOpaque is YES.
• GL_RGBA / GL_UNSIGNED_BYTE if isOpaque is NO.

Note that, with these texture formats, a texture that supports transparency requires twice the memory space of an opaque texture.

The depthAttachment is used only during the rendering of content to the color texture. If you are creating many color texture surfaces of the same size, you can save memory by using the same depthAttachment for all such surfaces. In this case, consider using the colorTextureSurfaceIsOpaque:withDepthAttachment: method instead.

+ (instancetype) colorTextureSurfaceWithPixelFormat:		(GLenum)	pixelFormat
withPixelType:		(GLenum)	pixelType
withDepthAttachment:		(id< CC3FramebufferAttachment >)	depthAttachment

Allocates and initializes an instance, sets the colorTexture property to a new blank 2D texture, and sets the depthAttachment property to the specified depth attachment.

To define the shape of the surface, you should either set the size property of the returned instance, or add it to a CC3SurfaceManager instance.

The empty colorTexture is configured with the specified pixel format and pixel type. See the notes for the CC3Texture pixelFormat and pixelType properties for the range of values permitted for these parameters.

The depthAttachment is used only during the rendering of content to the color texture. If you are creating many color texture surfaces of the same size, you can save memory by using the same depthAttachment for all such surfaces.

- (instancetype) init

Initializes this instance to zero size.

Implements CC3Identifiable.

- (instancetype) initAsColorTextureIsOpaque:

(BOOL)

isOpaque

Initializes this instance, sets the colorTexture property to a new blank 2D texture, and sets the depthAttachment property to a new renderbuffer configured with the standard GL_DEPTH_COMPONENT16 depth format.

To define the shape of the surface, you should either set the size property of the returned instance, or add it to a CC3SurfaceManager instance.

The isOpaque parameter indicates whether or not the colorTexture should support transparency, by including or excluding an alpha component in each pixel. The colorTexture will support transparency if isOpaque is set to NO, otherwise the texture will not support transparency. Specifically, the pixelFormat / pixelType properties of the texture are configured as follows:

• GL_RGB / GL_UNSIGNED_SHORT_5_6_5 if isOpaque is YES.
• GL_RGBA / GL_UNSIGNED_BYTE if isOpaque is NO.

Note that, with these texture formats, a texture that supports transparency requires twice the memory space of an opaque texture.

The depthAttachment is used only during the rendering of content to the color texture. If you are creating many color texture surfaces of the same size, you can save memory by using the same depthAttachment for all such surfaces. In this case, consider using the initAsColorTextureIsOpaque:withDepthAttachment: method instead.

- (instancetype) initAsColorTextureIsOpaque:		(BOOL)	isOpaque
withDepthAttachment:		(id< CC3FramebufferAttachment >)	depthAttachment

Initializes this instance, sets the colorTexture property to a new blank 2D texture, and sets the depthAttachment property to the specified depth attachment.

To define the shape of the surface, you should either set the size property of the returned instance, or add it to a CC3SurfaceManager instance.

The isOpaque parameter indicates whether or not the colorTexture should support transparency, by including or excluding an alpha component in each pixel. The colorTexture will support transparency if isOpaque is set to NO, otherwise the texture will not support transparency. Specifically, the pixelFormat / pixelType properties of the texture are configured as follows:

• GL_RGB / GL_UNSIGNED_SHORT_5_6_5 if isOpaque is YES.
• GL_RGBA / GL_UNSIGNED_BYTE if isOpaque is NO.

Note that, with these texture formats, a texture that supports transparency requires twice the memory space of an opaque texture.

The depthAttachment is used only during the rendering of content to the color texture. If you are creating many color texture surfaces of the same size, you can save memory by using the same depthAttachment for all such surfaces.

- (instancetype) initAsColorTextureIsOpaque:		(BOOL)	isOpaque
withDepthFormat:		(GLenum)	depthFormat

Initializes this instance, sets the colorTexture property to a new blank 2D texture, and sets the depthAttachment property to a new renderbuffer configured with the specified depth format.

To define the shape of the surface, you should either set the size property of the returned instance, or add it to a CC3SurfaceManager instance.

The depthFormat argument may be one of the following values:

• GL_DEPTH_COMPONENT16
• GL_DEPTH_COMPONENT24
• GL_DEPTH24_STENCIL8

The isOpaque parameter indicates whether or not the colorTexture should support transparency, by including or excluding an alpha component in each pixel. The colorTexture will support transparency if isOpaque is set to NO, otherwise the texture will not support transparency. Specifically, the pixelFormat / pixelType properties of the texture are configured as follows:

• GL_RGB / GL_UNSIGNED_SHORT_5_6_5 if isOpaque is YES.
• GL_RGBA / GL_UNSIGNED_BYTE if isOpaque is NO.

Note that, with these texture formats, a texture that supports transparency requires twice the memory space of an opaque texture.

The depthAttachment is used only during the rendering of content to the color texture. If you are creating many color texture surfaces of the same size, you can save memory by using the same depthAttachment for all such surfaces. In this case, consider using the initAsColorTextureIsOpaque:withDepthAttachment: method instead.

- (instancetype) initAsColorTextureWithPixelFormat:		(GLenum)	pixelFormat
withPixelType:		(GLenum)	pixelType
withDepthAttachment:		(id< CC3FramebufferAttachment >)	depthAttachment

Initializes this instance, sets the colorTexture property to a new blank 2D texture, and sets the depthAttachment property to the specified depth attachment.

To define the shape of the surface, you should either set the size property of the returned instance, or add it to a CC3SurfaceManager instance.

The empty colorTexture is configured with the specified pixel format and pixel type. See the notes for the CC3Texture pixelFormat and pixelType properties for the range of values permitted for these parameters.

The depthAttachment is used only during the rendering of content to the color texture. If you are creating many color texture surfaces of the same size, you can save memory by using the same depthAttachment for all such surfaces.

- (instancetype) initWithFramebufferID:

(GLuint)

fbID

Initializes this instance with the specified existing framebuffer ID.

You can use this method to create an instance to interact with an existin GL framebuffer that has been created outside Cocos3D.

The value of the isManagingGL property will be set to NO, indicating that this instance will not delete the framebuffer from the GL engine when this instance is deallocated. It is up to you to coordinate the lifespan of this instance and the GL framebuffer. Do not use this instance once you have deleted the framebuffer from the GL engine.

+ (instancetype) surface

Allocates and initializes an autoreleased instance with zero size.

+ (instancetype) surfaceWithFramebufferID:

(GLuint)

fbID

Allocates and initializes an instance with the specified existing framebuffer ID.

You can use this method to create an instance to interact with an existin GL framebuffer that has been created outside Cocos3D.

The value of the isManagingGL property of the returned instance will be set to NO, indicating that the instance will not delete the framebuffer from the GL engine when the returned instance is deallocated. It is up to you to coordinate the lifespan of the returned instance and the GL framebuffer. Do not use the returned instance once you have deleted the framebuffer from the GL engine.

- (void) validate

Validates that this framebuffer has a valid configuration in the GL engine, and raises an assertion exception if the configuration is not valid.

Does nothing if this framebuffer has no attachments or no size.

This method is automatically invoked when an attachment is added, or the size property is changed. Normally, the application never needs to invoke this method.

Property Documentation

- (id<CC3FramebufferAttachment>) colorAttachment

readwritenonatomicretain

The attachment to which color data is rendered.

Implementation of the CC3RenderSurface colorAttachment property. Framebuffer attachments must also support the CC3FramebufferAttachment protocol.

When this property is set:

• If the size property of this surface is not zero, and the attachment has no size, or has a size that is different than the size of this surface, the attachment is resized.
• If the size property of this surface is zero, and the attachment already has a size, the size of this framebuffer is set to that of the attachment.
• If the shouldBindGLAttachments property is set to YES, the existing attachment is unbound from this framebuffer in the GL engine, and the new attachment is bound to this framebuffer in the GL engine.
• The validate method is invoked to validate the framebuffer structure.

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.

- (CC3Texture*) colorTexture

readwritenonatomicretain

If color content is being rendered to a texture, this property can be used to access that texture.

This is a convenience property. Setting this property wraps the specified texture in a CC3TextureFramebufferAttachment instance and sets it into the colorAttachment property. Reading this property returns the texture within the CC3TextureFramebufferAttachment in the colorAttachment property. It is an error to attempt to read this property if the colorAttachment property does not contain an instance of CC3TextureFramebufferAttachment.

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

- (id<CC3FramebufferAttachment>) depthAttachment

readwritenonatomicretain

The attachment to which depth data is rendered.

Implementation of the CC3RenderSurface depthAttachment property. Framebuffer attachments must also support the CC3FramebufferAttachment protocol.

When this property is set:

• If the size property of this surface is not zero, and the attachment has no size, or has a size that is different than the size of this surface, the attachment is resized.
• If the size property of this surface is zero, and the attachment already has a size, the size of this framebuffer is set to that of the attachment.
• If the shouldBindGLAttachments property is set to YES, the existing attachment is unbound from this framebuffer in the GL engine, and the new attachment is bound to this framebuffer in the GL engine.
• If the depth format of the attachment includes a stencil component, the stencilAttachment property is set to the this attachment as well.
• The validate method is invoked to validate the framebuffer structure.

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 on different surfaces.

- (CC3Texture*) depthTexture

readwritenonatomicretain

If depth content is being rendered to a texture, this property can be used to access that texture.

This is a convenience property. Setting this property wraps the specified texture in a CC3TextureFramebufferAttachment instance and sets it into the depthAttachment property. Reading this property returns the texture within the CC3TextureFramebufferAttachment in the depthAttachment property. It is an error to attempt to read this property if the depthAttachment property does not contain an instance of CC3TextureFramebufferAttachment.

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

- (GLuint) framebufferID

readnonatomicassign

The ID used to identify the framebuffer to the GL engine.

If the value of this property is not explicitly set during instance initialization, then the first time this property is accessed a framebuffer will automatically be generated in the GL engine, and its ID set into this property.

- (BOOL) isFullCoverage

readnonatomicassign

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

Always returns YES.

- (BOOL) isManagingGL

readnonatomicassign

Returns whether the framebuffer in the GL engine is being managed by this instance.

If the value of this property is YES, this instance is managing the framebuffer in the GL engine, and when this instance is deallocated, the framebuffer will automatically be deleted from the GL engine.

If the value of this property is NO, this instance is NOT managing the framebuffer in the GL engine, and when this instance is deallocated, the framebuffer will NOT automatically be deleted from the GL engine.

If the value of this property is NO, indicating the lifespan of the GL framebuffer is not managed by this instance, it is up to you to coordinate the lifespan of this instance and the GL framebuffer. Do not use this instance once you have deleted the framebuffer from the GL engine.

If this instance is initialized with with a specific value for the framebufferID property, the value of this property will be NO, otherwise, the value of this property will be YES.

- (BOOL) isOnScreen

readwritenonatomicassign

Returns whether this framebuffer is an on-screen surface.

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

- (BOOL) shouldBindGLAttachments

readwritenonatomicassign

Indicates whether the attachments should be bound to this framebuffer within the GL engine when they are attached to this framebuffer.

If this property is set to YES, when an attachment is added to this framebuffer, within the GL engine, the existing attachment will be unbound from this framebuffer and the new attachment will be bound to this framebuffer. This is typically the desired behaviour when working with framebuffers and their attachments.

If this property is set to NO, when an attachment is added to this framebuffer, no changes are made within the GL engine. Setting this property to NO can be useful when you want to construct an instance that matches an existing GL framebuffer and its attachments, that may have been created outside of Cocos3D. A key example of this is the framebuffers and renderbuffers used to display the content of the view.

The initial value of this property is YES, indicating that any attachments added to this framebuffer will also be bound to this framebuffer within the GL engine.

This property affects the behaviour colorAttachment, depthAttachment, stencilAttachment, colorTexture and depthTexture properties.

This property affects different behaviour than the isManagingGL property, and does not depend on that property.

- (CC3IntSize) size

readwritenonatomicassign

The size of this framebuffer surface in pixels.

Changing the value of this property changes the size of each attachment, rebinds each attachment to this framebuffer, and invokes the validate method.

When creating a framebuffer instance, it is slightly more efficient to set the size of the framebuffer after all attachments have been added.

- (id<CC3FramebufferAttachment>) stencilAttachment

readwritenonatomicretain

The attachment to which stencil data is rendered.

Implementation of the CC3RenderSurface stencilAttachment property. Framebuffer attachments must also support the CC3FramebufferAttachment protocol.

When this property is set:

• If the size property of this surface is not zero, and the attachment has no size, or has a size that is different than the size of this surface, the attachment is resized.
• If the size property of this surface is zero, and the attachment already has a size, the size of this framebuffer is set to that of the attachment.
• If the shouldBindGLAttachments property is set to YES, the existing attachment is unbound from this framebuffer in the GL engine, and the new attachment is bound to this framebuffer in the GL engine.
• The validate method is invoked to validate the framebuffer structure.

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.

- (CC3Viewport) viewport

readnonatomicassign

Returns a viewport with zero origin and width and height matching the size property.

---

The documentation for this class was generated from the following file:

• CC3RenderSurfaces.h