8.18.1.47. Plot

Four read-only sample plots. Two array-form widgets take a per-frame array<float> and copy it synchronously; two lambda-form widgets call back once per sample, skipping the backing array entirely.

plot_lines(IDENT, "title", values, scale_min, scale_max, size)
plot_histogram(IDENT, "title", values, scale_min, scale_max, size)
plot_lines_getter(IDENT, "title", count,
                  @(idx : int) : float => ...,
                  overlay, scale_min, scale_max, size)
plot_histogram_getter(IDENT, "title", count,
                      @(idx : int) : float => ...,
                      overlay, scale_min, scale_max, size)

All four share PlotState — title + samples round-trip into the snapshot so visual regression tests can diff the data.

Source: modules/dasImgui/examples/tutorial/plot.das.

8.18.1.47.1. Walkthrough

options gen2
options _comment_hygiene = true

require math
require imgui
require imgui_app
require opengl/opengl_boost
require live/glfw_live
require live/live_api
require live/live_commands
require live/live_vars
require live_host
require imgui/imgui_live
require imgui/imgui_boost_runtime
require imgui/imgui_boost_v2
require imgui/imgui_widgets_builtin
require imgui/imgui_containers_builtin
require imgui/imgui_visual_aids

// =============================================================================
// TUTORIAL: plot — four read-only sample-plot widgets.
//
//   plot_lines(IDENT, "title", values, scale_min, scale_max, size)
//   plot_histogram(IDENT, "title", values, scale_min, scale_max, size)
//     Array form — pass a per-frame array<float>. ImGui copies it
//     synchronously. Pass scale_min = scale_max = FLT_MAX to auto-fit
//     bounds to the data; explicit bounds avoid the per-frame jitter.
//
//   plot_lines_getter(IDENT, "title", count, getter, overlay,
//                     scale_min, scale_max, size)
//   plot_histogram_getter(IDENT, "title", count, getter, overlay,
//                         scale_min, scale_max, size)
//     Lambda form — callback (idx : int) : float fires once per sample
//     synchronously inside the C call. Use for synthesized signals or
//     virtualized buffers (avoids building a backing array).
//
// All four share PlotState — title + sample telemetry round-trips into
// the snapshot payload for visual regression testing.
//
// STANDALONE: daslang.exe modules/dasImgui/examples/tutorial/plot.das
// LIVE:       daslang-live modules/dasImgui/examples/tutorial/plot.das
// =============================================================================

let SAMPLES = 64
let FLT_MAX = 3.40282347e38f

var private g_phase : float = 0.0f

def fill_sine(var arr : array<float>; phase : float; n : int) {
    arr |> resize(n)
    for (i in range(n)) {
        arr[i] = sin(float(i) * 0.2f + phase)
    }
}

def fill_bars(var arr : array<float>) {
    arr |> resize(8)
    for (i in range(8)) {
        arr[i] = float(i) * 0.15f + 0.1f
    }
}

[export]
def init() {
    live_create_window("dasImgui plot tutorial", 800, 720)
    live_imgui_init(live_window)
    let io & = unsafe(GetIO())
    GetStyle().FontScaleMain = 1.4
}

