showcase.cpp

// vkdd showcase — a real, runnable window that draws (nearly) every primitive the
// library offers, so you can see them all at once.
//
//   ./vkdd_showcase                       # orbiting camera, press ESC / Q to quit
//   ./vkdd_showcase --screenshot out.ppm  # render one frame headlessly-ish and exit
//   ./vkdd_showcase --frames 120          # which animation frame to capture
//
// Everything below the SCENE marker is vkdd usage; everything above it is the
// bog-standard SDL2 + Vulkan 1.3 dynamic-rendering setup you already have in your
// own engine.
#include <vkdd/vkdd.h>

#include <SDL2/SDL.h>
#include <SDL2/SDL_vulkan.h>

#include <cmath>
#include <cstdio>
#include <cstring>
#include <string>
#include <vector>

using namespace vkm;

#define VK_CHECK(x)                                                                     \
    do {                                                                                \
        VkResult _r = (x);                                                              \
        if (_r != VK_SUCCESS) {                                                         \
            std::fprintf(stderr, "%s:%d vulkan error %d\n", __FILE__, __LINE__, _r);   \
            std::exit(1);                                                               \
        }                                                                               \
    } while (0)

namespace {

constexpr std::uint32_t kFramesInFlight = 2;

struct Frame {
    VkCommandPool   pool  = VK_NULL_HANDLE;
    VkCommandBuffer cmd   = VK_NULL_HANDLE;
    VkFence         fence = VK_NULL_HANDLE;
    VkSemaphore     acquired = VK_NULL_HANDLE;
};

struct App {
    SDL_Window* window = nullptr;

    VkInstance       instance = VK_NULL_HANDLE;
    VkSurfaceKHR     surface  = VK_NULL_HANDLE;
    VkPhysicalDevice phys     = VK_NULL_HANDLE;
    VkDevice         device   = VK_NULL_HANDLE;
    std::uint32_t    queueFamily = 0;
    VkQueue          queue    = VK_NULL_HANDLE;

    VkSwapchainKHR           swapchain = VK_NULL_HANDLE;
    VkFormat                 colorFormat = VK_FORMAT_B8G8R8A8_UNORM;
    VkFormat                 depthFormat = VK_FORMAT_D32_SFLOAT;
    VkExtent2D               extent{};
    std::vector<VkImage>     images;
    std::vector<VkImageView> views;
    std::vector<VkSemaphore> rendered; // one per swapchain image

    VkImage        depthImage = VK_NULL_HANDLE;
    VkDeviceMemory depthMemory = VK_NULL_HANDLE;
    VkImageView    depthView  = VK_NULL_HANDLE;

