Add ClipExtension docs

visgl · May 7, 2021 · 54004b1 · 54004b1
1 parent 90b4042
commit 54004b1
Show file tree

Hide file tree

Showing 4 changed files with 74 additions and 1 deletion.
diff --git a/docs/api-reference/extensions/clip-extension.md b/docs/api-reference/extensions/clip-extension.md
@@ -0,0 +1,71 @@
+
+# ClipExtension
+
+The `ClipExtension` adds support for clipping rendered layers by rectangular bounds.
+
+```js
+import {GeoJsonLayer} from '@deck.gl/layers';
+import {ClipExtension} from '@deck.gl/extensions';
+
+const layer = new GeoJsonLayer({
+  // Natural Earth countries dataset includes Antarctica, which renders stretched further to south in MapView with viewState normalization turned off
+  data: 'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_50m_admin_0_countries.geojson',
+  // clip rendered layer by Mercator bounds
+  extensions: [new ClipExtension()],
+  clipBounds: [-180, -85.051129, 180, 85.051129],
+});
+```
+
+## Installation
+
+To install the dependencies from NPM:
+
+```bash
+npm install deck.gl
+# or
+npm install @deck.gl/core @deck.gl/extensions
+```
+
+```js
+import {ClipExtension} from '@deck.gl/extensions';
+new ClipExtension();
+```
+
+To use pre-bundled scripts:
+
+```html
+<script src="https://unpkg.com/deck.gl@^8.0.0/dist.min.js"></script>
+<!-- or -->
+<script src="https://unpkg.com/@deck.gl/core@^8.0.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/extensions@^8.0.0/dist.min.js"></script>
+```
+
+```js
+new deck.ClipExtension();
+```
+
+## Constructor
+
+```js
+new ClipExtension();
+```
+
+## Layer Properties
+
+When added to a layer via the `extensions` prop, the `ClipExtension` adds the following properties to the layer:
+##### `clipBounds` (Array)
+
+Rectangular bounds to be used for clipping the rendered region.
+
+Supported format: `[left, bottom, right, top]`
+
+##### `clipByInstance` (Boolean, optional)
+
+`clipByInstance` controls whether an object is clipped by its anchor (e.g. icon, point) or by its geometry (e.g. path, polygon). If not specified, it is deduced from whether there is an attribute called `instancePositions`. This behavior can be overridden if:
+
+- the anchor attribute goes by some other name
+- to clip an anchored layer by geometry, like the text layer
+
+## Source
+
+[modules/extensions/src/clip](https://github.com/visgl/deck.gl/tree/master/modules/extensions/src/clip)
diff --git a/docs/api-reference/extensions/overview.md b/docs/api-reference/extensions/overview.md
@@ -12,6 +12,7 @@ This module contains the following extensions:
 - [DataFilterExtension](/docs/api-reference/extensions/data-filter-extension.md)
 - [Fp64Extension](/docs/api-reference/extensions/fp64-extension.md)
 - [PathStyleExtension](/docs/api-reference/extensions/path-style-extension.md)
+- [ClipExtension](/docs/api-reference/extensions/clip-extension.md)
 
 For instructions on authoring your own layer extensions, visit [developer guide](/docs/developer-guide/custom-layers/layer-extensions.md).
 

diff --git a/docs/api-reference/geo-layers/mvt-layer.md b/docs/api-reference/geo-layers/mvt-layer.md
@@ -52,7 +52,7 @@ To install the dependencies from NPM:
 ```bash
 npm install deck.gl
 # or
-npm install @deck.gl/core @deck.gl/layers @deck.gl/geo-layers
+npm install @deck.gl/core @deck.gl/layers @deck.gl/extensions @deck.gl/geo-layers
 ```
 
 ```js

diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md
@@ -13,6 +13,7 @@ The module entry point is now only lightly transpiled for the most commonly used
 - `PathLayer`'s `rounded` prop is deprecated, replaced by two separate flags `jointRounded` and `capRounded`.
 - `GeoJsonLayer`'s `lineJointRounded` prop now only controls line joints. To use rounded line caps, set `lineCapRounded` to `true`.
 - Dashed lines via `PathStyleExtension` now draw rounded dash caps if `capRounded` is `true`.
+- `@deck.gl/geo-layers` now requires `@deck.gl/extensions`, due to `ClipExtension` dependency.
 
 ### onError Callback
-Original file line number
+Diff line change
@@ Expand Up / @@ -52,7 +52,7 @@ To install the dependencies from NPM: @@
     ```bash
     npm install deck.gl
     # or
-    npm install @deck.gl/core @deck.gl/layers @deck.gl/geo-layers
+    npm install @deck.gl/core @deck.gl/layers @deck.gl/extensions @deck.gl/geo-layers
     ```
     ```js
@@ Expand Down @@