Merge f7480da into 8f8d5e6

docs/api-reference/lights/ambient-light.md

@@ -0,0 +1,27 @@
+# AmbientLight
+
+Create an ambient light source which illuminates all the objects equally.Ambient light comes from all directions, adding ambient light ensures that object colors are rendered but does not show structure in 3D objects like directional and point lights do. Only one ambient light is supported.
+
+
+## Usage
+
+Create an ambient light source with color and intensity.
+```js
+const ambientLight= new AmbientLight({
+  color: [128, 128, 0],
+  intensity: 2.0
+});
+```
+
+## Methods
+
+### constructor
+
+The constructor for the `AmbientLight` class. Use this to create a new `AmbientLight`.
+
+```js
+const ambientLight = new AmbientLight({color, intensity});
+```
+
+* `color` - (*array*,)  RGB color of ambient light source, default value is `[255, 255, 255]`.
+* `intensity` - (*number*) Strength of ambient light source, default value is `1.0`.

docs/api-reference/lights/directional-light.md

@@ -0,0 +1,29 @@
+# DirectionalLight
+
+Create a directional light source which emits from a specific direction.A directional light can be considered "infinitely" far away (like the Sun) and does not attenuate with distance. At most 5 directional lights can be supported.
+
+
+## Usage
+
+Create a directional light source with color, intensity and direction.
+```js
+const directionalLight= new DirectionalLight({
+  color: [128, 128, 0],
+  intensity: 2.0,
+  direction: [0, -100, -100]
+});
+```
+
+## Methods
+
+### constructor
+
+The constructor for the `DirectionalLight` class. Use this to create a new `DirectionalLight`.
+
+```js
+const directionalLight = new DirectionalLight({color, intensity, direction});
+```
+
+* `color` - (*array*,)  RGB color of directional light source, default value is `[255, 255, 255]`.
+* `intensity` - (*number*) Strength of directional light source, default value is `1.0`.
+* `direction` - (*array*,)  3D vector specifies the direction the light comes from, default value is `[0, 0, -1]`.

docs/api-reference/lights/point-light.md

