How stanislavpetrovv/advanced_raymarching works
Project Type & Purpose
• This is a GPU-accelerated 3D ray-marching demo written in Python. It uses ModernGL (a Python wrapper over OpenGL) to set up an OpenGL context, compile/link a set of GLSL shader programs (vertex + fragment shaders), load textures, accept mouse input (zoom via scroll), and render an anti-aliased 3D scene in real time.
File Structure Analysis
• main.py – Entry point. Sets up window/context, loads resources, handles input, drives the render loop.
• requirements.txt – Lists Python dependencies (e.g. ModernGL, GLFW/GLUT bindings, NumPy, etc.).
• programs/ – Contains GLSL modules:
• vertex.glsl – Vertex shader for full-screen quad.
• fragment.glsl – Main ray-marching fragment shader.
• .glsl, hg_sdf.glsl, material.glsl – Scene SDF definitions and material routines.
• textures/ – Image assets (e.g. roof textures) loaded by the fragment shader.
• screenshots/ – Demo output, for documentation only.
• LICENSE, README.md – Project metadata.
Core Architectural Components
a. Application Layer (CPU side)
• Window & Context Manager (GLFW/GLUT via ModernGL)
• Input Handler (mouse scroll events → zoom uniforms)
• Resource Loader (reads .glsl files and texture images)
• Shader Manager (compiles & links GLSL programs)
• Configuration (reads AA setting from fragment.glsl or command line)
b. Rendering Pipeline (GPU side)
• Vertex Shader (vertex.glsl) → draws a full-screen quad
• Fragment Shader (fragment.glsl) → ray-marching algorithm
• Scene Definitions (map.glsl, hg_sdf.glsl) → Signed Distance Functions
• Material/Shading (material.glsl) → lighting, shading, anti-aliasing
• Texture Samplers (roof textures) → material detail
c. External Dependencies
• ModernGL (OpenGL binding)
• Windowing library (e.g. GLFW)
• NumPy (for any array math)
Relationships & Data Flow
1. User scroll input → Input Handler
2. Input Handler updates uniform variables in Shader Manager
3. Resource Loader reads GLSL code & textures at startup
4. Shader Manager compiles & links shaders → sends programs to GPU
• Vertex shader → full-screen primitive
• Fragment shader → ray-marching + SDF evaluations + shading
6. GPU writes to Framebuffer → OS window displays result
Architectural Patterns & Principles
• Pipeline pattern: clear separation of CPU-side setup vs. GPU-side execution
• Modularity: each GLSL file encapsulates a specific concern (geometry, scene SDF, material, main ray-marching)
• Single responsibility: main.py orchestrates only resource, input, and loop management
Construction Steps
1. Sketch high-level boundaries: CPU vs. GPU vs. External.
3. Populate GPU cluster: Vertex → Fragment → SDF & Material modules → Framebuffer.