PointLayer

PointLayer is a layer for rendering point data based on WebGL graphics technology. PointLayer uses the same rendering logic as VectorTileLayer and shares the same Symbol styles.

PointLayer is used exactly like VectorLayer in the core maptalks library, but benefits from WebGL technology for significantly better performance.

PointLayer only supports adding Marker and MultiPoint. Adding other data will raise an error.

PointLayer supports all marker and text styles of the Symbol styles.

It is an indirect subclass of maptalks.OverlayLayer (directly inheriting from Vector3DLayer) and inherits all methods of Vector3DLayer.

INFO

By default, PointLayer assembles all Markers into a single 3D Mesh for rendering. Updating some Marker-related styles causes the layer to rebuild the Mesh, and frequent operations may cause performance issues. See the performance optimization for vector layers document for details.

Constructor

import { PointLayer } from '@maptalks/gl-layers';

const layer = new PointLayer('point0');

Details

Parameters:

• id* String the layer id
• options* Object options, the available options are as follows:

Option	Type	Description	Default
iconErrorUrl	String	The fallback icon for icons that fail to load	null
collision	Boolean	Whether to enable collision detection	false
collisionFrameLimit	Number	The time limit for collision detection calculation per frame, in ms	1
sceneConfig	Object	The sceneConfig of the point rendering program	default config
sceneConfig.collision	Boolean	The collision detection switch of the point rendering program	true
sceneConfig.fading	Boolean	Whether to enable the fade effect of collision detection	false
sceneConfig.fadingDuration	Number	The duration of the collision detection fade, in ms	16 * 14
sceneConfig.fadeInDelay	Number	The delay before showing after passing collision detection, in ms	600
sceneConfig.fadeOutDelay	Number	The delay before hiding after failing collision detection, in ms	100
sceneConfig.uniquePlacement	Boolean	Whether to avoid duplicate labels (unique placement)	false
sceneConfig.depthFunc	String	The depth test function. Possible values are: 'always', '<=', '<', '>=', '>', '=', '!=', 'never'	'always'
glyphSdfLimitPerFrame	Number	The maximum number of SDF glyphs drawn per tile per frame	15
picking	Boolean	Whether the layer is allowed to query data with the identify or identifyAtPoint methods	true
textGamma	Number	The gamma value of text, which can be used to adjust text sharpness	1
geometryEvents	Boolean	Whether geometries are allowed to respond to events	true
styleScale	Number	The overall scale factor of the layer's icons and text	1

|attribution | String | The attribution of the layer | null | |minZoom | Number | The minimum zoom level at which the layer is displayed | null | |maxZoom | Number | The maximum zoom level at which the layer is displayed | null | |visible | Boolean | Whether the layer is visible | true | |opacity | Number | The opacity of the layer | 1 | |hitDetect | Boolean | Whether to enable layer drawing detection (dynamic mouse cursor styles); disabling it can improve performance | true | |collisionScope | String | The scope of the collision detection index: "map" or "layer" | "layer" |

Methods

updateSymbol(idx, symbol)

Updates the symbol of the style with index idx.

layer.updateSymbol(0, symbol);

Parameters:

• idx Number the index of the style
• symbol Object the symbol properties to update

Returns:

• this

outlineAll()

Highlights all data on the layer.

Because highlighting is implemented with post-processing, the layer must be added to a GroupGLLayer with the outline post-processing enabled.

layer.addTo(groupGLLayer);
layer.outlineAll();

Returns:

• this

outline(geoIds)

Highlights all geometries whose ids are in geoIds.

layer.addTo(groupGLLayer);
layer.outline([0, 1, 2]);

Parameters:

• geoIds Number[] | String[] an array of geometry ids

Returns:

• this

cancelOutline()

Cancels the highlight.

Returns:

• this

toJSON()

Gets the JSON serialization object of the layer.

This object can be deserialized into a layer object with the Layer.fromJSON method.

const json = layer.toJSON();
const copiedLayer = maptalks.Layer.fromJSON(json);

Returns:

• Object

identify(coordinate, options)

Queries features at the given coordinate on the layer (only rendered data can be queried).

layer.identify([121.23, 39.34], { tolerance: 2 });

Parameters:

• coordinate Number[] the coordinate value
• options Object options, the possible properties are: | Property | Type | Description | Default | | ------ | :----: | ---- | :-----------: | | tolerance | Number | The pixel tolerance for the query | 3 |

Returns:

• Geometry[]

identifyAtPoint(containerPoint, options)

Queries features at the given container point on the layer.

layer.identifyAtPoint([400, 300], { tolerance: 2 });

Parameters:

• containerPoint Number[] container coordinates (screen pixels)
• options Object options, the possible properties are: | Property | Type | Description | Default | | ------ | :----: | ---- | :-----------: | | tolerance | Number | The pixel tolerance for the query | 3 |

Returns:

• Object[]

Methods Inherited from OverlayLayer

See the API documentation of the parent class OverlayLayer for details.

getGeometryById(id)

Gets the geometry with the given id.

Parameters:

• id Number | String the id of the geometry

Returns:

• Geometry

getGeometries(filter, context)

Gets all geometries matching the given condition.

Parameters:

• filter Function the filter function
• context Object the this value used when the function runs

Returns:

• Geometry[]

getFirstGeometry()

Gets the first geometry.

Returns:

• Geometry

getLastGeometry()

Gets the last geometry.

Returns:

• Geometry

getCount()

Gets the number of geometries.

Returns:

• Number

