SDK JS
    Preparing search index...

    Class BillboardInstancesLayer

    Draws screen-facing icon billboards at many geographic points, all in one instanced pass. An "instance" is a BillboardInstance — a [lng, lat, height] position, a symbolId indexing the shared sprite atlas, and an optional heading added to that symbol's own rotation — so the caller supplies two things: the atlas (its image plus the symbols UV table) and the instance list. The layer anchors at the instances' centroid, packs them into a quantized ENU tile, and draws each sprite at the size its atlas entry declares. Add it with map.addLayer; it needs a WebGL2 context (on WebGL1 it draws nothing rather than throwing) and Mercator — a non-affine (globe) frame hides it. Heights are used exactly as given; this layer does not sample terrain.

    import { BillboardInstancesLayer } from '@bitruvius/sdk-maplibre';

    const layer = new BillboardInstancesLayer({
      id: 'markers',
      atlas, // { image, width, height, symbols: [{ uv, sizePx }, …] }
      instances: [{ position: [4.8952, 52.3702, 0], symbolId: 0 }],
    });
    map.addLayer(layer);
    map.on('click', (e) => console.log(layer.pickFeature(e.point.x, e.point.y)));

    Implements

    • CustomLayerInterface
    Index

    Constructors

    constructor

    Properties

    id renderingMode type

    Methods

    getCenter onAdd onRemove pickFeature prerender render setOpacity setVisible

    Constructors

    Properties

    id: string

    A unique layer id.

    renderingMode: "3d" = ...

    Either "2d" or "3d". Defaults to "2d".

    type: "custom" = ...

    The layer's type. Must be "custom".

    Methods

    • The anchor [lng, lat] (instances' centroid).

      Returns [number, number] | null

      [lng, lat] in degrees, or null until loaded.

    • MapLibre CustomLayerInterface hook — invoked when the layer is added with map.addLayer; uploads the atlas and packs the instances.

      Parameters

      Returns void

    • MapLibre CustomLayerInterface hook — invoked when the layer is removed with map.removeLayer; releases GL resources.

      Returns void

    • Pick the billboard under a CSS pixel (uses the last rendered frame).

      Parameters

      • cssX: number

        Canvas X in CSS pixels, top-left origin (e.g. a MapLibre click event's e.point.x).

      • cssY: number

        Canvas Y in CSS pixels, top-left origin (e.g. e.point.y).

      Returns BillboardPickHit | null

      The BillboardPickHit under the cursor, or null on a miss / before the first frame.

    • Optional method called during a render frame to allow a layer to prepare resources or render into a texture.

      The layer cannot make any assumptions about the current GL state and must bind a framebuffer before rendering.

      Parameters

      Returns void

    • Called during a render frame allowing the layer to draw into the GL context.

      The layer can assume blending and depth state is set to allow the layer to properly blend and clip other layers. The layer cannot make any other assumptions about the current GL state.

      If the layer needs to render to a texture, it should implement the prerender method to do this and only use the render method for drawing directly into the main framebuffer.

      The blend function is set to gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA). This expects colors to be provided in premultiplied alpha form where the r, g and b values are already multiplied by the a value. If you are unable to provide colors in premultiplied form you may want to change the blend function to gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA).

      Parameters

      Returns void

    • Fade the billboards over the basemap.

      Parameters

      • opacity: number

        Opacity in [0, 1] (clamped); 0 = transparent, 1 = opaque.

      Returns void

    • Show/hide the layer without removing it.

      Parameters

      • visible: boolean

        true to show, false to hide.

      Returns void

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods