SpotLight
A SpotLight defines a positional light source that originates from a single point and eminates in a given direction, to illuminate Meshes.
Overview
- SpotLights have a position and direction.
- SpotLights may be defined in either World or View coordinate space. When in World-space, their positions are relative to the World coordinate system, and will appear to move as the Camera moves. When in View-space, their positions are relative to the View coordinate system, and will behave as if fixed to the viewer's head as the Camera moves.
- SpotLights have constantAttenuation, linearAttenuation and quadraticAttenuation factors, which indicate how their intensity attenuates over distance.
- A SpotLight can also have a Shadow component, to configure it to cast a shadow.
- AmbientLight, DirLight,
SpotLight and PointLight instances are registered by ID
on Scene#lights for convenient access.
Examples
TODO
Usage
In the example below we'll customize the default Scene's light sources, defining an AmbientLight and a couple of SpotLights, then create a Phong-shaded box mesh.
new xeogl.AmbientLight({
color: [0.8, 0.8, 0.8],
intensity: 0.5
});
new xeogl.SpotLight({
pos: [0, 100, 100],
dir: [0, -1, 0],
color: [0.5, 0.7, 0.5],
intensity: 1
constantAttenuation: 0,
linearAttenuation: 0,
quadraticAttenuation: 0,
space: "view"
});
new xeogl.PointLight({
pos: [0, 100, 100],
dir: [0, -1, 0],
color: [0.5, 0.7, 0.5],
intensity: 1
constantAttenuation: 0,
linearAttenuation: 0,
quadraticAttenuation: 0,
space: "view"
});
// Create box mesh
new xeogl.Mesh({
material: new xeogl.PhongMaterial({
ambient: [0.5, 0.5, 0.5],
diffuse: [1,0.3,0.3]
}),
geometry: new xeogl.BoxGeometry()
});Constructor
SpotLight
-
[owner] -
[cfg] -
[cfg.pos=[ -
[cfg.dir=[ -
[cfg.color=[0.7,
Parameters:
-
[owner]Component optionalOwner component. When destroyed, the owner will destroy this component as well. Creates this component within the default Scene when omitted.
-
[cfg]optionalThe SpotLight configuration
-
[id]String optionalOptional ID, unique among all components in the parent Scene, generated automatically when omitted.
-
[meta]String:Object optionalOptional map of user-defined metadata to attach to this SpotLight.
-
[intensity=1.0]Number optionalIntensity of this SpotLight.
-
[constantAttenuation=0]Number optionalConstant attenuation factor.
-
[linearAttenuation=0]Number optionalLinear attenuation factor.
-
[quadraticAttenuation=0]Number optionalQuadratic attenuation factor.
-
[space="view"]String optionalThe coordinate system this SpotLight is defined in - "view" or "world".
-
[shadow=false]Boolean optionalFlag which indicates if this SpotLight casts a shadow.
-
-
[cfg.pos=[Float32Array1.0, 1.0, 1.0 ]] Position, in either World or View space, depending on the value of the space parameter.
-
[cfg.dir=[Float32Array0.0, -1.0, 0.0 ]] Direction in which this Spotlight is shining, in either World or View space, depending on the value of the space parameter.
-
[cfg.color=[0.7,Float32Array0.7, 0.8 ]] Color of this SpotLight.
Index
Properties
Events
Methods
create
-
[cfg]
Convenience method for creating a Component within this Component's Scene.
The method is given a component configuration, like so:
var material = myComponent.create({
type: "xeogl.PhongMaterial",
diffuse: [1,0,0],
specular: [1,1,0]
}, "myMaterial");Parameters:
-
[cfg]optionalConfiguration for the component instance.
Returns:
destroy
()
Destroys this component.
Fires a destroyed event on this Component.
Automatically disassociates this component from other components, causing them to fall back on any defaults that this component overrode on them.
TODO: describe effect with respect to #create
error
-
message
Logs an error for this component to the JavaScript console.
The console message will have this format: [ERROR] [<component type> =<component id>: <message>
Also fires the message as an error event on the parent Scene.
Parameters:
-
messageStringThe message to log
fire
-
event -
value -
[forget=false]
Fires an event on this component.
Notifies existing subscribers to the event, optionally retains the event to give to any subsequent notifications on the event as they are made.
Parameters:
-
eventStringThe event type name
-
valueObjectThe event parameters
-
[forget=false]Boolean optionalWhen true, does not retain for subsequent subscribers
hasSubs
-
event
Returns true if there are any subscribers to the given event on this component.
Parameters:
-
eventStringThe event
Returns:
True if there are any subscribers to the given event on this component.
isType
-
type
Tests if this component is of the given type, or is a subclass of the given type.
The type may be given as either a string or a component constructor.
This method works by walking up the inheritance type chain, which this component provides in property Component/superTypes:property, returning true as soon as one of the type strings in the chain matches the given type, of false if none match.
Examples:
var myRotate = new xeogl.Rotate({ ... });
myRotate.isType(xeogl.Component); // Returns true for all xeogl components
myRotate.isType("xeogl.Component"); // Returns true for all xeogl components
myRotate.isType(xeogl.Rotate); // Returns true
myRotate.isType(xeogl.Transform); // Returns true
myRotate.isType("xeogl.Transform"); // Returns true
myRotate.isType(xeogl.Mesh); // Returns false, because xeogl.Rotate does not (even indirectly) extend xeogl.MeshParameters:
-
typeString | FunctionComponent type to compare with, eg "xeogl.PhongMaterial", or a xeogl component constructor.
Returns:
True if this component is of given type or is subclass of the given type.
log
-
message
Logs a console debugging message for this component.
The console message will have this format: [LOG] [<component type> <component id>: <message>
Parameters:
-
messageStringThe message to log
off
-
subId
Cancels an event subscription that was previously made with Component#on() or Component#once().
Parameters:
-
subIdStringPublication subId
on
-
event -
callback -
[scope=this]
Subscribes to an event on this component.
The callback is be called with this component as scope.
Parameters:
-
eventStringThe event
-
callbackFunctionCalled fired on the event
-
[scope=this]Object optionalScope for the callback
Returns:
Handle to the subscription, which may be used to unsubscribe with {@link #off}.
once
-
event -
callback -
[scope=this]
Subscribes to the next occurrence of the given event, then un-subscribes as soon as the event is subIdd.
This is equivalent to calling Component#on(), and then calling Component#off() inside the callback function.
Parameters:
-
eventStringData event to listen to
-
callbackFunction(data)Called when fresh data is available at the event
-
[scope=this]Object optionalScope for the callback
Properties
color
Float32Array
The color of this SpotLight.
Default: [0.7, 0.7, 0.8]
constantAttenuation
Number
The constant attenuation factor for this SpotLight.
Default: 0
destroyed
Boolean
True as soon as this Component has been destroyed
dir
Float32Array
The direction in which the light is shining.
Default: [1.0, 1.0, 1.0]
intensity
Number
The intensity of this SpotLight.
Fires a SpotLight/intensity:event event on change.
Default: 1.0
linearAttenuation
Number
The linear attenuation factor for this SpotLight.
Default: 0
model
Model
final
The Model which contains this Component, if any.
Will be null if this Component is not in a Model.
pos
Array(Number)
The position of this SpotLight.
This will be either World- or View-space, depending on the value of SpotLight/space:property.
Default: [1.0, 1.0, 1.0]
quadraticAttenuation
Number
The quadratic attenuation factor for this SpotLight.
Default: 0
shadow
Boolean
Flag which indicates if this SpotLight casts a shadow.
Default: false
type
String
final
JavaScript class name for this Component.
For example: "xeogl.AmbientLight", "xeogl.MetallicMaterial" etc.
Events
destroyed
Fired when this Component is destroyed.