getExtent()

Gets the geographic extent of all geometries on the layer.

Returns:

• Extent

forEach(fn, context)

Iterates over the geometries and executes the function.

Parameters:

• fn Function the function applied to each geometry, function(geometry) {}
• context Object the this value used when the function runs

Returns:

• this

isEmpty()

Checks whether the layer is empty.

Returns:

• Boolean

addGeometry(geometries, fitView)

Adds geometries to the layer.

Parameters:

• geometries Geometry | Geometry[] a geometry or an array of geometries
• fitView Boolean

Returns:

• this

removeGeometry(geometries)

Removes geometries from the layer.

Parameters:

• geometries Geometry | Geometry[]

Returns:

• this

clear()

Clears the layer and removes all geometries.

Returns:

• this

setStyle(style)

Sets the style of the layer. See this link for the style documentation.

const style = [
  {
    filter : true,            // 数据的过滤条件
    symbol: {                 // 样式定义
      markerWidth: 6,
      markerHeight: 6,
      markerType: 'ellipse',
      markerFill: '#0f0'
    }
  }
];
layer.setStyle(style);

Parameters:

• style Object[] the layer style object. Each style object contains two properties, filter and symbol: filter is a filter condition of the feature-filter type, and symbol is a style object.

Returns:

• this

getStyle()

Gets the layer style.

Returns:

• Object[]

removeStyle()

Removes the layer style.

Returns:

• this

Methods Inherited from Layer

See the API documentation of the parent class Layer for details.

getId()

Gets the layer id.

Returns:

• Number | String

setId(id)

Sets the layer id.

Returns:

• this

addTo(map)

Adds the layer to the map.

Returns:

• this

getMinZoom()

Gets the minimum zoom level.

Returns:

• Number

getMaxZoom()

Gets the maximum zoom level.

Returns:

• Number

getMap()

Gets the map object that the layer is added to.

Returns:

• Map

getProjection()

Gets the projection of the layer.

Returns:

• Projection

show()

Shows the layer.

Returns:

• this

hide()

Hides the layer.

Returns:

• this

isVisible()

Checks whether the layer is visible.

Returns:

• Boolean

remove()

Removes the layer.

Returns:

• this

on(events, handler, context)

Registers an event listener on the layer.

Returns:

• this

addEventListener(events, handler, context)

Same as the on method.

Returns:

• this

once(events, handler, context)

Registers a one-time event listener on the layer; it is removed after being fired.

Returns:

• this

off(events, handler, context)

Removes the registered event listener from the layer.

Returns:

• this

removeEventListener(events, handler, context)

Same as the off method.

Returns:

• this

listens(events, handler, context)

Checks whether the layer is listening to the given events.

Returns:

• Boolean

fire(event, params)

Manually fires an event; params is the event parameter.

Returns:

• this

setOptions(options)

Sets the layer options.

Returns:

• this

config(key, value)

Updates a layer option.

Returns:

• this

Static Methods

fromJSON(json)

Creates a PointLayer object from the layer's JSON object.

const json = layer.toJSON();

const layerCopied = maptalks.Layer.fromJSON(json);

Returns:

• PointLayer

Events

Example code for listening to layer events:

// 监听workerready事件
layer.once('workerready', e => {
  // e为事件参数
  console.log('worker is ready');
});

// 监听tileload事件
layer.on('tileload', e => {
  // e为事件参数
  console.log('loaded a tile', e.tile);
});

Layer Events

canvasisdirty

Fired when the layer canvas is redrawn.

Properties:

Property	Type	Value
type	String	"canvasisdirty"
target	Layer	this

Note: The renderer also fires rendering events such as buildmarkermesh, updatemesh, partialupdate, removegeo, and iblupdated (verified in 2026).

Events Inherited from OverlayLayer

addgeo

Fired when a geometry is added.

Properties:

Property	Type	Value
type	String	"addgeo"
target	Layer	this
geometries	Geometry[]	the added geometries

removegeo

Fired when a geometry is removed.

Properties:

Property	Type	Value
type	String	"removegeo"
target	Layer	this
geometries	Geometry[]	the removed geometries

setstyle

Fired after the layer style is set with setStyle.

Properties:

Property	Type	Value
type	String	"setstyle"
target	Layer	this
style	Object[]	the style array

removestyle

Fired after the layer style is cleared with removeStyle.

Properties:

Property	Type	Value
type	String	"removestyle"
target	Layer	this

Events Inherited from Layer

clear

Fired when the layer is cleared.

Properties:

Property	Type	Value
type	String	"clear"
target	VectorTileLayer	this

idchange

Fired when the layer id changes.

Properties:

Property	Type	Value
type	String	"idchange"
target	VectorTileLayer	this
old	String	the old id
new	String	the new id

renderercreate

Fired when the renderer is created.

Properties:

Property	Type	Value
type	String	"renderercreate"
target	VectorTileLayer	this
renderer	VectorTileLayerRenderer

canvascreate

Fired when the canvas is created.

Properties:

Property	Type	Value
type	String	"canvascreate"
target	VectorTileLayer	this
gl	WebGLRenderingContext2D

renderstart

Fired when rendering starts.

Properties:

Property	Type	Value
type	String	"renderstart"
target	VectorTileLayer	this

renderend

Fired when rendering ends.

Properties:

Property	Type	Value
type	String	"renderend"
target	VectorTileLayer	this

This document has been cross-checked against the @maptalks/gl-layers 2026 source code (api-notes-vt-gl.md)