CommandBuffer::beginRenderPassWithFramebuffer convenience method.

Author: jdolan

Sources/ObjectivelyGPU/CommandBuffer.c

@@ -27,6 +27,7 @@
 #include "ComputePass.h"
 #include "CopyPass.h"
 #include "Fence.h"
+#include "Framebuffer.h"
 #include "RenderDevice.h"
 #include "RenderPass.h"
 
@@ -125,6 +126,29 @@ static RenderPass *beginRenderPass(CommandBuffer *self, const SDL_GPUColorTarget
   return renderPass;
 }
 
+/**
+ * @fn RenderPass *CommandBuffer::beginRenderPassWithFramebuffer(CommandBuffer *self, const Framebuffer *framebuffer, SDL_GPULoadOp loadOp, SDL_GPUStoreOp storeOp)
+ * @memberof CommandBuffer
+ */
+static RenderPass *beginRenderPassWithFramebuffer(CommandBuffer *self, const Framebuffer *framebuffer, SDL_GPULoadOp loadOp, SDL_GPUStoreOp storeOp) {
+
+  assert(framebuffer);
+
+  SDL_GPUColorTargetInfo color[GPU_MAX_COLOR_TARGETS];
+  for (Uint32 i = 0; i < framebuffer->numColorTargets; i++) {
+    color[i] = $(framebuffer, colorTargetInfo, i, loadOp, storeOp, NULL);
+  }
+
+  SDL_GPUDepthStencilTargetInfo depth;
+  const SDL_GPUDepthStencilTargetInfo *depthStencil = NULL;
+  if (framebuffer->depthFormat != SDL_GPU_TEXTUREFORMAT_INVALID) {
+    depth = $(framebuffer, depthTargetInfo, loadOp, storeOp, framebuffer->clearDepth);
+    depthStencil = &depth;
+  }
+
+  return beginRenderPass(self, framebuffer->numColorTargets ? color : NULL, framebuffer->numColorTargets, depthStencil);
+}
+
 /**
  * @fn void CommandBuffer::blitTexture(const CommandBuffer *self, const SDL_GPUBlitInfo *info)
  * @memberof CommandBuffer
@@ -302,6 +326,7 @@ static void initialize(Class *clazz) {
   ((CommandBufferInterface *) clazz->interface)->beginComputePass = beginComputePass;
   ((CommandBufferInterface *) clazz->interface)->beginCopyPass = beginCopyPass;
   ((CommandBufferInterface *) clazz->interface)->beginRenderPass = beginRenderPass;
+  ((CommandBufferInterface *) clazz->interface)->beginRenderPassWithFramebuffer = beginRenderPassWithFramebuffer;
   ((CommandBufferInterface *) clazz->interface)->blitTexture = blitTexture;
   ((CommandBufferInterface *) clazz->interface)->cancel = cancel;
   ((CommandBufferInterface *) clazz->interface)->generateMipmaps = generateMipmaps;

Sources/ObjectivelyGPU/CommandBuffer.h

@@ -35,6 +35,7 @@
 typedef struct ComputePass ComputePass;
 typedef struct CopyPass CopyPass;
 typedef struct Fence Fence;
+typedef struct Framebuffer Framebuffer;
 typedef struct RenderPass RenderPass;
 typedef struct RenderDevice RenderDevice;
 typedef struct CommandBuffer CommandBuffer;
@@ -183,6 +184,25 @@ struct CommandBufferInterface {
    */
   RenderPass *(*beginRenderPass)(CommandBuffer *self, const SDL_GPUColorTargetInfo *colorTargets, Uint32 numColorTargets, const SDL_GPUDepthStencilTargetInfo *depthStencil);
 
+  /**
+   * @fn RenderPass *CommandBuffer::beginRenderPassWithFramebuffer(CommandBuffer *self, const Framebuffer *framebuffer, SDL_GPULoadOp loadOp, SDL_GPUStoreOp storeOp)
+   * @brief Begins a render pass over all of @p framebuffer's color targets and its
+   *  depth target (if any), using its own clear color(s) and clear depth when @p loadOp
+   *  is `SDL_GPU_LOADOP_CLEAR`.
+   * @details Convenience for the common case of "render into this framebuffer" with a
+   *  single load/store op shared by every target. For a mix of load ops across targets,
+   *  per-target clear overrides, a query pool, or a subset of a framebuffer's targets
+   *  (e.g. a depth-only pass), build the target infos yourself via
+   *  `Framebuffer::colorTargetInfo`/`depthTargetInfo` and call `beginRenderPass` directly.
+   * @param self The CommandBuffer.
+   * @param framebuffer The Framebuffer to render into.
+   * @param loadOp Load operation applied uniformly to every target.
+   * @param storeOp Store operation applied uniformly to every target.
+   * @return A new RenderPass, retained. Must be released by the caller.
+   * @memberof CommandBuffer
+   */
+  RenderPass *(*beginRenderPassWithFramebuffer)(CommandBuffer *self, const Framebuffer *framebuffer, SDL_GPULoadOp loadOp, SDL_GPUStoreOp storeOp);
+
   /**
    * @fn void CommandBuffer::blitTexture(const CommandBuffer *self, const SDL_GPUBlitInfo *info)
    * @brief Blits a region of one texture to another.

Sources/ObjectivelyGPU/Framebuffer.c

@@ -65,7 +65,7 @@ static SDL_GPUColorTargetInfo colorTargetInfo(const Framebuffer *self, Uint32 in
     .texture = self->colorTextures[index]->texture,
     .load_op = loadOp,
     .store_op = storeOp,
-    .clear_color = clearColor ? *clearColor : (SDL_FColor) { 0.f, 0.f, 0.f, 1.f },
+    .clear_color = clearColor ? *clearColor : self->clearColors[index],
   };
 
   if (self->sampleCount > SDL_GPU_SAMPLECOUNT_1) {
@@ -117,8 +117,10 @@ static Framebuffer *initWithDevice(Framebuffer *self, RenderDevice *device, cons
     self->numColorTargets = info->numColorTargets;
     for (Uint32 i = 0; i < info->numColorTargets; i++) {
       self->colorFormats[i] = info->colorFormats[i];
+      self->clearColors[i] = info->clearColors[i];
     }
     self->depthFormat = info->depthFormat;
+    self->clearDepth = info->clearDepth;
     self->sampleCount = info->sampleCount;
 
     $(self, resize, &info->size);

Sources/ObjectivelyGPU/Framebuffer.h

@@ -87,6 +87,23 @@ typedef struct GPU_FramebufferCreateInfo {
    */
   SDL_GPUSampleCount sampleCount;
 
