CC3EnvironmentMapTexture Class Reference

#import <CC3RenderSurfaces.h>

Inheritance diagram for CC3EnvironmentMapTexture:

Instance Methods
(void)	- generateSnapshotOfScene:fromGlobalLocation:
(instancetype)	- initCubeWithColorPixelFormat:andColorPixelType:andDepthAttachment:
(instancetype)	- initCubeWithDepthAttachment:
(instancetype)	- initCubeWithSideLength:
(instancetype)	- initCubeWithSideLength:withColorPixelFormat:withColorPixelType:withDepthAttachment:
(instancetype)	- initCubeWithSideLength:withDepthAttachment:
(instancetype)	- initCubeWithSideLength:withDepthFormat:
Instance Methods inherited from CC3TextureCube
(void)	- loadCubeFace:fromCGImage:
(BOOL)	- loadCubeFace:fromFile:
(BOOL)	- loadFromFilePattern:
(BOOL)	- loadFromFilesPosX:negX:posY:negY:posZ:negZ:
(void)	- replacePixels:inCubeFace:withContent:
Instance Methods inherited from CC3Texture
(CCTexture *)	- __deprecated
(NSString *)	- constructorDescription
(void)	- drawWithVisitor:
(void)	- generateMipmap
(id)	- initCubeColoredForAxes
(id)	- initCubeFromFilePattern:
(id)	- initCubeFromFilesPosX:negX:posY:negY:posZ:negZ:
(id)	- initCubeWithPixelFormat:andPixelType:
(id)	- initCubeWithPixelFormat:withPixelType:
(id)	- initCubeWithSideLength:withPixelFormat:withPixelType:
(id)	- initCubeWithSize:andPixelFormat:andPixelType:
(id)	- initFromFile:
(id)	- initWithCCTexture:
(id)	- initWithCGImage:
(id)	- initWithPixelFormat:andPixelType:
(id)	- initWithPixelFormat:withPixelType:
(id)	- initWithSize:andPixelFormat:andPixelType:
(id)	- initWithSize:withColor:
(id)	- initWithSize:withPixelFormat:withPixelType:
(void)	- remove
(void)	- replacePixels:inTarget:withContent:
(void)	- resizeTo:
Instance Methods inherited from CC3Identifiable
(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)	- init
(id)	- initAtIndex:fromPODResource:
(void)	- initUserData
(id)	- initWithName:
(id)	- initWithTag:
(id)	- initWithTag:withName:
(GLuint)	- nextTag
(void)	- populateFrom:

Class Methods
(instancetype)	+ textureCubeWithColorPixelFormat:andColorPixelType:andDepthAttachment:
(instancetype)	+ textureCubeWithDepthAttachment:
(instancetype)	+ textureCubeWithSideLength:
(instancetype)	+ textureCubeWithSideLength:withColorPixelFormat:withColorPixelType:withDepthAttachment:
(instancetype)	+ textureCubeWithSideLength:withDepthAttachment:
(instancetype)	+ textureCubeWithSideLength:withDepthFormat:
Class Methods inherited from CC3TextureCube
(BOOL)	+ defaultShouldFlipHorizontallyOnLoad
(BOOL)	+ defaultShouldFlipVerticallyOnLoad
(void)	+ setDefaultShouldFlipHorizontallyOnLoad:
(void)	+ setDefaultShouldFlipVerticallyOnLoad:
Class Methods inherited from CC3Texture
(void)	+ addTexture:
(NSString *)	+ cachedTexturesDescription
(ccTexParams)	+ defaultTextureParameters
(CC3Texture *)	+ getTextureNamed:
(BOOL)	+ isPreloading
(void)	+ removeAllTextures
(void)	+ removeTexture:
(void)	+ removeTextureNamed:
(void)	+ setDefaultTextureParameters:
(void)	+ setIsPreloading:
(void)	+ setShouldCacheAssociatedCCTextures:
(void)	+ setShouldGenerateMipmaps:
(BOOL)	+ shouldCacheAssociatedCCTextures
(BOOL)	+ shouldGenerateMipmaps
(id)	+ textureCubeColoredForAxes
(id)	+ textureCubeFromFilePattern:
(id)	+ textureCubeFromFilesPosX:negX:posY:negY:posZ:negZ:
(id)	+ textureCubeWithPixelFormat:andPixelType:
(id)	+ textureCubeWithPixelFormat:withPixelType:
(id)	+ textureCubeWithSideLength:withPixelFormat:withPixelType:
(id)	+ textureCubeWithSize:andPixelFormat:andPixelType:
(id)	+ textureFromFile:
(NSString *)	+ textureNameFromFilePath:
(id)	+ textureWithCCTexture:
(id)	+ textureWithCGImage:
(id)	+ textureWithPixelFormat:andPixelType:
(id)	+ textureWithPixelFormat:withPixelType:
(id)	+ textureWithSize:andPixelFormat:andPixelType:
(id)	+ textureWithSize:withColor:
(id)	+ textureWithSize:withPixelFormat:withPixelType:
Class Methods inherited from CC3Identifiable
(GLint)	+ instanceCount
(void)	+ resetTagAllocation

