[feature] an emulator for viewing fbgl programs

1 files changed, 30 insertions, 203 deletions

diff --git a/emu/README.md b/emu/README.md
index 5033baf..4d0e013 100644
--- a/emu/README.md
+++ b/emu/README.md
@@ -1,230 +1,57 @@
-# FBGL Virtual Framebuffer Emulator
+# FBGL Framebuffer Emulator
 
-Test your FBGL programs without actual framebuffer hardware using SDL2!
+Professional LD_PRELOAD-based framebuffer emulator with clean architecture.
 
-## Quick Start
+## Structure
 
-```bash
-# 1. Install dependencies
-sudo apt-get install libsdl2-dev build-essential
-
-# 2. Build the emulator
-make
-
-# 3. Run your FBGL program
-./fbgl_run.sh ./your_fbgl_program
-```
-
-## Components
+- `fbgl_preload.h` - Public header with configuration and types
+- `fbgl_preload.c` - Implementation with hook functions
+- `sdl_viewer.c` - SDL-based viewer application
 
-1. **libfbgl_preload.so** - LD_PRELOAD library that intercepts framebuffer calls
-2. **fbgl_viewer** - SDL2 window that displays the virtual framebuffer
-3. **fbgl_run.sh** - Convenient wrapper script to run everything
+## Features
 
-## Installation
+- Clean struct-based state management
+- Proper header/source separation
+- Statistics tracking
+- Error handling
+- FPS counter in viewer
 
-### Option 1: Using Makefile
+## Building
 
 ```bash
-# Download/create these files in the same directory:
-# - fbgl_preload.c
-# - fbgl_viewer.c
-# - fbgl_run.sh
-# - Makefile (below)
-
-make all
+make
 ```
 
-### Option 2: Manual compilation
-
+Or manually:
 ```bash
-# Compile the preload library
-gcc -shared -fPIC fbgl_preload.c -ldl -o libfbgl_preload.so
-
-# Compile the viewer
-gcc fbgl_viewer.c -lSDL2 -o fbgl_viewer
-
-# Make runner script executable
-chmod +x fbgl_run.sh
+gcc -shared -fPIC -o libfbgl_preload.so fbgl_preload.c -ldl
+gcc -o sdl_viewer sdl_viewer.c $(pkg-config --cflags --libs sdl2)
 ```
 
 ## Usage
 
-### Basic Usage
 
+Terminal 2:
 ```bash
-./fbgl_run.sh ./my_fbgl_app
+LD_PRELOAD=./libfbgl_preload.so ./your_fbgl_program
 ```
 
