Here is a detailed breakdown of the **3dGraphics** project, formatted in a way you can directly feed into your chatbot's notes.

---

## Project: 3D Graphics Engine (Java/OpenGL)

**Repository:** `3dGraphics` (v3 branch — rewrite)
**Type:** Native desktop OpenGL graphics engine / interactive demo
**Language:** Java (JDK 17)
**Platform:** Windows desktop application

---

### What It Is

A from-scratch 3D graphics engine written in Java, built with minimal reliance on external libraries. It renders 3D scenes using OpenGL 4.6, loads `.obj` mesh files, runs a custom job-based threading model, and includes a built-in **flamegraph profiler overlay** to visualize frame performance in real time. The primary demo scene renders the classic **Utah teapot** with orbit controls and a green solid shader.

This is the project referenced on Ross's resume under **"Graphics Engine and Paper, IB Physics (Spring 2021)"** — the current codebase is a v3 rewrite from the original.

---

### Technology Stack

| Area | Technology |
|------|-----------|
| Language | Java 17 |
| Windowing / Input | LWJGL 3 (GLFW bindings) |
| Graphics API | OpenGL 4.6 core profile |
| Image Loading | LWJGL STB (STBImage) |
| Shading Language | GLSL 400 core |
| Build / IDE | IntelliJ IDEA (module-based, no Maven/Gradle) |
| Packaging | IDEA fat JAR artifact + `jlink` minimal JRE for distribution |
| Distribution | Bundled JRE (`RossGraphicsEngine/java/`) for shipping as a Windows `.exe` |

No web frameworks, no databases, no HTTP servers — this is a pure offline desktop GPU application.

---

### Architecture Overview

The engine is structured around a **Job / Thread Pool** architecture:

```
Main Thread (GLFW / Render)
    └── Engine.renderLoop()
            └── JobModule.renderJobs() → submits Job list to thread pool each frame

Update Thread (daemon)
    └── Engine.updateLoop()
            └── JobModule.updateJobs() → camera/input jobs + scene update jobs

Work-Stealing Thread Pool (4 threads)
    └── Executes all Job instances concurrently per frame
```

**Key architectural ideas:**
1. **Job Graph:** All work is expressed as `Job` instances. Each `Job` has a `code()` method, optional subtasks, and built-in profiling hooks.
2. **Update/Render Split:** Update thread runs at `Settings.maxTPS`; the main thread owns the OpenGL context and runs at `Settings.maxFPS`. This is standard for OpenGL apps.
3. **Scene Plugin Pattern:** The `Scene` interface lets you swap demo scenes by implementing `start()`, `update()`, and `render()` — each returns a list of jobs to run that frame.
4. **Profiler-Driven Overlay:** Jobs record nanosecond timing. Press **Enter** to snapshot a flamegraph overlay rendered as 2D orthographic quads directly in the GL window.
5. **Custom Math Library:** No external math library — `Mat4f`, `Vec3f`, `Vec4f`, `Quaternion`, `Rotations`, and `Camera` are all hand-written.

---

### Module Breakdown

**`src/Ross/Instance/`** — App Entry
- `Main.java` — Entry point; wires `JobModule` + scene, starts engine
- `testscene.java` — Demo scene: loads Utah teapot OBJ, handles orbit camera, optional flamegraph overlay

**`src/Ross/Modules/`** — Engine Core
- `Engine.java` — Nanosecond-compensated update and render loops
- `JobModule.java` — Central orchestrator: owns window, queues, camera state, shared matrices, renderer
- `Job.java` — Abstract job with profiling, subtask support, and `CountDownLatch` completion
- `JobQueue.java` — `ConcurrentLinkedQueue` of pending jobs; sorts by longest-last-duration for scheduling
- `JobProfiler.java` — Ring buffer of `FlameEvent` records with per-frame markers
- `Settings.java` — Global config: resolution, TPS/FPS caps, FOV, wireframe toggle, vsync
- `Window.java` — GLFW window init, OpenGL 4.6 core context, KHR_debug, viewport resize handling
- `Renderer.java` — Binds shader uniforms (matrices, light, booleans), issues draw calls

