New debug draw extension for AABBs

CMakeLists.txt

@@ -175,6 +175,7 @@ option(NBL_FAST_MATH "Enable fast low-precision math" OFF) # the reason OFF is b
 option(NBL_BUILD_EXAMPLES "Enable building examples" ON)
 option(NBL_BUILD_MITSUBA_LOADER "Enable nbl::ext::MitsubaLoader?" OFF) # TODO: once it compies turn this ON by default!
 option(NBL_BUILD_IMGUI "Enable nbl::ext::ImGui?" ON)
+option(NBL_BUILD_DEBUG_DRAW "Enable Nabla Debug Draw extension?" ON)
 
 option(NBL_BUILD_OPTIX "Enable nbl::ext::OptiX?" OFF)
 if(NBL_COMPILE_WITH_CUDA)

include/nbl/config/BuildConfigOptions.h.in

@@ -59,6 +59,8 @@
 
 #cmakedefine _NBL_BUILD_DPL_
 
+#cmakedefine NBL_BUILD_DEBUG_DRAW
+
 // !
 // TODO: This has to disapppear from the main header and go to the OptiX extension header + config
 #cmakedefine OPTIX_INCLUDE_DIR "@OPTIX_INCLUDE_DIR@"

include/nbl/ext/DebugDraw/CDrawAABB.h

