How aygaoua/minirt_ works
1. Project purpose and runtime shape
- This is a C ray tracer (miniRT) that reads a scene description from a .rt file, builds an in-memory scene, and renders it to a window/image using MLX42.
- The repository is organized as a classic pipeline: parse scene → build geometry/light data → cast rays → compute shading → display image.
2. Top-level execution boundary
- sources/main.c is the application entrypoint.
- It likely coordinates startup, file loading, parsing, scene initialization, render invocation, and teardown.
- The main boundary is between text input from scene files and rendered pixel output.
3. Scene description ingestion
- The scenes/ directory contains sample .rt inputs used for evaluation and extra scenes.
- The parser subsystem under sources/parsing/ handles the .rt grammar, validates scene constraints, and populates runtime structures.
- This layer is responsible for converting human-readable scene definitions into typed objects such as camera, ambient light, point lights, spheres, planes, and cylinders.
4. Parsing subsystem responsibilities
- Files like camera.c, light.c, ambient_lightning.c, sphere_pars.c, plane_pars.c, and cylinder_pars.c suggest each object type has dedicated parsing/validation logic.
- collector.c, object_list.c, and parser.c likely orchestrate tokenization, dispatch, and accumulation of parsed elements.
- data_validation*.c and check_elements.c enforce correctness rules such as bounds, uniqueness, and format constraints.
- atof.c indicates custom numeric parsing rather than relying purely on standard conversion.
5. Runtime scene model
- The headers in includes/ define the shared data model used across parsing, geometry, lighting, and rendering.
- miniRT.h is the central project header, while geometry.h, lighting.h, pars.h, and rt_mathematics.h split the domain into subsystems.
- The scene likely consists of linked lists or collections of primitives and lights, with camera and ambient values stored globally or in a scene struct.
6. Geometry and intersection subsystem
- sources/geometry/ contains the ray/object intersection logic for the supported primitives: sphere, plane, cylinder.
- rays.c, hits.c, and objects.c likely manage ray construction, intersection selection, and object dispatch.
- lists.c suggests object collections and iteration over scene primitives.
- cylinder_1.c implies the cylinder logic is split, probably because it needs both side-surface and cap handling.
7. Lighting and shading subsystem
- sources/lighting/ implements color handling and shading, with phong.c indicating Phong illumination.
- lights.c and colors.c likely combine ambient, diffuse, and specular terms, plus shadow checks.
- The lighting stage consumes intersection results and surface normals to produce final pixel colors.
- This is the main abstraction boundary where pure geometry becomes visible image output.
8. Math and transformation layer
- sources/rt_mathematics/ is the computational backbone: tuples/vectors, matrix math, normalization, reflection, scaling, rotation, translation, and coordinate transforms.
- Files such as mtx.c, tuple_mtx_ops.c, transformations.c, and render_*.c suggest a reusable math kernel used by both parsing validation and rendering.
- This layer isolates low-level linear algebra from ray-tracing logic, which is important for maintainability and diagramming dependencies.
9. Rendering pipeline
- The render_1.c to render_5.c split suggests the render loop is decomposed into multiple stages, likely camera ray generation, per-pixel tracing, hit selection, shading, and post-processing or image writing.
- The pipeline probably traverses the camera’s view plane, generates one ray per pixel, computes closest hits against all objects, then shades and writes the resulting color.
- Any shadows are likely handled by secondary rays from hit points toward lights.
10. Windowing and image output
- The project depends on MLX42 under lib/MLX42/ for graphics window management, image buffers, input hooks, and pixel display.
- This external library is the boundary between CPU-side ray tracing and the user-facing GUI/window.
- MLX42 is vendored in the repo, so the project is self-contained at build time except for system graphics dependencies.
11. Shared utility library
- lib/libft/ is the standard 42-style helper library used for string, memory, numeric, and I/O utilities, plus get_next_line.
- It supports parsing and general housekeeping rather than architecture-critical rendering logic.
- In a diagram, it is best treated as a foundational utility dependency beneath parsing and file handling.
12. Build and packaging
- Makefile is the top-level build entry, likely compiling the app, linking libft and MLX42, and producing the miniRT binary.
- The repo is mostly single-binary, monolithic C application architecture rather than a multi-service system.
- The key architectural concern is dependency layering: libft/utilities → parsing/math → geometry/lighting → MLX42 output.
13. High-level data flow to show in a diagram
- Scene file input flows into the parser.
- Parser produces scene state: camera, ambient light, lights, and primitive object lists.
- The renderer consumes that scene state, uses math helpers to transform and trace rays, calls geometry intersection functions, then passes hit information into lighting.
- The final color buffer is handed to MLX42 for display in a window.
14. Important boundaries and coupling points
- Parsing is separated from rendering: once the scene is built, render logic should not depend on raw file text.
- Geometry is separated from shading: intersection code determines “what was hit,” while lighting code determines “what color it becomes.”
- Math is shared and central, making it the lowest-level reusable layer.
- MLX42 remains the only external UI/display boundary; everything else is application logic inside the repo.
Main entry points: hits.c Hits · render_1.c Render · miniRT.h Scene Model · parser.c Parser
Components 20
Application
Entrypoint and top-level orchestration
- Main · Starts the app and drives load-render-teardown flow
sources/main.c - Scene Model · Central scene and data definitions used across the pipeline
includes/miniRT.h
Parsing
Scene file ingestion and validation
- Parser · Coordinates .rt file reading and dispatch into object parsers
sources/parsing/parser.c - Collector · Accumulates parsed tokens and scene elements
sources/parsing/collector.c - Validation · Enforces scene constraints and format correctness
sources/parsing/data_validation.c - Camera · Parses camera definition and view parameters
sources/parsing/camera.c - Lights · Parses ambient and point light definitions
sources/parsing/light.c - Primitives · Parses sphere, plane, and cylinder records
sources/parsing/object_list.c
Geometry
Ray and primitive intersection logic
- Rays · Constructs rays and manages hit traversal inputs
sources/geometry/rays.c - Hits · Selects closest intersections and combines object tests
sources/geometry/hits.c - Sphere · Sphere ray intersection logic
sources/geometry/sphere.c - Plane · Plane ray intersection logic
sources/geometry/plane.c - Cylinder · Cylinder side and cap intersection logic
sources/geometry/cylinder.c
Lighting
Shading and color composition
Math
Linear algebra and transform utilities
Dependencies
Vendored runtime and utility libraries
Scenes
Sample .rt scene inputs
- Scenes · Reference .rt files used for evaluation and examples
scenes/evaluation/objects.rt
Connections 21
- Main → Parser: loads scene · Reads the .rt file and starts parsing
- Main → Render: renders · Invokes the rendering loop after scene setup
- Parser → Collector: accumulates · Builds the scene from parsed elements
- Parser → Validation: checks · Validates structure and constraints during parse
- Collector → Scene Model: populates · Materializes the shared runtime scene state
- Camera → Scene Model: writes camera · Stores parsed camera parameters
- Lights → Scene Model: writes lights · Stores ambient and point light data
- Primitives → Scene Model: writes objects · Adds primitives to the scene model
- Render → Scene Model: consumes · Uses camera, lights, and object lists for tracing
- Render → Math Core: uses · Relies on vector and matrix operations
- Render → Rays: emits rays · Generates primary rays per pixel
- Rays → Hits: tests hits · Feeds rays into intersection selection
- Hits → Sphere: dispatches · Evaluates sphere intersections
- Hits → Plane: dispatches · Evaluates plane intersections
- Hits → Cylinder: dispatches · Evaluates cylinder intersections
- Hits → Shading: returns hit · Passes closest hit and surface data to shading
- Shading → Phong: applies · Computes diffuse and specular response
- Shading → Math Core: uses · Uses normals, reflection, and normalization helpers
- Render → MLX42: display buffer · Uploads final pixels to the window/image backend
- Parser → libft: parses text · Uses helper routines for input and string handling
- Main → Scenes: reads examples · Can be driven by bundled scene files