Move uniforms to command buffer scope (#55)

Co-authored-by: Caleb Cornett <caleb.cornett@outlook.com>

Author: 2 people

include/SDL3/SDL_gpu.h

@@ -1141,6 +1141,107 @@ extern SDL_DECLSPEC void SDLCALL SDL_GpuReleaseGraphicsPipeline(
     SDL_GpuDevice *device,
     SDL_GpuGraphicsPipeline *graphicsPipeline);
 
+/*
+ * COMMAND BUFFERS
+ *
+ * Render state is managed via command buffers.
+ * When setting render state, that state is always local to the command buffer.
+ *
+ * Commands only begin execution on the GPU once Submit is called.
+ * Once the command buffer is submitted, it is no longer valid to use it.
+ *
+ * In multi-threading scenarios, you should acquire and submit a command buffer on the same thread.
+ * As long as you satisfy this requirement, all functionality related to command buffers is thread-safe.
+ */
+
+/**
+ * Acquire a command buffer.
+ * This command buffer is managed by the implementation and should not be freed by the user.
+ * The command buffer may only be used on the thread it was acquired on.
+ * The command buffer should be submitted on the thread it was acquired on.
+ *
+ * \param device a GPU context
+ * \returns a command buffer
+ *
+ * \since This function is available since SDL 3.x.x
+ *
+ * \sa SDL_GpuSubmit
+ * \sa SDL_GpuSubmitAndAcquireFence
+ */
+extern SDL_DECLSPEC SDL_GpuCommandBuffer *SDLCALL SDL_GpuAcquireCommandBuffer(
+    SDL_GpuDevice *device);
+
+/*
+ * UNIFORM DATA
+ *
+ * Uniforms are for passing data to shaders.
+ * The uniform data will be constant across all executions of the shader.
+ *
+ * There are 4 available uniform slots per shader stage (vertex, fragment, compute).
+ * Uniform data pushed to a slot on a stage keeps its value throughout the command buffer
+ * until you call the relevant Push function on that slot again.
+ *
+ * For example, you could write your vertex shaders to read a camera matrix from uniform binding slot 0,
+ * push the camera matrix at the start of the command buffer, and that data will be used for every
+ * subsequent draw call.
+ *
+ * It is valid to push uniform data during a render or compute pass.
+ *
+ * Uniforms are best for pushing small amounts of data.
+ * If you are pushing more than a matrix or two per call you should consider using a storage buffer instead.
+ */
+
+/**
+ * Pushes data to a vertex uniform slot on the command buffer.
+ * Subsequent draw calls will use this uniform data.
+ *
+ * \param commandBuffer a command buffer
+ * \param slotIndex the vertex uniform slot to push data to
+ * \param data client data to write
+ * \param dataLengthInBytes the length of the data to write
+ *
+ * \since This function is available since SDL 3.x.x
+ */
+extern SDL_DECLSPEC void SDLCALL SDL_GpuPushVertexUniformData(
+    SDL_GpuCommandBuffer *commandBuffer,
+    Uint32 slotIndex,
+    const void *data,
+    Uint32 dataLengthInBytes);
+
+/**
+ * Pushes data to a fragment uniform slot on the command buffer.
+ * Subsequent draw calls will use this uniform data.
+ *
+ * \param commandBuffer a command buffer
+ * \param slotIndex the fragment uniform slot to push data to
+ * \param data client data to write
+ * \param dataLengthInBytes the length of the data to write
+ *
+ * \since This function is available since SDL 3.x.x
+ */
+extern SDL_DECLSPEC void SDLCALL SDL_GpuPushFragmentUniformData(
+    SDL_GpuCommandBuffer *commandBuffer,
+    Uint32 slotIndex,
+    const void *data,
+    Uint32 dataLengthInBytes);
+
+/**
+ * Pushes data to a uniform slot on the command buffer.
+ * Subsequent draw calls will use this uniform data.
+ *
+ * \param commandBuffer a command buffer
+ * \param slotIndex the uniform slot to push data to
+ * \param data client data to write
+ * \param dataLengthInBytes the length of the data to write
+ *
+ * \since This function is available since SDL 3.x.x
+ */
+extern SDL_DECLSPEC void SDLCALL SDL_GpuPushComputeUniformData(
+    SDL_GpuCommandBuffer *commandBuffer,
+    Uint32 slotIndex,
+    const void *data,
+    Uint32 dataLengthInBytes);
+
 /*
  * A NOTE ON CYCLING
  *
@@ -1375,40 +1476,6 @@ extern SDL_DECLSPEC void SDLCALL SDL_GpuBindFragmentStorageBuffers(
     SDL_GpuBuffer **storageBuffers,
     Uint32 bindingCount);
 
-/**
- * Pushes data to a vertex uniform slot on the bound graphics pipeline.
- * Subsequent draw calls will use this uniform data.
- *
- * \param renderPass a render pass handle
- * \param slotIndex the vertex uniform slot to push data to
- * \param data client data to write
- * \param dataLengthInBytes the length of the data to write
- *
- * \since This function is available since SDL 3.x.x
- */
-extern SDL_DECLSPEC void SDLCALL SDL_GpuPushVertexUniformData(
-    SDL_GpuRenderPass *renderPass,
-    Uint32 slotIndex,
-    const void *data,
-    Uint32 dataLengthInBytes);
-
-/**
- * Pushes data to a fragment uniform slot on the bound graphics pipeline.
- * Subsequent draw calls will use this uniform data.
- *
- * \param renderPass a render pass handle
- * \param slotIndex the fragment uniform slot to push data to
- * \param data client data to write
- * \param dataLengthInBytes the length of the data to write
- *
- * \since This function is available since SDL 3.x.x
- */
-extern SDL_DECLSPEC void SDLCALL SDL_GpuPushFragmentUniformData(
-    SDL_GpuRenderPass *renderPass,
-    Uint32 slotIndex,
-    const void *data,
-    Uint32 dataLengthInBytes);
-
 /* Drawing */
 
 /**
@@ -1575,23 +1642,6 @@ extern SDL_DECLSPEC void SDLCALL SDL_GpuBindComputeStorageBuffers(
     SDL_GpuBuffer **storageBuffers,
     Uint32 bindingCount);
 
-/**
- * Pushes data to a uniform slot on the bound compute pipeline.
- * Subsequent draw calls will use this uniform data.
- *
- * \param computePass a compute pass handle
- * \param slotIndex the uniform slot to push data to
- * \param data client data to write
- * \param dataLengthInBytes the length of the data to write
- *
- * \since This function is available since SDL 3.x.x
- */
-extern SDL_DECLSPEC void SDLCALL SDL_GpuPushComputeUniformData(
-    SDL_GpuComputePass *computePass,
-    Uint32 slotIndex,
-    const void *data,
-    Uint32 dataLengthInBytes);
-
 /**
  * Dispatches compute work.
  * You must not call this function before binding a compute pipeline.
@@ -1963,23 +2013,6 @@ extern SDL_DECLSPEC SDL_GpuTextureFormat SDLCALL SDL_GpuGetSwapchainTextureForma
     SDL_GpuDevice *device,
     SDL_Window *window);
 
-/**
- * Acquire a command buffer.
- * This command buffer is managed by the implementation and should not be freed by the user.
- * The command buffer may only be used on the thread it was acquired on.
- * The command buffer should be submitted on the thread it was acquired on.
- *
- * \param device a GPU context
- * \returns a command buffer
- *
- * \since This function is available since SDL 3.x.x
- *
- * \sa SDL_GpuSubmit
- * \sa SDL_GpuSubmitAndAcquireFence
- */
-extern SDL_DECLSPEC SDL_GpuCommandBuffer *SDLCALL SDL_GpuAcquireCommandBuffer(
-    SDL_GpuDevice *device);
-
 /**
  * Acquire a texture to use in presentation.
  * When a swapchain texture is acquired on a command buffer,

src/dynapi/SDL_dynapi_procs.h

@@ -1101,6 +1101,10 @@ SDL_DYNAPI_PROC(void,SDL_GpuReleaseTransferBuffer,(SDL_GpuDevice *a, SDL_GpuTran
 SDL_DYNAPI_PROC(void,SDL_GpuReleaseComputePipeline,(SDL_GpuDevice *a, SDL_GpuComputePipeline *b),(a,b),)
 SDL_DYNAPI_PROC(void,SDL_GpuReleaseShader,(SDL_GpuDevice *a, SDL_GpuShader *b),(a,b),)
 SDL_DYNAPI_PROC(void,SDL_GpuReleaseGraphicsPipeline,(SDL_GpuDevice *a, SDL_GpuGraphicsPipeline *b),(a,b),)
+SDL_DYNAPI_PROC(SDL_GpuCommandBuffer*,SDL_GpuAcquireCommandBuffer,(SDL_GpuDevice *a),(a),return)
+SDL_DYNAPI_PROC(void,SDL_GpuPushVertexUniformData,(SDL_GpuCommandBuffer *a, Uint32 b, const void *c, Uint32 d),(a,b,c,d),)
+SDL_DYNAPI_PROC(void,SDL_GpuPushFragmentUniformData,(SDL_GpuCommandBuffer *a, Uint32 b, const void *c, Uint32 d),(a,b,c,d),)
+SDL_DYNAPI_PROC(void,SDL_GpuPushComputeUniformData,(SDL_GpuCommandBuffer *a, Uint32 b, const void *c, Uint32 d),(a,b,c,d),)
 SDL_DYNAPI_PROC(SDL_GpuRenderPass*,SDL_GpuBeginRenderPass,(SDL_GpuCommandBuffer *a, SDL_GpuColorAttachmentInfo *b, Uint32 c, SDL_GpuDepthStencilAttachmentInfo *d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(void,SDL_GpuBindGraphicsPipeline,(SDL_GpuRenderPass *a, SDL_GpuGraphicsPipeline *b),(a,b),)
 SDL_DYNAPI_PROC(void,SDL_GpuSetViewport,(SDL_GpuRenderPass *a, SDL_GpuViewport *b),(a,b),)
@@ -1113,8 +1117,6 @@ SDL_DYNAPI_PROC(void,SDL_GpuBindVertexStorageBuffers,(SDL_GpuRenderPass *a, Uint
 SDL_DYNAPI_PROC(void,SDL_GpuBindFragmentSamplers,(SDL_GpuRenderPass *a, Uint32 b, SDL_GpuTextureSamplerBinding *c, Uint32 d),(a,b,c,d),)
 SDL_DYNAPI_PROC(void,SDL_GpuBindFragmentStorageTextures,(SDL_GpuRenderPass *a, Uint32 b, SDL_GpuTextureSlice *c, Uint32 d),(a,b,c,d),)
 SDL_DYNAPI_PROC(void,SDL_GpuBindFragmentStorageBuffers,(SDL_GpuRenderPass *a, Uint32 b, SDL_GpuBuffer **c, Uint32 d),(a,b,c,d),)
-SDL_DYNAPI_PROC(void,SDL_GpuPushVertexUniformData,(SDL_GpuRenderPass *a, Uint32 b, const void *c, Uint32 d),(a,b,c,d),)
-SDL_DYNAPI_PROC(void,SDL_GpuPushFragmentUniformData,(SDL_GpuRenderPass *a, Uint32 b, const void *c, Uint32 d),(a,b,c,d),)
 SDL_DYNAPI_PROC(void,SDL_GpuDrawIndexedPrimitives,(SDL_GpuRenderPass *a, Uint32 b, Uint32 c, Uint32 d, Uint32 e),(a,b,c,d,e),)
 SDL_DYNAPI_PROC(void,SDL_GpuDrawPrimitives,(SDL_GpuRenderPass *a, Uint32 b, Uint32 c),(a,b,c),)
 SDL_DYNAPI_PROC(void,SDL_GpuDrawPrimitivesIndirect,(SDL_GpuRenderPass *a, SDL_GpuBuffer *b, Uint32 c, Uint32 d, Uint32 e),(a,b,c,d,e),)
@@ -1124,7 +1126,6 @@ SDL_DYNAPI_PROC(SDL_GpuComputePass*,SDL_GpuBeginComputePass,(SDL_GpuCommandBuffe
 SDL_DYNAPI_PROC(void,SDL_GpuBindComputePipeline,(SDL_GpuComputePass *a, SDL_GpuComputePipeline *b),(a,b),)
 SDL_DYNAPI_PROC(void,SDL_GpuBindComputeStorageTextures,(SDL_GpuComputePass *a, Uint32 b, SDL_GpuTextureSlice *c, Uint32 d),(a,b,c,d),)
 SDL_DYNAPI_PROC(void,SDL_GpuBindComputeStorageBuffers,(SDL_GpuComputePass *a, Uint32 b, SDL_GpuBuffer **c, Uint32 d),(a,b,c,d),)
-SDL_DYNAPI_PROC(void,SDL_GpuPushComputeUniformData,(SDL_GpuComputePass *a, Uint32 b, const void *c, Uint32 d),(a,b,c,d),)
 SDL_DYNAPI_PROC(void,SDL_GpuDispatchCompute,(SDL_GpuComputePass *a, Uint32 b, Uint32 c, Uint32 d),(a,b,c,d),)
 SDL_DYNAPI_PROC(void,SDL_GpuEndComputePass,(SDL_GpuComputePass *a),(a),)
 SDL_DYNAPI_PROC(void,SDL_GpuMapTransferBuffer,(SDL_GpuDevice *a, SDL_GpuTransferBuffer *b, SDL_bool c, void **d),(a,b,c,d),)
@@ -1147,7 +1148,6 @@ SDL_DYNAPI_PROC(SDL_bool,SDL_GpuClaimWindow,(SDL_GpuDevice *a, SDL_Window *b, SD
 SDL_DYNAPI_PROC(void,SDL_GpuUnclaimWindow,(SDL_GpuDevice *a, SDL_Window *b),(a,b),)
 SDL_DYNAPI_PROC(void,SDL_GpuSetSwapchainParameters,(SDL_GpuDevice *a, SDL_Window *b, SDL_GpuSwapchainComposition c, SDL_GpuPresentMode d),(a,b,c,d),)
 SDL_DYNAPI_PROC(SDL_GpuTextureFormat,SDL_GpuGetSwapchainTextureFormat,(SDL_GpuDevice *a, SDL_Window *b),(a,b),return)
-SDL_DYNAPI_PROC(SDL_GpuCommandBuffer*,SDL_GpuAcquireCommandBuffer,(SDL_GpuDevice *a),(a),return)
 SDL_DYNAPI_PROC(SDL_GpuTexture*,SDL_GpuAcquireSwapchainTexture,(SDL_GpuCommandBuffer *a, SDL_Window *b, Uint32 *c, Uint32 *d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(void,SDL_GpuSubmit,(SDL_GpuCommandBuffer *a),(a),)
 SDL_DYNAPI_PROC(SDL_GpuFence*,SDL_GpuSubmitAndAcquireFence,(SDL_GpuCommandBuffer *a),(a),return)