+  /**
+   * @brief The clear color for each color attachment, indices `[0, numColorTargets)`.
+   * @details Stashed on the Framebuffer and used as the default `clearColor` by
+   *   `colorTargetInfo` (when passed `NULL`) and by
+   *   `CommandBuffer::beginRenderPassWithFramebuffer`. Omitted entries default to
+   *   opaque black.
+   */
+  SDL_FColor clearColors[GPU_MAX_COLOR_TARGETS];
+
+  /**
+   * @brief The clear depth value for the depth attachment, if any.
+   * @details Stashed on the Framebuffer and used by
+   *   `CommandBuffer::beginRenderPassWithFramebuffer`. Typically `1.f` (the far plane);
+   *   omitted defaults to `0.f`.
+   */
+  float clearDepth;
+
 } GPU_FramebufferCreateInfo;
 
 /**
@@ -105,18 +122,15 @@ typedef struct GPU_FramebufferCreateInfo {
  *     .size = { 1920, 1080 },
  *     .colorFormats = { SDL_GPU_TEXTUREFORMAT_R16G16B16A16_FLOAT },
  *     .numColorTargets = 1,
+ *     .clearColors = { { 0.f, 0.f, 0.f, 1.f } },
  *     .depthFormat = SDL_GPU_TEXTUREFORMAT_D32_FLOAT,
+ *     .clearDepth = 1.f,
  *     .sampleCount = SDL_GPU_SAMPLECOUNT_1,
  *   });
  *
- *   SDL_GPUColorTargetInfo color = $(fb, colorTargetInfo, 0,
- *     SDL_GPU_LOADOP_CLEAR, SDL_GPU_STOREOP_STORE,
- *     &(SDL_FColor) { 0, 0, 0, 1 });
- *
- *   SDL_GPUDepthStencilTargetInfo depth = $(fb, depthTargetInfo,
- *     SDL_GPU_LOADOP_CLEAR, SDL_GPU_STOREOP_DONT_CARE, 1.f);
- *
- *   RenderPass *pass = $(commands, beginRenderPass, &color, 1, &depth);
+ *   // Renders into all of fb's targets, clearing to its own clearColors/clearDepth.
+ *   RenderPass *pass = $(commands, beginRenderPassWithFramebuffer, fb,
+ *     SDL_GPU_LOADOP_CLEAR, SDL_GPU_STOREOP_STORE);
  *   // ...
  *   release(pass);
  *   release(fb);
@@ -180,6 +194,19 @@ struct Framebuffer {
    */
   SDL_GPUTextureFormat depthFormat;
 
+  /**
+   * @brief The clear color for each color attachment, indices `[0, numColorTargets)`.
+   * @details Used as the default `clearColor` by `colorTargetInfo` (when passed `NULL`)
+   *   and by `CommandBuffer::beginRenderPassWithFramebuffer`.
+   */
+  SDL_FColor clearColors[GPU_MAX_COLOR_TARGETS];
+
+  /**
+   * @brief The clear depth value for the depth attachment, if any.
+   * @details Used by `CommandBuffer::beginRenderPassWithFramebuffer`.
+   */
+  float clearDepth;
+
   /**
    * @brief The depth attachment texture, or `NULL` if `depthFormat` is invalid.
    * @details Single-sample depth also carries `SAMPLER` and is returned directly by
@@ -230,7 +257,7 @@ struct FramebufferInterface {
    * @param index The color attachment index, in `[0, numColorTargets)`.
    * @param loadOp Load operation at the start of the pass.
    * @param storeOp Store operation at the end of the pass.
-   * @param clearColor Clear color used when `loadOp` is `SDL_GPU_LOADOP_CLEAR`, or NULL for black.
+   * @param clearColor Clear color used when `loadOp` is `SDL_GPU_LOADOP_CLEAR`, or NULL to use the framebuffer's own `clearColors[index]`.
    * @return A stack-allocated `SDL_GPUColorTargetInfo`.
    * @memberof Framebuffer
    */