Properties
GLfloat	numberOfFacesPerSnapshot
CC3GLFramebuffer *	renderSurface

Detailed Description

A texture that supports an environment map created by rendering the scene from the node's perspective in all six axis directions.

You can use this texture in any model object, wherever you use any cube-map texture. The generateSnapshotOfScene:fromGlobalLocation: method is used to capture the scene images to this texture. You can trigger this as often as you need, to keep the image current with the scene contents.

Method Documentation

- (void) generateSnapshotOfScene:		(CC3Scene *)	scene
fromGlobalLocation:		(CC3Vector)	location

Generates up to six faces of this cube-map, by creating a view of the specified scene, from the specified global location, once for each face of this cube-mapped texture.

The scene's drawSceneContentForEnvironmentMapWithVisitor: method is invoked to render the scene as an environment map, using the visitor in the scene's envMapDrawingVisitor property.

Typcally, you invoke this method on each frame rendering loop, and use the numberOfFacesPerSnapshot property to control how often the texture is updated.

- (instancetype) initCubeWithColorPixelFormat:		(GLenum)	colorFormat
andColorPixelType:		(GLenum)	colorType
andDepthAttachment:		(id< CC3FramebufferAttachment >)	__deprecated

Deprecated:

Use initCubeWithSideLength:withColorPixelFormat:withColorPixelType:withDepthAttachment: instead.

- (instancetype) initCubeWithDepthAttachment:

(id< CC3FramebufferAttachment >)

__deprecated

Deprecated:

Use initCubeWithSideLength:withDepthAttachment: instead.

- (instancetype) initCubeWithSideLength:

(GLuint)

sideLength

Initializes this instance with the specified side length, with the standard GL_RGBA/GL_UNSIGNED_BYTE pixelFormat/pixelType, and backed by a new depth buffer with the standard GL_DEPTH_COMPONENT16 depth format.

The sideLength argument indicates the length, in pixels, of each side of the texture.

The internal depth buffer is used only during the rendering of the environment to this texture. If you are creating many environmental textures of the same size, for different objects, you can save memory by using the same depth buffer for all such environment textures. In this case, consider using the initCubeWithSideLength:WithDepthAttachment: method instead.

- (instancetype) initCubeWithSideLength:		(GLuint)	sideLength
withColorPixelFormat:		(GLenum)	colorFormat
withColorPixelType:		(GLenum)	colorType
withDepthAttachment:		(id< CC3FramebufferAttachment >)	depthAttachment

Initializes this instance with the specified side length, with the specified pixel format and type, and backed by the specified depth attachment.

The sideLength argument indicates the length, in pixels, of each side of the texture.

The depthAttachment argument must not be nil.