**`src/Ross/Modules/scene/`** — Scene System
- `Scene.java` — Interface contract (`start`, `update`, `render`)
- `Utils.java` — Input smoothing (scroll → FOV, cursor clamping), OBJ → `Model` helper

**`src/Ross/Modules/shaders/`** — Shader Pipeline
- `Shader.java` — GLSL compile/link, uniform location cache, `glUseProgram`
- `StaticShader.java` — Binds attributes 0–3 (position, color, normal, UV) for the static lit pipeline

**`src/Ross/Modules/models/`** — Mesh Pipeline
- `OBJloader.java` — Parses `.obj` files into `OBJobject` (float arrays + indices)
- `OBJobject.java` — DTO holding raw vertex/normal/UV/index arrays
- `ModelBuilder.java` — Uploads vertex data to OpenGL VAO/VBOs
- `Model.java` — Holds VAO ID + vertex count
- `TexturedModel.java` — `Model` + `Texture`
- `ModelRenderer.java` — Issues `glDrawElements`, supports wireframe via `Settings`

**`src/Ross/Modules/math/`** — Math Library
- `Mat4f.java`, `Vec3f.java`, `Vec4f.java`, `Quaternion.java`, `Rotations.java`, `Camera.java`

**`src/Ross/Modules/flamegraph/`** — Profiler Visualization
- `FlamegraphBuilder.java` — Maps profiler events to screen-space rects per thread row
- `FlameRect.java` — Batches all rects into a single `Model` for efficient overlay drawing

**`src/Ross/textures/`** — Texture System
- `TextureLoader.java` — STB image load → OpenGL 2D texture upload
- `Texture.java` — Texture handle wrapper

**`res/shaders/static/`** — GLSL Source
- `vertexShader.glsl` / `fragmentShader.glsl` — GLSL 400 core, static lit pipeline

**`res/test/`** — Sample Meshes
- Utah teapot, axis helper, cube, sphere, teddy bear — standard OBJ test models

---

### User Controls (from README)

| Key | Action |
|-----|--------|
| Ctrl + drag | Rotate teapot |
| WASD / Q / E | Camera movement |
| Scroll | Adjust FOV |
| Enter | Toggle flamegraph overlay |
| Backspace | Clear flamegraph |

---

### Distribution

The project ships as a fat JAR with a bundled minimal JRE (`RossGraphicsEngine/java/`) built via `jlink` (modules: `java.base`, `java.desktop`, `jdk.unsupported`). This allows the app to run as a standalone Windows executable without requiring the user to have Java installed.

---

### Chatbot Notes

- This is one of Ross's **oldest and most foundational** projects — started in high school (IB Physics, Spring 2021) and rewritten in v3
- It demonstrates low-level graphics knowledge: custom math, shader pipelines, VAO/VBO management, all from scratch
- The flamegraph profiler is a particularly clever addition — built entirely within the engine's own rendering system
- The project is referenced in the **"Graphics Engine and Paper"** resume entry and has an accompanying research paper on the mathematics and systems behind graphics processing
- It's on GitHub and Ross considers it worth pointing to for detailed technical review


# Original paper summary and evolution

Now I have everything I need. Here is the new section to append to the chatbot briefing:

---

## Evolution: From the Original Engine to v3

### The Original (v1) — IB Physics Internal Assessment, Spring 2021

Ross built the first version of this engine as a high school IB Physics project. He authored a 15-page research paper alongside it, documenting the mathematics and systems behind 3D graphics from scratch. The paper covers models (vertices, indices, normals, UV coordinates), the OpenGL rendering pipeline (VAOs, VBOs, shaders), the model/view/projection matrix stack, and his original engine architecture.

**Original architecture** consisted of six canonical components:

