DirectX Graphics API Documentation

Windows API Reference | d3d11

D3D11_QUERY_DATA_TIMESTAMP Structure

Namespace: d3d11

Header: d3d11_query.h

Syntax

typedef struct D3D11_QUERY_DATA_TIMESTAMP {
    UINT64  Timestamp;
} D3D11_QUERY_DATA_TIMESTAMP;

Members

Member Description
Timestamp A 64-bit unsigned integer that contains the timestamp value. This value is in GPU clock cycles.

Remarks

This structure is used by the D3D11_QUERY_TIMESTAMP query type. A timestamp query captures the current value of the GPU's internal clock at the time the query is issued.

Timestamps are useful for performance analysis and measuring the duration of specific GPU operations. The timestamp value is not absolute; it's a relative measure of GPU clock cycles.

To use timestamp queries, you typically:

  1. Create a query object of type D3D11_QUERY_TIMESTAMP.
  2. Call ID3D11DeviceContext::Begin to start the timing.
  3. Execute the GPU operations you want to time.
  4. Call ID3D11DeviceContext::End to stop the timing.
  5. Call ID3D11DeviceContext::GetData to retrieve the timestamp values. You'll need to retrieve two values: one from the End call and one from the Begin call (or vice versa, depending on how you structure your retrieval).
  6. Subtract the start timestamp from the end timestamp to get the duration in GPU clock cycles.
  7. To convert this duration to a meaningful time unit (like seconds), you need to know the GPU's clock frequency, which can be obtained from ID3D11Device::CheckFeatureSupport with D3D11_FEATURE_D3D11_OPTIONS5 and checking the FlippingRawValueInGpuTimestampFrequency member.

See Also

D3D11 Structures
Direct3D 11 Structures

Example

The following C++ code snippet demonstrates how to use timestamp queries:


#include <d3d11.h>
#include <dxgi.h>
#include <wrl.h> // For Microsoft::WRL::ComPtr

// Assume pDeviceContext is a valid ID3D11DeviceContext*

Microsoft::WRL::ComPtr<ID3D11Query> pTimestampQuery;
D3D11_QUERY_DESC timestampQueryDesc;
timestampQueryDesc.Type = D3D11_QUERY_TIMESTAMP;
timestampQueryDesc.MiscFlags = 0;

if (FAILED(pDeviceContext->CreateQuery(&timestampQueryDesc, &pTimestampQuery)))
{
    // Handle error
    return;
}

// Begin timing
pDeviceContext->End(pTimestampQuery.Get());

// ... perform GPU work ...

// End timing
pDeviceContext->End(pTimestampQuery.Get());

// Retrieve data
D3D11_QUERY_DATA_TIMESTAMP timestampData;
UINT64 startTime = 0;
UINT64 endTime = 0;

// Repeatedly call GetData until data is available
while (pDeviceContext->GetData(pTimestampQuery.Get(), &timestampData, sizeof(timestampData), 0) == S_FALSE)
{
    // Wait or do other work
}
startTime = timestampData.Timestamp;

// Retrieve the second timestamp
while (pDeviceContext->GetData(pTimestampQuery.Get(), &timestampData, sizeof(timestampData), 0) == S_FALSE)
{
    // Wait or do other work
}
endTime = timestampData.Timestamp;

// Calculate duration in GPU clock cycles
if (endTime >= startTime)
{
    UINT64 gpuDurationCycles = endTime - startTime;

    // You would typically need the GPU frequency to convert to seconds
    // float gpuFrequencyHz = ...; // obtained via CheckFeatureSupport
    // float durationSeconds = static_cast<float>(gpuDurationCycles) / gpuFrequencyHz;
}

Note

The actual availability and precision of timestamps depend on the GPU hardware and driver. Not all hardware supports precise timestamping.