Be aware that the possible combinations of color and depth pixel formats is quite limited with cube-mapped framebuffer attachments. If you have trouble finding a suitable combination, you can use the initWithDepthAttachment: method, which invokes this method with GL_RGBA as the colorFormat and GL_UNSIGNED_BYTE as the colorType.

The depth attachment is used only during the rendering of the environment to this texture. If you are creating many environmental textures of the same size, for different objects, you can save memory by using the same depth attachment for all such environment textures.

- (instancetype) initCubeWithSideLength:		(GLuint)	sideLength
withDepthAttachment:		(id< CC3FramebufferAttachment >)	depthAttachment

Initializes this instance with the specified side length, with the standard GL_RGBA/GL_UNSIGNED_BYTE pixelFormat/pixelType, and backed by the specified depth attachment.

The sideLength argument indicates the length, in pixels, of each side of the texture.

The depthAttachment argument must not be nil.

The depth attachment is used only during the rendering of the environment to this texture. If you are creating many environmental textures of the same size, for different objects, you can save memory by using the same depth attachment for all such environment textures.

- (instancetype) initCubeWithSideLength:		(GLuint)	sideLength
withDepthFormat:		(GLenum)	depthFormat

Initializes this instance with the specified side length, with the standard GL_RGBA/GL_UNSIGNED_BYTE pixelFormat/pixelType, and backed by a new depth buffer of the specified depth format.

The sideLength argument indicates the length, in pixels, of each side of the texture.

The depthFormat argument may be one of the following values:

• GL_DEPTH_COMPONENT16
• GL_DEPTH_COMPONENT24
• GL_DEPTH24_STENCIL8

The internal depth buffer is used only during the rendering of the environment to this texture. If you are creating many environmental textures of the same size, for different objects, you can save memory by using the same depth buffer for all such environment textures. In this case, consider using the initCubeWithSideLength:WithDepthAttachment: method instead.

+ (instancetype) textureCubeWithColorPixelFormat:		(GLenum)	colorFormat
andColorPixelType:		(GLenum)	colorType
andDepthAttachment:		(id< CC3FramebufferAttachment >)	__deprecated

Deprecated:

Use textureCubeWithSideLength:withColorPixelFormat:withColorPixelType:withDepthAttachment: instead.

+ (instancetype) textureCubeWithDepthAttachment:

(id< CC3FramebufferAttachment >)

__deprecated

Deprecated:

Use textureCubeWithSideLength:withDepthAttachment: instead.

+ (instancetype) textureCubeWithSideLength:

(GLuint)

sideLength

Allocates and initializes an autoreleased instance with the specified side length, with the standard GL_RGBA/GL_UNSIGNED_BYTE pixelFormat/pixelType, and backed by a new depth buffer with the standard GL_DEPTH_COMPONENT16 depth format.

The sideLength argument indicates the length, in pixels, of each side of the texture.

The internal depth buffer is used only during the rendering of the environment to this texture. If you are creating many environmental textures of the same size, for different objects, you can save memory by using the same depth buffer for all such environment textures. In this case, consider using the textureCubeWithSideLength:WithDepthAttachment: method instead.

+ (instancetype) textureCubeWithSideLength:		(GLuint)	sideLength
withColorPixelFormat:		(GLenum)	colorFormat
withColorPixelType:		(GLenum)	colorType
withDepthAttachment:		(id< CC3FramebufferAttachment >)	depthAttachment

Allocates and initializes an autoreleased instance with the specified side length, with the specified pixel format and type, and backed by the specified depth attachment.

The sideLength argument indicates the length, in pixels, of each side of the texture.

The depthAttachment argument must not be nil.

Be aware that the possible combinations of color and depth pixel formats is quite limited with cube-mapped framebuffer attachments. If you have trouble finding a suitable combination, you can use the initWithDepthAttachment: method, which invokes this method with GL_RGBA as the colorFormat and GL_UNSIGNED_BYTE as the colorType.