| Component | Role |
|-----------|------|
| **Engine** | Root component; owned both the update loop (separate thread) and render loop (main thread) |
| **Scene Handler** | Managed scenes; passed `InputHandler` and `MasterRenderer` instances into each scene |
| **Window** | GLFW window creation and polling |
| **Resource Handler** | Loaded textures into memory for shared access |
| **Input Handler** | Read GLFW event callbacks; stored key/mouse state in arrays queryable via getters |
| **Master Renderer** | Highest-level programmable rendering stage; executed shader components and accepted model data from scenes |

The scene was the critical integration point — the `Scene Handler` injected the `InputHandler` and `MasterRenderer` into each scene, and the scene pushed model data through the renderer. This created a linear dependency chain: Engine → Scene Handler → Scene → Master Renderer.

---

### Identified Weaknesses (Self-Documented in the Paper)

Ross explicitly noted three architectural limitations at the end of the paper, which directly motivated the v3 rewrite:

1. **Matrix pipeline**: No clean system for passing model/matrix data to the GPU. Every render required recalculating all matrices, and there was no coordinate or chunk system for placing objects in a world.
2. **Scene system**: Barebones and non-functional for its intended purpose. Couldn't seamlessly transition between scenes (e.g. menu → render → title screen). Switching scenes was not well supported.
3. **Model management**: No organized system for how models were stored and managed within scenes.

He also reflected on the broader lesson — the architecture "wound up with" rather than being deliberately planned. He cited the "perils of future coding" as a trap he fell into, and noted that proper roadmapping is essential, especially in team settings.

---

### The v3 Rewrite — What Changed

The v3 codebase replaces the original six-component architecture with a **job-graph / thread-pool model** that directly addresses the identified weaknesses:

| Original Problem | v3 Solution |
|-----------------|-------------|
| No clean matrix pipeline | `JobModule` owns all shared matrices (`modelview`, `perspective`) and injects control/matrix jobs every update frame, centralizing state |
| Scene system too barebones | `Scene` interface now returns `ArrayList<Job>` from `start()`, `update()`, and `render()` — scenes are plug-and-play job emitters, not stateful managers |
| No model management system | `ModelBuilder` / `OBJloader` / `OBJobject` pipeline cleanly separates loading, upload, and rendering; `Utils.buildModel` provides a scene-level convenience layer |
| Architecture "wound up with" | v3 is a deliberate ground-up rewrite structured around the job abstraction from the start |

**New additions not present in v1:**

- **Job / JobQueue / JobProfiler**: All engine work is expressed as `Job` instances with nanosecond profiling hooks. A `ConcurrentLinkedQueue` sorts jobs by longest-last-duration for scheduling.
- **Work-stealing thread pool** (`Executors.newWorkStealingPool(4)`): Jobs run in parallel each frame, with `CountDownLatch` synchronization at batch boundaries.
- **Flamegraph overlay**: Press Enter to snapshot a real-time 2D orthographic overlay of per-thread job timings — rendered entirely within the engine's own GL pipeline.
- **Custom math library**: `Mat4f`, `Vec3f`, `Vec4f`, `Quaternion`, `Rotations`, `Camera` — all hand-written, replacing whatever simpler math was used in v1.
- **Settings centralization**: All global config (resolution, TPS/FPS caps, FOV, wireframe, vsync) lives in `Settings.java` rather than being scattered.
- **Distribution pipeline**: `jlink` + bundled JRE (`RossGraphicsEngine/java/`) allows shipping a standalone Windows executable — no Java install required.

---

### Chatbot Notes on the Evolution

- The original paper is a genuine piece of work — Ross researched and documented the full math stack (model matrix, lookAt/pointAt view matrix, perspective and orthographic projection matrices) from scratch at ~17 years old.
- The paper's self-critique section is unusually honest and insightful for a high school project. Ross identified specific architectural debt and later fixed it in v3.
- The v3 rewrite is not just a refactor — it is a philosophical shift from a passive scene-driven renderer to an active job-graph engine with built-in observability.
- The flamegraph profiler is a direct consequence of the new architecture: since all work is a `Job` with timing hooks, visualizing the frame budget became a natural extension.
- This project trajectory — build it, reflect critically, rewrite with better architecture — is a recurring theme in how Ross approaches his work.