CC3Light Class Reference

#import <CC3Light.h>

Inheritance diagram for CC3Light:

Instance Methods
(void)	- addShadow:
(void)	- drawShadowsWithVisitor:
(id)	- init
(id)	- initWithLightIndex:
(id)	- initWithName:
(id)	- initWithName:withLightIndex:
(id)	- initWithTag:
(id)	- initWithTag:withLightIndex:
(id)	- initWithTag:withName:
(id)	- initWithTag:withName:withLightIndex:
(void)	- removeShadow:
(void)	- turnOffWithVisitor:
(void)	- turnOnWithVisitor:
(void)	- updateRelativeIntensityFrom:
(void)	- updateShadows
Instance Methods inherited from CC3Node
(void)	- __deprecated
(void)	- __deprecated
(void)	- __deprecated
(void)	- __deprecated
(void)	- __deprecated
(void)	- __deprecated
(void)	- __deprecated
(void)	- __deprecated
(void)	- __deprecated
(void)	- __deprecated
(id)	- __deprecated
(void)	- __deprecated
(void)	- addAndLocalizeChild:
(void)	- addAnimation:asTrack:
(GLuint)	- addAnimationFrom:to:
(void)	- addAnimationFrom:to:asTrack:
(GLuint)	- addAnimationFrom:to:ofBaseTrack:
(void)	- addAnimationFrom:to:ofBaseTrack:asTrack:
(GLuint)	- addAnimationFromCAFFile:
(void)	- addAnimationFromCAFFile:asTrack:
(GLuint)	- addAnimationFromCAFFile:linkedToCSFFile:
(void)	- addAnimationFromCAFFile:linkedToCSFFile:asTrack:
(GLuint)	- addAnimationFromFrame:toFrame:
(void)	- addAnimationFromFrame:toFrame:asTrack:
(GLuint)	- addAnimationFromFrame:toFrame:ofBaseTrack:
(void)	- addAnimationFromFrame:toFrame:ofBaseTrack:asTrack:
(GLuint)	- addAnimationFromPODFile:
(void)	- addAnimationFromPODFile:asTrack:
(GLuint)	- addAnimationInResource:
(void)	- addAnimationInResource:asTrack:
(void)	- addAnimationState:
(void)	- addAxesDirectionMarkers
(void)	- addChild:
(void)	- addContentFromPODFile:
(void)	- addContentFromPODFile:withName:
(void)	- addContentFromPODResourceFile:
(void)	- addContentFromPODResourceFile:withName:
(void)	- addDirectionMarker
(void)	- addDirectionMarkerColored:inDirection:
(void)	- addShadowVolumes
(void)	- addShadowVolumesForLight:
(void)	- addTexture:
(void)	- addTransformListener:
(void)	- alignInvertedTextures
(void)	- alignTextures
(GLfloat)	- animationBlendingWeightOnTrack:
(CCTime)	- animationTimeOnTrack:
(NSString *)	- appendStructureDescriptionTo:withIndent:
(void)	- applyEffectNamed:inPFXResourceFile:
(void)	- applyEffectNamed:inPFXResourceNamed:
(void)	- applyLocalTransformsTo:
(CC3Node *)	- asBumpMapLightTrackingWrapper
(CC3Node *)	- asCameraTrackingWrapper
(CC3Node *)	- asOrientingWrapper
(CC3Node *)	- asTrackingWrapper
(void)	- bindRestPose
(CC3Box)	- boundingBoxRelativeTo:
(void)	- buildTransformMatrixWithVisitor:
(void)	- checkDrawingOrder
(void)	- cleanupActions
(CC3Node *)	- closestNodeIntersectedByGlobalRay:
(BOOL)	- containsAnimationOnTrack:
(id)	- copy
(id)	- copyWithName:
(void)	- createBoundingVolume
(void)	- createBoundingVolumes
(void)	- createGLBuffers
(void)	- createSkinnedBoundingVolumes
(CC3NodeBoundingVolume *)	- defaultBoundingVolume
(void)	- deleteBoundingVolumes
(void)	- deleteGLBuffers
(NSString *)	- describeAnimationStateForFrames:
(NSString *)	- describeAnimationStateForFrames:fromTime:toTime:
(NSString *)	- describeCurrentAnimationState
(void)	- disableAllAnimation
(void)	- disableAllAnimationOnTrack:
(void)	- disableAllLocationAnimation
(void)	- disableAllQuaternionAnimation
(void)	- disableAllScaleAnimation
(void)	- disableAnimation
(void)	- disableAnimationOnTrack:
(void)	- disableLocationAnimation
(void)	- disableQuaternionAnimation
(void)	- disableScaleAnimation
(BOOL)	- doesIntersectBoundingVolume:
(BOOL)	- doesIntersectFrustum:
(BOOL)	- doesIntersectGlobalRay:
(BOOL)	- doesIntersectNode:
(void)	- doNotBufferVertexBitangents
(void)	- doNotBufferVertexBoneIndices
(void)	- doNotBufferVertexBoneWeights
(void)	- doNotBufferVertexColors
(void)	- doNotBufferVertexContent
(void)	- doNotBufferVertexIndices
(void)	- doNotBufferVertexLocations
(void)	- doNotBufferVertexNormals
(void)	- doNotBufferVertexPointSizes
(void)	- doNotBufferVertexTangents
(void)	- doNotBufferVertexTextureCoordinates
(void)	- drawWithVisitor:
(void)	- enableAllAnimation
(void)	- enableAllAnimationOnTrack:
(void)	- enableAllLocationAnimation
(void)	- enableAllQuaternionAnimation
(void)	- enableAllScaleAnimation
(void)	- enableAnimation
(void)	- enableAnimationOnTrack:
(void)	- enableLocationAnimation
(void)	- enableQuaternionAnimation
(void)	- enableScaleAnimation
(void)	- ensureRigidSkeleton
(void)	- establishAnimationFrameAt:
(void)	- establishAnimationFrameAt:onTrack:
(NSArray *)	- flatten
(void)	- flattenInto:
(void)	- flipNormals
(void)	- flipTexturesHorizontally
(void)	- flipTexturesVertically
(void)	- freezeAllInanimatesOnTrack:
(void)	- freezeIfInanimateOnTrack:
(CCAction *)	- getActionByTag:
(CC3NodeAnimation *)	- getAnimationOnTrack:
(CC3NodeAnimationState *)	- getAnimationStateOnTrack:
(CC3MeshNode *)	- getMeshNodeNamed:
(CC3Node *)	- getNodeNamed:
(CC3Node *)	- getNodeTagged:
(CC3ShadowVolumeMeshNode *)	- getShadowVolumeForLight:
(CC3Vector)	- globalLocationOfGlobalRayIntesection:
(CC3Matrix *)	- globalRotationMatrix
(BOOL)	- hasShadowVolumes
(BOOL)	- hasShadowVolumesForLight:
(void)	- hide
(BOOL)	- isAnimationEnabledOnTrack:
(BOOL)	- isDescendantOf:
(BOOL)	- isShadowVisible
(void)	- linkToPODNodes:
(CC3Vector)	- locationOfGlobalRayIntesection:
(void)	- markAnimationDirty
(void)	- markBoundingVolumeDirty
(void)	- markTransformDirty
(PODStructPtr)	- nodePODStructAtIndex:fromPODResource:
(CC3NodePuncturingVisitor *)	- nodesIntersectedByGlobalRay:
(void)	- nodeWasDestroyed:
(void)	- nodeWasTransformed:
(NSInteger)	- numberOfRunningActions
(void)	- pauseAllActions
(void)	- prewarmForShadowVolumes
(void)	- reattachBonesFrom:
(void)	- releaseRedundantContent
(void)	- remove
(void)	- removeAllChildren
(void)	- removeAllDirectionMarkers
(void)	- removeAllTransformListeners
(void)	- removeAnimation:
(void)	- removeAnimationState:
(void)	- removeAnimationTrack:
(void)	- removeChild:
(void)	- removeShaders
(void)	- removeShadowVolumes
(void)	- removeShadowVolumesForLight:
(void)	- removeTransformListener:
(void)	- resumeAllActions
(void)	- retainVertexBitangents
(void)	- retainVertexBoneIndices
(void)	- retainVertexBoneWeights
(void)	- retainVertexColors
(void)	- retainVertexContent
(void)	- retainVertexIndices
(void)	- retainVertexLocations
(void)	- retainVertexNormals
(void)	- retainVertexPointSizes
(void)	- retainVertexTangents
(void)	- retainVertexTextureCoordinates
(void)	- rotateBy:
(void)	- rotateByAngle:aroundAxis:
(void)	- rotateByAngle:aroundAxis:atLocation:
(void)	- rotateByQuaternion:
(CCAction *)	- runAction:
(CCAction *)	- runAction:withTag:
(void)	- selectShaders
(void)	- setAnimationBlendingWeight:onTrack:
(void)	- setSkeletalBoundingVolume:
(void)	- show
(void)	- stopAction:
(void)	- stopActionByTag:
(void)	- stopAllActions
(void)	- touchDisableAll
(void)	- touchEnableAll
(void)	- trackTargetWithVisitor:
(void)	- transformAndDrawWithVisitor:
(void)	- translateBy:
(void)	- updateAfterTransform:
(void)	- updateBeforeTransform:
(void)	- wasAdded
(void)	- wasRemoved
Instance Methods inherited from CC3Identifiable
(id)	- copyAsClass:
(void)	- copyUserDataFrom:
(id)	- copyWithName:asClass:
(id)	- copyWithZone:withName:
(id)	- copyWithZone:withName:asClass:
(BOOL)	- deriveNameFrom:
(BOOL)	- deriveNameFrom:usingSuffix:
(NSString *)	- fullDescription
(id)	- initAtIndex:fromPODResource:
(void)	- initUserData
(GLuint)	- nextTag
(void)	- populateFrom:

Class Methods
(void)	+ disableReservedLightsWithVisitor:
(GLuint)	+ lightCount
(GLuint)	+ lightPoolStartIndex
(id)	+ lightWithLightIndex:
(id)	+ lightWithName:withLightIndex:
(id)	+ lightWithTag:withLightIndex:
(id)	+ lightWithTag:withName:withLightIndex:
(void)	+ setLightPoolStartIndex:
Class Methods inherited from CC3Node
(GLfloat)	+ __deprecated
(CGFloat)	+ descriptorFontSize
(ccColor4F)	+ directionMarkerColor
(id)	+ node
(id)	+ nodeAtIndex:fromPODResource:
(id)	+ nodeWithName:
(id)	+ nodeWithTag:
(id)	+ nodeWithTag:withName:
(void)	+ setDefaultScaleTolerance:
(void)	+ setDescriptorFontSize:
(void)	+ setDirectionMarkerColor:
(void)	+ setWireframeBoxColor:
(ccColor4F)	+ wireframeBoxColor
Class Methods inherited from CC3Identifiable
(GLint)	+ instanceCount
(void)	+ resetTagAllocation

Properties
CC3AttenuationCoefficients attenuationCoefficients	__deprecated
ccColor4F	ambientColor
CC3AttenuationCoefficients	attenuation
CC3CameraShadowVolume *	cameraShadowVolume
ccColor4F	diffuseColor
CC3Vector	forwardDirection
CC3Vector4	globalHomogeneousPosition
BOOL	hasShadows
BOOL	isDirectionalOnly
BOOL	isLight
GLuint	lightIndex
CC3ShadowCastingVolume *	shadowCastingVolume
GLfloat	shadowIntensityFactor
NSArray *	shadows
BOOL	shouldCastShadowsWhenInvisible
BOOL	shouldCopyLightIndex
ccColor4F	specularColor
GLfloat	spotCutoffAngle
GLfloat	spotExponent
CC3StencilledShadowPainterNode *	stencilledShadowPainter
Properties inherited from CC3Node
CC3Vector sceneUpDirection	__deprecated
CC3Vector worldUpDirection	__deprecated
GLfloat scaleTolerance	__deprecated
CC3TargettingConstraint axisRestriction	__deprecated
CC3Vector globalLightLocation	__deprecated
CC3Matrix *transformMatrix	__deprecated
CC3Matrix *transformMatrixInverted	__deprecated
CC3Node *dirtiestAncestor	__deprecated
CC3Matrix *parentGlobalTransformMatrix	__deprecated
CC3Matrix *parentTransformMatrix	__deprecated
CC3Scene *world	__deprecated
BOOL shouldCleanupActionsWhenRemoved	__deprecated
BOOL shouldCleanupWhenRemoved	__deprecated
CC3Camera *	activeCamera
ccColor4F	ambientColor
CC3NodeAnimation *	animation
CC3NodeAnimationState *	animationState
ccBlendFunc	blendFunc
CC3Box	boundingBox
CC3NodeBoundingVolume *	boundingVolume
GLfloat	boundingVolumePadding
GLfloat	cameraDistanceProduct
CC3Vector	centerOfGeometry
NSArray *	children
CCColorRef	color
BOOL	containsAnimation
GLfloat	decalOffsetFactor
GLfloat	decalOffsetUnits
GLenum	depthFunction
CC3NodeDescriptor *	descriptorNode
ccColor4F	diffuseColor
NSArray *	directionMarkers
ccColor4F	emissionColor
BOOL	expectsVerticallyFlippedTextures
CC3Vector	forwardDirection
CC3Box	globalBoundingBox
CC3Vector	globalCenterOfGeometry
CC3Vector	globalForwardDirection
CC3Vector4	globalHomogeneousPosition
CC3Vector4	globalLightPosition
CC3Vector	globalLocation
CC3Vector	globalRightDirection
CC3Vector	globalRotation
CC3Vector	globalScale
CC3Matrix *	globalTransformMatrix
CC3Matrix *	globalTransformMatrixInverted
CC3Vector	globalUpDirection
BOOL	hasLocalContent
BOOL	hasSoftBodyContent
BOOL	hasTarget
BOOL	isAnimationEnabled
BOOL	isBasePODNode
BOOL	isBillboard
BOOL	isCamera
BOOL	isLight
BOOL	isLightProbe
BOOL	isMeshNode
BOOL	isOpaque
BOOL	isRunning
BOOL	isScene
BOOL	isShadowVolume
BOOL	isTouchable
BOOL	isTrackingForBumpMapping
BOOL	isTransformDirty
BOOL	isTransformRigid
BOOL	isUniformlyScaledGlobally
BOOL	isUniformlyScaledLocally
GLenum	lineSmoothingHint
GLfloat	lineWidth
CC3Matrix *	localTransformMatrix
CC3Vector	location
CC3NormalScaling	normalScalingMethod
CCOpacity	opacity
CC3Node *	parent
CC3PerformanceStatistics *	performanceStatistics
GLint	podContentIndex
GLint	podParentIndex
GLint	podTargetIndex
CC3Vector	projectedLocation
CGPoint	projectedPosition
CC3Quaternion	quaternion
CC3Vector	referenceUpDirection
GLfloat	reflectivity
const char *	renderStreamGroupMarker
CC3Vector	rightDirection
CC3Node *	rootAncestor
CC3Vector	rotation
GLfloat	rotationAngle
CC3Vector	rotationAxis
CC3Rotator *	rotator
CC3Vector	scale
CC3Scene *	scene
CC3ShaderContext *	shaderContext
CC3ShaderProgram *	shaderProgram
GLfloat	shadowExpansionLimitFactor
GLushort	shadowLagCount
GLushort	shadowLagFactor
GLfloat	shadowOffsetFactor
GLfloat	shadowOffsetUnits
NSArray *	shadowVolumes
GLfloat	shadowVolumeVertexOffsetFactor
GLfloat	shininess
BOOL	shouldAddShadowVolumeEndCapsOnlyWhenNeeded
BOOL	shouldAllowTouchableWhenInvisible
BOOL	shouldApplyOpacityAndColorToMeshContent
BOOL	shouldAutoremoveWhenEmpty
BOOL	shouldAutotargetCamera
BOOL	shouldBlendAtFullOpacity
BOOL	shouldCacheFaces
BOOL	shouldCastShadows
BOOL	shouldCastShadowsWhenInvisible
BOOL	shouldCullBackFaces
BOOL	shouldCullFrontFaces
BOOL	shouldDisableDepthMask
BOOL	shouldDisableDepthTest
BOOL	shouldDrawAllBoundingVolumes
BOOL	shouldDrawAllDescriptors
BOOL	shouldDrawAllLocalContentWireframeBoxes
BOOL	shouldDrawAllWireframeBoxes
BOOL	shouldDrawBoundingVolume
BOOL	shouldDrawDescriptor
BOOL	shouldDrawInClipSpace
BOOL	shouldDrawWireframeBox
BOOL	shouldIgnoreRayIntersection
BOOL	shouldInheritTouchability
BOOL	shouldLogIntersectionMisses
BOOL	shouldLogIntersections
BOOL	shouldShadowBackFaces
BOOL	shouldShadowFrontFaces
BOOL	shouldSmoothLines
BOOL	shouldStopActionsWhenRemoved
BOOL	shouldTrackTarget
BOOL	shouldUseClockwiseFrontFaceWinding
BOOL	shouldUseFixedBoundingVolume
BOOL	shouldUseLighting
BOOL	shouldUseLightProbes
BOOL	shouldUseSmoothShading
CC3Vector	skeletalScale
CC3SoftBodyNode *	softBodyNode
ccColor4F	specularColor
NSString *	structureDescription
CC3Node *	target
CC3Vector	targetLocation
CC3TargettingConstraint	targettingConstraint
CC3Texture *	texture
CC3Node *	touchableNode
BOOL	touchEnabled
NSSet *	transformListeners
GLfloat	uniformScale
CC3Vector	upDirection
BOOL	visible
CC3WireframeBoundingBoxNode *	wireframeBoxNode
GLint	zOrder
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

Detailed Description

CC3Light represents the light in the 3D scene.

CC3Light is a type of CC3Node, and can therefore participate in a structural node assembly. An instance can be the child of another node, and the light itself can have child nodes. For example, a light can be mounted on a boom object or camera, and will move along with the parent node.

CC3Light can be pointed so that it shines in a particular direction, or can be made to track a target node as that node moves.

To turn a CC3Light on or off, set the visible property.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

Lights in different scenes (different instances of CC3Scene) can have the same GL lightIndex value. Applications that make use of multiple CC3Scenes, either as a sequence of scenes, or as multiple scenes (and multiple CC3Layers) displayed on the screen at once, can reuse a light index across the scenes. The shouldCopyLightIndex property can be used to help copy lights across scenes.

If the application uses lights in the 2D scene as well, the indexes of those lights can be reserved by invoking the class method setLightPoolStartIndex:. Light indexes reserved for use by the 2D scene will not be used by the 3D scene.

Method Documentation

- (void) addShadow:

(id< CC3ShadowProtocol >)

shadowNode

Adds a shadow to the shadows cast by this light.

This method is invoked automatically when a shadow is added to a mesh node. Usually, the application never needs to invoke this method directly.

+ (void) disableReservedLightsWithVisitor:

(CC3NodeDrawingVisitor *)

