首页 / deck.gl / API 文档

LightingEffect

先看结论

光照效果。把若干光源组合成一个 effect 交给 Deck，让体块、柱体和模型产生明暗与阴影，而不是纯粹的平面色块。

最后验证 2026-11-03 · deck.gl 9.0 · 更新 2026-10-29 · 引用本文

new deck.LightingEffect({ ambientLight, directionalLights, pointLights })

构造参数

参数	默认	说明
`ambientLight`	白色、强度 1 的环境光	均匀照亮所有面，决定阴影处的亮度底线
`directionalLights`	空数组	`DirectionalLight` 数组，模拟太阳这类平行光源
`pointLights`	空数组	`PointLight` 数组，模拟路灯这类有位置的光源

属性

属性	说明
`ambientLight`	环境光实例
`directionalLights`	平行光数组
`pointLights`	点光源数组
`shadowColor`	阴影颜色，四元 RGBA 数组；未设置时不投射阴影

示例

var ambient = new deck.AmbientLight({
  color: [255, 255, 255],
  intensity: 1.0
});

// 主光，从左上前方压下来
var keyLight = new deck.DirectionalLight({
  color: [255, 244, 214],
  intensity: 2.2,
  direction: [-3, -9, -1]
});

// 补光，压住背面的纯黑
var fillLight = new deck.DirectionalLight({
  color: [180, 205, 255],
  intensity: 0.9,
  direction: [4, -2, -4]
});

var lightingEffect = new deck.LightingEffect({
  ambientLight: ambient,
  directionalLights: [keyLight, fillLight]
});
lightingEffect.shadowColor = [0, 0, 0, 0.45];

var deckgl = new deck.Deck({
  container: 'map',
  views: [new deck.MapView({ repeat: true })],
  effects: [lightingEffect],
  layers: [
    new deck.GeoJsonLayer({
      id: 'blocks',
      data: buildings,
      extruded: true,
      getElevation: function (f) { return f.properties.height; },
      material: {
        ambient: 0.35,
        diffuse: 0.6,
        shininess: 32,
        specularColor: [60, 64, 70]
      }
    })
  ]
});

哪些图层响应光照

只有声明了 material 的图层参与光照计算，典型的是 GeoJsonLayer 与 SolidPolygonLayer 挤出后的体块、 ColumnLayer、HexagonLayer 的柱体、 SimpleMeshLayer 与 ScenegraphLayer 的模型。平面点、线、文字不受影响，给它们配光照没有效果。

material 里的 ambient、diffuse、shininess 与光源强度共同决定最终亮度。光源调得很亮但材质 diffuse 为 0，表面依旧是黑的。

v9 的不可变更新

deck.gl 9 的图层实例不可变，光源变化后不能直接改图层对象。需要先用 clone 生成新图层，再交给 deckgl.setProps：

function applyNight() {
  keyLight.intensity = 0.4;
  lightingEffect.shadowColor = [0, 0, 0, 0.2];

  var next = deckgl.props.layers.map(function (layer) {
    return layer.clone({});
  });

  deckgl.setProps({ layers: next, effects: [lightingEffect] });
}

阴影开销不小。shadowColor 会让 deck.gl 额外渲染一张深度贴图，体块数量多时帧率下降明显。只在关键视角需要阴影，其他时候把 shadowColor 置空即可。

引用本文

经纬志（2026）。《LightingEffect》。https://www.jingweizhi.com/deckgl/api/lighting-effect.html（访问日期 2026-11-03）。