Add occlusion query support (QueryPool, RenderPass, CopyPass)

Adds QueryPool plus RenderPass::beginQuery/endQuery and
CopyPass::downloadQueryResults, wrapping a prototype SDL_gpu
occlusion/timestamp query API that isn't upstream yet. The types and
methods are always declared; their implementations are no-ops when
the linked SDL3 doesn't define SDL_GPU_OCCLUSION_QUERY, so client
code (e.g. Quetoo) can use occlusion queries unconditionally and get
silent, correct degradation rather than a build-time dependency on
an unmerged SDL API.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: jdolan

Examples/Hello.c

@@ -93,6 +93,13 @@ typedef struct {
    * @brief The @c Scene.
    */
   Scene scene;
+
+  /**
+   * @brief Occlusion query proof-of-concept: pool, readback buffer, and frame counter.
+   */
+  QueryPool *occlusionQueryPool;
+  SDL_GPUTransferBuffer *occlusionQueryTransfer;
+  Uint32 frames;
 } AppState;
 
 static AppState application;
@@ -213,10 +220,39 @@ static void drawScene(AppState *app, CommandBuffer *commands) {
   RenderPass *pass = $(commands, beginRenderPass, &color, 1, &depth);
   $(pass, bindPipeline, scene->pipeline);
   $(pass, bindVertexBuffers, 0, &(SDL_GPUBufferBinding) { .buffer = scene->vertexBuffer->buffer }, 1);
+  $(pass, beginQuery, app->occlusionQueryPool, 0);
   $(pass, drawPrimitives, (Uint32) SDL_arraysize(vertices), 1, 0, 0);
+  $(pass, endQuery, app->occlusionQueryPool, 0);
   release(pass);
 }
 
