docs(layers): Initial TileSourceLayer docs

docs/modules/layers/api-reference/tile-source-layer.md

@@ -1 +1,294 @@
 # TileSourceLayer
+
+<p class="badges">
+  <img src="https://img.shields.io/badge/from-v9.0-green.svg?style=flat-square" alt="from v9.0" />
+</p>
+
+import {TileSourceLayerDemo} from '@site/src/doc-demos/geo-layers';
+
+<TileSourceLayerDemo />
+
+> This class is experimental, which means it does not provide the compatibility and stability that one would typically expect from other layers, detailed in the [limitations](#limitations) section. Use with caution and report any issues that you find on GitHub.
+
+
+The `TileSourceLayer` is a composite layer that connects with an image service that can render map images optimized for the current view. Instead of loading a detailed map image covering the entire globe, an image is rendered.
+
+In contrast to the [TileLayer](./tile-layer.md) which loads many small image tiles, the `TileSourceLayer` loads a single image that covers the entire viewport in one single request, and updates the image by performing additional requests when the viewport changes.
+
+To use this layer, an *image source* must be specified. Image sources are specified by supplying a URL to the `TileSourceLayer` `data` property. See the section on image sources below for mor information.
+
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs groupId="language">
+  <TabItem value="js" label="JavaScript">
+
+```js
+import {Deck} from '@deck.gl/core';
+import {TileSourceLayer} from '@deck.gl/geo-layers';
+import {WMSSource} from '@loaders.gl/wms';
+
+const wmsSource = new WMSSource({
+  data: 'https://ows.terrestris.de/osm/service',
+  serviceType: 'wms',
+  layers: ['OSM-WMS']
+});
+
+new Deck({
+  layers: [
+    new TileSourceLayer({source: wmsSource})
+  ],
+  initialViewState: {
+    longitude: -122.4,
+    latitude: 37.74,
+    zoom: 9
+  },
+  controller: true,
+});
+```
+
+  </TabItem>
+  <TabItem value="ts" label="TypeScript">
+
+```ts
+import {Deck} from '@deck.gl/core';
+import {TileSourceLayer} from '@deck.gl/geo-layers';
+
+const layer = new TileSourceLayer({
+  data: 'https://ows.terrestris.de/osm/service',
+  serviceType: 'wms',
+  layers: ['OSM-WMS']
+});
+
+new Deck({
+  initialViewState: {
+    longitude: -122.4,
+    latitude: 37.74,
+    zoom: 9
+  },
+  controller: true,
+  layers: [layer]
+});
+```
+
+  </TabItem>
+  <TabItem value="react" label="React">
+
+```tsx
+import React from 'react';
+import DeckGL from '@deck.gl/react';
+import {TileSourceLayer} from '@deck.gl/geo-layers';
+
+function App() {
+  const layer = new TileSourceLayer({
+    data: 'https://ows.terrestris.de/osm/service',
+    serviceType: 'wms',
+    layers: ['OSM-WMS']
+  });
+
+  return <DeckGL
+    initialViewState={{
+      longitude: -122.4,
+      latitude: 37.74,
+      zoom: 9
+    }}
+    controller
+    layers={[layer]}
+  />;
+}
+```
+
+  </TabItem>
+</Tabs>
+
+
+## Installation
+
+To install the dependencies from NPM:
+
+```bash
+npm install deck.gl
+# or
+npm install @deck.gl/core @deck.gl/layers @deck.gl/geo-layers
+```
+
+```ts
+import {TileSourceLayer} from '@deck.gl/geo-layers';
+import type {TileSourceLayerProps} from '@deck.gl/geo-layers';
+
+new TileSourceLayer(...props: TileSourceLayerProps[]);
+```
+
+To use pre-bundled scripts:
+
+```html
+<script src="https://unpkg.com/deck.gl@^9.0.0/dist.min.js"></script>
+<!-- or -->
+<script src="https://unpkg.com/@deck.gl/core@^9.0.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl/layers@^9.0.0/dist.min.js"></script>
+<script src="https://unpkg.com/@deck.gl-community/layers@^9.0.0/dist.min.js"></script>
+```
+
+```js
+new deck.TileSourceLayer({});
+```
+
+## Sources
+
+The `TileSourceLayer` accepts a `TileSource` and loads and renders tiles from that TileSource to cover the current viewport.
+
+`loaders.gl` provides a variety of `TileSource` classes for various protocols and tile services. Generally thes sources can be created with a URL from which it can start loading map images. 
+
+
+However, it is also possible to connect the TileSourceLayer to any other REST based service that can render map images from a set of web mercator bounds and a given pixel resolution (perhaps an ArcGIS image server) by specify a custom URL template.
+
+### Roadmap
+
+A `WMSSource` knows how to build URLs for geospatial image services such as WMS. 
+
+Note that additional features, such as metadata loading, is only supported for known  services.
+
+### Layers
+
+Image servers such as WMS can render different layers. Typically as list of layers **must** be specified, otherwise requests for map images will fail. For WMS services, this is controlled by [layers](#layers). For other services, layers (if required by that service) can be specified in the template URL, either as a parameter or as a hard-coded part of the template string. 
+
+### Image Service Metadata
+
+Image services like WMS can often provide metadata (aka capabilities) about the service, listing;
+- attribution information, 
+- available layers
+- additional capabilities (pixel/neighborhood queries, legend generation etc). 
+
+The `TileSourceLayer` will automatically attempt to query metadata for known service types (currently WMS). 
+
+Template URLs only cover image requests and there is no support for providing a custom URL for the metadata queries. This needs to be handled by the application for non-WMS services.
+
+### Interactivity
+
+WMS services sometimes provide a mechanism to query a specific pixel. This is supported through the `getFeatureInfoText()` method on the `TileSourceLayer`
+
+## Methods
+
+#### `getFeatureInfoText` {#getfeatureinfotext}
+
+This is a method on the layer that can be called to retrieve additional information from the image service about the map near the specified pixel.
+
+Arguments:
+
+- `x` (number) - The x component of the pixel in the image
+- `y` (number) - The y component of the pixel in the image
+
+Returns
+
+- `Promise<string>` - Resolves to a string containing additional information about the map around the provided pixel
+
+
+## Properties
+
+Inherits all properties from [base `Layer`](../core/layer.md).
+
+### Data Options
+
+#### `data` (string) {#data}
+
+A base URL to a well-known service type, or a full URL template from which the map images should be loaded.
+
+If [serviceType](#servicetype) is set to `'template'`, data is expected to be a URL template. The template may contain the following substrings, which will be replaced with a viewport's actual bounds and size at request time:
+
+- `{east}`
+- `{north}`
+- `{west}`
+- `{south}`
+- `{width}`
+- `{height}`
+- `{layers}` - replaced with a string built from the content of [layers](#layers). The array of layer name strings will be joined by commas (`,`) into a single string.
+
+
+#### `serviceType` (string, optional) {#servicetype}
+
+- Default: `'auto'`
+
+Specifies the type of service at the URL supplied in `data`. Currently accepts either `'wms'` or `'template'`. The default `'auto'` setting will try to autodetect service from the URL.
+
+#### `layers` (string\[\], optional) {#layers}
+
+- Default: `[]`
+
+Specifies names of layers that should be visualized from the image service. 
+
+> Note that WMS services will typically not display anything unless at least one valid layer name is provided.
+
+#### `srs` (string, optional) {#srs}
+
+- Default: `'auto'`
+
+Spatial Reference System for map output, used to query image from the server. Can be one of `EPSG:4326'`, `'EPSG:3857'` or `'auto'`. 
+
+If `'auto'`, the layer will request `EPSG:3857` in `MapView`, and `EPSG:4326` otherwise. Note that a particular SRS may not be supported by your image server.
+
+
+### Callbacks
+
+#### `onMetadataLoad` (Function, optional) {#onmetadataload}
+
+`onMetadataLoad` called when the metadata of the image source successfully loads.
+
+- Default: `metadata => {}`
+
+Receives arguments:
+
+- `metadata` (object) - The metadata for the image services has been loaded. 
+
+Note that metadata will not be loaded when [serviceType](#servicetype) is set to `'template`.
+
+#### `onMetadataLoadError` (Function, optional) {#onmetadataloaderror}
+
+`onMetadataLoadError` called when metadata failed to load.
+
+- Default: `console.error`
+
+Receives arguments:
+
+- `error` (`Error`)
+
+#### `onImageLoadStart` (Function, optional) {#onimageloadstart}
+
+`onImageLoadStart` is a function that is called when the `TileSourceLayer` starts loading metadata after a new image source has been specified.
+
+- Default: `data => null`
+
+Receives arguments:
+
+- `requestId` (`number`) - Allows tracking of specific requests
+
+#### `onImageLoad` (Function, optional) {#onimageload}
+
+`onImageLoad` called when an image successfully loads.
+
+- Default: `() => {}`
+
+Receives arguments:
+
+- `requestId` (`number`) - Allows tracking of specific requests
+
+#### `onImageLoadError` (Function, optional) {#onimageloaderror}
+
+`onImageLoadError` called when an image failed to load.
+
+- Default: `console.error`
+
+Receives arguments:
+
+- `requestId` (`number`) - Allows tracking of specific requests
+- `error` (`Error`)
+
+## Limitations
+
+- Each instance of the `TileSourceLayer` only supports being rendered in one view. See [rendering layers in multiple views](../../developer-guide/views.md#rendering-layers-in-multiple-views) for a workaround.
+- This layer currently does not work well with perspective views (i.e. `pitch>0`).
+- This layer does not work with non-geospatial views such as the [OrthographicView](../core/orthographic-view.md) or the [OrbitView](../core/orbit-view.md).
+
+## Source
+
+[modules/geo-layers/src/wms-layer](https://github.com/visgl/deck.gl/tree/master/modules/geo-layers/src/wms-layer)