viz.hpp

Go to the documentation of this file.

/// @file include/viz/viz.hpp
/// @brief Lightweight real-time visualization layer for numerics apps.
#pragma once
 
#include <algorithm>
#include <cstdarg>
#include <cstdint>
#include <cstdio>
#include <raylib.h>
#include <raymath.h>
#include <vector>
 
namespace num::viz {
 
struct Color {
    uint8_t r = 0, g = 0, b = 0, a = 255;
};
 
inline constexpr Color kBlack = {0, 0, 0, 255};
inline constexpr Color kWhite = {255, 255, 255, 255};
inline constexpr Color kRed = {220, 40, 40, 255};
inline constexpr Color kGreen = {50, 200, 50, 255};
inline constexpr Color kBlue = {50, 100, 230, 255};
inline constexpr Color kYellow = {240, 220, 30, 255};
inline constexpr Color kGray = {120, 120, 120, 255};
inline constexpr Color kSkyBlue = {100, 180, 240, 255};
 
inline ::Color to_rl(Color c) {
    return {c.r, c.g, c.b, c.a};
}
inline Color from_rl(::Color c) {
    return {c.r, c.g, c.b, c.a};
}
 
inline Color unpack(uint32_t c) {
    return {uint8_t(c >> 24), uint8_t(c >> 16), uint8_t(c >> 8), uint8_t(c)};
}
 
/// @brief Heat colormap for \f$t\in[0,1]\f$.
inline Color heat_color(float t) {
    t = std::clamp(t, 0.0f, 1.0f);
    return from_rl(ColorFromHSV((1.0f - t) * 240.0f, 1.0f, 0.95f));
}
 
/// @brief Diverging colormap for \f$t\in[-1,1]\f$.
inline Color diverging_color(float t) {
    t = std::clamp(t, -1.0f, 1.0f);
    if (t >= 0.0f) {
        auto v = uint8_t(255 * t * t);
        return {v, 0, uint8_t(v / 10), 255};
    } else {
        auto v = uint8_t(255 * t * t);
        return {uint8_t(v / 10), 0, v, 255};
    }
}
 
/// @brief Phase/probability colormap for quantum wavefunctions.
inline Color phase_hsv_color(double prob, double phase, double max_prob) {
    if (max_prob < 1e-20)
        return kBlack;
    float amp = std::min(1.0f, float(std::sqrt(prob / max_prob)));
    float hue = float((phase + 3.14159265) / (2.0 * 3.14159265)) * 360.0f;
    float h6 = hue / 60.0f;
    int hi = int(h6) % 6;
    float f = h6 - int(h6);
    float s = 0.95f;
    float p = amp * (1.0f - s);
    float q = amp * (1.0f - s * f);
    float u = amp * (1.0f - s * (1.0f - f));
    float r, g, b;
    switch (hi) {
        case 0:
            r = amp;
            g = u;
            b = p;
            break;
        case 1:
            r = q;
            g = amp;
            b = p;
            break;
        case 2:
            r = p;
            g = amp;
            b = u;
            break;
        case 3:
            r = p;
            g = q;
            b = amp;
            break;
        case 4:
            r = u;
            g = p;
            b = amp;
            break;
        default:
            r = amp;
            g = p;
            b = q;
            break;
    }
    return {uint8_t(r * 255), uint8_t(g * 255), uint8_t(b * 255), 255};
}
 
inline Color lerp_color(Color a, Color b, float t) {
    t = std::clamp(t, 0.0f, 1.0f);
    return {
        uint8_t(a.r + t * (b.r - a.r)),
        uint8_t(a.g + t * (b.g - a.g)),
        uint8_t(a.b + t * (b.b - a.b)),
        uint8_t(a.a + t * (b.a - a.a)),
    };
}
 
namespace detail {
struct FieldCanvas {
    Texture2D tex{};
    std::vector<::Color> buf;
    int N = 0;
    bool valid = false;
 
