Skip to content

[Feat] Per-draw CPU/GPU timings from Deck #10777

Open

Description

@akre54

Target Use Case

Apps that tune layer density or level of detail need per-draw render cost from deck.gl. Today metrics.gpuTime is a one-second aggregate that requires deviceProps.debugGPUTime, and it cannot be attributed to individual draws.

Proposal

Add an experimental, opt-in Deck prop that reports CPU time and, when the device supports 'timestamp-query', GPU time for each draw:

new Deck({
  deviceProps: {optionalFeatures: ['timestamp-query']},
  _onFrameTimings: ({cpuMs, gpuMs}) => console.log(cpuMs, gpuMs)
});

When the prop is not set, no query sets are created. gpuMs is omitted when timestamp queries are unavailable or fail.

Measurement contract

A sample covers one Deck draw operation, not an individual layer or GPU draw command. A standalone frame normally produces one sample; interleaved Mapbox/MapLibre rendering may produce several layer-group samples per displayed frame.

  • cpuMs covers renderLayers, including effect passes. It excludes layer updates, picking, widgets, timestamp readback and the callback itself.
  • gpuMs spans the first through last layers render pass, potentially including gaps. It excludes effect pre/post-render passes and is not a sum of pass durations.
  • Samples with GPU readback arrive asynchronously; CPU-only samples without a GPU query arrive synchronously. Samples can arrive out of draw order. The initial callback has no frame identifier, so consumers must not pair samples to frames by callback order. Exact frame correlation would require a separately specified identifier.
  • Unsupported, failed, or skipped GPU measurements omit gpuMs. Multi-canvas draws and WebGL draws with luma's debug GPU profiler are CPU-only. Interrupted draws produce no sample, and finalization suppresses pending callbacks.
  • Disabled instrumentation creates no timing query sets. Enabled instrumentation has overhead, including asynchronous query readback that is excluded from cpuMs.

Implementation and detailed API documentation: #10778.

Activity

  1. akre54 commented on Oct 1, 2026

    @akre54
    CollaboratorAuthor

    Contract update from review of #10778: the fields are now cpuTime/gpuTime (matching DeckMetrics), and gpuTime is the sum of per-pass GPU durations instead of the span from the first pass to the last, so idle time between passes is not counted. Multi-canvas draws are now GPU timed too. GPU time is omitted (CPU-only samples) whenever luma's debug GPU timer is active, on both WebGL and WebGPU.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions