{"id":47619271,"url":"https://github.com/tiw302/mandelbrot-c","last_synced_at":"2026-04-26T07:01:56.947Z","repository":{"id":345957109,"uuid":"1185888795","full_name":"tiw302/mandelbrot-c","owner":"tiw302","description":"A simple Mandelbrot set explorer written in C. Crafted with SDL2 and multithreaded rendering for a smooth experience. ‹(•_•)›","archived":false,"fork":false,"pushed_at":"2026-04-20T04:35:36.000Z","size":17569,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-20T05:37:53.811Z","etag":null,"topics":["c","cuda","fractal","graphics","mandelbrot","multithreading","sdl2","web","webassembly"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tiw302.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-19T03:25:18.000Z","updated_at":"2026-04-20T04:35:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tiw302/mandelbrot-c","commit_stats":null,"previous_names":["tiw302/mandelbrot-c"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/tiw302/mandelbrot-c","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiw302%2Fmandelbrot-c","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiw302%2Fmandelbrot-c/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiw302%2Fmandelbrot-c/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiw302%2Fmandelbrot-c/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiw302","download_url":"https://codeload.github.com/tiw302/mandelbrot-c/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiw302%2Fmandelbrot-c/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32288653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T06:26:00.361Z","status":"ssl_error","status_checked_at":"2026-04-26T06:25:58.791Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","cuda","fractal","graphics","mandelbrot","multithreading","sdl2","web","webassembly"],"created_at":"2026-04-01T21:54:13.702Z","updated_at":"2026-04-26T07:01:56.935Z","avatar_url":"https://github.com/tiw302.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mandelbrot-C\n\n[![Build Status](https://github.com/tiw302/mandelbrot-c/actions/workflows/build.yml/badge.svg)](https://github.com/tiw302/mandelbrot-c/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Language](https://img.shields.io/badge/Language-C11-00599C.svg)](https://en.wikipedia.org/wiki/C11_(C_standard_revision))\n![GitHub repo size](https://img.shields.io/github/repo-size/tiw302/mandelbrot-c)\n![GitHub last commit](https://img.shields.io/github/last-commit/tiw302/mandelbrot-c)\n\nA high-performance, multi-threaded Mandelbrot and Julia set explorer written in C11. This project utilizes an Engine-Centric Architecture targeting Native Desktop (CPU/AVX2), Web (WebAssembly/SIMD128), and hardware-accelerated GPU rendering (WebGL/Sokol GFX).\n\nLive Web Demo: **[tiw302.github.io/mandelbrot-c/](https://tiw302.github.io/mandelbrot-c/)**\n\n---\n\n## Table of Contents\n\n| **Overview \u0026 UX** | **Engineering \u0026 Math** | **Dev \u0026 Ops** | **Project Lifecycle** |\n| :--- | :--- | :--- | :--- |\n| • [Introduction](#introduction) | • [The Mathematics](#the-mathematics) | • [Build \u0026 Installation](#build-and-installation) | • [Roadmap](#roadmap) |\n| • [Technical Preview](#technical-preview) | • [Technical Architecture](#technical-architecture) | • [Configuration](#configuration) | • [Contributing](#contributing) |\n| • [Core Features](#core-features) | • [Platform Implementations](#platform-implementations) | • [Project Structure](#project-structure) | • [License](#license) |\n| • [Interactive Controls](#interactive-controls) | | | |\n\n---\n\n## Introduction\n\nMandelbrot-C is an exploratory project focused on the intersection of low-level C programming and high-performance graphics. This journey began as a deep dive into C11 to understand pointers, memory management, and hardware acceleration. What started as a simple SDL2 experiment has evolved into a production-grade fractal engine.\n\nThroughout the development process, I have explored advanced topics including SIMD intrinsics, multi-threaded load balancing, WebAssembly porting, and shader-based 64-bit precision emulation.\n\n---\n\n## Technical Preview\n\n### Mandelbrot\n\n![Mandelbrot Screenshot](assets/images/Mandelbrot-Screenshot.png)\n![Mandelbrot Screenshot](assets/images/Mandelbrot-Screenshot2.png)\n![Mandelbrot Screenshot](assets/images/Mandelbrot-Screenshot3.png)\n\n### Julia Set Exploration\n\n![Julia Screenshot](assets/images/julia-Screenshot.png)\n![Julia Screenshot](assets/images/julia-Screenshot2.png)\n![Julia Screenshot](assets/images/julia-Screenshot3.png)\n\n---\n\n## Core Features\n\n- **Hybrid Rendering Pipeline:** Choice between optimized multi-threaded CPU rendering or hardware-accelerated GPU rendering.\n- **WASM Performance:** Desktop-class performance in the browser via WebAssembly, SIMD128, and multi-threaded Web Workers.\n- **Persistent State Sharing:** Share mathematical discoveries via URL parameters that track coordinates, zoom, iterations, and color palettes.\n- **Hi-Lo Precision GPU Math:** 64-bit precision emulation in GLSL shaders for deep-zoom exploration.\n- **Interactive Tour Mode:** Automated exploration paths for both Mandelbrot and Julia sets.\n- **Professional Screenshot System:** Deferred capture logic that ensures high-fidelity PNG exports by synchronizing with the GPU rendering cycle.\n- **Dynamic HUD:** A redesigned, responsive Heads-Up Display showing 14-decimal precision coordinates.\n\n---\n\n## Interactive Controls\n\n| Action | Desktop Key | Web Key | Web UI / Touch |\n| :--- | :--- | :--- | :--- |\n| **Zoom In** | Left-Drag (Box) | Left-Drag (Box) | Pinch-In |\n| **Pan** | Right-Drag | Right-Drag | Two-Finger Drag |\n| **Undo** | `Ctrl + Z` | `Ctrl + Z` | \"Undo\" Button |\n| **Screenshot** | `S` | `S` | \"Screenshot\" Button |\n| **Tour Mode** | `T` | `T` | \"Tour\" Button |\n| **GPU/CPU Toggle** | `G` | `G` | \"GPU\" Button |\n| **Julia Toggle** | `J` | `J` | \"Julia\" Button |\n| **Palette Cycle** | `P` | `P` | \"Palette\" Button |\n| **Iterations** | `Up/Down` | `Up/Down` | `Iter+/Iter-` |\n| **Reset View** | `R` | `R` | \"Reset\" Button |\n| **Copy Link** | - | - | \"Copy Link\" Button |\n| **Quit** | `Esc` / `Q` | - | - |\n\n---\n\n## The Mathematics\n\nThe Mandelbrot set is defined as the set of complex numbers $c$ for which the function $f_c(z) = z^2 + c$ remains bounded when iterated from $z = 0$.\n\n### Optimization Strategies\nTo maintain high frame rates in dense regions, the engine implements several mathematical optimizations:\n- **Main Cardioid Rejection:** Points inside the main cardioid are detected using a vectorized check to skip expensive iterations.\n- **Period-2 Bulb Check:** Similar to the cardioid, points within the largest circular bulb are filtered out early.\n- **Normalized Iteration Count:** Prevents color banding by using a fractional iteration formula, resulting in smooth gradients.\n\n---\n\n## Technical Architecture\n\n### Engine-Centric Design\nThe codebase strictly adheres to a modular architecture to ensure Separation of Concerns (SoC):\n- **Core [SSOT]:** Pure mathematical definitions (`mandelbrot.c`, `julia.c`) are the Single Source of Truth, agnostic to rendering APIs.\n- **Engine Layer:** Manages high-level rendering logic, thread-pools, and platform-agnostic graphics abstractions (via Sokol GFX).\n- **Application Layer:** Platform-specific entry points (SDL2 for Desktop, Emscripten for Web) handle input and OS-level interactions.\n\n### WebAssembly Subsystem\nThe WASM implementation utilizes `SharedArrayBuffer` to enable real multi-threading in the browser. The built-in `server.py` is configured to handle the required COOP/COEP security headers for local development.\n\n---\n\n## Platform Implementations\n\n### CPU Rendering (Native Desktop)\nThe native CPU engine is designed for maximum throughput on multi-core systems:\n- **Dynamic Load Balancing:** Instead of static partitioning, the engine uses an **Atomic Row Counter**. Threads dynamically \"claim\" the next available row of pixels, ensuring that no CPU core sits idle while others are stuck rendering dense \"black\" regions of the fractal.\n- **AVX2 Vectorization:** Utilizing 256-bit YMM registers, the engine processes **4 double-precision complex numbers** in a single instruction cycle (SIMD). This provides a theoretical 4x performance boost over scalar C code.\n- **Persistent Thread Pool:** To avoid OS overhead, threads are spawned once at startup and managed via condition variables, ready to render new frames instantly as the user navigates.\n\n### Web Rendering (WebAssembly \u0026 WASM-SIMD)\nBringing desktop-class performance to the browser required solving several engineering challenges:\n- **Multithreading via Web Workers:** By leveraging Emscripten's pthreads support, the C engine runs across multiple Web Workers. These workers communicate via a **SharedArrayBuffer**, allowing them to share the same pixel memory space as the main thread.\n- **WASM-SIMD128:** We utilize the modern WebAssembly SIMD proposal (128-bit) to process **2 double-precision points** simultaneously, bridging the gap between browser and native performance.\n- **Security \u0026 Headers:** To enable `SharedArrayBuffer`, the environment must be \"Cross-Origin Isolated.\" We implemented a specialized **Service Worker** (`coi-serviceworker.js`) to automatically inject COOP and COEP headers, ensuring the engine runs on standard static hosting without server-side configuration.\n\n### GPU Rendering (WebGL \u0026 Hi-Lo Precision)\nThe GPU path offloads all calculations to the graphics card for real-time smoothness:\n- **Hi-Lo Double Precision Emulation:** Standard GPUs (especially on web/mobile) only support 32-bit floats, which causes pixelation at high zoom. Our custom GLSL shader splits each 64-bit coordinate into two 32-bit \"High\" and \"Low\" parts, performing **extended precision arithmetic** manually within the shader.\n- **Sokol GFX Integration:** We use the Sokol GFX library as a lightweight abstraction layer, allowing the same shader code and pipeline logic to run seamlessly on both Native OpenGL (Desktop) and WebGL 2.0 (Browser).\n- **Deferred Readback:** Screenshots in GPU mode utilize a \"Deferred Capture\" system, ensuring the pixel data is read back from the GPU memory only after the frame is fully validated.\n\n---\n\n## Build and Installation\n\n### Interactive TUI Build (Recommended)\nRun the following for a user-friendly terminal menu:\n```bash\n./build.sh\n```\n\n### Manual Build\n```bash\n# Desktop (CPU)\ncmake -S . -B build -DBUILD_CPU=ON\ncmake --build build\n\n# Web (WASM)\nemcmake cmake -S . -B build-web -DBUILD_WEB=ON\ncmake --build build-web\n```\n\n---\n\n## Configuration\n\nRendering parameters can be tuned in `include/config.h`:\n- `DEFAULT_ITERATIONS`: Initial detail level.\n- `MAX_ITERATIONS_LIMIT`: Upper bound for runtime adjustments.\n- `DEFAULT_THREAD_COUNT`: Number of parallel threads (0 = auto-detect).\n- `ESCAPE_RADIUS`: Mathematical threshold for divergence.\n\n---\n\n## Project Structure\n\n```text\n.\n├── include/             # Global configuration and platform headers\n├── src/\n│   ├── core/           # Pure Mathematical Engine (Single Source of Truth)\n│   ├── engine/         # Platform-Agnostic Renderers, Tours, and Logic\n│   └── app/            # Platform-Specific Entries (Desktop, Web)\n├── web/                 # Web Frontend (HTML, CSS, JS)\n├── assets/              # Shared Typography and Media\n├── tests/               # Automated Unit Testing Suite\n├── third_party/         # External Abstractions (Sokol, stb, etc.)\n├── CMakeLists.txt       # Unified Cross-platform Build System\n└── build.sh             # Interactive TUI Build Wrapper\n```\n\n---\n\n## Roadmap\n\n### Performance Optimization\n- [x] Implement dynamic load balancing using atomic row-counters to maximize CPU utilization.\n- [x] Integrate a pre-calculated Look-Up Table (LUT) for color mapping.\n- [x] Implement smooth coloring algorithms using fractional iteration counts.\n- [x] Deploy hardware-specific vectorization (AVX2 for Desktop, SIMD128 for WebAssembly).\n- [x] Research and implement pure-shader fractal calculation for GPU rendering.\n- [x] Optimize Julia set calculation using hardware-specific vectorization.\n\n### Features and Exploration\n- [x] Add interactive runtime controls for iteration depth and palette switching.\n- [x] Implement automated \"camera path\" and \"tour\" modes.\n- [x] Connect HTML5 Frontend APIs to the web-engine for a responsive experience.\n- [x] Implement URL-based state recovery and deep-linking for sharing discoveries.\n- [x] Add mobile touch support (pinch-to-zoom and gesture-based panning).\n\n### Engineering and Quality\n- [x] Establish a strict Engine-Centric Monorepo architecture.\n- [x] Implement a high-performance CMake build system.\n- [x] Expand unit testing coverage to ensure mathematical consistency.\n- [x] Implement automatic CPU core detection for dynamic thread pool allocation.\n- [x] Implement Hi-Lo 64-bit precision emulation for GPU shaders.\n- [ ] Research and implement arbitrary-precision arithmetic for infinite zoom.\n\n---\n\n## Contributing\n\nI am still a learner in the vast world of C programming and high-performance computing. If you spot any bugs, identify memory safety concerns, or have suggestions for improving SIMD and GPGPU optimizations, I would be deeply grateful for your guidance. Every piece of advice, feedback, or architectural suggestion is a valuable lesson for me.\n\nIf you would like to help:\n1. Feel free to open an **issue** to discuss bugs or improvements.\n2. If you'd like to contribute code, please **fork** the repository and open a **pull request**.\n3. Descriptive commit messages and clear explanations are highly appreciated.\n\nThank you for being a part of my learning journey and for helping make this project better!\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE) - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiw302%2Fmandelbrot-c","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiw302%2Fmandelbrot-c","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiw302%2Fmandelbrot-c/lists"}