    Frame frames[kFramesInFlight];
};

std::uint32_t findMemoryType(VkPhysicalDevice phys, std::uint32_t bits, VkMemoryPropertyFlags want) {
    VkPhysicalDeviceMemoryProperties props{};
    vkGetPhysicalDeviceMemoryProperties(phys, &props);
    for (std::uint32_t i = 0; i < props.memoryTypeCount; ++i)
        if ((bits & (1u << i)) && (props.memoryTypes[i].propertyFlags & want) == want) return i;
    std::fprintf(stderr, "no suitable memory type\n");
    std::exit(1);
}

void imageBarrier(VkCommandBuffer cmd, VkImage image, VkImageAspectFlags aspect,
                  VkImageLayout from, VkImageLayout to, VkAccessFlags srcAccess,
                  VkAccessFlags dstAccess, VkPipelineStageFlags srcStage,
                  VkPipelineStageFlags dstStage) {
    VkImageMemoryBarrier b{VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER};
    b.srcAccessMask = srcAccess;
    b.dstAccessMask = dstAccess;
    b.oldLayout = from;
    b.newLayout = to;
    b.srcQueueFamilyIndex = b.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
    b.image = image;
    b.subresourceRange = {aspect, 0, 1, 0, 1};
    vkCmdPipelineBarrier(cmd, srcStage, dstStage, 0, 0, nullptr, 0, nullptr, 1, &b);
}

// ---- setup -------------------------------------------------------------------

void createInstance(App& app) {
    unsigned n = 0;
    SDL_Vulkan_GetInstanceExtensions(app.window, &n, nullptr);
    std::vector<const char*> exts(n);
    SDL_Vulkan_GetInstanceExtensions(app.window, &n, exts.data());

    VkApplicationInfo ai{VK_STRUCTURE_TYPE_APPLICATION_INFO};
    ai.pApplicationName = "vkdd showcase";
    ai.apiVersion = VK_API_VERSION_1_3;

    VkInstanceCreateInfo ci{VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO};
    ci.pApplicationInfo = &ai;
    ci.enabledExtensionCount = std::uint32_t(exts.size());
    ci.ppEnabledExtensionNames = exts.data();
    VK_CHECK(vkCreateInstance(&ci, nullptr, &app.instance));
}

void pickDeviceAndQueue(App& app) {
    std::uint32_t count = 0;
    vkEnumeratePhysicalDevices(app.instance, &count, nullptr);
    std::vector<VkPhysicalDevice> devices(count);
    vkEnumeratePhysicalDevices(app.instance, &count, devices.data());

    for (VkPhysicalDevice d : devices) {
        std::uint32_t qcount = 0;
        vkGetPhysicalDeviceQueueFamilyProperties(d, &qcount, nullptr);
        std::vector<VkQueueFamilyProperties> qs(qcount);
        vkGetPhysicalDeviceQueueFamilyProperties(d, &qcount, qs.data());
        for (std::uint32_t i = 0; i < qcount; ++i) {
            VkBool32 present = VK_FALSE;
            vkGetPhysicalDeviceSurfaceSupportKHR(d, i, app.surface, &present);
            if ((qs[i].queueFlags & VK_QUEUE_GRAPHICS_BIT) && present) {
                VkPhysicalDeviceProperties props{};
                vkGetPhysicalDeviceProperties(d, &props);
                // Prefer a discrete GPU, but take the first match if that's all there is.
                if (app.phys == VK_NULL_HANDLE ||
                    props.deviceType == VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU) {
                    app.phys = d;
                    app.queueFamily = i;
                }
                break;
            }
        }
    }
    if (!app.phys) {
        std::fprintf(stderr, "no Vulkan device with graphics+present\n");
        std::exit(1);
    }
    VkPhysicalDeviceProperties props{};
    vkGetPhysicalDeviceProperties(app.phys, &props);
    std::printf("vkdd showcase: %s\n", props.deviceName);
}

void createDevice(App& app) {
    float priority = 1.0f;
    VkDeviceQueueCreateInfo qi{VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO};
    qi.queueFamilyIndex = app.queueFamily;
    qi.queueCount = 1;
    qi.pQueuePriorities = &priority;

    VkPhysicalDeviceVulkan13Features f13{VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES};
    f13.dynamicRendering = VK_TRUE;

    VkPhysicalDeviceFeatures2 f2{VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2};
    f2.pNext = &f13;
    f2.features.fillModeNonSolid = VK_TRUE;
    f2.features.wideLines = VK_TRUE;

    const char* deviceExts[] = {VK_KHR_SWAPCHAIN_EXTENSION_NAME};

    VkDeviceCreateInfo ci{VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO};
    ci.pNext = &f2;
    ci.queueCreateInfoCount = 1;
    ci.pQueueCreateInfos = &qi;
    ci.enabledExtensionCount = 1;
    ci.ppEnabledExtensionNames = deviceExts;
    VK_CHECK(vkCreateDevice(app.phys, &ci, nullptr, &app.device));
    vkGetDeviceQueue(app.device, app.queueFamily, 0, &app.queue);
}

void createSwapchain(App& app) {
    VkSurfaceCapabilitiesKHR caps{};
    VK_CHECK(vkGetPhysicalDeviceSurfaceCapabilitiesKHR(app.phys, app.surface, &caps));
    app.extent = caps.currentExtent;

    std::uint32_t n = 0;
    vkGetPhysicalDeviceSurfaceFormatsKHR(app.phys, app.surface, &n, nullptr);
    std::vector<VkSurfaceFormatKHR> formats(n);
    vkGetPhysicalDeviceSurfaceFormatsKHR(app.phys, app.surface, &n, formats.data());
    app.colorFormat = formats[0].format;
    VkColorSpaceKHR colorSpace = formats[0].colorSpace;
    for (const auto& f : formats)
        if (f.format == VK_FORMAT_B8G8R8A8_UNORM) { // linear-ish: what vkdd's colors assume
            app.colorFormat = f.format;
            colorSpace = f.colorSpace;
            break;
        }

    VkSwapchainCreateInfoKHR ci{VK_STRUCTURE_TYPE_SWAPCHAIN_CREATE_INFO_KHR};
    ci.surface = app.surface;
    ci.minImageCount = caps.minImageCount < 3 ? caps.minImageCount + 1 : caps.minImageCount;
    if (caps.maxImageCount && ci.minImageCount > caps.maxImageCount) ci.minImageCount = caps.maxImageCount;
    ci.imageFormat = app.colorFormat;
    ci.imageColorSpace = colorSpace;
    ci.imageExtent = app.extent;
    ci.imageArrayLayers = 1;
    ci.imageUsage = VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT | VK_IMAGE_USAGE_TRANSFER_SRC_BIT;
    ci.imageSharingMode = VK_SHARING_MODE_EXCLUSIVE;
    ci.preTransform = caps.currentTransform;
    ci.compositeAlpha = VK_COMPOSITE_ALPHA_OPAQUE_BIT_KHR;
    ci.presentMode = VK_PRESENT_MODE_FIFO_KHR;
    ci.clipped = VK_TRUE;
    VK_CHECK(vkCreateSwapchainKHR(app.device, &ci, nullptr, &app.swapchain));

    vkGetSwapchainImagesKHR(app.device, app.swapchain, &n, nullptr);
    app.images.resize(n);
    vkGetSwapchainImagesKHR(app.device, app.swapchain, &n, app.images.data());

    app.views.resize(n);
    app.rendered.resize(n);
    for (std::uint32_t i = 0; i < n; ++i) {
        VkImageViewCreateInfo vi{VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO};
        vi.image = app.images[i];
        vi.viewType = VK_IMAGE_VIEW_TYPE_2D;
        vi.format = app.colorFormat;
        vi.subresourceRange = {VK_IMAGE_ASPECT_COLOR_BIT, 0, 1, 0, 1};
        VK_CHECK(vkCreateImageView(app.device, &vi, nullptr, &app.views[i]));

        VkSemaphoreCreateInfo si{VK_STRUCTURE_TYPE_SEMAPHORE_CREATE_INFO};
        VK_CHECK(vkCreateSemaphore(app.device, &si, nullptr, &app.rendered[i]));
    }

    // Depth attachment.
    VkImageCreateInfo ii{VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO};
    ii.imageType = VK_IMAGE_TYPE_2D;
    ii.format = app.depthFormat;
    ii.extent = {app.extent.width, app.extent.height, 1};
    ii.mipLevels = ii.arrayLayers = 1;
    ii.samples = VK_SAMPLE_COUNT_1_BIT;
    ii.tiling = VK_IMAGE_TILING_OPTIMAL;
    ii.usage = VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT;
    ii.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;
    VK_CHECK(vkCreateImage(app.device, &ii, nullptr, &app.depthImage));

    VkMemoryRequirements req{};
    vkGetImageMemoryRequirements(app.device, app.depthImage, &req);
    VkMemoryAllocateInfo mi{VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO};
    mi.allocationSize = req.size;
    mi.memoryTypeIndex = findMemoryType(app.phys, req.memoryTypeBits, VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT);
    VK_CHECK(vkAllocateMemory(app.device, &mi, nullptr, &app.depthMemory));
    VK_CHECK(vkBindImageMemory(app.device, app.depthImage, app.depthMemory, 0));

    VkImageViewCreateInfo dvi{VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO};
    dvi.image = app.depthImage;
    dvi.viewType = VK_IMAGE_VIEW_TYPE_2D;
    dvi.format = app.depthFormat;
    dvi.subresourceRange = {VK_IMAGE_ASPECT_DEPTH_BIT, 0, 1, 0, 1};
    VK_CHECK(vkCreateImageView(app.device, &dvi, nullptr, &app.depthView));
}

void createFrames(App& app) {
    for (auto& f : app.frames) {
        VkCommandPoolCreateInfo pi{VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO};
        pi.flags = VK_COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT;
        pi.queueFamilyIndex = app.queueFamily;
        VK_CHECK(vkCreateCommandPool(app.device, &pi, nullptr, &f.pool));

        VkCommandBufferAllocateInfo ai{VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO};
        ai.commandPool = f.pool;
        ai.level = VK_COMMAND_BUFFER_LEVEL_PRIMARY;
        ai.commandBufferCount = 1;
        VK_CHECK(vkAllocateCommandBuffers(app.device, &ai, &f.cmd));

        VkFenceCreateInfo fi{VK_STRUCTURE_TYPE_FENCE_CREATE_INFO};
        fi.flags = VK_FENCE_CREATE_SIGNALED_BIT;
        VK_CHECK(vkCreateFence(app.device, &fi, nullptr, &f.fence));

        VkSemaphoreCreateInfo si{VK_STRUCTURE_TYPE_SEMAPHORE_CREATE_INFO};
        VK_CHECK(vkCreateSemaphore(app.device, &si, nullptr, &f.acquired));
    }
}

void destroyApp(App& app) {
    vkDeviceWaitIdle(app.device);
    for (auto& f : app.frames) {
        vkDestroySemaphore(app.device, f.acquired, nullptr);
        vkDestroyFence(app.device, f.fence, nullptr);
        vkDestroyCommandPool(app.device, f.pool, nullptr);
    }
    vkDestroyImageView(app.device, app.depthView, nullptr);
    vkDestroyImage(app.device, app.depthImage, nullptr);
    vkFreeMemory(app.device, app.depthMemory, nullptr);
    for (auto s : app.rendered) vkDestroySemaphore(app.device, s, nullptr);
    for (auto v : app.views) vkDestroyImageView(app.device, v, nullptr);
    vkDestroySwapchainKHR(app.device, app.swapchain, nullptr);
    vkDestroyDevice(app.device, nullptr);
    vkDestroySurfaceKHR(app.instance, app.surface, nullptr);
    vkDestroyInstance(app.instance, nullptr);
    SDL_DestroyWindow(app.window);
    SDL_Quit();
}

// ---- SCENE -------------------------------------------------------------------
// From here down it's all vkdd.

// Rainbow helper so every shape gets its own hue.
vec3 hue(float t) {
    t = t - std::floor(t);
    auto f = [&](float o) { return 0.5f + 0.5f * std::cos(6.28318f * (t + o)); };
    return vec3{f(0.0f), f(0.33f), f(0.67f)};
}

void buildScene(vkdd::DebugDraw& dd, float time, VkExtent2D extent) {
    // Ground plane + world origin.
    dd.grid(-17.0f, 17.0f, 0.0f, 1.0f, vec3{0.22f, 0.24f, 0.30f});
    dd.axisTriad(mat4::identity(), 1.5f);
    dd.text3d(vec3{0, -0.35f, 0}, "origin", vkdd::GRAY, 1.5f);

    // ---- front row: filled volumetric primitives, one hue each ---------------
    dd.filled();
    const float y = 0.9f;
    dd.box(vec3{-7.5f, y, 0}, vec3{1.4f, 1.6f, 1.4f}, hue(0.00f));
    dd.sphere(vec3{-5.0f, y, 0}, 0.85f, hue(0.08f), 24);
    dd.cone(vec3{-2.5f, 0.0f, 0}, vkm::up, hue(0.16f), 0.8f, 1.9f);
    dd.cylinder(vec3{0.0f, 0.0f, 0}, vkm::up, hue(0.24f), 0.7f, 1.8f);
    dd.capsule(vec3{2.5f, 0.6f, 0}, vec3{2.5f, 1.8f, 0}, 0.6f, hue(0.32f));
    dd.disc(vec3{5.0f, 0.02f, 0}, vkm::up, 1.0f, hue(0.40f));
    dd.ring(vec3{7.5f, 0.02f, 0}, vkm::up, 0.5f, 1.0f, hue(0.48f));

    const char* names[] = {"box", "sphere", "cone", "cylinder", "capsule", "disc", "ring"};
    for (int i = 0; i < 7; ++i)
        dd.text3d(vec3{-7.5f + float(i) * 2.5f, 2.3f, 0}, names[i], vkdd::WHITE, 1.5f);

    // ---- back row: the same shapes in wireframe ------------------------------
    dd.wire();
    const float z = -3.5f;
    dd.box(vec3{-7.5f, y, z}, vec3{1.4f, 1.6f, 1.4f}, hue(0.55f));
    dd.sphere(vec3{-5.0f, y, z}, 0.85f, hue(0.62f), 16);
    dd.cone(vec3{-2.5f, 0.0f, z}, vkm::up, hue(0.68f), 0.8f, 1.9f);
    dd.cylinder(vec3{0.0f, 0.0f, z}, vkm::up, hue(0.74f), 0.7f, 1.8f);
    dd.capsule(vec3{2.5f, 0.6f, z}, vec3{2.5f, 1.8f, z}, 0.6f, hue(0.80f));
    dd.circle(vec3{5.0f, 0.02f, z}, vkm::up, 1.0f, hue(0.86f));
    dd.ring(vec3{7.5f, 0.02f, z}, vkm::up, 0.5f, 1.0f, hue(0.92f));
    dd.aabb(vec3{-9.8f, 0.0f, -4.6f}, vec3{-8.8f, 1.8f, -2.4f}, vkdd::LIME);
    dd.text3d(vec3{-9.3f, 2.6f, -3.5f}, "aabb", vkdd::LIME, 1.5f);
    dd.filled();

    // ---- lines, curves, arrows ----------------------------------------------
    dd.arrow(vec3{0, 0, 5.0f}, vec3{0, 2.6f, 5.0f}, vkdd::RED, 0.25f);
    dd.arrow(vec3{0, 0, 5.0f}, vec3{2.4f, 0.8f, 5.0f}, vkdd::YELLOW, 0.25f);
    dd.text3d(vec3{0, 3.2f, 5.0f}, "arrow", vkdd::RED, 1.5f);

    dd.bezier(vec3{-9, 0.2f, 5.0f}, vec3{-7, 3.5f, 5.0f}, vec3{-5, -1.5f, 5.0f},
              vec3{-3, 2.0f, 5.0f}, vkdd::CYAN, 48);
    dd.text3d(vec3{-6, 3.0f, 5.0f}, "bezier", vkdd::CYAN, 1.5f);

    vec3 poly[] = {{3.5f, 0.3f, 5.0f}, {4.5f, 1.8f, 5.0f}, {5.5f, 0.5f, 5.0f},
                   {6.5f, 2.2f, 5.0f}, {7.5f, 0.8f, 5.0f}};
    dd.lineWidth(3.0f); // thick screen-space lines
    dd.polyline(std::span<const vec3>(poly, 5), vkdd::MAGENTA);
    dd.lineWidth(1.0f);
    dd.text3d(vec3{5.5f, 3.0f, 5.0f}, "polyline (3px)", vkdd::MAGENTA, 1.5f);

    dd.arc(vec3{9.8f, 0.5f, 2.6f}, vkm::up, vkm::right, vkm::pi * 1.25f, 1.2f, vkdd::ORANGE);
    dd.cross(vec3{9.8f, 0.5f, 2.6f}, 0.4f, vkdd::WHITE);
    dd.point(vec3{9.8f, 2.0f, 2.6f}, vkdd::WHITE, 10.0f);

    dd.plane(vec3{-10.0f, 1.2f, 1.5f}, normalize(vec3{1, 0.6f, 0.2f}), 1.6f, vkdd::YELLOW, 1.2f);
    dd.text3d(vec3{-10.0f, 2.6f, 1.5f}, "plane + normal", vkdd::YELLOW, 1.5f);

    // A triangle with its vertex normals visualized.
    const vec3 tri[] = {{10.0f, 0.2f, -1.2f}, {11.6f, 0.2f, 0.6f}, {10.6f, 2.0f, -0.2f}};
    const vec3 norms[] = {normalize(vec3{0.2f, 0.6f, 0.8f}), normalize(vec3{0.5f, 0.5f, 0.7f}),
                          normalize(vec3{0.1f, 0.9f, 0.4f})};
    dd.triangle(tri[0], tri[1], tri[2], hue(0.5f));
    dd.normals(std::span<const vec3>(tri, 3), std::span<const vec3>(norms, 3), 0.9f, vkdd::CYAN);
    dd.text3d(vec3{10.7f, 2.6f, -0.2f}, "normals", vkdd::CYAN, 1.5f);

    // duration() + channel(): a "hit marker" fires once a second and lingers 1.5s,
    // tagged so a whole category can be toggled off with setChannelEnabled().
    dd.channel("hits");
    static int lastPulse = -1;
    const int pulse = int(time);
    if (pulse != lastPulse) {
        lastPulse = pulse;
        dd.duration(1.5f); // outlives the frame it was queued in
        dd.wire();
        dd.sphere(vec3{-10.5f, 1.0f + 0.4f * float(pulse % 3), -6.5f}, 0.9f, vkdd::RED, 12);
        dd.filled();
        dd.duration(0.0f);
    }
    dd.text3d(vec3{-10.5f, 3.4f, -6.5f}, "duration + channel", vkdd::RED, 1.5f);
    dd.channel("default"); // back to the default channel

    // ---- animated instanced field (one draw call for the lot) ---------------
    for (int gx = 0; gx < 16; ++gx) {
        for (int gz = 0; gz < 8; ++gz) {
            float fx = float(gx) - 7.5f, fz = float(gz);
            float h = 0.35f + 0.3f * std::sin(time * 1.6f + fx * 0.5f + fz * 0.4f) + 0.35f;
            vec3 pos{fx * 0.8f, h * 0.5f, -7.0f - fz * 0.8f};
            dd.boxInstanced(pos, vec3{0.5f, h, 0.5f}, hue(0.05f * float(gx + gz) + time * 0.1f));
        }
    }
    for (int i = 0; i < 12; ++i) {
        float a = time * 0.5f + float(i) * (6.28318f / 12.0f);
        dd.sphereInstanced(vec3{std::cos(a) * 11.0f, 1.2f + std::sin(a * 3.0f) * 0.6f,
                                std::sin(a) * 11.0f},
                           0.35f, hue(float(i) / 12.0f));
    }
    dd.text3d(vec3{0, 2.2f, -10.0f}, "instanced (2 draw calls)", vkdd::LIME, 1.5f);

    // ---- transform stack: an orbiting, spinning local-space rig --------------
    dd.pushTransform(vkm::rotate(time * 0.6f, vkm::up) * vkm::translate(vec3{6.5f, 3.2f, 6.5f}) *
                     vkm::rotate(time * 1.3f, normalize(vec3{1, 1, 0})));
    dd.filled();
    dd.box(vec3{0, 0, 0}, vec3{1.0f, 1.0f, 1.0f}, hue(time * 0.2f));
    dd.wire();
    dd.box(vec3{0, 0, 0}, vec3{1.3f, 1.3f, 1.3f}, vkdd::WHITE);
    dd.axisTriad(mat4::identity(), 1.2f);
    dd.filled();
    dd.popTransform();

    // ---- translucency + x-ray overlay ---------------------------------------
    dd.alpha(0.35f);
    dd.sphere(vec3{-5.0f, 0.9f, 0}, 1.4f, vkdd::CYAN, 24); // glass shell over the sphere
    dd.alpha(1.0f);

    dd.noDepth(); // draws through everything — good for finding occluded things
    dd.wire();
    dd.box(vec3{-7.5f, 0.9f, 0}, vec3{2.0f, 2.2f, 2.0f}, vkdd::RED);
    dd.text3d(vec3{-7.5f, -0.4f, 0}, "x-ray", vkdd::RED, 1.5f);
    dd.filled();
    dd.depthTest(true);

    // ---- another camera's frustum -------------------------------------------
    mat4 otherView = look_at(vec3{-11.0f, 4.5f, 8.0f}, vec3{-7.0f, 1.0f, 2.0f}, vkm::up);
    mat4 otherProj = perspective(rad(30.0f), 1.6f, 1.0f, 5.5f);
    dd.frustum(otherProj * otherView, vkdd::PURPLE);
    dd.text3d(vec3{-11.0f, 5.2f, 8.0f}, "frustum", vkdd::PURPLE, 1.5f);

    // ---- screen-space HUD text ----------------------------------------------
    dd.text2d(16, 16, "vkdd - immediate-mode debug draw for vulkan", vkdd::WHITE, 3.0f);
    dd.text2d(16, 48, "filled + wire volumetrics, curves, text, instancing, x-ray",
              vec3{0.6f, 0.7f, 0.8f}, 2.0f);

    char buf[128];
    const auto s = dd.stats();
    std::snprintf(buf, sizeof(buf), "lines %u  tris %u  points %u", s.lineVertices,
                  s.triangleVertices, s.pointVertices);
    dd.text2d(16, float(extent.height) - 32.0f, buf, vkdd::LIME, 2.0f);
    dd.text2d(float(extent.width) - 272.0f, 16.0f, "esc / q to quit", vkdd::GRAY, 2.0f);
}

// ---- screenshot ---------------------------------------------------------------

void writePPM(const App& app, VkImage src, const char* path) {
    const VkDeviceSize size = VkDeviceSize(app.extent.width) * app.extent.height * 4;

    VkBufferCreateInfo bi{VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO};
    bi.size = size;
    bi.usage = VK_BUFFER_USAGE_TRANSFER_DST_BIT;
    VkBuffer buffer = VK_NULL_HANDLE;
    VK_CHECK(vkCreateBuffer(app.device, &bi, nullptr, &buffer));

    VkMemoryRequirements req{};
    vkGetBufferMemoryRequirements(app.device, buffer, &req);
    VkMemoryAllocateInfo mi{VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO};
    mi.allocationSize = req.size;
    mi.memoryTypeIndex = findMemoryType(app.phys, req.memoryTypeBits,
                                        VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
                                            VK_MEMORY_PROPERTY_HOST_COHERENT_BIT);
    VkDeviceMemory memory = VK_NULL_HANDLE;
    VK_CHECK(vkAllocateMemory(app.device, &mi, nullptr, &memory));
    VK_CHECK(vkBindBufferMemory(app.device, buffer, memory, 0));

    // One-shot copy: swapchain image (already in PRESENT_SRC) -> host buffer.
    VkCommandBufferAllocateInfo ai{VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO};
    ai.commandPool = app.frames[0].pool;
    ai.level = VK_COMMAND_BUFFER_LEVEL_PRIMARY;
    ai.commandBufferCount = 1;
    VkCommandBuffer cmd = VK_NULL_HANDLE;
    VK_CHECK(vkAllocateCommandBuffers(app.device, &ai, &cmd));

    VkCommandBufferBeginInfo bbi{VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO};
    bbi.flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT;
    VK_CHECK(vkBeginCommandBuffer(cmd, &bbi));
    imageBarrier(cmd, src, VK_IMAGE_ASPECT_COLOR_BIT, VK_IMAGE_LAYOUT_PRESENT_SRC_KHR,
                 VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, 0, VK_ACCESS_TRANSFER_READ_BIT,
                 VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT, VK_PIPELINE_STAGE_TRANSFER_BIT);

    VkBufferImageCopy region{};
    region.imageSubresource = {VK_IMAGE_ASPECT_COLOR_BIT, 0, 0, 1};
    region.imageExtent = {app.extent.width, app.extent.height, 1};
    vkCmdCopyImageToBuffer(cmd, src, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL, buffer, 1, &region);

    imageBarrier(cmd, src, VK_IMAGE_ASPECT_COLOR_BIT, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
                 VK_IMAGE_LAYOUT_PRESENT_SRC_KHR, VK_ACCESS_TRANSFER_READ_BIT, 0,
                 VK_PIPELINE_STAGE_TRANSFER_BIT, VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT);
    VK_CHECK(vkEndCommandBuffer(cmd));

    VkSubmitInfo si{VK_STRUCTURE_TYPE_SUBMIT_INFO};
    si.commandBufferCount = 1;
    si.pCommandBuffers = &cmd;
    VK_CHECK(vkQueueSubmit(app.queue, 1, &si, VK_NULL_HANDLE));
    VK_CHECK(vkQueueWaitIdle(app.queue));

    void* mapped = nullptr;
    VK_CHECK(vkMapMemory(app.device, memory, 0, size, 0, &mapped));
    const auto* px = static_cast<const unsigned char*>(mapped);

    const bool bgr = app.colorFormat == VK_FORMAT_B8G8R8A8_UNORM ||
                     app.colorFormat == VK_FORMAT_B8G8R8A8_SRGB;
    std::FILE* f = std::fopen(path, "wb");
    if (!f) {
        std::fprintf(stderr, "cannot open %s\n", path);
        std::exit(1);
    }
    std::fprintf(f, "P6\n%u %u\n255\n", app.extent.width, app.extent.height);
    std::vector<unsigned char> row(std::size_t(app.extent.width) * 3);
    for (std::uint32_t yy = 0; yy < app.extent.height; ++yy) {
        for (std::uint32_t xx = 0; xx < app.extent.width; ++xx) {
            const unsigned char* p = px + (std::size_t(yy) * app.extent.width + xx) * 4;
            row[xx * 3 + 0] = bgr ? p[2] : p[0];
            row[xx * 3 + 1] = p[1];
            row[xx * 3 + 2] = bgr ? p[0] : p[2];
        }
        std::fwrite(row.data(), 1, row.size(), f);
    }
    std::fclose(f);
    vkUnmapMemory(app.device, memory);
    vkFreeMemory(app.device, memory, nullptr);
    vkDestroyBuffer(app.device, buffer, nullptr);
    vkFreeCommandBuffers(app.device, app.frames[0].pool, 1, &cmd);
    std::printf("wrote %s (%ux%u)\n", path, app.extent.width, app.extent.height);
}

} // namespace

