Framebuffer: sampleable depth + resolveColorTexture/resolveDepthTexture

Add a resolveDepthTexture() accessor mirroring resolveColorTexture() (renamed
from resolvedColorTexture): both return the single-sample, sampleable texture to
read back (the attachment itself when single-sample, the resolve target under
MSAA). Single-sample depth attachments now carry SAMPLER so scene depth can be
read directly (e.g. soft particles); multisampled depth stays a plain
depth-stencil target (its separate resolveDepthTexture, populated by a resolve
pass, is reserved for when MSAA lands, since SDL has no depth store-op resolve).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jdolan

Sources/ObjectivelyGPU/Framebuffer.c

@@ -43,6 +43,7 @@ static void dealloc(Object *self) {
     release(this->resolveTextures[i]);
   }
   release(this->depthTexture);
+  release(this->resolveDepthTexture);
 
   release(this->device);
 
@@ -146,16 +147,15 @@ static bool resize(Framebuffer *self, const SDL_Size *size) {
   }
   release(self->depthTexture);
   self->depthTexture = NULL;
+  release(self->resolveDepthTexture);
+  self->resolveDepthTexture = NULL;
 
   self->size = *size;
 
   const bool multisampled = self->sampleCount > SDL_GPU_SAMPLECOUNT_1;
 
   for (Uint32 i = 0; i < self->numColorTargets; i++) {
 
-    // A multisampled color target is resolved before sampling, so it needs only
-    // COLOR_TARGET usage; the single-sample paths (no MSAA, or the resolve target)
-    // also carry SAMPLER so they can be blit/sampled.
     self->colorTextures[i] = $(self->device, createTexture, &(SDL_GPUTextureCreateInfo) {
       .type = SDL_GPU_TEXTURETYPE_2D,
       .format = self->colorFormats[i],
@@ -182,10 +182,15 @@ static bool resize(Framebuffer *self, const SDL_Size *size) {
   }
 
   if (self->depthFormat != SDL_GPU_TEXTUREFORMAT_INVALID) {
+
+    // Single-sample depth carries SAMPLER so it can be read directly via
+    // resolveDepthTexture (e.g. soft particles). Multisampled depth is a plain
+    // depth-stencil target; sampling it requires the separate resolveDepthTexture,
+    // populated by a resolve pass (SDL has no depth store-op resolve) — TODO when MSAA lands.
     self->depthTexture = $(self->device, createTexture, &(SDL_GPUTextureCreateInfo) {
       .type = SDL_GPU_TEXTURETYPE_2D,
       .format = self->depthFormat,
-      .usage = SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET,
+      .usage = SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET | (multisampled ? 0 : SDL_GPU_TEXTUREUSAGE_SAMPLER),
       .width = (Uint32) self->size.w,
       .height = (Uint32) self->size.h,
       .layer_count_or_depth = 1,
@@ -198,14 +203,22 @@ static bool resize(Framebuffer *self, const SDL_Size *size) {
 }
 
 /**
- * @fn Texture *Framebuffer::resolvedColorTexture(const Framebuffer *self, Uint32 index)
+ * @fn Texture *Framebuffer::resolveColorTexture(const Framebuffer *self, Uint32 index)
  * @memberof Framebuffer
  */
-static Texture *resolvedColorTexture(const Framebuffer *self, Uint32 index) {
+static Texture *resolveColorTexture(const Framebuffer *self, Uint32 index) {
   assert(index < self->numColorTargets);
   return self->resolveTextures[index] ?: self->colorTextures[index];
 }
 
+/**
+ * @fn Texture *Framebuffer::resolveDepthTexture(const Framebuffer *self)
+ * @memberof Framebuffer
+ */
+static Texture *resolveDepthTexture(const Framebuffer *self) {
+  return self->resolveDepthTexture ?: self->depthTexture;
+}
+
 #pragma mark - Class lifecycle
 
 /**
@@ -219,7 +232,8 @@ static void initialize(Class *clazz) {
   ((FramebufferInterface *) clazz->interface)->depthTargetInfo = depthTargetInfo;
   ((FramebufferInterface *) clazz->interface)->initWithDevice = initWithDevice;
   ((FramebufferInterface *) clazz->interface)->resize = resize;
-  ((FramebufferInterface *) clazz->interface)->resolvedColorTexture = resolvedColorTexture;
+  ((FramebufferInterface *) clazz->interface)->resolveColorTexture = resolveColorTexture;
+  ((FramebufferInterface *) clazz->interface)->resolveDepthTexture = resolveDepthTexture;
 }
 
 /**

Sources/ObjectivelyGPU/Framebuffer.h

@@ -171,7 +171,7 @@ struct Framebuffer {
   /**
    * @brief The single-sample resolve targets, or all `NULL` unless `sampleCount` > `SDL_GPU_SAMPLECOUNT_1`.
    * @details Render passes resolve `colorTextures[i]` into `resolveTextures[i]`; that is
-   *   the texture to sample, blit, or present. See `resolvedColorTexture`.
+   *   the texture to sample, blit, or present. See `resolveColorTexture`.
    */
   Texture *resolveTextures[GPU_MAX_COLOR_TARGETS];
 
@@ -182,13 +182,22 @@ struct Framebuffer {
 
   /**
    * @brief The depth attachment texture, or `NULL` if `depthFormat` is invalid.
-   * @details Multisampled with the pass when `sampleCount` > `SDL_GPU_SAMPLECOUNT_1`. It is
-   *   not resolved: depth is used for testing and discarded. A consumer needing sampleable
-   *   resolved depth must resolve it in its own shader pass (SDL has no depth store-op resolve).
+   * @details Single-sample depth also carries `SAMPLER` and is returned directly by
+   *   `resolveDepthTexture`. Multisampled depth is a plain depth-stencil target
+   *   (`resolveDepthTexture` returns the separate `resolveDepthTexture` instead, since
+   *   SDL has no depth store-op resolve). Sample via `resolveDepthTexture`, not this.
    * @private
    */
   Texture *depthTexture;
 
+  /**
+   * @brief The single-sample, sampleable depth resolve target, or `NULL`.
+   * @details Only allocated when multisampled (single-sample reads the depth attachment
+   *   directly). Populated by an explicit resolve pass; returned by `resolveDepthTexture`.
+   * @private
+   */
+  Texture *resolveDepthTexture;
+
   /**
    * @brief The owning RenderDevice, used for texture allocation and dealloc.
    * @private
@@ -255,15 +264,27 @@ struct FramebufferInterface {
   Framebuffer *(*initWithDevice)(Framebuffer *self, RenderDevice *device, const GPU_FramebufferCreateInfo *info);
 
   /**
-   * @fn Texture *Framebuffer::resolvedColorTexture(const Framebuffer *self, Uint32 index)
-   * @brief Returns the single-sample color texture for attachment @p index, to sample, blit, or present.
+   * @fn Texture *Framebuffer::resolveColorTexture(const Framebuffer *self, Uint32 index)
+   * @brief Returns the single-sample, sampleable color texture for attachment @p index, to sample, blit, or present.
    * @details Returns `resolveTextures[index]` when multisampled, otherwise `colorTextures[index]`.
    * @param self The Framebuffer.
    * @param index The color attachment index, in `[0, numColorTargets)`.
    * @return The resolved color texture, or `NULL` if @p index has no attachment.
    * @memberof Framebuffer
    */
-  Texture *(*resolvedColorTexture)(const Framebuffer *self, Uint32 index);
+  Texture *(*resolveColorTexture)(const Framebuffer *self, Uint32 index);
+
+  /**
+   * @fn Texture *Framebuffer::resolveDepthTexture(const Framebuffer *self)
+   * @brief Returns the single-sample, sampleable depth texture, to read scene depth (e.g. soft particles).
+   * @details Single-sample: the depth attachment itself (created with `SAMPLER`). Multisampled: the
+   *   separate `resolveDepthTexture`, which must first be populated by a resolve pass (SDL has no depth
+   *   store-op resolve). Returns `NULL` if the framebuffer has no depth attachment.
+   * @param self The Framebuffer.
+   * @return The sampleable depth texture, or `NULL` if there is no depth attachment.
+   * @memberof Framebuffer
+   */
+  Texture *(*resolveDepthTexture)(const Framebuffer *self);
 
   /**
    * @fn bool Framebuffer::resize(Framebuffer *self, const SDL_Size *size)

Sources/ObjectivelyGPU/RenderDevice.c

@@ -121,7 +121,7 @@ static void endFrame(RenderDevice *self) {
 
   GPU_Assert(self->commands, "endFrame called without a frame in flight");
 
-  Texture *color = $(self->framebuffer, resolvedColorTexture, 0);
+  Texture *color = $(self->framebuffer, resolveColorTexture, 0);
   GPU_Assert(color, "framebuffer has no color attachment to present");
 
   $(self->commands, blitTexture, &(SDL_GPUBlitInfo) {

Sources/ObjectivelyGPU/RenderDevice.h

@@ -290,7 +290,7 @@ struct RenderDeviceInterface {
   /**
    * @fn void RenderDevice::endFrame(RenderDevice *self)
    * @brief Ends the frame begun by `beginFrame`: presents the framebuffer and submits.
-   * @details Blits the framebuffer's resolved color (`Framebuffer::resolvedColorTexture`,
+   * @details Blits the framebuffer's resolved color (`Framebuffer::resolveColorTexture`,
    *   the resolve target when multisampled) into the acquired swapchain texture, submits
    *   the frame's command buffer, and releases it. Must be paired with a non-NULL
    *   `beginFrame` return.