usage.cpp

// Illustrative usage of vkdd. This is compiled as a sample only when a real
// Vulkan SDK (loader) is present, since it links vkCmd* at runtime. The handles
// here are assumed to come from your own renderer.
#include <vkdd/vkdd.h>

using namespace vkm; // vec3, mat4, perspective, look_at, ...

// Called once at startup, after your VkDevice exists.
static vkdd::DebugDraw setup(VkPhysicalDevice phys, VkDevice device, VkFormat color, VkFormat depth) {
    vkdd::DebugDraw dd;
    vkdd::InitInfo info;
    info.physicalDevice = phys;
    info.device = device;
    info.colorFormat = color;
    info.depthFormat = depth;
    info.framesInFlight = 2;
    info.maxLineVertices = 1u << 18; // lots of grid/wire geometry
    if (!dd.init(info)) {
        // handle failure in your app (bad handles, OOM, pipeline error)
    }
    return dd;
}

// Called every frame. `cmd` must already be in the recording state.
static void renderFrame(vkdd::DebugDraw& dd, VkCommandBuffer cmd, VkExtent2D extent, float dt) {
    // 1) queue shapes (world space). Pass dt so timed shapes age out.
    dd.reset(dt);
    dd.grid();
    dd.axisTriad(mat4::identity(), 1.0f);

    dd.filled();
    dd.box(vec3{0, 0.5f, 0}, vec3{1, 1, 1}, vkdd::CYAN);
    dd.sphere(vec3{2, 1, 0}, 0.75f, vkdd::GREEN);
    dd.cone(vec3{-2, 0, 0}, vkm::up, vkdd::MAGENTA, 0.5f, 1.5f);
    dd.cylinder(vec3{-4, 0, 0}, vkm::up, vkdd::LIME, 0.4f, 1.2f);
    dd.capsule(vec3{4, 0.5f, 0}, vec3{4, 2.0f, 0}, 0.4f, vkdd::ORANGE);

    dd.wire();
    dd.sphere(vec3{2, 1, 0}, 0.85f, vkdd::WHITE);

    dd.arrow(vec3{0, 0, 0}, vec3{0, 2, 2}, vkdd::RED);

    // thick lines (needs the viewport passed to draw())
    dd.lineWidth(3.0f);
    dd.line(vec3{-5, 0, -5}, vec3{5, 0, 5}, vkdd::YELLOW);
    dd.lineWidth(1.0f);

    dd.point(vec3{0, 3, 0}, vkdd::WHITE, 8.0f);
    dd.plane(vec3{0, 0, -3}, vkm::up, 2.0f, vkdd::YELLOW, 1.0f);

    // extra primitives
    dd.cross(vec3{1, 1, 1}, 0.3f, vkdd::WHITE);
    dd.bezier({-3, 0, 3}, {-1, 3, 3}, {1, 3, 3}, {3, 0, 3}, vkdd::CYAN);
    dd.arc(vec3{0, 0, 0}, vkm::up, vkm::right, vkm::pi, 1.5f, vkdd::ORANGE);

    // x-ray overlay (shows through geometry), translucent fill, channels
    dd.noDepth();
    dd.alpha(0.4f);
    dd.box(vec3{0, 0.5f, 0}, vec3{1.2f, 1.2f, 1.2f}, vkdd::RED);
    dd.alpha(1.0f);
    dd.depthTest(true);

    dd.channel("collision");
    dd.duration(2.0f);                       // persists 2s — good for one-frame events
    dd.sphere(vec3{5, 1, 5}, 0.3f, vkdd::RED);
    dd.duration(0.0f);
    dd.setChannelEnabled("collision", true); // toggle whole categories on/off

    // instanced shapes (one draw call for many)
    for (int i = 0; i < 50; ++i)
        dd.boxInstanced(vec3{float(i) * 0.5f - 12.0f, 0.25f, -6.0f}, vec3{0.4f, 0.4f, 0.4f}, vkdd::LIME);

    // transform stack: queue in local space
    dd.pushTransform(vkm::translate(vec3{0, 2, -2}) * vkm::rotate(0.5f, vkm::up));
    dd.axisTriad(mat4::identity(), 0.5f);
    dd.popTransform();

    // text: screen-space HUD and a world-space label
    dd.text2d(10.0f, 10.0f, "vkdd debug overlay", vkdd::WHITE, 2.0f);
    dd.text3d(vec3{0, 2.5f, 0}, "origin", vkdd::YELLOW, 1.5f);

    // 2) build the camera matrix and visualize a second camera's frustum
    mat4 view = look_at(vec3{6, 5, 8}, vec3{0, 0, 0}, vkm::up);
    mat4 proj = perspective(rad(60.0f), float(extent.width) / float(extent.height), 0.1f, 100.0f);
    mat4 viewProj = proj * view;
    dd.frustum(viewProj, vkdd::PURPLE);

    // 3) upload (OUTSIDE your render pass), then draw (INSIDE it)
    dd.update(cmd);

    VkViewport vp{0, 0, float(extent.width), float(extent.height), 0.0f, 1.0f};
    VkRect2D scissor{{0, 0}, extent};
    vkCmdSetViewport(cmd, 0, 1, &vp);
    vkCmdSetScissor(cmd, 0, 1, &scissor);

    // ... vkCmdBeginRendering(cmd, ...) with the same color/depth formats ...
    dd.draw(viewProj, cmd, extent); // pass extent so thick lines / text size correctly
    // ... vkCmdEndRendering(cmd) ...
}

int main() {
    // This sample is structural; wire it to your own Vulkan setup to run it.
    (void)&setup;
    (void)&renderFrame;
    return 0;
}