@@ -0,0 +1,208 @@
+// Copyright (C) 2018-2025 - DevSH Graphics Programming Sp. z O.O.
+// This file is part of the "Nabla Engine".
+// For conditions of distribution and use, see copyright notice in nabla.h
+
+#ifndef _NBL_EXT_DEBUG_DRAW_DRAW_AABB_H_
+#define _NBL_EXT_DEBUG_DRAW_DRAW_AABB_H_
+
+#include "nbl/video/declarations.h"
+#include "nbl/builtin/hlsl/cpp_compat.hlsl"
+#include "nbl/builtin/hlsl/shapes/aabb.hlsl"
+#include "nbl/builtin/hlsl/math/linalg/fast_affine.hlsl"
+#include "nbl/ext/DebugDraw/builtin/hlsl/common.hlsl"
+
+namespace nbl::ext::debug_draw
+{
+    class DrawAABB final : public core::IReferenceCounted
+    {
+    public:
+        static constexpr inline uint32_t IndicesCount = 24u;
+
+        enum DrawMode : uint16_t
+        {
+            ADM_DRAW_SINGLE = 0b01,
+            ADM_DRAW_BATCH = 0b10,
+            ADM_DRAW_BOTH = 0b11
+        };
+
+        struct SCachedCreationParameters
+        {
+            using streaming_buffer_t = video::StreamingTransientDataBufferST<core::allocator<uint8_t>>;
+
+            static constexpr inline auto RequiredAllocateFlags = core::bitflag<video::IDeviceMemoryAllocation::E_MEMORY_ALLOCATE_FLAGS>(video::IDeviceMemoryAllocation::EMAF_DEVICE_ADDRESS_BIT);
+            static constexpr inline auto RequiredUsageFlags = core::bitflag(asset::IBuffer::EUF_STORAGE_BUFFER_BIT) | asset::IBuffer::EUF_SHADER_DEVICE_ADDRESS_BIT;
+
+            DrawMode drawMode = ADM_DRAW_BOTH;
+
+            core::smart_refctd_ptr<video::IUtilities> utilities;
+
+            //! optional, default MDI buffer allocated if not provided
+            core::smart_refctd_ptr<streaming_buffer_t> streamingBuffer = nullptr;
+        };
+
+        struct SCreationParameters : SCachedCreationParameters
+        {
+            video::IQueue* transfer = nullptr;  // only used to make the 24 element index buffer and instanced pipeline on create
+            core::smart_refctd_ptr<asset::IAssetManager> assetManager = nullptr;
+
+            core::smart_refctd_ptr<video::IGPUPipelineLayout> singlePipelineLayout;
+            core::smart_refctd_ptr<video::IGPUPipelineLayout> batchPipelineLayout;
+            core::smart_refctd_ptr<video::IGPURenderpass> renderpass = nullptr;
+
+            inline bool validate() const
+            {
+                const auto validation = std::to_array
+                ({
+                    std::make_pair(bool(assetManager), "Invalid `creationParams.assetManager` is nullptr!"),
+                    std::make_pair(bool(utilities), "Invalid `creationParams.utilities` is nullptr!"),
+                    std::make_pair(bool(transfer), "Invalid `creationParams.transfer` is nullptr!"),
+                    std::make_pair(bool(renderpass), "Invalid `creationParams.renderpass` is nullptr!"),
+                    std::make_pair(bool(utilities->getLogicalDevice()->getPhysicalDevice()->getQueueFamilyProperties()[transfer->getFamilyIndex()].queueFlags.hasFlags(video::IQueue::FAMILY_FLAGS::TRANSFER_BIT)), "Invalid `creationParams.transfer` is not capable of transfer operations!")
+                });
+
+                system::logger_opt_ptr logger = utilities->getLogger();
+                for (const auto& [ok, error] : validation)
+                    if (!ok)
+                    {
+                        logger.log(error, system::ILogger::ELL_ERROR);
+                        return false;
+                    }
+
+                assert(bool(assetManager->getSystem()));
+
+                return true;
+            }
+        };
+
+        struct DrawParameters
+        {
+            video::IGPUCommandBuffer* commandBuffer = nullptr;
+            hlsl::float32_t4x4 cameraMat = hlsl::float32_t4x4(1);
+            float lineWidth = 1.f;
+        };
+
+        // creates an instance that can draw one AABB via push constant or multiple using streaming buffer
+        static core::smart_refctd_ptr<DrawAABB> create(SCreationParameters&& params);
+
+        // creates pipeline layout from push constant range
+        static core::smart_refctd_ptr<video::IGPUPipelineLayout> createPipelineLayoutFromPCRange(video::ILogicalDevice* device, const asset::SPushConstantRange& pcRange);
+
+        // creates default pipeline layout for pipeline specified by draw mode (note: if mode==BOTH, returns layout for BATCH mode)
+        static core::smart_refctd_ptr<video::IGPUPipelineLayout> createDefaultPipelineLayout(video::ILogicalDevice* device, DrawMode mode = ADM_DRAW_BATCH);
+
+        //! mounts the extension's archive to given system - useful if you want to create your own shaders with common header included
+        static const core::smart_refctd_ptr<system::IFileArchive> mount(core::smart_refctd_ptr<system::ILogger> logger, system::ISystem* system, const std::string_view archiveAlias = "");
+
+        inline const SCachedCreationParameters& getCreationParameters() const { return m_cachedCreationParams; }
+
+        // records draw command for single AABB, user has to set pipeline outside
+        bool renderSingle(const DrawParameters& params, const hlsl::shapes::AABB<3, float>& aabb, const hlsl::float32_t4& color);
+
+        // records draw command for rendering batch of AABB instances as InstanceData
+        // user has to set span of filled-in InstanceData; camera matrix used in push constant
+        inline bool render(const DrawParameters& params, video::ISemaphore::SWaitInfo waitInfo, std::span<const InstanceData> aabbInstances)
+        {
+            if (!(m_cachedCreationParams.drawMode & ADM_DRAW_BATCH))
+            {
+                m_cachedCreationParams.utilities->getLogger()->log("DrawAABB has not been enabled for draw batches!", system::ILogger::ELL_ERROR);
+                return false;
+            }
+
+            using offset_t = SCachedCreationParameters::streaming_buffer_t::size_type;
+            constexpr auto MdiSizes = std::to_array<offset_t>({ sizeof(hlsl::float32_t3), sizeof(InstanceData) });
+            // shared nPoT alignment needs to be divisible by all smaller ones to satisfy an allocation from all
+            constexpr offset_t MaxAlignment = std::reduce(MdiSizes.begin(), MdiSizes.end(), 1, [](const offset_t a, const offset_t b)->offset_t {return std::lcm(a, b); });
+            // allocator initialization needs us to round up to PoT
+            const auto MaxPOTAlignment = hlsl::roundUpToPoT(MaxAlignment);
+
+            auto* streaming = m_cachedCreationParams.streamingBuffer.get();
+
+            auto* const streamingPtr = reinterpret_cast<uint8_t*>(streaming->getBufferPointer());
+            assert(streamingPtr);
+
+            auto& commandBuffer = params.commandBuffer;
+            commandBuffer->bindGraphicsPipeline(m_batchPipeline.get());
+            commandBuffer->setLineWidth(params.lineWidth);
+            asset::SBufferBinding<video::IGPUBuffer> indexBinding = { .offset = 0, .buffer = m_indicesBuffer };
+            commandBuffer->bindIndexBuffer(indexBinding, asset::EIT_32BIT);
+
+            auto setInstancesRange = [&](InstanceData* data, uint32_t count) -> void {
+                for (uint32_t i = 0; i < count; i++)
+                {
+                    auto inst = data + i;
+                    *inst = aabbInstances[i];
+                    inst->transform = hlsl::mul(params.cameraMat, inst->transform);
+                }
+                };
+
+            const uint32_t numInstances = aabbInstances.size();
+            const uint32_t instancesPerIter = streaming->getBuffer()->getSize() / sizeof(InstanceData);
+            if (numInstances > instancesPerIter)
+                return false;
+            using suballocator_t = core::LinearAddressAllocatorST<offset_t>;
+            uint32_t beginOffset = 0;
+            while (beginOffset < numInstances)
+            {
+                const uint32_t instanceCount = hlsl::min<uint32_t>(instancesPerIter, numInstances);
+                offset_t inputOffset = 0u;
+                offset_t ImaginarySizeUpperBound = 0x1 << 30;
+                suballocator_t imaginaryChunk(nullptr, inputOffset, 0, hlsl::roundUpToPoT(MaxAlignment), ImaginarySizeUpperBound);
+                uint32_t instancesByteOffset = imaginaryChunk.alloc_addr(sizeof(InstanceData) * instanceCount, sizeof(InstanceData));
+                const uint32_t totalSize = imaginaryChunk.get_allocated_size();
+
+                inputOffset = SCachedCreationParameters::streaming_buffer_t::invalid_value;
+                std::chrono::steady_clock::time_point waitTill = std::chrono::steady_clock::now() + std::chrono::milliseconds(1u);
+                streaming->multi_allocate(waitTill, 1, &inputOffset, &totalSize, &MaxAlignment);
+
+                auto* const streamingInstancesPtr = reinterpret_cast<InstanceData*>(streamingPtr + instancesByteOffset);
+                setInstancesRange(streamingInstancesPtr, instanceCount);
+                beginOffset += instanceCount;
+
+                assert(!streaming->needsManualFlushOrInvalidate());
+
+                SPushConstants pc;
+                pc.pInstanceBuffer = m_cachedCreationParams.streamingBuffer->getBuffer()->getDeviceAddress() + instancesByteOffset;
+
+                commandBuffer->pushConstants(m_batchPipeline->getLayout(), asset::IShader::E_SHADER_STAGE::ESS_VERTEX, 0, sizeof(SPushConstants), &pc);
+                commandBuffer->drawIndexed(IndicesCount, instanceCount, 0, 0, 0);
+
+                streaming->multi_deallocate(1, &inputOffset, &totalSize, waitInfo);
+            }
+
+            return true;
+        }
+
+        static hlsl::float32_t3x4 getTransformFromAABB(const hlsl::shapes::AABB<3, float>& aabb);
+
+    protected:
+        struct ConstructorParams
+        {
+            SCachedCreationParameters creationParams;
+            core::smart_refctd_ptr<video::IGPUGraphicsPipeline> singlePipeline = nullptr;
+            core::smart_refctd_ptr<video::IGPUGraphicsPipeline> batchPipeline = nullptr;
+            core::smart_refctd_ptr<video::IGPUBuffer> indicesBuffer = nullptr;
+        };
+
+	    DrawAABB(ConstructorParams&& params) :
+            m_cachedCreationParams(std::move(params.creationParams)),
+            m_singlePipeline(std::move(params.singlePipeline)),
+            m_batchPipeline(std::move(params.batchPipeline)),
+            m_indicesBuffer(std::move(params.indicesBuffer))
+        {}
+	    ~DrawAABB() override {}
+
+    private:
+        static core::smart_refctd_ptr<video::IGPUGraphicsPipeline> createPipeline(SCreationParameters& params, const video::IGPUPipelineLayout* pipelineLayout, const std::string& vsPath, const std::string& fsPath);
+        static bool createStreamingBuffer(SCreationParameters& params);
+        static core::smart_refctd_ptr<video::IGPUBuffer> createIndicesBuffer(SCreationParameters& params);
+
+        core::smart_refctd_ptr<video::IGPUBuffer> m_indicesBuffer;
+
+        SCachedCreationParameters m_cachedCreationParams;
+
+        core::smart_refctd_ptr<video::IGPUGraphicsPipeline> m_singlePipeline;
+        core::smart_refctd_ptr<video::IGPUGraphicsPipeline> m_batchPipeline;
+};
+}
+
+#endif

