Clarify whats experimental in 4.2 (visgl#1211)

asyrafduyshart · Dec 4, 2017 · 79e1747 · 79e1747
1 parent 67e28f6
commit 79e1747
Show file tree

Hide file tree

Showing 15 changed files with 179 additions and 102 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -23,6 +23,11 @@ For Earlier Beta Releases see below
 
 ### deck.gl v4.2 Beta Releases
 
+#### [4.2.0-...] -
+- DOCS: updates to clarify what is experimental in 4.2, in "What's New" and "API Reference".
+- DOCS: New Roadmap doc, linking to RFCs.
+- DOCS: List experimental 4.2 features in Roadmap doc.
+
 #### [4.2.0-alpha.29] - Dec 1
 - Picking null color fix
 

diff --git a/docs/README.md b/docs/README.md
@@ -32,12 +32,13 @@ To make this simple concept work, deck.gl handles a number of challenges:
 
 ## Ecosystem
 
-deck.gl has been developed in parallel with a number of companion modules:
+deck.gl is one of the main frameworks in the [vis.gl](https://vis.gl) framework suite.
+
+deck.gl has been developed in parallel with a number of companion modules, e.g.:
 
 * [luma.gl](https://uber.github.io/luma.gl/#/) - A general purpose WebGL library designed to be interoperable both with the raw WebGL API and (as far as possible) with other WebGL libraries. In particular, luma.gl does not claim ownership of the WebGL context, and can work with any supplied context, including contexts created by the application or other WebGL libraries.
 * [react-map-gl](https://uber.github.io/react-map-gl/#/) - A React wrapper around Mapbox GL which works seamlessly with deck.gl.
 
-In addition, in the future we plan to publish additional deck.gl layers and layer packages as separate modules.
 
 ## Learning deck.gl
 

diff --git a/docs/api-reference/attribute-manager.md b/docs/api-reference/attribute-manager.md
@@ -1,6 +1,6 @@
 # AttributeManager Class (Advanced)
 
-Note: The `AttributeManager` is used internally by deck.gl layers. Unless you are writing custom deck.gl layers, or you are working with some very narrow advanced performance optimization use cases, you do not need to use this class.
+> The `AttributeManager` is used internally by deck.gl layers. Unless you are writing custom deck.gl layers, or you are working with some very narrow advanced performance optimization use cases, you do not need to use this class.
 
 The `AttributeManager` class provides automated attribute allocations and updates.
 

diff --git a/docs/api-reference/first-person-state.md b/docs/api-reference/first-person-state.md
@@ -1,5 +1,4 @@
-# FirstPersonState Class
-
+# FirstPersonState Class (Experimental)
 
 ## Constructor
 

diff --git a/docs/api-reference/first-person-viewport.md b/docs/api-reference/first-person-viewport.md
@@ -1,4 +1,4 @@
-# FirstPersonViewport Class
+# FirstPersonViewport Class (Experimental)
 
 The [`FirstPersonViewport`] class is a subclass of [Viewport](/docs/api-reference/viewport.md) that creates a "camera" at the exact position, direction and orientation specified by the application. This is in contrast with e.g. [ThirdPersonViewport](/docs/api-reference/viewport.md) where the camera will be offset from and look "down" on the specified position.
 

diff --git a/docs/api-reference/layer-manager.md b/docs/api-reference/layer-manager.md
@@ -1,6 +1,6 @@
 # LayerManager Class (Advanced)
 
-Note: The `LayerManager` class is an internal class that is exposed primarily to enable deck.gl to be used without React. If you are using the [`DeckGL`](/docs/api-reference/deckgl.md) React Component, a layer manager is created under the hood to handle layer management, and you do not need to use this class.
+> The `LayerManager` class is an internal class that is exposed primarily to enable deck.gl to be used without React. If you are using the [`DeckGL`](/docs/api-reference/deckgl.md) React Component, a layer manager is created under the hood to handle layer management, and you do not need to use this class.
 
 The `LayerManager` class handles updates, drawing and picking for a set of layers.
 

diff --git a/docs/api-reference/map-state.md b/docs/api-reference/map-state.md
@@ -1 +1 @@
-# MapState Class
+# MapState Class (Experimental)
diff --git a/docs/api-reference/orbit-state.md b/docs/api-reference/orbit-state.md
@@ -1 +1 @@
-# OrbitState Class
+# OrbitState Class (Experimental)
diff --git a/docs/api-reference/react/deckgl.md b/docs/api-reference/react/deckgl.md
@@ -2,8 +2,6 @@
 
 `DeckGL` is a React component that takes deck.gl layer instances and viewport parameters, and renders those layers as a transparent overlay.
 
-`DeckGL` can accept child components. Child components can be automatically positioned underneath the deck.gl `viewports`. Such child components are often maps (e.g. represented by instances of the `StaticMap` component from [react-map-gl]()), but can be any React components.
-
 ## Usage
 
 // Basic standalone use
@@ -17,6 +15,10 @@ const App = (viewport, data) => (
 );
 ```
 
+## Experimental Usage
+
+`DeckGL` can accept child components. Child components can be automatically positioned underneath the deck.gl `viewports`. Such child components are often maps (e.g. represented by instances of the `StaticMap` component from [react-map-gl]()), but can be any React components.
+
 // Multiple viewports and a base map
 ```js
   const viewports = [
@@ -60,36 +62,6 @@ The array of deck.gl layers to be rendered. This array is expected to be an arra
 
 Optionally takes a function `({layer, viewport, isPicking}) => Boolean` that is called before a layer is rendered. Gives the application an opportunity to filter out layers from the layer list during either rendering or picking. Filtering can be done per viewport or per layer or both. This enables techniques like adding helper layers that work as masks during picking but do not show up during rendering. All the lifecycle methods are still triggered even a if a layer is filtered out using this prop.
 
-##### `viewports`
-
-A singe viewport, or an array of `Viewport`s or "Viewport Descriptors".
-
-* (`Viewport`|`Viewports[]`, optional) - A singe viewport, or an array of `Viewports` or "Viewport Descriptors".
-
-Default: If not supplied, deck.gl will try to create a `WebMercatorViewport` from other props (longitude, latitude, ...).
-
-This property should contain one or more ([`Viewport`](/docs/api-reference/viewport.md), optional)instances which represents your "camera" (essentially view and projection matrices, together with viewport width and height). By changing the `viewport` you change the view of your layers, e.g. as a result of mouse events or through programmatic animations.
-
-deck.gl will render all the viewports in order.
-
-If `viewports` is not supplied, deck.gl will look for web mercator projection parameters (latitude, longitude, zoom, bearing and pitch) and create a `WebMercatorViewport` (which is a subclass of `Viewport`).
-
-##### `children`
-
-To make it easy to use React components in combination with deck.gl viewports (e.g. to place a base map under a viewport, or add a label on top of a viewport), deck.gl can make such components automatically adjust as that viewport is added, removed or resized.
-
-`DeckGL` classifies any top-level children (`props.children`) that have a `viewportId` property as "viewport base components". It will perform special processing on them as follows:
-* It resizes and repositions any `viewportId` children to precisely match the extends of the deck.gl viewport with the corresponding id.
-* It automatically hides any `viewportId` children whose id is not matched by any current deck.gl viewport.
-* It injects viewport properties (`longitude`, `latitude` etc).
-* Also injects the `visible: viewport.isMapSynched()` prop to hide base maps that cannot display per the current viewport 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 `viewportId` property are rendered as is.
-
 
 #### View State Properties
 
@@ -232,11 +204,42 @@ Remarks:
 NOTE: replaces deprecated method `queryVisibleObjects`.
 
 
-### Deprecated Properties
+### Experimental Properties
+
+These properties are considered experimental and can change in the next minor version of deck.gl. They are included as previews of functionality that is being developed.
+
+##### `viewports`
+
+A singe viewport, or an array of `Viewport`s or "Viewport Descriptors".
+
+* (`Viewport`|`Viewports[]`, optional) - A singe viewport, or an array of `Viewports` or "Viewport Descriptors".
+
+Default: If not supplied, deck.gl will try to create a `WebMercatorViewport` from other props (longitude, latitude, ...).
+
+This property should contain one or more ([`Viewport`](/docs/api-reference/viewport.md), optional)instances which represents your "camera" (essentially view and projection matrices, together with viewport width and height). By changing the `viewport` you change the view of your layers, e.g. as a result of mouse events or through programmatic animations.
+
+deck.gl will render all the viewports in order.
+
+If `viewports` is not supplied, deck.gl will look for web mercator projection parameters (latitude, longitude, zoom, bearing and pitch) and create a `WebMercatorViewport` (which is a subclass of `Viewport`).
 
-##### `viewport`
+##### `children`
+
+The following semantics of the children property are considered experimental.
+
+To make it easy to use React components in combination with deck.gl viewports (e.g. to place a base map under a viewport, or add a label on top of a viewport), deck.gl can make such components automatically adjust as that viewport is added, removed or resized.
+
+`DeckGL` classifies any top-level children (`props.children`) that have a `viewportId` property as "viewport base components". It will perform special processing on them as follows:
+* It resizes and repositions any `viewportId` children to precisely match the extends of the deck.gl viewport with the corresponding id.
+* It automatically hides any `viewportId` children whose id is not matched by any current deck.gl viewport.
+* It injects viewport properties (`longitude`, `latitude` etc).
+* Also injects the `visible: viewport.isMapSynched()` prop to hide base maps that cannot display per the current viewport 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 `viewportId` property are rendered as is.
 
-Deprecated. Use `viewports` property instead, that prop can accept a single `Viewport` or an array with a single `Viewport`.
 
 ## Source
 [src/react/deckgl.js](https://github.com/uber/deck.gl/blob/4.1-release/src/react/deckgl.js)
diff --git a/docs/api-reference/third-person-viewport.md b/docs/api-reference/third-person-viewport.md
@@ -1,4 +1,4 @@
-# ThirdPersonViewport Class
+# ThirdPersonViewport Class (Experimental)
 
 The [`ThirdPersonViewport`] class is a subclass of [Viewport](/docs/api-reference/viewport.md). This viewport creates a "camera" that looks at an exact position, position using the direction, distance and orientation specified by the application.
 

diff --git a/docs/api-reference/web-mercator-viewport.md b/docs/api-reference/web-mercator-viewport.md
@@ -1,4 +1,3 @@
-
 # WebMercatorViewport Class
 
 The `WebMercatorViewport` class is a subclass of [ThirdPersonViewport](/docs/api-reference/third-person-viewport.md) that enables 3D rendering to seamlessly overlay on top of map components that take web mercator style map coordinates (`latitude`, `lon`, `zoom`, `pitch`, `bearing` etc).

diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -0,0 +1,62 @@
+# Roadmap
+
+Interested in what is coming down the road? We are trying to make the deck.gl roadmap as public as possible.
+
+We currently are using four ways to share information about the direction of deck.gl.
+* **Roadmap Document** - (this document) Contains a high-level summary of our current thoughts and ambitions.
+* **RFCs** - We are now publishing our RFCs (Requests For Comments) for features in upcoming releases. These are available in the [developer documents](https://github.com/uber/deck.gl/tree/master/dev-docs/RFCs) section of the github repo.
+* **Experimental exports** - We are making unfinished features available as experimental exports. This gives users a clear indication about what is coming and even allow early adopters a chance to play with and provide comments on these features.
+* **Blog** - We will of course continue to use the vis.gl blog to share information about what we are doing.
+
+Naturally, the github issues also contains relevant information, but in a less structured form.
+
+
+## deck.gl v.Next
+
+* **Pure JavaScript support** - deck.gl is today a React library, but in 4.2 the internal code is essentially 100% independent of React. We want to define an official JavaScript API and publish the React "wrappers" as an optional add-on module. (Please don't worry if you are a React user, deck.gl will continue to be "React-first", designed from the ground up with the "reactive programming paradigm" in mind).
+* **Multi-viewport** support - Extensive work has been done in 4.2 (available in the `experimental` namespace), we expect to finalize and make much of this functionality official in next release.
+* **Visual Effects** - Shadows, blur, postprocessing etc. This continues to be strong goal that unfortunately has been pushed forward.
+* **Transitions and Animations** - 4.2 introduces viewport transitions. Expect to see similar support for layer properties and attributes.
+* **Code Size** - deck.gl has gone through rapid development and we need to overhaul the code and build processes to reduce the size.
+
+In addition, in the future we plan to publish separate modules with deck.gl layers and core functionality.
+
+## Longer Term
+
+Other themes we want to develop are:
+* **Aggregation** - Improve and generalize automatic data aggregation (the current HexagonLayer and GridLayer are examples of what to expect).
+* **Better Infovis Support** - Better support for non-geospatial visualizations. (Don't worry if you are a geospatial user, deck.gl will remain a "geospatial-first" library since that is the more difficult use case.)
+* **Better GPGPU/WebGL2 Support** - Many stones are still left unturned here. Expect better performance, and new features (such as animations of entire attributes), especially in WebGL2 capable browsers.
+
+
+## Short Term: Experimental Features in 4.2
+
+A lot of multi-viewport support was added during deck.gl 4.2 development. The APIs are still not considered stable so the related classes are exported as part of the "experimental" namespace, and in most cases.
+
+### Multi-Viewport Support
+
+deck.gl now allows you to divide your screen into multiple viewports and render your layers from different perspectives, using the experimental `_viewports` property. It is e.g. possible to render a top-down map view next to a first person view for dramatic new perspectives on your data. E.g. an app can allow your users to "walk around" in the city onto which its data is overlaid.
+
+### WebVR Support and Example
+
+Multi viewport support can be used to integrate with the WebVR API and create dual WebVR compatible viewports that render a first person view of your data for left and right eye respectively which will display as stereoscopic 3D in supporting hardware.
+
+### Automatic Positioning of React Children under Viewports
+
+In addition, a new `viewportId` React property can be added to `DeckGL`'s children. This will synchronize the position of the react component with the corresponding deck.gl viewport, which makes it trivial to precisely position e.g. multiple "base maps" and other background or foreground HTML components in multi-viewport layouts. The `viewportId` prop also automatically hides the react children when a viewport with the corresponding id is not present or when viewport parameters can not be supported by the underlying map component.
+
+### Orbit Controller and Orbit Viewport Support
+
+TBA
+
+### Controller Hierarchy
+
+TBA
+
+### All Viewports Now Geospatially Enabled
+
+All `Viewport` classes are now geospatially enabled: they now take an optional `longitude`/`latitude` reference point. In this mode, `position`s will be treated as meter offsets from that reference point per `COORDINATE_SYSTEM.METER_OFFSET` conventions.
+
+This means that you can now use a FirstPersonViewport (the successor to the `PerspectiveViewport` with layers encoded in `COORDINATE_SYSTEM.LNG_LAT` and `COORDINATE_SYSTEM.METER_OFFSETS`) and place a camera anywhere in the scene (in contrast to the `WebMercatorViewport` which only allows you to look "down" on a position on the map).
+
+Viewports even accept a `modelMatrix` to allow viewport/camera positions to be specified in exactly the same coordinates as `METER_OFFSET` layers, making it possible to place a camera at the exact location any of your existing data points without having to think or do any math.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		# OrbitState Class
		# OrbitState Class (Experimental)
Original file line number	Diff line number	Diff line change
		@@ -1,4 +1,3 @@

		# WebMercatorViewport Class

		The `WebMercatorViewport` class is a subclass of [ThirdPersonViewport](/docs/api-reference/third-person-viewport.md) that enables 3D rendering to seamlessly overlay on top of map components that take web mercator style map coordinates (`latitude`, `lon`, `zoom`, `pitch`, `bearing` etc).
Expand Down