forge-ui-rendering

Render the CPU-side immediate-mode UI (forge_ui_ctx.h, forge_ui_window.h) using the SDL GPU API. Based on GPU Lesson 28.

When to use

• You have a ForgeUiContext producing vertex/index arrays and need to draw them
• You need to render text glyphs from a font atlas with alpha blending
• You need a single-draw-call 2D UI pipeline with dynamic buffer streaming
• You want to integrate the UI track output into a GPU application

Key API calls

• SDL_CreateGPUTexture with SDL_GPU_TEXTUREFORMAT_R8_UNORM — single-channel atlas
• SDL_CreateGPUSampler — linear filter, clamp-to-edge for atlas
• SDL_CreateGPUGraphicsPipeline — alpha blend, no depth, cull none
• SDL_CreateGPUTransferBuffer / SDL_MapGPUTransferBuffer — per-frame upload
• SDL_UploadToGPUBuffer — copy vertex + index data via copy pass
• SDL_PushGPUVertexUniformData — orthographic projection matrix
• SDL_DrawGPUIndexedPrimitives — single batched draw call
• forge_ui_ctx_begin / forge_ui_ctx_end — UI declaration phase
• forge_ui_wctx_begin / forge_ui_wctx_end — window z-order sorting

Correct order

1. Init (once) a. Load font with forge_ui_ttf_load, build atlas with forge_ui_atlas_build b. Upload atlas pixels to R8_UNORM GPU texture via transfer buffer + copy pass c. Create sampler (linear, clamp-to-edge) d. Create vertex and fragment shaders from compiled HLSL bytecode e. Create pipeline: alpha blend enabled, no depth, cull none, 4x FLOAT2 vertex attrs f. Pre-allocate vertex and index GPU buffers (power-of-two sizes) g. Init ForgeUiContext and ForgeUiWindowContext

2. Each frame a. Query window size and mouse state b. forge_ui_ctx_begin — start UI declaration c. Declare windows and widgets (labels, buttons, checkboxes, sliders, text input) d. forge_ui_wctx_end / forge_ui_ctx_end — finalize vertex/index arrays e. Resize GPU buffers if needed (power-of-two growth) f. Create single transfer buffer, map, copy vertex+index data, unmap g. Copy pass: upload vertex data at offset 0, index data after h. Release transfer buffer i. Acquire swapchain, begin render pass (clear) j. Bind pipeline, vertex buffer, index buffer, atlas texture+sampler k. Push orthographic projection uniform l. SDL_DrawGPUIndexedPrimitives — one call for all UI m. End render pass, submit command buffer

Key concepts

1. ForgeUiVertex is 32 bytes — 8 floats: pos(2), uv(2), color(4). Pipeline reads as 4x FLOAT2.
2. White-pixel technique — solid rects use UVs pointing to a white region in the atlas where coverage = 1.0, so the fragment shader works for both text and solid geometry.
3. R8_UNORM atlas — single-channel texture saves 4x memory vs RGBA8. Fragment shader reads .r as coverage.
4. Orthographic projection — maps [0..W, 0..H] pixels to [-1..+1] clip space with Y flipped for top-left origin. Rebuilt every frame for automatic resize handling.
5. No depth buffer — 2D UI uses painter's algorithm via z_order sorting in the window context.
6. No backface culling — UI quads may have either winding order.
7. Single draw call — all widgets batched into one vertex/index stream by the UI context.

Theme colors

The forge-gpu project uses a dark blue-gray palette defined in scripts/forge_diagrams/_common.py. All UI colors follow this theme. The key property: dark surfaces carry a strong blue tint (B/R ratio ~1.8) that tapers toward neutral at brighter levels (~1.07 for text).

Reference palette (sRGB)

Deriving new colors

When adding new UI elements, derive colors from the theme by maintaining the blue tint ratio for the brightness level:

• Dark (0.10–0.20 R/G): set B ≈ R × 1.7–1.8
• Medium (0.20–0.40 R/G): set B ≈ R × 1.5–1.6
• Bright (0.40–0.60 R/G): set B ≈ R × 1.3–1.4
• Near-white (0.80+ R/G): set B ≈ R × 1.05–1.15

The default widget colors in forge_ui_ctx.h and forge_ui_window.h already follow this theme. The clear color and label colors are set per lesson (see main.c CLEAR_R/G/B and TITLE_LABEL_R/G/B defines).

Common mistakes

1. Using RGBA8 for the atlas — wastes 4x GPU memory and requires CPU-side pixel expansion. Use R8_UNORM.
2. Forgetting to flip Y in the projection — without -2.0f / height, the UI renders upside down.
3. Not checking SDL_SubmitGPUCommandBuffer return — must check on every path, including error paths after swapchain acquisition.
4. Leaking the transfer buffer — release it after the copy pass ends, not after submit.
5. Not handling the minimized window case — when swapchain texture is NULL, submit the command buffer and return.
6. Fixed-size buffers — if the UI grows beyond initial capacity, you must resize. Use power-of-two growth.
7. Depth testing with alpha blending — depth test would discard semi-transparent fragments. Disable it for 2D UI.

Template

#define SDL_MAIN_USE_CALLBACKS 1
#include "ui/forge_ui.h"
#include "ui/forge_ui_ctx.h"
#include "ui/forge_ui_window.h"
#include "math/forge_math.h"
#include <SDL3/SDL.h>
#include <SDL3/SDL_main.h>

/* Include compiled shader headers */
#include "shaders/compiled/ui_vert_spirv.h"
#include "shaders/compiled/ui_vert_dxil.h"
#include "shaders/compiled/ui_frag_spirv.h"
#include "shaders/compiled/ui_frag_dxil.h"

typedef struct UiUniforms {
    mat4 projection;  /* orthographic pixel-to-NDC mapping */
} UiUniforms;

typedef struct app_state {
    SDL_Window    *window;
    SDL_GPUDevice *device;
    SDL_GPUGraphicsPipeline *pipeline;
    SDL_GPUTexture *atlas_texture;   /* R8_UNORM font atlas */
    SDL_GPUSampler *atlas_sampler;   /* linear, clamp-to-edge */
    SDL_GPUBuffer  *vertex_buffer;
    SDL_GPUBuffer  *index_buffer;
    Uint32 vertex_buffer_size;
    Uint32 index_buffer_size;
    ForgeUiFont     font;
    ForgeUiFontAtlas atlas;
    ForgeUiContext   ui_ctx;
    ForgeUiWindowContext ui_wctx;
    /* ... widget state ... */
} app_state;

/* Orthographic projection: top-left origin, y-down */
static mat4 ui_ortho_projection(float width, float height)
{
    mat4 m = mat4_identity();
    m.m[0]  =  2.0f / width;
    m.m[5]  = -2.0f / height;
    m.m[12] = -1.0f;
    m.m[13] =  1.0f;
    return m;
}