include/nbl/ext/DebugDraw/builtin/hlsl/aabb_instances.fragment.hlsl

@@ -0,0 +1,13 @@
+#pragma shader_stage(fragment)
+
+#include "nbl/ext/DebugDraw/builtin/hlsl/common.hlsl"
+
+using namespace nbl::ext::debug_draw;
+
+[shader("pixel")]
+float32_t4 main(PSInput input) : SV_TARGET
+{
+    float32_t4 outColor = input.color;
+
+    return outColor;
+}

include/nbl/ext/DebugDraw/builtin/hlsl/aabb_instances.vertex.hlsl

@@ -0,0 +1,21 @@
+#pragma shader_stage(vertex)
+
+#include "nbl/ext/DebugDraw/builtin/hlsl/common.hlsl"
+
+using namespace nbl::hlsl;
+using namespace nbl::ext::debug_draw;
+
+[[vk::push_constant]] SPushConstants pc;
+
+[shader("vertex")]
+PSInput main()
+{
+    PSInput output;
+    const float32_t3 vertex = getUnitAABBVertex();
+    InstanceData instance = vk::BufferPointer<InstanceData>(pc.pInstanceBuffer + sizeof(InstanceData) * glsl::gl_InstanceIndex()).Get();
+
+    output.position = math::linalg::promoted_mul(instance.transform, vertex);
+    output.color = instance.color;
+
+    return output;
+}

