From eee4198ac8184cf982e5202590de618feb87cadf Mon Sep 17 00:00:00 2001
From: Krzosa Karol <git.exclaim518@passmail.net>
Date: Thu, 19 Mar 2026 23:16:06 +0100
Subject: [PATCH] first commit

---
 README.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b14d316
--- /dev/null
+++ b/README.md
@@ -0,0 +1,88 @@
+# 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`).