int main(int argc, char** argv) {
    const char* screenshot = nullptr;
    int captureFrame = 90; // let the animation settle into a nice pose first
    for (int i = 1; i < argc; ++i) {
        if (!std::strcmp(argv[i], "--screenshot") && i + 1 < argc) screenshot = argv[++i];
        else if (!std::strcmp(argv[i], "--frames") && i + 1 < argc) captureFrame = std::atoi(argv[++i]);
    }

    if (SDL_Init(SDL_INIT_VIDEO) != 0) {
        std::fprintf(stderr, "SDL_Init: %s\n", SDL_GetError());
        return 1;
    }

    App app;
    app.window = SDL_CreateWindow("vkdd showcase", SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED,
                                  1600, 900, SDL_WINDOW_VULKAN);
    if (!app.window) {
        std::fprintf(stderr, "SDL_CreateWindow: %s\n", SDL_GetError());
        return 1;
    }

    createInstance(app);
    if (!SDL_Vulkan_CreateSurface(app.window, app.instance, &app.surface)) {
        std::fprintf(stderr, "SDL_Vulkan_CreateSurface: %s\n", SDL_GetError());
        return 1;
    }
    pickDeviceAndQueue(app);
    createDevice(app);
    createSwapchain(app);
    createFrames(app);

    // ---- vkdd init ----------------------------------------------------------
    vkdd::DebugDraw dd;
    vkdd::InitInfo info;
    info.physicalDevice = app.phys;
    info.device = app.device;
    info.colorFormat = app.colorFormat;
    info.depthFormat = app.depthFormat;
    info.framesInFlight = kFramesInFlight;
    info.maxLineVertices = 1u << 19; // the grid + all that wireframe adds up
    info.errorCallback = [](const char* msg) { std::fprintf(stderr, "vkdd: %s\n", msg); };
    if (!dd.init(info)) {
        std::fprintf(stderr, "vkdd init failed\n");
        return 1;
    }

    std::uint32_t frameIndex = 0;
    std::uint64_t frameCount = 0;
    float time = 0.0f;
    bool running = true;

    while (running) {
        SDL_Event e;
        while (SDL_PollEvent(&e)) {
            if (e.type == SDL_QUIT) running = false;
            if (e.type == SDL_KEYDOWN &&
                (e.key.keysym.sym == SDLK_ESCAPE || e.key.keysym.sym == SDLK_q))
                running = false;
        }

        const float dt = 1.0f / 60.0f; // fixed step keeps --screenshot reproducible
        time += dt;

        Frame& f = app.frames[frameIndex];
        VK_CHECK(vkWaitForFences(app.device, 1, &f.fence, VK_TRUE, UINT64_MAX));

        std::uint32_t imageIndex = 0;
        VkResult acq = vkAcquireNextImageKHR(app.device, app.swapchain, UINT64_MAX, f.acquired,
                                             VK_NULL_HANDLE, &imageIndex);
        if (acq == VK_ERROR_OUT_OF_DATE_KHR) continue;
        if (acq != VK_SUCCESS && acq != VK_SUBOPTIMAL_KHR) VK_CHECK(acq);
        VK_CHECK(vkResetFences(app.device, 1, &f.fence));

        // ---- queue this frame's debug geometry ------------------------------
        dd.reset(dt);
        buildScene(dd, time, app.extent);

        // Orbiting camera.
        const float a = 0.30f + time * 0.12f;
        const float r = 20.0f;
        mat4 view = look_at(vec3{std::sin(a) * r, 12.0f, std::cos(a) * r}, vec3{0, 0.5f, -2.0f},
                            vkm::up);
        mat4 proj = perspective(rad(42.0f), float(app.extent.width) / float(app.extent.height),
                                0.1f, 200.0f);
        mat4 viewProj = proj * view;

        // ---- record ---------------------------------------------------------
        VK_CHECK(vkResetCommandBuffer(f.cmd, 0));
        VkCommandBufferBeginInfo bi{VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO};
        bi.flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT;
        VK_CHECK(vkBeginCommandBuffer(f.cmd, &bi));

        dd.update(f.cmd); // upload — must be OUTSIDE vkCmdBeginRendering

        imageBarrier(f.cmd, app.images[imageIndex], VK_IMAGE_ASPECT_COLOR_BIT,
                     VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, 0,
                     VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT, VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT,
                     VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT);
        imageBarrier(f.cmd, app.depthImage, VK_IMAGE_ASPECT_DEPTH_BIT, VK_IMAGE_LAYOUT_UNDEFINED,
                     VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL, 0,
                     VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT,
                     VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT,
                     VK_PIPELINE_STAGE_EARLY_FRAGMENT_TESTS_BIT);

        VkRenderingAttachmentInfo color{VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO};
        color.imageView = app.views[imageIndex];
        color.imageLayout = VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL;
        color.loadOp = VK_ATTACHMENT_LOAD_OP_CLEAR;
        color.storeOp = VK_ATTACHMENT_STORE_OP_STORE;
        color.clearValue.color = {{0.05f, 0.06f, 0.08f, 1.0f}};

        VkRenderingAttachmentInfo depth{VK_STRUCTURE_TYPE_RENDERING_ATTACHMENT_INFO};
        depth.imageView = app.depthView;
        depth.imageLayout = VK_IMAGE_LAYOUT_DEPTH_ATTACHMENT_OPTIMAL;
        depth.loadOp = VK_ATTACHMENT_LOAD_OP_CLEAR;
        depth.storeOp = VK_ATTACHMENT_STORE_OP_DONT_CARE;
        depth.clearValue.depthStencil = {1.0f, 0};

        VkRenderingInfo ri{VK_STRUCTURE_TYPE_RENDERING_INFO};
        ri.renderArea = {{0, 0}, app.extent};
        ri.layerCount = 1;
        ri.colorAttachmentCount = 1;
        ri.pColorAttachments = &color;
        ri.pDepthAttachment = &depth;
        vkCmdBeginRendering(f.cmd, &ri);

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

        dd.draw(viewProj, f.cmd, app.extent); // extent: thick lines + text need it

        vkCmdEndRendering(f.cmd);

        imageBarrier(f.cmd, app.images[imageIndex], VK_IMAGE_ASPECT_COLOR_BIT,
                     VK_IMAGE_LAYOUT_COLOR_ATTACHMENT_OPTIMAL, VK_IMAGE_LAYOUT_PRESENT_SRC_KHR,
                     VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT, 0,
                     VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT,
                     VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT);
        VK_CHECK(vkEndCommandBuffer(f.cmd));

        VkPipelineStageFlags waitStage = VK_PIPELINE_STAGE_COLOR_ATTACHMENT_OUTPUT_BIT;
        VkSubmitInfo si{VK_STRUCTURE_TYPE_SUBMIT_INFO};
        si.waitSemaphoreCount = 1;
        si.pWaitSemaphores = &f.acquired;
        si.pWaitDstStageMask = &waitStage;
        si.commandBufferCount = 1;
        si.pCommandBuffers = &f.cmd;
        si.signalSemaphoreCount = 1;
        si.pSignalSemaphores = &app.rendered[imageIndex];
        VK_CHECK(vkQueueSubmit(app.queue, 1, &si, f.fence));

        VkPresentInfoKHR pi{VK_STRUCTURE_TYPE_PRESENT_INFO_KHR};
        pi.waitSemaphoreCount = 1;
        pi.pWaitSemaphores = &app.rendered[imageIndex];
        pi.swapchainCount = 1;
        pi.pSwapchains = &app.swapchain;
        pi.pImageIndices = &imageIndex;
        vkQueuePresentKHR(app.queue, &pi);

        frameIndex = (frameIndex + 1) % kFramesInFlight;
        if (screenshot && ++frameCount >= std::uint64_t(captureFrame)) {
            VK_CHECK(vkDeviceWaitIdle(app.device));
            writePPM(app, app.images[imageIndex], screenshot);
            running = false;
        }
    }

    vkDeviceWaitIdle(app.device);
    dd.shutdown();
    destroyApp(app);
    return 0;
}