+/**
+ * @brief Occlusion query proof-of-concept: downloads and logs this frame's result.
+ * @details A real application would defer the readback to a later frame instead
+ *   of blocking on the GPU like this. When occlusion queries are unsupported by
+ *   the linked SDL3, this always reports a "not occluded" sentinel value.
+ */
+static void logOcclusionQueryResult(AppState *app) {
+
+  CommandBuffer *commands = $(app->renderDevice, acquireCommandBuffer);
+
+  CopyPass *copyPass = $(commands, beginCopyPass);
+  $(copyPass, downloadQueryResults, app->occlusionQueryPool, 0, 1, &(SDL_GPUTransferBufferLocation) {
+    .transfer_buffer = app->occlusionQueryTransfer,
+  });
+  release(copyPass);
+
+  SDL_GPUFence *fence = $(commands, submitAndFence);
+  release(commands);
+
+  $(app->renderDevice, waitForFences, true, &fence, 1);
+  $(app->renderDevice, releaseFence, fence);
+
+  const Uint64 *result = $(app->renderDevice, mapTransferBuffer, app->occlusionQueryTransfer, false);
+  SDL_Log("Occlusion query result: %" SDL_PRIu64 " samples passed", *result);
+  $(app->renderDevice, unmapTransferBuffer, app->occlusionQueryTransfer);
+}
+
 #pragma mark - SDL application callbacks
 
 /**
@@ -254,6 +290,16 @@ SDL_AppResult SDL_AppInit(void **appState, int argc, char *argv[]) {
 
   initScene(app);
 
+  app->occlusionQueryPool = $(app->renderDevice, createQueryPool, &(SDL_GPUQueryPoolCreateInfo) {
+    .type = SDL_GPU_QUERY_PRECISE_OCCLUSION,
+    .query_count = 1,
+  });
+
+  app->occlusionQueryTransfer = $(app->renderDevice, createTransferBuffer, &(SDL_GPUTransferBufferCreateInfo) {
+    .usage = SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD,
+    .size = sizeof(Uint64),
+  });
+
   return SDL_APP_CONTINUE;
 }
 
@@ -268,6 +314,10 @@ SDL_AppResult SDL_AppIterate(void *appState) {
   if (commands) {
     drawScene(app, commands);
     $(app->renderDevice, endFrame);
+
+    if ((app->frames++ % 60) == 0) {
+      logOcclusionQueryResult(app);
+    }
   }
 
   return SDL_APP_CONTINUE;
@@ -298,6 +348,9 @@ void SDL_AppQuit(void *appState, SDL_AppResult result) {
   release(app->scene.pipeline);
   release(app->scene.vertexBuffer);
 
+  release(app->occlusionQueryPool);
+  $(app->renderDevice, releaseTransferBuffer, app->occlusionQueryTransfer);
+
   release(app->framebuffer);
   release(app->renderDevice);
 

ObjectivelyGPU.xcodeproj/project.pbxproj

@@ -55,6 +55,8 @@
 		CEBA3F772FF3418E00758CA6 /* Objectively.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = CEA0030000000000000000F0 /* Objectively.framework */; };
 		CEBA3F782FF3419100758CA6 /* ObjectivelyGPU.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 6251F22589273797656C269E /* ObjectivelyGPU.framework */; };
 		CECF83982FEF6A7200CB0CCA /* Mathlib.h in Headers */ = {isa = PBXBuildFile; fileRef = CECF83972FEF6A7200CB0CCA /* Mathlib.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		496C55EEAC4C86E3B7C6550E /* QueryPool.h in Headers */ = {isa = PBXBuildFile; fileRef = 989E64805790578A941CB5B9 /* QueryPool.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		45AD38AB8109398E51564CFD /* QueryPool.c in Sources */ = {isa = PBXBuildFile; fileRef = 872CC6C6CBA08F1A36626F57 /* QueryPool.c */; };
 		CECF83B62FEF765400CB0CCA /* Hello.frag.metal in CopyFiles */ = {isa = PBXBuildFile; fileRef = CECF83A52FEF712F00CB0CCA /* Hello.frag.metal */; };
 		CECF83B72FEF765400CB0CCA /* Hello.frag.spv in CopyFiles */ = {isa = PBXBuildFile; fileRef = CECF83A62FEF712F00CB0CCA /* Hello.frag.spv */; };
 		CECF83B92FEF765400CB0CCA /* Hello.vert.metal in CopyFiles */ = {isa = PBXBuildFile; fileRef = CECF83A82FEF712F00CB0CCA /* Hello.vert.metal */; };
@@ -182,6 +184,8 @@
 		CECF83952FEF65FF00CB0CCA /* Makefile.am */ = {isa = PBXFileReference; lastKnownFileType = text; path = Makefile.am; sourceTree = "<group>"; };
 		CECF83962FEF65FF00CB0CCA /* ObjectivelyGPU.pc.in */ = {isa = PBXFileReference; lastKnownFileType = text; path = ObjectivelyGPU.pc.in; sourceTree = "<group>"; };
 		CECF83972FEF6A7200CB0CCA /* Mathlib.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = Mathlib.h; sourceTree = "<group>"; };
+		989E64805790578A941CB5B9 /* QueryPool.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = QueryPool.h; sourceTree = "<group>"; };
+		872CC6C6CBA08F1A36626F57 /* QueryPool.c */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.c; path = QueryPool.c; sourceTree = "<group>"; };
 		CECF83A32FEF6F5B00CB0CCA /* Makefile.am */ = {isa = PBXFileReference; lastKnownFileType = text; path = Makefile.am; sourceTree = "<group>"; };
 		CECF83A42FEF712F00CB0CCA /* Hello.frag.glsl */ = {isa = PBXFileReference; lastKnownFileType = text; path = Hello.frag.glsl; sourceTree = "<group>"; };
 		CECF83A52FEF712F00CB0CCA /* Hello.frag.metal */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.metal; path = Hello.frag.metal; sourceTree = "<group>"; };
@@ -306,6 +310,8 @@
 				CEBA3F652FF3211F00758CA6 /* GraphicsPipeline.h */,
 				CEBA3F662FF3211F00758CA6 /* GraphicsPipeline.c */,
 				CECF83972FEF6A7200CB0CCA /* Mathlib.h */,
+				989E64805790578A941CB5B9 /* QueryPool.h */,
+				872CC6C6CBA08F1A36626F57 /* QueryPool.c */,
 				9220C57BBAA3C951D8083799 /* RenderDevice.h */,
 				77315F9BC357C97B885E883C /* RenderDevice.c */,
 				206D63692B601BD90F377BF5 /* RenderPass.h */,
@@ -397,6 +403,7 @@
 				CECF83C72FF03A3500CB0CCA /* Framebuffer.h in Headers */,
 				CEBA3F6B2FF3211F00758CA6 /* GraphicsPipeline.h in Headers */,
 				CECF83982FEF6A7200CB0CCA /* Mathlib.h in Headers */,
+				496C55EEAC4C86E3B7C6550E /* QueryPool.h in Headers */,
 				A09AD953AC672E0DE9D1E26D /* ObjectivelyGPU.h in Headers */,
 				59897FC7BCC194032E971A9B /* RenderDevice.h in Headers */,
 				683F683E23149C267D613EA0 /* RenderPass.h in Headers */,
@@ -579,6 +586,7 @@
 				CCCB11DB70E4A962360A2119 /* CopyPass.c in Sources */,
 				CECF83C82FF03A3500CB0CCA /* Framebuffer.c in Sources */,
 				CEBA3F702FF3211F00758CA6 /* GraphicsPipeline.c in Sources */,
+				45AD38AB8109398E51564CFD /* QueryPool.c in Sources */,
 				CEBA3F732FF3211F00758CA6 /* Sampler.c in Sources */,
 				CEBA3F722FF3211F00758CA6 /* Shader.c in Sources */,
 				86E5132F5DCCB6B674151343 /* RenderDevice.c in Sources */,

Sources/ObjectivelyGPU/CopyPass.c

@@ -26,6 +26,7 @@
 
 #include "CommandBuffer.h"
 #include "CopyPass.h"
+#include "QueryPool.h"
 #include "RenderDevice.h"
 
 #define _Class _CopyPass
@@ -83,6 +84,32 @@ static void downloadTexture(const CopyPass *self, const SDL_GPUTextureRegion *sr
   SDL_DownloadFromGPUTexture(self->pass, src, dst);
 }
 
+/**
+ * @fn void CopyPass::downloadQueryResults(const CopyPass *self, QueryPool *pool, Uint32 firstQuery, Uint32 count, const SDL_GPUTransferBufferLocation *dst)
+ * @memberof CopyPass
+ */
+static void downloadQueryResults(const CopyPass *self, QueryPool *pool, Uint32 firstQuery, Uint32 count, const SDL_GPUTransferBufferLocation *dst) {
+
+  assert(pool);
+
+#ifdef SDL_GPU_OCCLUSION_QUERY
+  if (pool->pool) {
+    SDL_DownloadGPUQueryResults(self->pass, pool->pool, firstQuery, count, (SDL_GPUTransferBufferLocation *) dst);
+    return;
+  }
+#endif
+
+  // Occlusion queries are unsupported: no GPU work will ever populate `dst`, so
+  // write a "not occluded" sentinel for every requested result directly, rather
+  // than leaving the destination uninitialized (which callers would likely
+  // misread as "occluded", incorrectly culling everything).
+  Uint64 *results = $(self->commands->device, mapTransferBuffer, dst->transfer_buffer, false);
+  for (Uint32 i = 0; i < count; i++) {
+    results[(dst->offset / sizeof(Uint64)) + i] = 1;
+  }
+  $(self->commands->device, unmapTransferBuffer, dst->transfer_buffer);
+}
+
 /**
  * @fn CopyPass *CopyPass::init(CopyPass *self, CommandBuffer *commands, SDL_GPUCopyPass *pass)
  * @memberof CopyPass
@@ -159,6 +186,7 @@ static void initialize(Class *clazz) {
   ((CopyPassInterface *) clazz->interface)->copyTextureToTexture = copyTextureToTexture;
   ((CopyPassInterface *) clazz->interface)->downloadBuffer = downloadBuffer;
   ((CopyPassInterface *) clazz->interface)->downloadTexture = downloadTexture;
+  ((CopyPassInterface *) clazz->interface)->downloadQueryResults = downloadQueryResults;
   ((CopyPassInterface *) clazz->interface)->init = init;
   ((CopyPassInterface *) clazz->interface)->uploadBuffer = uploadBuffer;
   ((CopyPassInterface *) clazz->interface)->uploadData = uploadData;

Sources/ObjectivelyGPU/CopyPass.h

@@ -35,6 +35,7 @@
 typedef struct CommandBuffer CommandBuffer;
 typedef struct CopyPass CopyPass;
 typedef struct CopyPassInterface CopyPassInterface;
+typedef struct QueryPool QueryPool;
 
 /**
  * @brief A scoped copy pass for uploading CPU data and copying GPU resources.
@@ -121,6 +122,17 @@ struct CopyPassInterface {
    */
   void (*downloadTexture)(const CopyPass *self, const SDL_GPUTextureRegion *src, const SDL_GPUTextureTransferInfo *dst);
 
+  /**
+   * @fn void CopyPass::downloadQueryResults(const CopyPass *self, QueryPool *pool, Uint32 firstQuery, Uint32 count, const SDL_GPUTransferBufferLocation *dst)
+   * @brief Downloads a range of query results to a CPU-accessible transfer buffer.
+   * @details Each result is a `Uint64`, laid out contiguously starting at @p dst.
+   *   When @p pool is backed by an unsupported SDL3 build, every result is
+   *   reported as "not occluded" (nonzero) rather than left uninitialized; see
+   *   `QueryPool`.
+   * @memberof CopyPass
+   */
+  void (*downloadQueryResults)(const CopyPass *self, QueryPool *pool, Uint32 firstQuery, Uint32 count, const SDL_GPUTransferBufferLocation *dst);
+
   /**
    * @fn CopyPass *CopyPass::init(CopyPass *self, CommandBuffer *commands, SDL_GPUCopyPass *pass)
    * @brief Initializes this CopyPass wrapping the given SDL copy pass.

Sources/ObjectivelyGPU/Makefile.am

@@ -15,6 +15,7 @@ pkginclude_HEADERS = \
     Framebuffer.h \
     GraphicsPipeline.h \
     Mathlib.h \
+    QueryPool.h \
     RenderDevice.h \
     RenderPass.h \
     Sampler.h \
@@ -32,6 +33,7 @@ libObjectivelyGPU_la_SOURCES = \
     CopyPass.c \
     Framebuffer.c \
     GraphicsPipeline.c \
+    QueryPool.c \
     RenderDevice.c \
     RenderPass.c \
     Sampler.c \

Sources/ObjectivelyGPU/QueryPool.c

@@ -0,0 +1,115 @@
+/*
+ * ObjectivelyGPU: Object oriented graphics framework for SDL3 and C.
+ * Copyright (C) 2026 Jay Dolan <jay@jaydolan.com>
+ *
+ * This software is provided 'as-is', without any express or implied
+ * warranty. In no event will the authors be held liable for any damages
+ * arising from the use of this software.
+ *
+ * Permission is granted to anyone to use this software for any purpose,
+ * including commercial applications, and to alter it and redistribute it
+ * freely, subject to the following restrictions:
+ *
+ * 1. The origin of this software must not be misrepresented; you must not
+ * claim that you wrote the original software. If you use this software
+ * in a product, an acknowledgment in the product documentation would be
+ * appreciated but is not required.
+ *
+ * 2. Altered source versions must be plainly marked as such, and must not be
+ * misrepresented as being the original software.
+ *
+ * 3. This notice may not be removed or altered from any source distribution.
+ */
+
+#include <assert.h>
+
+#include "QueryPool.h"
+#include "RenderDevice.h"
+
+#define _Class _QueryPool
+
+#pragma mark - Object
+
+/**
+ * @see Object::dealloc(Object *)
+ */
+static void dealloc(Object *self) {
+
+  QueryPool *this = (QueryPool *) self;
+
+  if (this->device) {
+#ifdef SDL_GPU_OCCLUSION_QUERY
+    if (this->pool) {
+      SDL_ReleaseGPUQueryPool(this->device->device, this->pool);
+    }
+#endif
+    release(this->device);
+  }
+
+  super(Object, self, dealloc);
+}
+
+#pragma mark - QueryPool
+
+/**
+ * @fn QueryPool *QueryPool::initWithDevice(QueryPool *self, RenderDevice *device, const SDL_GPUQueryPoolCreateInfo *info)
+ * @memberof QueryPool
+ */
+static QueryPool *initWithDevice(QueryPool *self, RenderDevice *device, const SDL_GPUQueryPoolCreateInfo *info) {
+
+  assert(device);
+  assert(info);
+
+  self = (QueryPool *) super(Object, self, init);
+  if (self) {
+
+    self->device = retain(device);
+    self->type = info->type;
+    self->queryCount = info->query_count;
+
+#ifdef SDL_GPU_OCCLUSION_QUERY
+    self->pool = SDL_CreateGPUQueryPool(device->device, (SDL_GPUQueryPoolCreateInfo *) info);
+    GPU_Assert(self->pool, "SDL_CreateGPUQueryPool");
+#else
+    self->pool = NULL; // Occlusion queries are not supported by this SDL_gpu build.
+#endif
+  }
+
+  return self;
+}
+
+#pragma mark - Class lifecycle
+
+/**
+ * @see Class::initialize(Class *)
+ */
+static void initialize(Class *clazz) {
+
+  ((ObjectInterface *) clazz->interface)->dealloc = dealloc;
+
+  ((QueryPoolInterface *) clazz->interface)->initWithDevice = initWithDevice;
+}
+
+/**
+ * @fn Class *QueryPool::_QueryPool(void)
+ * @memberof QueryPool
+ */
+Class *_QueryPool(void) {
+  static Class *clazz;
+  static Once once;
+
+  do_once(&once, {
+    clazz = _initialize(&(const ClassDef) {
+      .name            = "QueryPool",
+      .superclass      = _Object(),
+      .instanceSize    = sizeof(QueryPool),
+      .interfaceOffset = offsetof(QueryPool, interface),
+      .interfaceSize   = sizeof(QueryPoolInterface),
+      .initialize      = initialize,
+    });
+  });
+
+  return clazz;
+}
+
+#undef _Class