EDIT: Docs and minor bug fixed

src/render/rg_graph.cpp

@@ -59,6 +59,15 @@ RGBufferHandle RenderGraph::create_buffer(const RGBufferDesc &desc)
 	return _resources.add_transient(desc);
 }
 
+// Render Graph: builds a per-frame DAG from declared image/buffer accesses,
+// inserts precise barriers and layouts, and records passes using dynamic rendering.
+//
+// Key steps:
+//  - add_pass(): store declarations and callbacks (build to declare, record to issue commands)
+//  - compile():  topologically sort by read/write hazards and generate Vk*Barrier2 sequences
+//  - execute():  emit pre-pass barriers, begin dynamic rendering if attachments exist, invoke record()
+//
+// See docs/RenderGraph.md for API overview and pass patterns.
 void RenderGraph::add_pass(const char *name, RGPassType type, BuildCallback build, RecordCallback record)
 {
 	Pass p{};

src/render/vk_renderpass_geometry.cpp

@@ -15,6 +15,8 @@
 #include "vk_swapchain.h"
 #include "render/rg_graph.h"
 
+// Basic conservative frustum test against RenderObject AABB.
+// Clip space uses Vulkan Z0 (0..w). Returns true if any part of the box is inside.
 bool is_visible(const RenderObject &obj, const glm::mat4 &viewproj)
 {
     const std::array<glm::vec3, 8> corners{

src/render/vk_renderpass_lighting.cpp

@@ -185,7 +185,9 @@ void LightingPass::draw_lighting(VkCommandBuffer cmd,
     vkCmdBindDescriptorSets(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, _pipelineLayout, 1, 1,
                             &_gBufferInputDescriptorSet, 0, nullptr);
 
-    // Allocate and write shadow descriptor set for this frame (set = 2)
+    // Allocate and write shadow descriptor set for this frame (set = 2).
+    // When RT is enabled, TLAS is bound in the global set at (set=0, binding=1)
+    // via DescriptorManager::gpuSceneDataLayout(). See docs/RayTracing.md.
     VkDescriptorSet shadowSet = ctxLocal->currentFrame->_frameDescriptors.allocate(
         deviceManager->device(), _shadowDescriptorLayout);
     {

src/render/vk_renderpass_transparent.cpp

@@ -92,7 +92,9 @@ void TransparentPass::draw_transparent(VkCommandBuffer cmd,
     writer.write_buffer(0, gpuSceneDataBuffer.buffer, sizeof(GPUSceneData), 0, VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER);
     writer.update_set(deviceManager->device(), globalDescriptor);
 
-    // Sort transparent back-to-front using camera-space depth
+    // Sort transparent back-to-front using camera-space depth.
+    // We approximate object depth by transforming the mesh bounds origin.
+    // For better results consider using per-object center or per-draw depth range.
     std::vector<const RenderObject *> draws;
     draws.reserve(dc.TransparentSurfaces.size());
     for (const auto &r: dc.TransparentSurfaces) draws.push_back(&r);