# Visualize

`Visualize` is a real-time graph viewer for instrumenting your programs.

You run a graphical app (`visualize.exe`), then your own program connects through a small C/C++ header-only API and streams plot data into shared memory. The viewer reads that memory and draws graphs live.

Demo video: `visualize_plot_zooms.mp4`

## What this project is for

- Quickly inspect runtime stats from external programs.
- Plot continuously changing values (frame time, latency, memory, counters, custom metrics).
- Organize data as `plot -> series -> points`.
- Visualize without building a full UI in your own app.

## Data Flow

```mermaid
flowchart LR
    A[Your Program] -->|VIS_* API calls| B[Shared Memory Buffer\n32 MB]
    B --> C[Visualize Viewer App]
    C --> D[Plot Canvas Renderer]
    D --> E[Line / Scatter / Histogram / Bar Graphs]
```

## Core concept

The integration API is defined in `src/visualize/visualize.h`.

- Shared memory transport (`VIS_CreateSharedMemory`, `VIS_Connect`)
- Plot/series selection (`VIS_Plot`, `VIS_Series`)
- Data writes (`VIS_Point`, `VIS_Value`, `VIS_NamedValue`, `VIS_NamedPoint`)
- Labels and metadata (`VIS_Title`, `VIS_XLabel`, `VIS_YLabel`, `VIS_SeriesName`)
- Synchronization/commands (`VIS_Clear`, command ring buffer)

Internally, data is written as lightweight nodes into a single mapped buffer and then copied by the viewer into frame-local structures for safe rendering.

## Supported graph types

| Plot kind | Purpose |
|---|---|
| Line | Time-series and trend lines |
| Scatter | Point clouds / sampled observations |
| Histogram | Distribution of values |
| Bar | Named categorical values |

## Quick start

Before building, open the **x64 Visual Studio Command Prompt** and run commands from there. This ensures `cl.exe` (MSVC) is available on your `PATH`.

### 1) Build and run the viewer (Windows/MSVC)

From repository root:

```bat
build.bat
```

This produces `build/visualize.exe`.

### 2) Send data from your program

Minimal example:

```cpp
#include "src/visualize/visualize.h"

void send_metrics() {
    VIS_Plot(0);
    VIS_Title("Application Timing");
    VIS_XLabel("Frame");
    VIS_YLabel("Milliseconds");

    VIS_Series(0);
    VIS_SeriesName("Update");
    VIS_Point(1.0, 0.42);

    VIS_Series(1);
    VIS_SeriesName("Render");
    VIS_Point(1.0, 0.31);
}
```

Notes:

- Start the viewer first so shared memory exists.
- API uses a fixed named shared-memory region (`VIS_BUFFER_NAME`).
- Buffer size is `32 MB` (`VIS_BUFFER_SIZE`).