Move SwapchainTexture and acquireSwapchainTexture to CommandBuffer

SwapchainTexture belongs on CommandBuffer: SDL3 acquires the swapchain
texture from a command buffer, and the texture is only valid until that
buffer is submitted. RenderDevice::acquireSwapchainTexture was a thin
wrapper that just forwarded to cmd->cmd — remove it entirely.

Callers:

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jdolan

Examples/Hello-iOS/Hello-iOS.c

@@ -275,7 +275,7 @@ SDL_AppResult SDL_AppIterate(void *unused) {
 	while (app.angleY >= 360.0f) app.angleY -= 360.0f;
 
 	CommandBuffer *cmd = $(app.renderDevice, acquireCommandBuffer);
-	Swapchain swapchain = { 0 };
+	SwapchainTexture swapchain = { 0 };
 	if (!$(app.renderDevice, acquireSwapchainTexture, cmd, &swapchain)) {
 		$(cmd, cancel);
 		release(cmd);

Examples/Hello.c

@@ -182,39 +182,35 @@ int main(int argc, char **argv) {
 		}
 
 		CommandBuffer *cmd = $(renderDevice, acquireCommandBuffer);
-		Swapchain swapchain = { 0 };
 
-		if (!$(renderDevice, acquireSwapchainTexture, cmd, &swapchain)) {
-			$(cmd, cancel);
-			release(cmd);
-			continue;
-		}
-
-		float4x4 modelView = float4x4_rotation(angleX, float3_new(1.f, 0.f, 0.f));
-		modelView = float4x4_mul(float4x4_rotation(angleY, float3_new(0.f, 1.f, 0.f)), modelView);
-		modelView = float4x4_mul(float4x4_translation(float3_new(0.f, 0.f, -2.5f)), modelView);
-		const float4x4 projection = float4x4_perspective(45.f, (float) swapchain.size.w / (float) swapchain.size.h, 0.01f, 100.f);
-		const float4x4 modelViewProjection = float4x4_mul(projection, modelView);
-
-		SDL_GPUColorTargetInfo colorTarget = {
-			.texture = swapchain.texture,
-			.clear_color = { 0.1f, 0.1f, 0.2f, 1.0f },
-			.load_op = SDL_GPU_LOADOP_CLEAR,
-			.store_op = SDL_GPU_STOREOP_STORE,
-		};
-
-		SDL_GPUDepthStencilTargetInfo depthTarget = $(framebuffer, depthTargetInfo,
-			SDL_GPU_LOADOP_CLEAR, SDL_GPU_STOREOP_DONT_CARE, 1.f);
-
-		RenderPass *renderPass = $(cmd, beginRenderPass, &colorTarget, 1, &depthTarget);
-		$(renderPass, bindPipeline, pipeline);
-		$(renderPass, bindVertexBuffers, 0, &(SDL_GPUBufferBinding) {
-			.buffer = vertexBuffer,
-			.offset = 0,
-		}, 1);
-		$(cmd, pushVertexUniformData, 0, modelViewProjection.f, sizeof(modelViewProjection));
-		$(renderPass, drawPrimitives, (Uint32) SDL_arraysize(vertex_data), 1, 0, 0);
-		release(renderPass);
+		SwapchainTexture swapchain = { 0 };
+    if ($(cmd, acquireSwapchainTexture, window, &swapchain)) {
+
+      float4x4 modelView = float4x4_rotation(angleX, float3_new(1.f, 0.f, 0.f));
+      modelView = float4x4_mul(float4x4_rotation(angleY, float3_new(0.f, 1.f, 0.f)), modelView);
+      modelView = float4x4_mul(float4x4_translation(float3_new(0.f, 0.f, -2.5f)), modelView);
+      const float4x4 projection = float4x4_perspective(45.f, (float) swapchain.size.w / (float) swapchain.size.h, 0.01f, 100.f);
+      const float4x4 modelViewProjection = float4x4_mul(projection, modelView);
+
+      SDL_GPUColorTargetInfo colorTarget = {
+        .texture = swapchain.texture,
+        .clear_color = { 0.1f, 0.1f, 0.2f, 1.0f },
+        .load_op = SDL_GPU_LOADOP_CLEAR,
+        .store_op = SDL_GPU_STOREOP_STORE,
+      };
+
+      SDL_GPUDepthStencilTargetInfo depthTarget = $(framebuffer, depthTargetInfo, SDL_GPU_LOADOP_CLEAR, SDL_GPU_STOREOP_DONT_CARE, 1.f);
+
+      RenderPass *renderPass = $(cmd, beginRenderPass, &colorTarget, 1, &depthTarget);
+      $(renderPass, bindPipeline, pipeline);
+      $(renderPass, bindVertexBuffers, 0, &(SDL_GPUBufferBinding) {
+        .buffer = vertexBuffer,
+        .offset = 0,
+      }, 1);
+      $(cmd, pushVertexUniformData, 0, modelViewProjection.f, sizeof(modelViewProjection));
+      $(renderPass, drawPrimitives, (Uint32) SDL_arraysize(vertex_data), 1, 0, 0);
+      release(renderPass);
+    }
 
 		$(cmd, submit);
 		release(cmd);

Examples/HelloCompute.c

@@ -143,9 +143,9 @@ int main(int argc, char **argv) {
 		}
 
 		CommandBuffer *cmd = $(renderDevice, acquireCommandBuffer);
-		Swapchain swapchain = { 0 };
+		SwapchainTexture swapchain = { 0 };
 
-		if (!$(renderDevice, acquireSwapchainTexture, cmd, &swapchain)) {
+		if (!$(cmd, acquireSwapchainTexture, window, &swapchain)) {
 			$(cmd, cancel);
 			release(cmd);
 			continue;

Sources/ObjectivelyGPU/CommandBuffer.c

@@ -33,11 +33,16 @@
 #pragma mark - CommandBuffer
 
 /**
- * @fn bool CommandBuffer::acquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SDL_GPUTexture **texture, Uint32 *w, Uint32 *h)
+ * @fn bool CommandBuffer::acquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SwapchainTexture *swapchain)
  * @memberof CommandBuffer
  */
-static bool acquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SDL_GPUTexture **texture, Uint32 *w, Uint32 *h) {
-  return SDL_AcquireGPUSwapchainTexture(self->cmd, window, texture, w, h);
+static bool acquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SwapchainTexture *swapchain) {
+  assert(swapchain);
+
+  Uint32 w = 0, h = 0;
+  const bool ok = SDL_AcquireGPUSwapchainTexture(self->cmd, window, &swapchain->texture, &w, &h);
+  swapchain->size = MakeSize(w, h);
+  return ok && swapchain->texture;
 }
 
 /**
@@ -194,14 +199,17 @@ static SDL_GPUFence *submitAndFence(const CommandBuffer *self) {
 }
 
 /**
- * @fn bool CommandBuffer::waitAndAcquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SDL_GPUTexture **texture, Uint32 *w, Uint32 *h)
+ * @fn bool CommandBuffer::waitAndAcquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SwapchainTexture *swapchain)
  * @memberof CommandBuffer
  */
-static bool waitAndAcquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SDL_GPUTexture **texture, Uint32 *w, Uint32 *h) {
+static bool waitAndAcquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SwapchainTexture *swapchain) {
+  assert(swapchain);
 
-  const bool ok = SDL_WaitAndAcquireGPUSwapchainTexture(self->cmd, window, texture, w, h);
+  Uint32 w = 0, h = 0;
+  const bool ok = SDL_WaitAndAcquireGPUSwapchainTexture(self->cmd, window, &swapchain->texture, &w, &h);
   GPU_Assert(ok, "SDL_WaitAndAcquireGPUSwapchainTexture");
 
+  swapchain->size = MakeSize(w, h);
   return ok;
 }
 

Sources/ObjectivelyGPU/CommandBuffer.h

@@ -37,6 +37,25 @@ typedef struct CopyPass CopyPass;
 typedef struct RenderPass RenderPass;
 typedef struct CommandBuffer CommandBuffer;
 typedef struct CommandBufferInterface CommandBufferInterface;
+typedef struct SwapchainTexture SwapchainTexture;
+
+/**
+ * @brief The swapchain texture acquired for a single frame.
+ * @details Valid only between a successful `acquireSwapchainTexture` call and
+ * the `submit` of the same `CommandBuffer`. SDL3 reclaims the texture on submit.
+ */
+struct SwapchainTexture {
+
+  /**
+   * @brief The swapchain render target for this frame.
+   */
+  SDL_GPUTexture *texture;
+
+  /**
+   * @brief The swapchain dimensions in pixels.
+   */
+  SDL_Size size;
+};
 
 /**
  * @brief A recorded sequence of GPU commands for a single frame.
@@ -87,17 +106,18 @@ struct CommandBufferInterface {
   ObjectInterface objectInterface;
 
   /**
-   * @fn bool CommandBuffer::acquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SDL_GPUTexture **texture, Uint32 *w, Uint32 *h)
+   * @fn bool CommandBuffer::acquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SwapchainTexture *swapchain)
    * @brief Acquires the next swapchain texture for rendering.
+   * @details Returns `false` (without asserting) when the window is minimised
+   *   or the swapchain is temporarily unavailable. The caller should skip
+   *   rendering for that frame.
    * @param self The CommandBuffer.
    * @param window The window whose swapchain to acquire.
-   * @param texture Receives the swapchain texture, or NULL if unavailable this frame.
-   * @param w Receives the swapchain width in pixels, or NULL.
-   * @param h Receives the swapchain height in pixels, or NULL.
-   * @return True on success, false on error.
+   * @param swapchain Output structure populated with the texture and dimensions.
+   * @return True on success, false when the swapchain is unavailable this frame.
    * @memberof CommandBuffer
    */
-  bool (*acquireSwapchainTexture)(const CommandBuffer *self, SDL_Window *window, SDL_GPUTexture **texture, Uint32 *w, Uint32 *h);
+  bool (*acquireSwapchainTexture)(const CommandBuffer *self, SDL_Window *window, SwapchainTexture *swapchain);
 
   /**
    * @fn ComputePass *CommandBuffer::beginComputePass(const CommandBuffer *self, ...)
@@ -239,18 +259,17 @@ struct CommandBufferInterface {
   SDL_GPUFence *(*submitAndFence)(const CommandBuffer *self);
 
   /**
-   * @fn bool CommandBuffer::waitAndAcquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SDL_GPUTexture **texture, Uint32 *w, Uint32 *h)
+   * @fn bool CommandBuffer::waitAndAcquireSwapchainTexture(const CommandBuffer *self, SDL_Window *window, SwapchainTexture *swapchain)
    * @brief Blocks until a swapchain texture is available, then acquires it.
-   * @details Prefer `acquireSwapchainTexture` unless you must block.
+   * @details Prefer `acquireSwapchainTexture` unless you must guarantee a
+   *   texture this frame (e.g. during resize).
    * @param self The CommandBuffer.
    * @param window The window whose swapchain to acquire.
-   * @param texture Receives the swapchain texture.
-   * @param w Receives the swapchain width in pixels, or NULL.
-   * @param h Receives the swapchain height in pixels, or NULL.
+   * @param swapchain Output structure populated with the texture and dimensions.
    * @return True on success, false on error.
    * @memberof CommandBuffer
    */
-  bool (*waitAndAcquireSwapchainTexture)(const CommandBuffer *self, SDL_Window *window, SDL_GPUTexture **texture, Uint32 *w, Uint32 *h);
+  bool (*waitAndAcquireSwapchainTexture)(const CommandBuffer *self, SDL_Window *window, SwapchainTexture *swapchain);
 };
 
 /**

Sources/ObjectivelyGPU/RenderDevice.c

@@ -78,21 +78,6 @@ static CommandBuffer *acquireCommandBuffer(const RenderDevice *self) {
   return buffer;
 }
 
-/**
- * @fn bool RenderDevice::acquireSwapchainTexture(const RenderDevice *self, CommandBuffer *cmd, Swapchain *swapchain)
- * @memberof RenderDevice
- */
-static bool acquireSwapchainTexture(const RenderDevice *self, CommandBuffer *cmd, Swapchain *swapchain) {
-
-  SDL_AcquireGPUSwapchainTexture(cmd->cmd,
-                                 self->window,
-                                 &swapchain->texture,
-                                 (unsigned int *) &swapchain->size.w,
-                                 (unsigned int *) &swapchain->size.h);
-
-  return swapchain->texture != NULL;
-}
-
 /**
  * @fn SDL_GPUBuffer *RenderDevice::createBuffer(const RenderDevice *self, const SDL_GPUBufferCreateInfo *info)
  * @memberof RenderDevice
@@ -788,7 +773,6 @@ static void initialize(Class *clazz) {
   ((ObjectInterface *) clazz->interface)->dealloc = dealloc;
 
   ((RenderDeviceInterface *) clazz->interface)->acquireCommandBuffer = acquireCommandBuffer;
-  ((RenderDeviceInterface *) clazz->interface)->acquireSwapchainTexture = acquireSwapchainTexture;
   ((RenderDeviceInterface *) clazz->interface)->createBuffer = createBuffer;
   ((RenderDeviceInterface *) clazz->interface)->createBufferWithConstMem = createBufferWithConstMem;
   ((RenderDeviceInterface *) clazz->interface)->createBufferWithData = createBufferWithData;

Sources/ObjectivelyGPU/RenderDevice.h

@@ -41,27 +41,6 @@
 
 typedef struct CommandBuffer CommandBuffer;
 typedef struct RenderDevice RenderDevice;
-
-/**
- * @brief The Swapchain (render target) type.
- */
-struct Swapchain {
-
-  /**
-   * @brief The current render target.
-   * @private
-   */
-  SDL_GPUTexture *texture;
-
-  /**
-   * @brief The swapchain dimensions.
-   * @private
-   */
-  SDL_Size size;
-};
-
-typedef struct Swapchain Swapchain;
-
 typedef struct RenderDeviceInterface RenderDeviceInterface;
 
 /**
@@ -140,21 +119,6 @@ struct RenderDeviceInterface {
    */
   CommandBuffer *(*acquireCommandBuffer)(const RenderDevice *self);
 
-  /**
-   * @fn bool RenderDevice::acquireSwapchainTexture(const RenderDevice *self, CommandBuffer *cmd, Swapchain *swapchain)
-   * @brief Acquires the swapchain render target for the current frame.
-   * @details Wraps `SDL_AcquireGPUSwapchainTexture` using `self->window`. On
-   *   success, fills `swapchain->texture` with the current back-buffer and
-   *   `swapchain->size` with its pixel dimensions. Returns `false` (without
-   *   asserting) when the window is minimised or the swapchain is unavailable.
-   * @param self The RenderDevice.
-   * @param cmd The active CommandBuffer for this frame.
-   * @param swapchain Output structure to populate with the texture and dimensions.
-   * @return `true` if a swapchain texture was acquired; `false` otherwise.
-   * @memberof RenderDevice
-   */
-  bool (*acquireSwapchainTexture)(const RenderDevice *self, CommandBuffer *cmd, Swapchain *swapchain);
-
   /**
    * @fn SDL_GPUBuffer *RenderDevice::createBuffer(const RenderDevice *self, const SDL_GPUBufferCreateInfo *info)
    * @brief Creates a GPU-side buffer (vertex, index, indirect, etc.).