    void ensure(int n) {
        if (n == N && valid)
            return;
        if (valid)
            UnloadTexture(tex);
        N = n;
        buf.assign(n * n, ::BLACK);
        Image img = GenImageColor(n, n, ::BLACK);
        tex = LoadTextureFromImage(img);
        UnloadImage(img);
        valid = true;
    }
    void unload() {
        if (valid) {
            UnloadTexture(tex);
            valid = false;
            N = 0;
        }
    }
};
 
struct State {
    FieldCanvas canvas;
    bool paused = false;
    int substeps = 1;
    int slider_count = 0; // reset each frame
};
} // namespace detail
 
// Frame -- passed to the draw callback on every tick.
struct Frame {
    int width, height;
    bool& paused;
    int& substeps;
    detail::State& _s;
 
    // Advance the simulation fn() `substeps` times if not paused.
    // fn() -> void
    template<class Fn>
    void step(Fn fn) {
        if (!paused)
            for (int i = 0; i < substeps; ++i)
                fn();
    }
 
    // True on the frame R was pressed.
    bool reset_pressed() const { return IsKeyPressed(KEY_R); }
 
    // 2D primitives -- pixel coordinates, (0,0) = top-left.
    void dot(float x, float y, Color c, float r = 3.0f) {
        DrawCircleV({x, y}, r, to_rl(c));
    }
    void circle(float x, float y, float r, Color c) {
        DrawCircleLines(int(x), int(y), r, to_rl(c));
    }
    void line(float x0, float y0, float x1, float y1, Color c, float thick = 1.0f) {
        DrawLineEx({x0, y0}, {x1, y1}, thick, to_rl(c));
    }
    void rect(float x, float y, float w, float h, Color c) {
        DrawRectangleV({x, y}, {w, h}, to_rl(c));
    }
    void rect_outline(float x, float y, float w, float h, Color c, float thick = 1.0f) {
        DrawRectangleLinesEx({x, y, w, h}, thick, to_rl(c));
    }
    void text(const char* s, float x, float y, int sz, Color c) {
        DrawText(s, int(x), int(y), sz, to_rl(c));
    }
    // printf-style text -- uses a 256-byte internal buffer (safe for HUD
    // strings)
    void textf(float x, float y, int sz, Color c, const char* fmt, ...) {
        char buf[256];
        va_list args;
        va_start(args, fmt);
        vsnprintf(buf, sizeof(buf), fmt, args);
        va_end(args);
        DrawText(buf, int(x), int(y), sz, to_rl(c));
    }
 
    // Pixel field covering the full window.
    template<class Fn>
    void field(int N, Fn color_fn) {
        auto& cv = _s.canvas;
        cv.ensure(N);
        for (int row = 0; row < N; ++row)
            for (int col = 0; col < N; ++col)
                cv.buf[row * N + col] = to_rl(color_fn(col, row));
        UpdateTexture(cv.tex, cv.buf.data());
        DrawTexturePro(cv.tex,
                       {0, 0, float(N), float(N)},
                       {0, 0, float(width), float(height)},
                       {0, 0},
                       0.0f,
                       ::WHITE);
    }
 
    // GUI slider -- stacks vertically in the top-left corner.
    // Reads mouse drag to update val.
    void slider(const char* label, double lo, double hi, double& val) {
        constexpr int PAD = 10;
        constexpr int SLOT_H = 38;
        constexpr int BAR_W = 220;
        constexpr int BAR_H = 8;
        const int X = PAD;
        const int Y = PAD + _s.slider_count * SLOT_H;
        ++_s.slider_count;
 
        DrawRectangle(X - 4, Y - 2, BAR_W + 8, SLOT_H - 4, {0, 0, 0, 170});
        DrawRectangle(X, Y + 18, BAR_W, BAR_H, {80, 80, 80, 220});
 
        float t = std::clamp(float((val - lo) / (hi - lo)), 0.0f, 1.0f);
        int tx = X + int(t * BAR_W);
 
        Vector2 mp = GetMousePosition();
        Rectangle hit = {float(X), float(Y), float(BAR_W), float(SLOT_H)};
        if (IsMouseButtonDown(MOUSE_LEFT_BUTTON) && CheckCollisionPointRec(mp, hit)) {
            t = std::clamp((mp.x - X) / BAR_W, 0.0f, 1.0f);
            val = lo + t * (hi - lo);
            tx = X + int(t * BAR_W);
        }
 
        DrawCircle(tx, Y + 18 + BAR_H / 2, 9, {200, 200, 200, 240});
        DrawText(TextFormat("%s: %.3g", label, val), X, Y + 2, 13, {210, 210, 210, 230});
    }
 
