Inherits from CC3Node : CC3Identifiable : NSObject
Declared in CC3Light.h

Overview

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.

Tasks

Properties

__deprecated

@deprecated Property renamed to attenuation

@property (nonatomic, assign) CC3AttenuationCoefficients attenuationCoefficients __deprecated

Declared In

CC3Light.h

ambientColor

The ambient color of this light. Initially set to kCC3DefaultLightColorAmbient.

@property (nonatomic, assign) ccColor4F ambientColor

Declared In

CC3Light.h

attenuation

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.

@property (nonatomic, assign) CC3AttenuationCoefficients attenuation

Discussion

The initial value of this property is kCC3DefaultLightAttenuationCoefficients.

Declared In

CC3Light.h

cameraShadowVolume

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

@property (nonatomic, retain) CC3CameraShadowVolume *cameraShadowVolume

Discussion

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.

Declared In

CC3Light.h

diffuseColor

The diffuse color of this light. Initially set to kCC3DefaultLightColorDiffuse.

@property (nonatomic, assign) ccColor4F diffuseColor

Declared In

CC3Light.h

forwardDirection

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

@property (nonatomic, assign) CC3Vector forwardDirection

Discussion

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.

Declared In

CC3Light.h

globalHomogeneousPosition

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

@property (nonatomic, readonly) CC3Vector4 globalHomogeneousPosition

Discussion

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.

Declared In

CC3Light.h

hasShadows

Returns whether this light is casting shadows.

@property (nonatomic, readonly) BOOL hasShadows

Discussion

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

Declared In

CC3Light.h

isDirectionalOnly

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.

@property (nonatomic, assign) BOOL isDirectionalOnly

Discussion

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.

Declared In

CC3Light.h

isLight

Returns whether this node is a light. Returns YES.

@property (nonatomic, readonly) BOOL isLight

Declared In

CC3Light.h

lightIndex

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.

@property (nonatomic, readonly) GLuint lightIndex

Discussion

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.

Declared In

CC3Light.h

shadowCastingVolume

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

@property (nonatomic, retain) CC3ShadowCastingVolume *shadowCastingVolume

Discussion

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.

Declared In

CC3Light.h

shadowIntensityFactor

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.

@property (nonatomic, assign) GLfloat shadowIntensityFactor

Discussion

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.

Declared In

CC3Light.h

shadows

The shadows cast by this light.

@property (nonatomic, retain, readonly) NSArray *shadows

Discussion

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

Declared In

CC3Light.h

shouldCastShadowsWhenInvisible

Indicates whether this light should cast shadows even when invisible.

@property (nonatomic, assign) BOOL shouldCastShadowsWhenInvisible

Discussion

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.

Declared In

CC3Light.h

shouldCopyLightIndex

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.

@property (nonatomic, assign) BOOL shouldCopyLightIndex

Discussion

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.

Declared In

CC3Light.h

specularColor

The specular color of this light. Initially set to kCC3DefaultLightColorSpecular.

@property (nonatomic, assign) ccColor4F specularColor

Declared In

CC3Light.h

spotCutoffAngle

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.

@property (nonatomic, assign) GLfloat spotCutoffAngle

Discussion

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

Declared In

CC3Light.h

spotExponent

Indicates the intensity distribution of the light.

@property (nonatomic, assign) GLfloat spotExponent

Discussion

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.

Declared In

CC3Light.h

stencilledShadowPainter

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

@property (nonatomic, retain) CC3StencilledShadowPainterNode *stencilledShadowPainter

Discussion

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.

Declared In

CC3Light.h

Class Methods

disableReservedLightsWithVisitor:

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

+ (void)disableReservedLightsWithVisitor:(CC3NodeDrawingVisitor *)visitor

Discussion

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.

Declared In

CC3Light.h

lightCount

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

+ (GLuint)lightCount

Discussion

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.

Declared In

CC3Light.h

lightPoolStartIndex

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

+ (GLuint)lightPoolStartIndex

Discussion

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

Declared In

CC3Light.h

lightWithLightIndex:

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.

+ (id)lightWithLightIndex:(GLuint)ltIndx

Discussion

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.

Declared In

CC3Light.h

lightWithName:withLightIndex:

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.

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

Discussion

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.

Declared In

CC3Light.h

lightWithTag:withLightIndex:

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

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

Discussion

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.

Declared In

CC3Light.h

lightWithTag:withName:withLightIndex:

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

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

Discussion

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.

Declared In

CC3Light.h

setLightPoolStartIndex:

Sets the smallest index number to assign to a 3D light. This value should be between zero inclusive and CC3OpenGL.sharedGL.maxNumberOfLights exclusive.

+ (void)setLightPoolStartIndex:(GLuint)newStartIndex

Discussion

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.

Declared In

CC3Light.h

Instance Methods

addShadow:

Adds a shadow to the shadows cast by this light.

- (void)addShadow:(id<CC3ShadowProtocol>)shadowNode

Discussion

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

Declared In

CC3Light.h

drawShadowsWithVisitor:

Draws any shadows cast by this light.

- (void)drawShadowsWithVisitor:(CC3NodeDrawingVisitor *)visitor

Declared In

CC3Light.h

init

Initializes this unnamed instance with an automatically generated unique tag value. The tag value will be generated automatically via the method nextTag.

- (id)init

Discussion

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.

Declared In

CC3Light.h

initWithLightIndex:

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.

- (id)initWithLightIndex:(GLuint)ltIndx

Discussion

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.

Declared In

CC3Light.h

initWithName:

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.

- (id)initWithName:(NSString *)aName

Discussion

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.

Declared In

CC3Light.h

initWithName:withLightIndex:

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.

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

Discussion

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.

Declared In

CC3Light.h

initWithTag:

Initializes this unnamed instance with the specified tag.

- (id)initWithTag:(GLuint)aTag

Discussion

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.

Declared In

CC3Light.h

initWithTag:withLightIndex:

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

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

Discussion

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.

Declared In

CC3Light.h

initWithTag:withName:

Initializes this instance with the specified tag and name.

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

Discussion

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.

Declared In

CC3Light.h

initWithTag:withName:withLightIndex:

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

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

Discussion

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.

Declared In

CC3Light.h

removeShadow:

Removes a shadow from the shadows cast by this light.

- (void)removeShadow:(id<CC3ShadowProtocol>)shadowNode

Declared In

CC3Light.h

turnOffWithVisitor:

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

- (void)turnOffWithVisitor:(CC3NodeDrawingVisitor *)visitor

Discussion

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.

Declared In

CC3Light.h

turnOnWithVisitor:

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.

- (void)turnOnWithVisitor:(CC3NodeDrawingVisitor *)visitor

Discussion

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.

Declared In

CC3Light.h

updateRelativeIntensityFrom:

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

- (void)updateRelativeIntensityFrom:(ccColor4F)totalLight

Discussion

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.

Declared In

CC3Light.h

updateShadows

Update the shadows that are cast by this light.

- (void)updateShadows

Declared In

CC3Light.h