API Docs for:

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 optional

    Owner component. When destroyed, the owner will destroy this component as well. Creates this component within the default Scene when omitted.

  • [cfg] optional

    The SpotLight configuration

    • [id] String optional

      Optional ID, unique among all components in the parent Scene, generated automatically when omitted.

    • [meta] String:Object optional

      Optional map of user-defined metadata to attach to this SpotLight.

    • [intensity=1.0] Number optional

      Intensity of this SpotLight.

    • [constantAttenuation=0] Number optional

      Constant attenuation factor.

    • [linearAttenuation=0] Number optional

      Linear attenuation factor.

    • [quadraticAttenuation=0] Number optional

      Quadratic attenuation factor.

    • [space="view"] String optional

      The coordinate system this SpotLight is defined in - "view" or "world".

    • [shadow=false] Boolean optional

      Flag which indicates if this SpotLight casts a shadow.

  • [cfg.pos=[ Float32Array

    1.0, 1.0, 1.0 ]] Position, in either World or View space, depending on the value of the space parameter.

  • [cfg.dir=[ Float32Array

    0.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, Float32Array

    0.7, 0.8 ]] Color of this SpotLight.

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] optional

    Configuration 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:

  • message String

    The 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:

  • event String

    The event type name

  • value Object

    The event parameters

  • [forget=false] Boolean optional

    When true, does not retain for subsequent subscribers

hasSubs

(
  • event
)
Boolean

Returns true if there are any subscribers to the given event on this component.

Parameters:

  • event String

    The event

Returns:

Boolean:

True if there are any subscribers to the given event on this component.

isType

(
  • type
)
Boolean

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.Mesh

Parameters:

  • type String | Function

    Component type to compare with, eg "xeogl.PhongMaterial", or a xeogl component constructor.

Returns:

Boolean:

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>

Also fires the message as a log event on the parent Scene.

Parameters:

  • message String

    The message to log

off

(
  • subId
)

Cancels an event subscription that was previously made with Component#on() or Component#once().

Parameters:

  • subId String

    Publication subId

on

(
  • event
  • callback
  • [scope=this]
)
String

Subscribes to an event on this component.

The callback is be called with this component as scope.

Parameters:

  • event String

    The event

  • callback Function

    Called fired on the event

  • [scope=this] Object optional

    Scope for the callback

Returns:

String:

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:

  • event String

    Data event to listen to

  • callback Function(data)

    Called when fresh data is available at the event

  • [scope=this] Object optional

    Scope for the callback

warn

(
  • message
)

Logs a warning for this component to the JavaScript console.

The console message will have this format: [WARN] [<component type> =<component id>: <message>

Also fires the message as a warn event on the parent Scene.

Parameters:

  • message String

    The message to log

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]

id

String final

Unique ID for this Component within its parent Scene.

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

metadata

Object

Arbitrary, user-defined metadata on this component.

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

scene

Scene final

The parent Scene that contains this Component.

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.