首页 / luma.gl / API 文档

AnimationLoop

先看结论

把设备、逐帧回调与时间信息包在一起的小型循环，替代手写 requestAnimationFrame。

最后验证 2026-11-03 · luma.gl 9.4 · 更新 2026-10-27 · 引用本文

new AnimationLoop(props) → AnimationLoop

构造参数

参数	必需	说明
`device`	是	设备实例或设备 Promise。v9 不再自动创建
`onInitialize`	否	首帧之前调用一次，参数与逐帧回调相同，可返回 Promise
`onRender`	否	每帧调用，绘制逻辑写在这里
`onFinalize`	否	停止或销毁时调用，用来释放资源
`onError`	否	回调抛出异常时接收错误，默认打印到控制台
`stats`	否	外部传入的统计对象
`autoResizeViewport`	否	是否自动按设备像素比设置视口
`onAddHTML`	否	返回一段 HTML，插入信息面板

回调收到的字段

onInitialize、onRender、onFinalize 收到同一个 AnimationProps 对象，常用字段如下：

字段	说明
`device`	当前设备
`canvas` / `canvasContext`	画布与画布上下文，可查询像素尺寸
`width` / `height`	当前绘制尺寸，已按设备像素比换算
`aspect`	宽高比，用于相机投影
`time`	当前时间戳，毫秒
`startTime`	循环开始的时间戳
`tick`	已渲染的帧数
`tock`	循环运行的总时长，毫秒
`timeline`	挂载的时间轴对象，未挂载时为 null

方法

方法	说明
`start()`	启动循环，返回 Promise。首帧前会等待设备就绪并执行 `onInitialize`
`stop()`	停止循环，触发 `onFinalize`
`destroy()`	停止并释放内部资源
`setNeedsRedraw(reason)`	标记需要重绘，适合按需渲染模式
`needsRedraw()`	读取并清除重绘标记
`redraw(time)`	立即渲染一帧，不等待下一帧回调
`setProps(props)`	运行时更新可变参数
`attachTimeline(timeline)`	挂载时间轴，循环自动推进它
`waitForRender()`	等待下一帧渲染完成

标准写法

const loop = new AnimationLoop({
  device: device,

  onInitialize: function (props) {
    console.log('画布尺寸', props.width, props.height);
  },

  onRender: function (props) {
    const pass = props.device.beginRenderPass({
      clearColor: [0.05, 0.07, 0.10, 1]
    });

    model.draw(pass);
    pass.end();
  },

  onFinalize: function () {
    model.destroy();
  },

  onError: function (error) {
    console.error('渲染出错', error);
  }
});

await loop.start();

暂停与按需渲染

静态内容不需要每帧重画。用 setNeedsRedraw 标记变化，在回调里读取 needsRedraw()，没有标记时直接返回，可以显著降低空闲时的 GPU 占用与耗电。

onRender: function (props) {
  if (!loop.needsRedraw()) return;

  const pass = props.device.beginRenderPass({ clearColor: [0, 0, 0, 1] });
  model.draw(pass);
  pass.end();
}

// 数据或视角变化后
loop.setNeedsRedraw('data-updated');

与模板类配合

makeAnimationLoop(TemplateClass, props) 接收一个带 onInitialize 与 onRender 的类，把实例生命周期交给循环管理。适合把示例代码组织成可复用的类，而不是散落的闭包。

设备先建好再进循环。把 await luma.createDevice(...) 放在 AnimationLoop 之前，能避免「device 为 null」导致的空绘制。需要延迟创建时，也可以传入设备的 Promise，循环会等待它。

引用本文

经纬志（2026）。《AnimationLoop》。https://www.jingweizhi.com/lumagl/api/animation-loop.html（访问日期 2026-11-03）。