LightComponent
Extends: Component
The Light Component enables the Entity to light the scene. There are three types of light: directional, omni and spot. Directional lights are global in that they are considered to be infinitely far away and light the entire scene. Omni and spot lights are local in that they have a position and a range. A spot light is a specialization of an omni light where light is emitted in a cone rather than in all directions. Lights also have the ability to cast shadows to add realism to your scenes.
// Add a pc.LightComponent to an entity
const entity = new pc.Entity();
entity.addComponent('light', {
type: "omni",
color: new pc.Color(1, 0, 0),
range: 10
});
// Get the pc.LightComponent on an entity
const lightComponent = entity.light;
// Update a property on a light component
entity.light.range = 20;
Summary
Properties
affectDynamic | If enabled the light will affect non-lightmapped objects. |
affectLightmapped | If enabled the light will affect lightmapped objects. |
affectSpecularity | If enabled and the light type is pc. |
bake | If enabled the light will be rendered into lightmaps. |
bakeArea | If bake is true and the light type is LIGHTTYPE_DIRECTIONAL, this specifies the penumbra angle in degrees, allowing a soft shadow boundary. |
bakeDir | If enabled and bake=true, the light's direction will contribute to directional lightmaps. |
bakeNumSamples | If bake is true, this specifies the number of samples used to bake this light into the lightmap. |
cascadeDistribution | The distribution of subdivision of the camera frustum for individual shadow cascades. |
castShadows | If enabled the light will cast shadows. |
color | The Color of the light. |
cookie | Projection texture. |
cookieAngle | Angle for spotlight cookie rotation. |
cookieAsset | Asset that has texture that will be assigned to cookie internally once asset resource is available. |
cookieChannel | Color channels of the projection texture to use. |
cookieFalloff | Toggle normal spotlight falloff when projection texture is used. |
cookieIntensity | Projection texture intensity (default is 1). |
cookieOffset | Spotlight cookie position offset. |
cookieScale | Spotlight cookie scale. |
falloffMode | Controls the rate at which a light attenuates from its position. |
innerConeAngle | The angle at which the spotlight cone starts to fade off. |
intensity | The brightness of the light. |
isStatic | Mark light as non-movable (optimization). |
layers | An array of layer IDs (Layer#id) to which this light should belong. |
luminance | The physically based luminance. |
mask | Defines a mask to determine which MeshInstances are lit by this light. |
normalOffsetBias | Normal offset depth bias. |
numCascades | Number of shadow cascades. |
outerConeAngle | The angle at which the spotlight cone has faded to nothing. |
penumbraSize | Size of penumbra for contact hardening shadows. |
range | The range of the light. |
shadowBias | The depth bias for tuning the appearance of the shadow mapping generated by this light. |
shadowDistance | The distance from the viewpoint beyond which shadows are no longer rendered. |
shadowIntensity | The intensity of the shadow darkening, 1 being shadows are entirely black. |
shadowResolution | The size of the texture used for the shadow map. |
shadowType | Type of shadows being rendered by this light. |
shadowUpdateMode | Tells the renderer how often shadows must be updated for this light. |
shadowUpdateOverrides | Returns an array of SHADOWUPDATE_ settings per shadow cascade, or undefined if not used. |
shape | The light source shape. |
type | The type of light. |
vsmBlurMode | Blurring mode for variance shadow maps. |
vsmBlurSize | Number of samples used for blurring a variance shadow map. |
Inherited
Properties
enabled | Enables or disables the component. |
entity | The Entity that this Component is attached to. |
system | The ComponentSystem used to create this Component. |
Methods
fire | Fire an event, all additional arguments are passed on to the event listener. |
hasEvent | Test if there are any handlers bound to an event name. |
off | Detach an event handler from an event. |
on | Attach an event handler to an event. |
once | Attach an event handler to an event. |
Details
Constructor
LightComponent(system, entity)
Creates a new LightComponent instance.
Parameters
system | LightComponentSystem | The ComponentSystem that created this Component. |
entity | Entity | The Entity that this Component is attached to. |
Properties
If enabled and the light type is pc.LIGHTTYPE_DIRECTIONAL, material specularity will not be affected by this light. Defaults to true.
If bake is true and the light type is LIGHTTYPE_DIRECTIONAL, this specifies the penumbra angle in degrees, allowing a soft shadow boundary. Defaults to 0.
If enabled and bake=true, the light's direction will contribute to directional lightmaps. Be aware, that directional lightmap is an approximation and can only hold single direction per pixel. Intersecting multiple lights with bakeDir=true may lead to incorrect look of specular/bump-mapping in the area of intersection. The error is not always visible though, and highly scene-dependent.
If bake is true, this specifies the number of samples used to bake this light into the lightmap. Defaults to 1. Maximum value is 255.
The distribution of subdivision of the camera frustum for individual shadow cascades. Only used if LightComponent#numCascades is larger than 1. Can be a value in range of 0 and 1. Value of 0 represents a linear distribution, value of 1 represents a logarithmic distribution. Defaults to 0.5. Larger value increases the resolution of the shadows in the near distance.
The Color of the light. The alpha component of the color is ignored. Defaults to white (1, 1, 1).
Controls the rate at which a light attenuates from its position. Can be:
- LIGHTFALLOFF_LINEAR: Linear.
- LIGHTFALLOFF_INVERSESQUARED: Inverse squared.
Affects omni and spot lights only. Defaults to LIGHTFALLOFF_LINEAR.
The angle at which the spotlight cone starts to fade off. The angle is specified in degrees. Affects spot lights only. Defaults to 40.
An array of layer IDs (Layer#id) to which this light should belong. Don't push/pop/splice or modify this array, if you want to change it - set a new one instead.
The physically based luminance. Only used if scene.physicalUnits is true. Defaults to 0.
Number of shadow cascades. Can be 1, 2, 3 or 4. Defaults to 1, representing no cascades.
The angle at which the spotlight cone has faded to nothing. The angle is specified in degrees. Affects spot lights only. Defaults to 45.
Size of penumbra for contact hardening shadows. For area lights acts as a multiplier with the dimensions of the area light. For punctual and directional lights it's the area size of the light. Defaults to 1.0.
The depth bias for tuning the appearance of the shadow mapping generated by this light. Valid range is 0 to 1. Defaults to 0.05.
The distance from the viewpoint beyond which shadows are no longer rendered. Affects directional lights only. Defaults to 40.
The intensity of the shadow darkening, 1 being shadows are entirely black. Defaults to 1.
The size of the texture used for the shadow map. Valid sizes are 64, 128, 256, 512, 1024, 2048. Defaults to 1024.
Type of shadows being rendered by this light. Options:
- SHADOW_PCF3: Render depth (color-packed on WebGL 1.0), can be used for PCF 3x3 sampling.
- SHADOW_VSM8: Render packed variance shadow map. All shadow receivers must also cast shadows for this mode to work correctly.
- SHADOW_VSM16: Render 16-bit exponential variance shadow map. Requires OES_texture_half_float extension. Falls back to SHADOW_VSM8, if not supported.
- SHADOW_VSM32: Render 32-bit exponential variance shadow map. Requires OES_texture_float extension. Falls back to SHADOW_VSM16, if not supported.
- SHADOW_PCF5: Render depth buffer only, can be used for hardware-accelerated PCF 5x5 sampling. Requires WebGL2. Falls back to SHADOW_PCF3 on WebGL 1.0.
- SHADOW_PCSS: Render depth as color, and use the software sampled PCSS method for shadows.
Tells the renderer how often shadows must be updated for this light. Can be:
- SHADOWUPDATE_NONE: Don't render shadows.
- SHADOWUPDATE_THISFRAME: Render shadows only once (then automatically switches to SHADOWUPDATE_NONE.
- SHADOWUPDATE_REALTIME: Render shadows every frame (default).
Returns an array of SHADOWUPDATE_ settings per shadow cascade, or undefined if not used.
The light source shape. Can be:
- LIGHTSHAPE_PUNCTUAL: Infinitesimally small point.
- LIGHTSHAPE_RECT: Rectangle shape.
- LIGHTSHAPE_DISK: Disk shape.
- LIGHTSHAPE_SPHERE: Sphere shape.
Defaults to pc.LIGHTSHAPE_PUNCTUAL.
The type of light. Can be:
- "directional": A light that is infinitely far away and lights the entire scene from one direction.
- "omni": An omni-directional light that illuminates in all directions from the light source.
- "spot": An omni-directional light but is bounded by a cone.
Defaults to "directional".
Blurring mode for variance shadow maps. Can be:
- BLUR_BOX: Box filter.
- BLUR_GAUSSIAN: Gaussian filter. May look smoother than box, but requires more samples.
Number of samples used for blurring a variance shadow map. Only uneven numbers work, even are incremented. Minimum value is 1, maximum is 25. Defaults to 11.
Inherited
Properties
Methods
fire(name, [arg1], [arg2], [arg3], [arg4], [arg5], [arg6], [arg7], [arg8])
Fire an event, all additional arguments are passed on to the event listener.
obj.fire('test', 'This is the message');
Parameters
name | string | Name of event to fire. |
arg1 | * | First argument that is passed to the event handler. |
arg2 | * | Second argument that is passed to the event handler. |
arg3 | * | Third argument that is passed to the event handler. |
arg4 | * | Fourth argument that is passed to the event handler. |
arg5 | * | Fifth argument that is passed to the event handler. |
arg6 | * | Sixth argument that is passed to the event handler. |
arg7 | * | Seventh argument that is passed to the event handler. |
arg8 | * | Eighth argument that is passed to the event handler. |
Returns
EventHandlerSelf for chaining.
hasEvent(name)
Test if there are any handlers bound to an event name.
obj.on('test', function () { }); // bind an event to 'test'
obj.hasEvent('test'); // returns true
obj.hasEvent('hello'); // returns false
Parameters
name | string | The name of the event to test. |
Returns
booleanTrue if the object has handlers bound to the specified event name.
off([name], [callback], [scope])
Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.
const handler = function () {
};
obj.on('test', handler);
obj.off(); // Removes all events
obj.off('test'); // Removes all events called 'test'
obj.off('test', handler); // Removes all handler functions, called 'test'
obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this
Parameters
name | string | Name of the event to unbind. |
callback | HandleEventCallback | Function to be unbound. |
scope | object | Scope that was used as the this when the event is fired. |
Returns
EventHandlerSelf for chaining.
on(name, callback, [scope])
Attach an event handler to an event.
obj.on('test', function (a, b) {
console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
Parameters
name | string | Name of the event to bind the callback to. |
callback | HandleEventCallback | Function that is called when event is fired. Note the callback is limited to 8 arguments. |
scope | object | Object to use as 'this' when the event is fired, defaults to current this. |
Returns
EventHandlerSelf for chaining.
once(name, callback, [scope])
Attach an event handler to an event. This handler will be removed after being fired once.
obj.once('test', function (a, b) {
console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
obj.fire('test', 1, 2); // not going to get handled
Parameters
name | string | Name of the event to bind the callback to. |
callback | HandleEventCallback | Function that is called when event is fired. Note the callback is limited to 8 arguments. |
scope | object | Object to use as 'this' when the event is fired, defaults to current this. |
Returns
EventHandlerSelf for chaining.