[feature] emulator init commit for testing wo hardware access

1 files changed, 230 insertions, 0 deletions

diff --git a/emu/README.md b/emu/README.md
new file mode 100644
index 0000000..5033baf
--- /dev/null
+++ b/emu/README.md
@@ -0,0 +1,230 @@
+# FBGL Virtual Framebuffer Emulator
+
+Test your FBGL programs without actual framebuffer hardware using SDL2!
+
+## Quick Start
+
+```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
+
+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
+
+## Installation
+
+### Option 1: Using Makefile
+
+```bash
+# Download/create these files in the same directory:
+# - fbgl_preload.c
+# - fbgl_viewer.c
+# - fbgl_run.sh
+# - Makefile (below)
+
+make all
+```
+
+### Option 2: Manual compilation
+
+```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
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+./fbgl_run.sh ./my_fbgl_app
+```
+
+### With Arguments
+
+```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!"
+```
+
+## 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
+```
+
+### Program crashes
+
+Check stderr output for preload messages. Make sure your program is compiled with `-lm` for math functions.
+
+## 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.