visitor

Disables the lights that were reserved for the 2D scene by setLightPoolStartIndex:.

This method is invoked automatically by CC3Scene near the beginning of each frame drawing cycle. Usually, the application never needs to invoke this method directly.

- (void) drawShadowsWithVisitor:

(CC3NodeDrawingVisitor *)

visitor

Draws any shadows cast by this light.

- (id) init

Initializes this unnamed instance with an automatically generated unique tag value.

The tag value will be generated automatically via the method nextTag.

The lightIndex property will be set to the next available GL light index. This method will return nil if all GL light indexes have been consumed.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

Implements CC3Identifiable.

- (id) initWithLightIndex:

(GLuint)

ltIndx

Initializes this unnamed instance with the specified GL light index, and an automatically generated unique tag value.

The tag value will be generated automatically via the method nextTag.

If multiple lights are used to illumniate a scene (a CC3Scene instance), each light must have its own GL light index. Do not assign the same light index to more than one light in a scene.

This method will return nil if the specified light index is not less than the maximum number of lights available.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

- (id) initWithName:

(NSString *)

aName

Initializes this instance with the specified name and an automatically generated unique tag value.

The tag value will be generated automatically via the method nextTag.

The lightIndex property will be set to the next available GL light index. This method will return nil if all GL light indexes have been consumed.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