@@ -0,0 +1,30 @@
+# PointLight
+
+Create a point light source which emits from a point in all directions.Point lights attenuation is not available. At most 5 directional lights can be supported.
+
+
+## Usage
+
+Create a point light source with color, intensity and position.
+```js
+const pointLight= new PointLight({
+  color: [128, 128, 0],
+  intensity: 2.0,
+  position: [0, 0, 200]
+});
+```
+
+## Methods
+
+### constructor
+
+The constructor for the `PointLight` class. Use this to create a new `PointLight`.
+
+```js
+const pointLight = new PointLight({color, intensity, position});
+```
+#### Parameters
+
+* `color` - (*array*,)  RGB color of point light source, default value is `[255, 255, 255]`.
+* `intensity` - (*number*) Strength of point light source, default value is `1.0`.
+* `position` - (*array*,)  Location of point light source, default value is `[0, 0, 1]`.Coordinate system is the same as that in [view state](/docs/api-reference/view.md#viewstate-string-object-null).

docs/developer-guide/using-lighting.md

@@ -0,0 +1,139 @@
+# Guide to Using Lighting Effect
+
+A deck.gl lighting effect is a visual approximation of environment illumination based on simplified models to make rendering appear more realistic.
+
+To enable lighting in deck.gl, it is required that both the lighting effect and material instances are properly instantiated.
+
+## Constructing Lighting Effect Instance
+
+A [LightingEffect](/docs/effects/lighting-effect.md) can be instantiated with a `lights` object:
+
+```js
+import {AmbientLight, PointLight, DirectionalLight, LightingEffect} from '@deck.gl/core';
+
+// create ambient light source
+const ambientLight = new AmbientLight({
+  color: [255, 255, 255],
+  intensity: 1.0
+});
+// create point light source
+const pointLight = new PointLight({
+  color: [255, 255, 255],
+  intensity: 2.0,
+  // use coordinate system as the same as view state
+  position: [-125, 50.5, 5000]
+});
+// create directional light source
+const directionalLight = new DirectionalLight({
+  color: [255, 255, 255],
+  intensity: 1.0,
+  direction: [-3, -9, -1]
+});
+// create lighting effect with light sources
+const lightingEffect = new LightingEffect({ambientLight, pointLight, directionalLight});
+```
+
+The `lights` has all the light sources that the lighting effect uses to build the visualization. Users typically specify the following types of light sources:
+
+* [AmbientLight](/docs/api-reference/lights/ambient-light.md)
+* [PointLight](/docs/api-reference/lights/point-light.md)
+* [DirectionalLight](/docs/api-reference/lights/directional-light.md)
+
+
+## Constructing Material Instance
+
+A material represents a lighting model specified per layer, a [PhongMaterial](http://uber.github.io/luma.gl/#/documentation/api-reference/phong-material)
+can be instantiated with model parameters.
+
+```js
+import {PhongMaterial} from '@luma.gl/core';
+
+const material =  new PhongMaterial({
+  ambient: 0.2,
+  diffuse: 0.5,
+  shininess: 32,
+  specularColor: [255, 255, 255]
+});
+```
+
+
+## Using Material Instance
+
+To enable lighting for a layer, material prop is required.
+
+```js
+new GeoJsonLayer({
+  id: 'geojson-layer',
+  // layer props
+  ...
+  // lighting only applies to extruded polygons
+  extruded: true,
+  // specify material properties per layer
+  material
+});
+```
+Refer to each layer's [documentation](/docs/layers/README.md) to see if the material prop is supported.
+
+## Using Effect Instance
+To enable lighting in deck.gl, [effects prop](/docs/api-reference/deck.md#effects-array-) is required
+### Pure JS
+
+```js
+import {Deck, LightingEffect} from '@deck.gl/core';
+import {GeoJsonLayer} from '@deck.gl/layers';
+
+const lightingEffect = new LightingEffect({
+  ...
+});
+
+const INITIAL_VIEW_STATE = {
+  latitude: 49.254,
+  longitude: -123.13,
+  zoom: 11,
+  pitch: 45
+};
+const deckgl = new Deck({
+  canvas: 'my-deck-canvas',
+  initialViewState: INITIAL_VIEW_STATE,
+  controller: true,
+  // add lighting effect to deck
+  effects: [lightingEffect],
+  layers: [new GeoJsonLayer({
+    ...
+  })]
+});
+```
+
+### React
+
+```js
+import DeckGL from '@deck.gl/react';
+import {LightingEffect} from '@deck.gl/core';
+import {GeoJsonLayer} from '@deck.gl/layers';
+
+const lightingEffect = new LightingEffect({
+  ...
+});
+
+const INITIAL_VIEW_STATE = {
+  latitude: 49.254,
+  longitude: -123.13,
+  zoom: 11,
+  pitch: 45
+};
+
+<DeckGL
+  initialViewState={INITIAL_VIEW_STATE}
+  controller={true}
+  effects={[lightingEffect]}
+  layers={[new GeoJsonLayer({
+    ...
+  })]}
+/>
+```
+
+## Remarks
+
+* A default lighting effect is created in deck when user doesn't provide one.
+* A default material is created in layers which support material prop.
+* Lighting is only applied to extruded polygons or point clouds.

docs/effects/lighting-effect.md

@@ -2,87 +2,28 @@
 
 The Lighting Effect applies ambient, point and directional lighting to layers which support material property.
 
-```js
-import DeckGL, {GeoJsonLayer, LightingEffect} from '@deck.gl/core';
-import {AmbientLight, PointLight, DirectionalLight, PhongMaterial} from '@luma.gl/core';
-
-// create ambient light source
-const ambientLight = new AmbientLight({
-  color: [255, 255, 255],
-  intensity: 1.0
-});
-// create point light source
-const pointLight = new PointLight({
-  color: [255, 255, 255],
-  intensity: 2.0,
-  // use coordinate system as the same as view state
-  position: [-125, 50.5, 5000]
-});
-// create directional light source
-const directionalLight = new DirectionalLight({
-  color: [255, 255, 255],
-  intensity: 1.0,
-  direction: [-3, -9, -1]
-});
-
-const lightingEffect = new LightingEffect({ambientLight, pointLight, directionalLight});
-
-const material =  new PhongMaterial({
-  ambient: 0.2,
-  diffuse: 0.5,
-  shininess: 32,
-  specularColor: [255, 255, 255]
-});
-
-const INITIAL_VIEW_STATE = {
-  latitude: 49.254,
-  longitude: -123.13,
-  zoom: 11,
-  pitch: 45
-};
-
-const deckgl = new Deck({
-  canvas: 'my-deck-canvas',
-  initialViewState: INITIAL_VIEW_STATE,
-  controller: true,
-  // add lighting effect to deck
-  effects: [lightingEffect],
-  layers: [
-    new GeoJsonLayer({
-        id: 'geojson-layer',
-        // layer props
-        ...
-        // lighting only applies to extruded polygons
-        extruded: true,
-        // specify material properties per layer
-        material
-    })
-  ]
-});
-```
-
 ## Constructor
 
 ```js
 new LightingEffect({light0, light1, light2, ...});
 ```
 
 Parameters:
-* `props`(Object) - a collection of light sources. Keys can be any arbitrary name and values are instances of [LightSource](https://github.com/uber/luma.gl/tree/master/modules/core/src/lighting/light-source.js).
+* `lights`(Object) - a collection of light sources. Keys can be any arbitrary name and values are instances of [LightSource](https://github.com/uber/luma.gl/tree/master/modules/core/src/lighting/light-source.js).
 
-## Properties
+## Members
 
 ### Light Sources
 
 ##### `ambientLight` (Object, optional)
 
-An ambient light source which illuminates all the objects equally.
+An [AmbientLight](/docs/api-reference/lights/ambient-light.md) source which illuminates all the objects equally.
 
 * Default: ambient light source with color = `[255, 255, 255]` and intensity = `1.0`
 
 ##### `directionalLights` (Array, optional)
 
-Array of Directional light source which emits from a specific directions.
+Array of [DirectionalLight](/docs/api-reference/lights/directional-light.md) source which emits from a specific directions.
 
 * Default: two directional light sources
 
@@ -93,22 +34,14 @@ Array of Directional light source which emits from a specific directions.
 
 ##### `pointLights` (Array, optional)
 
-Array of point light source which emits from a point in all directions.
+Array of [PointLight](/docs/api-reference/lights/point-light.md) source which emits from a point in all directions.
 
 * Default: `[]`
 
 ## Remarks
 
 * Only one ambient light is supported.
 * Point light position uses the same coordinate system as view state.
-* To enable lighting on a layer, it is required that both the [effects prop of Deck](/docs/api-reference/deck.md#effects) and the material prop of the layer are specified. Refer to each layer's documentation to see if the lighting effect is supported.
-    * [GeoJsonLayer](/docs/layers/geojson-layer.md)
-    * [HexagonLayer](/docs/layers/hexagon-layer.md)
-    * [ColumnLayer](/docs/layers/column-layer.md)
-    * [GridLayer](/docs/layers/grid-layer.md)
-    * [GridCellLayer](/docs/layers/grid-cell-layer.md)
-    * [PointCloudLayer](/docs/layers/point-cloud-layer.md)
-    * [PolygonLayer](/docs/layers/polygon-layer.md)
 
 ## Source
 

docs/layers/column-layer.md

@@ -136,6 +136,7 @@ Whether the layer should be rendered in high-precision 64-bit mode. Note that si
 * Default: `new PhongMaterial()`
 
 This is an object that contains material props for [lighting effect](/docs/effects/lighting-effect.md) applied on extruded polygons.
+Check [PhongMaterial](http://uber.github.io/luma.gl/#/documentation/api-reference/phong-material) for more details.
 
 ### Data Accessors
 

docs/layers/geojson-layer.md

@@ -218,7 +218,7 @@ Whether the layer should be rendered in high-precision 64-bit mode. Note that si
 * Default: `new PhongMaterial()`
 
 This is an object that contains material props for [lighting effect](/docs/effects/lighting-effect.md) applied on extruded polygons.
-
+Check [PhongMaterial](http://uber.github.io/luma.gl/#/documentation/api-reference/phong-material) for more details.
 
 ### Data Accessors
 

docs/layers/gpu-grid-layer.md

@@ -125,6 +125,7 @@ Whether the layer should be rendered in high-precision 64-bit mode
 * Default: `new PhongMaterial()`
 
 This is an object that contains material props for [lighting effect](/docs/effects/lighting-effect.md) applied on extruded polygons.
+Check [PhongMaterial](http://uber.github.io/luma.gl/#/documentation/api-reference/phong-material) for more details.
 
 ### Data Accessors
 

docs/layers/grid-cell-layer.md

@@ -115,6 +115,7 @@ Whether the layer should be rendered in high-precision 64-bit mode. Note that si
 * Default: `new PhongMaterial()`
 
 This is an object that contains material props for [lighting effect](/docs/effects/lighting-effect.md) applied on extruded polygons.
+Check [PhongMaterial](http://uber.github.io/luma.gl/#/documentation/api-reference/phong-material) for more details.
 
 ### Data Accessors
 

docs/layers/grid-layer.md

@@ -179,6 +179,7 @@ Whether the layer should be rendered in high-precision 64-bit mode. Note that si
 * Default: `new PhongMaterial()`
 
 This is an object that contains material props for [lighting effect](/docs/effects/lighting-effect.md) applied on extruded polygons.
+Check [PhongMaterial](http://uber.github.io/luma.gl/#/documentation/api-reference/phong-material) for more details.
 
 ### Data Accessors
 

docs/layers/h3-hexagon-layer.md

@@ -129,7 +129,7 @@ Whether the layer should be rendered in high-precision 64-bit mode. Note that si
 * Default: `new PhongMaterial()`
 
 This is an object that contains material props for [lighting effect](/docs/effects/lighting-effect.md) applied on extruded polygons.
-
+Check [PhongMaterial](http://uber.github.io/luma.gl/#/documentation/api-reference/phong-material) for more details.
 
 ### Data Accessors