From 77a239fff415939ee8f4bf174307aee745af8f47 Mon Sep 17 00:00:00 2001 From: Xiaoji Chen Date: Fri, 20 Apr 2018 09:27:03 -0700 Subject: [PATCH] Documentation Formats (#1722) --- .markdownlintrc | 2 + docs/README.md | 3 +- docs/advanced/64-bits.md | 23 +- docs/advanced/attribute-management.md | 6 +- docs/advanced/composite-layers.md | 12 +- docs/advanced/coordinate-systems.md | 3 +- docs/advanced/custom-layers.md | 4 + docs/advanced/layer-lifecycle.md | 8 +- docs/advanced/performance.md | 6 +- docs/advanced/picking.md | 24 +- docs/advanced/primitive-layers.md | 19 +- docs/advanced/prop-types.md | 4 +- docs/advanced/subclassed-layers.md | 7 +- docs/advanced/tips-and-tricks.md | 4 +- docs/advanced/updates.md | 11 +- docs/advanced/views.md | 7 + docs/advanced/writing-shaders.md | 5 +- docs/api-reference/attribute-manager.md | 97 +++--- docs/api-reference/base-layer.md | 3 - docs/api-reference/composite-layer.md | 45 ++- docs/api-reference/deck.md | 161 +++++---- docs/api-reference/deckgl.md | 3 - docs/api-reference/first-person-state.md | 44 +-- docs/api-reference/first-person-view.md | 27 +- docs/api-reference/first-person-viewport.md | 37 +- docs/api-reference/internal/layer-manager.md | 103 ++++-- docs/api-reference/layer-manager.md | 3 - docs/api-reference/layer.md | 190 ++++++----- docs/api-reference/map-controller.md | 12 +- docs/api-reference/orthographic-view.md | 39 ++- docs/api-reference/orthographic-viewport.md | 55 +-- docs/api-reference/perspective-view.md | 33 +- docs/api-reference/perspective-viewport.md | 50 +-- docs/api-reference/react/deckgl.md | 182 +++++----- .../react/viewport-controller.md | 138 ++++++-- docs/api-reference/standalone/deckgl.md | 4 + docs/api-reference/test-utils/render-test.md | 39 +-- .../test-utils/scene-renderer.md | 44 +-- docs/api-reference/test-utils/test-layer.md | 25 +- docs/api-reference/third-person-view.md | 27 +- docs/api-reference/third-person-viewport.md | 41 ++- docs/api-reference/view.md | 65 ++-- docs/api-reference/viewport.md | 116 ++++--- docs/api-reference/web-mercator-viewport.md | 109 +++--- docs/developer-guide/building-apps.md | 8 +- docs/developer-guide/testing/README.md | 8 +- docs/developer-guide/testing/testing.md | 2 + .../using-with-unit-test-frameworks.md | 1 + docs/get-started/getting-started.md | 18 +- docs/get-started/interactivity.md | 12 +- docs/get-started/using-layers.md | 2 +- docs/get-started/using-standalone.md | 3 +- docs/get-started/using-with-mapbox-gl.md | 3 +- docs/get-started/using-with-react.md | 1 + docs/layers/README.md | 2 +- docs/layers/arc-layer.md | 18 +- docs/layers/geojson-layer.md | 44 +-- docs/layers/grid-cell-layer.md | 18 +- docs/layers/grid-layer.md | 45 ++- docs/layers/hexagon-cell-layer.md | 16 +- docs/layers/hexagon-layer.md | 42 +-- docs/layers/icon-layer.md | 30 +- docs/layers/line-layer.md | 16 +- docs/layers/path-layer.md | 24 +- docs/layers/point-cloud-layer.md | 18 +- docs/layers/polygon-layer.md | 44 ++- docs/layers/scatterplot-layer.md | 24 +- docs/layers/screen-grid-layer.md | 16 +- docs/layers/solid-polygon-layer.md | 24 +- docs/layers/text-layer.md | 13 +- docs/roadmap.md | 3 + docs/shader-modules/lighting.md | 2 +- docs/shader-modules/project.md | 5 +- docs/shader-modules/project32.md | 9 +- docs/shader-modules/project64.md | 9 +- docs/upgrade-guide.md | 9 +- docs/whats-new.md | 321 +++++++++--------- package.json | 2 +- scripts/test.sh | 1 + 79 files changed, 1515 insertions(+), 1138 deletions(-) delete mode 100644 docs/api-reference/base-layer.md delete mode 100644 docs/api-reference/deckgl.md delete mode 100644 docs/api-reference/layer-manager.md diff --git a/.markdownlintrc b/.markdownlintrc index a2ac9795266..9162a441803 100644 --- a/.markdownlintrc +++ b/.markdownlintrc @@ -1,8 +1,10 @@ { "default": true, "colors": true, + "header-increment": false, "line-length": false, "ul-style": {"style": "sublist"}, + "no-trailing-punctuation": {"punctuation": ".,;:"}, "no-duplicate-header": false, "no-inline-html": false, "no-hard-tabs": false, diff --git a/docs/README.md b/docs/README.md index 1e848ea2b97..44c95e784fe 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@

These docs are for - + Looking for an old version? @@ -27,6 +27,7 @@ deck.gl is designed to make visualization of large data sets simple. It enables The basic idea of using deck.gl is to render a stack of visual overlays, usually (but not always) over maps. To make this simple concept work, deck.gl handles a number of challenges: + * Handling of large data sets and performant updates * Interactive event handling such as picking * Cartographic projections and integration with underlying map diff --git a/docs/advanced/64-bits.md b/docs/advanced/64-bits.md index 6720973091a..c910478ecf5 100644 --- a/docs/advanced/64-bits.md +++ b/docs/advanced/64-bits.md @@ -29,15 +29,16 @@ float point numbers. This transfers to ~ `1x10^-15` relative error within The error bound as tested on 2015 MacBook Pro with AMD Radeon R9 M370X GPU: -``` -Addition and subtraction: < 1 ulp -Multiplication: ~1.5 ulps -Division: ~2 ulps -Square root: ~2.6 ulps -Exponential: ~2.6 ulps -Logarithm: ~11.6 ulps -Trigonometry: ~5 ulps -``` +| Operation | Error | +| ---- | ---- | +| Addition and subtraction | < 1 ulp | +| Multiplication | ~1.5 ulps | +| Division | ~2 ulps | +| Square root | ~2.6 ulps | +| Exponential | ~2.6 ulps | +| Logarithm | ~11.6 ulps | +| Trigonometry | ~5 ulps | + Note: `ulp` = [unit of least precision](https://en.wikipedia.org/wiki/Unit_in_the_last_place) ## Performance Implications @@ -58,5 +59,5 @@ performance benchmark layers in the layer-browser example in deck.gl repo. ## References -- http://crd-legacy.lbl.gov/~dhbailey/mpdist -- https://gmplib.org +* [http://crd-legacy.lbl.gov/~dhbailey/mpdist](http://crd-legacy.lbl.gov/~dhbailey/mpdist) +* [https://gmplib.org](https://gmplib.org) diff --git a/docs/advanced/attribute-management.md b/docs/advanced/attribute-management.md index d8da71f14b7..be1c5f5821f 100644 --- a/docs/advanced/attribute-management.md +++ b/docs/advanced/attribute-management.md @@ -37,11 +37,11 @@ vertex shader attributes are generated by iteration over a data array, and updates to these attributes are needed either when the data itself changes, or when other data relevant to the calculations change. -- First the application registers descriptions of its dynamic vertex +* First the application registers descriptions of its dynamic vertex attributes using AttributeManager.add(). -- Then, when any change that affects attributes is detected by the +* Then, when any change that affects attributes is detected by the application, the app will call AttributeManager.invalidate(). -- Finally before it renders, it calls AttributeManager.update() to +* Finally before it renders, it calls AttributeManager.update() to ensure that attributes are automatically rebuilt if anything has been invalidated. diff --git a/docs/advanced/composite-layers.md b/docs/advanced/composite-layers.md index 3b5843ac707..f854c816876 100644 --- a/docs/advanced/composite-layers.md +++ b/docs/advanced/composite-layers.md @@ -9,6 +9,7 @@ A composite layer is a special kind of layer that creates other layers. It enabl Sometimes an existing layer renders the right thing, but it would be desirable that it accepts another data format, had another interface (different accessors), or performed aggregation on its data. Examples could be: + * Creating a `LASPointCloudLayer` that accepts `data` as an ArrayBuffer object that is loaded directly from a [LAS](https://www.asprs.org/committee-general/laser-las-file-format-exchange-activities.html) file, and convert it to the format that `PointCloudLayer` consumes. * Creating an `S2Layer` with an accessor that takes [S2](https://code.google.com/archive/p/s2-geometry-library/) tokens, uses the S2 library to calculates the polygons corresponding to that cell, and renders it using e.g. the PolygonLayer. @@ -27,7 +28,7 @@ A common use case of composite layers is to augment the interface of existing la A composite layer can be created by extending the `CompositeLayer` class: -``` +```js import {Layer, ScatterplotLayer} from 'deck.gl'; class NiceScatterplotLayer extends CompositeLayer { @@ -40,7 +41,7 @@ NiceScatterplotLayer.layerName = 'NiceScatterplotLayer'; We will need to define the layer-specific properties of the new layer. In this example, the new layer's interface is almost identical to that of the ScatterplotLayer, except instead of one `getColor` accessor, you need two accessors `getStrokeColor` and `getFillColor`: -``` +```js NiceScatterplotLayer.defaultProps = { ...ScatterplotLayer.defaultProps, getFillColor: d => [255, 255, 0], @@ -56,7 +57,7 @@ By convention, the `id` of sublayers should be the `id` of the composite layer p In this example, the idea is to draw two ScatterplotLayers, one for fill and one on top for the outline: -``` +```js class NiceScatterplotLayer extends CompositeLayer { renderLayers() { return [ @@ -83,7 +84,7 @@ We then want to map the user defined `getFillColor` and `getStrokeColor` accesso Finally, to make [`updateTrigger`](/docs/api-reference/layer.md#-updatetriggers-object-optional-) work when colors need to be recalculated, we will map respective accessor names to `getColor`. -``` +```js class NiceScatterplotLayer extends CompositeLayer { renderLayers() { @@ -124,7 +125,7 @@ By default, the composite layer passes the picking info from its sublayers as-is In this case, The composite layer may intercept the event info and modify it by implementing the `getPickingInfo()` method: -``` +```js class AwesomeCompositeLayer extends CompositeLayer { ... @@ -136,4 +137,5 @@ class AwesomeCompositeLayer extends CompositeLayer { } ``` + For more details, read about [how picking works](/docs/advanced/picking.md). diff --git a/docs/advanced/coordinate-systems.md b/docs/advanced/coordinate-systems.md index 18a09fad828..60760ccc60d 100644 --- a/docs/advanced/coordinate-systems.md +++ b/docs/advanced/coordinate-systems.md @@ -31,6 +31,7 @@ The meter offset system on the other hand is very performant, but uses a lineari The choice of coordinate system can be specified per layer, meaning that different layers can have data with positions specified in "different" coordinate systems. If some care is taken, they can all be rendered and drawn at the same time, and correctly overlaid. An example of a use case where different coordinate systems are combined: + * Render a layer showing 3D buildings could have vertices specified in longitudes and latitudes (simply because available building data sources tend to be encoded this way) * Render layer showing cars or pedestrians moving between the buildings with all positions specified using meter offsets from an anchor point somewhere in the city), because meter offsets are more natural encoding for this data. @@ -55,7 +56,7 @@ Note: deck.gl always calculates a "meters per pixel" scale, allowing the applica ### The modelMatrix -Note that deck.gl only supports **meter** offsets, with y axis aligned with map north. If you like to work in other units (feet, miles etc) or other orientations (y axis pointing south, or at an angle) you should define a `modelMatrix` and build a 4x4 transformation matrix (e.g. using the [math.gl]() library). +Note that deck.gl only supports **meter** offsets, with y axis aligned with map north. If you like to work in other units (feet, miles etc) or other orientations (y axis pointing south, or at an angle) you should define a `modelMatrix` and build a 4x4 transformation matrix (e.g. using the [math.gl](https://uber-web.github.io/math.gl/#/documentation/overview) library). The `modelMatrix` is particularly potent when used with meter offset coordinates (and non-geospatial coordinates, of course) and is usually the right solution for pre-processing (flipping, rotating, scaling etc) your data, since these operations will be done essentially for free in the GPU, rather than having to lock up your main thread for seconds after each load to transform your "big data" using JavaScript on the CPU. diff --git a/docs/advanced/custom-layers.md b/docs/advanced/custom-layers.md index ef2d3f1ebff..a25c1290951 100644 --- a/docs/advanced/custom-layers.md +++ b/docs/advanced/custom-layers.md @@ -12,17 +12,21 @@ There are a couple of ways to build a layer in deck.gl, and it is helpful to con ## Creating The Layer class + Your layer class must be a subclass of [Layer](/docs/api-reference/layer.md). + ```js import {Layer} from 'deck.gl'; class AwesomeLayer extends Layer {...} ``` + It can be a direct subclass of `Layer`, or extend another layer. ### Naming Your Layer Store the layer name in the `layerName` static property on your `Layer` subclass: + ```js AwesomeLayer.layerName = 'AwesomeLayer'; ``` diff --git a/docs/advanced/layer-lifecycle.md b/docs/advanced/layer-lifecycle.md index 5f2bd32ae3e..55d7cc9534f 100644 --- a/docs/advanced/layer-lifecycle.md +++ b/docs/advanced/layer-lifecycle.md @@ -108,20 +108,20 @@ you understand property change management and how to use the Still, there are a couple of notable differences between the lifecycle methods provided by the two frameworks: -- deck.gl performs preliminary analysis on certain props and context and +* deck.gl performs preliminary analysis on certain props and context and provides a `changeFlags` object to your `shouldUpdateState` and `updateState`. -- deck.gl's `updateState` method is called both on layer initialization and +* deck.gl's `updateState` method is called both on layer initialization and on when props or context is updated. This is different from React's `willReceiveProps` that is not called when the component is initially created, The deck.gl model avoids requiring the same property checks to be performed twice in both the constructor and `willReceiveProps`. -- deck.gl separates rendering into the `draw` and `renderLayers` methods, +* deck.gl separates rendering into the `draw` and `renderLayers` methods, where React just needs `render`. -- deck.gl's `pick` and `pickInfo` methods have no correspondence in +* deck.gl's `pick` and `pickInfo` methods have no correspondence in React's lifecycle. **Note**: deck.gl uses a simpler component model than React. diff --git a/docs/advanced/performance.md b/docs/advanced/performance.md index bbaa5866772..21810c5ab64 100644 --- a/docs/advanced/performance.md +++ b/docs/advanced/performance.md @@ -33,6 +33,7 @@ frequently, buffer generation can cause "stutter" in e.g. animations, even for layers with just a few thousand items. While it is usually possible to overcome these issues using special techniques, but it can require extra work. Before optimizing data updates, make sure that: + * you are not modifying the data prop when it hasn't changed. The layer will do a shallow equal to determine if it needs to regenerate buffers. So if nothing has changed, make sure you supply the **same** data object (typically @@ -65,6 +66,7 @@ It is good to be aware that excessive overdraw (drawing many objects/pixels on t deck.gl performs picking by drawing the layer into an off screen picking buffer. This essentially means that every layer that supports picking will be drawn off screen when panning and hovering. The picking is performed using the same GPU code that does the visual rendering, so the performance should be easy to predict. Picking limitations: + * The picking system can only distinguish between 16M items per layer. * The picking system can only handle 256 layers with the pickable flag set to true. @@ -77,15 +79,17 @@ The layer count of an advanced deck.gl application tends to gradually increase, ## Profiling Ideas Some profiling techniques: + * Using the `seer` chrome extension you can also get GPU timings for your layers. * The `layer-browser` example (in the `examples` folder has a couple of performance tests that you can use to get FPS readings on your hardware for Scatterplot layers with 1M and 10M points. ## Common Issues A couple of particular things to watch out for that tend to have a big impact on performance: -* If not needed disable Retina/High DPI rendering. It generetes 4x the number of pixels (fragments) and can have a big performance impact that depends on which computer or monitor is being used. This feature can be controlled using `useDevicePixels` prop of `DeckGL` component and it is on by default. +* If not needed disable Retina/High DPI rendering. It generetes 4x the number of pixels (fragments) and can have a big performance impact that depends on which computer or monitor is being used. This feature can be controlled using `useDevicePixels` prop of `DeckGL` component and it is on by default. * Avoid using luma.gl debug mode in production. It queries the GPU error status after each operation which has a big impact on performance. Smaller considerations: + * Enabling picking can have a small performance penalty so make sure the `pickable` property is `false` in layers that do not need picking (this is the default value). diff --git a/docs/advanced/picking.md b/docs/advanced/picking.md index 42943736972..ddd4f68a038 100644 --- a/docs/advanced/picking.md +++ b/docs/advanced/picking.md @@ -12,8 +12,9 @@ After the picking buffer is rendered, deck.gl looks at the color of the pixel un [`layer.decodePickingColor()`](/docs/api-reference/layer.md#-decodepickingcolor-) to determine which object of the layer has been picked. A `hover` event is triggered on a layer if: -- The layer is picked, and the picked object is different from the last frame -- The layer is not picked, but it was in the last frame + +* The layer is picked, and the picked object is different from the last frame +* The layer is not picked, but it was in the last frame A `click` event is triggered on a layer only if it's picked. @@ -38,6 +39,7 @@ system, which most layers use. To take full control of picking, a layer need to take the following steps: 1. Add a picking color attribute during initialization: + ```js initializeState() { ... @@ -46,8 +48,9 @@ initializeState() { }); } ``` -- Calculate the attribute by providing a different picking color for every object that -you need to differentiate, such as: + +* Calculate the attribute by providing a different picking color for every object that you need to differentiate, such as: + ```js calculatePickingColors(attribute) { const {data} = this.props; @@ -63,20 +66,19 @@ calculatePickingColors(attribute) { } ``` -- The default implementation of [`layer.encodePickingColor()`](/docs/api-reference/layer.md#-encodepickingcolor-) and -[`layer.decodePickingColor()`](/docs/api-reference/layer.md#-decodepickingcolor-) is likely sufficient, but you may need to implement your own pair. -- By default, the `object` field of the picking `info` object is indexed from the layer's `data` prop. Custom layers often need to define on their own terms what constitutes meaningful information to the user's callbacks. A layer can achieve this by overriding [`layer.getPickingInfo()`](/docs/api-reference/layer.md#-getpickinginfo-) to add or modify fields to the `info` object. +* The default implementation of [`layer.encodePickingColor()`](/docs/api-reference/layer.md#-encodepickingcolor-) and [`layer.decodePickingColor()`](/docs/api-reference/layer.md#-decodepickingcolor-) is likely sufficient, but you may need to implement your own pair. +* By default, the `object` field of the picking `info` object is indexed from the layer's `data` prop. Custom layers often need to define on their own terms what constitutes meaningful information to the user's callbacks. A layer can achieve this by overriding [`layer.getPickingInfo()`](/docs/api-reference/layer.md#-getpickinginfo-) to add or modify fields to the `info` object. ## Implementing Picking in Custom Shaders All core layers (including composite layers) support picking using luma.gl's `picking module`. If you are using custom shaders with any of the core layers or building custom layers with your own shaders following steps are needed to achieve `Picking`. -### Model object creation. +### Model object creation When creating `Model` object, add picking module to `modules` array. -``` +```js new Model(gl, { ... vs: CUSTOM_VS, @@ -89,7 +91,7 @@ new Model(gl, { Vertex shader should set current picking color using `picking_setPickingColor` method provided by picking shader module. -``` +```glsl attribute vec3 instancePickingColors; void main(void) { @@ -105,7 +107,7 @@ void main(void) { Fragment shader should use `picking_filterPickingColor` to update `gl_FragColor`, which outputs picking color if it is the picking pass. -``` +```glsl attribute vec3 instancePickingColors; void main(void) { diff --git a/docs/advanced/primitive-layers.md b/docs/advanced/primitive-layers.md index ed1660f63e0..ca58b429b79 100644 --- a/docs/advanced/primitive-layers.md +++ b/docs/advanced/primitive-layers.md @@ -54,7 +54,8 @@ be instanced, or use dynamic geometry: the same geometry many times. Usually the simplest way to go when creating layers that renders a lot of similar objects (think ScatterplotLayer, ArcLayers etc). - ``` + +```js /// examples/sample-layers/mesh-layer/mesh-layer.js import {GL, Model, Geometry} from 'luma.gl'; @@ -72,12 +73,14 @@ be instanced, or use dynamic geometry: isInstanced: true })); } - ``` +``` + * **Dynamic geometry layer** - This is needed when dealing with data that needs to be rendered using multiple similar but unique geometries, such as polygons (i.e. the geometries are not copies of each othat that only differ in terms of. - ``` + +```js /// examples/trips/trips-layer/trips-layer.js import {GL, Model, Geometry} from 'luma.gl'; @@ -92,13 +95,13 @@ be instanced, or use dynamic geometry: isIndexed: true }); } - ``` +``` It sometimes desirable to have a single layer render using multiple geometry primitives (e.g both circles and lines, or triangles and textured meshes etc), rather than creating separate layers. The custom -[AxesLayer example](https://github.com/uber/deck.gl/tree/5.1-release/examples/plot/plot-layer/axes-layer.js) +[AxesLayer example](https://github.com/uber/deck.gl/tree/5.2-release/examples/plot/plot-layer/axes-layer.js) uses this technique to share attributes between grids and labels. #### Defining Attributes @@ -110,7 +113,7 @@ A layer should also define its attributes during initialization. This allows the Define attributes by calling [`attributeManager.add`](/docs/api-reference/attribute-manager.md#-add-): -``` +```js initializeState() { const {gl} = this.context; this.setState({ @@ -194,12 +197,12 @@ that support all three deck.gl projection modes: latlon (default), meters and ne By always using the following shader functions for handling projections and scaling, a single layer class can support all projection modes for free: -- All positions must be passed through the `project_position` function +* All positions must be passed through the `project_position` function (available both in JavaScript and GLSL) to convert non-linear web-mercator coordinates to linear mercator "world" or "pixel" coordinates, that can be passed to the projection matrix. -- All offsets must be passed through the `project_scale` function +* All offsets must be passed through the `project_scale` function (available both in JavaScript and GLSL) to convert distances to world coordinates (note that that distance scales are latitude dependent under web mercator projection diff --git a/docs/advanced/prop-types.md b/docs/advanced/prop-types.md index d43381d66ef..9c13bf5db2c 100644 --- a/docs/advanced/prop-types.md +++ b/docs/advanced/prop-types.md @@ -6,6 +6,7 @@ This article documents the system that deck.gl offers to provide extra type annotations for layer properties. For a number of reasons it is useful to have access to descriptions of the types of the various properties in a layer. + * Enable specification of advanced (e.g. async) properties * Transitions and Animation * Type Checking (during development) @@ -32,5 +33,6 @@ const defaultProps = { ``` Tips: + * **Open Ranges** - It's unnecessary use `Math.MAX_` constants for open numeric ranges, just leave the max or min out to specify an open range. -``` + diff --git a/docs/advanced/subclassed-layers.md b/docs/advanced/subclassed-layers.md index 0eb29eda68f..8721ddaa9f3 100644 --- a/docs/advanced/subclassed-layers.md +++ b/docs/advanced/subclassed-layers.md @@ -60,9 +60,10 @@ export default MultiColorPathLayer extends PathLayer { You can replace the shaders used in a layer by overriding the `getShaders()` method. Every core layer calls this method during initialization. It returns the shaders and modules used by the layer in an object: -- `vs`: string, GLSL source of the vertex shader -- `fs`: string, GLSL source of the fragment shader -- `modules`: Array, list of shader modules to be used + +* `vs`: string, GLSL source of the vertex shader +* `fs`: string, GLSL source of the fragment shader +* `modules`: Array, list of shader modules to be used Read about [writing your own shaders](/docs/advanced/writing-shaders.md). diff --git a/docs/advanced/tips-and-tricks.md b/docs/advanced/tips-and-tricks.md index 3176de71e6a..59bcb645fa2 100644 --- a/docs/advanced/tips-and-tricks.md +++ b/docs/advanced/tips-and-tricks.md @@ -58,7 +58,7 @@ support. * In the browser console, setting `luma.log.priority` to various values will enable increasing levels of debugging. - - **Level 3** will display all uniforms and attributes before each draw + + **Level 3** will display all uniforms and attributes before each draw call, allowing you to be confident in what values your shaders are actually working on. - - **Level 4** will trace every single gl call. + + **Level 4** will trace every single gl call. diff --git a/docs/advanced/updates.md b/docs/advanced/updates.md index 56389e54012..0b37c8158f1 100644 --- a/docs/advanced/updates.md +++ b/docs/advanced/updates.md @@ -7,10 +7,10 @@ One of the keys to getting good performance and desired behavior from deck.gl is Before jumping into the details, it might be helpful review the reactive programming paradigm that the deck.gl is architecture is based on: -- In a reactive application, a complete UI description is "re-rendered" every time something in the application state changes (in the case of a deck.gl application, a new list of layers is created whenever something changes). -- The UI framework (in this case, deck.gl) makes the choices about what to update, by comparing (or "diffing") the newly rendered UI description with the last rendered UI description. -- The framework then the makes minimal necessary changes to account for the differences, and then redraws. -- The required changes are made to "WebGL state" in case of deck.gl, and to the Browser's DOM (HTML element tree) in case of React. +* In a reactive application, a complete UI description is "re-rendered" every time something in the application state changes (in the case of a deck.gl application, a new list of layers is created whenever something changes). +* The UI framework (in this case, deck.gl) makes the choices about what to update, by comparing (or "diffing") the newly rendered UI description with the last rendered UI description. +* The framework then the makes minimal necessary changes to account for the differences, and then redraws. +* The required changes are made to "WebGL state" in case of deck.gl, and to the Browser's DOM (HTML element tree) in case of React. ## Creating New Layers on Every Render? @@ -46,6 +46,7 @@ Once a `data` change has been confirmed by deck.gl it will invalidate all attrib Accessors. Note that changing the value of an accessor (i.e. supplying a different function to the accessor prop) will not in itself trigger an attribute update. This is because the function identity is a poor indicator of whether an update is needed, and the convenience of using local functions as prop values. Thus, the code below will not trigger expensive attribute updates, which is what most applications would expect + ```js new Layer({ getColor: x => x.color, // this creates a new function every render @@ -54,6 +55,7 @@ new Layer({ ``` However, neither will this code + ```js new Layer({ getColor: pill === 'red' ? this._getRedPill() : this._getBluePill(), // Does not trigger an attribute update!!! @@ -79,6 +81,7 @@ new Layer({ } }) ``` + In the above code, deck.gl compares the value of the `getColor` update trigger with its previous value on every render, and whenever it changes, it will regenerate the colors attribute using the function supplied to `getColor` at that time. diff --git a/docs/advanced/views.md b/docs/advanced/views.md index 5f11a07a70a..88268f7c394 100644 --- a/docs/advanced/views.md +++ b/docs/advanced/views.md @@ -8,6 +8,7 @@ Note that if no `View` is specified, deck.gl will automatically create a `MapVie ## What is in a View? A view specifies + * an `id` * relative extents (x, y, width, height) * projection mode and parameters (e.g. perspective vs. orthographic) @@ -44,6 +45,7 @@ The `View` class allows the application full control of what projection to use t While the projections suggested in the table leverage stock methods in the math.gl library, custom projection functions can be provided. The `View.projection` prop accepts any function that returns a 4x4 projection matrix. The function will be called with the `View`s props, merged with `width`, `height`, `aspect` and `distance`. A perspective / orthographic mode switch could be implemented as follows: + ```js import {View} from 'deck.gl'; import {Matrix4} from 'math.gl'; @@ -85,6 +87,7 @@ While a `View` by itself does not contain enough information to support projecti The main deck.gl component (i.e. `Deck`, or `DeckGL` if using React) takes a `view` prop that accepts a list of `View` instances. Common examples in 3D applications that render a 3D scene multiple times with different "cameras": + * To show views from multiple viewpoints (cameras), e.g. in a split screen setup. * To show a detail view (e.g, first person), and an overlaid, smaller "map" view (e.g. third person or top down, zoomed out to show where the primary viewpoint is). * To support stereoscopic rendering, where left and right views are needed, providing the necessary parallax between left and right eye. @@ -92,6 +95,7 @@ Common examples in 3D applications that render a 3D scene multiple times with di Views can be side-by-side (top and bottom in this first example). Note how the application controls both the height and the y position of the two views. + ```js React Note: If you are using React, you should not use this component directly. Instead you should be rendering the [`DeckGL` React Component](docs/api-reference/react/deckgl.md) +`Deck` is a class that takes deck.gl layer instances and viewport parameters, renders those layers as a transparent overlay, and handles events. -`Deck` is a class that takes deck.gl layer instances and viewport parameters, and renders those layers as a transparent overlay. - -* Picking methods are supplied to enable applications to use their own event handling. - -* TBA - child handling from react component. +If you are using React, you should not use this component directly. Instead you should be rendering the [`DeckGL` React Component](docs/api-reference/react/deckgl.md). ## Usage -// Basic standalone use ```js +// Basic standalone use import {Deck, ScatterplotLayer} from 'deck.gl'; const App = (viewState, data) => ( @@ -23,61 +19,21 @@ const App = (viewState, data) => ( ); ``` -### Methods -##### constructor +## Constructor Creates a new Deck instance. -`new Deck(props)` - - -##### delete - -Frees resources associated with this object immediately. - - -##### setProps - -Updates properties - -`deck.setProps({...});` - - -##### pickObject - -Get the closest pickable and visible object at screen coordinate. - -`deck.pickObject({x, y, radius, layerIds})` - -* `x` (Number) - x position in pixels -* `y` (Number) - y position in pixels -* `radius` (Number, optional) - radius of tolerance in pixels. Default `0`. -* `layerIds` (Array, optional) - a list of layer ids to query from. If not specified, then all pickable and visible layers are queried. - -Returns: a single [`info`](/docs/get-started/interactivity.md#the-picking-info-object) object, or `null` if nothing is found. - - -##### pickObjects - -Get all pickable and visible objects within a bounding box. - -`deck.pickObjects({x, y, width, height, layerIds})` +````js +const deck = new Deck(props); +``` Parameters: -* `x` (Number) - left of the bounding box in pixels -* `y` (Number) - top of the bouding box in pixels -* `width` (Number, optional) - width of the bouding box in pixels. Default `1`. -* `height` (Number, optional) - height of the bouding box in pixels. Default `1`. -* `layerIds` (Array, optional) - a list of layer ids to query from. If not specified, then all pickable and visible layers are queried. -Returns: an array of unique [`info`](/docs/get-started/interactivity.md#the-picking-info-object) objects +See the [Properties](#properties) section. -Remarks: -- This query methods are designed to quickly find objects by utilizing the picking buffer. They offer more flexibility for developers to handle events in addition to the built-in hover and click callbacks. -- Note there is a limitation in the query methods: occluded objects are not returned. To improve the results, you may try setting the `layerIds` parameter to limit the query to fewer layers. -### Properties +## Properties ##### `width` (Number, required) @@ -100,12 +56,14 @@ Optionally takes a function `({layer, viewport, isPicking}) => Boolean` that is A single `View`, or an array of [`View`](/docs/api-reference/view.md) instances (optionally mixed with [`Viewport`](/docs/api-reference/viewport.md) instances, although the latter is deprecated). If not supplied, a single `MapView` will be created. If an empty array is supplied, no `View` will be shown. Remarks: + * During render and picking, deck.gl will render all the `View`s in the supplied order, this can matter if they overlap. * `View`s represent your "camera(s)" (essentially view and projection matrices, together with viewport width and height). By changing the `views` property you change the view of your layers. -#### `viewState` (Object) +##### `viewState` (Object) A geospatial `viewState` would typically contain the following fields: + * `latitude` (Number, optional) - Current latitude - used to define a mercator projection if `viewport` is not supplied. * `longitude` (Number, optional) - Current longitude - used to define a mercator projection if `viewport` is not supplied. * `zoom` (Number, optional) - Current zoom - used to define a mercator projection if `viewport` is not supplied. @@ -113,7 +71,7 @@ A geospatial `viewState` would typically contain the following fields: * `pitch` (Number, optional) - Current pitch - used to define a mercator projection if `viewport` is not supplied. -#### Configuration Properties +### Configuration Properties ##### `id` (String, optional) @@ -133,7 +91,9 @@ When true, device's full resolution will be used for rendering, this value can c Default value is `true`. -Note: Consider setting to `false` unless you require high resolution, as it affects rendering performance. +Note: + +* Consider setting to `false` unless you require high resolution, as it affects rendering performance. ##### `gl` (Object, optional) @@ -145,41 +105,110 @@ Flag to enable debug mode. Default value is `false`. -Note: debug mode is somewhat slower as it will use synchronous operations to keep track of GPU state. +Note: + +* debug mode is somewhat slower as it will use synchronous operations to keep track of GPU state. + +### Event Callbacks ##### `onWebGLInitialized` (Function, optional) Callback, called once the WebGL context has been initiated Callback arguments: -- `gl` - the WebGL context. + +* `gl` - the WebGL context. ##### `onLayerHover` (Function, optional) Callback - called when the object under the pointer changes. Callback Arguments: -- `info` - the [`info`](/docs/get-started/interactivity.md#the-picking-info-object) + +* `info` - the [`info`](/docs/get-started/interactivity.md#the-picking-info-object) object for the topmost picked layer at the coordinate, null when no object is picked. -- `pickedInfos` - an array of info objects for all pickable layers that +* `pickedInfos` - an array of info objects for all pickable layers that are affected. -- `event` - the original [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object +* `event` - the original [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object ##### `onLayerClick` (Function, optional) Callback - called when clicking on the layer. Callback Arguments: -- `info` - the [`info`](/docs/get-started/interactivity.md#the-picking-info-object) + +* `info` - the [`info`](/docs/get-started/interactivity.md#the-picking-info-object) object for the topmost picked layer at the coordinate, null when no object is picked. -- `pickedInfos` - an array of info objects for all pickable layers that are affected. -- `event` - the original [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object +* `pickedInfos` - an array of info objects for all pickable layers that are affected. +* `event` - the original [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object + + +## Methods + +##### `delete` + +Frees resources associated with this object immediately. + + +##### `setProps` + +Updates properties + +```js +deck.setProps({...}); +``` + + +##### `pickObject` + +Get the closest pickable and visible object at screen coordinate. + +```js +deck.pickObject({x, y, radius, layerIds}) +``` + +* `x` (Number) - x position in pixels +* `y` (Number) - y position in pixels +* `radius` (Number, optional) - radius of tolerance in pixels. Default `0`. +* `layerIds` (Array, optional) - a list of layer ids to query from. If not specified, then all pickable and visible layers are queried. + +Returns: + +* a single [`info`](/docs/get-started/interactivity.md#the-picking-info-object) object, or `null` if nothing is found. + + +##### `pickObjects` + +Get all pickable and visible objects within a bounding box. + +```js +deck.pickObjects({x, y, width, height, layerIds}) +``` + +Parameters: + +* `x` (Number) - left of the bounding box in pixels +* `y` (Number) - top of the bouding box in pixels +* `width` (Number, optional) - width of the bouding box in pixels. Default `1`. +* `height` (Number, optional) - height of the bouding box in pixels. Default `1`. +* `layerIds` (Array, optional) - a list of layer ids to query from. If not specified, then all pickable and visible layers are queried. + +Returns: + +* an array of unique [`info`](/docs/get-started/interactivity.md#the-picking-info-object) objects + +Remarks: + +* This query methods are designed to quickly find objects by utilizing the picking buffer. They offer more flexibility for developers to handle events in addition to the built-in hover and click callbacks. +* Note there is a limitation in the query methods: + +* occluded objects are not returned. To improve the results, you may try setting the `layerIds` parameter to limit the query to fewer layers. ## Remarks -- Since deck.gl is based on WebGL and uses a single WebGL context, it can only render into a single canvas. Thus all its `View`s will render into the same canvas (unless you use multiple DeckGL instances, but that can have significant resource and performance impact). +* Since deck.gl is based on WebGL and uses a single WebGL context, it can only render into a single canvas. Thus all its `View`s will render into the same canvas (unless you use multiple DeckGL instances, but that can have significant resource and performance impact). ## Source -[src/react/deckgl.js](https://github.com/uber/deck.gl/blob/5.0-release/src/core/deck.js) +[src/react/deckgl.js](https://github.com/uber/deck.gl/blob/5.0-release/modules/core/src/core/deck.js) diff --git a/docs/api-reference/deckgl.md b/docs/api-reference/deckgl.md deleted file mode 100644 index 66c13d079f3..00000000000 --- a/docs/api-reference/deckgl.md +++ /dev/null @@ -1,3 +0,0 @@ -# DeckGL (React Component) - -The documentation for this component has moved to [`DeckGL`](/docs/api-reference/react/deckgl.md). \ No newline at end of file diff --git a/docs/api-reference/first-person-state.md b/docs/api-reference/first-person-state.md index de8e17f1099..0c166f1cced 100644 --- a/docs/api-reference/first-person-state.md +++ b/docs/api-reference/first-person-state.md @@ -3,24 +3,26 @@ ## Constructor Viewport arguments + * `width` - Width of viewport * `height` - Height of viewport Position and orientation -* `position` - typically in meters from anchor point -* `direction`, +* `position` - typically in meters from anchor point +* `direction` * `bearing` - Rotation around y axis * `pitch` - Rotation around x axis Geospatial "anchor" + * `longitude` * `latitude` * `zoom` - * `syncBearing` = true, // Whether to lock bearing to direction Constraints - simple movement limit + * `bounds` - Bounding box of the world, in the shape of {minX, maxX, minY, maxY, minZ, maxZ} Internal Interaction states, required to calculate change during transform @@ -35,19 +37,21 @@ Internal Interaction states, required to calculate change during transform * `startZoom` - Model state when the zoom operation first started +## Methods + Implements a viewState: -##### getViewportProps() +##### `getViewportProps()` -##### getInteractiveState() +##### `getInteractiveState()` -##### panStart({pos}) +##### `panStart({pos})` Start panning `pos` (`[Number, Number]`) - position on screen where the pointer grabs -##### pan({pos, startPos}) +##### `pan({pos, startPos})` Pan @@ -57,19 +61,19 @@ Pan the start of the operation. Must be supplied of `panStart()` was not called -##### panEnd() +##### `panEnd()` End panning Must call if `panStart()` was called -##### rotateStart({pos}) +##### `rotateStart({pos})` Start rotating `pos` (`[Number, Number]`) - position on screen where the center is -##### rotate({deltaScaleX, deltaScaleY}) +##### `rotate({deltaScaleX, deltaScaleY})` Rotate @@ -82,19 +86,19 @@ Rotate change to pitch. -1 sets to minPitch and 1 sets to maxPitch. -##### rotateEnd() +##### `rotateEnd()` End rotating Must call if `rotateStart()` was called -##### zoomStart({pos}) +##### `zoomStart({pos})` Start zooming @param {[Number, Number]} pos - position on screen where the center is -##### zoom({pos, startPos, scale}) +##### `zoom({pos, startPos, scale})` Zoom @@ -109,20 +113,20 @@ Zoom relative scale. assert(scale > 0, '`scale` must be a positive number') -##### zoomEnd() +##### `zoomEnd()` End zooming Must call if `zoomStart()` was called -##### moveLeft() +##### `moveLeft()` -##### moveRight() +##### `moveRight()` -##### moveForward() +##### `moveForward()` -##### moveBackward() +##### `moveBackward()` -##### zoomIn() +##### `zoomIn()` -##### zoomOut() +##### `zoomOut()` diff --git a/docs/api-reference/first-person-view.md b/docs/api-reference/first-person-view.md index 4716ccca3a9..64e6da09941 100644 --- a/docs/api-reference/first-person-view.md +++ b/docs/api-reference/first-person-view.md @@ -13,28 +13,33 @@ const viewport = new FirstPersonView({ }); ``` -## Methods -Inherits all [View methods](/docs/api-reference/viewport.md#methods). +## Constructor -### Constructor +```js +new FirstPersonView({fov: 45, width: 500, height: 500}); +``` Projection matrix arguments: -* `orthographic`=`false` (`Boolean`) - -* `fov`=`75` (`Number`, optional) - Field of view covered by camera. -* `near`=`0.5` (`Number`, optional) - Distance of near clipping plane. -* `far`=`100` (`Number`, optional) - Distance of far clipping plane. -* `aspect`= (`Number`, optional) - Aspect ratio. If not provided the `width/height` ratio will be used when creating `Viewport`s. -* `distance`= (`Number`, optional) - - +* `orthographic` (Boolean) - Default `false`. +* `fov` (Number, optional) - Field of view covered by camera. Default `75`. +* `near` (Number, optional) - Distance of near clipping plane. Default `0.1`. +* `far` (Number, optional) - Distance of far clipping plane. Default `1000`. +* `aspect` (Number, optional) - Aspect ratio. If not provided the `width/height` ratio will be used when creating `Viewport`s. +* `distance` (Number, optional) - See [View constructor](/docs/api-reference/viewport.md#constructor) for additional parameters, especially for specifying alternate projection matrices, geospatial anchor etc. +## Methods + +Inherits all [View methods](/docs/api-reference/viewport.md#methods). + + ## Remarks * Like all `View`s, the `FirstPersonView` will work with all geospatial coordinate systems if a geospatial "anchor point" is supplied through the `longitude`, `latitude` and `zoom` options. The `position` vector will then be interpreted as meter offsets from this anchor point. ## Source -[src/core/views/perspective-view.js](https://github.com/uber/deck.gl/blob/5.1-release/src/core/views/perspective-view.js) +[modules/core/src/core/views/perspective-view.js](https://github.com/uber/deck.gl/blob/5.2-release/modules/core/src/core/views/perspective-view.js) diff --git a/docs/api-reference/first-person-viewport.md b/docs/api-reference/first-person-viewport.md index 36cc7cf626f..97774432400 100644 --- a/docs/api-reference/first-person-viewport.md +++ b/docs/api-reference/first-person-viewport.md @@ -25,35 +25,44 @@ const viewport = new FirstPersonViewport({ }); ``` -## Methods -Inherits all [Viewport methods](/docs/api-reference/viewport.md#methods). +## Constructor -### Constructor +```js +new FirstPersonViewport({fov: 45, width: 500, height: 500}); +``` Parameters: -- `opts` (Object) - viewport options - * `width` (Number) - Width of "viewport" or window. Default to `1`. - * `height` (Number) - Height of "viewport" or window. Default to `1`. + +* `opts` (Object) - viewport options + + `width` (Number) - Width of "viewport" or window. Default to `1`. + + `height` (Number) - Height of "viewport" or window. Default to `1`. view matrix arguments: - * `eye` (`Vector3`, optional) - Defines eye position, default unit distance along z axis. + + + `eye` (`Vector3`, optional) - Defines eye position, default unit distance along z axis. Default to `[0, 0, 1.5]` (eye 1.5 meters above the "ground" to emulate a human perspective). - * `lookAt` (`Vector3`, optional) - Which point is camera looking at. Default to origin `[0, 0, 0]`. - * `up` (`Vector3`, optional) - Defines up direction. Default to positive y axis `[0, 1, 0]`. + + `lookAt` (`Vector3`, optional) - Which point is camera looking at. Default to origin `[0, 0, 0]`. + + `up` (`Vector3`, optional) - Defines up direction. Default to positive y axis `[0, 1, 0]`. projection matrix arguments: - * `fov` (Number, optional) - Field of view covered by camera. Default to `75`. - * `near` (Number, optional) - Distance of near clipping plane. Default to `1`. - * `far` (Number, optional) - Distance of far clipping plane. Default to `100`. - * `aspect` (Number, optional) - Aspect ratio. Default to the viewport's `width/height`. + + + `fov` (Number, optional) - Field of view covered by camera. Default to `75`. + + `near` (Number, optional) - Distance of near clipping plane. Default to `1`. + + `far` (Number, optional) - Distance of far clipping plane. Default to `100`. + + `aspect` (Number, optional) - Aspect ratio. Default to the viewport's `width/height`. See [Viewport constructor](/docs/api-reference/viewport.md#constructor) for additional parameters, especially for specifying alternate projection matrices, geospatial anchor etc. +## Methods + +Inherits all [Viewport methods](/docs/api-reference/viewport.md#methods). + + ## Remarks * Like all `Viewport`s, the `FirstPersonViewport` will work with all geospatial coordinate systems if a geospatial "anchor point" is supplied through the `longitude`, `latitude` and `zoom` options. The `position` vector will then be interpreted as meter offsets from this anchor point. ## Source -[src/core/viewports/perspective-viewport.js](https://github.com/uber/deck.gl/blob/5.1-release/src/core/viewports/perspective-viewport.js) +[modules/core/src/core/viewports/perspective-viewport.js](https://github.com/uber/deck.gl/blob/5.2-release/modules/core/src/core/viewports/perspective-viewport.js) diff --git a/docs/api-reference/internal/layer-manager.md b/docs/api-reference/internal/layer-manager.md index 77e85f0a86c..cacc3a613c5 100644 --- a/docs/api-reference/internal/layer-manager.md +++ b/docs/api-reference/internal/layer-manager.md @@ -7,51 +7,74 @@ The `LayerManager` class handles updates, drawing and picking for a set of layer For more information consult the [Using Standalone](/docs/advanced/using-standalone.md) article. -## Methods - -##### constructor +## Constructor Creates a new `LayerManager` instance. -`const layerManager = new LayerManager(gl, {eventManager: ...}})` +```js +new LayerManager(gl, {eventManager: ...}})` +``` + +Parameters: * `gl` ([WebGLRenderingContext](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext)) -##### needsRedraw +## Methods + +##### `needsRedraw` Checks if layers need to be redrawn. -`layerManager.needsRedraw({clearRedrawFlags = false})` +```js +layerManager.needsRedraw({clearRedrawFlags = false}); +``` +Parameters: -##### getLayers +* `clearRedrawFlags` (Bool) - Reset the needs redraw status + +Returns: + +* `true` if redraw is needed. + +##### `getLayers` Returns an list of layers, optionally be filtered by a list of layer ids. -`const layers = layerManager.getLayers({layerIds=[]})` +```js +const layers = layerManager.getLayers({layerIds=[]}); +``` + +Parameters: * `layerIds` (String[], optional) - A list of layer id strings. If supplied, the returned list will only contain layers whose `id` property matches (see note) one of the strings in the list. -Returns (`Layer[]`) - array of layer instances. +Returns: + +* `Layer[]` - array of layer instances. Notes: + * The returned list of layers is "expanded" in the sense that composite layers will have been recursively rendered and the list will thus only contain primitive layers. * When supplying the layer id of a composite layer, all the sub layers rendered by that layer will be included. * layer id matching checks that a layer id *starts with* one of the supplied strings. This ensures that sublayers rendered by a composite layer with the given id will also be included in the matched list. -##### setParameters +##### `setParameters` -Updates parameters +Updates parameters. -`layerManager.setParameters({ +```js +layerManager.setParameters({ useDevicePixels, pickingRadius, onLayerClick, onLayerHover -}) -` +}); +``` + +Parameters: * `useDevicePixels` (`Boolean`, optional) - Whether to use retina/HD display or not. * `eventManager` - A source of DOM input events @@ -60,62 +83,82 @@ Updates parameters * `onLayerHover` (`Function`, optional) - A handler to be called when any layer is hovered over. Notes: + * The event "source" is expected to provide `on()`/`off()` methods for registration, and to call registered handlers with an "Event" object of the following shape: - * `offsetCenter` (Object: {x, y}) - center of the event - * `srcEvent` (Object) - native JS Event object + + `offsetCenter` (Object: {x, y}) - center of the event + + `srcEvent` (Object) - native JS Event object -##### setViews +##### `setViews` Updates the current views. -`layerManager.setViews(views)` +```js +layerManager.setViews(views); +``` + +Parameters: * `views` (`View[]`) - The new [View](/docs/api-reference/view.md) instances. -##### setLayers +##### `setLayers` Provide a new list of layers. Layers will be matched against old layers, and any composite layers will be recursively expanded into primitive layers. -`layerManager.updateLayers({newLayers})` +```js +layerManager.updateLayers({newLayers}); +``` * `newLayers` (Layer[]) - Array of layers -##### updateLayers +##### `updateLayers` Updates the current list of layers. -##### drawLayers +##### `drawLayers` -Draw all layers +Draw all layers. -`layerManager.drawLayers({pass})` +```js +layerManager.drawLayers({pass}); +``` + +Parameters: * `pass` (String) - The render pass identifier, for debugging purpose -##### pickObject +##### `pickObject` + +Pick the closest info at given coordinate. -Pick the closest info at given coordinate +```js +layerManager.pickLayer({x, y, mode, radius = 0, layerIds}) +``` -`layerManager.pickLayer({x, y, mode, radius = 0, layerIds})` +Parameters: * `x` (Number) - The x position of the pointer * `y` (Number) - The y position of the pointer * `mode` (String) - One of `hover` or `click` -##### pickObjects +##### `pickObjects` -Get all unique infos within a bounding box +Get all unique infos within a bounding box. -`layerManager.queryLayer({x, y, width, height, layerIds})` +```js +layerManager.queryLayer({x, y, width, height, layerIds}); +``` + +Parameters: * `x` (Number) - The x position of the pointer * `y` (Number) - The y position of the pointer ## Source + [src/core/lib/layer-manager.js](https://github.com/uber/deck.gl/blob/5.0-release/src/core/lib/layer-manager.js) diff --git a/docs/api-reference/layer-manager.md b/docs/api-reference/layer-manager.md deleted file mode 100644 index 5c5fdf131ce..00000000000 --- a/docs/api-reference/layer-manager.md +++ /dev/null @@ -1,3 +0,0 @@ -# LayerManager Class (Internal) - -The documentation for this component has moved to [`LayerManager`](/docs/api-reference/internal/layer-manager.md). diff --git a/docs/api-reference/layer.md b/docs/api-reference/layer.md index 2daacab23cc..faafd043dfa 100644 --- a/docs/api-reference/layer.md +++ b/docs/api-reference/layer.md @@ -2,56 +2,66 @@ The `Layer` class is the base class of all deck.gl layers, and it provides a number of **base properties** availabe in all layers. + ## Static Members -#### `layerName` (String, required) +##### `layerName` (String, required) This static property should contain the name of the layer, typically the name of layer's class (it cannot reliably be autodeduced in minified code). It is used as the default Layer id as well as for debugging and profiling. -#### `defaultProps` (Object, optional) +##### `defaultProps` (Object, optional) All deck.gl layers define a `defaultProps` static member listing their props and default values. Using `defaultProps` improves both the code readability and performance during layer instance construction. Remarks: + * For developer that would like to write new layers, it's highly recommended to follow core deck.gl layers and define `defaultProps`. In the future version of deck.gl, a check will be in place to enforce this ## Constructor -``` +```js new Layer(...props); ``` Parameters: -- `props` (Object) - `Layer` properties. + +* `props` (Object) - `Layer` properties. Notes: + * More than one property object can be supplied. * Property objects will be merged with the same semantics as [Object.assign](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign), i.e. props in later objects will overwrite props earlier object. * Every layer specifies default values for all its props, and these values will be used internally if that prop is not specified by the application in the Layer constructor. + +## Properties + ### Basic Properties ##### `id` (String, optional) -- Default: layers `layerName` static property. +* Default: layers `layerName` static property. The `id` must be unique among all your layers at a given time. The default value of `id` is the `Layer`'s "name". If more than one instance of a specific type of layer exist at the same time, they must possess different `id` strings for deck.gl to properly distinguish them. Remarks: -* For React users: `id` is similar to the `key` property used in React to match components between rendering calls, with the difference that deck.gl requires the `id` whereas in React the `key` is optional but recommended. + +For React users: + +* `id` is similar to the `key` property used in React to match components between rendering calls, with the difference that deck.gl requires the `id` whereas in React the `key` is optional but recommended. * A layer's name is defined by the `Layer.layerName` static member, or inferred from the constructor name (which is not robust in minified code). * Note that for sublayers (generated by composite layers), a composite layer id is generated by appending the sub layer's id to the parent layer's `id`, so there are no `id` collisions. ##### `data` (Array or Iterable, optional) -- Default: `[]` +* Default: `[]` The data prop should contain an iterable JavaScript container, please see JavaScript `[Symbol.iterator]`. ##### `visible` (Boolean, optional) -- Default: `true` +* Default: `true` Whether the layer is visible. Under most circumstances, using `visible` prop to control the visibility of layers are recommended over doing conditional rendering. Compare: @@ -77,9 +87,9 @@ In the second example (conditional rendering) the layer state will be destroyed The opacity of the layer. deck.gl automatically applies gamma to the opacity in an attempt to make opacity changes appear linear (i.e. the opacity is visually proportional to the value of the prop) Remarks + * While it is a recommended convention that all deck.gl layers should support the `opacity` prop, it is up to each layer's fragment shader to implement support for opacity. ---- ### Interaction Properties @@ -87,7 +97,7 @@ Layers can be interacted with using these properties. ##### `pickable` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer responds to mouse pointer picking events. @@ -109,25 +119,24 @@ Requires `pickable` to be true. ##### `highlightColor` (Array, optional) -- Default: `[0, 0, 128, 128]` +* Default: `[0, 0, 128, 128]` RGBA color to be used to render highlighted object. ##### `highlightedObjectIndex` (Integer, optional) -- Default: `-1` +* Default: `-1` When provided a valid value corresponding object (one instance in instanced rendering or group of primitives with same picking color) will be highlighted with `highlightColor`. ##### `autoHighlight` (Boolean, optional) -- Default: `false` +* Default: `false` When true, current object pointed by mouse pointer (when hovered over) is highlighted with `highlightColor`. Requires `pickable` to be true. ---- ### Coordinate System Properties @@ -155,7 +164,6 @@ Allows local coordinate system transformations to be applied to a layer, which i Note that the matrix projection is applied after the non-linear mercator projection calculations are resolved, so be careful when using model matrices with longitude/latitude encoded coordinates. They normally work best with non-mercator viewports or meter offset based mercator layers ---- ### Data Properties @@ -178,7 +186,8 @@ deck.gl automatically derives the number of drawing instances from the `data` pr Accessors such as `getColor` and `getPosition` are called to retrieve colors and positions when a layer is first added. From then on, to maximize performance, deck.gl does not recalculate colors or positions unless the `data` prop changes by shallow comparison. Sometimes `data` remains the same, but the outcome of an accessor has changed. In the following example, this is caused by changes in the external values `maleColor` and `femaleColor`: -``` + +```js const layer = new ScatterplotLayer({ ... // Other props getColor: d => d.male ? maleColor : femaleColor @@ -186,7 +195,8 @@ Sometimes `data` remains the same, but the outcome of an accessor has changed. I ``` In this case, you need to explicitly inform deck.gl to re-evaluate `getColor` for all data items. You do so by defining `updateTriggers`: -``` + +```js const layer = new ScatterplotLayer({ ... // Other props getColor: d => d.male ? maleColor : femaleColor, @@ -204,9 +214,10 @@ For example, `updateTriggers.getColor` is a list of variables that affect the ou The variables may be numbers, strings, objects or functions. During each rendering cycle, deck.gl shallow-compares them with the previous values. -Note: change of the `data` prop has higher priority than the `updateTriggers`. If the app supplies a new `data` object, then all attributes will be automatically updated, even if the updateTriggers have not changed. To block excessive attribute updates, set the [`dataComparator`](/docs/api-reference/layer.md#-datacomparator-function-optional-) prop. +Note: + +* change of the `data` prop has higher priority than the `updateTriggers`. If the app supplies a new `data` object, then all attributes will be automatically updated, even if the updateTriggers have not changed. To block excessive attribute updates, set the [`dataComparator`](/docs/api-reference/layer.md#-datacomparator-function-optional-) prop. ---- ### Render Properties @@ -219,7 +230,7 @@ Please refer to the luma.gl v4 [setParameters](http://uber.github.io/luma.gl/#/d ##### `getPolygonOffset` (Function, optional) -- Default: `({layerIndex}) => [0, -layerIndex * 100]` +* Default: `({layerIndex}) => [0, -layerIndex * 100]` When multiple layers are rendered on the same plane, [z-fighting](https://en.wikipedia.org/wiki/Z-fighting) may create undesirable artifacts. To improve the visual quality of composition, deck.gl allows layers to use `gl.polygonOffset` to apply an offset to its depth. By default, each layer is offset a small amount by its index so that layers are cleanly stacked from bottom to top. @@ -227,13 +238,17 @@ This accessor takes a single parameter `uniform` - an object that contains the c If the accessor is assigned a falsy value, polygon offset will be set to `[0, 0]`. -*Remarks: While this feature helps mitigate z-fighting, at close up zoom levels the issue might return because of the precision error of 32-bit projection matrices. Try set the `fp64` prop to `true` in this case.* +*Remarks: + +* While this feature helps mitigate z-fighting, at close up zoom levels the issue might return because of the precision error of 32-bit projection matrices. Try set the `fp64` prop to `true` in this case.* ##### `transitions` (Object, optional) -- Default: `{}` + +* Default: `{}` When creating layers, animation can be enabled by supplying an `transitions` prop. Animation parameters are defined per attribute by using attribute names or accessor names as keys: -``` + +```js new Layer({ transitions: { getPositions: 600, @@ -248,37 +263,40 @@ new Layer({ | Parameter | Type | Default | Description | | --------- | -------- | ----------- | ----------- | | duration | Number | `0` | Duration of the transition animation, in milliseconds | -| easing | Function | LINEAR (`t => t`) | Easing function that maps a value from [0, 1] to [0, 1], see http://easings.net/ | +| easing | Function | LINEAR (`t => t`) | Easing function that maps a value from [0, 1] to [0, 1], see [http://easings.net/](http://easings.net/) | | onStart | Function | `null` | Callback when the transition is started | | onEnd | Function | `null` | Callback when the transition is done | | onInterrupt | Function | `null` | Callback when the transition is interrupted | As a shorthand, if an accessor key maps to a number rather than an object, then the number is assigned to the `duration` parameter. + ## Members -*Remarks: Layer members are designed to support the creation of new layers or layer sub-classing and are NOT intended to be used by applications.* +*Layer members are designed to support the creation of new layers or layer sub-classing and are NOT intended to be used by applications.* + ##### `context` (Object) The context object stores information that are shared by all layers. -- `gl` ([WebGLRenderingContext](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext)) - WebGL context of the current canvas. -- `viewport` ([Viewport](/docs/api-reference/viewport.md)) - The current viewport +* `gl` ([WebGLRenderingContext](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext)) - WebGL context of the current canvas. +* `viewport` ([Viewport](/docs/api-reference/viewport.md)) - The current viewport ##### `state` (Object) The state object allows a layer to store persistent information cross rendering cycles. -- `attributeManager` ([AttributeManager](/docs/api-reference/attribute-manager.md)) - The attribute manager of this layer. +* `attributeManager` ([AttributeManager](/docs/api-reference/attribute-manager.md)) - The attribute manager of this layer. ##### `props` (Object) [Properties](/docs/api-reference/layer.md#constructor) of this layer. + ## Methods -*Layer methods are designed to support the creation of new layers or layer sub-classing and are NOT intended to be called by applications*. +*Layer methods are designed to support the creation of new layers or layer sub-classing and are NOT intended to be called by applications.* ### General Methods @@ -286,7 +304,6 @@ The state object allows a layer to store persistent information cross rendering Used to update the layers [`state`](/docs/api-reference/layer.md#-state-object-) object. Calling this method will also cause the layer to rerender. ---- ### Layer Lifecycle Methods @@ -299,8 +316,8 @@ This method is called only once for each layer to set up the initial state. `initializeState(context)` * `context` - The layer context is supplied as a parameter - * `context.gl` (`WebGLRenderingContext`) - gl context - * ... + + `context.gl` (`WebGLRenderingContext`) - gl context + + ... deck.gl will already have created the `state` object at this time, and added the `gl` context and the `attributeManager` state. @@ -316,19 +333,21 @@ Parameters: * `oldProps` (Object) - Layer properties from the previous rendering cycle. * `context` (Object) - Layer context from the current rendering cycle. * `oldContext` (Object) - Layer context from the previous rendering cycle. -* `changeFlags`: an object that contains the following boolean flags: `dataChanged`, `propChanged`, `viewportChanged`, `somethingChanged` +* `changeFlags`: + +* an object that contains the following boolean flags: + +* `dataChanged`, `propChanged`, `viewportChanged`, `somethingChanged` Returns: -- `true` this layer needs to be updated. +* `true` this layer needs to be updated. Remarks: -- Prop change is determined by shallow comparison. -- Data change is determined by shallow comparison of `props.data` unless -[`dataComparator`](/docs/api-reference/layer.md#-datacomparator-function-optional-) -is supplied. -- The default implementation returns `true` if any change has been detected in data or props, but **ignores viewport changes**. +* Prop change is determined by shallow comparison. +* Data change is determined by shallow comparison of `props.data` unless [`dataComparator`](/docs/api-reference/layer.md#-datacomparator-function-optional-) is supplied. +* The default implementation returns `true` if any change has been detected in data or props, but **ignores viewport changes**. ##### `updateState` @@ -342,7 +361,11 @@ Parameters: * `oldProps` (Object) - Layer properties from the previous rendering cycle. * `context` (Object) - Layer context from the current rendering cycle. * `oldContext` (Object) - Layer context from the previous rendering cycle. -* `changeFlags`: an object that contains the following boolean flags: `dataChanged`, `propChanged`, `viewportChanged`, `somethingChanged` +* `changeFlags`: + +* an object that contains the following boolean flags: + +* `dataChanged`, `propChanged`, `viewportChanged`, `somethingChanged` The default implementation will invalidate all attributeManager attributes if the `data` prop has changed. @@ -354,10 +377,12 @@ Called on a layer to render to the WebGL canvas. Parameters: -- `uniforms`: an object that contains all the [default unforms](/docs/advanced/writing-shaders.md#uniforms) to be passed to the shaders. -- `context` - The layer context is supplied as a parameter - * `context.gl` (`WebGLRenderingContext`) - gl context - * ... +* `uniforms`: + +* an object that contains all the [default unforms](/docs/advanced/writing-shaders.md#uniforms) to be passed to the shaders. +* `context` - The layer context is supplied as a parameter + + `context.gl` (`WebGLRenderingContext`) - gl context + + ... The default implementation looks for a variable `model` in the layer's state (which is expected to be an instance of the luma.gl `Model` class) and calls `draw` on that model with the parameters. @@ -367,21 +392,22 @@ Called when a layer is being hovered or clicked, before any user callbacks are c Parameters: -- `pickParams` (Object) - * `pickParams.info` (Object) - The current `info` object. By default it contains the +* `pickParams` (Object) + + `pickParams.info` (Object) - The current `info` object. By default it contains the following fields: - + `x` (Number) - Mouse position x relative to the viewport. - + `y` (Number) - Mouse position y relative to the viewport. - + `lngLat` ([Number, Number]) - Mouse position in world coordinates. Only applies if [`coordinateSystem`](/docs/api-reference/layer.md#-projectionmode-number-optional-) is `COORDINATE_SYSTEM.LNGLAT`. - + `color` (Number[4]) - The color of the pixel that is being picked. It represents a "picking color" that is encoded by [`layer.encodePickingColor()`](/docs/api-reference/layer.md#-encodepickingcolor-). - + `index` (Number) - The index of the object that is being picked. It is the returned value of [`layer.decodePickingColor()`](/docs/api-reference/layer.md#-decodepickingcolor-). - + `picked` (Boolean) - `true` if `index` is not `-1`. - * `pickParams.mode` (String) - One of `hover` and `click` + + - `x` (Number) - Mouse position x relative to the viewport. + - `y` (Number) - Mouse position y relative to the viewport. + - `lngLat` ([Number, Number]) - Mouse position in world coordinates. Only applies if [`coordinateSystem`](/docs/api-reference/layer.md#-projectionmode-number-optional-) is `COORDINATE_SYSTEM.LNGLAT`. + - `color` (Number[4]) - The color of the pixel that is being picked. It represents a "picking color" that is encoded by [`layer.encodePickingColor()`](/docs/api-reference/layer.md#-encodepickingcolor-). + - `index` (Number) - The index of the object that is being picked. It is the returned value of [`layer.decodePickingColor()`](/docs/api-reference/layer.md#-decodepickingcolor-). + - `picked` (Boolean) - `true` if `index` is not `-1`. + + `pickParams.mode` (String) - One of `hover` and `click` Returns: -- An `info` object with optional fields about what was picked. This object will be passed to the layer's `onHover` or `onClick` callbacks. -- `null`, if the corresponding event should cancelled with no callback functions called. +* An `info` object with optional fields about what was picked. This object will be passed to the layer's `onHover` or `onClick` callbacks. +* `null`, if the corresponding event should cancelled with no callback functions called. The default implementation populates the `info.object` field with the `info.index` element from the layer's `data` prop. @@ -389,7 +415,6 @@ The default implementation populates the `info.object` field with the `info.inde This method is called before the layer is being removed. A layer should release all resources created during its life span. ---- ### Layer Projection Methods @@ -401,13 +426,13 @@ Projects a map coordinate using the current viewport settings. Parameters: - - `coordinates` (Array) - `[lng, lat, altitude]` Passing an altitude is optional. - - `opts` (Object) - - `topLeft` (Boolean, optional) - Whether projected coords are top left. Default to `true`. +* `coordinates` (Array) - `[lng, lat, altitude]` Passing an altitude is optional. +* `opts` (Object) + + `topLeft` (Boolean, optional) - Whether projected coords are top left. Default to `true`. Returns: - - A screen coordinates array `[x, y]` or `[x, y, z]` if an altitude was given. +* A screen coordinates array `[x, y]` or `[x, y, z]` if an altitude was given. ##### `unproject` @@ -415,13 +440,13 @@ Unprojects a pixel coordinate using the current viewport settings. Parameters: - - `pixels` (Array) - `[x, y, z]` Passing a `z` is optional. - - `opts` (Object) - - `topLeft` (Boolean, optional) - Whether projected coords are top left. Default to `true`. +* `pixels` (Array) - `[x, y, z]` Passing a `z` is optional. +* `opts` (Object) + + `topLeft` (Boolean, optional) - Whether projected coords are top left. Default to `true`. Returns: - - A map coordinates array `[lng, lat]` or `[lng, lat, altitude]` if a `z` was given. +* A map coordinates array `[lng, lat]` or `[lng, lat, altitude]` if a `z` was given. ##### `projectFlat` @@ -429,24 +454,25 @@ Projects a map coordinate using the current viewport settings, ignoring any pers Parameters: - - `coordinates` (Array) - `[longitude, latitude]` coordinates. - - `scale` (Number) - Map zoom scale calculated from `Math.pow(2, zoom)`. +* `coordinates` (Array) - `[longitude, latitude]` coordinates. +* `scale` (Number) - Map zoom scale calculated from `Math.pow(2, zoom)`. Returns: - - Screen coordinates in `[x, y]`. +* Screen coordinates in `[x, y]`. ##### `unprojectFlat` Unrojects a pixel coordinate using the current viewport settings, ignoring any perspective tilt (meaning that the pixel was projected). Parameters: - - `pixels` (Array) - `[x, y]` - - `scale` (Number) - Map zoom scale calculated from `Math.pow(2, zoom)`. + +* `pixels` (Array) - `[x, y]` +* `scale` (Number) - Map zoom scale calculated from `Math.pow(2, zoom)`. Returns: - - Map or world coordinates in `[longitude, latitude]`. +* Map or world coordinates in `[longitude, latitude]`. ##### `screenToDevicePixels` @@ -454,13 +480,12 @@ Simply multiplies `pixels` parameter with `window.devicePixelRatio` if available Parameters: - - `pixels` (Number) - The number in screen pixels. +* `pixels` (Number) - The number in screen pixels. Retures: - - A number in device pixels +* A number in device pixels ---- ### Layer Picking Methods @@ -473,13 +498,15 @@ This color is encoded by the `layer.encodePickingColor()` method. Parameters: -- `color` (Array) - The color to be decoded in `[r, g, b]`. +* `color` (Array) - The color to be decoded in `[r, g, b]`. Returns: -- A number representing the index of the feature. The null picking color (See `Layer.nullPickingColor`) will be decoded as -1. +* A number representing the index of the feature. The null picking color (See `Layer.nullPickingColor`) will be decoded as -1. -Note: The null picking color is returned when a pixel is picked that is not covered by the layer, or when they layer has selected to render a pixel using the null picking color to make it unpickable. +Note: + +* The null picking color is returned when a pixel is picked that is not covered by the layer, or when they layer has selected to render a pixel using the null picking color to make it unpickable. ##### `encodePickingColor` @@ -487,22 +514,25 @@ Converts a "sub-feature index" number to a color. This color can later be decode Parameters: -- `index` (Integer) - The index to be encoded. +* `index` (Integer) - The index to be encoded. Returns: -- An array of `[r, g, b]`. +* An array of `[r, g, b]`. To get a color that does not correspond to any sub-feature, use `layer.nullPickingColor()`. Notes: + * indices to be encoded must be integers larger than or equal to 0. * Picking colors are 24 bit values and can thus encode up to 16 million indices. ##### `nullPickingColor` Returns: -- a "null" picking color which is equal the the color of pixels not covered by the layer. This color is guaranteed not to match any index value greater than or equal to zero. + +* a "null" picking color which is equal the the color of pixels not covered by the layer. This color is guaranteed not to match any index value greater than or equal to zero. ## Source -[src/core/lib/layer.js](https://github.com/uber/deck.gl/blob/5.1-release/src/core/lib/layer.js) + +[modules/core/src/core/lib/layer.js](https://github.com/uber/deck.gl/blob/5.2-release/modules/core/src/core/lib/layer.js) diff --git a/docs/api-reference/map-controller.md b/docs/api-reference/map-controller.md index 3d3bcc5af27..9400203441a 100644 --- a/docs/api-reference/map-controller.md +++ b/docs/api-reference/map-controller.md @@ -6,11 +6,13 @@ The `MapController` class can be passed to the `Deck.controller` or `DeckGL.cont ## Usage ```js - this.setState({viewport: v})} - /> +import DeckGL, {MapController} from 'deck.gl'; + + this.setState({viewport: v})} +/> ``` ## Methods diff --git a/docs/api-reference/orthographic-view.md b/docs/api-reference/orthographic-view.md index 94205c1e94e..3fb6e9fb026 100644 --- a/docs/api-reference/orthographic-view.md +++ b/docs/api-reference/orthographic-view.md @@ -3,40 +3,45 @@ The `OrthographicView` class is a subclass of the [Viewport](/docs/api-reference/view.md) that creates an orthogonal view. Remarks: + * This class is just a convenience, the application can use `Viewport` directly together with e.g. the `mat4.ortho` and `mat4.lookAt` functions from the `gl-matrix` module. ## Constructor +```js +new OrthographicView({ + left: 0, + top: 0, + width: 500, + height: 500 +}); +``` + Parameters: -- `opts` (Object) - Orthogonal view options +* `opts` (Object) - Orthogonal view options projection matrix arguments: - * `near` (Number, optional) - Distance of near clipping plane. Default to `1`. - * `far` (Number, optional) - Distance of far clipping plane. Default to `100`. - * `left` (Number) - Left bound of the frustum - * `top` (Number) - Top bound of the frustum + + + `near` (Number, optional) - Distance of near clipping plane. Default to `1`. + + `far` (Number, optional) - Distance of far clipping plane. Default to `100`. + + `left` (Number) - Left bound of the frustum + + `top` (Number) - Top bound of the frustum automatically calculated by default: - * `right` (Number, optional) - Right bound of the frustum. - * `bottom` (Number, optional) - Bottom bound of the frustum. + + + `right` (Number, optional) - Right bound of the frustum. + + `bottom` (Number, optional) - Bottom bound of the frustum. when zooming with orthographic view, the size (width and height) of the view and window are no longer the same. In such case, specify `right` and `bottom` together with `left` and `top` explicitly to define the view size. refer to `examples/experimental/orthographic-zooming` for example. -```js -const view = new OrthographicView({ - left: 0, - top: 0, - width: 500, - height: 500 -}); -``` - ## Methods Inherits all [Viewport methods](/docs/api-reference/view.md#methods). + ## Source -[src/core/views/orthographic-view.js](https://github.com/uber/deck.gl/blob/5.1-release/src/core/views/orthographic-view.js) + +[modules/core/src/core/views/orthographic-view.js](https://github.com/uber/deck.gl/blob/5.2-release/modules/core/src/core/views/orthographic-view.js) diff --git a/docs/api-reference/orthographic-viewport.md b/docs/api-reference/orthographic-viewport.md index 195329ccdff..2f2f39493f8 100644 --- a/docs/api-reference/orthographic-viewport.md +++ b/docs/api-reference/orthographic-viewport.md @@ -3,50 +3,55 @@ The `OrthographicViewport` class is a subclass of the [Viewport](/docs/api-reference/viewport.md) that creates an orthogonal view. Remarks: + * This class is just a convenience, the application can use `Viewport` directly together with e.g. the `mat4.ortho` and `mat4.lookAt` functions from the `gl-matrix` module. ## Constructor +```js +new OrthographicViewport({ + eye: [0, 0, 100], + left: 0, + top: 0, + width: 500, + height: 500 +}); +``` + Parameters: -- `opts` (Object) - Orthogonal view options - * `width` (Number) - Width of "viewport" or window. Default to `1`. - * `height` (Number) - Height of "viewport" or window. Default to `1`. +* `opts` (Object) - Orthogonal viewport options + + + `width` (Number) - Width of "viewport" or window. Default to `1`. + + `height` (Number) - Height of "viewport" or window. Default to `1`. view matrix arguments: - * `eye` (Vector3, optional) - Defines eye position, default unit distance along z axis. + + + `eye` (Vector3, optional) - Defines eye position, default unit distance along z axis. Default to `[0, 0, 1]`. - * `lookAt` (Vector3, optional) - Which point is camera looking at. Default to origin `[0, 0, 0]`. - * `up` (Vector3, optional) - Defines up direction. Default to positive y axis `[0, 1, 0]`. + + `lookAt` (Vector3, optional) - Which point is camera looking at. Default to origin `[0, 0, 0]`. + + `up` (Vector3, optional) - Defines up direction. Default to positive y axis `[0, 1, 0]`. projection matrix arguments: - * `near` (Number, optional) - Distance of near clipping plane. Default to `1`. - * `far` (Number, optional) - Distance of far clipping plane. Default to `100`. - * `left` (Number) - Left bound of the frustum - * `top` (Number) - Top bound of the frustum - automatically calculated by default: - * `right` (Number, optional) - Right bound of the frustum. - * `bottom` (Number, optional) - Bottom bound of the frustum. + + `near` (Number, optional) - Distance of near clipping plane. Default to `1`. + + `far` (Number, optional) - Distance of far clipping plane. Default to `100`. + + `left` (Number) - Left bound of the frustum + + `top` (Number) - Top bound of the frustum - when zooming with orthographic viewport, the size (width and height) of the viewport and window are no longer the same. In such case, specify `right` and `bottom` together with `left` and `top` explicitly to define the viewport size. + automatically calculated by default: - refer to `examples/experimental/orthographic-zooming` for example. + + `right` (Number, optional) - Right bound of the frustum. + + `bottom` (Number, optional) - Bottom bound of the frustum. -```js -const viewport = new OrthographicViewport({ - eye: [0, 0, 100], - left: 0, - top: 0, - width: 500, - height: 500 -}); -``` + when zooming with orthographic viewport, the size (width and height) of the viewport and window are no longer the same. In such case, specify `right` and `bottom` together with `left` and `top` explicitly to define the viewport size. ## Methods Inherits all [Viewport methods](/docs/api-reference/viewport.md#methods). + ## Source -[src/core/viewports/orthographic-viewport.js](https://github.com/uber/deck.gl/blob/5.1-release/src/core/viewports/orthographic-viewport.js) + +[modules/core/src/core/viewports/orthographic-viewport.js](https://github.com/uber/deck.gl/blob/5.2-release/modules/core/src/core/viewports/orthographic-viewport.js) diff --git a/docs/api-reference/perspective-view.md b/docs/api-reference/perspective-view.md index ec41b8c11f6..b8299518c37 100644 --- a/docs/api-reference/perspective-view.md +++ b/docs/api-reference/perspective-view.md @@ -1,39 +1,42 @@ # PerspectiveView Class -Note: The `PerspectiveView` class is deprecated. Use `FirstPersonView` instead and specify the `fov` parameter to generate perspective projection matrix. +> The `PerspectiveView` class is deprecated. Use `FirstPersonView` instead and specify the `fov` parameter to generate perspective projection matrix. The [`PerspectiveView`] class is a subclass of [View](/docs/api-reference/view.md) that creates a perspective view. Remarks: + * This class is just a convenience, the application can use `View` directly together with e.g. the `mat4.perspective` and `mat4.lookAt` functions from the `gl-matrix` module. + ## Constructor +```js +new PerspectiveView({fov: 45, width: 500, height: 500}); +``` + Parameters: -- `opts` (Object) - Perspective view options +* `opts` (Object) - Perspective view options + Projection matrix arguments: - * `fov` (Number, optional) - Field of view covered by camera. Default to `75`. - * `near` (Number, optional) - Distance of near clipping plane. Default to `1`. - * `far` (Number, optional) - Distance of far clipping plane. Default to `100`. + + + `fov` (Number, optional) - Field of view covered by camera. Default to `75`. + + `near` (Number, optional) - Distance of near clipping plane. Default to `1`. + + `far` (Number, optional) - Distance of far clipping plane. Default to `100`. Automatically calculated: - * `fov` (Number, optional) - Field of view covered by camera. Default to `75`. - * `aspect` (Number, optional) - Aspect ratio. Default to the view's `widht/height`. -```js -const view = new PerspectiveView({ - fov: 45, - width: 500, - height: 500 -}); -``` + + `fov` (Number, optional) - Field of view covered by camera. Default to `75`. + + `aspect` (Number, optional) - Aspect ratio. Default to the view's `widht/height`. ## Methods Inherits all [View methods](/docs/api-reference/view.md#methods). + ## Source -[src/core/views/perspective-view.js](https://github.com/uber/deck.gl/blob/5.1-release/src/core/views/perspective-view.js) + +[modules/core/src/core/views/perspective-view.js](https://github.com/uber/deck.gl/blob/5.2-release/modules/core/src/core/views/perspective-view.js) diff --git a/docs/api-reference/perspective-viewport.md b/docs/api-reference/perspective-viewport.md index a0cf62ff8bf..17a8b6bf87e 100644 --- a/docs/api-reference/perspective-viewport.md +++ b/docs/api-reference/perspective-viewport.md @@ -1,49 +1,55 @@ # PerspectiveViewport Class -Note: The `PerspectiveViewport` class is deprecated. Use `FirstPersonViewport` instead and specify the `fov` parameter to generate perspective projection matrix. +> The `PerspectiveViewport` class is deprecated. Use `FirstPersonViewport` instead and specify the `fov` parameter to generate perspective projection matrix. The [`PerspectiveViewport`] class is a subclass of [Viewport](/docs/api-reference/viewport.md) that creates a perspective view. Remarks: + * This class is just a convenience, the application can use `Viewport` directly together with e.g. the `mat4.perspective` and `mat4.lookAt` functions from the `gl-matrix` module. + ## Constructor +```js +new PerspectiveViewport({ + eye: [0, 0, 100], + fov: 45, + width: 500, + height: 500 +}); +``` + Parameters: -- `opts` (Object) - Perspective view options - * `width` (Number) - Width of "viewport" or window. Default to `1`. - * `height` (Number) - Height of "viewport" or window. Default to `1`. +* `opts` (Object) - Perspective viewport options + + + `width` (Number) - Width of "viewport" or window. Default to `1`. + + `height` (Number) - Height of "viewport" or window. Default to `1`. View matrix arguments: - * `eye` (Vector3, optional) - Defines eye position, default unit distance along z axis. - Default to `[0, 0, 1]`. - * `lookAt` (Vector3, optional) - Which point is camera looking at. Default to origin `[0, 0, 0]`. - * `up` (Vector3, optional) - Defines up direction. Default to positive y axis `[0, 1, 0]`. + + + `eye` (Vector3, optional) - Defines eye position, default unit distance along z axis. Default to `[0, 0, 1]`. + + `lookAt` (Vector3, optional) - Which point is camera looking at. Default to origin `[0, 0, 0]`. + + `up` (Vector3, optional) - Defines up direction. Default to positive y axis `[0, 1, 0]`. Projection matrix arguments: - * `fov` (Number, optional) - Field of view covered by camera. Default to `75`. - * `near` (Number, optional) - Distance of near clipping plane. Default to `1`. - * `far` (Number, optional) - Distance of far clipping plane. Default to `100`. + + + `fov` (Number, optional) - Field of view covered by camera. Default to `75`. + + `near` (Number, optional) - Distance of near clipping plane. Default to `1`. + + `far` (Number, optional) - Distance of far clipping plane. Default to `100`. Automatically calculated: - * `fov` (Number, optional) - Field of view covered by camera. Default to `75`. - * `aspect` (Number, optional) - Aspect ratio. Default to the viewport's `widht/height`. -```js -const viewport = new PerspectiveViewport({ - eye: [0, 0, 100], - fov: 45, - width: 500, - height: 500 -}); -``` + + `fov` (Number, optional) - Field of view covered by camera. Default to `75`. + + `aspect` (Number, optional) - Aspect ratio. Default to the viewport's `widht/height`. ## Methods Inherits all [Viewport methods](/docs/api-reference/viewport.md#methods). ## Source -[src/core/viewports/perspective-viewport.js](https://github.com/uber/deck.gl/blob/5.1-release/src/core/viewports/perspective-viewport.js) + +[modules/core/src/core/viewports/perspective-viewport.js](https://github.com/uber/deck.gl/blob/5.2-release/modules/core/src/core/viewports/perspective-viewport.js) diff --git a/docs/api-reference/react/deckgl.md b/docs/api-reference/react/deckgl.md index 93ae1cfd392..f764911ee82 100644 --- a/docs/api-reference/react/deckgl.md +++ b/docs/api-reference/react/deckgl.md @@ -7,8 +7,8 @@ Make sure to read the [Using deck.gl with React](/docs/get-started/using-with-re ## Usage -// Basic standalone use ```js +// Basic usage import DeckGL, {ScatterplotLayer} from 'deck.gl'; const App = (viewState, data) => ( @@ -20,32 +20,32 @@ const App = (viewState, data) => ( Like any React component, `DeckGL` can accept child components. Child components can be automatically positioned and sized to fit perfectly underneath any `View` in the list of `views`. Child components are often maps (e.g. the `StaticMap` component from react-map-gl), but can be any React components. -// Multiple views and an auto-positioned base map ```js - const views = [ - new FirstPersonView({...}), - new MapView({id: 'basemap', ...}) - ]; - - render() { - return ( - - - - - - ); - } +import DeckGL, {MapView, FirstPersonView} from 'deck.gl'; +// Multiple views and an auto-positioned base map +const views = [ + new FirstPersonView({...}), + new MapView({id: 'basemap', ...}) +]; + +render() { + return ( + + + + + + ); +} ``` - -### Properties +## Properties ##### `width` (Number, required) @@ -74,13 +74,12 @@ Default: If the `views` property is not supplied, deck.gl will create a full scr > deck.gl will render all the views in the provided order. This may not matter as depth testing is enabled by default by deck.gl (unless transparent layers are being rendered, in which case rendering order starts to matter again), but is useful when rendering 2D layers and disabling depth testing. +### View State Properties + ##### `viewState` (Object, optional) A set of parameters that specify a view point. The exact parameters depend on the choice of `View` and `Controller` classes in use. For geospatial views, the view state should contain fields like `longitude`, `latitude`, `zoom` etc.. - -#### View State Properties - If a `viewState` prop is not supplied, `DeckGL` will attempt to autocreate a geospatial view state from the following props. ##### `latitude` (Number, optional) @@ -104,7 +103,7 @@ Current bearing - used to define a mercator projection if `viewState` is not sup Current pitch - used to define a mercator projection if `viewState` is not supplied. -#### Configuration Properties +### Configuration Properties ##### `id` (String, optional) @@ -138,67 +137,115 @@ Default value is `false`. Note: debug mode is somewhat slower as it will use synchronous operations to keep track of GPU state. +### Event Callbacks + ##### `onWebGLInitialized` (Function, optional) Callback, called once the WebGL context has been initiated Callback arguments: -- `gl` - the WebGL context. + +* `gl` - the WebGL context. ##### `onLayerHover` (Function, optional) Callback - called when the object under the pointer changes. Callback Arguments: -- `info` - the [`info`](/docs/get-started/interactivity.md#the-picking-info-object) -object for the topmost picked layer at the coordinate, null when no object is picked. -- `pickedInfos` - an array of info objects for all pickable layers that -are affected. -- `event` - the original [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object + +* `info` - the [`info`](/docs/get-started/interactivity.md#the-picking-info-object) object for the topmost picked layer at the coordinate, null when no object is picked. +* `pickedInfos` - an array of info objects for all pickable layers that are affected. +* `event` - the original [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object ##### `onLayerClick` (Function, optional) Callback - called when clicking on the layer. Callback Arguments: -- `info` - the [`info`](/docs/get-started/interactivity.md#the-picking-info-object) -object for the topmost picked layer at the coordinate, null when no object is picked. -- `pickedInfos` - an array of info objects for all pickable layers that are affected. -- `event` - the original [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object +* `info` - the [`info`](/docs/get-started/interactivity.md#the-picking-info-object) object for the topmost picked layer at the coordinate, null when no object is picked. +* `pickedInfos` - an array of info objects for all pickable layers that are affected. +* `event` - the original [MouseEvent](https://developer.mozilla.org/en-US/docs/Web/API/MouseEvent) object + + +### Children + +The following semantics of the standard React `children` property are considered experimental. + +#### JSX layers + +It is possible to use JSX syntax to create deck.gl layers as React children of the `DeckGL` React components, instead of providing them as ES6 class instances to the `layers` prop. + +```jsx + + + +``` + +For more information on this syntax and its limitations, see [Using deck.gl with React](/docs/get-started/using-with-react.md) article. + + +#### Autopositioned Children + +To make it easy to use React components in combination with deck.gl views (e.g. to place a base map under a view, or add a label on top of a view), deck.gl can make such components automatically adjust as that view is added, removed or resized. + +`DeckGL` classifies any top-level children (`props.children`) that have a `viewId` property as "view base components". It will perform special processing on them as follows: + +* It resizes and repositions any `viewId` children to precisely match the extends of the deck.gl view with the corresponding id. +* It automatically hides any `viewId` children whose id is not matched by any current deck.gl view. +* It injects view state properties (`longitude`, `latitude` etc). +* Also injects the `visible: viewport.isMapSynched()` prop to hide base maps that cannot display per the current view state parameters. + +Additional Notes: + +* The DeckGL components own `canvas` element is added last to the child list, to sit on top of all the base components, however Z index can be used to override this. +* Child repositioning is done with CSS styling on a wrapper div, resizing is done through width and height properties. +* Hiding of children is performed by removing the elements from the child list +* Children without the `viewId` property are rendered as is. + + +## Methods -### Methods +### Picking Methods The picking methods are supplied to enable applications to use their own event handling. -##### pickObject +##### `pickObject` Get the closest pickable and visible object at screen coordinate. -`deck.pickObject({x, y, radius, layerIds})` +```js +deck.pickObject({x, y, radius, layerIds}); +``` Parameters: -- `options` (Object) + +* `options` (Object) + `x` (Number) - x position in pixels + `y` (Number) - y position in pixels + `radius` (Number, optional) - radius of tolerance in pixels. Default `0`. + `layerIds` (Array, optional) - a list of layer ids to query from. If not specified, then all pickable and visible layers are queried. -Returns: a single [`info`](/docs/get-started/interactivity.md#the-picking-info-object) object, or `null` if nothing is found. +Returns: + +* A single [`info`](/docs/get-started/interactivity.md#the-picking-info-object) object, or `null` if nothing is found. NOTE: replaces deprecated method `queryObject`. -##### pickObjects +##### `pickObjects` > replaces deprecated method `queryVisibleObjects`. Get all pickable and visible objects within a bounding box. -`deck.pickObjects({x, y, width, height, layerIds})` +```js +deck.pickObjects({x, y, width, height, layerIds}); +``` Parameters: -- `options` (Object) + +* `options` (Object) + `x` (Number) - left of the bounding box in pixels + `y` (Number) - top of the bouding box in pixels + `width` (Number, optional) - width of the bouding box in pixels. Default `1`. @@ -206,46 +253,17 @@ Parameters: + `layerIds` (Array, optional) - a list of layer ids to query from. If not specified, then all pickable and visible layers are queried. -Returns: an array of unique [`info`](/docs/get-started/interactivity.md#the-picking-info-object) objects +Returns: -Remarks: -- This query methods are designed to quickly find objects by utilizing the picking buffer. They offer more flexibility for developers to handle events in addition to the built-in hover and click callbacks. -- Note there is a limitation in the query methods: occluded objects are not returned. To improve the results, you may try setting the `layerIds` parameter to limit the query to fewer layers. -- * Since deck.gl is WebGL based (and WebGL contexts are limited to a single canvas), deck.gl can only render into a single canvas. Thus all views need to render into in the same canvas. (You could of course use multiple DeckGL instances, but that can have significant resource and performance impact). +* An array of unique [`info`](/docs/get-started/interactivity.md#the-picking-info-object) objects +Remarks: - -##### `children` - -The following semantics of the standard React `children` property are considered experimental. - -**JSX layers** - -It is possible to use JSX syntax to create deck.gl layers as React children of the `DeckGL` React components, instead of providing them as ES6 class instances to the `layers` prop. -```jsx - - - -``` -For more information on this syntax and its limitations, see [Using deck.gl with React](/docs/get-started/using-with-react.md) article. - - -**Autopositioned Children** - -To make it easy to use React components in combination with deck.gl views (e.g. to place a base map under a view, or add a label on top of a view), deck.gl can make such components automatically adjust as that view is added, removed or resized. - -`DeckGL` classifies any top-level children (`props.children`) that have a `viewId` property as "view base components". It will perform special processing on them as follows: -* It resizes and repositions any `viewId` children to precisely match the extends of the deck.gl view with the corresponding id. -* It automatically hides any `viewId` children whose id is not matched by any current deck.gl view. -* It injects view state properties (`longitude`, `latitude` etc). -* Also injects the `visible: viewport.isMapSynched()` prop to hide base maps that cannot display per the current view state parameters. - -Additional Notes: -* The DeckGL components own `canvas` element is added last to the child list, to sit on top of all the base components, however Z index can be used to override this. -* Child repositioning is done with CSS styling on a wrapper div, resizing is done through width and height properties. -* Hiding of children is performed by removing the elements from the child list -* Children without the `viewId` property are rendered as is. +* This query methods are designed to quickly find objects by utilizing the picking buffer. They offer more flexibility for developers to handle events in addition to the built-in hover and click callbacks. +* Note there is a limitation in the query methods: occluded objects are not returned. To improve the results, you may try setting the `layerIds` parameter to limit the query to fewer layers. +* Since deck.gl is WebGL based (and WebGL contexts are limited to a single canvas), deck.gl can only render into a single canvas. Thus all views need to render into in the same canvas. (You could of course use multiple DeckGL instances, but that can have significant resource and performance impact). ## Source + [src/react/deckgl.js](https://github.com/uber/deck.gl/blob/5.1-release/src/react/deckgl.js) diff --git a/docs/api-reference/react/viewport-controller.md b/docs/api-reference/react/viewport-controller.md index 030ce225a55..c900cd1c0b7 100644 --- a/docs/api-reference/react/viewport-controller.md +++ b/docs/api-reference/react/viewport-controller.md @@ -5,73 +5,153 @@ ## Usage +```js +import DeckGL, {ViewportController, ScatterplotLayer} from 'deck.gl'; + +class App extends Component { + + render() { + return ( + this.setState({viewState})} > + + + ); + } +}; +``` ## Properties -##### viewportState (Class Constructor) +### ViewState Properties -##### state: PropTypes.object (instance) +##### `width` (Number, required) -##### onViewportChange: PropTypes.func, +Width of the canvas. + +##### `height` (Number, required) + +Height of the canvas. + +##### `latitude` (Number, optional) + +Current latitude - used to define a mercator projection if `viewState` is not supplied. + +##### `longitude` (Number, optional) + +Current longitude - used to define a mercator projection if `viewState` is not supplied. + +##### `zoom` (Number, optional) + +Current zoom - used to define a mercator projection if `viewState` is not supplied. + +##### `bearing` (Number, optional) + +Current bearing - used to define a mercator projection if `viewState` is not supplied. + +##### `pitch` (Number, optional) + +Current pitch - used to define a mercator projection if `viewState` is not supplied. + + +### Configuration Properties + +##### `controls` (Object) + +A map control instance to replace the default map controls + +The object must expose these methods: + +* `setProps` - Update the props of the control. +* `finalize` - Called when the control is being removed. + + +### Event Callbacks + +##### `onViewportChange` (Function) `onViewportChange` callback is fired when the user interacted with the map. The object passed to the callback contains viewport properties such as `longitude`, `latitude`, `zoom` etc. -##### getCursor: PropTypes.func, +##### `getCursor` (Function, optional) -Accessor that returns a cursor style to show interactive state +Accessor that returns a cursor style to show interactive state. -##### controls: PropTypes.shape +### Event Handling Options -A map control instance to replace the default map controls +##### `scrollZoom` (Boolean, optional) + +* Default: `true` + +Enable scroll to zoom. + +##### `dragPan` (Boolean, optional) + +* Default: `true` + +Enable drag to pan. + +##### `dragRotate` (Boolean, optional) + +* Default: `true` + +Enable drag to rotate. + +##### `doubleClickZoom` (Boolean, optional) + +* Default: `true` -The object must expose one property: `events` as an array of subscribed +Enable double click to zoom. -event names; and two methods: `setState(state)` and `handle(event)` +##### `touchZoom` (Boolean, optional) +* Default: `true` -### Event Handling Controls +Enable pinch to zoom (touch). -##### scrollZoom: PropTypes.bool, +##### `touchRotate` (Boolean, optional) -Scroll to zoom +* Default: `false` -##### dragPan: PropTypes.bool, +Enable pinch to rotate. -Drag to pan +##### `keyboard` (Boolean, optional) -##### dragRotate: PropTypes.bool, +* Default: `true` -Drag to rotate +Enable keyboard navigation. -##### doubleClickZoom: PropTypes.bool, -Double click to zoom +### Viewport Constraints -##### touchZoomRotate: PropTypes.bool, +##### `maxZoom` (Number, optional) -Pinch to zoom / rotate +* Default: `20` +Max zoom level. -### Viewport constraints +##### `minZoom` (Number, optional) -##### maxZoom: PropTypes.number, +* Default: `0` -Max zoom level +Min zoom level. -##### minZoom: PropTypes.number, +##### `maxPitch` (Number, optional) -Min zoom level +* Default: `60` -##### maxPitch: PropTypes.number, +Max pitch in degrees. -Max pitch in degrees +##### `minPitch` (Number, optional) -##### minPitch: PropTypes.number, +* Default: `0` -Min pitch in degrees +Min pitch in degrees. ## Source diff --git a/docs/api-reference/standalone/deckgl.md b/docs/api-reference/standalone/deckgl.md index 818ed3038d6..8e2e9dd99f1 100644 --- a/docs/api-reference/standalone/deckgl.md +++ b/docs/api-reference/standalone/deckgl.md @@ -6,6 +6,7 @@ Make sure to read the [Using deck.gl Scripting API](/docs/get-started/using-stan ## Usage + ```js new deck.DeckGL({ mapboxApiAccessToken: '', @@ -38,6 +39,7 @@ The container in which deck.gl should append its canvas. Can be either a HTMLDiv Default: `window.mapboxgl` The scripting API offers out-of-the-box integration with Mapbox. To add a base map to your visualization, you need to include the Mapbox library and stylesheet: + ```html @@ -50,7 +52,9 @@ To disable the base map, simply exclude the mapbox script or set `map` to false. ```js mapboxgl = require('mapbox-gl@~0.44.1/dist/mapbox-gl.js'); ``` + And + ```js new deck.DeckGL({ ... diff --git a/docs/api-reference/test-utils/render-test.md b/docs/api-reference/test-utils/render-test.md index 43430b3257e..f60ef027de2 100644 --- a/docs/api-reference/test-utils/render-test.md +++ b/docs/api-reference/test-utils/render-test.md @@ -6,6 +6,7 @@ Uses a [`SceneRenderer`](/docs/api-reference/test-utils/scene-renderer.md) to re ## Usage In the test script that is to run in the browser: set up and run a render test + ```js import {RenderTest} from '@deck.gl/test-utils'; import {TEST_CASES} from './test-cases'; @@ -24,6 +25,7 @@ renderTest.run(); ``` In `test-cases.js`: + ```js import {PathLayer} from 'deck.gl'; @@ -52,9 +54,7 @@ export default [{ }]; ``` -## Methods - -### constructor +## Constructor ```js import {RenderTest} from '@deck.gl/test-utils'; @@ -63,32 +63,25 @@ const renderTest = new RenderTest({ }); ``` -* `testCases` (`Array`) - array of objects describing test cases, see format description below. +* `testCases` (`Array`) - an array of objects describing each scene to be rendered. The following fields are available to define test cases: + + `name` + + `views` (defaults to `[new MapView()]`) + + `viewState` + + `layers` + + `referenceImage` + For more information see the scene format description in [`SceneRenderer`](/docs/api-reference/test-utils/scene-renderer.md). * `width` - Width to render, must match the size of your golden image * `height` - Height to render, must match the size of your golden image * `colorDeltaThreshold` - Max color delta in the YIQ difference metric for two pixels to be considered the same | * `testPassThreshold` - Percentage of pixels that must be the same for the test to pass -### run - -Run the render tests - -`renderTest.run()` - - -## Data Types - - -### Test Case Format - -Test cases are an array of objects describing each scene to be rendered. The following fields are available to define test cases -* `name` -* `views` (defaults to `[new MapView()]`) -* `viewState` -* `layers` -* `referenceImage` +## Methods -For more information see the scene format description in [`SceneRenderer`](/docs/api-reference/test-utils/scene-renderer.md). +##### `run` +Run the render tests +```js +renderTest.run(); +``` diff --git a/docs/api-reference/test-utils/scene-renderer.md b/docs/api-reference/test-utils/scene-renderer.md index 2fc10db87eb..eff09ea6888 100644 --- a/docs/api-reference/test-utils/scene-renderer.md +++ b/docs/api-reference/test-utils/scene-renderer.md @@ -3,41 +3,29 @@ Takes a list of scenes (each scene specifiying a list of `Layer`s, one or more `View`s and a view state), renders each scene in a `Deck` instance, captures the output into an image and calls a callback, then renders the next scene, finally calling a completion callback. -## Methods - -### constructor +## Constructor Renders a series of scenes calling the `onSceneRendered` callback after each scene, and `onComplete` after all scenes have been rendered. `new SceneRenderer({scenes, width, height, onSceneRendered, onComplete})` -* `scenes` -* `width` = 800 -* `height` = 450 -* `onSceneRendered` -* `onComplete` = noop - - -### run - -`sceneRenderer.run()` - -Runs the test suite, calling the callbacks. - - -## Callbacks +* `scenes` (Array) - Each scene object describes what needs to be rendered: + + `name` - name of scene. + + `views` (defaults to `[new MapView()]`) - list of `View`s. + + `viewState` - The position to use with the views. + + `layers` - The list of layers to render. +* `width` (Number) - Default `800` +* `height` (Number) - Default `450` +* `onSceneRendered` (Function) - Callback when a scene is rendered. Can return a promise. The next scene will not be rendered until this promise completes. If the return value is not a promise, next scene will be rendered immediately. +* `onComplete` (Function) - Callback when complete. -### onSceneRendered - -Can return a promise. The next scene will not be rendered until this promise completes. If the return value is not a promise, next scene will be rendered immediately. +## Methods -## Data Types +##### `run` -### Scene Objects +```js +sceneRenderer.run(); +``` -Each scene object describes what needs to be rendered -* `name` - name of scene. -* `views` (defaults to `[new MapView()]`) - list of `View`s. -* `viewState` - The position to use with the views. -* `layers` - The list of layers to render. +Runs the test suite, calling the callbacks. diff --git a/docs/api-reference/test-utils/test-layer.md b/docs/api-reference/test-utils/test-layer.md index 930fc6e1e94..94f558e847f 100644 --- a/docs/api-reference/test-utils/test-layer.md +++ b/docs/api-reference/test-utils/test-layer.md @@ -4,6 +4,7 @@ ## Usage Example of layer unit tests using `tape`. Any unit test framework can be used. + ```js import test from 'tape-catch'; import * as FIXTURES from 'deck.gl/test/data/geojson-data'; @@ -51,30 +52,28 @@ Initialize a layer, test layer update on a series of newProps, assert on the res Initialize a parent layer and its subLayer, update the parent layer a series of newProps, assert on the updated subLayer. -`testLayer({Layer, spies, testCases})` +```js +testLayer({Layer, spies, testCases}); +``` * `Layer` (`Object`) - The layer component class * `spies` (`Array`) - Array of Layer class methods to spy on. -* `testCases` (`Array`) - A list of testCases +* `testCases` (`Array`) - A list of testCases. Each test cases is an object with the following fields: + + `title` (`String`) - title of the test case + + `props` (`Object`) - Specifies a complete new set of props + + `updateProps` (`Object`) - Specifies an incremental prop change (overrides props from previous test case) + + `spies` (`Array`) - The list of updates to update + + `assert` (`Function`) - callbacks with updated layer, and oldState Notes: -* Updates are called sequentially. updateProps will be merged -with previous props - -## Test Cases - -Test cases are an array of objects with the following fields: -* `title` (`String`) - title of the test case -* `props` (`Object`) - Specifies a complete new set of props -* `updateProps` (`Object`) - Specifies an incremental prop change (overrides props from previous test case) -* `spies` (`Array`) - The list of updates to update -* `assert` (`Function`) - callbacks with updated layer, and oldState +* Updates are called sequentially. updateProps will be merged with previous props ## Writing assert Functions Assert functions are called with the following properties: + * `layer` * `oldState` * `subLayers` diff --git a/docs/api-reference/third-person-view.md b/docs/api-reference/third-person-view.md index 2f14050ce04..0cd7dfaef77 100644 --- a/docs/api-reference/third-person-view.md +++ b/docs/api-reference/third-person-view.md @@ -9,6 +9,8 @@ For more information consult the [Views](/docs/advanced/views.md) article. ## Usage ```js +import {ThirdPersonView} from 'deck.gl'; + const view = new ThirdPersonView({ cameraDistance: 2, // Camera distance from object cameraDirection: 2, // Camera distance from object @@ -18,25 +20,34 @@ const view = new ThirdPersonView({ }); ``` -## Methods -Inherits all [View methods](/docs/api-reference/view.md#methods). +## Constructor -### Constructor +```js +new ThirdPersonView({fov: 45, width: 500, height: 500, ...}); +``` Parameters: + +* `opts` (Object) - Third person view options + projection matrix arguments: - * `fov` (Number, optional) - Field of view covered by camera. Default to `75`. - * `near` (Number, optional) - Distance of near clipping plane. Default to `1`. - * `far` (Number, optional) - Distance of far clipping plane. Default to `100`. - * `aspect` (Number, optional) - Aspect ratio. Default to the view's `width/height`. + + + `fov` (Number, optional) - Field of view covered by camera. Default to `75`. + + `near` (Number, optional) - Distance of near clipping plane. Default to `1`. + + `far` (Number, optional) - Distance of far clipping plane. Default to `100`. + + `aspect` (Number, optional) - Aspect ratio. Default to the view's `width/height`. See [View constructor](/docs/api-reference/view.md#constructor) for additional parameters, especially for specifying alternate projection matrices, geospatial anchor etc. +## Methods + +Inherits all [View methods](/docs/api-reference/view.md#methods). + ## Remarks * Like all `View`s, the `ThirdPersonView` will work with all geospatial coordinate systems if a geospatial "anchor point" is supplied through the `longitude`, `latitude` and `zoom` options. The `position` vector will then be interpreted as meter offsets from this anchor point. ## Source -[src/core/views/perspective-view.js](https://github.com/uber/deck.gl/blob/5.1-release/src/core/views/perspective-view.js) +[modules/core/src/core/views/perspective-view.js](https://github.com/uber/deck.gl/blob/5.2-release/modules/core/src/core/views/perspective-view.js) diff --git a/docs/api-reference/third-person-viewport.md b/docs/api-reference/third-person-viewport.md index 0c72cacf174..ff54967d94f 100644 --- a/docs/api-reference/third-person-viewport.md +++ b/docs/api-reference/third-person-viewport.md @@ -9,6 +9,8 @@ For more information consult the [Viewports](/docs/advanced/viewports.md) articl ## Usage ```js +import {ThirdPersonViewport} from 'deck.gl'; + const viewport = new ThirdPersonViewport({ // Viewport params width: 500, @@ -16,8 +18,10 @@ const viewport = new ThirdPersonViewport({ // "Object" position position: [0, 0, 100], // "Object" position - direction: // object direction, - up: , // + bearing: 45, + pitch: 30, + + up: [0, 0, 1], // cameraDistance: 2, // Camera distance from object cameraDirection: 2, // Camera distance from object @@ -31,31 +35,40 @@ const viewport = new ThirdPersonViewport({ }); ``` -## Methods -Inherits all [Viewport methods](/docs/api-reference/viewport.md#methods). +## Constructor -### Constructor +```js +new ThirdPersonViewport({width, height, pitch, bearing, ...}); +``` Parameters: -- `opts` (Object) - viewport options - * `width` (Number) - Width of "viewport" or window. Default to `1`. - * `height` (Number) - Height of "viewport" or window. Default to `1`. - view matrix arguments: +* `opts` (Object) - Third person viewport options + + + `width` (Number) - Width of "viewport" or window. Default to `1`. + + `height` (Number) - Height of "viewport" or window. Default to `1`. + + `pitch` (Number, optional) - Camera angle in degrees (0 is straight down). Default to `0`. + + `bearing` (Number, optional) - Map rotation in degrees (0 means north is up). Default to `0`. projection matrix arguments: - * `fov` (Number, optional) - Field of view covered by camera. Default to `75`. - * `near` (Number, optional) - Distance of near clipping plane. Default to `1`. - * `far` (Number, optional) - Distance of far clipping plane. Default to `100`. - * `aspect` (Number, optional) - Aspect ratio. Default to the viewport's `width/height`. + + + `fov` (Number, optional) - Field of view covered by camera. Default to `75`. + + `near` (Number, optional) - Distance of near clipping plane. Default to `1`. + + `far` (Number, optional) - Distance of far clipping plane. Default to `100`. + + `aspect` (Number, optional) - Aspect ratio. Default to the viewport's `width/height`. See [Viewport constructor](/docs/api-reference/viewport.md#constructor) for additional parameters, especially for specifying alternate projection matrices, geospatial anchor etc. +## Methods + +Inherits all [Viewport methods](/docs/api-reference/viewport.md#methods). + + ## Remarks * Like all `Viewport`s, the `ThirdPersonViewport` will work with all geospatial coordinate systems if a geospatial "anchor point" is supplied through the `longitude`, `latitude` and `zoom` options. The `position` vector will then be interpreted as meter offsets from this anchor point. ## Source -[src/core/viewports/perspective-viewport.js](https://github.com/uber/deck.gl/blob/5.1-release/src/core/viewports/perspective-viewport.js) +[modules/core/src/core/viewports/perspective-viewport.js](https://github.com/uber/deck.gl/blob/5.2-release/modules/core/src/core/viewports/perspective-viewport.js) diff --git a/docs/api-reference/view.md b/docs/api-reference/view.md index 56cbf8b4889..99f04d1cce0 100644 --- a/docs/api-reference/view.md +++ b/docs/api-reference/view.md @@ -20,58 +20,67 @@ const view = new View({}); | `ORTHOGRAPHIC_2D` | Builds orthographic projection from `left`, `right`, `top`, `bottom`, `near` and `far` parameters. | -## Methods +## Constructor -### constructor +```js +const view = View({id, x, y, width, height, ...}); +``` -`View({id, x, y, width, height, })` +Parameters: -* `id` (String) +* `opts` (Object) - View options -* `x`=`0` (String|Number) - A relative or absolute position -* `y`=`0` (String|Number) - A relative or absolute position -* `width`=`'100%'` (String|Number) - A relative or absolute extent -* `height`=`'100%'` (String|Number) - A relative or absolute extent + + `id` (String) + + `x` (String|Number) - A relative or absolute position. Default `0`. + + `y` (String|Number) - A relative or absolute position. Default `0`. + + `width` (String|Number) - A relative or absolute extent. Default `'100%'`. + + `height` (String|Number) - A relative or absolute extent. Default `'100%'`. + + `type` (`Viewport`) - The constructor of the viewport. Default `Viewport`. -* `type`=`Viewport` (`Viewport`) - + Projection Matrix Parameters -Projection Matrix Parameters -* `projectionMode`=`PROJECTION.PERSPECTIVE` (Enum) - the kind of projection matrix -* `fov` (Number, optional) - Field of view covered by camera. Default to `75`. -* `near` (Number, optional) - Distance of near clipping plane. Default to `1`. -* `far` (Number, optional) - Distance of far clipping plane. Default to `100`. + + `projectionMode` (Enum) - the kind of projection matrix. Default `PROJECTION.PERSPECTIVE`. + + `fov` (Number, optional) - Field of view covered by camera. Default to `75`. + + `near` (Number, optional) - Distance of near clipping plane. Default to `1`. + + `far` (Number, optional) - Distance of far clipping plane. Default to `100`. + + `left` + + `right` -* `left` -* `right` + Advanced usage -Advanced usage -* `getProjectionMatrix` (Array[16], optional) - Function that returns a projection matrix. + + `getProjectionMatrix` (Array[16], optional) - Function that returns a projection matrix. +## Methods -### equals +##### `equals` Returns `true` if the supplied `View` instance is identical (equivalent) with this view. A value of `false` does not guarantee that the views are not equivalent. `View.equals(view)` -- `view` (View) - The view to compare with. + +* `view` (View) - The view to compare with. Returns: -- `true` if the given view is identical to the current one. +* `true` if the given view is identical to the current one. -### getViewport -`View.getViewport({width, height, viewState})` +##### `getViewport` + +```js +View.getViewport({width, height, viewState}) +``` Builds a viewport using the viewport type and props in the `View` and provided `width`, `height` and `view state`. -### getMatrix +##### `getMatrix` -`View.getMatrix({width, height})` +```js +View.getMatrix({width, height}) +``` -* `viewMatrix` (Array[16], optional) - View matrix. Default to identity matrix. -Defaults is to create from `fov`, `near`, `far` opts (aspect is calculated). +* `viewMatrix` (Array[16], optional) - View matrix. Default to identity matrix. Defaults is to create from `fov`, `near`, `far` opts (aspect is calculated). A projection matrix depends on the aspect ratio and needs to be recalculated whenever width and height changes. @@ -83,4 +92,4 @@ A projection matrix depends on the aspect ratio and needs to be recalculated whe ## Source -[src/core/views/view.js](https://github.com/uber/deck.gl/blob/5.0-release/src/core/views/view.js) +[modules/core/src/core/views/view.js](https://github.com/uber/deck.gl/blob/5.0-release/modules/core/src/core/views/view.js) diff --git a/docs/api-reference/viewport.md b/docs/api-reference/viewport.md index 7ae980e745d..ec282630fb9 100644 --- a/docs/api-reference/viewport.md +++ b/docs/api-reference/viewport.md @@ -1,108 +1,122 @@ # Viewport Class -> The `Viewport` class is normally not instantiated directly. Firstly, the `View` class is more commonly used by apps, and even when a `Viewport` is needed, one of its subclasses is typically used. However, in cases where the application wants to use "externally" generated view or projection matrices (e.g. when using the WebVR API), the `Viewport` class can be useful. - A deck.gl `Viewport` is essentially a geospatially enabled camera, and combines a number of responsibilities: + * It enables projection and unprojection of coordinates (between world and viewport), both in JavaScript and in GLSL. * It also contains the size and position of the target rectangle on screen where the camera will render. * The viewport class provides both direct `project`/`unproject` function members as well as projection matrices including `view` and `projection` matrices, and can generate their inverses as well to facilitate e.g. lighting calculations in WebGL shaders. * In geospatial setups, Viewports can contain geospatial anchors. For more information: + * See the deck.gl [Viewports](/docs/advanced/viewports.md) article. * See the math.gl article on [View and Projection Matrices](https://uber-web.github.io/math.gl/#/documentation/articles/view-and-projection-matrices) ## Usage +The `Viewport` class is normally not instantiated directly. Firstly, the `View` class is more commonly used by apps, and even when a `Viewport` is needed, one of its subclasses is typically used. However, in cases where the application wants to use "externally" generated view or projection matrices (e.g. when using the WebVR API), the `Viewport` class can be useful. + + +## Constructor + ```js -const viewport = new Viewport({width: 500, height: 500, ...}); +new Viewport({width: 500, height: 500, viewMatrix, projectionMatrix, ...}); ``` -## Methods +Parameters + +* `opts` (Object) - Viewport options + + + `x` (Number) - Default `0` + + `y` (Number) - Default `0` + + `width` (Number) - Width of "viewport" or window. Default `1`. + + `height` (Number) - Height of "viewport" or window. Default `1`. + + `viewMatrix` (Array[16], optional) - View matrix. Defaults to identity matrix. + + `projectionMatrix` (Array[16], optional) - Projection matrix. -### Constructor + Position parameters -`new Viewport({width: 500, height: 500, viewMatrix, projectionMatrix, ...});` + + `position` + + `modelMatrix` -View Parameters -* `x`=`0` -* `y`=`0` -* `width`=`1` (`Number`) - Width of "viewport" or window. -* `height`=`1` (`Number`) - Height of "viewport" or window. -* `viewMatrix`= (`Array[16]`, optional) - View matrix. Defaults to identity matrix. -* `projectionMatrix` (`Array[16]`, optional) - Projection matrix. + Geospatial Anchor Options (Optional) -Position parameters -* `position` -* `modelMatrix` + + `latitude` (Number, optional) - Center of viewport on map (alternative to center). + + `longitude` (Number, optional) - Center of viewport on map (alternative to center). + + `zoom` (Number, optional) - [zoom level](https://wiki.openstreetmap.org/wiki/Zoom_levels) . + + `focalDistance` (Number, optional) - modifier of viewport scale if `zoom` is not supplied. Corresponds to the number of pixels per meter. Default to `1`. -Geospatial Anchor Options (Optional) -* `latitude`=`37` (`Number`, optional) - Center of viewport on map (alternative to center). -* `longitude`=`-122` (`Number`, optional) - Center of viewport on map (alternative to center). -* `zoom`=`11` (`Number`, optional) - [zoom level](https://wiki.openstreetmap.org/wiki/Zoom_levels) . -* `focalDistance` (Number, optional) - modifier of viewport scale if `zoom` is not supplied. Corresponds to the number of pixels per meter. Default to `1`. + Projection Matrix Parameters (Optional). -Projection Matrix Parameters (Optional). -* `orthographic`=`false` - whether to create an orthographic or perspective projection matrix. -* `fov`=`75` (`Number`) - Field of view covered by camera, in the perspective case. -* `focalDistance`=`1` - (orthographic projections only). The distance at which the field-of-view frustum is sampled to extract the extents of the view box. -* `aspect`=`1` (`Number`) - Aspect ratio. Defaults to the viewport's `width/height`. -* `near`=`0.1` (`Number`) - Distance of near clipping plane. -* `far`=`500` (`Number`) - Distance of far clipping plane.. -- Option 3: Specify parameters for an orthographic projection matrix. Same parameters + + `orthographic` (Boolean) - whether to create an orthographic or perspective projection matrix. Default `false`. + + `fov` (Number) - Field of view covered by camera, in the perspective case. Default `75`. + + `focalDistance` (Number) - (orthographic projections only) The distance at which the field-of-view frustum is sampled to extract the extents of the view box. Default `1`. + + `aspect` (Number) - Aspect ratio. Defaults to the viewport's `width/height`. + + `near` (Number) - Distance of near clipping plane. Default `0.1`. + + `far` (Number) - Distance of far clipping plane. Default `1000`. Remarks: + * If the `projectionMatrix` parameter is not supplied, `Viewport` will try to create a projection matrix from the project matrix parameters. +## Methods -### equals +##### `equals` Parameters: -- `viewport` (Viewport) - The viewport to compare with. +* `viewport` (Viewport) - The viewport to compare with. Returns: -- `true` if the given viewport is identical to the current one. +* `true` if the given viewport is identical to the current one. -### project +##### `project` Projects latitude, longitude (and altitude) to pixel coordinates in window using viewport projection parameters. Parameters: - - `coordinates` (Array) - `[lng, lat, altitude]` Passing an altitude is optional. - - `opts` (Object) - - `topLeft` (Boolean, optional) - Whether projected coords are top left. Default to `true`. +* `coordinates` (Array) - `[lng, lat, altitude]` Passing an altitude is optional. +* `opts` (Object) + + `topLeft` (Boolean, optional) - Whether projected coords are top left. Default to `true`. + +Returns: + +* `[x, y]` or `[x, y, z]` in pixels coordinates. `z` is pixel depth. + + If input is `[lng, lat]`: returns `[x, y]`. + + If input is `[lng, lat, Z]`: returns `[x, y, z]`. -Returns: `[x, y]` or `[x, y, z]` in pixels coordinates. `z` is pixel depth. -- If input is `[lng, lat]`: returns `[x, y]`. -- If input is `[lng, lat, Z]`: returns `[x, y, z]`. +Note: -Note: By default, returns top-left coordinates for canvas/SVG type render +* By default, returns top-left coordinates for canvas/SVG type render -### unproject +##### `unproject` Unproject pixel coordinates on screen onto [lng, lat, altitude] on map. Parameters: - - `pixels` (Array) - `[x, y, z]` Passing a `z` is optional. - - `opts` (Object) - - `topLeft` (Boolean, optional) - Whether projected coords are top left. Default to `true`. - - `targetZ` (Number, optional) - If pixel depth `z` is not specified in `pixels`, this is used as the elevation plane to unproject onto. Default `0`. +* `pixels` (Array) - `[x, y, z]` Passing a `z` is optional. +* `opts` (Object) + + `topLeft` (Boolean, optional) - Whether projected coords are top left. Default to `true`. + + `targetZ` (Number, optional) - If pixel depth `z` is not specified in `pixels`, this is used as the elevation plane to unproject onto. Default `0`. + +Returns: + +* `[lng, lat]` or `[longitude, lat, Z]` in map coordinates. `Z` is elevation in meters. + + If input is `[x, y]` without specifying `opts.targetZ`: returns `[lng, lat]`. + + If input is `[x, y]` with `opts.targetZ`: returns `[lng, lat, targetZ]`. + + If input is `[x, y, z]`: returns `[lng, lat, Z]`. -Returns: `[lng, lat]` or `[longitude, lat, Z]` in map coordinates. `Z` is elevation in meters. -- If input is `[x, y]` without specifying `opts.targetZ`: returns `[lng, lat]`. -- If input is `[x, y]` with `opts.targetZ`: returns `[lng, lat, targetZ]`. -- If input is `[x, y, z]`: returns `[lng, lat, Z]`. +Note: -Note: By default, takes top-left coordinates from JavaScript mouse events. +* By default, takes top-left coordinates from JavaScript mouse events. ## Remarks @@ -115,4 +129,4 @@ Note: By default, takes top-left coordinates from JavaScript mouse events. ## Source -[src/core/viewports/viewport.js](https://github.com/uber/deck.gl/blob/5.1-release/src/core/viewports/viewport.js) +[modules/core/src/core/viewports/viewport.js](https://github.com/uber/deck.gl/blob/5.2-release/modules/core/src/core/viewports/viewport.js) diff --git a/docs/api-reference/web-mercator-viewport.md b/docs/api-reference/web-mercator-viewport.md index b25e1bc9256..4d4b5b437b2 100644 --- a/docs/api-reference/web-mercator-viewport.md +++ b/docs/api-reference/web-mercator-viewport.md @@ -9,82 +9,96 @@ For more information consult the [Viewports](/docs/advanced/viewports.md) articl ## Usage The `WebMercatorViewport` is the default viewport for deck.gl. If you are using the `DeckGL` React component you may not even need to instantiate it explicitly. -```js + +```jsx import DeckGL from 'deck.gl'; - + + ``` -```js +Is equivalent to + +```jsx import DeckGL, {WebMercatorViewport} from 'deck.gl'; -const viewport = new WebMercatorViewport(width, height, longitude, latitude, zoom, pitch, bearing}); +const viewport = new WebMercatorViewport({width, height, longitude, latitude, zoom, pitch, bearing}); + ``` -## Methods -### Constructor +## Constructor + +```js +new WebMercatorViewport({width, height, longitude, latitude, zoom, pitch, bearing}); +``` Parameters: -- `opts` (Object) - Orthogonal view options - * `width` (Number) - Width of "viewport" or window. Default to `1`. - * `height` (Number) - Height of "viewport" or window. Default to `1`. +* `opts` (Object) - Web Mercator viewport options + + + `width` (Number) - Width of "viewport" or window. Default to `1`. + + `height` (Number) - Height of "viewport" or window. Default to `1`. web mercator style arguments: - * `latitude` (Number, optional) - Center of viewport on map (alternative to center). Default to `37`. - * `longitude` (Number, optional) - Center of viewport on map (alternative to center). Default to `-122`. - * `zoom` (Number, optional) - `center`. Default to `11`. - * `pitch` (Number, optional) - Camera angle in degrees (0 is straight down). Default to `0`. - * `bearing` (Number, optional) - Map rotation in degrees (0 means north is up). Default to `0`. - * `altitude` (Number, optional) - Altitude of camera in screen units. Default to `1.5`. + + + `latitude` (Number, optional) - Center of viewport on map (alternative to center). Default to `37`. + + `longitude` (Number, optional) - Center of viewport on map (alternative to center). Default to `-122`. + + `zoom` (Number, optional) - `center`. Default to `11`. + + `pitch` (Number, optional) - Camera angle in degrees (0 is straight down). Default to `0`. + + `bearing` (Number, optional) - Map rotation in degrees (0 means north is up). Default to `0`. + + `altitude` (Number, optional) - Altitude of camera in screen units. Default to `1.5`. projection matrix arguments: - * farZMultiplier (Number, optional) - Default to `10`. + + + `farZMultiplier` (Number, optional) - Default to `10`. Remarks: - - Altitude has a default value that matches assumptions in mapbox-gl - - `width` and `height` are forced to 1 if supplied as 0, to avoid - division by zero. This is intended to reduce the burden of apps to - to check values before instantiating a `Viewport`. - - When using mercatorProjection, per cartographic tradition, longitudes and - latitudes are specified as degrees. + +* `altitude` has a default value that matches assumptions in mapbox-gl +* `width` and `height` are forced to 1 if supplied as 0, to avoid division by zero. This is intended to reduce the burden of apps to check values before instantiating a `Viewport`. +* When using Mercator projection, per cartographic tradition, longitudes and latitudes are specified as degrees. Inherits all [Viewport methods](/docs/api-reference/viewport.md#methods). -### projectFlat +## Methods + +##### `projectFlat` Project `[longitude, latitude]` on sphere onto "screen pixel" coordinates `[x, y]` without considering any perspective (effectively ignoring pitch, bearing and altitude). Parameters: - - `coordinates` (Array) - `[longitude, latitude]` coordinates. - - `scale` (Number) - Map zoom scale calculated from `Math.pow(2, zoom)`. +* `coordinates` (Array) - `[longitude, latitude]` coordinates. +* `scale` (Number) - Map zoom scale calculated from `Math.pow(2, zoom)`. Returns: - - Screen coordinates in `[x, y]`. +* Screen coordinates in `[x, y]`. -### unprojectFlat +##### `unprojectFlat` Unprojects a screen coordinate `[x, y]` to `[longitude, latitude]` on sphere without considering any perspective (effectively ignoring pitch, bearing and altitude). Parameters: - - `pixels` (Array) - `[x, y]` - - `scale` (Number) - Map zoom scale calculated from `Math.pow(2, zoom)`. + +* `pixels` (Array) - `[x, y]` +* `scale` (Number) - Map zoom scale calculated from `Math.pow(2, zoom)`. Returns: - - Map or world coordinates in `[longitude, latitude]`. +* Map or world coordinates in `[longitude, latitude]`. -### getDistanceScales +##### `getDistanceScales` Returns: -- An object with precalculated distance scales allowing conversion between + +* An object with precalculated distance scales allowing conversion between lnglat deltas, meters and pixels. Remarks: + * The returned scales represent simple linear approximations of the local Web Mercator projection scale around the viewport center. Error increases with distance from viewport center (Very roughly 1% per 100km). @@ -93,47 +107,47 @@ Remarks: precision, which can greatly outweigh the small linear approximation error mentioned above. -### metersToLngLatDelta +##### `metersToLngLatDelta` Converts a meter offset to a lnglat offset using linear approximation. For information on numerical precision, see remarks on `getDistanceScales`. Parameters: -- `xyz` (Array) - Array of `[x, y, z]` in meter deltas. Passing a `z` is optional. +* `xyz` (Array) - Array of `[x, y, z]` in meter deltas. Passing a `z` is optional. Returns: -- Array of deltas in `[longitude, latitude]` or `[longitude, latitude, altitude]` -if `z` is provided. +* Array of deltas in `[longitude, latitude]` or `[longitude, latitude, altitude]` if `z` is provided. -### lngLatDeltaToMeters +##### `lngLatDeltaToMeters` Converts a lnglat offset to a meter offset using linear approximation. For information on numerical precision, see remarks on [`getDistanceScales`](/docs/api-reference/web-mercator-viewport.md#-getdistancescales-). Parameters: -- `deltaLngLatZ` - Array of `[longitude, latitude, altitude]` deltas. -Passing a `altitude` is optional. + +* `deltaLngLatZ` - Array of `[longitude, latitude, altitude]` deltas. Passing a `altitude` is optional. Returns: -- Array of meter deltas in `[x, y]` or `[x, y, z]` if `altitude` is provided. -### addMetersToLngLat +* Array of meter deltas in `[x, y]` or `[x, y, z]` if `altitude` is provided. + +##### `addMetersToLngLat` Add a meter delta to a base lnglat coordinate using linear approximation. For information on numerical precision, see remarks on [`getDistanceScales`](/docs/api-reference/web-mercator-viewport.md#-getdistancescales-). Parameters: -- `lngLatZ` (Array) - Base coordinate in `[longitude, latitude, altitude]`. -Passing a `altitude` is optional. -- `xyz` (Array) - Array of `[x, y, z]` in meter deltas. Passing a `z` is optional. + +* `lngLatZ` (Array) - Base coordinate in `[longitude, latitude, altitude]`. Passing a `altitude` is optional. +* `xyz` (Array) - Array of `[x, y, z]` in meter deltas. Passing a `z` is optional. Returns: -- New coordinate array in `[longitude, latitude]` or `[longitude, latitude, altitude]` -if `z` is provided. + +* New coordinate array in `[longitude, latitude]` or `[longitude, latitude, altitude]` if `z` is provided. ## Remarks @@ -144,4 +158,5 @@ if `z` is provided. ## Source -[src/core/viewports/web-mercator-viewport.js](https://github.com/uber/deck.gl/blob/5.1-release/src/core/viewports/web-mercator-viewport.js) + +[modules/core/src/core/viewports/web-mercator-viewport.js](https://github.com/uber/deck.gl/blob/5.2-release/modules/core/src/core/viewports/web-mercator-viewport.js) diff --git a/docs/developer-guide/building-apps.md b/docs/developer-guide/building-apps.md index 6b858f0f19a..10a31d6851f 100644 --- a/docs/developer-guide/building-apps.md +++ b/docs/developer-guide/building-apps.md @@ -21,9 +21,11 @@ When installed from npm, deck.gl and related libraries come with three separate | `dist/es6` | `esnext` | This distribution uses `babel-preset-env` and with very few exceptions essentially untranspiled ES6/ES2015 code. This is the smallest distribution, that will three-shake best, and is intended to be the best choice if you are only targeting "evergreen" browsers. | You will have to check the documentation of your particular bundler to see what configuration options are available: + * Webpack 4 allows you to choose the `esnext` distribution by specifying a `resolve.mainFields` array. -* Webpack 2 and later will pick `module` main field over `main` if it is available -For other bundlers, please refer to the respective documentation +* Webpack 2 and later will pick `module` main field over `main` if it is available. + +For other bundlers, please refer to the respective documentation. ### About Tree-Shaking @@ -31,6 +33,7 @@ For other bundlers, please refer to the respective documentation deck.gl was designed from the start to leverage tree-shaking. This technique has been talked about for quite some time but has been slow in actually providing the expected benefits. With the combination of webpack 4 and babel 7 we are finally starting to see significant results, so you may want to experiment with upgrading your bundler if you are not getting results. Note that tree-shaking still has limitations: + * At least in webpack, tree shaking is done by the uglifierm, which is typically only run on production builds, so it is typically not possible to assess the benefits of tree shaking during development. In addition, this makes it even harder to make statements about bundle size impact from looking at bundle sizes in development builds. The recommendation is to always measure impact on your final production builds. * Static dependency analyzers err on the side of safety and will still include any symbol it is not sure will never be used. * This is compounded by the fact that there are side effects in various language feature that complicate or defeat current static dependency analysis techniques, causing "dead code" to still be bundled. The good news is that the analyzers are getting better. @@ -50,6 +53,7 @@ So, what bundle size impact should you expect? When do you know if you have set | ES5 | 754 KB (176 KB) | 748 KB (166 KB) | Transpiled to ES5, no tree-shaking | Notes: + * Numbers represent the minified bundle size of a minimal application, bundled with Webpack 4, which means that the results benefit from some tree shaking. * The number in parenthesis is the compressed bundle size. This is how much bigger you might expect your compressed bundle to get. diff --git a/docs/developer-guide/testing/README.md b/docs/developer-guide/testing/README.md index e2c0157fcfc..1289e91324b 100644 --- a/docs/developer-guide/testing/README.md +++ b/docs/developer-guide/testing/README.md @@ -1,6 +1,7 @@ # @deck.gl/test-utils A set of utilities to facilitate testing deck.gl layers. Tests can be run: + * completely in Node.js (lifecycle tests only). * completely in the Browser (lifecycle and rendering tests). * from Node in a controlled Browser instance (`TestDriver` classes). @@ -9,11 +10,14 @@ A set of utilities to facilitate testing deck.gl layers. Tests can be run: ## Installing The deck.gl test utilities are published as a separate npm module that is only intended to be used during development. Install it as as a "dev dependency" as follows: -``` + +```bash npm install --save-dev @deck.gl/test-utils ``` + or -``` + +```bash yarn add -D @deck.gl/test-utils ``` diff --git a/docs/developer-guide/testing/testing.md b/docs/developer-guide/testing/testing.md index a865fe91e6b..1cccc7d8957 100644 --- a/docs/developer-guide/testing/testing.md +++ b/docs/developer-guide/testing/testing.md @@ -18,6 +18,7 @@ For details on how the automation works, see the [probe.gl](https://uber-web.git ## Usage In your node.js start script: + ```js // This is the script that runs in Node.js and starts the browser const {BrowserTestDriver} = require('probe.gl/test'); @@ -36,6 +37,7 @@ Create a `BrowserTestDriver` instance. `renderTestDriver.run()` Runs the tests: + * starts a Chrome browser instance, * starts a server (typically a webpack-dev-server) that bundles a test script. * the test script renders a set of tests (described below), compares the output against golden images diff --git a/docs/developer-guide/testing/using-with-unit-test-frameworks.md b/docs/developer-guide/testing/using-with-unit-test-frameworks.md index 3c1bad659fe..01b5d296b4b 100644 --- a/docs/developer-guide/testing/using-with-unit-test-frameworks.md +++ b/docs/developer-guide/testing/using-with-unit-test-frameworks.md @@ -6,6 +6,7 @@ Lifecycle test functions are designed to allow for intregration with different u ## Example The lifecycle test drivers simplify testing of successive updates of a layer. This example uses `tape`. + ```js import test from 'tape-catch'; import * as FIXTURES from 'deck.gl/test/data/geojson-data'; diff --git a/docs/get-started/getting-started.md b/docs/get-started/getting-started.md index 3c834f3d70c..715bb4c4cb7 100644 --- a/docs/get-started/getting-started.md +++ b/docs/get-started/getting-started.md @@ -3,10 +3,13 @@ ## Installation First, you need to install the deck.gl (and luma.gl) frameworks + ```bash npm install --save deck.gl ``` + or + ```bash yarn add deck.gl ``` @@ -15,45 +18,54 @@ yarn add deck.gl ## Running the Examples -The deck.gl repository contains an [examples folder](https://github.com/uber/deck.gl/tree/5.1-release/examples) with a selection of small, standalone examples that could be good starting points for your application. +The deck.gl repository contains an [examples folder](https://github.com/uber/deck.gl/tree/5.2-release/examples) with a selection of small, standalone examples that could be good starting points for your application. You should be able to copy these folders to your preferred locations, and get them running simply as follows: Clone the deck.gl repo, if you haven't already + ```bash git clone git@github.com:uber/deck.gl.git ``` -For most consistent results, it is recommended that you check out the latest release branch (e.g. `git checkout 5.1-release`) instead of `master` when running examples. +For most consistent results, it is recommended that you check out the latest release branch (e.g. `git checkout 5.2-release`) instead of `master` when running examples. + ```bash -git checkout 5.1-release +git checkout 5.2-release ``` Change directory to the example you are interested in + ```bash cd deck.gl/examples/... ``` Then install dependencies using the installer of your choice: + ```bash npm install ``` + or + ```bash yarn ``` and then running using: + ```bash npm start ``` If the example uses a mapbox base map you need a [Mapbox access token](/docs/get-started/using-with-mapbox-gl.md) + ```bash export MapboxAccessToken={Your Token Here} && npm start ``` If you want to build the example against the latest deck.gl source code in the cloned repo (rather than the published version of deck.gl listed in the examples `package.json`) + ```bash npm run start-local ``` diff --git a/docs/get-started/interactivity.md b/docs/get-started/interactivity.md index 4f3a06acf2f..4a2421a71b2 100644 --- a/docs/get-started/interactivity.md +++ b/docs/get-started/interactivity.md @@ -61,7 +61,8 @@ For applications that have basic event handling needs, deck.gl has built-in supp There are two ways to subscribe to the built-in picking event handling: -- Set callback for each pickable layer by setting [`onHover`](/docs/api-reference/layer.md#-onhover-function-optional-) and [`onClick`](/docs/api-reference/layer.md#-onclick-function-optional-) props: +* Set callback for each pickable layer by setting [`onHover`](/docs/api-reference/layer.md#-onhover-function-optional-) and [`onClick`](/docs/api-reference/layer.md#-onclick-function-optional-) props: + ```js const layer = new ScatterplotLayer({ ... @@ -70,7 +71,9 @@ const layer = new ScatterplotLayer({ onClick: info => console.log('Clicked:', info) }); ``` -- Set callback for all pickable layers by setting [`onLayerHover`](/docs/api-reference/deckgl.md#-onlayerhover-function-optional-) and [`onLayerClick`](/docs/api-reference/deckgl.md#-onlayerclick-function-optional-) props of the `DeckGL` canvas: + +* Set callback for all pickable layers by setting [`onLayerHover`](/docs/api-reference/deckgl.md#-onlayerhover-function-optional-) and [`onLayerClick`](/docs/api-reference/deckgl.md#-onlayerclick-function-optional-) props of the `DeckGL` canvas: + ```js diff --git a/docs/get-started/using-with-mapbox-gl.md b/docs/get-started/using-with-mapbox-gl.md index bf1cdbdbff3..03c8976c3a0 100644 --- a/docs/get-started/using-with-mapbox-gl.md +++ b/docs/get-started/using-with-mapbox-gl.md @@ -4,7 +4,7 @@ While a deck.gl application could choose to render on top of any JavaScript Map ## About react-map-gl -As shown in the [examples](https://github.com/uber/deck.gl/tree/5.1-release/examples/), the `DeckGL` React component works especially well as the child of a React component such as react-map-gl that displays a map using parameters similar to the deck.gl Viewport (i.e. latitude, longitude, zoom etc). In this configuration your deck.gl layers will render as a perfectly synchronized geospatial overlay over the underlying map. +As shown in the [examples](https://github.com/uber/deck.gl/tree/5.2-release/examples/), the `DeckGL` React component works especially well as the child of a React component such as react-map-gl that displays a map using parameters similar to the deck.gl Viewport (i.e. latitude, longitude, zoom etc). In this configuration your deck.gl layers will render as a perfectly synchronized geospatial overlay over the underlying map. ## About Mapbox Tokens @@ -13,6 +13,7 @@ To show maps from a service such as Mapbox you will need to register with Mapbox To get a token, you typically need to register (create an account) with the map data provider (mapbox), and apply for a token. The token will usually be free until a certain level of traffic is exceeded. While the token will need to be hard-coded into your application in production, there are several ways to provide a token during development: + * Modify file to specify your Mapbox token, * Set an environment variable (MapboxAccessToken) - through the use of a webpack loader or browserify transform, see the hello-world examples for details. * Provide a token in the URL. See documentation of react-map-gl. diff --git a/docs/get-started/using-with-react.md b/docs/get-started/using-with-react.md index 5265df26b98..070ae318ce5 100644 --- a/docs/get-started/using-with-react.md +++ b/docs/get-started/using-with-react.md @@ -90,6 +90,7 @@ render(, document.body.appendChild(document.createElement('div'))); ## Using JSX with deck.gl Layers It is possible to use JSX syntax to create deck.gl layers as React children of the `DeckGL` React components, instead of providing them as ES6 class instances to the `layers` prop. There are no performance advantages to this syntax but it can allow for a more consistent, React-like coding style. + ```jsx render() { return ( diff --git a/docs/layers/README.md b/docs/layers/README.md index 6a0afb20ebc..57a714d813b 100644 --- a/docs/layers/README.md +++ b/docs/layers/README.md @@ -23,6 +23,6 @@ These are layers from an older releases that now have better counterparts. They ## Sample Layers -deck.gl provides a number of sample layers in the [examples folders](https://github.com/uber/deck.gl/tree/5.1-release/examples/sample-layers) intended to illustrate various ideas and approaches to how layers can be designed. These layers sometimes have documentation in the example code, but they are not listed here in the official documentation. +deck.gl provides a number of sample layers in the [examples folders](https://github.com/uber/deck.gl/tree/5.2-release/examples/sample-layers) intended to illustrate various ideas and approaches to how layers can be designed. These layers sometimes have documentation in the example code, but they are not listed here in the official documentation. To use one of the sample layers an application simply needs to copy it into its own source tree. This is necessary because these layers are not included in the deck.gl distribution (i.e. they are not `export`ed by deck.gl). diff --git a/docs/layers/arc-layer.md b/docs/layers/arc-layer.md index 28db28e1064..c9f053df4b6 100644 --- a/docs/layers/arc-layer.md +++ b/docs/layers/arc-layer.md @@ -39,13 +39,13 @@ Inherits from all [Base Layer](/docs/api-reference/layer.md) properties. ##### `strokeWidth` (Number, optional) -- Default: `1` +* Default: `1` The stroke width used to draw each arc. Unit is pixels. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode @@ -53,19 +53,19 @@ Whether the layer should be rendered in high-precision 64-bit mode ##### `getSourcePosition` (Function, optional) -- Default: `object => object.sourcePosition` +* Default: `object => object.sourcePosition` Method called to retrieve the source position of each object. ##### `getTargetPosition` (Function, optional) -- Default: `object => object.targetPosition` +* Default: `object => object.targetPosition` Method called to retrieve the target position of each object. ##### `getSourceColor` (Function, optional) -- Default: `object => object.color` +* Default: `object => object.color` Method called to determine the rgba color of the source. If the alpha parameter is not provided, it will be set to `255`. @@ -74,15 +74,17 @@ If the method does not return a value for the given object, fallback to `[0, 0, ##### `getTargetColor` (Function, optional) -- Default `object => object.color` +* Default `object => object.color` Method called to determine the rgba color of the source. + * If the alpha parameter is not provided, it will be set to `255`. * If the method does not return a value for the given object, fallback to `[0, 0, 255, 255]`. ## Source -[src/core-layers/arc-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/arc-layer) - +[modules/core/src/core-layers/arc-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/arc-layer) + + diff --git a/docs/layers/geojson-layer.md b/docs/layers/geojson-layer.md index 971da8b2c61..a9c814346bf 100644 --- a/docs/layers/geojson-layer.md +++ b/docs/layers/geojson-layer.md @@ -44,7 +44,7 @@ pure GeoJson "payloads". ##### `filled` (Boolean, optional) -- Default: `true` +* Default: `true` Whether to draw filled polygons (solid fill). Note that for each polygon, only the area between the outer polygon and any holes will be filled. This @@ -52,7 +52,7 @@ prop is effective only when the polygon is NOT extruded. ##### `stroked` (Boolean, optional) -- Default: `false` +* Default: `false` Whether to draw an outline around polygons (solid fill). Note that for complex polygons, both the outer polygon as well the outlines of @@ -63,17 +63,18 @@ any holes will be drawn. Extrude Polygon and MultiPolygon features along the z-axis if set to true. The height of the drawn features is obtained using the `getElevation` accessor. -- Default: `false` +* Default: `false` ##### `wireframe` (Boolean, optional) -- Default: `false` +* Default: `false` Whether to generate a line wireframe of the hexagon. The outline will have "horizontal" lines closing the top and bottom polygons and a vertical line (a "strut") for each vertex on the polygon. Remarks: + * These lines are rendered with `GL.LINE` and will thus always be 1 pixel wide. * Wireframe and solid extrusions are exclusive, you'll need to create two layers with the same data if you want a combined rendering effect. @@ -81,7 +82,7 @@ Remarks: ##### `lineWidthScale` (Boolean, optional) -- Default: `1` +* Default: `1` The line width multiplier that multiplied to all lines, including the `LineString` and `MultiLineString` features and also the outline for `Polygon` and `MultiPolygon` @@ -89,32 +90,32 @@ features if the `stroked` attribute is true. ##### `lineWidthMinPixels` (Number, optional) -- Default: `0` +* Default: `0` The minimum line width in pixels. ##### `lineWidthMaxPixels` (Number, optional) -- Default: Number.MAX_SAFE_INTEGER +* Default: Number.MAX_SAFE_INTEGER The maximum line width in pixels. ##### `lineJointRounded` (Boolean, optional) -- Default: `false` +* Default: `false` Type of joint. If `true`, draw round joints. Otherwise draw miter joints. ##### `lineMiterLimit` (Number, optional) -- Default: `4` +* Default: `4` The maximum extent of a joint in ratio to the stroke width. Only works if `lineJointRounded` is `false`. ##### `elevationScale` (Number, optional) -- Default: `1` +* Default: `1` Elevation multiplier. The final elevation is calculated by `elevationScale * getElevation(d)`. `elevationScale` is a handy property to scale @@ -122,25 +123,25 @@ all polygon elevation without updating the data. ##### `pointRadiusScale` (Number, optional) -- Default: `1` +* Default: `1` A global radius multiplier for all points. ##### `pointRadiusMinPixels` (Number, optional) -- Default: `0` +* Default: `0` The minimum radius in pixels. ##### `pointRadiusMaxPixels` (Number, optional) -- Default: `Number.MAX_SAFE_INTEGER` +* Default: `Number.MAX_SAFE_INTEGER` The maximum radius in pixels. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode @@ -154,14 +155,14 @@ deck.gl. ##### `getLineColor` -- Default: `f => f.properties.lineColor || [0, 0, 0, 255]` +* Default: `f => f.properties.lineColor || [0, 0, 0, 255]` Called to retrieve the color of line and/or the outline of polygon color for a GeoJson feature, depending on its type. Color supports `[R, G, B]` and `[R, G, B, A]`, where `A` has a value between `0` and `255`. ##### `getFillColor` (Function, optional) -- Default: `f => f.properties.fillColor || [0, 0, 0, 255]` +* Default: `f => f.properties.fillColor || [0, 0, 0, 255]` Called to retrieve the solid color of the polygon and point features of a GeoJson. Color supports `[R, G, B]` and `[R, G, B, A]`, where `A` has a value between `0` and `255`. @@ -169,13 +170,13 @@ Note: This accessor is only called for `Polygon` and `MultiPolygon` and `Point` ##### `getRadius` -- Default: `f => f.properties.radius || f => f.properties.size || 1` +* Default: `f => f.properties.radius || f => f.properties.size || 1` Called to retrieve the radius of `Point` and `MultiPoint` feature. ##### `getLineWidth` -- Default: `f => f.properties.lineWidth || 1` +* Default: `f => f.properties.lineWidth || 1` Called to retrieve the line width in meters for a GeoJson feature. @@ -185,7 +186,7 @@ features. It is called for `Polygon` and `MultiPolygon` features if the ##### `getElevation` (Function, optional) -- Default: `f => f.properties.elevation || 1000` +* Default: `f => f.properties.elevation || 1000` Called to retrieve the elevation of a polygon feature (when `extruded` is true). @@ -194,7 +195,7 @@ otherwise will be in unit coordinates. Note: This accessor is only called for `Polygon` and `MultiPolygon` features. -### Remarks +## Remarks * By supplying a GeoJson `FeatureCollection` you can render multiple polygons, lines and points. @@ -204,5 +205,6 @@ Note: This accessor is only called for `Polygon` and `MultiPolygon` features. the color of that `Feature`. ## Source -[src/core-layers/geojson-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/geojson-layer) + +[modules/core/src/core-layers/geojson-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/geojson-layer) diff --git a/docs/layers/grid-cell-layer.md b/docs/layers/grid-cell-layer.md index d334fbe9e40..e9a53949551 100644 --- a/docs/layers/grid-cell-layer.md +++ b/docs/layers/grid-cell-layer.md @@ -43,20 +43,20 @@ Inherits from all [Base Layer](/docs/api-reference/layer.md) properties. ##### `cellSize` (Number, optional) -- Default: `1000` +* Default: `1000` Size of each grid cell in meters ##### `coverage` (Number, optional) -- Default: `1` +* Default: `1` Cell size scale factor. The size of cell is calculated by `cellSize * coverage`. ##### `elevationScale` (Number, optional) -- Default: `1` +* Default: `1` Elevation multiplier. The elevation of cell is calculated by `elevationScale * getElevation(d)`. `elevationScale` is a handy property @@ -64,13 +64,13 @@ to scale all cell elevations without updating the data. ##### `extruded` (Boolean, optional) -- Default: `true` +* Default: `true` Whether to enable grid elevation. If se to false, all grid will be flat. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode @@ -83,26 +83,26 @@ Be aware that this prop will likely be changed in a future version of deck.gl. ##### `getPosition` (Function, optional) -- Default: `cell => cell.position` +* Default: `cell => cell.position` Method called to retrieve the top left corner of each cell. Expecting [lon, lat]. ##### `getElevation` (Function, optional) -- Default: `cell => cell.elevation` +* Default: `cell => cell.elevation` Method called to retrieve the elevation of each cell. Expecting a number, 1 unit approximate to 100 meter ##### `getColor` (Function, optional) -- Default: `cell => cell.color` +* Default: `cell => cell.color` Method called to retrieve the rgba color of each cell. Expecting [r, g, b, a]. If the alpha is not provided, it will be set to `255`. ## Source -[/src/core-layers/grid-cell-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/grid-cell-layer) +[modules/core/src/core-layers/grid-cell-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/grid-cell-layer) diff --git a/docs/layers/grid-layer.md b/docs/layers/grid-layer.md index 9fd11d79a8c..21763741208 100644 --- a/docs/layers/grid-layer.md +++ b/docs/layers/grid-layer.md @@ -45,26 +45,26 @@ Inherits from all [Base Layer](/docs/api-reference/layer.md) properties. ##### `cellSize` (Number, optional) -- Default: `1000` +* Default: `1000` Size of each cell in meters ##### `colorDomain` (Array, optional) -- Default: `[min(count), max(count)]` +* Default: `[min(count), max(count)]` Color scale domain, default is set to the range of point counts in each cell. ##### `colorRange` (Array, optional) -- Default: +* Default: Color ranges as an array of colors formatted as `[255, 255, 255]`. Default is [colorbrewer](http://colorbrewer2.org/#type=sequential&scheme=YlOrRd&n=6) `6-class YlOrRd`. ##### `coverage` (Number, optional) -- Default: `1` +* Default: `1` Cell size multiplier, clamped between 0 - 1. The final size of cell is calculated by `coverage * cellSize`. Note: coverage does not affect how points @@ -72,19 +72,19 @@ are binned. Coverage are linear based. ##### `elevationDomain` (Array, optional) -- Default: `[0, max(count)]` +* Default: `[0, max(count)]` Elevation scale input domain, default is set to the extent of point counts in each cell. ##### `elevationRange` (Array, optional) -- Default: `[0, 1000]` +* Default: `[0, 1000]` Elevation scale output range ##### `elevationScale` (Number, optional) -- Default: `1` +* Default: `1` Cell elevation multiplier. The elevation of cell is calculated by `elevationScale * getElevation(d)`. @@ -92,34 +92,34 @@ Cell elevation multiplier. The elevation of cell is calculated by ##### `extruded` (Boolean, optional) -- Default: `true` +* Default: `true` Whether to enable cell elevation. Cell elevation scale by count of points in each cell. If set to false, all cell will be flat. ##### `upperPercentile` (Number, optional) -- Default: `100` +* Default: `100` Filter cells and re-calculate color by `upperPercentile`. Cells with value larger than the upperPercentile will be hidden. ##### `lowerPercentile` (Number, optional) -- Default: `0` +* Default: `0` Filter cells and re-calculate color by `lowerPercentile`. Cells with value smaller than the lowerPercentile will be hidden. ##### `elevationUpperPercentile` (Number, optional) -- Default: `100` +* Default: `100` Filter cells and re-calculate elevation by `elevationUpperPercentile`. Cells with elevation value larger than the elevationUpperPercentile will be hidden. ##### `elevationLowerPercentile` (Number, optional) -- Default: `100` +* Default: `100` Filter cells and re-calculate elevation by `elevationLowerPercentile`. Cells with elevation value smaller than the elevationLowerPercentile will be hidden. @@ -127,13 +127,11 @@ smaller than the elevationLowerPercentile will be hidden. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode -##### `lightSettings` (Object, optional) - -**EXPERIMENTAL** +##### `lightSettings` (Object, optional) **EXPERIMENTAL** This is an object that contains light settings for extruded polygons. Be aware that this prop will likely be changed in a future version of deck.gl. @@ -142,13 +140,13 @@ Be aware that this prop will likely be changed in a future version of deck.gl. ##### `getPosition` (Function, optional) -- Default: `object => object.position` +* Default: `object => object.position` Method called to retrieve the position of each point. ##### `getColorValue` (Function, optional) -- Default: `points => points.length` +* Default: `points => points.length` `getColorValue` is the accessor function to get the value that cell color is based on. It takes an array of points inside each cell as arguments, returns a number. For example, @@ -158,7 +156,7 @@ By default `getColorValue` returns the length of the points array. Note: grid layer compares whether `getColorValue` has changed to recalculate the value for each bin that its color based on. You should pass in the function defined outside the render function so it doesn't create a new function on every rendering pass. -``` +```js class MyGridLayer { getColorValue (points) { return points.length; @@ -177,7 +175,7 @@ You should pass in the function defined outside the render function so it doesn' ##### `getElevationValue` (Function, optional) -- Default: `points => points.length` +* Default: `points => points.length` Similar to `getColorValue`, `getElevationValue` is the accessor function to get the value that cell elevation is based on. It takes an array of points inside each cell as arguments, returns a number. @@ -188,17 +186,18 @@ You should pass in the function defined outside the render function so it doesn' ##### `onSetColorDomain` (Function, optional) -- Default: `() => {}` +* Default: `() => {}` This callback will be called when bin color domain has been calculated. ##### `onSetElevationDomain` (Function, optional) -- Default: `() => {}` +* Default: `() => {}` This callback will be called when bin elevation domain has been calculated. ## Source -[src/core-layers/grid-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/grid-layer) + +[modules/core/src/core-layers/grid-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/grid-layer) diff --git a/docs/layers/hexagon-cell-layer.md b/docs/layers/hexagon-cell-layer.md index 748826ca8c3..2d63fbef04a 100644 --- a/docs/layers/hexagon-cell-layer.md +++ b/docs/layers/hexagon-cell-layer.md @@ -64,14 +64,14 @@ they will be used to calculate primitive hexagon instead of `hexagonVertices` ##### `coverage` (Number, optional) -- Default: `1` +* Default: `1` Hexagon radius multiplier, between 0 - 1. The radius of hexagon is calculated by `coverage * radius` ##### `elevationScale` (Number, optional) -- Default: `1` +* Default: `1` Hexagon elevation multiplier. The elevation of hexagon is calculated by `elevationScale * getElevation(d)`. `elevationScale` is a handy property @@ -79,13 +79,13 @@ to scale all hexagon elevations without updating the data. ##### `extruded` (Boolean, optional) -- Default: `true` +* Default: `true` Whether to extrude hexagon. If se to false, all hexagons will be set to flat. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode @@ -98,25 +98,25 @@ Be aware that this prop will likely be changed in a future version of deck.gl. ##### `getCentroid` (Function, optional) -- Default: `object => object.centroid` +* Default: `object => object.centroid` Method called to retrieve the centroid of each hexagon. Centorid should be set to [lon, lat] ##### `getColor` (Function, optional) -- Default: `object => object.color` +* Default: `object => object.color` Method called to retrieve the color of each object. Color should be set to [r, g, b, a] with each number between 0-255. ##### `getElevation` (Function, optional) -- Default: `object => object.elevation` +* Default: `object => object.elevation` Method called to retrieve the elevation of each object. 1 unit approximate to 100 meters. ## Source -[src/core-layers/hexagon-cell-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/hexagon-cell-layer) +[modules/core/src/core-layers/hexagon-cell-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/hexagon-cell-layer) diff --git a/docs/layers/hexagon-layer.md b/docs/layers/hexagon-layer.md index e6f15a24b72..9e3e55fb93e 100644 --- a/docs/layers/hexagon-layer.md +++ b/docs/layers/hexagon-layer.md @@ -43,13 +43,13 @@ Inherits from all [Base Layer](/docs/api-reference/layer.md) properties. ##### `radius` (Number, optional) -- Default: `1000` +* Default: `1000` Radius of hexagon bin in meters. The hexagons are pointy-topped (rather than flat-topped). ##### `hexagonAggregator` (Function, optional) -- Default: `d3-hexbin` +* Default: `d3-hexbin` `hexagonAggregator` is a function to aggregate data into hexagonal bins. The `hexagonAggregator` takes props of the layer and current viewport as arguments. @@ -64,7 +64,7 @@ see `src/core-layers/point-density-hexagon-layer/hexagon-aggregator` ##### `colorDomain` (Array, optional) -- Default: `[min(count), max(count)]` +* Default: `[min(count), max(count)]` Color scale input domain. The color scale maps continues numeric domain into discrete color range. If not provided, the layer will set `colorDomain` to the @@ -73,14 +73,14 @@ to number of counts by passing in an arbitrary color domain. This property is ex ##### `colorRange` (Array, optional) -- Default: +* Default: Hexagon color ranges as an array of colors formatted as `[[255, 255, 255, 255]]`. Default is [colorbrewer](http://colorbrewer2.org/#type=sequential&scheme=YlOrRd&n=6) `6-class YlOrRd`. ##### `getColorValue` (Function, optional) -- Default: `points => points.length` +* Default: `points => points.length` `getColorValue` is the accessor function to get the value that bin color is based on. It takes an array of points inside each bin as arguments, returns a number. For example, @@ -92,7 +92,7 @@ recalculate the value for each bin that its color based on. You should pass in the function defined outside the render function so it doesn't create a new function on every rendering pass. -``` +```js class MyHexagonLayer { getColorValue (points) { return points.length; @@ -111,7 +111,7 @@ new function on every rendering pass. ##### `coverage` (Number, optional) -- Default: `1` +* Default: `1` Hexagon radius multiplier, clamped between 0 - 1. The final radius of hexagon is calculated by `coverage * radius`. Note: coverage does not affect how points @@ -119,7 +119,7 @@ are binned. The radius of the bin is determined only by the `radius` property. ##### `elevationDomain` (Array, optional) -- Default: `[0, max(count)]` +* Default: `[0, max(count)]` Elevation scale input domain. The elevation scale is a linear scale that maps number of counts to elevation. By default it is set to between @@ -129,13 +129,13 @@ with the same elevation scale for comparison. ##### `elevationRange` (Array, optional) -- Default: `[0, 1000]` +* Default: `[0, 1000]` Elevation scale output range ##### `getElevationValue` (Function, optional) -- Default: `points => points.length` +* Default: `points => points.length` Similar to `getColorValue`, `getElevationValue` is the accessor function to get the value that bin elevation is based on. It takes an array of points inside each bin as arguments, returns a number. @@ -148,7 +148,7 @@ new function on every rendering pass. ##### `elevationScale` (Number, optional) -- Default: `1` +* Default: `1` Hexagon elevation multiplier. The actual elevation is calculated by `elevationScale * getElevation(d)`. `elevationScale` is a handy property to scale @@ -156,41 +156,41 @@ all hexagons without updating the data. ##### `extruded` (Boolean, optional) -- Default: `false` +* Default: `false` Whether to enable cell elevation. Cell elevation scale by count of points in each cell. If set to false, all cells will be flat. ##### `upperPercentile` (Number, optional) -- Default: `100` +* Default: `100` Filter bins and re-calculate color by `upperPercentile`. Hexagons with color value larger than the upperPercentile will be hidden. ##### `lowerPercentile` (Number, optional) -- Default: `0` +* Default: `0` Filter bins and re-calculate color by `lowerPercentile`. Hexagons with color value smaller than the lowerPercentile will be hidden. ##### `elevationUpperPercentile` (Number, optional) -- Default: `100` +* Default: `100` Filter bins and re-calculate elevation by `elevationUpperPercentile`. Hexagons with elevation value larger than the elevationUpperPercentile will be hidden. ##### `elevationLowerPercentile` (Number, optional) -- Default: `100` +* Default: `100` Filter bins and re-calculate elevation by `elevationLowerPercentile`. Hexagons with elevation value smaller than the elevationLowerPercentile will be hidden. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode @@ -203,22 +203,22 @@ This is an object that contains light settings for extruded polygons. ##### `getPosition` (Function, optional) -- Default: `object => object.position` +* Default: `object => object.position` Method called to retrieve the position of each point. ##### `onSetColorDomain` (Function, optional) -- Default: `() => {}` +* Default: `() => {}` This callback will be called when bin color domain has been calculated. ##### `onSetElevationDomain` (Function, optional) -- Default: `() => {}` +* Default: `() => {}` This callback will be called when bin elevation domain has been calculated. ## Source -[src/core-layers/hexagon-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/hexagon-layer) +[modules/core/src/core-layers/hexagon-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/hexagon-layer) diff --git a/docs/layers/icon-layer.md b/docs/layers/icon-layer.md index df1f3fec141..2f9842598a1 100644 --- a/docs/layers/icon-layer.md +++ b/docs/layers/icon-layer.md @@ -49,26 +49,26 @@ Atlas image url or texture Icon names mapped to icon definitions. Each icon is defined with the following values: - - `x`: x position of icon on the atlas image - - `y`: y position of icon on the atlas image - - `width`: width of icon on the atlas image - - `height`: height of icon on the atlas image - - `anchorX`: horizontal position of icon anchor. Default: half width. - - `anchorY`: vertical position of icon anchor. Default: half height. - - `mask`: whether icon is treated as a transparency mask. +* `x`: x position of icon on the atlas image +* `y`: y position of icon on the atlas image +* `width`: width of icon on the atlas image +* `height`: height of icon on the atlas image +* `anchorX`: horizontal position of icon anchor. Default: half width. +* `anchorY`: vertical position of icon anchor. Default: half height. +* `mask`: whether icon is treated as a transparency mask. If `true`, user defined color is applied. If `false`, pixel color from the image is applied. Default: `false` ##### `sizeScale` (Number, optional) -- Default: `1` +* Default: `1` Icon size multiplier. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode @@ -76,36 +76,36 @@ Whether the layer should be rendered in high-precision 64-bit mode ##### `getPosition` (Function, optional) -- Default: `d => d.position` +* Default: `d => d.position` Method called to retrieve the position of each object, returns `[lng, lat, z]`. ##### `getIcon` (Function, optional) -- Default: `d => d.icon` +* Default: `d => d.icon` Method called to retrieve the icon name of each object, returns string. ##### `getSize` (Function, optional) -- Default: `d => d.size || 1` +* Default: `d => d.size || 1` Method called to retrieve the height of each icon, returns a number. Unit is pixels. ##### `getColor` (Function, optional) -- Default: `d => d.color || [0, 0, 0, 255]` +* Default: `d => d.color || [0, 0, 0, 255]` Method called to retrieve the color of each object, returns `[r, g, b, a]`. If the alpha component is not supplied, it is set to `255`. ##### `getAngle` (Function, optional) -- Default: `d => d.angle || 0` +* Default: `d => d.angle || 0` Method called to retrieve the rotating angle (in degree) of each object, returns a number. ## Source -[src/core-layers/icon-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/icon-layer) +[modules/core/src/core-layers/icon-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/icon-layer) diff --git a/docs/layers/line-layer.md b/docs/layers/line-layer.md index 2ac782820d0..6b026d8854a 100644 --- a/docs/layers/line-layer.md +++ b/docs/layers/line-layer.md @@ -39,13 +39,13 @@ Inherits from all [Base Layer](/docs/api-reference/layer.md) properties. ##### `strokeWidth` (Number, optional) -- Default: `1` +* Default: `1` The stroke width used to draw each line. Unit is pixels. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode @@ -53,26 +53,26 @@ Whether the layer should be rendered in high-precision 64-bit mode ##### `getSourcePosition` (Function, optional) -- Default: `object => object.sourcePosition` +* Default: `object => object.sourcePosition` Method called to retrieve the source position of each object. ##### `getTargetPosition` (Function, optional) -- Default: `object => object.targetPosition` +* Default: `object => object.targetPosition` Method called to retrieve the target position of each object. ##### `getColor` (Function, optional) -- Default: `object => object.color` +* Default: `object => object.color` Method called to determine the rgba color of the source. + * If the alpha parameter is not provided, it will be set to `255`. -* If the method does not return a value for the given object, fallback to -`[0, 0, 0, 255]`. +* If the method does not return a value for the given object, fallback to `[0, 0, 0, 255]`. ## Source -[src/core-layers/line-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/line-layer) +[modules/core/src/core-layers/line-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/line-layer) diff --git a/docs/layers/path-layer.md b/docs/layers/path-layer.md index 47f57df8db3..d387e6f7583 100644 --- a/docs/layers/path-layer.md +++ b/docs/layers/path-layer.md @@ -43,44 +43,44 @@ Inherits from all [Base Layer](/docs/api-reference/layer.md) properties. ##### `widthScale` (Number, optional) -- Default: `1` +* Default: `1` The path width multiplier that multiplied to all paths. ##### `widthMinPixels` (Number, optional) -- Default: `0` +* Default: `0` The minimum path width in pixels. ##### `widthMaxPixels` (Number, optional) -- Default: Number.MAX_SAFE_INTEGER +* Default: Number.MAX_SAFE_INTEGER The maximum path width in pixels. ##### `rounded` (Boolean, optional) -- Default: `false` +* Default: `false` Type of joint. If `true`, draw round joints. Otherwise draw miter joints. ##### `miterLimit` (Number, optional) -- Default: `4` +* Default: `4` The maximum extent of a joint in ratio to the stroke width. Only works if `rounded` is `false`. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode ##### `dashJustified` (Boolean, optional) -- Default: `false` +* Default: `false` Only effective if `getDashArray` is specified. If `true`, adjust gaps for the dashes to align at both ends. @@ -88,7 +88,7 @@ Only effective if `getDashArray` is specified. If `true`, adjust gaps for the da ##### `getPath` (Function, optional) -- Default: `(object, index) => object.paths` +* Default: `(object, index) => object.paths` Returns the specified path for the object. @@ -98,7 +98,7 @@ A path is an array of coordinates. Returns an array of color -- Default `(object, index) => object.color || [0, 0, 0, 255]` +* Default `(object, index) => object.color || [0, 0, 0, 255]` Method called to determine the rgba color of the source. @@ -107,14 +107,14 @@ If the color alpha (the fourth component) is not provided, ##### `getWidth` (Function, optional) -- Default: `(object, index) => object.width || 1` +* Default: `(object, index) => object.width || 1` Method called to determine the width to draw each path with. Unit is meters. ##### `getDashArray` (Function, optional) -- Default: `null` +* Default: `null` Method called to get the dash array to draw each path with. Returns an array of two numbers: `[dashSize, gapSize]` relative to the width of the path. Returns `[0, 0]` to draw the path in solid line. @@ -123,4 +123,4 @@ If this accessor is not specified, all paths are drawn as solid lines. ## Source -[src/core-layers/path-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/path-layer) +[modules/core/src/core-layers/path-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/path-layer) diff --git a/docs/layers/point-cloud-layer.md b/docs/layers/point-cloud-layer.md index d695618844a..05e90f0796f 100644 --- a/docs/layers/point-cloud-layer.md +++ b/docs/layers/point-cloud-layer.md @@ -39,15 +39,16 @@ Inherits from all [Base Layer](/docs/api-reference/layer.md) properties. ##### `radiusPixels` (Number, optional) -- Default: `10` +* Default: `10` Global radius of all points. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode + ##### `lightSettings` (Object, optional) **EXPERIMENTAL** This is an object that contains light settings for the point cloud. @@ -57,25 +58,26 @@ Be aware that this prop will likely be changed in a future version of deck.gl. ##### `getPosition` (Function, optional) -- Default: `object => object.position` +* Default: `object => object.position` Method called to retrieve the position of each object. ##### `getNormal` (Function, optional) -- Default: `object => object.normal` +* Default: `object => object.normal` Method called to retrieve the normal of each object. ##### `getColor` (Function, optional) -- Default: `object => object.color` +* Default: `object => object.color` Method called to retrieve the rgba color of each object. + * If the alpha parameter is not provided, it will be set to `255`. -* If the method does not return a value for the given object, fallback to -`[0, 0, 0, 255]`. +* If the method does not return a value for the given object, fallback to `[0, 0, 0, 255]`. ## Source -[src/core-layers/point-cloud-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/point-cloud-layer) + +[modules/core/src/core-layers/point-cloud-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/point-cloud-layer) diff --git a/docs/layers/polygon-layer.md b/docs/layers/polygon-layer.md index cd81cdf6600..40fd48a9e89 100644 --- a/docs/layers/polygon-layer.md +++ b/docs/layers/polygon-layer.md @@ -63,21 +63,21 @@ Inherits from all [Base Layer](/docs/api-reference/layer.md) properties. ##### `filled` (Boolean, optional) -- Default: `true` +* Default: `true` Whether to draw a filled polygon (solid fill). Note that only the area between the outer polygon and any holes will be filled. ##### `stroked` (Boolean, optional) -- Default: `false` +* Default: `false` Whether to draw an outline around the polygon (solid fill). Note that both the outer polygon as well the outlines of any holes will be drawn. ##### `extruded` (Boolean, optional) -- Default: `false` +* Default: `false` Whether to extrude the polygons (based on the elevations provided by the `getElevation` accessor. If set to false, all polygons will be flat, this @@ -85,7 +85,7 @@ generates less geometry and is faster than simply returning `0` from `getElevati ##### `wireframe` (Boolean, optional) -- Default: `false` +* Default: `false` Whether to generate a line wireframe of the hexagon. The outline will have "horizontal" lines closing the top and bottom polygons and a vertical line @@ -95,7 +95,7 @@ Requires the `extruded` prop to be true. ##### `elevationScale` (Number, optional) -- Default: `1` +* Default: `1` Elevation multiplier. The final elevation is calculated by `elevationScale * getElevation(d)`. `elevationScale` is a handy property to scale @@ -103,52 +103,50 @@ all elevation without updating the data. ##### `lineWidthScale` (Boolean, optional) -- Default: `1` +* Default: `1` The line width multiplier that multiplied to all outlines of `Polygon` and `MultiPolygon` features if the `stroked` attribute is true. ##### `lineWidthMinPixels` (Number, optional) -- Default: `0` +* Default: `0` The minimum line width in pixels. ##### `lineWidthMaxPixels` (Number, optional) -- Default: Number.MAX_SAFE_INTEGER +* Default: Number.MAX_SAFE_INTEGER The maximum line width in pixels. ##### `lineJointRounded` (Boolean, optional) -- Default: `false` +* Default: `false` Type of joint. If `true`, draw round joints. Otherwise draw miter joints. ##### `lineMiterLimit` (Number, optional) -- Default: `4` +* Default: `4` The maximum extent of a joint in ratio to the stroke width. Only works if `lineJointRounded` is `false`. ##### `lineDashJustified` (Boolean, optional) -- Default: `false` +* Default: `false` Justify dashes together. Only works if `getLineDashArray` is specified. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode -##### `lightSettings` (Object, optional) - -**EXPERIMENTAL** +##### `lightSettings` (Object, optional) **EXPERIMENTAL** This is an object that contains light settings for extruded polygons. Be aware that this prop will likely be changed in a future version of deck.gl. @@ -157,7 +155,7 @@ Be aware that this prop will likely be changed in a future version of deck.gl. ##### `getPolygon` (Function, optional) -- default: `object => object.polygon` +* default: `object => object.polygon` Like any deck.gl layer, the polygon accepts a data prop which is expected to be an iterable container of objects, and an accessor @@ -167,33 +165,33 @@ This accessor returns the polygon corresponding to an object in the `data` strea ##### `getFillColor` (Function, optional) -- Default: `object => object.fillColor || [0, 0, 0, 255]` +* Default: `object => object.fillColor || [0, 0, 0, 255]` The fill color for the polygon ##### `getColor` (Function, optional) -- Default: `object => object.color || object => object.strokeColor || [0, 0, 0, 255]` +* Default: `object => object.color || object => object.strokeColor || [0, 0, 0, 255]` The outline color for the polygon, if drawn in the outline mode ##### `getWidth` (Function, optional) -- Default: `object => object.strokeWidth || 1` +* Default: `object => object.strokeWidth || 1` The width of the outline of the polygon, in meters ##### `getElevation` (Function, optional) -- Default: `object => object.elevation || 1000` +* Default: `object => object.elevation || 1000` ##### `getLineDashArray` (Function, optional) -- Default: `null` +* Default: `null` Method called to get the dash array to draw each outline with. (See Path Layer) -### Remarks +## Remarks * Polygons are always closed, i.e. there is an implicit line segment between the first and last vertices, when those vertices are not equal. @@ -205,5 +203,5 @@ Method called to get the dash array to draw each outline with. (See Path Layer) ## Source -[src/core-layers/polygon-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/polygon-layer) +[modules/core/src/core-layers/polygon-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/polygon-layer) diff --git a/docs/layers/scatterplot-layer.md b/docs/layers/scatterplot-layer.md index 275436448a5..39d892bdc25 100644 --- a/docs/layers/scatterplot-layer.md +++ b/docs/layers/scatterplot-layer.md @@ -40,37 +40,37 @@ Inherits from all [Base Layer](/docs/api-reference/layer.md) properties. ##### `radiusScale` (Number, optional) -- Default: `1` +* Default: `1` A global radius multiplier for all points. ##### `outline` (Boolean, optional) -- Default: `false` +* Default: `false` Only draw outline of points. ##### `strokeWidth` (Number, optional) -- Default: `1` +* Default: `1` Width of the outline, in pixels. Requires `outline` to be `true`. ##### `radiusMinPixels` (Number, optional) -- Default: `0` +* Default: `0` The minimum radius in pixels. ##### `radiusMaxPixels` (Number, optional) -- Default: `Number.MAX_SAFE_INTEGER` +* Default: `Number.MAX_SAFE_INTEGER` The maximum radius in pixels. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode. @@ -78,26 +78,26 @@ Whether the layer should be rendered in high-precision 64-bit mode. ##### `getPosition` (Function, optional) -- Default: `object => object.position` +* Default: `object => object.position` Method called to retrieve the position of each object. ##### `getRadius` (Function, optional) -- Default: `object => object.radius` +* Default: `object => object.radius` Method called to retrieve the radius of each object. ##### `getColor` (Function, optional) -- Default: `object => object.color` +* Default: `object => object.color` Method called to retrieve the rgba color of each object. + * If the alpha parameter is not provided, it will be set to `255`. -* If the method does not return a value for the given object, fallback to -`[0, 0, 0, 255]`. +* If the method does not return a value for the given object, fallback to `[0, 0, 0, 255]`. ## Source -[src/core-layers/scatterplot-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/scatterplot-layer) +[modules/core/src/core-layers/scatterplot-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/scatterplot-layer) diff --git a/docs/layers/screen-grid-layer.md b/docs/layers/screen-grid-layer.md index 1369de04815..4f3f490d782 100644 --- a/docs/layers/screen-grid-layer.md +++ b/docs/layers/screen-grid-layer.md @@ -41,25 +41,25 @@ Inherits from all [Base Layer](/docs/api-reference/layer.md) properties. ##### `cellSizePixels` (Number, optional) -- Default: `100` +* Default: `100` Unit width/height of the bins. ##### `minColor` (Number[4], optional) -- Default: `[0, 0, 0, 255]` +* Default: `[0, 0, 0, 255]` Expressed as an rgba array, minimal color that could be rendered by a tile. This prop is deprecated in version 5.2.0, use `colorRange` and `colorDomain` instead. ##### `maxColor` (Number[4], optional) -- Default: `[0, 255, 0, 255]` +* Default: `[0, 255, 0, 255]` Expressed as an rgba array, maximal color that could be rendered by a tile. This prop is deprecated in version 5.2.0, use `colorRange` and `colorDomain` instead. ##### `colorDomain` (Array, optional) **EXPERIMENTAL** -- Default: `[1, max(weight)]` +* Default: `[1, max(weight)]` Color scale input domain. The color scale maps continues numeric domain into discrete color range. If not provided, the layer will set `colorDomain` to [1, max-of-all-cell-weights], You can control how the color of cells mapped @@ -67,7 +67,7 @@ to value of its weight by passing in an arbitrary color domain. This property is ##### `colorRange` (Array, optional) **EXPERIMENTAL** -- Default: +* Default: Specified as an array of colors formatted as `[[255, 255, 255, 255]]`. Default is [colorbrewer](http://colorbrewer2.org/#type=sequential&scheme=YlOrRd&n=6) `6-class YlOrRd`. @@ -79,16 +79,16 @@ NOTE: `minColor` and `maxColor` take precedence over `colorDomain` and `colorRan ##### `getPosition` (Function, optional) -- Default: `object => object.position` +* Default: `object => object.position` Method called to retrieve the position of each object. ##### `getWeight` (Function, optional) -- Default: `object => 1` +* Default: `object => 1` Method called to retrieve the weight of each object. ## Source -[src/core-layers/screen-grid-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/screen-grid-layer) +[modules/core/src/core-layers/screen-grid-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/screen-grid-layer) diff --git a/docs/layers/solid-polygon-layer.md b/docs/layers/solid-polygon-layer.md index 0e53bf864ce..86042ea82ca 100644 --- a/docs/layers/solid-polygon-layer.md +++ b/docs/layers/solid-polygon-layer.md @@ -36,14 +36,14 @@ Inherits from all [Base Layer](/docs/api-reference/layer.md) properties. ##### `filled` (Boolean, optional) -- Default: `true` +* Default: `true` Whether to fill the polygons (based on the color provided by the `getFillColor` accessor. ##### `extruded` (Boolean, optional) -- Default: `false` +* Default: `false` Whether to extrude the polygons (based on the elevations provided by the `getElevation` accessor. If set to false, all polygons will be flat, this @@ -51,7 +51,7 @@ generates less geometry and is faster than simply returning `0` from `getElevati ##### `wireframe` (Boolean, optional) -- Default: `false` +* Default: `false` Whether to generate a line wireframe of the hexagon. The outline will have "horizontal" lines closing the top and bottom polygons and a vertical line @@ -59,7 +59,7 @@ Whether to generate a line wireframe of the hexagon. The outline will have ##### `elevationScale` (Number, optional) -- Default: `1` +* Default: `1` Elevation multiplier. The final elevation is calculated by `elevationScale * getElevation(d)`. `elevationScale` is a handy property to scale @@ -67,7 +67,7 @@ all elevation without updating the data. ##### `fp64` (Boolean, optional) -- Default: `false` +* Default: `false` Whether the layer should be rendered in high-precision 64-bit mode. @@ -77,9 +77,7 @@ Whether the layer should be rendered in high-precision 64-bit mode. * Wireframe and solid extrusions are exclusive, you'll need to create two layers with the same data if you want a combined rendering effect. -##### `lightSettings` (Object, optional - -**EXPERIMENTAL** +##### `lightSettings` (Object, optional) **EXPERIMENTAL** This is an object that contains light settings for extruded polygons. Be aware that this prop will likely be changed in a future version of deck.gl. @@ -88,7 +86,7 @@ Be aware that this prop will likely be changed in a future version of deck.gl. ##### `getPolygon` (Function, optional) -- Default: `object => object.polygon || object.geometry.coordinates` +* Default: `object => object.polygon || object.geometry.coordinates` Like any deck.gl layer, the polygon accepts a data prop which is expected to be an iterable container of objects, and an accessor @@ -98,19 +96,19 @@ This accessor returns the polygon corresponding to an object in the `data` strea ##### `getFillColor` (Function, optional) -- Default: `object => object.fillColor || object.properties.color || [0, 0, 0, 255]` +* Default: `object => object.fillColor || object.properties.color || [0, 0, 0, 255]` The fill color for the polygon ##### `getLineColor` (Function, optional) -- Default: `object => object.lineColor || object.properties.color || [0, 0, 0, 255]` +* Default: `object => object.lineColor || object.properties.color || [0, 0, 0, 255]` The line color for the polygon ##### `getElevation` (Function, optional) -- Default: `object => object.elevation` +* Default: `object => object.elevation` Method called to retrieve the elevation of each object's polygon. @@ -128,5 +126,5 @@ otherwise will be in unit coordinates. ## Source -[src/core-layers/primitive-polygon-layer](https://github.com/uber/deck.gl/tree/5.1-release/src/core-layers/primitive-polygon-layer) +[modules/core/src/core-layers/solid-polygon-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/solid-polygon-layer) diff --git a/docs/layers/text-layer.md b/docs/layers/text-layer.md index e0c28bedda1..61fdcc78dfd 100644 --- a/docs/layers/text-layer.md +++ b/docs/layers/text-layer.md @@ -1,11 +1,7 @@ # Text Layer -### About - The text layer renders text labels on the map using texture mapping. This Layer is extended based on [Icon Layer](/docs/layers/icon-layer.md) and wrapped using [Composite Layer](/docs/api-reference/composite-layer.md). -### Example - ```js import DeckGL from 'deck.gl'; import TextLayer from './text-layer'; @@ -30,6 +26,8 @@ const App = ({data, viewport}) => { }; ``` +## Properties + ### Data Accessors ##### `getText` (Function, optional) @@ -106,6 +104,9 @@ Method called to specify the alignment baseline. Available options include `'top Method called to specify screen space offset relative to the `coordinates` in pixel unit. This function is rarely used in common cases. -### Font Style and Character Set Support -Currently, the layer uses a monospaced font style called [Lucida Console](https://en.wikipedia.org/wiki/Lucida#Lucida_Console) and only supports the ASCII character set. If the text label happens to contain unicode characters, the layer replaces them with a single space and renders the text label without throwing an error. +## Source + +[modules/core/src/core-layers/text-layer](https://github.com/uber/deck.gl/tree/5.2-release/modules/core/src/core-layers/text-layer) + + diff --git a/docs/roadmap.md b/docs/roadmap.md index 970e473cee2..75d1d54a4d4 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -3,6 +3,7 @@ Interested in what is coming down the road? We are trying to make the deck.gl roadmap as public as possible. We are currently using the following ways to share information about the direction of deck.gl. + * **Roadmap Document** - (this document) A high-level summary of our current direction for future releases. * **Blog** - We use the [vis.gl blog](https://medium.com/@vis.gl) blog to share information about what we are doing. * **RFCs** - A wealth of technical detail around planned features is available in our RFCs (Requests For Comments). RFCs are technical writeups that describe a proposed feature. RFCs are available [here](https://github.com/uber/deck.gl/tree/master/dev-docs/RFCs). @@ -16,6 +17,7 @@ We are currently using the following ways to share information about the directi The [@deck.gl/experimental-layers](https://www.npmjs.com/package/@deck.gl/experimental-layers) is available as of deck.gl v5.2 and contains early versions of future layers. There are a number of interesting layers in this module, however there are caveats: + * We do not provide website documentation for these layers, so if you want to use these layers you may need to refer directly to the deck.gl source code. * While we make reasonable attempts to not break things, we do not guarantee that they will be stable between releases. * To prevent surprises, you may want to pin the version of the `@deck.gl/experimental-layers` module in your `package.json`. @@ -50,6 +52,7 @@ These are some of things we tackled in our most recent release TBA - This is a planned feature for a future release **Restrict Event Handling to match Viewport Size** - Controllers need to be able to be restricted to a certain area (in terms of event handling). Some controllers are completely general (just general drag up/down): + * When working with a map controller, especially panning and zooming, the point under the mouse represents a grab point or a reference for the operation and mapping event coordinates correctly is imporant for the experience. * Controllers might not be designed to receive coordinates from outside their viewports. * Basically, if the map backing one WebMercator viewport doesn't fill the entire canvas, and the application wants to use a MapControls diff --git a/docs/shader-modules/lighting.md b/docs/shader-modules/lighting.md index d01e40fe270..89ab1ba916d 100644 --- a/docs/shader-modules/lighting.md +++ b/docs/shader-modules/lighting.md @@ -4,7 +4,7 @@ The `lighting` module provides a way to light a vertex using world positions and ## Usage -``` +```glsl // geometry attribute vec3 positions; attribute vec3 normals; diff --git a/docs/shader-modules/project.md b/docs/shader-modules/project.md index ef02b7881a6..f2aa948b0c4 100644 --- a/docs/shader-modules/project.md +++ b/docs/shader-modules/project.md @@ -28,10 +28,12 @@ void main(void) { The JavaScript uniforms are extracted mainly from the viewport with a few additional parameters (which deck.gl supplies from `LayerManager` state or `Layer` props of course). Provided by `LayerManager`: + * `viewport` * `devicePixelRatio` Provided by `Layer` props: + * `coordinateSystem` * `coordinateOrigin` * `modelMatrix` @@ -99,8 +101,7 @@ Converts the given number of pixels to a clipspace offset that can be added to a `vec4 project_pixels_to_clipspace(vec2 pixels)` -* `pixels` (`vec2`) - adjustment in logical pixels -Returns values in clip space offsets that can be added directly to `gl_Position` +* `pixels` (`vec2`) - adjustment in logical pixels. Returns values in clip space offsets that can be added directly to `gl_Position` ## Remarks diff --git a/docs/shader-modules/project32.md b/docs/shader-modules/project32.md index 8b4b92fc4ea..dbd74c52b84 100644 --- a/docs/shader-modules/project32.md +++ b/docs/shader-modules/project32.md @@ -13,10 +13,11 @@ The `project32` shader module is an extension of the `project` shader module tha `vec4 project_position_to_clipspace(vec3 position, vec2 position64xyLow, vec3 offset, out vec4 worldPosition)` Parameters: -- `position` - vertex position in the layer's coordinate system. -- `position64xyLow` - always ignored -- `offset` - meter offset from the coordinate -- `worldPosition` - projected position in the world space + +* `position` - vertex position in the layer's coordinate system. +* `position64xyLow` - always ignored +* `offset` - meter offset from the coordinate +* `worldPosition` - projected position in the world space Returns: Projected position in the clipspace. diff --git a/docs/shader-modules/project64.md b/docs/shader-modules/project64.md index df87610470d..bbc5fb38f5c 100644 --- a/docs/shader-modules/project64.md +++ b/docs/shader-modules/project64.md @@ -29,10 +29,11 @@ Uniform names are not considered part of the official API of shader modules and `vec4 project_position_to_clipspace(vec3 position, vec2 position64xyLow, vec3 offset, out vec4 worldPosition)` Parameters: -- `position` - vertex position in the layer's coordinate system. -- `position64xyLow` - low part of the vertex position's xy -- `offset` - meter offset from the coordinate -- `worldPosition` - projected position in the world space + +* `position` - vertex position in the layer's coordinate system. +* `position64xyLow` - low part of the vertex position's xy +* `offset` - meter offset from the coordinate +* `worldPosition` - projected position in the world space Returns: Projected position in the clipspace. diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md index ab6b1db5e49..1e5a3addf1c 100644 --- a/docs/upgrade-guide.md +++ b/docs/upgrade-guide.md @@ -14,6 +14,7 @@ ### Experimental Features Some experimental exports have been removed: + * The experimental React controller components (`MapController` and `OrbitController`) have been removed. These are now replaced with JavaScript classes that can be used with the `Deck.controller` / `DeckGL.controller` property. @@ -98,11 +99,13 @@ Be aware that deck.gl 4.1 bumps the luma.gl peer dependency from 3.0 to 4.0. The ### Layer Life Cycle Optimization * **shouldUpdateState** - deck.gl v4.1 contains additional optimizations of the layer lifecycle and layer diffing algorithms. Most of these changes are completely under the hood but one visible change is that the default implementation of `Layer.shouldUpdate` no longer returns true if only the viewport has changed. This means that layers that need to update state in response to changes in screen space (viewport) will need to redefine `shouldUpdate`: + ```js shouldUpdateState({changeFlags}) { return changeFlags.somethingChanged; // default is now changeFlags.propsOrDataChanged; } ``` + Note that this change has already been done in all the provided deck.gl layers that are screen space based, including the `ScreenGridLayer` and the `HexagonLayer`. ### luma.gl `Model` class API change @@ -123,7 +126,7 @@ new Model({gl, ...opts}); Custom layers are **no longer expected** to call `assembleShaders` directly. Instead, the new `Model` class from luma.gl v4 will take shaders and the modules they are using as parameters and assemble shaders automatically. -``` +```js // luma.gl v4 const model = new Model(gl, { vs: VERTEX_SHADER, @@ -166,12 +169,14 @@ These set of layers were deprecated in deck.gl v4, and are now removed in v5. Yo ### Changed Import: The `DeckGL` React component A small but breaking change that will affect all applications is that the 'deck.gl/react' import is no longer available. As of v4.0, the app is required to import deck.gl as follows: -``` + +```js // V4 import DeckGL from 'deck.gl'; // V3 import DeckGL from 'deck.gl/react'; ``` + While it would have been preferable to avoid this change, a significant modernization of the deck.gl build process and preparations for "tree-shaking" support combined to make it impractical to keep supporting the old import style. diff --git a/docs/whats-new.md b/docs/whats-new.md index 536ee2e32d5..8252597a69e 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -3,7 +3,7 @@ This page contains highlights of each deck.gl release. Also check our [vis.gl blog](https://medium.com/@vis.gl) for news about new releases and features in deck.gl. -# deck.gl v6.0 +## deck.gl v6.0 Release date: TBD, target late Q2, 2018 @@ -15,7 +15,7 @@ deck.gl layers can now specify additional type information about properties. Whe -# deck.gl v5.2 +## deck.gl v5.2 Release date: TBD, target April, 2018 @@ -39,84 +39,86 @@ Release date: TBD, target April, 2018 -## Use deck.gl without React +### Use deck.gl without React deck.gl can now be used in non-React applications. A new top-level JavaScript class [`Deck`](/docs/api-reference/deck.md) is provided as an alternative to the traditional top-level `DeckGL` React component. This allows deck.gl to be used in any JavaScript application or framework. The new API is officially supported, however since it is not yet extensively battle-tested in applications there may be some rough corners, so to help developers set expectations we are labeling this as a "pre release" recommended for "early adopters". -## Scripting Support +### Scripting Support deck.gl now publishes a bundle that can be imported using a simple `