Implements CC3Identifiable.

- (id) initWithName:		(NSString *)	aName
withLightIndex:		(GLuint)	ltIndx

Initializes this instance with the specified GL light index, the specified name, and an automatically generated unique tag value.

The tag value will be generated automatically via the method nextTag.

If multiple lights are used to illumniate a scene (a CC3Scene instance), each light must have its own GL light index. Do not assign the same light index to more than one light in a scene.

This method will return nil if the specified light index is not less than the maximum number of lights available.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

- (id) initWithTag:

(GLuint)

aTag

Initializes this unnamed instance with the specified tag.

The lightIndex property will be set to the next available GL light index. This method will return nil if all GL light indexes have been consumed.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

Implements CC3Identifiable.

- (id) initWithTag:		(GLuint)	aTag
withLightIndex:		(GLuint)	ltIndx

Initializes this unnamed instance with the specified GL light index, and the specified tag.

If multiple lights are used to illumniate a scene (a CC3Scene instance), each light must have its own GL light index. Do not assign the same light index to more than one light in a scene.

This method will return nil if the specified light index is not less than the maximum number of lights available.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

- (id) initWithTag:		(GLuint)	aTag
withName:		(NSString *)	aName

Initializes this instance with the specified tag and name.

The lightIndex property will be set to the next available GL light index. This method will return nil if all GL light indexes have been consumed.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

Implements CC3Identifiable.

- (id) initWithTag:		(GLuint)	aTag
withName:		(NSString *)	aName
withLightIndex:		(GLuint)	ltIndx

Initializes this instance with the specified GL light index, the specified name, and the specified tag.