    // 3D camera descriptor
    struct Cam3 {
        float px = 0, py = 0, pz = 0; // camera position
        float tx = 0, ty = 0, tz = 0; // look-at target
        float ux = 0, uy = 1, uz = 0; // up vector (default: world-Y)
        float fovy = 45.0f;
    };
 
    // Begin 3D rendering mode.  All 3D draw calls must sit between
    // begin3d/end3d.
    void begin3d(Cam3 cam) {
        Camera3D c{};
        c.position = {cam.px, cam.py, cam.pz};
        c.target = {cam.tx, cam.ty, cam.tz};
        c.up = {cam.ux, cam.uy, cam.uz};
        c.fovy = cam.fovy;
        c.projection = CAMERA_PERSPECTIVE;
        BeginMode3D(c);
    }
    void end3d() { EndMode3D(); }
 
    void sphere3d(float x, float y, float z, float r, Color c) {
        DrawSphere({x, y, z}, r, to_rl(c));
    }
    void sphere3d_wire(float x, float y, float z, float r, Color c) {
        DrawSphereWires({x, y, z}, r, 6, 6, to_rl(c));
    }
    void line3d(float x0, float y0, float z0, float x1, float y1, float z1, Color c) {
        DrawLine3D({x0, y0, z0}, {x1, y1, z1}, to_rl(c));
    }
    void cube3d(float x, float y, float z, float sx, float sy, float sz, Color c) {
        DrawCube({x, y, z}, sx, sy, sz, to_rl(c));
    }
};
 
// run() -- open a window and call draw(Frame&) at 60 Hz until ESC / close.
//
// Built-in key bindings:
//   SPACE  pause / unpause
//   R      sets reset flag (check via f.reset_pressed())
//   +/-    increase / decrease substeps (capped at 16)
//   ESC    quit
template<class DrawFn>
void run(const char* title, int w, int h, DrawFn draw, Color bg = {15, 15, 15, 255}) {
    SetConfigFlags(FLAG_MSAA_4X_HINT);
    InitWindow(w, h, title);
    SetTargetFPS(60);
 
    detail::State state;
    Frame frame{w, h, state.paused, state.substeps, state};
 
    while (!WindowShouldClose()) {
        if (IsKeyPressed(KEY_SPACE))
            state.paused = !state.paused;
        if (IsKeyPressed(KEY_EQUAL) || IsKeyPressed(KEY_KP_ADD))
            state.substeps = std::min(state.substeps + 1, 16);
        if (IsKeyPressed(KEY_MINUS) || IsKeyPressed(KEY_KP_SUBTRACT))
            state.substeps = std::max(state.substeps - 1, 1);
 
        state.slider_count = 0;
 
        BeginDrawing();
        ClearBackground(to_rl(bg));
 
        draw(frame);
 
        if (state.paused) {
            DrawRectangle(w / 2 - 70, h / 2 - 18, 140, 36, {0, 0, 0, 160});
            DrawText("PAUSED", w / 2 - 46, h / 2 - 10, 24, ::YELLOW);
        }
 
        EndDrawing();
    }
 
    state.canvas.unload();
    CloseWindow();
}
 
} // namespace num::viz