Add DX improvements: buffer/texture helpers, sampler presets, Framebuffer class

- RenderDevice::createBufferWithConstMem(usage, mem, size): create + upload in one call
- RenderDevice::createBufferWithData(usage, Data *): same via Objectively Data
- RenderDevice::uploadBuffer(buffer, data, size, offset, cycle): dynamic per-frame upload
- RenderDevice::createTextureFromSurface(surface, usage): SDL_Surface -> GPU texture
- RenderDevice::samplerNearest/Linear/Anisotropic(): lazy-cached preset samplers
- CopyPass::uploadData(dst, data, size, offset, cycle): batched upload within a pass
- Framebuffer class: owns color+depth textures, produces SDL_GPU*TargetInfo structs
- Hello.c updated to use createBufferWithConstMem and Framebuffer
- Thread SDL_GPUDevice through CommandBuffer and CopyPass for transfer buffer access

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

Author: jdolan

Examples/Hello.c

@@ -53,39 +53,6 @@ static const VertexData vertex_data[] = {
 	{ -0.5f, -0.5f, -0.5f,  0, 1, 0 }, {  0.5f, -0.5f, -0.5f, 0, 0, 1 }, {  0.5f, -0.5f,  0.5f, 1, 0, 1 },
 };
 
-static void upload_vertex_buffer(const RenderDevice *renderDevice, SDL_GPUBuffer *buffer) {
-
-  SDL_GPUTransferBuffer *transferBuffer = $(renderDevice, createTransferBuffer, &(SDL_GPUTransferBufferCreateInfo) {
-		.usage = SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD,
-		.size = sizeof(vertex_data),
-	});
-
-	void *mapped = $(renderDevice, mapTransferBuffer, transferBuffer, false);
-	SDL_memcpy(mapped, vertex_data, sizeof(vertex_data));
-	$(renderDevice, unmapTransferBuffer, transferBuffer);
-
-	CommandBuffer *cmd = $(renderDevice, acquireCommandBuffer);
-	CopyPass *copyPass = $(cmd, beginCopyPass);
-
-	$(copyPass, uploadBuffer,
-	  &(SDL_GPUTransferBufferLocation) {
-		.transfer_buffer = transferBuffer,
-		.offset = 0,
-	  },
-	  &(SDL_GPUBufferRegion) {
-		.buffer = buffer,
-		.offset = 0,
-		.size = sizeof(vertex_data),
-	  },
-	  false);
-
-	release(copyPass);
-	$(cmd, submit);
-	release(cmd);
-
-	$(renderDevice, releaseTransferBuffer, transferBuffer);
-}
-
 /**
  * @brief
  */
