or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

carto.mdcore-engine.mdeffects.mdextensions.mdindex.mdjson-config.mdlayers.mdmap-integration.mdreact.mdviews.mdwidgets.md
tile.json

extensions.mddocs/

Extensions

Pluggable layer behavior modification system providing additional functionality like brushing, filtering, styling, and clipping without modifying core layer code.

Capabilities

LayerExtension Base Class

Abstract base class for all layer extensions.

/**
 * Base class for all layer extensions
 * Provides hooks for modifying layer behavior
 */
abstract class LayerExtension {
  constructor(opts?: any);
  /** Get shader modifications */
  getShaders(): any;
  /** Initialize extension state */
  initializeState(context: LayerContext, extension: LayerExtension): void;
  /** Update extension state */
  updateState(params: UpdateParameters, extension: LayerExtension): void;
  /** Custom draw logic */
  draw(params: any, extension: LayerExtension): void;
  /** Clean up extension resources */
  finalizeState(extension: LayerExtension): void;
}

BrushingExtension

Enables interactive brushing/selection of data points with mouse or touch gestures.

/**
 * Interactive brushing extension for data selection
 * Allows users to select data points by drawing rectangles
 */
class BrushingExtension extends LayerExtension {
  constructor();
}

interface BrushingExtensionProps {
  /** Enable brushing */
  brushingEnabled?: boolean;
  /** Brushing radius in pixels */
  brushingRadius?: number;
  /** Current brush position */
  brushingTarget?: [number, number];
  /** Brush selection color */
  getBrushingTarget?: AccessorFunction<any, [number, number]>;
}

Usage Example:

import { ScatterplotLayer, BrushingExtension } from "deck.gl";

const layer = new ScatterplotLayer({
  id: 'scatter',
  data: myData,
  getPosition: d => d.coordinates,
  getRadius: 100,
  getFillColor: d => d.selected ? [255, 0, 0] : [128, 128, 128],
  brushingEnabled: true,
  brushingRadius: 50,
  extensions: [new BrushingExtension()]
});

DataFilterExtension

Provides GPU-accelerated data filtering based on attribute ranges or categories.

/**
 * GPU-accelerated data filtering extension
 * Filters data points based on attribute values
 */
class DataFilterExtension extends LayerExtension {
  constructor(options?: DataFilterExtensionOptions);
}

interface DataFilterExtensionOptions {
  /** Number of filter dimensions */
  filterSize?: number;
  /** Enable count aggregation for filtered data */
  countItems?: boolean;
}

interface DataFilterExtensionProps {
  /** Function to get filter value */
  getFilterValue?: AccessorFunction<any, number | number[]>;
  /** Filter range [min, max] */
  filterRange?: [number, number] | [number, number][];
  /** Enable soft edges for filter transitions */
  filterSoftRange?: [number, number] | [number, number][];
  /** Filter transform matrix */
  filterTransformSize?: boolean;
  /** Filter transform color */
  filterTransformColor?: boolean;
}

Usage Example:

import { ScatterplotLayer, DataFilterExtension } from "deck.gl";

const layer = new ScatterplotLayer({
  id: 'scatter',
  data: myData,
  getPosition: d => d.coordinates,
  getRadius: 100,
  getFillColor: [255, 0, 0],
  getFilterValue: d => d.value, // Filter based on this attribute
  filterRange: [10, 50], // Show only data with values between 10-50
  filterSoftRange: [8, 52], // Soft transition at edges
  extensions: [new DataFilterExtension({ filterSize: 1 })]
});

PathStyleExtension

Adds advanced styling capabilities to path-based layers including dash patterns and arrow caps.

/**
 * Advanced path styling extension
 * Adds dash patterns, arrows, and custom path styling
 */
class PathStyleExtension extends LayerExtension {
  constructor(options?: PathStyleExtensionOptions);
}

interface PathStyleExtensionOptions {
  /** Enable dash patterns */
  dash?: boolean;
  /** Enable start/end caps */
  highPrecisionDash?: boolean;
}

interface PathStyleExtensionProps {
  /** Function to get dash array pattern */
  getDashArray?: AccessorFunction<any, number[]>;
  /** Dash array scale factor */
  dashArrayScale?: number;
  /** Dash gap color */
  dashGapColor?: Color;
  /** Dash justified mode */
  dashJustified?: boolean;
}

Usage Example:

import { PathLayer, PathStyleExtension } from "deck.gl";

const layer = new PathLayer({
  id: 'paths',
  data: pathData,
  getPath: d => d.coordinates,
  getColor: [255, 0, 0],
  getWidth: 5,
  getDashArray: [10, 5], // 10 pixels solid, 5 pixels gap
  dashGapColor: [0, 0, 0, 0], // Transparent gaps
  extensions: [new PathStyleExtension({ dash: true })]
});

FillStyleExtension

Adds texture and pattern fill capabilities to polygon-based layers.

/**
 * Advanced fill styling extension for polygons
 * Adds texture mapping and pattern fills
 */
class FillStyleExtension extends LayerExtension {
  constructor(options?: FillStyleExtensionOptions);
}

interface FillStyleExtensionOptions {
  /** Enable pattern fills */
  pattern?: boolean;
}