include/nbl/ext/DebugDraw/builtin/hlsl/common.hlsl

@@ -0,0 +1,50 @@
+#ifndef _NBL_DEBUG_DRAW_EXT_COMMON_HLSL
+#define _NBL_DEBUG_DRAW_EXT_COMMON_HLSL
+
+#include "nbl/builtin/hlsl/cpp_compat.hlsl"
+#ifdef __HLSL_VERSION
+#include "nbl/builtin/hlsl/math/linalg/fast_affine.hlsl"
+#include "nbl/builtin/hlsl/glsl_compat/core.hlsl"
+#include "nbl/builtin/hlsl/bda/__ptr.hlsl"
+#endif
+
+namespace nbl
+{
+namespace ext
+{
+namespace debug_draw
+{
+
+struct InstanceData
+{
+    hlsl::float32_t4x4 transform;
+    hlsl::float32_t4 color;
+};
+
+struct SSinglePushConstants
+{
+    InstanceData instance;
+};
+
+struct SPushConstants
+{
+    uint64_t pInstanceBuffer;
+};
+
+#ifdef __HLSL_VERSION
+struct PSInput
+{
+    float32_t4 position : SV_Position;
+    nointerpolation float32_t4 color : TEXCOORD0;
+};
+
+float32_t3 getUnitAABBVertex()
+{
+    return (hlsl::promote<uint32_t3>(hlsl::glsl::gl_VertexIndex()) >> uint32_t3(0,2,1)) & 0x1u;
+}
+#endif
+
+}
+}
+}
+#endif

include/nbl/ext/DebugDraw/builtin/hlsl/single.vertex.hlsl

@@ -0,0 +1,20 @@
+#pragma shader_stage(vertex)
+
+#include "nbl/ext/DebugDraw/builtin/hlsl/common.hlsl"
+
+using namespace nbl::hlsl;
+using namespace nbl::ext::debug_draw;
+
+[[vk::push_constant]] SSinglePushConstants pc;
+
+[shader("vertex")]
+PSInput main()
+{
+    PSInput output;
+    float32_t3 vertex = getUnitAABBVertex();
+
+    output.position = math::linalg::promoted_mul(pc.instance.transform, vertex);
+    output.color = pc.instance.color;
+
+    return output;
+}

include/nbl/system/ISystem.h

@@ -70,6 +70,7 @@ class NBL_API2 ISystem : public core::IReferenceCounted
         //
         virtual inline bool isDirectory(const system::path& p) const
         {
+            // TODO: fix bug, input "nbl/ext/DebugDraw/builtin/hlsl" -> returs true when no such dir present in mounted stuff due to how it uses parent paths in loop (goes up up till matches "nbl" builtin archive and thinks it resolved the requested dir)
             if (isPathReadOnly(p))
                 return p.extension()==""; // TODO: this is a temporary decision until we figure out how to check if a file is directory in android APK
             else

src/nbl/ext/CMakeLists.txt

@@ -54,6 +54,18 @@ if(NBL_BUILD_TEXT_RENDERING)
 	add_subdirectory(TextRendering)
 endif()
 
+if(NBL_BUILD_DEBUG_DRAW)
+    add_subdirectory(DebugDraw)
+    set(NBL_EXT_DEBUG_DRAW_INCLUDE_DIRS
+        ${NBL_EXT_DEBUG_DRAW_INCLUDE_DIRS}
+        PARENT_SCOPE
+    )
+    set(NBL_EXT_DEBUG_DRAW_LIB
+        ${NBL_EXT_DEBUG_DRAW_LIB}
+        PARENT_SCOPE
+    )
+endif()
+
 propagate_changed_variables_to_parent_scope()
 
 NBL_ADJUST_FOLDERS(ext)