1// Copyright 2021-2023 The Khronos Group Inc.
2//
3// SPDX-License-Identifier: CC-BY-4.0
4
5= VK_EXT_primitives_generated_query
6:toc: left
7:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/
8:sectnums:
9
10This proposal regards layering OpenGL over Vulkan, and provides a convenience
11query for use by such layers.
12
13== Problem Statement
14
15In OpenGL, the `GL_PRIMITIVES_GENERATED` query can be used independently from
16whether transform feedback is active or not.
17There is no direct equivalent in Vulkan.
18
19This extension provides a simple and efficient way to implement this OpenGL
20query on top of Vulkan.
21
22== Solution Space
23
24=== Emulation Through Other Vulkan Queries
25
26In Vulkan, the second result from the
27`VK_QUERY_TYPE_TRANSFORM_FEEDBACK_STREAM_EXT` query produces the same value as
28OpenGL's `GL_PRIMITIVES_GENERATED` query.
29However, this can only be used when transform feedback is active, and thus is
30not suitable.
31
32The result of `VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT` from the
33`VK_QUERY_TYPE_PIPELINE_STATISTICS` query also produces the same result.
34Support for this query implies support for a number of other statistics that
35are not universally available, and so the `pipelineStatisticsQuery` feature is
36often not available on Android devices.
37Furthermore, emulating `GL_PRIMITIVES_GENERATED` and
38`GL_CLIPPING_INPUT_PRIMITIVES_ARB` through the same Vulkan query creates
39unnecessary complications, given that only one query of each type can be active
40at a time in Vulkan.
41
42=== A New Query Type
43
44A new Vulkan query type can be introduced to provide identical results to
45OpenGL's `GL_PRIMITIVES_GENERATED` query.
46There are a number of limitations to address:
47
48- Similarly to `VK_QUERY_PIPELINE_STATISTIC_CLIPPING_INVOCATIONS_BIT`, as
49  stated by the Vulkan spec, if `rasterizerDiscardEnable` is enabled the query
50  may not produce valid results on some hardware.
51- Some hardware cannot produce a valid value when a non-zero transform feedback
52  stream is used (i.e.
53  `VkPipelineRasterizationStateStreamCreateInfoEXT::rasterizationStream` is not
54  zero).
55
56This solution is adopted for this problem.
57
58== Proposal
59
60A new query type is added, namely `VK_QUERY_TYPE_PRIMITIVES_GENERATED_EXT`,
61that behaves identically to the OpenGL `GL_PRIMITIVES_GENERATED` query.
62
63=== Features
64
65[source,c]
66----
67typedef struct VkPhysicalDevicePrimitivesGeneratedQueryFeaturesEXT {
68    VkStructureType    sType;
69    void*              pNext;
70    VkBool32           primitivesGeneratedQuery;
71    VkBool32           primitivesGeneratedQueryWithRasterizerDiscard;
72    VkBool32           primitivesGeneratedQueryWithNonZeroStreams;
73} VkPhysicalDevicePrimitivesGeneratedQueryFeaturesEXT;
74----
75
76- `primitivesGeneratedQuery` specifies if the query is usable.
77- If `primitivesGeneratedQueryWithRasterizerDiscard` is false, then rasterizer
78  discard (through
79  `VkPipelineRasterizationStateCreateInfo::rasterizerDiscardEnable` or
80  equivalent dynamic state) must not be enabled.
81- If `primitivesGeneratedQueryWithNonZeroStreams` is false, the query cannot be
82  used in conjunction with non-zero transform feedback streams.
83
84On hardware where `primitivesGeneratedQueryWithRasterizerDiscard` is not
85available, the OpenGL layer can discard the rasterization result by some other
86means; for example by using an empty scissor.
87
88On hardware where `primitivesGeneratedQueryWithNonZeroStreams` is not
89available, the transform feedback query can be used for non-zero streams since
90transform feedback is necessarily active.
91This is nonetheless not a concern for OpenGL layers as non-zero transform
92feedback streams are not supported in OpenGL.
93