interface FillStyleExtensionProps {
  /** Fill pattern texture */
  fillPatternAtlas?: string | Texture;
  /** Fill pattern mapping */
  fillPatternMapping?: {[key: string]: PatternDefinition};
  /** Function to get fill pattern */
  getFillPattern?: AccessorFunction<any, string>;
  /** Pattern scale factor */
  getFillPatternScale?: AccessorFunction<any, number>;
  /** Pattern offset */
  getFillPatternOffset?: AccessorFunction<any, [number, number]>;
}

interface PatternDefinition {
  x: number;
  y: number;
  width: number;
  height: number;
}

Fp64Extension

Enables 64-bit floating point precision for handling very large coordinate values.

/**
 * 64-bit floating point precision extension
 * Enables accurate rendering of very large coordinate values
 */
class Fp64Extension extends LayerExtension {
  constructor();
}

Usage Example:

import { ScatterplotLayer, Fp64Extension } from "deck.gl";

const layer = new ScatterplotLayer({
  id: 'high-precision-scatter',
  data: largeCoordinateData,
  getPosition: d => d.preciseCoordinates, // Very large coordinates
  getRadius: 100,
  getFillColor: [255, 0, 0],
  coordinateSystem: COORDINATE_SYSTEM.LNGLAT,
  extensions: [new Fp64Extension()]
});

ClipExtension

Provides GPU-accelerated clipping of layer content to arbitrary shapes.

/**
 * GPU-accelerated clipping extension
 * Clips layer content to specified rectangular or circular bounds
 */
class ClipExtension extends LayerExtension {
  constructor();
}

interface ClipExtensionProps {
  /** Clipping bounds [minX, minY, maxX, maxY] */
  clipBounds?: [number, number, number, number];
  /** Clipping bounds by plane equations */
  clipByInstance?: boolean;
}

CollisionFilterExtension

Prevents overlapping of visual elements like text labels or icons.

/**
 * Collision filtering extension for preventing overlaps
 * Automatically hides overlapping labels or icons
 */
class CollisionFilterExtension extends LayerExtension {
  constructor();
}

interface CollisionFilterExtensionProps {
  /** Enable collision filtering */
  collisionEnabled?: boolean;
  /** Collision group ID */
  getCollisionPriority?: AccessorFunction<any, number>;
}

MaskExtension

Applies masking effects to layers using alpha channels or stencil buffers.

/**
 * Masking extension for selective rendering
 * Uses masks to show/hide parts of layers
 */
class MaskExtension extends LayerExtension {
  constructor();
}

interface MaskExtensionProps {
  /** Mask channels to use */
  maskChannels?: number;
  /** Mask by instance */
  maskByInstance?: boolean;
}

TerrainExtension

Drapes layers over 3D terrain surfaces (experimental).

/**
 * Terrain draping extension (experimental)
 * Projects layers onto 3D terrain surfaces
 */
class _TerrainExtension extends LayerExtension {
  constructor();
}

interface TerrainExtensionProps {
  /** Terrain texture or height data */
  terrainDrawMode?: string;
  /** Terrain bounds */
  terrainBounds?: [number, number, number, number];
  /** Terrain height scale */
  terrainHeightScale?: number;
}

Advanced Extension Usage

Multi-Extension Combinations

Extensions can be combined for complex behaviors:

import { 
  PathLayer, 
  DataFilterExtension, 
  PathStyleExtension, 
  BrushingExtension 
} from "deck.gl";

const advancedPathLayer = new PathLayer({
  id: 'advanced-paths',
  data: pathData,
  getPath: d => d.coordinates,
  getColor: d => d.selected ? [255, 0, 0] : [128, 128, 128],
  getWidth: 5,
  
  // Data filtering
  getFilterValue: d => d.priority,
  filterRange: [1, 10],
  
  // Path styling
  getDashArray: d => d.type === 'dashed' ? [10, 5] : [1, 0],
  
  // Brushing
  brushingEnabled: true,
  brushingRadius: 20,
  
  extensions: [
    new DataFilterExtension({ filterSize: 1 }),
    new PathStyleExtension({ dash: true }),
    new BrushingExtension()
  ]
});

Custom Extension Development

Create custom extensions by extending the base class:

import { LayerExtension } from "deck.gl";

class CustomHighlightExtension extends LayerExtension {
  getShaders() {
    return {
      modules: [
        {
          name: 'custom-highlight',
          fs: `
            uniform bool highlightEnabled;
            uniform vec3 highlightColor;
            
            void main() {
              if (highlightEnabled && isHighlighted) {
                gl_FragColor.rgb = mix(gl_FragColor.rgb, highlightColor, 0.5);
              }
            }
          `
        }
      ]
    };
  }
  
  initializeState(context, extension) {
    // Initialize extension-specific state
  }
  
  updateState(params, extension) {
    const { props } = params;
    // Update uniforms based on props
  }
}

// Usage
const layer = new ScatterplotLayer({
  id: 'scatter',
  data: myData,
  // ... other props
  highlightEnabled: true,
  highlightColor: [255, 255, 0],
  extensions: [new CustomHighlightExtension()]
});

Performance Considerations

Extensions add computational overhead:

  1. GPU Extensions (DataFilter, Clip): Process on GPU, minimal CPU impact
  2. CPU Extensions (Brushing, Collision): Process on CPU, can affect performance with large datasets
  3. Shader Extensions (PathStyle, FillStyle): Add shader complexity

Optimize by:

  • Using GPU-based extensions when possible
  • Limiting the number of simultaneous extensions
  • Pre-filtering data before applying extensions
  • Using appropriate precision levels (Fp64Extension only when needed)