If multiple lights are used to illumniate a scene (a CC3Scene instance), each light must have its own GL light index. Do not assign the same light index to more than one light in a scene.

This method will return nil if the specified light index is not less than the maximum number of lights available.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

+ (GLuint) lightCount

Returns the number of lights that have already been instantiated (and not yet deallocated).

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

+ (GLuint) lightPoolStartIndex

Indicates the smallest index number to assign to a 3D light.

See the description of the setLightPoolStartIndex: method for more information on this value.

+ (id) lightWithLightIndex:

(GLuint)

ltIndx

Allocates and initializes an autoreleased unnamed instance with the specified GL light index, and an automatically generated unique tag value.

The tag value will be generated automatically via the method nextTag.

If multiple lights are used to illumniate a scene (a CC3Scene instance), each light must have its own GL light index. Do not assign the same light index to more than one light in a scene.

This method will return nil if the specified light index is not less than the maximum number of lights available.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

+ (id) lightWithName:		(NSString *)	aName
withLightIndex:		(GLuint)	ltIndx

Allocates and initializes an autoreleased instance with the specified GL light index, the specified name, and an automatically generated unique tag value.

The tag value will be generated automatically via the method nextTag.

If multiple lights are used to illumniate a scene (a CC3Scene instance), each light must have its own GL light index. Do not assign the same light index to more than one light in a scene.

This method will return nil if the specified light index is not less than the maximum number of lights available.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

+ (id) lightWithTag:		(GLuint)	aTag
withLightIndex:		(GLuint)	ltIndx

Allocates and initializes an autoreleased unnamed instance with the specified GL light index, and the specified tag.

If multiple lights are used to illumniate a scene (a CC3Scene instance), each light must have its own GL light index. Do not assign the same light index to more than one light in a scene.

This method will return nil if the specified light index is not less than the maximum number of lights available.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

+ (id) lightWithTag:		(GLuint)	aTag
withName:		(NSString *)	aName
withLightIndex:		(GLuint)	ltIndx

Allocates and initializes an autoreleased instance with the specified GL light index, the specified name, and the specified tag.

If multiple lights are used to illumniate a scene (a CC3Scene instance), each light must have its own GL light index. Do not assign the same light index to more than one light in a scene.

This method will return nil if the specified light index is not less than the maximum number of lights available.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

- (void) removeShadow:

(id< CC3ShadowProtocol >)

shadowNode

Removes a shadow from the shadows cast by this light.

+ (void) setLightPoolStartIndex:

(GLuint)

newStartIndex

Sets the smallest index number to assign to a 3D light.

This value should be between zero inclusive and CC3OpenGL.sharedGL.maxNumberOfLights exclusive.

If the 2D scene uses lights, setting this value to a number above zero will reserve the indexes below this number for the 2D scene and those indexes will not be used in lights in the 3D scene.

This value defaults to zero. If your application requires light indexes to be reserved and not assigned in the 3D scene, set this value.

- (void) turnOffWithVisitor:

(CC3NodeDrawingVisitor *)

visitor

Turns this light off on by disabling this light in the GL engine.

This method is invoked automatically by CC3Scene at the end of each frame drawing cycle. Usually, the application never needs to invoke this method directly.

- (void) turnOnWithVisitor:

(CC3NodeDrawingVisitor *)

visitor

If this light is visible, turns it on by enabling this light in the GL engine, and then applies the properties of this light to the GL engine.

This method is invoked automatically by CC3Scene near the beginning of each frame drawing cycle. Usually, the application never needs to invoke this method directly.

- (void) updateRelativeIntensityFrom:

(ccColor4F)

totalLight

Updates the relative intensity of this light, as compared to the specified total scene illumination.

Certain characteristics, such as shadow intensities, depend on the relative intensity of this light, relative to the total intensity of all lights in the scene.

Sets the intensity of shadows cast by this light by comparing the intensity of the diffuse component of this light against the total ambient and diffuse illumination from all lights, to get a measure of the fraction of total scene illumination that is contributed by this light.

Using this technique, the presence of multiple lights, or strong ambient light, will serve to lighten the shadows cast by any single light. A single light with no ambient light will cast completely black opaque shadows.

That calculated fraction is then multiplied by the value of the shadowIntensityFactor property to determine the intensity (opacity) of the shadows cast by this light. The shadowIntensityFactor increases flexibility by allowing the shadow intensity to be adjusted relative to the calculated value to improve realisim.

This method is invoked automatically when any of the the ambientColor, diffuseColor, visible, or shadowIntensityFactor properties of any light in the scene is changed, or if the ambientLight property of the CC3Scene is changed.

