miniRT / the ray tracer, explained

00 · orientationBig picture

miniRT is a CPU ray tracer. For every pixel of an 800×600 window it shoots a ray from the camera through that pixel into the scene, finds the nearest object the ray hits, and computes a color there from ambient light, diffuse (Lambert) light and shadows — plus specular highlights, multiple colored lights and a procedural checkerboard in the bonus. The image is drawn once into an MLX image buffer and re-rendered only when the camera moves.

The one data structure to know: t_scene

includes/miniRT.h:184

typedef struct s_scene {
    t_ambient  ambient;    /* ratio + color (exactly one "A") */
    t_camera   camera;     /* pos + dir + fov (exactly one "C") */
    t_light    *lights;    /* linked list: 1 in mandatory, N in bonus */
    t_object   *objects;   /* linked list of tagged unions */
    int        has_ambient, has_camera, has_light;
} t_scene;

t_object (miniRT.h:153) is a tagged union: an enum type + an anonymous union { sphere; plane; cylinder; cone; triangle; } + a t_material + next. One malloc per object, no nested allocations. Everything hangs off t_app (miniRT.h:208), a stack variable in main that owns the MLX state and the scene.

The two binaries & the linking trick

So the shared object parser (parse_objects.c) behaves strictly in the mandatory binary and extensibly in the bonus binary just because a different check_count/parse_material got linked in. This is the most elegant design decision in the project.

Constants that matter

includes/miniRT.h:22-26

01 · orientationFile map

Every source file and what lives inside it. Files tagged BONUS are linked only into miniRT_bonus.

02 · orientationLife of a ray

This is the story to tell an evaluator who says “explain how your program works.”

1. main srcs/main.c:15 — checks argc == 2, calls parse_scene, mlx_setup, render, registers the hooks (mouse; KeyPress=2; DestroyNotify=17; Expose=12) and enters mlx_loop.
2. Parse (§03) — the .rt file is read line by line, tokenized on whitespace, dispatched by identifier (A C L sp pl cy [+ co tr]), each element validated hard. Any error → Error\n + message on stderr, exit 1. Result: a fully populated t_scene.
3. Render (§06) — build_camera_basis converts pos/dir/FOV into a viewport 1 unit in front of the camera. For each pixel, 4 sub-pixel rays (2×2 anti-aliasing) are generated by get_ray(u, v) and averaged.
4. Intersect (§05) — ray_color → intersect_scene walks the object list, calls the per-shape intersector via hit_object, keeps the hit with the smallest t. A t_hit carries the point, a unit normal that always faces the ray, and a pointer to the object's material.
5. Shade (§07/§08) — shade = ambient + for each light: if not in_shadow, add diffuse (bonus: + specular, × light color). Clamp to [0,1].
6. Write pixel — mlx_put_pixel packs r,g,b (×255.999) into an int and writes it directly into the image buffer at addr + y·line_len + x·(bpp/8).
7. After the double loop, one mlx_put_image_to_window blits the frame. Keys/scroll mutate the camera and re-run steps 3–7; ESC or the window cross destroy everything, free_scene, exit(0).

On a miss, the background is a vertical white→blue gradient render.c:19-29 — an aesthetic choice, not black; one line to change.

03 · subsystemParser

srcs/parser/ — entry: parse_scene(file, scene), parse_scene.c:83

End-to-end flow

1. Extension check parse_scene.c:51-61, 87-88 — needs len >= 4 and the last 3 chars == ".rt" (shortest valid name is a.rt; case-sensitive).
2. open(file, O_RDONLY) :89-91 — failure → error. A directory named foo.rt opens fine, but the first read() returns −1 (EISDIR), caught at :37-38 as “read error”.
3. ft_memset(scene, 0, …) :92 — zeroes the has_* flags and NULLs the lists.
4. Line loop read_all :63-81 — read_line → split_line → dispatch → free the line and tokens immediately.
5. Post-conditions :95-96 — missing any of A/C/L → error. A scene with zero objects is legal (renders only the background).

