Automatic timestamp queries on pipelines

[reczkok]

Proposal: Enhanced Timestamp Querying for GPU Pass Performance Profiling

Overview

Profiling the performance of compute and render passes is essential for GPU optimization. However, the current vanilla WebGPU approach for timestamp queries is cumbersome and error-prone. It requires developers to manually create a QuerySet and two buffers—one for query resolution and another for reading—due to incompatible usage flags.

Current Implementation

In vanilla WebGPU, timing a pass involves the following manual steps:

device.createQuerySet({
  type: 'timestamp',
  count: 2,
});
device.createBuffer({
  size: BigInt64Array.BYTES_PER_ELEMENT * 2,
  usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.QUERY_RESOLVE,
});
device.createBuffer({
  size: BigInt64Array.BYTES_PER_ELEMENT * 2,
  usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
});

Developers must also inject timestamp properties into the pass descriptor and resolve the query set post-pass. Given that pass durations are typically shorter than the overhead of GPU-host communication, reading the timestamp after every pass becomes impractical.

Proposed Solutions

To streamline this process and improve developer experience, we propose two potential approaches:

1. High-Level API: withPerformanceListener

Introduce a method that encapsulates the entire timestamp querying process:

withPerformanceListener(listener: (time: number) => void /* or bigint for nanosecond precision */)

Key Features:

• Automated Setup: Internally creates the QuerySet and both required buffers, manages the injection of timestamp queries into the pass descriptor, and resolves the queries.
• Asynchronous Callback: The provided listener is invoked as soon as the read buffer is available, delivering the performance data with minimal delay.
• Optional Rate Limiting: Allows throttling of query reads to balance precision with GPU-host communication overhead.

2. Lower-Level Abstraction: TgpuQuerySet

Alternatively, we could develop an abstraction—TgpuQuerySet—that closely mirrors the native WebGPU API. This approach preserves familiarity while reducing boilerplate:

const querySet = root.createQuerySet({
  type: 'timestamp',
  count: 2,
});

pipeline
  // ... pipeline configuration
  .withTimestampQuery(querySet) // optionally accepts a descriptor with sensible defaults
  .dispatchWorkgroups(...);

const data = await querySet.read(); // returns timestamp data (bigint)

Advantages:

• API Consistency: Retains a design similar to existing WebGPU buffers, making it easier for developers to adopt.
• Flexibility: Provides fine-grained control over timestamp queries while still abstracting away repetitive boilerplate.
• Seamless Integration: Simplifies incorporation into existing pipelines with minimal disruption.

[reczkok]

@mhawryluk @iwoplaza @aleksanderkatan what do you think?

[aleksanderkatan]

I like the idea, I have no strong preference between option 1 and option 2

[mhawryluk]

I like the proposal. I think for this usage a high level abstraction makes sense, so I would go for option no. 1