GPU: Query API

include/SDL3/SDL_gpu.h

@@ -597,6 +597,20 @@ typedef struct SDL_GPUCopyPass SDL_GPUCopyPass;
  */
 typedef struct SDL_GPUFence SDL_GPUFence;
 
+/**
+ * An opaque handle representing a query pool.
+ *
+ * \since This struct is available since SDL 3.6.0.
+ *
+ * \sa SDL_CreateGPUQueryPool
+ * \sa SDL_ReleaseGPUQueryPool
+ * \sa SDL_BeginGPUQuery
+ * \sa SDL_EndGPUQuery
+ * \sa SDL_CopyGPUQueryResultsToBuffer
+ * \sa SDL_GetGPUTimestampFrequency
+ */
+typedef struct SDL_GPUQueryPool SDL_GPUQueryPool;
+
 /**
  * Specifies the primitive topology of a graphics pipeline.
  *
@@ -1370,6 +1384,20 @@ typedef enum SDL_GPUSwapchainComposition
     SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084
 } SDL_GPUSwapchainComposition;
 
+/**
+ * Specifies a kind of GPU Query.
+ *
+ * \since This enum is available since SDL 3.6.0.
+ *
+ * \sa SDL_CreateGPUQueryPool
+ */
+typedef enum SDL_GPUQueryType
+{
+    SDL_GPU_QUERY_TIMESTAMP,
+    SDL_GPU_QUERY_BINARY_OCCLUSION,
+    SDL_GPU_QUERY_PRECISE_OCCLUSION
+} SDL_GPUQueryType;
+
 /* Structures */
 
 /**
@@ -1816,6 +1844,21 @@ typedef struct SDL_GPUTransferBufferCreateInfo
     SDL_PropertiesID props;            /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
 } SDL_GPUTransferBufferCreateInfo;
 
+/**
+ * A structure specifying the parameters of a query pool.
+ *
+ * \since This struct is available since SDL 3.6.0.
+ *
+ * \sa SDL_CreateGPUQueryPool
+ */
+typedef struct SDL_GPUQueryPoolCreateInfo
+{
+    SDL_GPUQueryType type;   /**< The type of query intended to be used by the client. */
+    Uint32 query_count;      /**< The maximum number of queries in the pool. */
+
+    SDL_PropertiesID props;  /**< A properties ID for extensions. Should be 0 if no extensions are needed. */
+} SDL_GPUQueryPoolCreateInfo;
+
 /* Pipeline state structures */
 
 /**
@@ -4028,6 +4071,30 @@ extern SDL_DECLSPEC void SDLCALL SDL_DownloadFromGPUBuffer(
     const SDL_GPUBufferRegion *source,
     const SDL_GPUTransferBufferLocation *destination);
 
+/**
+ * Copies results of a GPU query to a buffer.
+ *
+ * This data is not guaranteed to be copied until the command buffer fence is
+ * signaled.
+ *
+ * After this function is called, the data in the query pool is no longer valid,
+ * so don't call this function multiple times before performing another query.
+ *
+ * \param copy_pass a copy pass handle.
+ * \param pool a query pool handle.
+ * \param first_query starting index of the queries to copy.
+ * \param count the number of queries to copy.
+ * \param destination the destination buffer and offset.
+ *
+ * \since This struct is available since SDL 3.6.0.
+ */
+extern SDL_DECLSPEC void SDLCALL SDL_CopyGPUQueryResultsToBuffer(
+    SDL_GPUCopyPass *copy_pass,
+    SDL_GPUQueryPool *pool,
+    Uint32 first_query,
+    Uint32 count,
+    SDL_GPUBufferLocation *destination);
+
 /**
  * Ends the current copy pass.
  *
@@ -4492,6 +4559,94 @@ extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUFence(
     SDL_GPUDevice *device,
     SDL_GPUFence *fence);
 
+/**
+ * Gets GPU timestamp frequency.
+ *
+ * Use this to compute wall clock times from timestamps.
+ *
+ * \param device a GPU context.
+ * \returns the number of nanoseconds required for a timestamp query to be incremented by 1.
+ *
+ * \since This function is available since SDL 3.6.0.
+ *
+ * \sa SDL_CreateGPUQueryPool
+ */
+extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetGPUTimestampFrequency(SDL_GPUDevice *device);
+
+/**
+ * Creates a query pool object to be used in queries.
+ *
+ * \param device a GPU context.
+ * \param createinfo a struct describing the state of the pool to create.
+ * \returns a query pool object on success, or NULL on failure; call
+ *          SDL_GetError() for more information.
+ *
+ * \since This function is available since SDL 3.6.0.
+ *
+ * \sa SDL_GetGPUTimestampFrequency
+ * \sa SDL_BeginGPUQuery
+ * \sa SDL_EndGPUQuery
+ * \sa SDL_CopyGPUQueryResultsToBuffer
+ * \sa SDL_ReleaseGPUQueryPool
+ */
+extern SDL_DECLSPEC SDL_GPUQueryPool * SDLCALL SDL_CreateGPUQueryPool(
+    SDL_GPUDevice *device,
+    SDL_GPUQueryPoolCreateInfo *createinfo);
+
+/**
+ * Begins a query on a command buffer.
+ *
+ * For timestamp queries, this will produce a timestamp as soon as all previous commands are taken by the command queue.
+ * Note that this means for timestamp queries you should use a different index from the one you use in SDL_EndGPUQuery.
+ *
+ * \param command_buffer a command buffer.
+ * \param pool a query pool.
+ * \param index the index within the pool for the query.
+ *
+ * \since This function is available since SDL 3.6.0.
+ *
+ * \sa SDL_EndGPUQuery
+ */
+extern SDL_DECLSPEC void SDLCALL SDL_BeginGPUQuery(
+    SDL_GPUCommandBuffer *command_buffer,
+    SDL_GPUQueryPool *pool,
+    Uint32 index);
+
+/**
+ * Ends a query on a command buffer.
+ *
+ * For timestamp queries, this will produce a timestamp as soon as all previous commands are finished in the command queue.
+ * Note that this means for timestamp queries you should use a different index from the one you used in SDL_BeginGPUQuery.
+ *
+ * \param command_buffer a command buffer.
+ * \param pool a query pool.
+ * \param index the index within the pool for the query.
+ *
+ * \since This function is available since SDL 3.6.0.
+ *
+ * \sa SDL_BeginGPUQuery
+ */
+extern SDL_DECLSPEC void SDLCALL SDL_EndGPUQuery(
+    SDL_GPUCommandBuffer *command_buffer,
+    SDL_GPUQueryPool *pool,
+    Uint32 index);
+
+/**
+ * Frees the given query pool as soon as it is safe to do so.
+ *
+ * You must not reference the query pool after calling this function.
+ *
+ * \param device a GPU context.
+ * \param pool a query pool.
+ *
+ * \since This function is available since SDL 3.6.0.
+ *
+ * \sa SDL_CreateGPUQueryPool
+ */
+extern SDL_DECLSPEC void SDLCALL SDL_ReleaseGPUQueryPool(
+    SDL_GPUDevice *device,
+    SDL_GPUQueryPool *pool);
+
 /* Format Info */
 
 /**