WebGPU timestamp-query Feature

The WebGPU

timestamp-query

feature is your power tool to get precise measurement about the GPU command execution times by recording timestamps before and after command execution. This allows you to analyze and optimize the performance of your GPU workloads (so you can squeeze every drop of power out of that GPU)!

You can't just use the

timestamp-query

feature out of the box - you have to do a few things first!

Before tryign to use the

timestamp-query

feature - you have to first enable it when requesting the device. This is important, as you can't use the timestamp queries in WebGPU, unless you enable this feature (otherwise you'll get an errors).

The modification to the

requestDevice(..)

call is shown below.

<?php
const device = await adapter.requestDevice({
  requiredFeatures: ["timestamp-query"],
});

const device = await adapter.requestDevice({
requiredFeatures: ["timestamp-query"],
});

Now you're ready to setup the queries.

The following gives you an example of setting up the query set - and the buffers for reading back the data (i.e., timing information).

<?php
const querySet = device.createQuerySet({
  type: 'timestamp',
  count: 2,
});

const queryResolveBuffer = device.createBuffer({
  size: 16, // 2 timestamps, each 64 bits (8 bytes)
  usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
});

const readBuffer = device.createBuffer({
  size: 16,
  usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
});

After this - you're ready to go! So in your render looop - you can call

writeTimestamp(..)

at the start and

writeTimestamp(..)

at the end - but within the

commandEncoder

- as it still needs to be executed by the GPU (calculate timing information and copy it back).

<?php
const commandEncoder = device.createCommandEncoder();

commandEncoder.writeTimestamp(querySet, 0);
const renderPass = commandEncoder.beginRenderPass(renderPassDescriptor);
renderPass.setPipeline(pipeline);
renderPass.setBindGroup(0, uniformBindGroup);
renderPass.draw(4, 1, 0, 0);
renderPass.end();
commandEncoder.writeTimestamp(querySet, 1);

// Resolve the query results to the resolve buffer
commandEncoder.resolveQuerySet(querySet, 0, 2, queryResolveBuffer, 0);
// Copy the results to the read buffer
commandEncoder.copyBufferToBuffer(queryResolveBuffer, 0, readBuffer, 0, 16);

device.queue.submit([commandEncoder.finish()]);

await device.queue.onSubmittedWorkDone();

const commandEncoder = device.createCommandEncoder();

commandEncoder.writeTimestamp(querySet, 0);
const renderPass = commandEncoder.beginRenderPass(renderPassDescriptor);
renderPass.setPipeline(pipeline);
renderPass.setBindGroup(0, uniformBindGroup);
renderPass.draw(4, 1, 0, 0);
renderPass.end();
commandEncoder.writeTimestamp(querySet, 1);

// Resolve the query results to the resolve buffer
commandEncoder.resolveQuerySet(querySet, 0, 2, queryResolveBuffer, 0);
// Copy the results to the read buffer
commandEncoder.copyBufferToBuffer(queryResolveBuffer, 0, readBuffer, 0, 16);

device.queue.submit([commandEncoder.finish()]);

await device.queue.onSubmittedWorkDone();

After the work on the GPU has finished - you just copy it back and use it for analysis - for example - we calculate the fps and display it on the window - to see what is the maximum FPS.

<?php
await readBuffer.mapAsync(GPUMapMode.READ);
const mappedRange = readBuffer.getMappedRange();
const timestamps = new BigUint64Array(mappedRange);

const startTime = Number(timestamps[0]);
const endTime = Number(timestamps[1]);
const timeTakenNs = endTime - startTime;

const timeTakenMs = timeTakenNs / 1000000;
const maxFPS = 1000 / timeTakenMs;

console.log(`Time taken: ${timeTakenMs.toFixed(2)} ms`);
console.log(`Maximum FPS: ${maxFPS.toFixed(2)} fps`);

// Unmap the buffer after reading the data
readBuffer.unmap();

await readBuffer.mapAsync(GPUMapMode.READ);
const mappedRange = readBuffer.getMappedRange();
const timestamps = new BigUint64Array(mappedRange);

const startTime = Number(timestamps[0]);
const endTime = Number(timestamps[1]);
const timeTakenNs = endTime - startTime;

const timeTakenMs = timeTakenNs / 1000000;
const maxFPS = 1000 / timeTakenMs;

console.log(`Time taken: ${timeTakenMs.toFixed(2)} ms`);
console.log(`Maximum FPS: ${maxFPS.toFixed(2)} fps`);

// Unmap the buffer after reading the data
readBuffer.unmap();

Below in the resources shows a complete example - where were implement a ray-tracer - which renders 16,000+ triangles using an octree structure (in real-time). We use the `timing-query` to give us the GPUs possible timing information (so we can display the maximum FPS - which should be greater than 60fps if we are expecting real-time performance).