- The
opacityprop of all layers is now default to1(used to be0.8).
ArcLayerpropsgetStrokeWidth: usegetWidth
LineLayerpropsgetStrokeWidth: usegetWidth
H3HexagonLayerpropsgetColor: usegetFillColorandgetLineColor
projectshader moduleproject_scale: useproject_sizeproject_to_clipspace: useproject_position_to_clipspaceproject_pixel_to_clipspace: useproject_pixel_size_to_clipspace
WebMercatorViewportclassgetLocationAtPoint: usegetMapCenterByLngLatPositionlngLatDeltaToMetersmetersToLngLatDelta
LayerclasssetLayerNeedsUpdate: usesetNeedsUpdatesetUniforms: usemodel.setUniformsuse64bitProjectionprojectFlat: useprojectPosition
The pre-bundled version, a.k.a. the scripting API has been aligned with the interface of the core Deck class.
- Top-level view state props such as
longitude,latitude,zoomare no longer supported. To specify the default view state, useinitialViewState. controlleris no longer on by default, usecontroller: true.
- The common space is no longer scaled to the current zoom level. This is part of an effort to make the geometry calculation more consistent and predictable. While one old common unit is equivalent to 1 screen pixel at the viewport center, one new common unit is equivalent to
viewport.scalepixels at the viewport center. viewport.distanceScaleskeys are renamed:pixelsPerMeter->unitsPerMetermetersPerPixel->metersPerUnit
- Low part of a
DOUBLEattribute is renamed from*64xyLowto*64Lowand uses the same size as the high part. This mainly affect position attributes, e.g. allvec2 positions64xyLowandvec2 instancePositions64xyLoware nowvec3 positions64Lowandvec3 instancePositions64Low.project:vec3 project_position(vec3 position, vec2 position64xyLow)is nowvec3 project_position(vec3 position, vec3 position64Low).project:vec4 project_position(vec4 position, vec2 position64xyLow)is nowvec4 project_position(vec4 position, vec3 position64Low).project32andproject64:vec4 project_position_to_clipspace(vec3 position, vec2 position64xyLow, vec3 offset)is nowvec4 project_position_to_clipspace(vec3 position, vec3 position64Low, vec3 offset).
This change affects custom layers. deck.gl is no longer registering shaders by default. This means any modules array defined in layer.getShaders() or new Model() must now use the full shader module objects, instead of just their names. All supported shader modules can be imported from @deck.gl/core.
/// OLD
new Model({
// ...
modules: ['picking', 'project32', 'gouraud-lighting']
});Should now become
import {picking, project32, gouraudLighting} from '@deck.gl/core';
/// NEW
new Model({
// ...
modules: [picking, project32, gouraudLighting]
});We have fixed a bug when using initialViewState with multiple views. In the past, the state change in one view is unintendedly propagated to all views. As a result of this fix, multiple views (e.g. mini map) are no longer synchronized by default. To synchronize them, define the views with an explicit viewState.id:
new Deck({
// ...
views: [
new MapView({id: 'main'}),
new MapView({id: 'minimap', controller: false, viewState: {id: 'main', pitch: 0, zoom: 10}})
]
})See View class documentation for details.
layer.setLayerNeedsUpdateis renamed tolayer.setNeedsUpdate()and the old name will be removed in the next major release.- Previously deprecated
Layerclass method,screenToDevicePixels, is removed. Use luma.gl utility methods instead.
ScreenGridLayer: support is now limited to browsers that implement either WebGL2 or theOES_texture_floatextension. coverage stats- Some shader attributes are renamed for consistency:
| Layer | Old | New |
|---|---|---|
LineLayer |
instanceSourceTargetPositions64xyLow.xy |
instanceSourcePositions64xyLow |
instanceSourceTargetPositions64xyLow.zw |
instanceTargetPositions64xyLow |
|
PathLayer |
instanceLeftStartPositions64xyLow.xy |
instanceLeftPositions64xyLow |
instanceLeftStartPositions64xyLow.zw |
instanceStartPositions64xyLow |
|
instanceEndRightPositions64xyLow.xy |
instanceEndPositions64xyLow |
|
instanceEndRightPositions64xyLow.zw |
instanceRightPositions64xyLow |
|
ArcLayer |
instancePositions64Low |
instancePositions64xyLow |
ScenegraphLayer |
instancePositions64xy |
instancePositions64xyLow |
SimpleMeshLayer |
instancePositions64xy |
instancePositions64xyLow |
- Non-breaking Change: The
_JSONConverterclass has been renamed toJSONConverter(deprecated alias still available). - Non-breaking Change: The
_JSONConverter.convertJson()method has been renamed toJSONConverter.convert()(deprecated stub still available). - Breaking Change: The
_JSONConverterno longer automatically injects deck.glViewclasses and enumerations. If reqiured need to import and add these to yourJSONConfiguration. - Removed: The
JSONLayeris no longer included in this module. The code for this layer has been moved to an example in/test/apps/json-layer, and would need to be copied into applications to be used.
Following Layer class methods have been removed :
| Removed | Alternate | Comment |
|---|---|---|
use64bitProjection |
use Fp64Extension |
details in fp64 prop section below |
is64bitEnabled |
use Fp64Extension |
details in fp64 prop section below |
updateAttributes |
_updateAttributes |
method is renamed |
The deprecated fp64 prop is removed. The current 32-bit projection is generally precise enough for almost all use cases. If you previously use this feature:
/// old
import {COORDINATE_SYSTEM} from '@deck.gl/core';
new ScatterplotLayer({
coordinateSystem: COORDINATE_SYSTEM.LNGLAT_DEPRECATED,
fp64: true,
...
})It can be changed to:
/// new
import {COORDINATE_SYSTEM} from '@deck.gl/core';
import {Fp64Extension} from '@deck.gl/extensions';
new ScatterplotLayer({
coordinateSystem: COORDINATE_SYSTEM.LNGLAT_DEPRECATED,
extensions: [new Fp64Extension()],
...
})All core layer shaders now receive normalized color attributes and uniforms. If you were previously subclassing a core layer with custom vertex shaders, you should expect the color attributes to be in [0, 1] range instead of [0, 255].
The project64 shader module is no longer registered by default. If you were previously using a custom layer that depends on this module:
getShaders() {
return {vs, fs, modules: ['project64']};
}It can be changed to:
import {project64} from '@deck.gl/core';
getShaders() {
return {vs, fs, modules: [project64]};
}getElevationValue, getElevationWeight and getColorValue, getColorWeight are now compared using updateTriggers like other layer accessors. Update them without passing updateTriggers will no longer trigger layer update.
IE support is deprecated and will be removed in the next major release.
-
Fixed a bug where
coordinateOrigin'szis not applied inMETER_OFFSETSandLNGLAT_OFFSETScoordinate systems. -
If your application was subclassing
GridLayer, you should now subclassCPUGridLayerinstead, and either use it directly, or provide it as the sublayer class forGridLayerusing_subLayerProps:class EnhancedCPUGridLayer extends CPUGridLayer { // enhancments } // Code initilizing GridLayer const myGridLayer = new GridLayer({ // props ... // Override sublayer type for 'CPU' _subLayerProps: { CPU: { type: EnhancedCPUGridLayer } } });
getColorprops inColumnLayerandH3HexagonLayerare deprecated. UsegetLineColorandgetFillColorinstead.
@deck.gl/coreis moved fromdependenciestodevDependenciesfor all submodules. This will reduce the runtime error caused by installing multiple copies of the core.- The master module
deck.glnow include all submodules except@deck.gl/test-utils. See list of submodules for details. ContourLayer,GridLayer,HexagonLayerandScreenGridLayerare moved from@deck.gl/layersto@deck.gl/aggregation-layers. No action is required if you are importing them fromdeck.gl.@deck.gl/experimental-layersis deprecated. Experimental layers will be exported from their respective modules with a_prefix.BitmapLayeris moved to@deck.gl/layers.MeshLayeris renamed toSimpleMeshLayerand moved to@deck.gl/mesh-layers.TileLayerandTripsLayerare moved to@deck.gl/geo-layers.
Breaking Changes:
onLayerHoverandonLayerClickprops are replaced withonHoverandonClick. The first argument passed to the callback will always be a valid picking info object, and the second argument is the pointer event. This change makes these two events behave consistently with other event callbacks.
Deprecations:
ArcLayerandLineLayer'sgetStrokeWidthprops are deprecated. UsegetWidthinstead.
Breaking Changes:
HexagonCellLayeris removed. Use ColumnLayer withdiskResolution: 6instead.- A bug in projecting elevation was fixed in
HexagonLayer,GridLayerandGridCellLayer. The resulting heights of extruded grids/hexagons have changed. You may adjust them to match previous behavior by tweakingelevationScale. - The following former experimental layers' APIs are redesigned as they graduate to official layers. Refer to their documentations for details:
The old experimental prop lightSettings in many 3D layers is no longer supported. The new and improved settings are split into two places: a material prop for each 3D layer and a shared set of lights specified by LightingEffect with the effects prop of Deck.
Check Using Lighting in developer guide for more details.
v7.0 includes major bug fixes for OrbitView and OrthographicView. Their APIs are also changed for better clarity and consistency.
Breaking Changes:
- View state:
zoomis now logarithmic in allViewclasses.zoom: 0maps one unit in world space to one pixel in screen space. - View state:
minZoomandmaxZoomnow default to no limit. - View state:
offset(pixel-shift of the viewport center) is removed, usetarget(world position[x, y, z]of the viewport center) instead. - Constructor prop: added
targetto specify the viewport center in world position. OrthographicView's constructor propsleft,right,topandbottomare removed. Usetargetto specify viewport center.OrbitView's constructor propdistanceand static methodgetDistanceare removed. Usefovyandzoominstead.
Deprecations:
project_scale->project_sizeproject_to_clipspace->project_common_position_to_clipspaceproject_to_clipspace_fp64->project_common_position_to_clipspace_fp64project_pixel_to_clipspace->project_pixel_size_to_clipspace
If you are using DeckGL with react-map-gl, @deck.gl/react@^7.0.0 no longer works with react-map-gl v3.x.
The experimental OrthographicView class has the following breaking changes:
zoomis reversed (larger value means zooming in) and switched to logarithmic scale.- Changed view state defaults:
zoom-1->0offset-[0, 1]->[0, 0]minZoom-0.1->-10
eye,lookAtandupare now set in theOrthographicViewconstructor instead ofviewState.
Deprecations:
outlineis deprecated: usestrokedinstead.strokeWidthis deprecated: usegetLineWidthinstead. Note that whilestrokeWidthis in pixels, line width is now pecified in meters. The old appearance can be achieved by usinglineWidthMinPixelsand/orlineWidthMaxPixels.getColoris deprecated: usegetFillColorandgetLineColorinstead.
Breaking changes:
outline/strokedno longer turns off fill. Usefilled: falseinstead.
Breaking changes:
stroked,getLineWidthandgetLineColorprops now apply to point features (rendered with a ScatterplotLayer) in addition to polygon features. To revert to the old appearance, supply a_subLayerPropsoverride:
new GeoJsonLayer({
// ...other props
stroked: true,
_subLayerProps: {
points: {stroked: false}
}
});Shallow changes in getColorValue and getElevationValue props are now ignored by default. To trigger an update, use the updateTriggers prop. This new behavior is aligned with other core layers and improves runtime performance.
Although the prop types system is largely backward-compatible, it is possible that some custom layers may stop updating when a certain prop changes. This is because the automatically deduced prop type from defaultProps does not match its desired usage. Switch to explicit descriptors will fix the issue, e.g. from:
MyLayer.defaultProps = {
prop: 0
};To:
MyLayer.defaultProps = {
prop: {type: 'number', value: 0, min: 0}
};The default coordinate system COORDINATE_SYSTEM.LNGLAT is upgraded to offer high-precision results in a way that is much faster and more cross-platform compatible. The fp64 layer prop is ignored when using this new coordinate system. You can get the old fp64 mode back by using coordinateSystem: COORDINATE_SYSTEM.LNGLAT_DEPRECATED with fp64: true.
deck.gl v6.0 brings in luma.gl v6.0 which is a major release with a few breaking changes. The change that is most likely to affect deck.gl applications is probably that the way the GL constant is imported has changed. For details, see to the luma.gl Upgrade Guide.
Pixel sizes in line, icon and text layers now match their HTML/SVG counterparts. To achieve the same rendering output as v5, you should use half the previous value in the following props:
ArcLayer.getStrokeWidthLineLayer.getStrokeWidthIconLayer.getSizeorIconLayer.sizeScaleTextLayer.getSizeorTextLayer.sizeScalePointCloudLayer.radiusPixels
All layer accessors that support constant values have had their default values changed to constants. For example, ScatterplotLayer's default getRadius prop is changed from d => d.radius || 1 to 1. All dynamic attributes now must be explicitly specified. This change makes sure that using default values results in best performance.
- (React only) Viewport constraint props:
maxZoom,minZoom,maxPitch,minPitchare no longer supported by theDeckGLcomponent. They must be specified as part of theviewStateobject. - (React only)
ViewportControllerReact component has been removed. The functionality is now built in to theDeckandDeckGLclasses. Deck.onViewportChange(viewport)etc callbacks are no longer supported. UseDeck.onViewStateChange({viewState})DeckGL.viewportandDeckGL.viewportsprops are no longer supported. UseDeckGL.views.
minColor and maxColor props are deprecated. Use colorRange and colorDomain props.
Some previously deprecated project_ module GLSL functions have now been removed.
isGeneric field of attribute object returned by AttributeManager's update callbacks is replaced by constant. For more details check attribute manager.
Continuing the changes that started in 5.2: while the base Viewport class will remain supported, the various Viewport subclasses are now deprecated. For now, if for projection purposes you need to create a Viewport instance matching one of your View instances you can use View.makeViewport:
new MapView().makeViewport({width, height, viewState: {longitude, latitude, zoom}});| Layer | Removed Prop | New Prop | Comment |
|---|---|---|---|
ArcLayer |
strokeWidth |
getStrokeWidth |
Can be set to constant value |
LineLayer |
strokeWidth |
getStrokeWidth |
Can be set to constant value |
Core layers are broken out from @deck.gl/core to a new submodule @deck.gl/layers. Non-React users of deck.gl should now install both submodules:
npm install @deck.gl/core @deck.gl/layersAnd import layers from the new submodule instead of core:
import {ScatterplotLayer} from '@deck.gl/layers';Users of deck.gl are not affected by this change.
DeckGL.viewportsandDeckGL.viewportare deprecated and should be replaced withDeckGL.views.
- A number of
Viewportsubclasses have been deprecated. They should be replaced with theirViewcounterparts.
Some experimental exports have been removed:
- The experimental React controller components (
MapControllerandOrbitController) have been removed. These are now replaced with JavaScript classes that can be used with theDeck.controller/DeckGL.controllerproperty.
N/A
deck.gl 4.1 requires luma.gl as peer dependency, but 5.0 specifies it as a normal "dependency". This means that many applications no longer need to list luma.gl in their package.json. Applications that do might get multiple copies of luma.gl installed, which will not work. luma.gl will detect this situation during run-time throwing an exception, but npm and yarn will not detect it during install time. Thus your build can look successful during upgrade but fail during runtime.
Coordinate system related props have been renamed for clarity. The old props are no longer supported and will generate errors when used.
| Layer | Removed Prop | New Prop | Comment |
|---|---|---|---|
| Layer | projectionMode |
coordinateSystem |
Any constant from COORDINATE_SYSTEM |
| Layer | projectionOrigin |
coordinateOrigin |
[lng, lat] |
Note; There is also an important semantical change in that using coordinateSystem instead of projectionMode causes the superimposed METER_OFFSET system's y-axis to point north instead of south. This was always the intention so in some sense this was regarded as a bug fix.
Following methods and props have been renamed for clarity. The semantics are unchanged. The old props are still available but will generate a deprecation warning.
| Old Method | New Method | Comment |
|---|---|---|
queryObject |
pickObject |
These names were previously aligned with react-map-gl, but ended up confusing users. Since rest of the deck.gl documentation talks extensively about "picking" it made sense to stay with that terminology. |
queryVisibleObjects |
pickObjects |
The word "visible" was intended to remind the user that this function only selects the objects that are actually visible in at least one pixel, but again it confused more than it helped. |
| Removed uniform | Comment |
|---|---|
| renderPickingBuffer | picking shader module |
| pickingEnabled | picking shader module |
| selectedPickingColor | picking shader module |
The shader uniforms are used for implementing picking in custom shaders, these uniforms are no longer set by the deck.gl. Custom shaders can now use luma.gl picking shader module.
Following WebGL parameters are set during DeckGL component initialization.
| WebGL State | Value |
|---|---|
| depthTest | true |
| depthFunc | gl.LEQUAL |
| blendFuncSeparate | [gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA] |
All our layers enable depth test so we are going set this state during initialization. We are also changing blend function for more appropriate rendering when multiple elements are blended.
For any custom needs, these parameters can be overwritten by updating them in onWebGLInitialized callback or by passing them in parameters object to drawLayer method of Layer class.
The assembleShaders function was moved to luma.gl in v4.1 and is no longer re-exported from deck.gl. As described in v4.1 upgrade guide please use Model class instead or import it from luma.gl.
ScatterplotLayer and PolygonLayer supported immutable/ES6 containers using get method, due to performance reasons this support has been dropped.
deck.gl v4.1 is a backward-compatible release. Most of the functionality and APIs remain unchanged but there are smaller changes that might requires developers' attention if they develop custom layers. Note that applications that are only using the provided layers should not need to make any changes issues.
Be aware that deck.gl 4.1 bumps the luma.gl peer dependency from 3.0 to 4.0. There have been instances where this was not detected by the installer during update.
- shouldUpdateState - deck.gl v4.1 contains additional optimizations of the layer lifecycle and layer diffing algorithms. Most of these changes are completely under the hood but one visible change is that the default implementation of
Layer.shouldUpdateno longer returns true if only the viewport has changed. This means that layers that need to update state in response to changes in screen space (viewport) will need to redefineshouldUpdate:
shouldUpdateState({changeFlags}) {
return changeFlags.somethingChanged; // default is now changeFlags.propsOrDataChanged;
}Note that this change has already been done in all the provided deck.gl layers that are screen space based, including the ScreenGridLayer and the HexagonLayer.
- deck.gl v4.1 bumps luma.gl to from v3 to v4. This is major release that brings full WebGL2 enablement to deck.gl. This should not affect you if you are mainly using the provided deck.gl layers but if you are writing your own layers using luma.gl classes you may want to look at the upgrade guide of luma.gl.
The gl parameter is provided as a separate argument in luma.gl v4, instead of part of the options object.
// luma.gl v4
new Model(gl, {opts});
// luma.gl v3
new Model({gl, ...opts});Custom layers are no longer expected to call assembleShaders directly. Instead, the new Model class from luma.gl v4 will take shaders and the modules they are using as parameters and assemble shaders automatically.
// luma.gl v4
const model = new Model(gl, {
vs: VERTEX_SHADER,
fs: FRAGMENT_SHADER,
modules: ['fp64', ...],
shaderCache: this.context.shaderCache
...
}));
// luma.gl v3
const shaders = assembleShaders(gl, {
vs: VERTEX_SHADER,
fs: FRAGMENT_SHADER,
modules: ['fp64', 'project64'],
shaderCache: this.context.shaderCache
});
const model = new Model({
gl,
vs: shaders.vs,
fs: shaders.fs,
...
});| Layer | Status | Replacement |
|---|---|---|
ChoroplethLayer |
Removed | GeoJsonLayer, PolygonLayer and PathLayer |
ChoroplethLayer64 |
Removed | GeoJsonLayer, PolygonLayer and PathLayer |
ExtrudedChoroplethLayer |
Removed | GeoJsonLayer, PolygonLayer and PathLayer |
- ChoroplethLayer, ChoroplethLayer64, ExtrudedChoroplethLayer
These set of layers were deprecated in deck.gl v4, and are now removed in v5. You can still get same functionality using more unified, flexible and performant layers:
GeoJsonLayer, PolygonLayer and PathLayer.
A small but breaking change that will affect all applications is that the 'deck.gl/react' import is no longer available. As of v4.0, the app is required to import deck.gl as follows:
// V4
import DeckGL from 'deck.gl';
// V3
import DeckGL from 'deck.gl/react';While it would have been preferable to avoid this change, a significant modernization of the deck.gl build process and preparations for "tree-shaking" support combined to make it impractical to keep supporting the old import style.
| Layer | Status | Replacement |
|---|---|---|
ChoroplethLayer |
Deprecated | GeoJsonLayer, PolygonLayer and PathLayer |
ChoroplethLayer64 |
Deprecated | GeoJsonLayer, PolygonLayer and PathLayer |
ExtrudedChoroplethLayer |
Deprecated | GeoJsonLayer, PolygonLayer and PathLayer |
EnhancedChoroplethLayer |
Moved to examples | PathLayer |
- ChoroplethLayer, ChoroplethLayer64, ExtrudedChoroplethLayer
These set of layers are deprecated in deck.gl v4, with their functionality completely substituted by more unified, flexible and performant new layers:
GeoJsonLayer, PolygonLayer and PathLayer.
Developers should be able to just supply the same geojson data that are used with ChoroplethLayers to the new GeoJsonLayer. The props of the GeoJsonLayer are a bit different from the old ChoroplethLayer, so proper testing is recommended to achieve satisfactory result.
- EnhancedChoroplethLayer
This was a a sample layer in deck.gl v3 and has now been moved to a stand-alone example and is no longer exported from the deck.gl npm module.
Developers can either copy this layer from the example folder into their application's source tree, or consider using the new PathLayer which also handles wide lines albeit in a slightly different way.
| Layer | Old Prop | New Prop | Comment |
|---|---|---|---|
| Layer | dataIterator |
N/A | Prop was not functional in v3 |
| ScatterplotLayer | radius |
radiusScale |
Default has changed from 30 to 1 |
| ScatterplotLayer | drawOutline |
outline |
|
| ScreenGridLayer | unitWidth |
cellSizePixels |
|
| ScreenGridLayer | unitHeight |
cellSizePixels |
All line based layers (LineLayer and ArcLayerand theScatterplotLayerin outline mode) now use use shaders to render an exact pixel thickness on lines, instead of using theGL.LINE` drawing mode.
This particular change was caused by browsers dropping support for this feature (Chrome and Firefox).
Also GL.LINE mode rendering always had signficant limitations in terms of lack of support for mitering, unreliable support for anti-aliasing and platform dependent line width limits so this should represent an improvement in visual quality and consistency for these layers.
This prop has been removed in deck.gl v4. Note that it was not functioning as documented in deck.gl v3.
Props that have their name end of Scale is a set of props that multiply some existing value for all objects in the layers. These props usually correspond to WebGL shader uniforms that "scaling" all values of specific attributes simultaneously.
For API consistency reasons these have all been renamed with the suffix ..Scale. See the property table above.
This lifecycle was deprecated in v3 and is now removed in v4. Use Layer.updateState instead.
Update triggers can now be specified by referring to the name of the accessor, instead of the name of the actual WebGL attribute.
Note that this is supported on all layers supplied by deck.gl v4, but if you are using older layers, they need a small addition to their attribute definitions to specify the name of the accessor.
Use the new static function AttributeManager.setDefaultLogFunctions to set loggers for all AttributeManagers (i.e. for all layers).
This method has been deprecated since version 2.5 and is now removed in v4. Use AttributeManager.add() instead.