API Reference

Class List

pc.LightComponent

Extends: pc.Component

The Light Component enables the Entity to light the scene. There are three types of light: directional, point and spot. Directional lights are global in that they are considered to be infinitely far away and light the entire scene. Point and spot lights are local in that they have a position and a range. A spot light is a specialization of a point 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
var entity = new pc.Entity();
entity.addComponent('light', {
    type: "point",
    color: new pc.Color(1, 0, 0),
    range: 10
});
// Get the pc.LightComponent on an entity
var lightComponent = entity.light;
// Update a property on a light component
entity.light.range = 20;

Summary

Properties

affectDynamicIf enabled the light will affect non-lightmapped objects
affectLightmappedIf enabled the light will affect lightmapped objects
bakeIf enabled the light will be rendered into lightmaps
bakeDirIf enabled and bake=true, the light's direction will contribute to directional lightmaps.
castShadowsIf enabled the light will cast shadows.
colorThe Color of the light.
cookieProjection texture.
cookieAngleAngle for spotlight cookie rotation.
cookieAssetAsset that has texture that will be assigned to cookie internally once asset resource is available.
cookieChannelColor channels of the projection texture to use.
cookieFalloffToggle normal spotlight falloff when projection texture is used.
cookieIntensityProjection texture intensity (default is 1).
cookieOffsetSpotlight cookie position offset.
cookieScaleSpotlight cookie scale.
falloffModeControls the rate at which a light attentuates from its position.
innerConeAngleThe angle at which the spotlight cone starts to fade off.
intensityThe brightness of the light.
isStaticMark light as non-movable (optimization)
layersAn array of layer IDs (pc.Layer#id) to which this light should belong.
maskDefines a mask to determine which pc.MeshInstances are lit by this light.
normalOffsetBiasNormal offset depth bias.
outerConeAngleThe angle at which the spotlight cone has faded to nothing.
rangeThe range of the light.
shadowBiasThe depth bias for tuning the appearance of the shadow mapping generated by this light.
shadowDistanceThe distance from the viewpoint beyond which shadows are no longer rendered.
shadowResolutionThe size of the texture used for the shadow map.
shadowTypeType of shadows being rendered by this light.
shadowUpdateModeTells the renderer how often shadows must be updated for this light.
typeThe type of light.
vsmBlurModeBlurring mode for variance shadow maps:
vsmBlurSizeNumber of samples used for blurring a variance shadow map.

Inherited

Properties

enabledEnables or disables the component.
entityThe Entity that this Component is attached to
systemThe ComponentSystem used to create this Component

Methods

fireFire an event, all additional arguments are passed on to the event listener
hasEventTest if there are any handlers bound to an event name
offDetach an event handler from an event.
onAttach an event handler to an event
onceAttach an event handler to an event.

Details

Constructor

LightComponent(system, entity)

Creates a new Light Component.

// Add a pc.LightComponent to an entity
var entity = new pc.Entity();
entity.addComponent('light', {
    type: "point",
    color: new pc.Color(1, 0, 0),
    range: 10
});
// Get the pc.LightComponent on an entity
var lightComponent = entity.light;
// Update a property on a light component
entity.light.range = 20;

Parameters

systempc.LightComponentSystemThe ComponentSystem that created this Component.
entitypc.EntityThe Entity that this Component is attached to.

Properties

BooleanaffectDynamic

If enabled the light will affect non-lightmapped objects

BooleanaffectLightmapped

If enabled the light will affect lightmapped objects

Booleanbake

If enabled the light will be rendered into lightmaps

BooleanbakeDir

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.

BooleancastShadows

If enabled the light will cast shadows. Defaults to false.

pc.Colorcolor

The Color of the light. The alpha component of the color is ignored. Defaults to white (1, 1, 1).

NumbercookieAngle

Angle for spotlight cookie rotation.

NumbercookieAsset

Asset that has texture that will be assigned to cookie internally once asset resource is available.

StringcookieChannel

Color channels of the projection texture to use. Can be "r", "g", "b", "a", "rgb" or any swizzled combination.

BooleancookieFalloff

Toggle normal spotlight falloff when projection texture is used. When set to false, spotlight will work like a pure texture projector (only fading with distance). Default is false.

NumbercookieIntensity

Projection texture intensity (default is 1).

pc.Vec2cookieOffset

Spotlight cookie position offset.

pc.Vec2cookieScale

Spotlight cookie scale.

NumberfalloffMode

Controls the rate at which a light attentuates from its position. Can be:

Affects point and spot lights only. Defaults to pc.LIGHTFALLOFF_LINEAR.

NumberinnerConeAngle

The angle at which the spotlight cone starts to fade off. The angle is specified in degrees. Affects spot lights only. Defaults to 40.

Numberintensity

The brightness of the light. Defaults to 1.

BooleanisStatic

Mark light as non-movable (optimization)

Number[]layers

An array of layer IDs (pc.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.

Numbermask

Defines a mask to determine which pc.MeshInstances are lit by this light. Defaults to 1.

NumbernormalOffsetBias

Normal offset depth bias. Defaults to 0.

NumberouterConeAngle

The angle at which the spotlight cone has faded to nothing. The angle is specified in degrees. Affects spot lights only. Defaults to 45.

Numberrange

The range of the light. Affects point and spot lights only. Defaults to 10.

NumbershadowBias

The depth bias for tuning the appearance of the shadow mapping generated by this light. Defaults to 0.05.

NumbershadowDistance

The distance from the viewpoint beyond which shadows are no longer rendered. Affects directional lights only. Defaults to 40.

NumbershadowResolution

The size of the texture used for the shadow map. Valid sizes are 64, 128, 256, 512, 1024, 2048. Defaults to 1024.

NumbershadowType

Type of shadows being rendered by this light. Options:

  • pc.SHADOW_PCF3: Render depth (color-packed on WebGL 1.0), can be used for PCF 3x3 sampling.
  • pc.SHADOW_VSM8: Render packed variance shadow map. All shadow receivers must also cast shadows for this mode to work correctly.
  • pc.SHADOW_VSM16: Render 16-bit exponential variance shadow map. Requires OES_texture_half_float extension. Falls back to pc.SHADOW_VSM8, if not supported.
  • pc.SHADOW_VSM32: Render 32-bit exponential variance shadow map. Requires OES_texture_float extension. Falls back to pc.SHADOW_VSM16, if not supported.
  • pc.SHADOW_PCF5: Render depth buffer only, can be used for hardware-accelerated PCF 5x5 sampling. Requires WebGL2. Falls back to pc.SHADOW_PCF3 on WebGL 1.0.

NumbershadowUpdateMode

Tells the renderer how often shadows must be updated for this light. Options:

  • pc.SHADOWUPDATE_NONE: Don't render shadows.
  • pc.SHADOWUPDATE_THISFRAME: Render shadows only once (then automatically switches to pc.SHADOWUPDATE_NONE).
  • pc.SHADOWUPDATE_REALTIME: Render shadows every frame (default).

Stringtype

The type of light. Can be:

  • "directional": A light that is infinitely far away and lights the entire scene from one direction.
  • "point": A light that illuminates in all directions from a point.
  • "spot": A light that illuminates in all directions from a point and is bounded by a cone.
Defaults to "directional".

NumbervsmBlurMode

Blurring mode for variance shadow maps:

NumbervsmBlurSize

Number of samples used for blurring a variance shadow map. Only uneven numbers work, even are incremented. Minimum value is 1, maximum is 25.

Inherited

Properties

Booleanenabled

Enables or disables the component.

pc.Entityentity

The Entity that this Component is attached to

pc.ComponentSystemsystem

The ComponentSystem used to create this Component

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

nameObjectName 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

pc.EventHandler Self 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

nameStringThe name of the event to test

Returns

Boolean true 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.

var 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 hander functions, called 'test' with scope this

Parameters

nameStringName of the event to unbind
callbackpc.callbacks.HandleEventFunction to be unbound.
scopeObjectScope that was used as the this when the event is fired

Returns

pc.EventHandler Self 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

nameStringName of the event to bind the callback to
callbackpc.callbacks.HandleEventFunction that is called when event is fired. Note the callback is limited to 8 arguments.
scopeObjectObject to use as 'this' when the event is fired, defaults to current this

Returns

pc.EventHandler Self 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

nameStringName of the event to bind the callback to
callbackpc.callbacks.HandleEventFunction that is called when event is fired. Note the callback is limited to 8 arguments.
scopeObjectObject to use as 'this' when the event is fired, defaults to current this

Returns

pc.EventHandler Self for chaining.