CC3Light represents the light in the 3D world. More...
#import <CC3Light.h>
Public Member Functions | |
| (id) | - init |
| (id) | - initWithLightIndex: |
| (id) | - initWithName: |
| (id) | - initWithName:withLightIndex: |
| (id) | - initWithTag: |
| (id) | - initWithTag:withLightIndex: |
| (id) | - initWithTag:withName: |
| (id) | - initWithTag:withName:withLightIndex: |
| (void) | - turnOn |
Static Public Member Functions | |
| (void) | + disableReservedLights |
| (GLuint) | + lightCount |
| (GLuint) | + lightPoolStartIndex |
| (id) | + lightWithLightIndex: |
| (id) | + lightWithName:withLightIndex: |
| (id) | + lightWithTag:withLightIndex: |
| (id) | + lightWithTag:withName:withLightIndex: |
| (void) | + setLightPoolStartIndex: |
Properties | |
| ccColor4F | ambientColor |
| CC3AttenuationCoefficients | attenuationCoefficients |
| ccColor4F | diffuseColor |
| CC3Vector4 | homogeneousLocation |
| BOOL | isDirectionalOnly |
| GLuint | lightIndex |
| BOOL | shouldCopyLightIndex |
| ccColor4F | specularColor |
| GLfloat | spotCutoffAngle |
| GLfloat | spotExponent |
Detailed Description
CC3Light represents the light in the 3D world.
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 is also a type of CC3TargettingNode, and 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. All platforms support at least eight lights.
Lights in different scenes (different instances of CC3World) can have the same GL lightIndex value. Applications that make use of multiple CC3Worlds, either as a sequence of scenes, or as multiple worlds (and multiple CC3Layers) displayed on the screen at once, can reuse a light index across the worlds. The shouldCopyLightIndex property can be used to help copy lights across worlds.
If the application uses lights in the 2D world as well, the indexes of those lights can be reserved by invoking the class method setLightPoolStartIndex:. Light indexes reserved for use by the 2D world will not be used by the 3D world.
Member Function Documentation
| + (void) disableReservedLights |
Disables the lights that were reserved for the 2D world by setLightPoolStartIndex:.
This method is invoked automatically by CC3World near the beginning of each frame drawing cycle. Usually, the application never needs to invoke this method directly.
| - (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 [CC3OpenGLES11Engine engine].platform.maxLights.value. All platforms support at least eight lights.
Implements CC3Identifiable.
| - (id) initWithLightIndex: | (GLenum) | 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 CC3World 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. All platforms support at least eight lights.
Implements CC3Identifiable.
| - (id) initWithName: | (NSString *) | aName | |
| withLightIndex: | (GLenum) | 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 CC3World 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. All platforms support at least eight lights.
Implements CC3Identifiable.
| - (id) initWithTag: | (GLuint) | aTag | |
| withLightIndex: | (GLenum) | 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 CC3World 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. All platforms support at least eight lights.
Implements CC3Identifiable.
| - (id) initWithTag: | (GLuint) | aTag | |
| withName: | (NSString *) | aName | |
| withLightIndex: | (GLenum) | 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 CC3World 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. 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: | (GLenum) | 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 CC3World 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. All platforms support at least eight lights.
| + (id) lightWithName: | (NSString *) | aName | |
| withLightIndex: | (GLenum) | 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 CC3World 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. All platforms support at least eight lights.
| + (id) lightWithTag: | (GLuint) | aTag | |
| withLightIndex: | (GLenum) | 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 CC3World 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. All platforms support at least eight lights.
| + (id) lightWithTag: | (GLuint) | aTag | |
| withName: | (NSString *) | aName | |
| withLightIndex: | (GLenum) | 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 CC3World 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. All platforms support at least eight lights.
| + (void) setLightPoolStartIndex: | (GLuint) | newStartIndex |
Sets the smallest index number to assign to a 3D light.
This value should be between zero inclusive and [CC3OpenGLES11Engine engine].platform.maxLights.value exclusive.
If the 2D world uses lights, setting this value to a number above zero will reserve the indexes below this number for the 2D world and those indexes will not be used in lights in the 3D world.
This value defaults to zero. If your application requires light indexes to be reserved and not assigned in the 3D world, set this value.
| - (void) turnOn |
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 CC3World near the beginning of each frame drawing cycle. Usually, the application never needs to invoke this method directly.
Property Documentation
- (ccColor4F) ambientColor [read, write, assign] |
- (CC3AttenuationCoefficients) attenuationCoefficients [read, write, assign] |
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.
- (ccColor4F) diffuseColor [read, write, assign] |
- (CC3Vector4) homogeneousLocation [read, assign] |
The location of this light in the 4D homogeneous coordinate space.
The x, y and z components of the returned value will be the same as those in the globalLocation property. The w-component will be one if the light is considered to be actually located at the globalLocation property, or zero if the globalLocation property is an indication of the direction the light is coming from, and not an absolute location.
- (BOOL) isDirectionalOnly [read, write, assign] |
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.
- (GLuint) lightIndex [read, assign] |
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 [CC3OpenGLES11Engine engine].platform.maxLights.value. All platforms support at least eight lights.
- (BOOL) shouldCopyLightIndex [read, write, assign] |
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 CC3World), 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 [CC3OpenGLES11Engine engine].platform.maxLights.value. 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 CC3World instance).
Applications that make use of multiple CC3Worlds, either as a sequence of scenes, or as multiple worlds (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 CC3World instances.
- (ccColor4F) specularColor [read, write, assign] |
The specular color of this light.
Initially set to kCC3DefaultLightColorSpecular.
Implements CC3Node.
- (GLfloat) spotCutoffAngle [read, write, assign] |
Indicates the angle, in degrees, of dispersion of the light from the direction of the light.
Setting this value to any angle below kCC3SpotCutoffNone (180 degrees) 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 kCC3SpotCutoffNone or above will cause this light to be treated as an omnidirectional light. Initially set to kCC3SpotCutoffNone.
- (GLfloat) spotExponent [read, write, assign] |
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.
The documentation for this class was generated from the following file:
