Introduce Fence and TransfterBuffer.

Author: jdolan

Examples/Hello.c

@@ -98,7 +98,7 @@ typedef struct {
    * @brief Occlusion query proof-of-concept: pool, readback buffer, and frame counter.
    */
   QueryPool *occlusionQueryPool;
-  SDL_GPUTransferBuffer *occlusionQueryTransfer;
+  TransferBuffer *occlusionQueryTransfer;
   Uint32 frames;
 } AppState;
 
@@ -238,19 +238,19 @@ static void logOcclusionQueryResult(AppState *app) {
 
   CopyPass *copyPass = $(commands, beginCopyPass);
   $(copyPass, downloadQueryResults, app->occlusionQueryPool, 0, 1, &(SDL_GPUTransferBufferLocation) {
-    .transfer_buffer = app->occlusionQueryTransfer,
+    .transfer_buffer = app->occlusionQueryTransfer->buffer,
   });
   release(copyPass);
 
-  SDL_GPUFence *fence = $(commands, submitAndFence);
+  Fence *fence = $(commands, submitAndFence);
   release(commands);
 
-  $(app->renderDevice, waitForFences, true, &fence, 1);
-  $(app->renderDevice, releaseFence, fence);
+  $(fence, wait);
+  release(fence);
 
-  const Uint64 *result = $(app->renderDevice, mapTransferBuffer, app->occlusionQueryTransfer, false);
+  const Uint64 *result = $(app->occlusionQueryTransfer, map, false);
   SDL_Log("Occlusion query result: %" SDL_PRIu64 " samples passed", *result);
-  $(app->renderDevice, unmapTransferBuffer, app->occlusionQueryTransfer);
+  $(app->occlusionQueryTransfer, unmap);
 }
 
 #pragma mark - SDL application callbacks
@@ -349,7 +349,7 @@ void SDL_AppQuit(void *appState, SDL_AppResult result) {
   release(app->scene.vertexBuffer);
 
   release(app->occlusionQueryPool);
-  $(app->renderDevice, releaseTransferBuffer, app->occlusionQueryTransfer);
+  release(app->occlusionQueryTransfer);
 
   release(app->framebuffer);
   release(app->renderDevice);

ObjectivelyGPU.vs15/ObjectivelyGPU.vcxproj

@@ -25,6 +25,7 @@
     <ClInclude Include="..\Sources\ObjectivelyGPU\ComputePass.h" />
     <ClInclude Include="..\Sources\ObjectivelyGPU\ComputePipeline.h" />
     <ClInclude Include="..\Sources\ObjectivelyGPU\CopyPass.h" />
+    <ClInclude Include="..\Sources\ObjectivelyGPU\Fence.h" />
     <ClInclude Include="..\Sources\ObjectivelyGPU\Framebuffer.h" />
     <ClInclude Include="..\Sources\ObjectivelyGPU\GraphicsPipeline.h" />
     <ClInclude Include="..\Sources\ObjectivelyGPU\Mathlib.h" />
@@ -34,6 +35,7 @@
     <ClInclude Include="..\Sources\ObjectivelyGPU\Sampler.h" />
     <ClInclude Include="..\Sources\ObjectivelyGPU\Shader.h" />
     <ClInclude Include="..\Sources\ObjectivelyGPU\Texture.h" />
+    <ClInclude Include="..\Sources\ObjectivelyGPU\TransferBuffer.h" />
     <ClInclude Include="..\Sources\ObjectivelyGPU\Types.h" />
     <ClInclude Include="Sources\WindowlyGPU.h" />
   </ItemGroup>
@@ -43,6 +45,7 @@
     <ClCompile Include="..\Sources\ObjectivelyGPU\ComputePass.c" />
     <ClCompile Include="..\Sources\ObjectivelyGPU\ComputePipeline.c" />
     <ClCompile Include="..\Sources\ObjectivelyGPU\CopyPass.c" />
+    <ClCompile Include="..\Sources\ObjectivelyGPU\Fence.c" />
     <ClCompile Include="..\Sources\ObjectivelyGPU\Framebuffer.c" />
     <ClCompile Include="..\Sources\ObjectivelyGPU\GraphicsPipeline.c" />
     <ClCompile Include="..\Sources\ObjectivelyGPU\QueryPool.c" />
@@ -51,6 +54,7 @@
     <ClCompile Include="..\Sources\ObjectivelyGPU\Sampler.c" />
     <ClCompile Include="..\Sources\ObjectivelyGPU\Shader.c" />
     <ClCompile Include="..\Sources\ObjectivelyGPU\Texture.c" />
+    <ClCompile Include="..\Sources\ObjectivelyGPU\TransferBuffer.c" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\..\Objectively\Objectively.vs15\Objectively.vcxproj">

ObjectivelyGPU.xcodeproj/project.pbxproj

@@ -57,6 +57,10 @@
 		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 */; };
+		3402D3208D6A4CF886402DD3 /* Fence.h in Headers */ = {isa = PBXBuildFile; fileRef = B89C52ADCD12486D934D4F78 /* Fence.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		E7138396FE1A4AF0B311EBD6 /* Fence.c in Sources */ = {isa = PBXBuildFile; fileRef = 0F7C26CE48FB43D393B963EA /* Fence.c */; };
+		8D678937240347D29F529D34 /* TransferBuffer.h in Headers */ = {isa = PBXBuildFile; fileRef = F20F19F296684FA89413FFC0 /* TransferBuffer.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		17034614E26D4BBCA2806D4B /* TransferBuffer.c in Sources */ = {isa = PBXBuildFile; fileRef = DCDE588CEB8C4ED0A63C96C7 /* TransferBuffer.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 */; };
@@ -186,6 +190,10 @@
 		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>"; };
+		B89C52ADCD12486D934D4F78 /* Fence.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = Fence.h; sourceTree = "<group>"; };
+		0F7C26CE48FB43D393B963EA /* Fence.c */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.c; path = Fence.c; sourceTree = "<group>"; };
+		F20F19F296684FA89413FFC0 /* TransferBuffer.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = TransferBuffer.h; sourceTree = "<group>"; };
+		DCDE588CEB8C4ED0A63C96C7 /* TransferBuffer.c */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.c; path = TransferBuffer.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>"; };
@@ -305,6 +313,8 @@
 				338EC7DCAE74C1B8C397D189 /* Config.h */,
 				59334BDAED542AB6DE565EDD /* CopyPass.h */,
 				C862954A9DD435C1FF7CD31D /* CopyPass.c */,
+				B89C52ADCD12486D934D4F78 /* Fence.h */,
+				0F7C26CE48FB43D393B963EA /* Fence.c */,
 				CECF83C52FF03A3500CB0CCA /* Framebuffer.h */,
 				CECF83C62FF03A3500CB0CCA /* Framebuffer.c */,
 				CEBA3F652FF3211F00758CA6 /* GraphicsPipeline.h */,
@@ -322,6 +332,8 @@
 				CEBA3F6A2FF3211F00758CA6 /* Shader.c */,
 				CEBA3F5E2FF30F1E00758CA6 /* Texture.h */,
 				CEBA3F5F2FF30F1E00758CA6 /* Texture.c */,
+				F20F19F296684FA89413FFC0 /* TransferBuffer.h */,
+				DCDE588CEB8C4ED0A63C96C7 /* TransferBuffer.c */,
 				38F069D0DBE26C7E00B5B5EE /* Types.h */,
 				CECF83942FEF65EB00CB0CCA /* Makefile.am */,
 			);
@@ -400,6 +412,7 @@
 				CEBA3F6D2FF3211F00758CA6 /* ComputePipeline.h in Headers */,
 				6F351DFD232DA78A42D8B494 /* Config.h in Headers */,
 				DF73824CC25298378B451056 /* CopyPass.h in Headers */,
+				3402D3208D6A4CF886402DD3 /* Fence.h in Headers */,
 				CECF83C72FF03A3500CB0CCA /* Framebuffer.h in Headers */,
 				CEBA3F6B2FF3211F00758CA6 /* GraphicsPipeline.h in Headers */,
 				CECF83982FEF6A7200CB0CCA /* Mathlib.h in Headers */,
@@ -410,6 +423,7 @@
 				CEBA3F6C2FF3211F00758CA6 /* Sampler.h in Headers */,
 				CEBA3F6E2FF3211F00758CA6 /* Shader.h in Headers */,
 				CEBA3F602FF30F1E00758CA6 /* Texture.h in Headers */,
+				8D678937240347D29F529D34 /* TransferBuffer.h in Headers */,
 				90C29A39257729BE8D4FDDF8 /* Types.h in Headers */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
@@ -584,6 +598,7 @@
 				F73340493879CD8034F99D51 /* ComputePass.c in Sources */,
 				CEBA3F752FF330A700758CA6 /* ComputePipeline.c in Sources */,
 				CCCB11DB70E4A962360A2119 /* CopyPass.c in Sources */,
+				E7138396FE1A4AF0B311EBD6 /* Fence.c in Sources */,
 				CECF83C82FF03A3500CB0CCA /* Framebuffer.c in Sources */,
 				CEBA3F702FF3211F00758CA6 /* GraphicsPipeline.c in Sources */,
 				45AD38AB8109398E51564CFD /* QueryPool.c in Sources */,
@@ -592,6 +607,7 @@
 				86E5132F5DCCB6B674151343 /* RenderDevice.c in Sources */,
 				FF30FF2D56F9E4EA3C492CBB /* RenderPass.c in Sources */,
 				CEBA3F612FF30F1E00758CA6 /* Texture.c in Sources */,
+				17034614E26D4BBCA2806D4B /* TransferBuffer.c in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};

Sources/ObjectivelyGPU.h

@@ -28,6 +28,7 @@
 #include <ObjectivelyGPU/ComputePass.h>
 #include <ObjectivelyGPU/ComputePipeline.h>
 #include <ObjectivelyGPU/CopyPass.h>
+#include <ObjectivelyGPU/Fence.h>
 #include <ObjectivelyGPU/Framebuffer.h>
 #include <ObjectivelyGPU/GraphicsPipeline.h>
 #include <ObjectivelyGPU/Mathlib.h>
@@ -37,3 +38,4 @@
 #include <ObjectivelyGPU/Sampler.h>
 #include <ObjectivelyGPU/Shader.h>
 #include <ObjectivelyGPU/Texture.h>
+#include <ObjectivelyGPU/TransferBuffer.h>

Sources/ObjectivelyGPU/CommandBuffer.c

@@ -26,6 +26,7 @@
 #include "CommandBuffer.h"
 #include "ComputePass.h"
 #include "CopyPass.h"
+#include "Fence.h"
 #include "RenderDevice.h"
 #include "RenderPass.h"
 
@@ -251,10 +252,10 @@ static bool submit(CommandBuffer *self) {
 }
 
 /**
- * @fn SDL_GPUFence *CommandBuffer::submitAndFence(CommandBuffer *self)
+ * @fn Fence *CommandBuffer::submitAndFence(CommandBuffer *self)
  * @memberof CommandBuffer
  */
-static SDL_GPUFence *submitAndFence(CommandBuffer *self) {
+static Fence *submitAndFence(CommandBuffer *self) {
 
   GPU_Assert(!self->submitted, "command buffer already submitted");
   GPU_Assert(!self->pass, "cannot submit with an open pass");
@@ -264,7 +265,7 @@ static SDL_GPUFence *submitAndFence(CommandBuffer *self) {
 
   self->submitted = true;
 
-  return fence;
+  return $(alloc(Fence), initWithDevice, self->device, fence);
 }
 
 /**

Sources/ObjectivelyGPU/CommandBuffer.h

@@ -34,6 +34,7 @@
 
 typedef struct ComputePass ComputePass;
 typedef struct CopyPass CopyPass;
+typedef struct Fence Fence;
 typedef struct RenderPass RenderPass;
 typedef struct RenderDevice RenderDevice;
 typedef struct CommandBuffer CommandBuffer;
@@ -288,15 +289,14 @@ struct CommandBufferInterface {
   bool (*submit)(CommandBuffer *self);
 
   /**
-   * @fn SDL_GPUFence *CommandBuffer::submitAndFence(CommandBuffer *self)
-   * @brief Submits this command buffer and returns a fence for GPU completion.
-   * @details The fence must be released via `RenderDevice::releaseFence` when
-   *   no longer needed.
+   * @fn Fence *CommandBuffer::submitAndFence(CommandBuffer *self)
+   * @brief Submits this command buffer and returns a Fence for GPU completion.
+   * @details The returned Fence is retained; release it when no longer needed.
    * @param self The CommandBuffer.
-   * @return A new SDL_GPUFence, or NULL on error.
+   * @return A new, retained Fence, or `NULL` on error.
    * @memberof CommandBuffer
    */
-  SDL_GPUFence *(*submitAndFence)(CommandBuffer *self);
+  Fence *(*submitAndFence)(CommandBuffer *self);
 
   /**
    * @fn bool CommandBuffer::waitAndAcquireSwapchainTexture(const CommandBuffer *self, SwapchainTexture *swapchain)

Sources/ObjectivelyGPU/CopyPass.c

@@ -103,11 +103,13 @@ static void downloadQueryResults(const CopyPass *self, QueryPool *pool, Uint32 f
   // 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);
+  Uint64 *results = SDL_MapGPUTransferBuffer(self->commands->device->device, dst->transfer_buffer, false);
+  GPU_Assert(results, "SDL_MapGPUTransferBuffer");
+
   for (Uint32 i = 0; i < count; i++) {
     results[(dst->offset / sizeof(Uint64)) + i] = 1;
   }
-  $(self->commands->device, unmapTransferBuffer, dst->transfer_buffer);
+  SDL_UnmapGPUTransferBuffer(self->commands->device->device, dst->transfer_buffer);
 }
 
 /**

Sources/ObjectivelyGPU/Fence.c

@@ -0,0 +1,122 @@
+/*
+ * 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 "Fence.h"
+#include "RenderDevice.h"
+
+#define _Class _Fence
+
+#pragma mark - Object
+
+/**
+ * @see Object::dealloc(Object *)
+ */
+static void dealloc(Object *self) {
+
+  Fence *this = (Fence *) self;
+
+  if (this->device) {
+    if (this->fence) {
+      SDL_ReleaseGPUFence(this->device->device, this->fence);
+    }
+    release(this->device);
+  }
+
+  super(Object, self, dealloc);
+}
+
+#pragma mark - Fence
+
+/**
+ * @fn Fence *Fence::initWithDevice(Fence *self, RenderDevice *device, SDL_GPUFence *fence)
+ * @memberof Fence
+ */
+static Fence *initWithDevice(Fence *self, RenderDevice *device, SDL_GPUFence *fence) {
+
+  assert(device);
+  assert(fence);
+
+  self = (Fence *) super(Object, self, init);
+  if (self) {
+    self->device = retain(device);
+    self->fence = fence;
+  }
+
+  return self;
+}
+
+/**
+ * @fn bool Fence::query(const Fence *self)
+ * @memberof Fence
+ */
+static bool query(const Fence *self) {
+  return SDL_QueryGPUFence(self->device->device, self->fence);
+}
+
+/**
+ * @fn bool Fence::wait(const Fence *self)
+ * @memberof Fence
+ */
+static bool _wait(const Fence *self) {
+  return SDL_WaitForGPUFences(self->device->device, true, &self->fence, 1);
+}
+
+#pragma mark - Class lifecycle
+
+/**
+ * @see Class::initialize(Class *)
+ */
+static void initialize(Class *clazz) {
+
+  ((ObjectInterface *) clazz->interface)->dealloc = dealloc;
+
+  ((FenceInterface *) clazz->interface)->initWithDevice = initWithDevice;
+  ((FenceInterface *) clazz->interface)->query = query;
+  ((FenceInterface *) clazz->interface)->wait = _wait;
+}
+
+/**
+ * @fn Class *Fence::_Fence(void)
+ * @memberof Fence
+ */
+Class *_Fence(void) {
+  static Class *clazz;
+  static Once once;
+
+  do_once(&once, {
+    clazz = _initialize(&(const ClassDef) {
+      .name            = "Fence",
+      .superclass      = _Object(),
+      .instanceSize    = sizeof(Fence),
+      .interfaceOffset = offsetof(Fence, interface),
+      .interfaceSize   = sizeof(FenceInterface),
+      .initialize      = initialize,
+    });
+  });
+
+  return clazz;
+}
+
+#undef _Class