- (void) updateShadows

Update the shadows that are cast by this light.

Property Documentation

- (CC3AttenuationCoefficients attenuationCoefficients) __deprecated

readwritenonatomicassign

Deprecated:

Property renamed to attenuation

- (ccColor4F) ambientColor

readwritenonatomicassign

The ambient color of this light.

Initially set to kCC3DefaultLightColorAmbient.

- (CC3AttenuationCoefficients) attenuation

readwritenonatomicassign

The coefficients of the attenuation function that reduces the intensity of the light based on the distance from the light source.

The intensity of the light is attenuated according to the formula 1/sqrt(a + b * r + c * r * r), where r is the radial distance from the light source, and a, b and c are the coefficients from this property.

The initial value of this property is kCC3DefaultLightAttenuationCoefficients.

- (CC3CameraShadowVolume*) cameraShadowVolume

readwritenonatomicretain

A specialized bounding volume that encloses a pyramidal volume between the view plane (near clipping plane) of the camera, and this light.

Nodes that intersect this volume will cast a shadow from that light across the camera. The shadow volume of nodes that cast a shadow across the camera view plane are rendered differently than shadow volumes for nodes that do not cast their shadow across the camera.

If not set directly, this property is lazily created when a shadow is added. If no shadow has been added, this property will return nil.

- (ccColor4F) diffuseColor

readwritenonatomicassign

The diffuse color of this light.

Initially set to kCC3DefaultLightColorDiffuse.

- (CC3Vector) forwardDirection

readwritenonatomicassign

The direction in which this light is pointing, relative to the coordinate system of this light, which is relative to the parent's rotation.

The initial value of this property is kCC3VectorUnitZNegative, pointing down the negative Z-axis in the local coordinate system of this light. When this light is rotated, the original negative-Z axis of the camera's local coordinate system will point in this direction.

This orientation is opposite that for most other nodes, whose forwardDirection property orients the positve Z-axis of the node's coordinate system in the stated direction. This arrangement allows unrotated nodes to face the light in a natural stance, and allows the unrotated light to face the nodes.

See further notes in the notes for this property in the CC3Node class.

- (CC3Vector4) globalHomogeneousPosition

readnonatomicassign

The position of this light in a global 4D homogeneous coordinate space.

The X, Y & Z components of the returned 4D vector are the same as those in the globalLocation property. The W-component will be zero if the isDirectionalOnly property is set to YES, indicating that this position represents a direction. The W-component will be one if the isDirectionalOnly property is set to NO, indicating that this position represents a specific location.

- (BOOL) hasShadows

readnonatomicassign

Returns whether this light is casting shadows.

It is if any shadows have been added and not yet removed.

- (BOOL) isDirectionalOnly

readwritenonatomicassign

Indicates whether this light is directional and without a specified location.

Directional-only light is good for modeling sunlight, or other flat overhead lighting. Positional lighting is good for point-source lights like a single bulb, flare, etc.

The value of this property impacts features like attenuation, and the angle of reflection to the user view. A directional-only light is not subject to attenuation over distance, where an absolutely located light is. In addition, directional-only light bounces off a flat surface at a single angle, whereas the angle for a point-source light also depends on the location of the camera.

The value of this property also impacts performance. Because positional light involves significantly more calculations within the GL engine, setting this property to YES (the initial value) will improve lighting performance. You should only set this property to NO if you need to make use of the positional features described above.

The initial value is YES, indicating directional-only lighting.

- (BOOL) isLight

readnonatomicassign

Returns whether this node is a light.

Returns YES.

- (GLuint) lightIndex

readnonatomicassign

The index of this light to identify it to the GL engine.

This is automatically assigned during instance initialization. The value of lightIndex will be between zero and one less than the maximium number of available lights, inclusive.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

- (CC3ShadowCastingVolume*) shadowCastingVolume

readwritenonatomicretain

A specialized bounding volume that encloses a volume that includes the camera frustum plus the space between the camera frustum and this light.

Nodes that intersect this volume will cast a shadow from this light into the camera frustum, and that shadow will be visible. Shadows cast by nodes outside this volume will not intersect the frustum and will not be visible.

This volume is used to cull the updating and drawing of shadows that will not be visible, to enhance performance.

If not set directly, this property is lazily created when a shadow is added. If no shadow has been added, this property will return nil.

- (GLfloat) shadowIntensityFactor

readwritenonatomicassign