-### With Arguments
-
+Terminal 1:
 ```bash
-./fbgl_run.sh ./my_fbgl_app --arg1 value1 --arg2 value2
-```
-
-### Manual Usage (without script)
-
-```bash
-# Terminal 1: Start the viewer
-./fbgl_viewer &
-
-# Terminal 2: Run your program with LD_PRELOAD
-LD_PRELOAD=./libfbgl_preload.so ./my_fbgl_app
-```
-
-## Example Test Program
-
-Create a simple test program (`test_fbgl.c`):
-
-```c
-#define FBGL_IMPLEMENTATION
-#include "fbgl.h"
-#include <unistd.h>
-
-int main() {
-    fbgl_t fb;
-    
-    if (fbgl_init(NULL, &fb) < 0) {
-        return 1;
-    }
-    
-    // Draw some shapes
-    for (int i = 0; i < 100; i++) {
-        fbgl_set_bg(&fb, FBGL_RGB(0, 0, 0));
-        
-        // Draw moving circle
-        int x = 400 + (int)(200 * cos(i * 0.1));
-        int y = 300 + (int)(200 * sin(i * 0.1));
-        fbgl_draw_circle_filled(x, y, 50, FBGL_RGB(255, 0, 0), &fb);
-        
-        // Draw rectangle
-        fbgl_point_t tl = {100, 100};
-        fbgl_point_t br = {300, 300};
-        fbgl_draw_rectangle_outline(tl, br, FBGL_RGB(0, 255, 0), &fb);
-        
-        usleep(16666); // ~60 FPS
-    }
-    
-    fbgl_destroy(&fb);
-    return 0;
-}
-```
-
-Compile and run:
-
-```bash
-gcc test_fbgl.c -o test_fbgl -lm
-./fbgl_run.sh ./test_fbgl
-```
-
-## Makefile
-
-Create a file named `Makefile`:
-
-```makefile
-CC = gcc
-CFLAGS = -Wall -Wextra -O2
-LDFLAGS = -lSDL2 -ldl -lm
-
-.PHONY: all clean test
-
-all: libfbgl_preload.so fbgl_viewer fbgl_run.sh
-
-libfbgl_preload.so: fbgl_preload.c
-	@echo "Building preload library..."
-	$(CC) -shared -fPIC $(CFLAGS) $< -ldl -o $@
-
-fbgl_viewer: fbgl_viewer.c
-	@echo "Building SDL viewer..."
-	$(CC) $(CFLAGS) $< $(LDFLAGS) -o $@
-
-fbgl_run.sh:
-	@echo "Making runner script executable..."
-	@chmod +x fbgl_run.sh
-
-test: all test_fbgl
-	@echo "Running test program..."
-	./fbgl_run.sh ./test_fbgl
-
-test_fbgl: test_fbgl.c fbgl.h
-	@echo "Compiling test program..."
-	$(CC) $(CFLAGS) test_fbgl.c -lm -o test_fbgl
-
-clean:
-	@echo "Cleaning up..."
-	rm -f libfbgl_preload.so fbgl_viewer test_fbgl
-	@# Clean up shared memory
-	@ipcrm -M $$(ftok /tmp F 2>/dev/null | awk '{print $$NF}') 2>/dev/null || true
-
-install:
-	@echo "Installing to /usr/local/bin..."
-	sudo cp libfbgl_preload.so /usr/local/lib/
-	sudo cp fbgl_viewer /usr/local/bin/
-	sudo cp fbgl_run.sh /usr/local/bin/fbgl-run
-	@echo "Done! You can now run: fbgl-run ./your_program"
-
-uninstall:
-	@echo "Uninstalling..."
-	sudo rm -f /usr/local/lib/libfbgl_preload.so
-	sudo rm -f /usr/local/bin/fbgl_viewer
-	sudo rm -f /usr/local/bin/fbgl-run
-	@echo "Done!"
+./fbgl_viewer
 ```
 
-## Troubleshooting
 
-### "Shared memory not found" error
-
-The viewer needs to be started before the FBGL program. Use the `fbgl_run.sh` script which handles this automatically.
-
-### Black screen
-
-Make sure your FBGL program is actually drawing to the framebuffer and not exiting immediately.
-
-### Viewer doesn't start
-
-Check that SDL2 is installed:
-```bash
-sudo apt-get install libsdl2-dev
-```
+## Architecture
 
-### Program crashes
-
-Check stderr output for preload messages. Make sure your program is compiled with `-lm` for math functions.
+1. Hook library intercepts framebuffer syscalls
+2. Redirects to shared memory segment
+3. SDL viewer displays shared memory contents
+4. Program thinks it's using real /dev/fb0
 
 ## Configuration
 
-Edit the following constants in the source files to change resolution:
-
-In `fbgl_preload.c` and `fbgl_viewer.c`:
-```c
-#define VIRTUAL_FB_WIDTH 800
-#define VIRTUAL_FB_HEIGHT 600
-```
-
-Then recompile:
-```bash
-make clean && make
-```
-
-## How It Works
-
-1. **LD_PRELOAD** intercepts system calls (`open`, `ioctl`, `mmap`, etc.) that your FBGL program makes
-2. Instead of real framebuffer device, it provides a shared memory buffer
-3. The SDL viewer reads from this shared memory and displays it in a window
-4. Your FBGL program thinks it's writing to `/dev/fb0`, but it's actually writing to shared memory
-
-## Performance
-
-The emulator adds minimal overhead:
-- Shared memory for zero-copy data transfer
-- VSync enabled in SDL for smooth rendering
-- ~60 FPS typical performance
-
-## License
-
-This emulator is public domain. Use it however you want!
-
-## Credits
-
-Created for testing FBGL applications without hardware framebuffer access.
+Edit `fbgl_preload.h` to change:
+- Screen resolution (FBGL_WIDTH, FBGL_HEIGHT)
+- Color depth (FBGL_BPP)
+- Shared memory key (FBGL_SHM_KEY)