read_line — the hand-rolled GNL

parse_scene.c:23-49

Mallocs a 4096-byte buffer and reads the fd one byte at a time until \n, EOF, or 4095 chars. Return contract:

• returns the line if i > 0 || ret > 0 — the ret > 0 part means a bare \n returns an empty string, not NULL, so blank lines don't terminate parsing (they produce zero tokens and are skipped at :77);
• returns NULL only at true EOF with nothing read.

The 1 MiB size cap parse_scene.c:16-21 · commit ab79a0f: bump_total() counts each byte actually consumed into a line (called after the newline-break, so newlines don't count) and errors past 1 048 576 bytes. History: the old version over-counted and rejected a legitimate 10 000-object scene; the fix counts only bytes really read.

Tokenization & dispatch

• split_line tok_utils.c:52-76 — two-pass whitespace splitter. Whitespace is ft_isspace = space + ASCII 9–13, so CRLF files parse fine (the \r is stripped).
• dispatch dispatch.c:23-43 / dispatch_bonus.c:40-54 — first token → parser. A first token starting with # skips the line (comment support). Unknown identifier → Error\nunknown identifier: <tok>, exit 1. Inline comments after data are not supported (they become extra tokens).

Number parsing — three layers

1. valid_num parse_num2.c:28-44 — strict grammar before conversion: optional single sign, ≥1 digit, optional . + ≥1 digit, end of string. Rejects: "", "+", "1.", ".5", "++5", "1.2.3", "1e5", "0x1F".
2. ft_strtod parse_num.c:61-74 — sign + integer part + fraction part. Deliberately no scientific notation.
3. Range checks — parse_double parse_utils.c:15-28 enforces |v| ≤ 1 000 000; parse_ratio :30-38 enforces [0,1].

Triples go through next_component parse_num2.c:46-71 — the trickiest function in the parser:

if (!last && **s == ',')
    *s += 1;
else if (!last || **s != '\0')
    error_exit("expected exactly three comma separated values");

Read it as: not-last ⇒ a comma must follow (consume it); last ⇒ end-of-string must follow. Every malformed shape — 1,2 · 1,2,3,4 · 1,,3 · 1,2, — falls into the error. The 64-byte local buf with its i < 63 copy guard means a 200-digit component just stops copying, leaves *s on a char that is neither , nor \0, and hits the same clean error — no overflow possible.

• Colors parse_utils.c:40-58 — each component must be an integer in [0,255] (v != (int)v rejects 12.5), then is normalized to [0,1] by ÷255. All downstream color math is linear [0,1]; conversion back to 0–255 happens only at pixel-write time.
• Orientation vectors parse_utils.c:70-81 — each component in [−1,1], vector must not be ~zero (vec3_near_zero), then re-normalized with vec3_norm. So 0.5,0.5,0 is accepted and canonicalized rather than rejected — deliberate tolerance for rounding (e.g. 0.577,0.577,0.577); say so up front.

Element parsers

Bonus per-object material tail parse_opts_bonus.c:21-44, appended after the color: [ks] [shininess] [refl] [transp] [ior] [checkerboard 0/1] [checker_size]. Defaults from default_material material.c:15-31: ka .1, kd .9, ks .3, shininess 32, refl/transp 0, ior 1, checker off, size 1. Of these, only ks, shininess, checkerboard, checker_size are actually consumed by shading — the rest are forward-looking storage (admit it if asked).

Memory management

• Objects/lights: singly linked lists of individually malloc'd nodes, tail-append.
• Normal teardown: free_scene free_scene.c:15-36 walks both lists; called from the window-close path.
• On a parse error mid-file: error_exit main.c:33-39 writes Error\n + message to stderr and exit(1) — nothing is freed, but everything already allocated is still referenced from live stack frames, so valgrind reports it as “still reachable”, not “definitely lost”.

04 · subsystemMath toolkit

srcs/math/ — all vec3 functions are by-value: no pointers, no allocation

The shared quadratic solver

math/quad.c · t_quad in miniRT.h:169

Sphere, cylinder and cone are all at² + bt + c = 0. The t_quad struct is shared scratch space — the extra fields d f m n root exist so helpers stay under Norm limits without recomputing: the cylinder caches its projected vectors in d/f, the cone caches axis dot products in m/n.

• quad_solve quad.c:20-27 — disc = b² − 4ac; negative → miss (return 0); else cache sqrt_disc.
• quad_root1 = (−b − √disc)/2a — the near root (entry point).
• quad_root2 = (−b + √disc)/2a — the far root (exit; the relevant one when the ray starts inside the object, since root1 is then behind the origin).
• quad_nearest quad.c:46-55 — try root1, accept if t ≥ EPSILON; else root2; else miss. One call handles outside rays, inside rays, and objects behind the camera.

05 · subsystemIntersections

srcs/intersect/

Dispatch & nearest hit

• hit_object hit_object.c:15-24 — if/else on obj->type → sphere/plane/cylinder. The bonus version hit_object_bonus.c:15-28 adds cone and triangle. This one-file swap is the entire mandatory/bonus split on the intersection side.
• intersect_scene intersect.c:15-37 — walks the list, closest starts at 1e15, keeps hits with tmp.t < closest, copies the winning t_hit out whole. O(n) per ray — no BVH; fine at miniRT scale.

Every intersector fills the full t_hit: t, point, unit normal that always faces the ray, mat (a pointer into the object — no copy), front_face.

Sphere

sphere.c

Math. P on sphere ⟺ |P − C|² = r². Substitute P = O + tD, let oc = O − C:

(D·D)·t² + 2(oc·D)·t + (oc·oc − r²) = 0

Code mapping sphere.c:34-52: oc at :40, a = dot(dir,dir) :41 (would be 1.0 for unit dirs — computed anyway so the formula stays correct for any caller), b = 2·dot(oc,dir) :42, c = dot(oc,oc) − r² :43, then quad_solve + quad_nearest :44, fill hit :46-50.

Normal flipping — set_face_normal sphere.c:17-29: the outward normal is normalize(P − C); if dot(ray.dir, outward) < 0 the ray sees the outside → keep it, front_face = 1; otherwise the ray hit from inside (origin inside the sphere, quad_nearest returned root2) → negate, front_face = 0. Shading always receives a normal pointing against the incoming ray (the “Ray Tracing in One Weekend” convention).

Plane

plane.c

Solve (O + tD − p0)·n = 0 → t = ((p0 − O)·n) / (D·n).

• denom = dot(dir, normal) :21; |denom| < EPSILON → parallel → miss (:22) — also protects the division.
• t < EPSILON rejected (:26).
• Two-sided (:31-35): denom < 0 ⇒ the ray faces the stored normal → keep it; denom > 0 ⇒ the ray comes from behind → return the negated normal. Same “normal faces the ray” invariant, derived directly from denom's sign (no extra dot product — denom is dot(dir, n)).

Cylinder — the defense centerpiece

cylinder.c + cylinder_utils.c

Decomposition: infinite tube clipped by height + top disk + bottom disk, tested independently; smallest valid t wins (intersect_cylinder cylinder.c:81-103, min-reduction starting at INFINITY).

(a) Body quadratic — cylinder_quadratic cylinder_utils.c:18-34

P is on the infinite tube (center C, unit axis A, radius r) ⟺ the component of P − C perpendicular to the axis has length r. Instead of expanding a messy scalar formula, the code projects the axis component out first:

q->d = dir − (dir·A)A;      /* direction, axis part removed          */
q->f = oc  − (oc·A)A;       /* origin offset likewise (oc = O − C)   */
a = d·d;   b = 2·(d·f);   c = f·f − r²;

i.e. an ordinary circle quadratic in the plane perpendicular to the axis. Edge case at :28: a ≈ 0 ⇒ ray parallel to the axis ⇒ it can never cross the wall → return 0 (the caps still get tested). Also protects the ÷2a divisions.

(b) Height clamp — valid_body_hit cylinder_utils.c:39-49

proj = (P − C)·A is the signed distance along the axis from the (mid-height) center; valid iff −h/2 ≤ proj ≤ h/2 and t ≥ EPSILON.

(c) Root selection with clipping — hit_body cylinder.c:18-37

(d) Caps — hit_cap cylinder.c:56-76

Via cap_plane (:42-54): top uses top_center/+axis, bottom uses bottom_center/−axis; then plane intersection + disk membership |P − cap_center|² ≤ r² (:71-73 — squared, no sqrt). set_cap_hit cylinder_utils.c:84-93 flips the cap normal toward the ray like everything else. The cap centers were precomputed at parse time.

(e) Body normal — body_normal cylinder_utils.c:55-64

Project the hit point onto the axis, subtract: normalize(P − (C + proj·A)) — the radial vector at that height, perpendicular to the axis by construction.

(f) Camera inside the cylinder

scenes/cylinder_inside.rt proves it. root1 < 0 → rejected; root2 (the wall you're looking at) accepted; check_body_hit cylinder_utils.c:66-79 sees dot(dir, outward) > 0 → front_face = 0, normal negated → the interior wall shades correctly.

Cone (bonus)

cone_bonus.c + cone_utils_bonus.c

Stored as apex + axis (apex→base) + base radius + height; slope k = radius/height = tan(half-angle) cone_utils_bonus.c:27.

Body quadratic — cone_quad :20-36: P on cone ⟺ |perp(P−apex)|² = k²·((P−apex)·A)². Same perpendicular-decomposition trick, with m = dir·A, n = oc·A cached in the quad struct:

a = d⊥·d⊥ − k²m²;
b = 2·(d⊥·oc⊥ − k²mn);
c = oc⊥·oc⊥ − k²n²;

The −k²(…) terms are exactly what turns a cylinder into a cone: the allowed radius grows linearly with axial distance.

Height clamp & the double-cone trap — check_cone_body :54-74: proj = n + t·m (algebraically (P−apex)·A, but two dot products cheaper); valid iff 0 ≤ proj ≤ height.

Base cap: one disk at apex + axis·height cone_bonus.c:34-35, same plane+disk test; there is no apex-end cap (it's a point).

Body normal — cone_body_normal cone_utils_bonus.c:42-52: normalize(perp − k²·proj·axis) where perp is the radial vector. Why the −k²·proj·axis term: the surface is the zero set of F(P) = |perp|² − k²·proj²; the normal is its gradient ∇F ∝ perp − k²·proj·axis. A purely radial normal would shade like a cylinder.

Triangle (bonus) — Möller–Trumbore

triangle_bonus.c

Solve the linear system O + tD = v0 + u·e1 + v·e2 (e1 = v1−v0, e2 = v2−v0) by Cramer's rule via scalar triple products; hit iff u ≥ 0, v ≥ 0, u+v ≤ 1 (barycentric containment). No quadratic.

tri_solve :25-50: h = dir × e2, det = e1·h — |det| < EPSILON ⇒ ray parallel to the triangle's plane ⇒ miss. The sign of det is kept: > 0 front face, < 0 back face (triangles are two-sided; the precomputed normal is just flipped by det's sign at render time :63-67 — no per-ray cross product). u is computed and range-checked before v (early exit), then t = (e2·(s×e1))/det, rejected below EPSILON.

06 · subsystemCamera & render loop

srcs/render/

Camera basis

camera.c

Pinhole model with the viewport at distance 1 in front of the camera:

• half_w = tan((fov · π/180) / 2) :42 — FOV is horizontal, per subject. Trig: opposite/adjacent with adjacent = 1.
• half_h = half_w · (HEIGHT/WIDTH) :43 — aspect ratio keeps pixels square, spheres round.
• Soutenance fix commit 228f5f3 — it used to be the other way around (half_h = tan(…), FOV effectively vertical); the fix swapped the two lines.
• horizontal/vertical = full spanning vectors; lower_left = pos + dir − right·half_w − up·half_h :47-50.

Orthonormal axes — get_camera_axes camera.c:21-31:

if (fabs(dir.y) < 0.99)  world_up = (0,1,0);  else  world_up = (0,0,1);
right = norm(cross(dir, world_up));
up    = norm(cross(right, dir));

Edge case: a camera looking straight up/down would make cross(dir, (0,1,0)) the zero vector (normalizing = ÷0) — the 0.99 guard swaps the hint to (0,0,1). up is re-derived from right × dir so the basis is exactly orthogonal even when dir isn't perpendicular to the hint.

Ray generation — get_ray camera.c:64-75: target = lower_left + u·horizontal + v·vertical; dir = normalize(target − origin). (u,v) ∈ [0,1]².

Render loop

render.c

• render :78-93 — basis built once per frame; double loop y then x; one mlx_put_image_to_window at the end (:92).
• 2×2 supersampling — render_pixel :58-76: 4 rays per pixel at sub-pixel offsets 0.25 / 0.75 in each axis, averaged (×0.25 at :75). Stratified anti-aliasing; total 800×600×4 = 1.92 M primary rays per frame (why keypress re-renders visibly lag).
• u/v mapping — get_sample_color :45-56: u = px/WIDTH, v = 1 − py/HEIGHT — the y-flip: image memory row 0 is the top of the window but viewport v grows upward from lower_left.
• ray_color :34-43 — returns black if depth <= 0 but never recurses or decrements — MAX_DEPTH is scaffolding for a reflection bounce loop that was never enabled. Honest answer if asked.

Camera movement

translation.c + window/mlx_hooks.c

• W/S move along ±dir, A/D strafe along ±right (recomputed with the same up-hint logic, translation.c:18-27), speed 0.5, then full re-render.
• Mouse scroll (buttons 4/5): FOV ∓5°, clamped to [1,179], re-render.
• SPACE toggles app->is_locked (movement/zoom ignored while locked). The camera starts locked (is_locked = 1 in mlx_setup) — press SPACE first when demoing movement.
• Arrow keys are defined in the header but not handled — only WASD works (§12).

07 · subsystemShading — mandatory

srcs/shading/

shade shade.c:17-34: final = ambient + Σ lights (in_shadow ? 0 : diffuse), then color_clamp. (void)ray; at :22 — no specular in mandatory. The loop is list-shaped but the mandatory parser guarantees exactly one light.

Ambient — know this formula, it was a graded fix

ambient.c:15-21 · commit cc27a56

amb = color_scale(ambient->color, ambient->ratio);   /* A color × ratio  */
return color_multiply(hit->mat->color, amb);         /* ⊗ object color   */

The old version multiplied the object color in twice and dampened by ka = 0.1, making shadows nearly black and ignoring the A color. Numeric sanity check on scenes/min_shadow.rt: lit ≈ 150 vs shadowed ≈ 7 ≈ 0.05 × 150 (ratio 0.05). ✔

Diffuse — Lambert

diffuse.c:15-27

to_light  = norm(light->pos − hit->point);
intensity = max(0, dot(N, L)) · brightness · attenuation(light, point);
return color_scale(hit->mat->color, intensity);

dot(N,L) = cos θ: full strength when the surface faces the light, zero at grazing or facing away (the max(0, ·)). Notes: mandatory never multiplies by light->color (subject: unused in mandatory) and the material kd is parsed but never applied — brightness is the only diffuse gain.

Shadows

shadow.c

make_shadow_ray :16-28 offsets the origin point + SHADOW_BIAS·normal + SHADOW_BIAS·to_light (bias 1e-4). Why: without it, the shadow ray re-hits its own surface at t ≈ 1e-15 → every point thinks it's shadowed → “shadow acne” speckle. Offsetting along both normal and light direction covers grazing geometry. in_shadow :30-41 reuses the same intersect_scene:

if (intersect_scene(shadow_ray, scene, &tmp))
    return (tmp.t < light_dist - SHADOW_BIAS);

Only a hit strictly between point and light blocks; correct because intersect_scene returns the nearest hit, and t is world-distance because directions are unit length.

Attenuation

attenuation.c:15-25

1 / (kc + kl·d + kq·d²), clamped ≤ 1. The mandatory parser sets kc=1, kl=0, kq=0 → always exactly 1.0 (the subject has no falloff; the machinery is present but neutral). ⚠ The bonus parser forgets to set these — §12 bug #1.

Color pipeline

color.c + window/mlx_utils.c

All colors are doubles in [0,1] end-to-end (color_scale/add/multiply/clamp/lerp). color_clamp at the end of shade is required because several additive terms (multi-light + specular) can exceed 1.0, and 1.2 × 255 = 306 would bleed into the neighboring channel via the bit-shift packing. mlx_put_pixel mlx_utils.c:18-29 packs (int)(c × 255.999) per channel — ×255.999 maps 1.0 → 255 without hitting 256 — and writes *(unsigned int *)(addr + y·line_len + x·(bpp/8)).

08 · subsystemShading — bonus additions

shade_bonus.c · specular_bonus.c · checker_bonus.c

shade, bonus version shade_bonus.c:17-38:

apply_checker(hit, &tmp);                       /* may repoint hit->mat  */
final = ambient_light(hit, &scene->ambient);
while (light) {
    if (!in_shadow(scene, hit, light))
        final += color_multiply(diffuse + specular, light->color);
    light = light->next;
}
return color_clamp(final);

Four differences vs mandatory: checkerboard first, a real multi-light loop, Phong specular, and each light's contribution tinted by its own color commit b3f6ba6 — the color “was always parsed but never used”; a red light on a white sphere now gives ≈ (152, 51, 51). Ambient is deliberately not tinted by point lights.

Phong specular

specular_bonus.c:20-38 — true reflect-vector Phong, not Blinn half-vector

R = vec3_reflect(−to_light, normal);          /* v − 2(v·n)n     */
V = norm(−ray.dir);
spec = pow(max(0, dot(R, V)), shininess) · ks · brightness;
return white × spec;

The highlight base is white — it reflects the light source, not the object (that's why a red ball gets a white glint); it becomes light-tinted by the per-light multiply above. ks = 0.3, shininess = 32 by default, per-object overridable.

Checkerboard — 3D solid procedural texture (not UV)

checker_bonus.c

sum = floor(p.x/size) + floor(p.y/size) + floor(p.z/size);
if (sum % 2)  color = 1 − color;   /* photographic negative of the cell */

Space is diced into size-cubes; cell parity picks the original color or its inverse. floor() (not cast truncation) keeps cells consistent across negative coordinates; C's % on negatives yields −1, which is truthy, so alternation continues correctly through the origin. Works on every primitive because it only needs the 3D hit point. Trade-off to defend: a sphere looks “carved from a checkered block,” not latitude/longitude tiles like UV mapping would give.

09 · subsystemWindow & MLX

srcs/window/

mlx_setup

mlx_init.c:15-29

Straight-line init, NULL-checked at every step: mlx_init() (:17 — failure → Error\nmlx_init failed, exit 1; verified to fail cleanly with no DISPLAY, no segfault), mlx_new_window(800, 600, "miniRT") (:20), mlx_new_image (:23), mlx_get_data_addr (:26 — fills bpp, line_len, endian). Ends with app->is_locked = 1 (:28) — the camera starts LOCKED; press SPACE before demoing movement!

mlx_put_pixel

mlx_utils.c:18-29

argb = ((int)(r*255.999) << 16) | ((int)(g*255.999) << 8) | (int)(b*255.999);
dst  = mlx->addr + y * line_len + x * (bpp / 8);
*(unsigned int *)dst = argb;

• line_len = padded stride in bytes per row — the X server may align rows, so hardcoding WIDTH*4 could shear the image. Likewise bpp/8 vs a literal 4.
• ×255.999 maps 1.0 → 255 without ever producing 256.
• Why an image buffer and not mlx_pixel_put? mlx_pixel_put is one X11 round-trip per pixel (480 000 per frame); we write RAM and blit once. Also, pixels drawn before the window is mapped are lost — an image persists and the Expose handler re-puts it.

Events

main.c:24-28 + mlx_hooks.c — the magic numbers are X11 protocol event codes

• key_handler mlx_hooks.c:42-68 — ESC → close_handler; SPACE toggles is_locked (prints 🔒/🔓); when locked everything else is ignored; WASD move at speed 0.5 + re-render.
• close_handler mlx_hooks.c:70-78 — both ESC and the red cross funnel here: mlx_destroy_image → mlx_destroy_window → mlx_destroy_display (added in the soutenance commit; kills an X connection leak) → free(mlx.ptr) → free_scene → exit(0).
• expose_handler :80-84 — re-puts the stored image, so the window survives minimize/overlap without re-raytracing, and the first frame isn't lost if the put happens before the window is mapped.

10 · operationsScenes guide

Mandatory format: A ratio r,g,b · C pos dir fov · L pos brightness r,g,b · sp pos diameter color · pl point normal color · cy center axis diameter height color.

scenes/ — run with ./miniRT

scenes/bonus/ — run with ./miniRT_bonus

Bonus syntax by example (from showcase.rt)

L  -8,10,-6  0.8  255,80,80                    # colored light (color IS used in bonus)
co 4,-3,3  0,1,0  2.5  6  60,200,120  0.5 32   # cone: apex axis RADIUS height color [ks shin]
tr -1,4,7  -3,1,7  1,1,7  220,180,60           # triangle: three vertices + color
pl 0,-3,0  0,1,0  200,200,200  0.4 64 0 0 1 1 2
#  tail: ks=0.4 shininess=64 refl=0 transp=0 ior=1 checkerboard=1 size=2

The bonus scenes also demonstrate # comments and blank lines being accepted.

11 · operationsBuild & project health

zero warnings no relink norminette clean no forbidden functions

• Makefile: make → miniRT, make bonus → miniRT_bonus, flags -Wall -Wextra -Werror -ggdb; builds mlx_linux and libft first; links -lmlx -lft -lXext -lX11 -lm. Verified: both targets compile with zero warnings, and re-running make does not relink (“Nothing to be done”) — a standard evaluator check. Objects depend on both headers (Makefile:109), so header edits rebuild correctly.
• Norminette 3.3.59: fully clean on includes/, srcs/, libft/.
• Forbidden functions: clean. nm -u on both binaries minus MLX/libc internals leaves only open close read write malloc free exit and math (sqrt tan, + floor pow in bonus, allowed via -lm). The suspicious-looking rest (calloc getenv gethostname shm* strlen strncmp puts) all come from inside MiniLibX (X shared memory, getenv("DISPLAY")) — zero hits in project code. Number parsing is a homemade ft_strtod, not libc atof.

The soutenance commit (228f5f3) — “what did you fix recently?”

1. mlx_destroy_display on close — X connection leak fixed.
2. The Expose handler — the window survives minimize; the image is re-put if the first draw beats the window mapping.
3. FOV made horizontal, as the subject defines (camera.c).
4. A cylinder bug where a ray whose only hit was the bottom cap was lost (best not updated) — fixed in cylinder.c.
5. read_line read a byte before checking read's return — an uninitialized read when handed a directory — fixed.
6. The 1 MB scene cap (then refined by ab79a0f to count only bytes actually read, and c026715 to fit the norm's 25-line limit).

12 · operationsKnown weaknesses — read before the defense

2. MAX_DEPTH / depth is dead scaffolding — no recursion (no reflection/refraction). Say it plainly: “hook for a bounce loop; rays terminate at first hit.”
3. ka, kd, reflectivity, transparency, ior, roughness are parsed/stored but never used in shading; only ks/shininess/checker fields are consumed.
4. Error paths don't free — but everything stays reachable (§03); verify with valgrind and quote the numbers.
5. Performance: 4 rays/pixel, full re-render per keypress, linear object list. A 10k-object scene is slow — that's why the 1 MiB parse cap exists.
6. mlx_put_pixel assumes 32 bpp little-endian (*(unsigned int *)dst; endian stored but unused) — always true on evaluation Linux/X11.
7. Cone a ≈ 0 (ray parallel to the slant) has no explicit guard like the cylinder's: roots become ±inf and are rejected by the proj range check — implicit but harmless; know it.
8. Lines > 4095 chars are split by read_line; the continuation chunk fails as “unknown identifier” — clean failure, no overflow.
9. Camera within ~8° of vertical (the 0.99 threshold) switches the up-hint — can cause a visible roll change between two nearly-vertical cameras; cosmetic.
10. Plane t = 0 rejected by EPSILON — a camera exactly on a plane doesn't see it; by design.
11. The checkerboard token is a truncating cast (0.9 → 0) and checker_size ≤ 0 is accepted by the parser (but neutralized in apply_checker) — defensible as “documented format: 0/1 and a positive size.”
12. README vs reality: the header defines KEY_UP/DOWN/LEFT/RIGHT (miniRT.h:34-37) and the README advertises arrow keys, but key_handler only acts on WASD (mlx_hooks.c:62). The README also mentions reflection/transparency — parsed-but-unimplemented material fields. Either align the README before the defense or don't demo those.
13. error_exit after parsing (e.g. mlx_new_window failure) exits without free_scene — OS-reclaimed and still-reachable, but know it exists. Also mlx_get_data_addr's return is not NULL-checked (mlx_init.c:26).
14. The camera starts locked (is_locked = 1, mlx_init.c:28) — not a bug, but forget to press SPACE during the demo and movement “doesn't work.”

13 · defenseQ&A drill

Tap a question, answer out loud, then reveal. Use the buttons to open or close a whole group.

14 · defenseThe final 24 hours

1. Hour 0-1 — read §00 + §02 twice. Draw the pipeline from memory once.
2. Hour 1-3 — parser. Open parse_scene.c and follow one line of a real scene through read_line → split_line → dispatch → parse_sphere with this guide beside you. Rehearse next_component out loud.
3. Hour 3-6 — intersections. Re-derive on paper: the sphere quadratic, plane t, the cylinder perpendicular decomposition. Then read the code and match each line to your derivation. The cylinder is the most-asked topic — overlearn it.
4. Hour 6-8 — camera + render. Recompute half_w for FOV = 70 on paper; explain the y-flip and the 4-ray averaging.
5. Hour 8-10 — shading. Learn the ambient formula (it was a fix — evaluators love “why did this change”). Walk shade_bonus with a two-light scene.
6. Hour 10-11 — run everything: make re && make bonus, every scene in scenes/ and scenes/bonus/, valgrind on a good and a bad scene, norminette.
7. Hour 11-12 — decide about §12 bug #1 (fix it or prepare to own it).
8. Remaining — drill §13 with a partner or a rubber duck; sleep.

Live-demo checklist

• ./miniRT scenes/full_mandatory.rt — the main demo.
• ./miniRT scenes/cylinder_inside.rt — camera inside a cylinder works.
• ./miniRT scenes/min_shadow.rt — hard shadow + correct ambient in shadow.
• Bad inputs ready to type: ./miniRT, ./miniRT x.txt, a scene with 1,2,, RGB 256, FOV 180, duplicate C, missing L.
• ./miniRT_bonus scenes/bonus/showcase.rt (+ the others) for the bonus tour.
• Press SPACE to unlock the camera before demoing WASD/scroll; demo WASD only — arrow keys are not handled.
• valgrind --leak-check=full output pre-captured for a good and a bad run (and settle §12 bug #1 first — valgrind on the bonus flags it today).

15 · defenseGlossary