The depth attachment is used only during the rendering of the environment to this texture. If you are creating many environmental textures of the same size, for different objects, you can save memory by using the same depth attachment for all such environment textures.

+ (instancetype) textureCubeWithSideLength:		(GLuint)	sideLength
withDepthAttachment:		(id< CC3FramebufferAttachment >)	depthAttachment

Allocates and initializes an autoreleased instance with the specified side length, with the standard GL_RGBA/GL_UNSIGNED_BYTE pixelFormat/pixelType, and backed by the specified depth attachment.

The sideLength argument indicates the length, in pixels, of each side of the texture.

The depthAttachment argument must not be nil.

The depth attachment is used only during the rendering of the environment to this texture. If you are creating many environmental textures of the same size, for different objects, you can save memory by using the same depth attachment for all such environment textures.

+ (instancetype) textureCubeWithSideLength:		(GLuint)	sideLength
withDepthFormat:		(GLenum)	depthFormat

Allocates and initializes an autoreleased instance with the specified side length, with the standard GL_RGBA/GL_UNSIGNED_BYTE pixelFormat/pixelType, and backed by a new depth buffer of the specified depth format.

The sideLength argument indicates the length, in pixels, of each side of the texture.

The depthFormat argument may be one of the following values:

• GL_DEPTH_COMPONENT16
• GL_DEPTH_COMPONENT24
• GL_DEPTH24_STENCIL8

The internal depth buffer is used only during the rendering of the environment to this texture. If you are creating many environmental textures of the same size, for different objects, you can save memory by using the same depth buffer for all such environment textures. In this case, consider using the textureCubeWithSideLength:WithDepthAttachment: method instead.

Property Documentation

- (GLfloat) numberOfFacesPerSnapshot

readwritenonatomicassign

Indicates the number of faces of the cube-map that will be generated on each invocation of the generateSnapshotOfScene:fromGlobalLocation:withVisitor: method.

Generating each face in the cube-map requires rendering the scene from the perspective of a camera facing towards that face, and generating a full cube-map requires six separate scene renderings. Depending on the complexity of the scene, this can be quite costly.

However, in most situations, an environment map does not require high-fideility, and the workload can be spread over time by not generating all of the cube-map faces on every snapshot.

You can use this property to control the number of cube-map faces that will be generated each time a snapshot is taken using the generateSnapshotOfScene:fromGlobalLocation:withVisitor: method.

The maximum value of this property is 6, indicating that all six faces should be generated each time the generateSnapshotOfScene:fromGlobalLocation:withVisitor: method is invoked. Setting this property to a smaller value will cause fewer faces to be generated on each snapshot, thereby spreading the workload out over time. On each invocation, a different set of faces will be generated, in a cycle, ensuring that each face will be generated at some point.

As an example, setting this value to 2 will cause only 2 of the 6 faces of the cube-map to be generated each time the generateSnapshotOfScene:fromGlobalLocation:withVisitor: is invoked. Therefore, it would take 3 snapshot invocations to generate all 6 sides of the cube-map.

You can even set this property to a fractional value less than one to spread the updating of the faces out even further. For example, if the value of this property is set to 0.25, the generateSnapshotOfScene:fromGlobalLocation:withVisitor: method will only generate one face of this cube-map texture every fourth time it is invoked. On the other three invocations, the generateSnapshotOfScene:fromGlobalLocation:withVisitor: method will do nothing. Therefore, with the value of this property set to 0.25, it would take 24 snapshot invocations to generate all 6 sides of this cube-map.

The initial value of this property is 1, indicating that one face of the cube-map will be generated on each invocation of the generateSnapshotOfScene:fromGlobalLocation:withVisitor: method. With this value, it will take six invocations to generate all six sides of the cube-map.

- (CC3GLFramebuffer*) renderSurface

readnonatomicretain

Returns the surface to which the environment will be rendered.

---

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

• CC3RenderSurfaces.h