[export]
def update() {
    if (!live_begin_frame()) return
    begin_frame()

    ImGui_ImplGlfw_NewFrame()
    apply_synth_io_override()
    NewFrame()

    g_phase += 0.05f
    var sine_data : array<float>
    fill_sine(sine_data, g_phase, SAMPLES)
    var bar_data : array<float>
    fill_bars(bar_data)

    SetNextWindowPos(ImVec2(20.0f, 20.0f), ImGuiCond.Always)
    SetNextWindowSize(ImVec2(760.0f, 680.0f), ImGuiCond.Always)
    window(PL_WIN, (text = "plot tutorial", closable = false,
                    flags = ImGuiWindowFlags.None)) {

        text("Read-only sample plots - PlotState records title + samples each frame.")
        text(PL_HINT, (text = "Array form (lines / histogram) vs lambda form (lines_getter / histogram_getter)."))
        separator()

        // ---- Stage 1: plot_lines (array) — sine wave with explicit bounds ----
        plot_lines(PL_LINES, "Sine wave", sine_data, -1.2f, 1.2f, float2(0.0f, 80.0f))
        spacing()

        // ---- Stage 2: plot_histogram (array) — fixed bars ----
        plot_histogram(PL_HIST, "Histogram", bar_data, 0.0f, 1.5f, float2(0.0f, 80.0f))
        spacing()

        // ---- Stage 3: plot_lines_getter (lambda) — no backing array ----
        plot_lines_getter(PL_LINES_G, "sin(i*0.1)", SAMPLES,
                          @(idx : int) : float => sin(float(idx) * 0.1f + g_phase),
                          "", -1.2f, 1.2f, float2(0.0f, 80.0f))
        spacing()

        // ---- Stage 4: plot_histogram_getter (lambda) ----
        plot_histogram_getter(PL_HIST_G, "abs(sin(i*0.1))", SAMPLES,
                              @(idx : int) : float => abs(sin(float(idx) * 0.1f + g_phase)),
                              "", 0.0f, 1.2f, float2(0.0f, 80.0f))
    }

    end_of_frame()
    Render()
    var w, h : int
    live_get_framebuffer_size(w, h)
    glViewport(0, 0, w, h)
    glClearColor(0.10f, 0.10f, 0.12f, 1.0f)
    glClear(GL_COLOR_BUFFER_BIT)
    live_imgui_render()

    live_end_frame()
}

[export]
def shutdown() {
    live_imgui_shutdown()
    live_destroy_window()
}

[export]
def main() {
    init()
    while (!exit_requested()) {
        update()
    }
    shutdown()
}

8.18.1.47.1.1. Requires

Already in the baseline boost layer:

imgui/imgui_widgets_builtin — both array and lambda rails.
imgui/imgui_boost_runtime — PlotState.

8.18.1.47.1.2. Array form vs lambda form

Array (plot_lines / plot_histogram) — pass a values : array<float>. ImGui copies element-by-element inside the C call. Use when you already have a backing buffer (telemetry ring, captured samples, table column).
Lambda (*_getter) — pass values_count and a getter : lambda<(idx : int) : float>. The callback fires once per sample, synchronously inside the C call. Use for synthesized signals (sine, noise, generated frequency response) or virtualized buffers where building an array would waste work.

Both forms are O(n) per frame — the choice is about whether you want to allocate the array or generate on the fly.

8.18.1.47.1.3. Auto-fit vs explicit bounds

scale_min and scale_max default to FLT_MAX (3.4e38), which ImGui treats as “auto-fit to the data this frame.” That’s tempting, but the bounds change every frame — the plot stretches/compresses as the data range shifts, which reads as jitter:

// Auto-fit — bounds drift per frame:
plot_lines(LATENCY, "ms", samples)               // FLT_MAX defaults

// Explicit bounds — calm plot, comparable across frames:
plot_lines(LATENCY, "ms", samples,
           0.0f, 200.0f, float2(0.0f, 80.0f))    // 0..200 ms y-axis

Use auto-fit only when you don’t know the data range and don’t care about per-frame stability. For anything you’ll watch over time, explicit bounds.

8.18.1.47.1.4. Size

The last arg is the plot bbox in pixels — float2(width, height). width = 0.0f lets ImGui auto-size to the available content width; height = 0.0f falls back to a small default. Pass 80.0f or 120.0f for the height to keep two plots visible side-by-side.

8.18.1.47.1.5. The overlay arg

Lambda-form widgets take an extra overlay_text : string arg before scale_min. Pass "" for no overlay, or a status string that prints centered on top of the plot:

plot_lines_getter(FRAMETIME, "ms/frame", 60,
                  @(idx : int) : float => sample_at(idx),
                  "avg = {avg_ms:.2f}",
                  0.0f, 33.0f, float2(0.0f, 80.0f))

Useful for the “rolling average” or “max” annotation under the line.

8.18.1.47.1.6. Driving from outside

PlotState exposes title + samples in the snapshot payload — no imgui_force_set channel (the samples are caller-pushed). Snapshot probes are the right tool:

curl -X POST -d '{"name":"imgui_snapshot"}' localhost:9090/command \
    | jq '.globals."PL_WIN/PL_LINES".payload'

The samples array gives visual-regression tests something to diff without screenshotting.