89 lines
2.5 KiB
Markdown
89 lines
2.5 KiB
Markdown
# 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`).
|