Dev Ui Lesson

Arguments

The user (or you) can provide:

• Number: two-digit lesson number (e.g. 01, 02)
• Topic name: kebab-case (e.g. ttf-parsing, immediate-mode-basics)
• Description: what this teaches (e.g. "Parse TTF font files, extract glyph outlines")

If any are missing, infer from context or ask.

Steps

1. Analyze what's needed

• Check existing UI lessons: Is there already a lesson for this topic?
• Check common/ui/: Does relevant library code already exist?
• Identify the scope: What specific concepts does this lesson cover?
• Find cross-references: Which math/engine/GPU lessons relate?

2. Create the lesson directory

lessons/ui/NN-topic-name/

3. Create a demo program (main.c)

A focused C program that demonstrates the UI concept by producing data and verifying it. UI lesson programs must write BMP images as their primary visual output. These images are committed to assets/ and embedded in the README so readers see results immediately. Programs typically:

• Write output BMP images showing glyphs, atlases, or layouts
• Parse or generate font/UI data structures
• Print supplementary metrics, bounding boxes, or layout results to the console
• Validate data correctness (glyph counts, atlas coverage, vertex winding)

Requirements:

• Standalone — Builds independently with its own CMakeLists.txt
• No GPU code — All output is CPU-side (images, vertex arrays, console)
• Clear output — Shows the concept through printed results or saved images
• Well-commented — Explains what's happening and why
• Uses shared libraries — #include "math/forge_math.h" for vec2/rect math, #include "ui/forge_ui.h" for UI types (once the library exists)

Template structure:

/*
 * UI Lesson NN — Topic Name
 *
 * Demonstrates: [what this shows]
 *
 * SPDX-License-Identifier: Zlib
 */

#include <SDL3/SDL.h>
#include "math/forge_math.h"

int main(int argc, char *argv[])
{
    (void)argc;
    (void)argv;

    if (!SDL_Init(0)) {
        SDL_Log("SDL_Init failed: %s", SDL_GetError());
        return 1;
    }

    /* Demonstrate the UI concept here */

    SDL_Quit();
    return 0;
}

Console output formatting:

• Use ASCII-only characters for console output (cross-platform compatibility)
• Avoid Unicode box-drawing, symbols, or special characters that may not render on Windows Terminal
• Good: -, =, *, |, ->, [OK], [!], "px", "glyph", "atlas"
• Bad: ─, ═, •, ↓, →, ✓, ⚠ (may render as garbled text on Windows)

4. Create CMakeLists.txt

add_executable(NN-topic-name main.c)
target_include_directories(NN-topic-name PRIVATE ${FORGE_COMMON_DIR})
target_link_libraries(NN-topic-name PRIVATE SDL3::SDL3)

if(TARGET SDL3::SDL3-shared)
    add_custom_command(TARGET NN-topic-name POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E copy_if_different
            $<TARGET_FILE:SDL3::SDL3-shared>
            $<TARGET_FILE_DIR:NN-topic-name>
    )
endif()

Adapt as needed: Later lessons may link against a shared UI library (common/ui/) once it exists.

5. Create README.md

Structure:

# UI Lesson NN — Topic Name

[Brief subtitle explaining what this teaches]

## What you'll learn

[Bullet list of UI concepts covered]

## Why this matters

[1-2 paragraphs connecting this topic to real game/tool UI development.
Explain when and why a developer will need this.]

## Result

[Brief description of what the example program produces]

[Embed PNG images generated by the program. The program writes BMP files
(no libpng dependency needed in C), so convert them to PNG before committing.
Copy the PNGs to the lesson's `assets/` directory and reference them with
`![alt text](assets/file.png)`. Use tables to show multiple images side by