Implement and use type-safe command buffer uniform push wrappers (#59)

* Interleave debug scene render between robot render system opaque and transparent passes

* core : rename { pushVertexUniform => pushVertexUniformRaw }, same for Fragment uniforms

+ only for raw-data

* core : CommandBuffer : add pushVertexUniform(), pushFragmentUniform() type-safe wrappers

* Use type-safe command buffer uniform push wrappers

Author: ManifoldFR

CHANGELOG.md

@@ -13,13 +13,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - core : add `updateTransparencyClassification()` to tag an entity as opaque or untag it (https://github.com/Simple-Robotics/candlewick/pull/57)
 - proper support for transparent objects (https://github.com/Simple-Robotics/candlewick/pull/58)
 - shaders : add WBOIT composite shader, PBR transparent shader, `utils.glsl` util module, `pbr_lighting.glsl` (https://github.com/Simple-Robotics/candlewick/pull/58)
+- core/`CommandBuffer` : type-safe wrappers for pushing uniforms, add `Raw` suffix to raw methods (https://github.com/Simple-Robotics/candlewick/pull/59)
 
 ### Changed
 
 - remove `projMatrix` from PBR shader ubo (https://github.com/Simple-Robotics/candlewick/pull/58)
 - multibody/RobotScene : early return if pipeline is nullptr (https://github.com/Simple-Robotics/candlewick/pull/58)
 - multibody/RobotScene : reorganize pipelines (accomodate for transparent PBR shader)
 - shaders : refactor basic PBR shader (move some functions to new `pbr_lighting.glsl`) (https://github.com/Simple-Robotics/candlewick/pull/58)
+- interleave debug scene render between robot render system opaque and transparent passes
 
 ## [0.0.6] - 2025-05-14
 

examples/Ur5WithSystems.cpp

@@ -467,10 +467,11 @@ int main(int argc, char **argv) {
       renderDepthOnlyPass(command_buffer, depthPassInfo, viewProj, castables);
       switch (g_showDebugViz) {
       case FULL_RENDER:
-        robot_scene.render(command_buffer, g_camera);
+        robot_scene.renderOpaque(command_buffer, g_camera);
         debug_scene.render(command_buffer, g_camera);
         if (showFrustum)
           frustumBoundsDebug.render(command_buffer, g_camera);
+        robot_scene.renderTransparent(command_buffer, g_camera);
         break;
       case DEPTH_DEBUG:
         renderDepthDebug(renderer, command_buffer, depthDebugPass,

src/candlewick/core/CommandBuffer.h

@@ -4,9 +4,16 @@
 #include <SDL3/SDL_gpu.h>
 #include <SDL3/SDL_log.h>
 #include <utility>
+#include <span>
 
 namespace candlewick {
 
+template <typename T>
+concept GpuCompatibleData =
+    std::is_standard_layout_v<T> && !std::is_array_v<T> &&
+    !std::is_pointer_v<T> &&
+    (alignof(T) == 4 || alignof(T) == 8 || alignof(T) == 16);
+
 class CommandBuffer {
   SDL_GPUCommandBuffer *_cmdBuf;
 
@@ -59,15 +66,36 @@ class CommandBuffer {
     }
   }
 
+  template <GpuCompatibleData T>
+  CommandBuffer &pushVertexUniform(Uint32 slot_index, const T &data) {
+    return pushVertexUniformRaw(slot_index, &data, sizeof(T));
+  }
+
+  template <GpuCompatibleData T>
+  CommandBuffer &pushFragmentUniform(Uint32 slot_index, const T &data) {
+    return pushFragmentUniformRaw(slot_index, &data, sizeof(T));
+  }
+
+  template <GpuCompatibleData T>
+  CommandBuffer &pushVertexUniform(Uint32 slot_index, std::span<const T> data) {
+    return pushVertexUniformRaw(slot_index, data.data(), data.size_bytes());
+  }
+
+  template <GpuCompatibleData T>
+  CommandBuffer &pushFragmentUniform(Uint32 slot_index,
+                                     std::span<const T> data) {
+    return pushFragmentUniformRaw(slot_index, data.data(), data.size_bytes());
+  }
+
   /// \brief Push uniform data to the vertex shader.
-  CommandBuffer &pushVertexUniform(Uint32 slot_index, const void *data,
-                                   Uint32 length) {
+  CommandBuffer &pushVertexUniformRaw(Uint32 slot_index, const void *data,
+                                      Uint32 length) {
     SDL_PushGPUVertexUniformData(_cmdBuf, slot_index, data, length);
     return *this;
   }
   /// \brief Push uniform data to the fragment shader.
-  CommandBuffer &pushFragmentUniform(Uint32 slot_index, const void *data,
-                                     Uint32 length) {
+  CommandBuffer &pushFragmentUniformRaw(Uint32 slot_index, const void *data,
+                                        Uint32 length) {
     SDL_PushGPUFragmentUniformData(_cmdBuf, slot_index, data, length);
     return *this;
   }

src/candlewick/core/DebugScene.cpp

@@ -68,11 +68,11 @@ void DebugScene::renderMeshComponents(CommandBuffer &cmdBuf,
     }
 
     const GpuMat4 mvp = viewProj * tr;
-    cmdBuf.pushVertexUniform(TRANSFORM_SLOT, &mvp, sizeof(mvp));
+    cmdBuf.pushVertexUniform(TRANSFORM_SLOT, mvp);
     rend::bindMesh(render_pass, cmd.mesh);
     for (size_t i = 0; i < cmd.mesh.numViews(); i++) {
       const auto &color = cmd.colors[i];
-      cmdBuf.pushFragmentUniform(COLOR_SLOT, &color, sizeof(color));
+      cmdBuf.pushFragmentUniform(COLOR_SLOT, color);
       rend::drawView(render_pass, cmd.mesh.view(i));
     }
   });

src/candlewick/core/DepthAndShadowPass.cpp

@@ -146,7 +146,7 @@ void renderDepthOnlyPass(CommandBuffer &cmdBuf, const DepthPassInfo &passInfo,
     assert(validateMesh(mesh));
     rend::bindMesh(render_pass, mesh);
     mvp.noalias() = viewProj * tr;
-    cmdBuf.pushVertexUniform(DepthPassInfo::TRANSFORM_SLOT, &mvp, sizeof(mvp));
+    cmdBuf.pushVertexUniform(DepthPassInfo::TRANSFORM_SLOT, mvp);
     rend::draw(render_pass, mesh);
   }
 

src/candlewick/core/debug/DepthViz.cpp

@@ -83,7 +83,7 @@ void renderDepthDebug(const Renderer &renderer, CommandBuffer &command_buffer,
   cam_param_ubo_t cam_ubo{opts.mode, opts.near, opts.far,
                           opts.cam_proj == CameraProjection::ORTHOGRAPHIC};
 
-  command_buffer.pushFragmentUniform(0, &cam_ubo, sizeof(cam_ubo));
+  command_buffer.pushFragmentUniform(0, cam_ubo);
   SDL_DrawGPUPrimitives(render_pass, 6, 1, 0, 0);
 
   SDL_EndGPURenderPass(render_pass);

src/candlewick/core/debug/Frustum.cpp

@@ -70,7 +70,7 @@ namespace frustum_debug {
         color,
         eyePos,
     };
-    cmdBuf.pushVertexUniform(0, &ubo, sizeof(ubo));
+    cmdBuf.pushVertexUniform(0, ubo);
 
     SDL_DrawGPUPrimitives(render_pass, NUM_VERTICES, 1, 0, 0);
   }

src/candlewick/multibody/RobotScene.cpp

@@ -301,20 +301,27 @@ void RobotScene::collectOpaqueCastables() {
   });
 }
 
-void RobotScene::render(CommandBuffer &command_buffer, const Camera &camera) {
+void RobotScene::renderOpaque(CommandBuffer &command_buffer,
+                              const Camera &camera) {
   if (m_config.enable_ssao) {
     ssaoPass.render(command_buffer, camera);
   }
 
   renderPBRTriangleGeometry(command_buffer, camera, false);
 
+  renderOtherGeometry(command_buffer, camera);
+}
+
+void RobotScene::renderTransparent(CommandBuffer &command_buffer,
+                                   const Camera &camera) {
   renderPBRTriangleGeometry(command_buffer, camera, true);
 
-  renderOtherGeometry(command_buffer, camera);
+  compositeTransparencyPass(command_buffer);
+}
 
-  // transparent triangle pipeline required
-  if (pipelines.triangleMesh.transparent)
-    compositeTransparencyPass(command_buffer);
+void RobotScene::render(CommandBuffer &command_buffer, const Camera &camera) {
+  renderOpaque(command_buffer, camera);
+  renderTransparent(command_buffer, camera);
 }
 
 /// Function private to this translation unit.
@@ -381,7 +388,8 @@ enum FragmentSamplerSlots {
 };
 
 void RobotScene::compositeTransparencyPass(CommandBuffer &command_buffer) {
-  if (!pipelines.wboitComposite)
+  // transparent triangle pipeline required
+  if (!pipelines.triangleMesh.transparent || !pipelines.wboitComposite)
     return;
 
   SDL_GPUColorTargetInfo target;
@@ -451,10 +459,8 @@ void RobotScene::renderPBRTriangleGeometry(CommandBuffer &command_buffer,
                                  .sampler = ssaoPass.texSampler,
                              }});
   int _useSsao = m_config.enable_ssao;
-  command_buffer
-      .pushFragmentUniform(FragmentUniformSlots::LIGHTING, &lightUbo,
-                           sizeof(lightUbo))
-      .pushFragmentUniform(2, &_useSsao, sizeof(_useSsao));
+  command_buffer.pushFragmentUniform(FragmentUniformSlots::LIGHTING, lightUbo)
+      .pushFragmentUniform(2, _useSsao);
 
   SDL_BindGPUGraphicsPipeline(render_pass, pipeline);
 
@@ -472,17 +478,16 @@ void RobotScene::renderPBRTriangleGeometry(CommandBuffer &command_buffer,
         .mvp = mvp,
         .normalMatrix = math::computeNormalMatrix(modelView),
     };
-    command_buffer.pushVertexUniform(VertexUniformSlots::TRANSFORM, &data,
-                                     sizeof(data));
+    command_buffer.pushVertexUniform(VertexUniformSlots::TRANSFORM, data);
     if (enable_shadows) {
       Mat4f lightMvp = lightViewProj * tr;
-      command_buffer.pushVertexUniform(1, &lightMvp, sizeof(lightMvp));
+      command_buffer.pushVertexUniform(1, lightMvp);
     }
     rend::bindMesh(render_pass, mesh);
     for (size_t j = 0; j < mesh.numViews(); j++) {
       const auto material = obj.materials[j];
       command_buffer.pushFragmentUniform(FragmentUniformSlots::MATERIAL,
-                                         &material, sizeof(material));
+                                         material);
       rend::drawView(render_pass, mesh.view(j));
     }
   };
@@ -524,10 +529,8 @@ void RobotScene::renderOtherGeometry(CommandBuffer &command_buffer,
       const Mesh &mesh = obj.mesh;
       const Mat4f mvp = viewProj * tr;
       const auto &color = obj.materials[0].baseColor;
-      command_buffer
-          .pushVertexUniform(VertexUniformSlots::TRANSFORM, &mvp, sizeof(mvp))
-          .pushFragmentUniform(FragmentUniformSlots::MATERIAL, &color,
-                               sizeof(color));
+      command_buffer.pushVertexUniform(VertexUniformSlots::TRANSFORM, mvp)
+          .pushFragmentUniform(FragmentUniformSlots::MATERIAL, color);
       rend::bindMesh(render_pass, mesh);
       rend::draw(render_pass, mesh);
     }

src/candlewick/multibody/RobotScene.h

@@ -206,6 +206,10 @@ namespace multibody {
     /// this function.
     void render(CommandBuffer &command_buffer, const Camera &camera);
 
+    void renderOpaque(CommandBuffer &command_buffer, const Camera &camera);
+
+    void renderTransparent(CommandBuffer &command_buffer, const Camera &camera);
+
     /// \brief Release all resources.
     void release();
 

src/candlewick/multibody/Visualizer.cpp

@@ -113,8 +113,9 @@ void Visualizer::render() {
                              robotScene.worldSpaceBounds);
 
     auto &camera = controller.camera;
-    robotScene.render(cmdBuf, camera);
+    robotScene.renderOpaque(cmdBuf, camera);
     debugScene.render(cmdBuf, camera);
+    robotScene.renderTransparent(cmdBuf, camera);
     guiSystem.render(cmdBuf);
   }