Nuklear Immediate-Mode UI Toolkit

Nuklear is an immediate-mode UI toolkit that does not handle rendering or OS windowing/input directly. Instead, it follows a three-step loop every frame:

1. Input Mirroring: Capture your platform's input (mouse motion, button presses, keyboard) and pass it to Nuklear using nk_input_begin(&ctx) and nk_input_end(&ctx).
2. UI Building: Define your interface using Nuklear's layout and widget APIs (e.g., nk_begin, nk_button_label, nk_slider_float).
3. Drawing: Iterate through the draw commands generated by Nuklear using nk_foreach and pass those commands to your specific rendering backend (e.g., OpenGL, Vulkan, Direct3D). Finally, call nk_clear(&ctx) to reset the command list for the next frame.

/* 1. Setup (once) */
struct nk_context ctx;
// ... initialize ctx with nk_init_fixed ...

while (running) {
    /* 2. Input (every frame) */
    nk_input_begin(&ctx);
    // ... mirror input ...
    nk_input_end(&ctx);

    /* 3. Build UI (every frame) */
    if (nk_begin(&ctx, "Window", nk_rect(50, 50, 220, 220), NK_WINDOW_BORDER)) {
        if (nk_button_label(&ctx, "Click Me")) { /* handle click */ }
    }
    nk_end(&ctx);

    /* 4. Draw (every frame) */
    const struct nk_command *cmd;
    nk_foreach(cmd, &ctx) {
        // ... dispatch cmd->type to your renderer ...
    }
    nk_clear(&ctx);
}

Nuklear uses an immediate-mode paradigm where UI elements are declared and handled within a window block. The typical lifecycle involves:

1. Initializing the context with nk_init_fixed.
2. Starting a window with nk_begin.
3. Defining a layout (static, dynamic, or custom) using nk_layout_row_* functions.
4. Calling widget functions (e.g., nk_button_label, nk_slider_float) which return true if an interaction occurred.
5. Ending the window with nk_end.

Layouts determine how widgets are positioned:

• nk_layout_row_static: Uses fixed pixel dimensions for widgets.
• nk_layout_row_dynamic: Uses a ratio of the window width for widgets.
• nk_layout_row_begin/push/end: Allows for complex, custom-sized widget rows.

// init gui state
enum {EASY, HARD};
static int op = EASY;
static float value = 0.6f;
static int i =  20;
struct nk_context ctx;

// Initialize context
nk_init_fixed(&ctx, calloc(1, MAX_MEMORY), MAX_MEMORY, &font);

// Start a window
if (nk_begin(&ctx, "Show", nk_rect(50, 50, 220, 220), 
    NK_WINDOW_BORDER|NK_WINDOW_MOVABLE|NK_WINDOW_CLOSABLE)) {
    
    // 1. Fixed widget pixel width
    nk_layout_row_static(&ctx, 30, 80, 1);
    if (nk_button_label(&ctx, "button")) {
        // event handling
    }

    // 2. Fixed widget window ratio width
    nk_layout_row_dynamic(&ctx, 30, 2);
    if (nk_option_label(&ctx, "easy", op == EASY)) op = EASY;
    if (nk_option_label(&ctx, "hard", op == HARD)) op = HARD;

    // 3. Custom widget pixel width using row push
    nk_layout_row_begin(&ctx, NK_STATIC, 30, 2);
    {
        nk_layout_row_push(&ctx, 50);
        nk_label(&ctx, "Volume:", NK_TEXT_LEFT);
        nk_layout_row_push(&ctx, 110);
        nk_slider_float(&ctx, 0, &value, 1.0f, 0.1f);
    }
    nk_layout_row_end(&ctx);
}
k_end(&ctx);

The Nuklear SDL Vulkan integration operates by rendering the UI to independent render targets (overlay images). The application is responsible for managing these targets, ensuring they are correctly sized and resized.

Key Requirements:

• You must manage the lifecycle and sizing of the overlay images.
• The number of Nuklear overlay images must match the number of images in your Vulkan swap chain.
• You must call nk_sdl_resize whenever the overlay images are resized.

Integration Workflow:

1. Initialization: Call nk_sdl_init providing your window, device, physical device, graphics queue indices, overlay image views, swap chain length, and format.
2. Rendering: In your draw loop, call nk_sdl_render to render to the specific image_index. This returns an nk_semaphore.
3. Synchronization: Use the returned semaphore to coordinate with your application's rendering pipeline. Your application should then sample from the overlay_image to produce the final swap chain image.

/* Setup */
struct nk_context *ctx = nk_sdl_init(
    demo.win, 
    demo.device, 
    demo.physical_device, 
    demo.indices.graphics,
    demo.overlay_image_views, 
    demo.swap_chain_images_len,
    demo.swap_chain_image_format, 
    0, // flags
    MAX_VERTEX_BUFFER, 
    MAX_ELEMENT_BUFFER
);

/* In the draw loop */
k_semaphore semaphore =
    nk_sdl_render(demo.graphics_queue, image_index,
                    demo.image_available, NK_ANTI_ALIASING_ON);

if (!render(&demo, &bg, nk_semaphore, image_index)) {
    fprintf(stderr, "render failed\n");
    return false;
}