From a34c49f103c8950a57687ea3d866c244d95b4414 Mon Sep 17 00:00:00 2001 From: hachem Date: Mon, 24 Aug 2026 18:28:39 +0200 Subject: [docs]: added a few comments cause i wont be able to read this in a week's time --- src/platform/vulkan/vulkan_common.h | 25 +++++++++++++------------ src/platform/vulkan/vulkan_device.cpp | 4 ++-- src/platform/vulkan/vulkan_device.h | 4 ++-- src/platform/vulkan/vulkan_resources.cpp | 10 +++++----- src/platform/vulkan/vulkan_swapchain.cpp | 8 ++++---- 5 files changed, 26 insertions(+), 25 deletions(-) (limited to 'src/platform/vulkan') diff --git a/src/platform/vulkan/vulkan_common.h b/src/platform/vulkan/vulkan_common.h index 8f02f17..cb86d69 100644 --- a/src/platform/vulkan/vulkan_common.h +++ b/src/platform/vulkan/vulkan_common.h @@ -1,10 +1,10 @@ #pragma once -// Shared internals of the Vulkan RHI backend: the enum-mapping helpers, the +// shared internals of the Vulkan RHI backend: the enum-mapping helpers, the // opaque resource classes (Buffer/Texture/RenderTarget/Pipeline/CommandList), and -// the VulkanDevice declaration. The implementation is split across vulkan_device +// the VulkanDevice declaration. the implementation is split across vulkan_device // (lifecycle + frame loop), vulkan_swapchain (instance/device/swapchain/passes), -// vulkan_resources (buffer/texture/target/pipeline) and vulkan_cubemap. This +// vulkan_resources (buffer/texture/target/pipeline) and vulkan_cubemap. this // header is private to platform/vulkan/ — nothing outside includes it. #include "vulkan_device.h" // rendering/rhi.h (base classes + factory decls) @@ -63,7 +63,7 @@ namespace Donut::RHI inline auto vk_cull(CullMode c) -> VkCullModeFlags { return c == CullMode::None ? VK_CULL_MODE_NONE : c == CullMode::Back ? VK_CULL_MODE_BACK_BIT : VK_CULL_MODE_FRONT_BIT; } - // Buffer: host-visible + coherent, persistently mapped. + // buffer: host-visible + coherent, persistently mapped. class VkBufferR : public Buffer { public: @@ -81,7 +81,7 @@ namespace Donut::RHI VkDevice m_device; VkBuffer m_buf; VkDeviceMemory m_mem; void* m_mapped; size_t m_size; }; - // Texture: sampled image (2D or cube). Owns its handles unless it is a borrowed + // texture: sampled image (2D or cube). owns its handles unless it is a borrowed // wrapper around a render-target view. class VkTextureR : public Texture { @@ -138,7 +138,7 @@ namespace Donut::RHI VkTextureR m_color; // borrowed wrapper (view+sampler) for sampling }; - // Pipeline: the graphics pipeline + its (set-0) descriptor layout. + // pipeline: the graphics pipeline + its (set-0) descriptor layout. class VkPipelineR : public Pipeline { public: @@ -155,8 +155,9 @@ namespace Donut::RHI std::vector m_resources; }; - // CommandList: records into the frame's command buffer. Per-draw descriptor - // sets are allocated from a per-frame pool (no push-descriptor extension). + // CommandList: records into the frame's command buffer. MoltenVK has no + // push-descriptor extension, so we just grab a fresh descriptor set per draw + // from a per-frame pool. kinda wasteful, but it works and that's what counts. class VkCommandListR : public CommandList { public: @@ -219,7 +220,7 @@ namespace Donut::RHI auto draw_indexed(uint32_t index_count) -> void override { flush_descriptors(); vkCmdDrawIndexed(m_cmd, index_count, 1, 0, 0, 0); } - // Allocate + write + bind a descriptor set for the current pipeline's + // allocate + write + bind a descriptor set for the current pipeline's // declared resources, using whatever was bound since bind_pipeline. auto flush_descriptors() -> void { @@ -246,7 +247,7 @@ namespace Donut::RHI vkCmdBindDescriptorSets(m_cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, m_pipe->m_layout, 0, 1, &set, 0, nullptr); } - // Set by the device at begin_frame: + // set by the device at begin_frame: VkDevice m_device = VK_NULL_HANDLE; VkCommandBuffer m_cmd = VK_NULL_HANDLE; VkRenderPass m_swapchain_rp = VK_NULL_HANDLE; @@ -259,7 +260,7 @@ namespace Donut::RHI VkDescriptorImageInfo m_img_info[MAX_BINDINGS]{}; }; - // The backend device. Its methods are defined across vulkan_device.cpp, + // the backend device. its methods are defined across vulkan_device.cpp, // vulkan_swapchain.cpp, vulkan_resources.cpp and vulkan_cubemap.cpp. class VulkanDevice : public Device { @@ -298,7 +299,7 @@ namespace Donut::RHI auto pick_physical_and_device() -> bool; auto create_swapchain() -> bool; auto create_image_views() -> bool; - // Render passes are format-driven and cached: a pipeline/target's + // render passes are format-driven and cached: a pipeline/target's // attachment signature (colour + optional depth, present vs sampled) // maps to one pass. `present` = presented swapchain image. auto get_render_pass(VkFormat color, VkFormat depth, bool present) -> VkRenderPass; diff --git a/src/platform/vulkan/vulkan_device.cpp b/src/platform/vulkan/vulkan_device.cpp index ff2e296..a4f9ac7 100644 --- a/src/platform/vulkan/vulkan_device.cpp +++ b/src/platform/vulkan/vulkan_device.cpp @@ -58,7 +58,7 @@ namespace Donut::RHI if (!pick_physical_and_device()) return false; if (!create_swapchain()) return false; if (!create_image_views()) return false; - // The swapchain is a "present" target: its colour format + a D32 depth. + // the swapchain is a "present" target: its colour format + a D32 depth. m_swapchain_rp = get_render_pass(m_swapchain_format, VK_FORMAT_D32_SFLOAT, true); if (!m_swapchain_rp) return false; if (!create_depth_and_framebuffers())return false; @@ -156,7 +156,7 @@ namespace Donut::RHI VkCommandBuffer cmd; vkAllocateCommandBuffers(m_device, &cbai, &cmd); VkCommandBufferBeginInfo bi{ VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO }; bi.flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT; vkBeginCommandBuffer(cmd, &bi); - // The target ended its render pass in SHADER_READ_ONLY; move it to TRANSFER_SRC to copy. + // the target ended its render pass in SHADER_READ_ONLY; move it to TRANSFER_SRC to copy. VkImageMemoryBarrier b{ VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER }; b.oldLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL; b.newLayout = VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL; b.image = rt->m_image; b.subresourceRange = { VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1 }; diff --git a/src/platform/vulkan/vulkan_device.h b/src/platform/vulkan/vulkan_device.h index efc2433..85cc5ca 100644 --- a/src/platform/vulkan/vulkan_device.h +++ b/src/platform/vulkan/vulkan_device.h @@ -4,13 +4,13 @@ namespace Donut::RHI { - // Vulkan implementation of the RHI Device (MoltenVK on macOS). Owns the + // Vulkan implementation of the RHI Device (MoltenVK on macOS). owns the // instance/device/swapchain and translates the RHI's baked pipelines + // recorded command lists into native Vulkan; the geometry it draws is the // shared SceneRenderer / BlackHoleRenderer, identical to every other backend. auto create_vulkan_device() -> Scope; - // Must run BEFORE glfwInit() when Vulkan is the selected API: points GLFW at + // must run BEFORE glfwInit() when Vulkan is the selected API: points GLFW at // the loader the app links against (its own dlopen fails on macOS/Homebrew) // and configures the MoltenVK ICD / layer paths. auto vulkan_prepare_glfw() -> void; diff --git a/src/platform/vulkan/vulkan_resources.cpp b/src/platform/vulkan/vulkan_resources.cpp index e40ded3..ee2091b 100644 --- a/src/platform/vulkan/vulkan_resources.cpp +++ b/src/platform/vulkan/vulkan_resources.cpp @@ -93,7 +93,7 @@ namespace Donut::RHI smci.addressModeU = smci.addressModeV = smci.addressModeW = VK_SAMPLER_ADDRESS_MODE_CLAMP_TO_EDGE; vkCreateSampler(m_device, &smci, nullptr, &rt->m_sampler); - // Optional depth attachment (for off-screen passes that need a depth test). + // optional depth attachment (for off-screen passes that need a depth test). rt->m_has_depth = depth != Format::None; VkFormat dfmt = VK_FORMAT_UNDEFINED; if (rt->m_has_depth) @@ -126,9 +126,9 @@ namespace Donut::RHI return rt; } - // Builds an environment cubemap from an equirectangular HDRI: render the 6 + // builds an environment cubemap from an equirectangular HDRI: render the 6 // faces with the EquirectToCubemap pipeline, then a full mip chain by - // linear down-blits (so divergence-based LOD reads a blurred sky). Returns + // linear down-blits (so divergence-based LOD reads a blurred sky). returns // a Texture owning the cube image/view/sampler. auto VulkanDevice::create_pipeline(const PipelineDesc& desc) -> Ref @@ -190,8 +190,8 @@ namespace Donut::RHI gpci.stageCount = 2; gpci.pStages = stages; gpci.pVertexInputState = &vin; gpci.pInputAssemblyState = &ia; gpci.pViewportState = &vps; gpci.pRasterizationState = &rs; gpci.pMultisampleState = &ms; gpci.pColorBlendState = &cb; gpci.pDynamicState = &dsci; - // Resolve the target's attachment signature to a (cached) render pass. - // Pipeline<->pass compatibility is by attachment format, so this is the + // resolve the target's attachment signature to a (cached) render pass. + // pipeline<->pass compatibility is by attachment format, so this is the // same pass the matching swapchain / render target renders into. VkFormat pcolor = (desc.target.color == Format::Swapchain) ? m_swapchain_format : vk_format(desc.target.color); VkFormat pdepth = (desc.target.depth == Format::None) ? VK_FORMAT_UNDEFINED : vk_format(desc.target.depth); diff --git a/src/platform/vulkan/vulkan_swapchain.cpp b/src/platform/vulkan/vulkan_swapchain.cpp index 5bf2f60..cbd4512 100644 --- a/src/platform/vulkan/vulkan_swapchain.cpp +++ b/src/platform/vulkan/vulkan_swapchain.cpp @@ -117,8 +117,8 @@ namespace Donut::RHI sci.imageExtent = m_extent; sci.imageArrayLayers = 1; sci.imageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT; sci.preTransform = caps.currentTransform; sci.compositeAlpha = VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR; - // FIFO is always available (vsync). With vsync off, prefer IMMEDIATE - // (uncapped, may tear) then MAILBOX, if the surface supports them. + // FIFO is always there (that's vsync). with vsync off we'd rather have + // IMMEDIATE (uncapped, might tear) then MAILBOX, if the surface is cool with it. VkPresentModeKHR present_mode = VK_PRESENT_MODE_FIFO_KHR; if (!m_vsync) { @@ -153,11 +153,11 @@ namespace Donut::RHI return true; } - // A render pass for one attachment signature, created once and cached. + // a render pass for one attachment signature, created once and cached. // `present` targets (the swapchain) finish PRESENT_SRC and sync on the // colour-output stage; `sampled` targets (off-screen) finish // SHADER_READ_ONLY and round-trip through the fragment shader so the next - // pass can sample them. Depth (VK_FORMAT_UNDEFINED = none) is optional. + // pass can sample them. depth (VK_FORMAT_UNDEFINED = none) is optional. auto VulkanDevice::get_render_pass(VkFormat color, VkFormat depth, bool present) -> VkRenderPass { uint64_t key = (uint64_t)(uint32_t)color -- cgit v1.3