This property is used to adjust the shadow intensity as calculated when the updateRelativeIntensityFrom: method is invoked.

This property increases flexibility by allowing the shadow intensity to be ajusted relative to that calculated value to improve realisim.

The intensity of shadows cast by this light is calculated by comparing the intensity of the diffuse component of this light against the total ambient and diffuse illumination from all lights, to get a measure of the fraction of total scene illumination that is contributed by this light.

Using this technique, the presence of multiple lights, or strong ambient light, will serve to lighten the shadows cast by any single light. A single light with no ambient light will cast completely opaque, black shadows.

That fraction, representing the fraction of overall light coming from this light, is then multiplied by the value of this property to determine the intensity (opacity) of the shadows cast by this light.

This property must be zero or a positive value. A value between zero and one will serve to to lighten the shadow, relative to the shadow intensity (opacity) calculated from the relative intensity of this light, and a value of greater than one will serve to darken the shadow, relative to that calculated intensity.

The initial value of this property is one, meaning that the shadow intensity calculated from the relative intensity of this light will be used without adjustment.

- (NSArray*) shadows

readnonatomicretain

The shadows cast by this light.

If this light is casting no shadows, this property will be nil.

- (BOOL) shouldCastShadowsWhenInvisible

readwritenonatomicassign

Indicates whether this light should cast shadows even when invisible.

Normally, when a light is turned off, any shadows cast by that light should disappear as well. However, there are certain lighting situations where you might want a light to cast shadows, even when turned off, such as using one light to accent the shadows cast by another light that has different ambient or diffuse lighting characteristics.

The initial value of this propety is NO.

Setting this value sets the same property on any descendant mesh and light nodes.

- (BOOL) shouldCopyLightIndex

readwritenonatomicassign

When a copy is made of this node, indicates whether this node should copy the value of the lightIndex property to the new node when performing a copy of this node.

The initial value of this property is NO.

When this property is set to NO, and this light node is copied, the new copy will be assigned its own lightIndex, to identify it to the GL engine. This allows both lights to illuminate the same scene (instance of CC3Scene), and is the most common mechanism for assigning the lightIndex property.

OpenGL ES limits the number of lights available to illuminate a single scene. Once that limit is reached, additional lights cannot be created, and attempting to copy this node will fail, returning a nil node.

The maximum number of lights available is determined by the platform. That number can be retrieved from the CC3OpenGL.sharedGL.maxNumberOfLights property. All platforms support at least eight lights.

When this property is set to YES, and this light node is copied, the new copy will be assigned the same lightIndex as this node. This means that the copy may not be used in the same scene as the original light, but it may be used in another scene (another CC3Scene instance).

Applications that make use of multiple CC3Scenes, either as a sequence of scenes, or as multiple scenes (and multiple CC3Layers) displayed on the screen at once, can set this property to YES when making copies of a light to be placed in different CC3Scene instances.

- (ccColor4F) specularColor

readwritenonatomicassign

The specular color of this light.

Initially set to kCC3DefaultLightColorSpecular.

- (GLfloat) spotCutoffAngle

readwritenonatomicassign

Indicates the angle, in degrees, of dispersion of the light from the direction of the light.

Setting this value to any angle between zero and 90 degrees, inclusive, will cause this light to be treated as a spotlight whose direction is set by the forwardDirection property of this light, and whose angle of dispersion is controlled by this property. Setting this property to any value above 90 degrees will cause this light to be treated as an omnidirectional light.

This property is initially set to kCC3SpotCutoffNone (180 degrees).

- (GLfloat) spotExponent

readwritenonatomicassign

Indicates the intensity distribution of the light.

Effective light intensity is attenuated by the cosine of the angle between the direction of the light and the direction from the light to the vertex being lighted, raised to the power of the value of this property. Thus, higher spot exponents result in a more focused light source, regardless of the value of the spotCutoffAngle property.

The value of this property must be in the range [0, 128], and is clamped to that range if an attempt is made to set the value outside this range.

The initial value of this property is zero, indicating a uniform light distribution.

- (CC3StencilledShadowPainterNode*) stencilledShadowPainter

readwritenonatomicretain

The mesh node used to draw the shadows cast by any shadow volumes that have been added to mesh nodes for this light.

Shadow volumes are used to define a stencil that is then used to draw dark areas onto the viewport where mesh nodes are casting shadows. This painter is used to draw those dark areas where the stencil indicates.

If not set directly, this property is lazily created when a shadow is added. If no shadow has been added, this property will return nil.

---

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

• CC3Light.h