@@ -100,29 +67,20 @@ int main(int argc, char **argv) {
 
   $$(Resource, addResourcePath, EXAMPLES);
 
-	RenderDevice *renderDevice = $(alloc(RenderDevice), initWithWindow, window);
+  RenderDevice *renderDevice = $(alloc(RenderDevice), initWithWindow, window);
   assert(renderDevice);
 
-	SDL_GPUBuffer *vertexBuffer = $(renderDevice, createBuffer, &(SDL_GPUBufferCreateInfo) {
-		.usage = SDL_GPU_BUFFERUSAGE_VERTEX,
-		.size = sizeof(vertex_data),
-	});
-	upload_vertex_buffer(renderDevice, vertexBuffer);
+  SDL_GPUBuffer *vertexBuffer = $(renderDevice, createBufferWithConstMem,
+  	SDL_GPU_BUFFERUSAGE_VERTEX, vertex_data, sizeof(vertex_data));
 
-	int w = 0;
-	int h = 0;
+  int w = 0;
+  int h = 0;
   SDL_GetWindowSizeInPixels(window, &w, &h);
 
-  SDL_GPUTexture *depthTexture = $(renderDevice, createTexture, &(SDL_GPUTextureCreateInfo) {
-    .type = SDL_GPU_TEXTURETYPE_2D,
-    .format = SDL_GPU_TEXTUREFORMAT_D16_UNORM,
-    .usage = SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET,
-    .width = (Uint32) w,
-    .height = (Uint32) h,
-    .layer_count_or_depth = 1,
-    .num_levels = 1,
-    .sample_count = SDL_GPU_SAMPLECOUNT_1,
-  }, NULL);
+  Framebuffer *framebuffer = $(alloc(Framebuffer), initWithDevice, renderDevice,
+    &MakeSize(w, h),
+    SDL_GPU_TEXTUREFORMAT_INVALID,
+    SDL_GPU_TEXTUREFORMAT_D16_UNORM);
 
 	SDL_GPUShader *vertexShader = $(renderDevice, loadShader, "Hello.vert", &(SDL_GPUShaderCreateInfo) {
 		.entrypoint = "vs_main",
@@ -194,9 +152,7 @@ int main(int argc, char **argv) {
 	});
 
 	$(renderDevice, releaseShader, vertexShader);
-	vertexShader = NULL;
 	$(renderDevice, releaseShader, fragmentShader);
-	fragmentShader = NULL;
 
 	bool running = true;
 	float angleX = 0.0f;
@@ -256,14 +212,9 @@ int main(int argc, char **argv) {
 			.load_op = SDL_GPU_LOADOP_CLEAR,
 			.store_op = SDL_GPU_STOREOP_STORE,
 		};
-		SDL_GPUDepthStencilTargetInfo depthTarget = {
-			.texture = depthTexture,
-			.clear_depth = 1.0f,
-			.load_op = SDL_GPU_LOADOP_CLEAR,
-			.store_op = SDL_GPU_STOREOP_DONT_CARE,
-			.stencil_load_op = SDL_GPU_LOADOP_DONT_CARE,
-			.stencil_store_op = SDL_GPU_STOREOP_DONT_CARE,
-		};
+
+		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);
@@ -298,8 +249,8 @@ int main(int argc, char **argv) {
 	if (vertexBuffer) {
 		$(renderDevice, releaseBuffer, vertexBuffer);
 	}
-	if (depthTexture) {
-		$(renderDevice, releaseTexture, depthTexture);
+	if (framebuffer) {
+		release(framebuffer);
 	}
 	if (renderDevice) {
 		release(renderDevice);

Sources/ObjectivelyGPU.h

@@ -26,6 +26,7 @@
 #include <ObjectivelyGPU/CommandBuffer.h>
 #include <ObjectivelyGPU/ComputePass.h>
 #include <ObjectivelyGPU/CopyPass.h>
+#include <ObjectivelyGPU/Framebuffer.h>
 #include <ObjectivelyGPU/Mathlib.h>
 #include <ObjectivelyGPU/RenderDevice.h>
 #include <ObjectivelyGPU/RenderPass.h>

Sources/ObjectivelyGPU/CommandBuffer.c

@@ -61,7 +61,7 @@ static CopyPass *beginCopyPass(const CommandBuffer *self) {
   SDL_GPUCopyPass *pass = SDL_BeginGPUCopyPass(self->cmd);
   GPU_Assert(pass, "SDL_BeginGPUCopyPass");
 
-  return $(alloc(CopyPass), init, pass);
+  return $(alloc(CopyPass), init, pass, self->device);
 }
 
 /**

Sources/ObjectivelyGPU/CommandBuffer.h

@@ -68,6 +68,12 @@ struct CommandBuffer {
    * @brief The underlying SDL command buffer.
    */
   SDL_GPUCommandBuffer *cmd;
+
+  /**
+   * @brief The GPU device, threaded through to pass objects that need it.
+   * @private
+   */
+  SDL_GPUDevice *device;
 };
 
 /**

Sources/ObjectivelyGPU/CopyPass.c

@@ -22,6 +22,7 @@
  */
 
 #include <assert.h>
+#include <string.h>
 
 #include "CopyPass.h"
 
@@ -77,15 +78,17 @@ static void downloadTexture(const CopyPass *self, const SDL_GPUTextureRegion *sr
 }
 
 /**
- * @fn CopyPass *CopyPass::init(CopyPass *self, SDL_GPUCopyPass *pass)
+ * @fn CopyPass *CopyPass::init(CopyPass *self, SDL_GPUCopyPass *pass, SDL_GPUDevice *device)
  * @memberof CopyPass
  */
-static CopyPass *init(CopyPass *self, SDL_GPUCopyPass *pass) {
+static CopyPass *init(CopyPass *self, SDL_GPUCopyPass *pass, SDL_GPUDevice *device) {
 
   self = (CopyPass *) super(Object, self, init);
   if (self) {
     self->pass = pass;
     assert(self->pass);
+    self->device = device;
+    assert(self->device);
   }
 
   return self;
@@ -99,6 +102,36 @@ static void uploadBuffer(const CopyPass *self, const SDL_GPUTransferBufferLocati
   SDL_UploadToGPUBuffer(self->pass, src, dst, cycle);
 }
 
+/**
+ * @fn void CopyPass::uploadData(const CopyPass *self, SDL_GPUBuffer *dst, const void *data, Uint32 size, Uint32 offset, bool cycle)
+ * @memberof CopyPass
+ */
+static void uploadData(const CopyPass *self, SDL_GPUBuffer *dst, const void *data, Uint32 size, Uint32 offset, bool cycle) {
+  assert(self);
+  assert(dst);
+  assert(data);
+  assert(size);
+
+  SDL_GPUTransferBuffer *tbuf = SDL_CreateGPUTransferBuffer(self->device, &(SDL_GPUTransferBufferCreateInfo) {
+    .usage = SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD,
+    .size = size,
+  });
+  GPU_Assert(tbuf, "SDL_CreateGPUTransferBuffer");
+
+  void *mapped = SDL_MapGPUTransferBuffer(self->device, tbuf, cycle);
+  GPU_Assert(mapped, "SDL_MapGPUTransferBuffer");
+
+  memcpy(mapped, data, size);
+  SDL_UnmapGPUTransferBuffer(self->device, tbuf);
+
+  SDL_UploadToGPUBuffer(self->pass,
+    &(SDL_GPUTransferBufferLocation) { .transfer_buffer = tbuf },
+    &(SDL_GPUBufferRegion) { .buffer = dst, .offset = offset, .size = size },
+    cycle);
+
+  SDL_ReleaseGPUTransferBuffer(self->device, tbuf);
+}
+
 /**
  * @fn void CopyPass::uploadTexture(const CopyPass *self, const SDL_GPUTextureTransferInfo *src, const SDL_GPUTextureRegion *dst, bool cycle)
  * @memberof CopyPass
@@ -122,6 +155,7 @@ static void initialize(Class *clazz) {
   ((CopyPassInterface *) clazz->interface)->downloadTexture = downloadTexture;
   ((CopyPassInterface *) clazz->interface)->init = init;
   ((CopyPassInterface *) clazz->interface)->uploadBuffer = uploadBuffer;
+  ((CopyPassInterface *) clazz->interface)->uploadData = uploadData;
   ((CopyPassInterface *) clazz->interface)->uploadTexture = uploadTexture;
 }
 

Sources/ObjectivelyGPU/CopyPass.h

@@ -69,6 +69,12 @@ struct CopyPass {
    * @private
    */
   SDL_GPUCopyPass *pass;
+
+  /**
+   * @brief The GPU device, used by `uploadData` to manage transfer buffers.
+   * @private
+   */
+  SDL_GPUDevice *device;
 };
 
 /**
@@ -110,14 +116,15 @@ struct CopyPassInterface {
   void (*downloadTexture)(const CopyPass *self, const SDL_GPUTextureRegion *src, const SDL_GPUTextureTransferInfo *dst);
 
   /**
-   * @fn CopyPass *CopyPass::init(CopyPass *self, SDL_GPUCopyPass *pass)
+   * @fn CopyPass *CopyPass::init(CopyPass *self, SDL_GPUCopyPass *pass, SDL_GPUDevice *device)
    * @brief Initializes this CopyPass wrapping the given SDL copy pass.
    * @param self The CopyPass.
    * @param pass The SDL copy pass to wrap. Must not be NULL.
+   * @param device The SDL GPU device, used by `uploadData` to manage transfer buffers.
    * @return The initialized CopyPass, or NULL on failure.
    * @memberof CopyPass
    */
-  CopyPass *(*init)(CopyPass *self, SDL_GPUCopyPass *pass);
+  CopyPass *(*init)(CopyPass *self, SDL_GPUCopyPass *pass, SDL_GPUDevice *device);
 
   /**
    * @fn void CopyPass::uploadBuffer(const CopyPass *self, const SDL_GPUTransferBufferLocation *src, const SDL_GPUBufferRegion *dst, bool cycle)
@@ -130,6 +137,23 @@ struct CopyPassInterface {
    */
   void (*uploadBuffer)(const CopyPass *self, const SDL_GPUTransferBufferLocation *src, const SDL_GPUBufferRegion *dst, bool cycle);
 
+  /**
+   * @fn void CopyPass::uploadData(const CopyPass *self, SDL_GPUBuffer *dst, const void *data, Uint32 size, Uint32 offset, bool cycle)
+   * @brief Uploads raw CPU data to a GPU buffer, managing the transfer buffer internally.
+   * @details Allocates a temporary transfer buffer, copies @p data into it, records
+   *   the upload, and releases the transfer buffer — all within this call. Use this
+   *   to batch multiple buffer uploads into a single copy pass without manual transfer
+   *   buffer management.
+   * @param self The CopyPass.
+   * @param dst The GPU buffer to upload into.
+   * @param data CPU pointer to the source data.
+   * @param size Number of bytes to upload.
+   * @param offset Byte offset into @p dst where the data is written.
+   * @param cycle When true, the GPU buffer is cycled to avoid pipeline stalls.
+   * @memberof CopyPass
+   */
+  void (*uploadData)(const CopyPass *self, SDL_GPUBuffer *dst, const void *data, Uint32 size, Uint32 offset, bool cycle);
+
   /**
    * @fn void CopyPass::uploadTexture(const CopyPass *self, const SDL_GPUTextureTransferInfo *src, const SDL_GPUTextureRegion *dst, bool cycle)
    * @brief Uploads data from a CPU transfer buffer to a GPU texture.