Query API: Pipeline Statistics Query - #691

The results returned by pipeline statistics query will be the number of vertex shader invocations, the number of primitives sent to the clip stage, the number of primitives out by the clip stage, the number of fragment shader invocations, the number of compute shader invocations in order.

Because all query data stored in the QuerySet will be resolved into a buffer, we just copy the common parts supported by all backends to the destination buffer, so if we want to expand the results, just add the corresponding copy items.

For usage scenarios, we can use these pipeline statistics results to measure the relative complexity of different parts of applications, which can help to find bottlenecks while performance tuning.

The results returned by pipeline statistics query will be the number of vertex shader invocations, the number of primitives sent to the clip stage, the number of primitives out by the clip stage, the number of fragment shader invocations, the number of compute shader invocations in order.

Because all query data stored in the QuerySet will be resolved into a buffer, we just copy the common parts supported by all backends to the destination buffer, so if we want to expand the results, just add the corresponding copy items.

Yes, the question to know in which order they are written in the buffer when you resolve the query, and with what format (u64, u32). The other question is that right now only a few, say 4, of the pipeline statistics can be non-zero. But tomorrow, for example when WebGPU gain tessellation shaders, where are we going to write the additional data? It will be weird to users if without doing anything the amount of data written increases.

On Vulkan, it allows users to decide which data of pipeline statistics to query by setting VkQueryPoolCreateInfo::pipelineStatistics when creating query sets (always querying all pipeline statistics data on D3D12 and Metal), maybe we can add a GPUPipelineStatisticFlags in GPUQuerySetDescriptor such as:

dictionary GPUQuerySetDescriptor : GPUObjectDescriptorBase {
    required GPUQueryType type;
    required GPUSize32 count;
    GPUPipelineStatisticFlags pipelineStatistics;
};

typedef [EnforceRange] unsigned long GPUPipelineStatisticFlags;
interface GPUPipelineStatisticBit {
    const GPUPipelineStatisticFlags VERTEX_SHADER_INVOCATIONS   = 0x01;
    const GPUPipelineStatisticFlags CLIPPER_INVOCATIONS         = 0x02;
    const GPUPipelineStatisticFlags CLIPPER_PRIMITIVES_OUT      = 0x04;
    const GPUPipelineStatisticFlags FRAGMENT_SHADER_INVOCATIONS = 0x08;
    const GPUPipelineStatisticFlags COMPUTE_SHADER_INVOCATIONS  = 0x10;
};

That addresses part of the question, which is how we could deal with extensibility. But the other part is, can you describe what format and in which order will the different statistics be returned depending on that flag?

For example if I ask a pipeline statistic query with VERTEX_SHADER_INVOCATIONS | FRAGMENT_SHADER_INVOCATIONS, which of these formats will be the one I can use to read data in shaders from the resolve buffer?

struct Statistics {
    vertexShaderInvocations : u32; // or u64?
    fragmentShaderInvocations : u32;
}

struct Statistics {
    fragmentShaderInvocations : u32;
    vertexShaderInvocations : u32;
}

struct Statistics {
    vertexShaderInvocations : u32;
    clipperInvocations : u32; // unused
    clipperPrimitives : u32; // unused
    fragmentShaderInvocations : u32;
    computeShaderInvocations : u32; // unused
}

For example if I ask a pipeline statistic query with VERTEX_SHADER_INVOCATIONS | FRAGMENT_SHADER_INVOCATIONS, which of these formats will be the one I can use to read data in shaders from the resolve buffer?

The results in the resolve buffer will be stpred in the first format:

struct Statistics {
    vertexShaderInvocations : u64
    fragmentShaderInvocations : u64;
}

Only the pipeline statistics of the specified flags will be wrote to resolve buffer, and the order of results is not affected by the order of flags, it will always write in this order:

struct Statistics {
    vertexShaderInvocations : u64;
    clipperInvocations : u64; 
    clipperPrimitives : u64;
    fragmentShaderInvocations : u64;
    computeShaderInvocations : u64;
}

which does the same with Vulkan.
If we set GPUQuerySetDescriptor.pipelineStatistics=0, only a zero value is wrote to the buffer.

Do I need to add these notes to the PR now?

Thanks, we need to have at least the IDL for GPUPipelineStatisticBit and an explanation of what's in the resolve buffer, even if it isn't a proper spec. Other parts of the API are mostly self-explanatory for people who know other APIs, but not this, so it's worth having the description as soon as the IDL is introduced.

@kainino0x @kvark @JusSn, @haoxli addressed all comments, can this be merged?

Would be nice to get a thumbs up from Apple or Microsoft.

@litherum, @RafaelCintron Do you have any comments about pipeline statistics queries?