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 set a needs_render flag; a mlx_loop_hook re-runs steps 3–7 in 32-row slices, preview-first (§P1). 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.

Z1 · level zeroOne pixel's question

The easiest way to understand this project is not to start with the formulas. Start with what the computer is trying to accomplish, and meet each piece of math only at the exact moment the program needs it. That's what this Level-zero part does — no formula appears before the program has a problem only that formula can solve.

Forget the whole program. The final job is: fill an 800 × 600 rectangle of pixels with colors. So think about one single pixel. Imagine standing in a room, looking through a window — except the window is made of pixels. For every pixel, miniRT imagines a straight line going eye → through this pixel → into the 3D world, and asks:

Answering it is a fixed ladder of smaller questions:

pixel
  ↓
make a ray through that pixel
  ↓
does the ray hit something? ──── NO → background color
  ↓ YES
which object? (the nearest one)
  ↓
where exactly?
  ↓
which way is the surface facing there?
  ↓
is light reaching that point?
  ↓
how bright, what color?
  ↓
write RGB into the pixel

That's basically the whole project. The real code follows this ladder almost line for line: main parses and creates the window; render generates rays; intersect_scene finds the nearest hit; shade computes the lighting; mlx_put_pixel writes the RGB. Repeat 480 000 times.

What the .rt file actually is

A scene file like this is not the picture:

A 0.2  255,255,255          ← "there is a bit of light everywhere"
C 0,0,0  0,0,1  70          ← "the eye stands here, looks this way"
L 5,5,0  0.8  255,255,255   ← "a lamp hangs here"
sp 0,0,5  4  255,0,0        ← "a red ball floats there"

It is a description of a world. The parser's whole job is to transform that text into C structures — scene.camera, scene.lights, scene.objects — by reading each line, splitting it into words, and looking at the first word (read_line → split_line → dispatch). Note what this means: no geometry happens during parsing. We're just loading data. All the interesting questions start after.

Z2 · level zeroA tiny 2D world

Before any 3D, let's answer one real question the renderer faces, in a world simple enough to draw on graph paper. Two dimensions, everything on a grid:

y
5                    💡 light (5,5)
4
3
2        X ← the ray hit something here (2,2)
1
0    👁 camera
     0   1   2   3   4   5     x

The program needs to know: from X, which way is the lamp? You can answer without knowing anything about "vectors": starting at (2,2), to reach (5,5) you must move 3 right and 3 up, because 5−2 = 3 and 5−2 = 3. So:

Now the same move the program actually cares about — three positions of the lamp, same surface:

• Lamp straight above the surface → the surface catches it fully → bright.
• Lamp off to the side → the light grazes along the surface → dim.
• Lamp behind the surface → nothing arrives → dark (not "negative brightness" — just zero).

Later, one number will express all three cases at once (the dot product, M2/M8). For now it's enough that the question is geometric: "how squarely does this surface face the lamp?"

3D just adds one number

Everything above works identically with a third coordinate: positions become (x, y, z), subtraction subtracts three numbers instead of two. That's the entire jump to 3D. But keep one warning from the start — the same t_vec3 struct is used for two different meanings:

Z3 · level zeroOne pixel, all the way down

This is the showpiece: the whole program executed by hand, with real numbers, for one pixel. Every step names the function that does the same thing in code. The scene is the one from Z1:

A 0.2  255,255,255
C 0,0,0  0,0,1  70
L 5,5,0  0.8  255,255,255
sp 0,0,5  4  255,0,0        ← center (0,0,5), DIAMETER 4 → radius 2, red

Step 0 — parse. The camera sits at the origin looking along +z; the red sphere floats 5 units ahead; a white lamp hangs up-right at (5,5,0); ambient is 20% white. Color 255,0,0 is stored as (1, 0, 0). parse_scene → dispatch → parse_sphere

Step 1 — the ray. Take the pixel in the exact middle of the screen. The viewport is centered on the view direction, so the middle pixel's ray is simply "straight ahead": origin O = (0,0,0), direction D = (0,0,1) — already unit length. build_camera_basis, get_ray

Step 2 — does it hit the sphere? Run the quadratic recipe (built from scratch in M6):

oc = O − C = (0,0,−5)
a  = D·D            = 1
b  = 2·(oc·D)       = 2·(−5) = −10
c  = oc·oc − r²     = 25 − 4 = 21
disc = b² − 4ac     = 100 − 84 = 16  → positive: the ray crosses twice
t = (10 ± 4) / 2    → t₁ = 3 (entry),  t₂ = 7 (exit)

Keep the smallest positive t: t = 3. No other object exists, so the sphere wins the "nearest hit" contest by default. intersect_sphere, quad_solve, quad_nearest, intersect_scene

Step 3 — where exactly? Walk the ray: P = O + 3·D = (0,0,3). Sanity check: the sphere's near surface is at z = 5 − 2 = 3. ✓ ray_at

Step 4 — which way does the surface face? For a sphere, the outward direction at P is "away from the center": P − C = (0,0,−2), normalized: N = (0,0,−1) — pointing back at the camera. Makes sense: we hit the front of the ball. set_face_normal

Step 5 — which way is the lamp? Subtraction, exactly like Z2:

to_light = L − P = (5,5,0) − (0,0,3) = (5, 5, −3)
length   = √(25 + 25 + 9) = √59 ≈ 7.68
L̂ = (5,5,−3)/7.68 ≈ (0.651, 0.651, −0.390)

diffuse.c / shadow.c

Step 6 — is anything blocking it? Fire the shadow feeler from P (nudged off the surface by SHADOW_BIAS) toward the lamp. The scene has one object — the sphere we're standing on — and the feeler leaves it immediately; nothing sits within the 7.68 units to the lamp. Lit. in_shadow → intersect_scene

Step 7 — how bright? "How squarely does the surface face the lamp?" — the dot product delivers the cosine:

dot(N, L̂) = 0·0.651 + 0·0.651 + (−1)·(−0.390) = 0.390
diffuse   = 0.390 × brightness 0.8 = 0.312          (about ⅓ strength — the lamp
                                                     is well off to the side)

diffuse_light

Step 8 — assemble the color. Every term filters through the object's color (1,0,0):

ambient = (1,0,0) ⊗ (white × 0.2)  = (0.200, 0, 0)
diffuse = (1,0,0) × 0.312          = (0.312, 0, 0)
total   =                            (0.512, 0, 0)   ← already within [0,1], clamp changes nothing

shade, ambient_light, color_clamp

Step 9 — become memory. 0.512 × 255.999 ≈ 131, so the packed pixel is RGB(131, 0, 0) — a dark-ish red, written at addr + y·line_len + x·(bpp/8). One integer in memory. One pixel of the image. mlx_put_pixel

Z4 · level zeroFour rays per pixel, and why WASD re-renders everything

The staircase problem

Screens are made of square pixels; the world has curved and diagonal edges. If each pixel asks its question only once — through its center — every pixel is answered "entirely sphere" or "entirely sky", and a diagonal edge becomes a staircase (that artifact is called aliasing):

real edge:        what square pixels make of it:
      /                  ██
     /                 ██
    /                ██
   /               ██

The fix in this project: ask four times per pixel, at four spots inside the pixel's little square (a 2×2 grid — "supersampling"), and average the four answers. A pixel straddling the sphere's edge might get two answers "red sphere" and two "sky blue" — its final color is the 50/50 blend, and the staircase melts into a smooth ramp. Important: the screen is still 800 × 600; the four samples are questions, not pixels (render_pixel, render.c:58-76).

Pressing W

Every ray starts at the camera. Press W and the code does, almost literally in English:

Two things follow. First, the invisible viewport isn't an object stored in the world — it is calculated from the camera, so it moves with it and must be rebuilt (build_camera_basis). Second, every one of the 480 000 pixels now shoots from a different place — the old image cannot be "shifted a few pixels"; the whole frame must be recomputed. That cost used to freeze the window on every keypress — §P1 tells the story of how it was hidden (a cheap preview while moving, sliced rendering so input never waits, and a full-quality pass once you stop).

Strafing with A/D needs a "right" direction the camera never stored — so the code manufactures one with the cross product (M3) and does the same position-plus-movement. And note WASD only translates: position changes, the looking direction doesn't. (Rotation would be the opposite — same position, new direction.)

Z5 · level zeroThe vocabulary — what each piece of math is FOR

Memorize these jobs, not the formulas. Every formula in the project belongs to one of these one-line answers:

What you're really learning (and the order to learn it)

Everything in miniRT belongs to four families that compose: A — C architecture (parser, structs, lists, MLX, events); B — basic 3D math (vectors, length, normalize, dot, cross, tan); C — geometry (rays, t, shape equations, normals, closest hit); D — graphics (camera, lighting, shadows, RGB, anti-aliasing, image buffer). None is the result by itself; the dependency chain runs straight through them:

coordinates → positions & directions → vector ops → length + normalize
    → camera/viewport → pixel → ray → O + t·D → shape equations → t
    → closest t → hit point → normal → to-light → dot → brightness
    → shadow ray → RGB → 4-sample average → MLX pixel → IMAGE

That chain is the recommended learning order. In this handbook it maps to: this Level-zero part → Foundations M1–M9 (each tool in depth, with hand-checkable numbers) → the subsystem chapters §03–§09 (the real code) → §13 (the Q&A drill). Leave the bonus shapes (cone, Möller–Trumbore) and specular for last — until sphere + plane + camera + diffuse feel obvious, they only add noise.

M1 · foundationsVectors from zero

Everything in this project happens in a 3D world. To describe that world we only need one tool: three numbers written together, like (2, 1, 5). That triple is called a vector, and in the code it is the struct t_vec3 with fields x, y, z. The trick is that the same triple is used for two different jobs, and you must always know which job it is doing:

• A position ("where"): (2, 1, 5) can mean the point that is 2 steps right, 1 step up, 5 steps forward from the origin. The sphere's center, the camera's position, a hit point — these are positions.
• A direction ("which way, how fast"): the same (2, 1, 5) can mean an arrow pointing that way. A ray's direction, a surface normal, "toward the light" — these are directions. A direction has no home; only orientation and length.

The four basic operations

All vector math in srcs/math/vec3.c is done component by component — there is nothing more to it:

Length, and why we "normalize"

How long is the arrow (3, 4, 0)? In 2D you'd use the Pythagorean theorem (a² + b² = c² for right triangles). It works the same in 3D — just add the third square:

A vector whose length is exactly 1 is called a unit vector. Normalizing means rescaling a vector to length 1 without changing its direction: divide every component by the length. (3, 4, 0) normalized is (0.6, 0.8, 0) — same direction, length 1. That's vec3_norm vec3_bis.c:20.

M2 · foundationsThe dot product — the single most used tool

The dot product takes two vectors and produces one plain number. Computing it is trivial (vec3_dot, vec3_ops.c:16):

The magic is what that number means. There is a second, equivalent definition:

So the dot product answers the question: "how much do these two arrows agree in direction?" You don't need to compute any angle — three multiplications and two additions give you the cosine for free. Everything is in the sign and size:

Every place this project uses it

M3 · foundationsThe cross product — making perpendiculars

The cross product a × b takes two vectors and produces a new vector (not a number) with two famous properties (vec3_cross, vec3_ops.c:22):

• It is perpendicular to both a and b — it sticks straight out of the plane the two arrows lie in. Which of the two possible "straight out" sides? The right-hand rule: point your right hand's fingers along a, curl them toward b — your thumb shows a × b. (Swap the order and the result flips sign.)
• Its length equals the area of the parallelogram the two arrows span. If a and b are parallel, that area is 0 — the cross product is the zero vector.

Where the project needs perpendiculars

• The camera basis camera.c:21-31: given only "the camera looks this way" (dir), we need a "right" and an "up" to span the screen. right = norm(cross(dir, world_up)) — guaranteed perpendicular to the view direction. Then up = cross(right, dir) makes the third perpendicular. Edge case: if dir is straight up, cross(dir, world_up) is between parallel vectors = zero vector = can't normalize → the code switches to a different helper vector first. Now that guard makes sense.
• The triangle's normal parse_objects_bonus.c:52: two triangle edges lie in the triangle's plane, so cross(v1−v0, v2−v0) sticks straight out of the triangle — that IS the normal. And if the three points are on one line (a degenerate "triangle"), the edges are parallel, the cross product is ~zero, and the parser rejects it with vec3_near_zero.
• Möller–Trumbore (the ray/triangle test, M7) is built from cross and dot products chained together.

M4 · foundationsAngles: cos and tan, the only two we need

This project uses exactly two ideas from trigonometry, both defined on a right triangle (a triangle with one 90° corner). Name the sides relative to the angle θ you're looking at: the hypotenuse (the long slanted side), the adjacent side (touching θ) and the opposite side (across from θ). Then:

Where cos appears: brightness

We never call cos() in the code — the dot product of unit vectors (M2) is the cosine. Lambert's law (M8) says brightness ∝ cos of the angle between the surface normal and the light direction, and dot(N, L) delivers exactly that.

Where tan appears: the field of view

The camera (M9) imagines a screen floating exactly 1 unit in front of the eye. The FOV (field of view) is the angle of the wedge you can see. Split that wedge in half and you get a right triangle: adjacent = 1 (distance to the screen), opposite = half the screen's width. So:

M5 · foundationsRays & the number t

A ray is just "a starting point plus a direction": think of a laser pointer. In code it's two vectors — origin (a position) and dir (a unit direction). Every point the laser beam passes through can be written with a single number t, "how far along the beam":

Three consequences run the whole ray tracer:

• Negative t is behind the laser pointer. If the math says a surface is at t = −4, the object is behind the camera — not visible, rejected.
• Smaller positive t = closer. When a ray crosses several objects, the one with the smallest t hides the others. That's the entire job of intersect_scene: try everything, keep the minimum t.
• t is a distance, so it can be compared with other distances — e.g. "is the blocking object nearer than the light?" in the shadow test (M8).

M6 · foundationsFinding the hit point — geometry becomes algebra

Here is the core trick of all ray tracing, in three steps. It never varies:

1. Write the shape as a membership test — an equation that is true exactly for points on the surface.
2. Replace the point in that equation with the ray formula origin + t·dir.
3. What remains is an ordinary equation with one unknown, t. Solve for t. Each solution is a spot where the ray touches the surface.

Worked example: the sphere, with real numbers

Membership test: a point P is on a sphere (center C, radius r) exactly when its distance to the center is r. Distances involve square roots, which are ugly — so square both sides (the classic trick, used everywhere in this code):

Substitute the ray P = O + t·D, write oc = O − C (arrow from center to camera), expand, and group by powers of t:

Stare at it: D·D, oc·D, oc·oc are all known numbers (dot products of known vectors). So this is the school equation a·t² + b·t + c = 0 — a quadratic — with a = D·D, b = 2(oc·D), c = oc·oc − r². Exactly the three lines at sphere.c:41-43. And the school recipe for solving it:

Why a quadratic and not something simpler? Because a straight line can cross a sphere at most twice — in one side, out the other. Two possible crossings ⇒ an equation with up to two solutions ⇒ degree two. The discriminant just counts them:

The two roots have names in this codebase: quad_root1 (the −√ one, the entry, always the smaller t) and quad_root2 (the +√ one, the exit). quad_nearest (quad.c:46) tries the entry first; if it's behind the camera or inside the EPSILON dead zone, it falls back to the exit — which is exactly what you want when the camera sits inside the sphere: the entry is behind your head, the exit is the wall you're looking at.

The plane — same recipe, easier equation

Membership test: a plane is "all points level with p0, as judged by the normal n". A point P is on it when the arrow from p0 to P is perpendicular to n — and perpendicular means dot product zero (M2):

Substitute P = O + t·D and solve — t appears only to the first power (a line crosses a flat plane at most once, so no quadratic needed):

M7 · foundationsThe harder shapes, gently

Cylinder: split every arrow into "along" and "across"

What makes a point P belong to an (infinite) cylinder around an axis? Not its distance to the center — its distance to the axis line must equal the radius. To measure that, take the arrow v = P − C and split it into two pieces with the projection idea from M2:

The code does this split before solving (cylinder_utils.c:23-26): it removes the along-axis part from both the ray direction and the origin offset. What remains is a circle problem in the flat plane perpendicular to the axis — and circles give the same quadratic as the sphere. Then the finite height is a separate, trivial check: the hit's along-axis shadow (P−C)·A must sit between −h/2 and +h/2. The two flat caps are just the plane recipe (M6) plus "is the hit within r of the cap's center". Body, top cap, bottom cap are tested independently; the smallest t wins.

Cone: a cylinder whose radius grows

Same split, one change: the allowed "across" distance isn't a constant r anymore — it grows as you move away from the apex. At distance d along the axis the cone is exactly k·d wide, where k = radius/height (the slope of the slanted wall, a tan — M4!). So the membership test is |across|² = k²·d², and expanding it gives a quadratic whose coefficients carry the extra −k²(...) terms (cone_utils_bonus.c:33-35).

Triangle: weights instead of distances

A triangle needs a different idea. Any point in the plane of a triangle can be described as a weighted mix of its three corners — like mixing three paints. Call the weights w₀, w₁, w₂ with w₀ + w₁ + w₂ = 1. The point is inside the triangle exactly when no weight is negative — you're not "over-pulling" past any edge. These weights are called barycentric coordinates.

The code (triangle_bonus.c) solves for two of the weights, calls them u and v (the third is 1 − u − v), together with t, using Cramer's rule — a mechanical recipe for small equation systems built from the cross/dot products of M2–M3. It bails out early the moment a weight leaves [0, 1]: no point computing more if you're already outside. The algorithm has a name worth saying in the defense: Möller–Trumbore. Note there's no quadratic here — a line crosses a flat triangle at most once.

M8 · foundationsLight from zero

Real light leaves lamps, bounces around, and some of it ends in your eye. Simulating that forward is hopeless — almost all photons never reach you. So ray tracing runs the movie backwards: from the eye, through each pixel, out into the world — "what would a photon arriving along this line have last touched, and how much light was it carrying?" That's why our rays start at the camera.

When a ray lands on a surface, the code adds up three ingredients (shade.c / shade_bonus.c). Each answers one visual question:

1 · Diffuse — why surfaces facing the light are brighter

Hold a sheet of paper facing the sun: it catches a lot of light. Tilt it: the same beam now smears across a larger area, so each square centimeter gets less. Tilt it 90°: the beam slides along it, delivering nothing. The received energy per area follows the cosine of the tilt angle — that's Lambert's law, and it's the entire formula:

In code (diffuse.c): N is the surface normal (unit arrow sticking out of the surface — every intersector computes it), L = normalize(light_pos − hit_point) points at the light, and brightness is max(0, dot(N, L)) times the light's strength. The max(0, ·) handles surfaces facing away — negative cosine just means "the light is behind me", i.e. zero, not negative light.

2 · Shadows — blocked line of sight

A point is in shadow when something stands between it and the lamp. The test is charmingly literal (shadow.c): fire a second, invisible ray from the hit point toward the light — a "feeler". If it hits anything closer than the light itself, the light's contribution is skipped. Two refinements you can now fully explain: the feeler starts a hair off the surface (SHADOW_BIAS) so it doesn't collide with its own starting surface (M5's dead-zone problem), and "closer than the light" is a plain comparison of t against the light's distance — meaningful only because directions are normalized (M1).

3 · Ambient — the cheat that keeps shadows from being black holes

In the real world, light bounces off walls and floors and fills shadows with soft indirect light. Simulating bounces is expensive, so the subject prescribes a flat fake: add a small constant illumination to everything, unconditionally. That's the A line of the scene: a ratio (how strong) and a color. One multiplication, done (ambient.c).

Color: why multiply?

A color here is three numbers in [0, 1] — how much red, green, blue. Think of an object's color as a filter: a red ball is red because it reflects most red light and swallows most green and blue. "Reflects a fraction" is multiplication, channel by channel:

Since several lights and terms get added on top of each other, a channel can exceed 1.0; before painting the pixel it's clamped back to [0,1], because the screen can't display "more than fully bright" (color.c, and 1.2×255 = 306 would corrupt the packed pixel bytes).

Bonus: specular — the shiny glint

Glossy surfaces also reflect the lamp itself as a bright spot. Where? Light bounces off a mirror at the same angle it came in — the bounce direction R is computed by vec3_reflect. The closer your viewing direction is to R, the more of that mirror bounce you catch: measured by — once again — a dot product, dot(R, V). Raising it to a power (pow(…, shininess)) sharpens the spot: a high exponent kills every value except those very close to 1, shrinking the highlight to a tight glint. The spot is white, not the object's color, because you're seeing the lamp, not the paint (specular_bonus.c).

M9 · foundationsFrom pixels to rays

Last piece: the screen is an 800 × 600 grid of pixels; rays live in the 3D world. How does pixel (412, 187) become a ray? Picture a window floating exactly 1 unit in front of the eye, facing the way the camera looks. Each pixel owns one small rectangle of that window. The ray for a pixel is simply: start at the eye, aim through your rectangle's center.

Building that window from the scene file's three camera values (build_camera_basis, camera.c):

1. How wide is the window? The FOV triangle from M4: half-width = tan(fov/2). Height follows from the screen shape: half-height = half-width × 600/800, so pixels stay square and spheres stay round.
2. Which way is "right" and "up" on the window? The cross-product construction from M3: right = cross(dir, world_up), up = cross(right, dir) — two arrows perpendicular to the view direction.
3. Where is a pixel in 3D? Convert pixel (px, py) to fractions u = px/800, v = 1 − py/600 (both in [0,1]), then walk from the window's bottom-left corner: point = lower_left + u·horizontal + v·vertical. The "1 −" flips vertically because image memory counts rows downward from the top while the world's up points… up.
4. The ray = origin at the eye, direction = normalize(point − eye).

R1 · ray deep-diveThe rendering story — Person B's script

This project was built by two people, and a defense often splits the same way: Person A owns parsing and the intersection math, Person B owns the camera, the render loop, shading and MLX. This part is Person B's script — the rendering half learned as one continuous story instead of memorizing camera.c, render.c and shade.c separately. (Person A's story is §03 + §05.)

What do I receive? The parser has already done its work: at rendering time the scene exists as C structures — camera, ambient, lights, objects. When the evaluator says "explain your rendering", don't start at "sp 0,0,5…". Say: “At rendering time I already have the scene represented as C structures. My job starts at the camera” — and open camera.c.

The 90-second mental story

1. The camera gives me three things: position, direction, FOV.
2. From them I build an invisible viewport 1 unit ahead — its width comes from tan(fov/2), its "right" and "up" from cross products (R2).
3. The render loop visits every pixel; each pixel becomes fractions (u, v) of that viewport, four sub-pixel samples each (R3).
4. get_ray turns a (u, v) into a ray: aim from the eye through that spot (R4).
5. ray_color asks the intersection system for the nearest hit; a miss paints the background (R5).
6. A hit is shaded: ambient + (if the lamp is visible) diffuse — shadow tested with a second ray (§07).
7. The color is clamped, packed and written into the image buffer; the finished frame is presented in one blit (§P1).

R2 · ray deep-diveBuilding the viewport, brick by brick

M9 gave the picture; here we build the actual rectangle number by number, and end on the exact line of code. Running example: camera at pos = (0,0,0), looking along dir = (0,0,−1), FOV 90°.

1. Where is the rectangle's center? One unit in front of the eye: pos + dir = (0,0,−1). Note that adding a direction to a position means "step that way once" (M1).
2. How wide? half_w = tan(90°/2) = tan(45°) = 1 — the M4 triangle with adjacent = 1. Full width 2.
3. How tall? The screen is 800×600, so half_h = half_w · 600/800 = 0.75. (Ignore FOV for height — it follows from the aspect ratio, or spheres would stretch.)
4. Which way is "right"? right = norm(cross(dir, world_up)). For dir = (0,0,−1): right = (1,0,0), and then up = cross(right, dir) = (0,1,0).
5. Walk to the corner. From the center, go half a width left and half a height down:
   (0,0,−1) − (1,0,0)·1 − (0,1,0)·0.75 = (−1, −0.75, −1). That point is lower_left — the viewport's bottom-left corner, in world coordinates.

Now read the real line (camera.c:40-43) term by term — it is exactly the walk above:

b->lower_left = pos          ← start at the eye
              + dir          ← step to the rectangle's center, 1 unit ahead
              − right·half_w ← walk to the LEFT edge
              − up·half_h    ← walk DOWN to the bottom

Two more values complete the rectangle (camera.c:38-39): horizontal = right · 2·half_w = (2,0,0) and vertical = up · 2·half_h = (0,1.5,0) — the full-width and full-height spanning arrows.

Why "right" isn't just (1,0,0)

It is only (1,0,0) for this particular camera. Tilt the camera and the whole rectangle must tilt with it — that's why right is computed, not hardcoded. A pleasing detail: with world_up = (0,1,0), the formula gives cross(dir, world_up) = (−dir.z, 0, dir.x) — the y component is always 0. "Right" is always level, which is why the horizon never rolls. And that vector's length is √(dir.x² + dir.z²), which shrinks to ~0 when the camera looks straight up or down — precisely the degenerate case the 0.99 guard in get_camera_axes exists to catch (§06).

R3 · ray deep-diveget_sample_color, every line

render.c:38-49

static t_color	get_sample_color(t_app *app, t_camera_basis *basis, double px,
		double py)
{
	double	u;
	double	v;
	t_ray	ray;

	u = px / (double)WIDTH;
	v = 1.0 - py / (double)HEIGHT;
	ray = get_ray(basis, u, v);
	return (ray_color(ray, &app->scene, MAX_DEPTH));
}

u = px / WIDTH — turns "pixel column 412 of 800" into "51.5% of the way across". Why not hand px to get_ray directly? Because the camera should not know the image is 800 pixels wide. Fractions decouple the two worlds: change WIDTH to 1600 and get_ray doesn't change at all.

v = 1.0 − py / HEIGHT — same fraction, plus the famous flip. Image memory counts rows downward from the top; the viewport's vertical arrow points up from lower_left. Watch it with real numbers:

Without the 1 −, every scene would render upside-down.

Where do px, py come from? render_pixel (render.c:51-74) passes them fractional: x + (i + 0.5) / ss — sub-pixel offsets for anti-aliasing. ss = 2 − app->fast: in normal mode ss = 2 → a 2×2 grid of 4 samples averaged; in preview mode (§P1) ss = 1 → a single centered sample. Same function, two speeds.

The last two lines are the handoff: fractions → ray (R4), ray → color (R5). In plain English the whole function reads: “turn this sample position into percentages of the viewport, aim a ray through that spot, and ask what color it sees.”

R4 · ray deep-diveget_ray, every line

camera.c:53-66

t_ray	get_ray(t_camera_basis *b, double u, double v)
{
	t_ray	ray;
	t_vec3	target;

	target = vec3_add(b->lower_left,
			vec3_add(vec3_scale(b->horizontal, u),
				vec3_scale(b->vertical, v)));
	ray.origin = b->origin;
	ray.dir = vec3_norm(vec3_sub(target, b->origin));
	return (ray);
}

target = lower_left + u·horizontal + v·vertical — the R2 corner-plus-arrows walk: start at the bottom-left corner, go u of the way across, v of the way up. With the R2 numbers and the exact middle (u = v = 0.5):

target = (−1,−0.75,−1) + 0.5·(2,0,0) + 0.5·(0,1.5,0)
       = (−1,−0.75,−1) + (1,0,0) + (0,0.75,0)
       = (0, 0, −1)          ← the viewport's center: straight ahead ✓

target is a position on the window — not a ray yet.

ray.origin = b->origin — every primary ray starts at the eye.

ray.dir = norm(target − origin) — subtraction gives "the arrow from the eye to the window spot" (M1), and normalization makes its length exactly 1 so that every t downstream is a real world distance (M5). For a corner sample (u = v = 1): target = (1, 0.75, −1), raw arrow (1, 0.75, −1) with length √2.5625 ≈ 1.60, normalized ≈ (0.62, 0.47, −0.62).

R5 · ray deep-diveray_color → intersect_scene → shade

ray_color (render.c:27-36) asks one question — what did this ray hit? If intersect_scene says nothing: return the sky-gradient background. If it says something: hand the hit to shade. (The depth guard returns black at 0 but nothing ever decrements it — the honest answer is "a hook for reflection that isn't implemented", §12.)

t_hit is the baton passed from geometry to lighting. It carries everything shading will need: t (how far), point (where), normal (facing which way, always turned against the incoming ray), mat (color/properties), front_face (outside or inside).

intersect_scene (intersect.c:15-37) — the two local variables confuse people, so here they are in plain English:

The loop walks the object list asking each one: “can you beat the current best?” — hit_object(ray, obj, &tmp) && tmp.t < closest. How does it know whether it's testing a sphere or a plane? It doesn't need cleverness: hit_object is an if/else on obj->type, the tag of the tagged union (§00). Each shape function answers the same single question: “given this ray, what is your t?” Visibility falls out for free: no visibility algorithm exists anywhere — it emerges from “smallest positive t wins.”

shade (shade.c:17-34) then assembles the color: start with ambient (the always-on fill, §M8); for each light, ask in_shadow (a second ray, §07) and if the lamp is visible add diffuse (bonus: + specular, tinted by the light's color); clamp to [0,1]. The result rides back up: shade → ray_color → get_sample_color → render_pixel (averaged over the 4 samples) → mlx_put_pixel — one integer in the image buffer.

render_pixel(x, y)
  └─ 4 × get_sample_color(px, py)      fractions u,v  + the 1−v flip
        └─ get_ray(u, v)               corner + u·across + v·up → aim from the eye
        └─ ray_color(ray)              nearest hit, or background
              └─ intersect_scene       "who beats closest?" over the object list
              └─ shade                 ambient + Σ lit lights, clamp
  └─ average → mlx_put_pixel           one integer in memory: the pixel

R6 · ray deep-diveThe light system, end to end

M8 built the physics from zero and §07/§08 walk the formulas; this section tells the story of light as a system — from two lines of text in the scene file to the number in a pixel. The first distinction everything else hangs on: the program has two different kinds of light:

1. Ambient light     → always contributes a little light everywhere,
                       cannot be blocked, has no position
2. Point light(s)    → come FROM a position in 3D space,
                       can be blocked, strength depends on surface direction

The mandatory build has exactly one point light; the bonus allows several.

It starts in the .rt file

A  0.2        255,255,255      → ambient: strength 0.2, white
L  -10,10,-10 0.7 255,255,255  → point light: position, brightness, color

parse_ambient stores ratio + color into scene->ambient; parse_light builds the light node — position, brightness, color, and the attenuation trio, which mandatory sets to the neutral kc=1, kl=0, kq=0 (more on that below). So the lighting state exists before any rendering starts:

scene
 ├── ambient (ratio, color)
 ├── camera
 ├── lights → [light] → …      one node in mandatory, a list in bonus
 └── objects

The mandatory recipe

final = ambient_light()             ← the unconditional baseline
for the light:
    if NOT in_shadow():
        final += diffuse_light()    ← direct light, only if it arrives
color_clamp(final)

Ambient first: object color × (ambient color × ratio). A red sphere under 0.2 white ambient starts as dark red — never pitch black. This baseline is exactly what a shadowed point keeps.

Q1 — the shadow ray, the renderer's second kind of ray

PRIMARY RAY   camera → object      "what do I see?"
SHADOW RAY    object → light       "can this point see the lamp?"

make_shadow_ray starts at the hit point — nudged off the surface by SHADOW_BIAS so floating-point dust can't make the surface shadow itself (“shadow acne”) — and points at the light. Then a lovely architecture point: there is no special shadow geometry — the shadow ray is tested with the very same per-shape functions (hit_object) as camera rays. But since PR #18 the loop differs in one smart way: it returns at the first blocker it finds instead of searching for the nearest one, bounded by the light's distance:

X ───── object ───── ☀      ANY hit BEFORE the light   → shadow, stop looking
X ───── ☀ ───── object      hit BEHIND the light        → irrelevant, lit

Why that's legitimate: the camera ray needs the nearest hit (that's what you see); the shadow ray only asks “is there ANY obstacle?” — a yes/no question that the first blocker already answers. Same boolean, image bit-identical (checksum-verified), and it gets faster the more objects and lights a scene has. The distance comparison against the light is meaningful only because ray directions are unit length, so t is a real distance (M5).

Q2 — diffuse: the normal earns its keep

Light reaches the surface; how strong is the illumination? This is where the normal — carried in every t_hit since intersection — becomes crucial: dot(N, L) with L pointing at the light gives the alignment (M2): 1 facing the lamp head-on, 0 sideways, negative = lamp behind the surface → clamped to zero. Without normals, a sphere would render as a flat uniformly-colored disk; the dot product is what makes it look round.

Then two multipliers scale that alignment — worked numbers:

alignment dot(N,L) = 0.8      the surface mostly faces the lamp
light brightness   = 0.5      straight from the L line's ratio
attenuation        = 1.0      mandatory: kc=1, kl=0, kq=0 → always exactly 1
                              (the 1/(kc + kl·d + kq·d²) machinery exists,
                               but mandatory light does NOT fade with distance)
intensity = 0.8 × 0.5 × 1.0 = 0.4
red object (1,0,0) × 0.4    = (0.4, 0, 0)

Adding it up — where shadows come from

lit point:       ambient (0.1,0,0) + diffuse (0.4,0,0) = (0.5,0,0)
shadowed point:  ambient (0.1,0,0) + nothing           = (0.1,0,0)  ← the visible shadow

A shadow is not painted — it is simply the absence of the diffuse term. Finally color_clamp caps each channel at 1 (added terms can overshoot), and much later mlx_put_pixel converts [0,1] back to 0–255 bytes.

The whole mandatory pipeline in one picture

.rt file → parse_ambient() + parse_light() → scene holds the lighting state
─────────────────────────────────────────────────────────────────
camera ray → intersect_scene() → t_hit (point + normal + material)
   ↓
shade()
   ├─ ambient_light()                        the baseline
   └─ for the light:
        in_shadow() ── shadow ray ── intersect_scene()
        if visible: diffuse_light()
                       ├─ dot(normal, to_light)
                       ├─ × brightness
                       └─ × attenuation (≡ 1 in mandatory)
   ↓
add contributions → color_clamp() → pixel

What the bonus changes

• Multiple lights — the bonus parser appends to a list instead of rejecting a second L; the bonus shade() loops over all of them, running the two questions per light.
• Light color actually matters — mandatory parses the L color but never uses it; the bonus multiplies each light's (diffuse + specular) by that light's own RGB. Red light on a white object → red-looking illumination.
• Specular — a third question joins the two: “does the light's mirror-bounce direction point toward the camera?” (specular_light, classic Phong: ks = strength, shininess = how tight the glint is).

bonus:  final = ambient + Σ over visible lights: light_color × (diffuse + specular)
        then clamp

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 for a full-quality pass (movement uses a cheaper preview first — §P1).
• 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), at MOVE_SPEED = 8 units per second — movement is now time-based while a key is held (dt from gettimeofday), so the glide speed is independent of render cost. Movement never renders directly — it sets needs_render and the loop hook repaints in slices, preview-first (§P1).
• Mouse scroll (buttons 4/5): FOV ∓5°, clamped to [1,179] — same flag mechanism.
• 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. (For the light system told as one story — from the .rt lines to the pixel — see §R6.)

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 :29-46 walks the object list itself with the same per-shape testers — but any-hit, not nearest-hit (PR #18):

while (obj)
{
    tmp.t = light_dist;
    if (hit_object(shadow_ray, obj, &tmp) && tmp.t < light_dist)
        return (1);
    obj = obj->next;
}
return (0);

Only a hit strictly between point and light blocks — and the first such hit ends the search, because “is there any obstacle?” is a yes/no question. Output is bit-identical to the old nearest-hit version (checksum-verified); 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 once forgot to set these — an uninitialized read caught by valgrind, long since fixed (the story is in §12).

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:15-26 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  */
apply_bump(hit);                                /* may tilt the normal — §B1 */
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);

Five differences vs mandatory: checkerboard first, bump-tilted normals (§B1), 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.

B1 · subsystemsThe bonus, feature by feature

The subject lists five bonus points. All five are implemented, all through the linking trick (§00) — zero #ifdefs, the bonus binary just links different files for the same symbols:

Features 1–4 are covered in depth in §05 and §08. This section documents the fifth in full, because it exists nowhere else in the handbook.

Bump mapping — relief without geometry

The idea. A surface looks bumpy because light catches its slopes — bright on the side facing the lamp, dark on the far side. But lighting never sees geometry directly: it only sees the normal (M8 — brightness is dot(N, L)). So if you tilt the normal per point as if craters were there, the shading produces the relief — while the actual sphere stays mathematically perfect. Give-away an evaluator may spot, and the honest answer: the silhouette stays a perfect circle, because intersections are untouched — only lighting is fooled.

Scene syntax. Append a .pgm file path as the last token of a sphere line — with or without the material tail (scenes/bonus/bump_sphere.rt):

sp -2.6,0,0 4.4 205,175,130 0.35 24 0 0 1 0 1 scenes/bonus/textures/craters.pgm
sp  2.6,0,0 4.4 205,175,130 0.35 24              ← same sphere, no bump: the control

The loader (parse_texture_bonus.c) is written from scratch with only open/read/malloc — no forbidden functions, no MinilibX involvement. A PGM "P5" file is the simplest image format that exists: a 3-line text header (P5, width + height, maxval) followed by raw bytes, one byte per pixel, 0 = black = low, 255 = white = high. The loader checks the magic, bounds the dimensions to 1–4096, requires maxval 255, and reads the payload in a loop until complete — a missing file, wrong format, or truncated payload each exits cleanly with the fd closed (:62, :70, :94). The map is owned by the material and freed in free_scene (free_scene.c:26).

The parser trick (material_token_count, parse_texture_bonus.c:102-116): if the line's last token ends in .pgm, load it and return count − 1 — the rest of the material parser then sees the line as if the texture token never existed. And in the mandatory binary nothing loads PGMs at all: its strict check_count sees one token too many and refuses the scene, as the subject requires.

The shading (apply_bump, bump_bonus.c:48-69 — called from shade_bonus.c:23, right after the checkerboard) is four small steps per hit:

1. Where am I on the map? Convert the hit's normal to sphere UV — longitude from atan2(n.z, n.x), latitude from asin(n.y) (the classic globe unwrap; the M4 functions in reverse) → a texel (x, y).
2. Which way does the ground slope here? Central differences: height at (x+1) minus height at (x−1) gives the east–west slope; same vertically. This is a gradient — exactly the M7 cone-normal idea, but sampled from data instead of derived from algebra. The x lookup wraps (longitude is a circle) while y clamps (the poles end, bump_at :15-23).
3. Tilt in which directions? Slopes need axes to tilt along: a tangent frame — tangent = cross(world_up, N) (perpendicular to the normal, M3; fallback (1,0,0) at the poles where the cross degenerates) and bitangent = cross(N, tangent).
4. Tilt. N' = normalize(N + tangent·grad_u·2.2 + bitangent·grad_v·2.2) — the 2.2 is the bump strength. Every later consumer (diffuse, specular, shadow bias) just uses the tilted normal; nothing else changes.

Demo: ./miniRT_bonus scenes/bonus/bump_sphere.rt — a cratered sphere (craters.pgm) next to an identical smooth one under the same light; ripples.pgm is the second sample texture. Bad-input demos: a nonexistent path, a non-P5 file, a truncated file — each prints a specific Error message, and valgrind stays clean (no leaks, no open fds).

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 (mlx_init.c:37) — the camera starts LOCKED; press SPACE before demoing movement!

mlx_put_pixel

mlx_utils.c:15-26

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

• Writes go to back_addr — the back buffer of the double-buffering scheme (§P1); the front image is what the window shows.
• ×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.

line_len — the stride, drawn out

When you call mlx_new_image, there's no grid in memory — just one long line of bytes. To find pixel (x, y) you must compute where row y starts, and for that you need to know how many bytes one row occupies. That number is line_len, and the concept is called the stride.

Why isn't a row just width × 4 bytes? With 32 bits per pixel, 800 pixels of pixel data do take 800 × 4 = 3200 bytes. But the library is allowed to make each row slightly longer than its data, leaving unused padding bytes at the end, so that every row begins at a nicely aligned memory address (divisible by 8, 16, 64…). Aligned rows make copying to the X server and the hardware faster. So the real layout can be:

row 0:  [3200 bytes of pixels][64 bytes padding]   ← row is 3264 bytes long
row 1:  [3200 bytes of pixels][64 bytes padding]
row 2:  …

line_len is the honest answer to “how far apart are two consecutive rows, in bytes?” — 3264 in this sketch, not 3200.

What happens if you use width × 4 anyway? Row 0 lands correctly. Row 1 gets written 64 bytes too early — into row 0's padding and a bit before its true start. Row 2 is off by 128 bytes. The error grows with every row, so the picture comes out sheared into a diagonal smear — a classic, instantly recognizable bug.

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 MOVE_SPEED × dt (held keys, time-based) and set needs_render — the actual repaint happens in the loop hook, sliced and preview-first (§P1).
• 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.

P1 · performanceThe optimization story — how the camera became fluid

The starting problem

Before the fix, every keypress did this: key_handler → move_camera → render() — a full 2–5 second ray trace inside the event handler. While rendering, no events were processed. So holding a key for one second queued ~30 more keypresses, each of which would trigger another full render. The window froze for minutes, and even ESC sat unprocessed in the queue.

BEFORE                                AFTER
key event                             key event
  └─ move camera                        └─ move camera
  └─ render EVERYTHING (seconds,        └─ set needs_render = 1   (microseconds)
     30 more keys pile up,
     ESC waits minutes)               event queue empty?
                                        └─ loop_hook: render 32 rows, return
                                        └─ (events checked)
                                        └─ loop_hook: next 32 rows … until done
                                        └─ swap the finished frame onto screen

The five mechanisms, in the order they matter

1 · Never render inside an event handler. Handlers now do only two things: update the camera and set a flag (needs_render = 1, press_move_key, keys.c). A mlx_loop_hook — a function MiniLibX calls whenever the event queue is empty — checks the flag and renders (loop_hook, render_loop.c:52). The consequence is subtle but huge: a burst of 30 key repeats just sets the same flag 30 times, and exactly one render happens once the burst ends. Input can never pile up work anymore. This is the classic GUI pattern: events invalidate, a separate loop paints.

2 · Slice the render so it's interruptible. The loop hook doesn't render a whole frame — it renders 32 rows (SLICE_ROWS, miniRT.h:27), remembers where it stopped (app->row), and returns (render_span, render.c:77). MiniLibX then checks for events before calling it again. So ESC now waits at most one slice (~50 ms) instead of one frame (~seconds) — measured: ESC responds in 0.12 s where the old code took 11.7 s. And if a keypress arrives mid-frame, the flag resets row = 0 and the pass simply restarts with the new camera — no stale work completes.

3 · Two-speed rendering. While you're moving, perfection is wasted — the frame will be replaced in 100 ms anyway. So movement frames trace one ray per 2×2 pixel block into a half-resolution buffer (app->half): ¼ the pixels × no anti-aliasing = ~1/16 the work. When events stop arriving, a full-quality pass re-renders automatically. The full path's math is untouched — which is why the still image could be proven bit-identical to the old renderer's output.

4 · Edge-aware upsampling — the reason there's "no transition". A naive half-res preview looks like mosaic squares. Instead, for every output pixel the code looks at the 4 half-res samples around it and asks: do they agree? In flat regions (the sky gradient, the inside of a surface) they do — and bilinear interpolation between them is visually indistinguishable from actually tracing the pixel. Where they disagree beyond EDGE_SPREAD (miniRT.h:29) — a silhouette, a checker boundary — the code fires a real full ray for that exact pixel (upsample_span, preview.c:83). So edges are pixel-perfect and only flat areas are interpolated. Measured: the preview differs from the final image by ~1.3% of pixels, at roughly a third of a ray per pixel. That's the trick — the first image after you stop moving is already almost the final one, so the "refine" pass is nearly invisible.

5 · Double buffering. All rendering goes into a back image; only when a pass completes does the code mlx_put_image_to_window and swap front/back (present_frame, mlx_utils.c:28). The window therefore never shows a half-drawn frame — you never see the slices sweep — and when the window is minimized and restored, the expose handler re-puts the last complete frame. That's exactly what the eval sheet's "window content must remain consistent" test checks.

The preview, drawn out — mechanisms 3 + 4 in pictures

Preview mode is a cheap, temporary render so the program can respond instead of computing the full 800×600 image at maximum quality on every movement frame. It deliberately calculates fewer real rays, then reconstructs the missing pixels.

Step 1 — render a coarser grid. In preview mode render_span strides with step = 1 + app->fast, so it computes every second pixel of every second row — X means "actually shoot a ray here", · means "not yet":

FULL                      PREVIEW
X X X X X X               X · X · X ·
X X X X X X               · · · · · ·
X X X X X X               X · X · X ·
X X X X X X               · · · · · ·

Each computed sample also skips anti-aliasing (1 ray instead of 4) and lands in a half-resolution buffer — ¼ the pixels × ¼ the rays ≈ 1/16 the work.

Step 2 — fill the holes by looking at the neighbors. For every missing pixel, upsample_span asks the four nearest computed samples:

A ─────── B        A,B,C,D all similar (blue sky, a flat wall)?
│         │          → this is a SMOOTH area:
│    ?    │            interpolate between them (bilinear)
│         │            — visually indistinguishable from a real ray
C ─────── D

Step 3 — but what if there's an edge?

blue sky      blue sky      The four samples disagree strongly →
                            something important happens here: a
        ?                   silhouette, a checker boundary.
                            Don't guess — FIRE A REAL RAY for
red sphere    red sphere    this exact pixel.

The decision is is_edge: if any color channel's spread (max − min of the four samples) exceeds EDGE_SPREAD, the pixel gets the real-ray treatment. That's why it's called edge-aware upsampling:

surrounding colors similar   → interpolate (cheap, invisible)
surrounding colors different → probably an edge → real ray (exact)

Why this works. Large smooth areas — sky, floors, the inside of a sphere — don't need every pixel computed independently: several samples already agree on the answer. Precision only matters where the image changes. So the preview spends its computation exactly there, and nowhere else. Measured result: the reconstructed frame differs from a fully traced one by ~1.3% of pixels, at roughly a third of a ray per pixel.

Step 4 — present. When the preview pass finishes, present_frame runs the upsampling and only then blits — the window receives a complete reconstructed image, never a half-filled grid.

Why this is the only shape a fix can take

Ray tracing cost is roughly pixels × rays-per-pixel × objects × (1 + lights) — physics you can't cheat for the final image. That leaves exactly three legal moves:

• Do less work when nobody can see the difference → motion gets the preview (mechanisms 3 + 4);
• Never let the work block input → the flag and the slices (mechanisms 1 + 2);
• Never show unfinished work → the double buffer (mechanism 5).

Every line of the optimization is one of those three. Nothing else exists.

Where it lives, for the defense

A later web version scaled the same ideas further — slices became worker bands, the loop hook became a scheduler that measures each tier's cost, plus a bounding-sphere accelerator — but none of that touched the 42 repo. What's submitted is exactly the five mechanisms above: all within mlx's public API, all norm-clean, and all provably output-identical on still frames.

S1 · operationsScene-file reference

The complete .rt format — every field, every default, every gotcha — verified against the parser on the current (PR-17) branch.

General rules

• One element per line; identifier first, then fields in strict order, separated by whitespace. Blank lines and #-comment lines are allowed anywhere; elements in any order.
• Capital-letter identifiers (A C L) are unique — declared once. The bonus lifts this for L only (multiple lights).
• Colors are R,G,B as integers 0–255 (12.5 is rejected); ratios in 0.0–1.0; orientation vectors need each component in [−1, 1] — the parser re-normalizes the vector, but components outside the range are rejected.
• ⚠️ Sphere and cylinder sizes are DIAMETERS, not radii — the parser divides by 2. The cone's size is a RADIUS (its own documented format — parse_objects_bonus.c:20 says <radius> and stores it unhalved).
• Any malformed field → Error + exit(1).

Mandatory elements

A   0.2   255,255,255
│    │         └─ ambient color
│    └─ ambient ratio [0..1]  (how much light objects get with no lamp)
└─ Ambient light — exactly one

C   -50,0,20   0,0,1   70
│       │        │      └─ horizontal FOV in degrees, strictly 0 < fov < 180
│       │        └─ viewing direction (normalized; parser re-normalizes)
│       └─ camera position x,y,z
└─ Camera — exactly one

L   -40,50,0   0.6   10,0,255
│       │       │        └─ light color (ignored in mandatory, used in bonus)
│       │       └─ brightness ratio [0..1]
│       └─ light position x,y,z
└─ Light — one in mandatory, several in bonus

sp   0,0,20   12.6   10,0,255
│       │       │        └─ color
│       │       └─ DIAMETER (radius will be 6.3)
│       └─ center x,y,z
└─ sphere

pl   0,0,-10   0,1,0   0,0,225
│        │       │         └─ color
│        │       └─ normal vector (this one = plane faces up: a floor)
│        └─ any point on the plane
└─ plane (infinite)

cy   50,0,20.6   0,0,1   14.2   21.42   10,0,255
│        │         │      │       │         └─ color
│        │         │      │       └─ height (extends ±height/2 from center)
│        │         │      └─ DIAMETER
│        │         └─ axis (0,1,0 = standing up; 0,0,1 = lying along z)
│        └─ CENTER of the cylinder (mid-height, not its base)
└─ cylinder, with caps

Bonus-only extensions

All of these are rejected by the mandatory binary (strict token counts, no co/tr in its dispatch table).

co   0,10,10   0,-1,0   6   14   255,100,40
│        │        │     │    │        └─ color
│        │        │     │    └─ height (body spans apex → apex + axis·h)
│        │        │     └─ RADIUS (not a diameter!)
│        │        └─ axis, points from the apex toward the base
│        └─ APEX position (the tip)
└─ cone

tr   5,-5,4   14,-5,4   9,-5,16   200,180,60
│       └────────┴─────────┴─ three vertices    └─ color
└─ triangle (two-sided; degenerate/collinear rejected at parse)

The optional material tail

After any object's color you may append, in this exact order — stop wherever you want, but earlier positions are required to reach later ones (parse_opts_bonus.c:21-44):

Decoded examples from this repo's own scenes:

pl 0,-3,0 0,1,0 200,200,200  0.4 64   0 0 1   1 2
                              │   │   └─┴─┴─ refl/transp/ior left neutral
                              │   └─ shininess 64      └─ checker ON, 2-unit cells
                              └─ ks 0.4

sp -2.6,0,0 4.4 205,175,130  0.35 24  0 0 1  0 1  scenes/bonus/textures/craters.pgm
   cratered bump-mapped sphere: mild specular, no checker, PGM height map last

Practical gotchas when writing test scenes

• Camera direction is a direction, not a target. To look at the origin from position p, use dir = −p (the parser normalizes): from 14,19,-23 → roughly -0.45,-0.6,0.75.
• Cylinder and cone position semantics differ: cy takes its center (body spans ±h/2), co takes its apex (body spans apex → apex + axis·h). A cone "sitting" on a floor at y = −5 with height 14 opening downward: apex at y = 9, axis 0,-1,0.
• A plane's normal sign doesn't matter visually (shading is two-sided, §05) — but point + normal must describe the plane you mean.
• Ambient and brightness combine. With ambient near 0 shadows go pitch black; near 1 everything washes out. A 0.2 + L 0.7–0.85 is the sweet spot for eval scenes.
• Any malformed field exits with Error — negative diameters, 299 in a color, FOV 190, letters in numbers, 1,2,, duplicate C… that's precisely what the evaluator will type (drill list: §13 Parsing).

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. Full field-by-field reference, defaults and gotchas: §S1.

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
sp -2.6,0,0 4.4 205,175,130 scenes/bonus/textures/craters.pgm
#  a .pgm as LAST token = bump map (works with or without the tail) — §B1

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; the consumed fields are ks, shininess, the checker pair, and the bump map. reflectivity/transparency/ior remain forward-looking storage.
4. Error paths now clean up — error_exit calls cleanup_all() (frees the scene, closes the fd) before exiting, so even mid-parse failures are valgrind-clean. Verify once and quote the numbers.
5. Performance: still a linear object list, no acceleration structure — a 10k-object scene renders slowly (hence the 1 MiB parse cap). But input no longer blocks on rendering: see §P1 for the flag + slices + preview architecture.
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.”

E1 · defenseThe eval sheet's geometry tests, decoded

“Translate this object” — the scene file IS the interface

miniRT has no UI command like “select sphere → translate 10 units.” The scene is defined by the .rt file — so to translate an object you change its coordinates in the file and run miniRT again; to rotate a cylinder or cone you change its orientation/axis vector and run again. That's not a missing feature — it's the design the eval sheet expects you to demonstrate.

sp 0,0,0  10 255,60,60      ← before: red sphere centered at the origin
sp 12,0,0 10 255,60,60      ← "translated": same sphere, new center

The sphere never gained a translate() function. You changed its center, and every piece of existing intersection code works with the new position automatically, because it reads obj->sphere.center — concretely, the very first line of the sphere test: oc = vec3_sub(ray.origin, obj->sphere.center). The whole chain:

edit object position           edit cylinder axis
        ↓                              ↓
parser stores new center       parser stores new axis
        ↓                              ↓
intersection uses new center   cylinder intersection uses new axis
        ↓                              ↓
render changes accordingly     cylinder appears rotated

Making eval scenes fast at the terminal — a heredoc writes a scene without opening an editor (nothing ray-tracing-specific about it):

cat > scenes/eval/tr1_before.rt <<'EOF'
A 0.2 255,255,255
C -30,12,0 1,-0.35,0 70
L -25,20,-15 0.75 255,255,255
sp 0,0,0 10 255,60,60
sp 0,0,0 10 60,60,255
EOF

That scene puts a red and a blue sphere at exactly the same place — their surfaces coincide, so you won't see “two spheres.” (Fun precision: with coinciding surfaces the intersection distances tie, and the strict tmp.t < closest comparison in intersect_scene keeps the earlier object in the list — the red one.) The “after” scene then moves one sphere, and the render must change accordingly.

“Camera along the Y axis” — the test that hunts one specific bug

The difficult case is a camera looking straight up or straight down, e.g. dir = (0,−1,0). The camera basis normally starts from right = cross(dir, world_up) with world_up = (0,1,0). But now look at the two directions: (0,−1,0) and (0,1,0) are the same line. Ask the cross product “which way is sideways, given vertical and vertical?” and there is no unique answer — left, right, toward you, away from you are all equally perpendicular. So it returns (0,0,0): “I cannot determine a sideways direction from parallel inputs.” Zero is not a direction → no right → no horizontal viewport → the camera math breaks. That's exactly what the evaluator is fishing for.

How the code survives it (get_camera_axes, camera.c):

if (fabs(dir.y) < 0.99)
    world_up = vec3(0, 1, 0);
else
    world_up = vec3(0, 0, 1);

Read it as: “is the camera NOT looking almost vertically? Then Y is a fine reference. Otherwise Y is useless — use Z instead.” For dir = (0,−1,0): fabs(dir.y) = 1 → reference becomes (0,0,1), perpendicular to the view, and the crosses work again:

forward = ( 0,−1, 0)      looking straight down
right   = (−1, 0, 0)      = cross(forward, (0,0,1))
up      = ( 0, 0, 1)      = cross(right, forward)

Geometrically that's the only sane answer: looking straight down Y, the image lies in the X–Z plane — world Y can't serve as “up on the screen” anymore because Y is now the direction you're looking through the screen. The screen must be spanned by the other two axes.

The evaluator's camera placements, and what each one actually challenges:

E2 · defenseThe control sheet, test by test

This is the official evaluation sheet turned into a runbook: for every test — what the evaluator does, the ready-made scene to open (all live in scenes/eval/, one file per test, named after its section), the pass criterion, and the sentence to say while it renders. Each sheet section is all-or-nothing: one failed test = zero points for that section.

Technical elements of the display

• Window opens with one parameter and stays open — ./miniRT scenes/eval/t1_sphere_origin.rt. The window lives until you close it; the render arrives via the loop hook (§P1).
• Hide / overlap / minimize / restore → content stays consistent — drag another window across it, minimize and restore. Why it works: frames are drawn into an image buffer and the Expose handler re-puts the last complete frame — no re-raytracing, no blank window (§09, §P1 mechanism 5).
• Resolution change → content consistent — the window is a fixed 800×600 image; changing the screen setup just triggers Expose events, answered from the stored frame.
• ESC and the red cross both exit properly — both funnel into the same close_handler: destroy image → window → display → free scene → exit(0). Offer valgrind as proof.

The basic shapes

• t1_sphere_origin.rt — sphere at {0,0,0}, camera facing it. Say: the sphere looks round because of per-pixel normals (§M8) — without them it would be a flat disk.
• t2_plane_z0.rt — plane with z value null (point 0,0,0, normal 0,0,1), camera facing it. Planes are two-sided (§05), so orientation of the normal can't hide it.
• t3_cylinder_y.rt — cylinder along the y axis, camera facing it. Wall + two caps tested independently; smallest t wins (§05).

Translations and rotations

The full decode of what's really being tested is §E1 — the scene file IS the interface; geometry must not be hardcoded to the origin or the axes.

• Translation — t4_translation_before.rt (red and blue spheres both at {0,0,0}) then t4_translation_after.rt (blue moved 8 units along the camera's direction — more than the diameter 6). Staging note baked into the scene: the camera sits slightly above and looks slightly down, so after the parallel translation both spheres remain visible instead of the near one occluding the far one (the trap E1 warns about).
• Rotation — t5_rotation_before.rt (axis 0,1,0) then t5_rotation_after.rt (axis 1,0,0 — exactly a 90°/π/2 rotation about z). Say: the cylinder has no rotate(); its orientation IS the axis vector, and every intersection reads it fresh.

Multi-objects

• t6_multi_intersect.rt — a sphere and a cylinder overlapping. The seam is clean because visibility is decided per pixel by "smallest positive t wins" (intersect_scene, §05) — no special intersection-of-objects code exists or is needed.
• t6_multi_repeat.rt — two spheres, two cylinders and a plane: objects are linked-list nodes, so the same type any number of times is free.

Camera position and direction

Same scene, four cameras, all pointed at {0,0,0}:

• t7_cam_x.rt — along X (dir −1,0,0): proves right/up are computed, not hardcoded.
• t7_cam_y.rt — along Y, straight down: the trap. dir is parallel to the default world-up, the cross product would be zero — the 0.99 guard swaps the reference to (0,0,1). Full story: §E1.
• t7_cam_z.rt — along Z: the ordinary case.
• t7_cam_random.rt — off every axis and diagonal (camera 14,19,−23, dir = −position pre-normalized into [−1,1]; the parser re-normalizes). Recipe for any such camera: dir = −pos, scaled until each component fits [−1,1].

Brightness 1/2 — sideways light, and the halo that must move

• t8_brightness_side.rt — sphere at the origin, spot far to the left: one side lit, one dark, smooth falloff between — that gradient is max(0, dot(N, L)) in action (§07, §R6).
• t8_brightness_translated.rt — the SAME sphere moved to (6,2,4), same light. The halo must sit on the moved sphere: it does, because lighting starts from the hit point, which comes from the intersection against the current center — nothing about lighting is precomputed at parse time. "Computed after translation, not before."

Brightness 2/2 — shadows

• t9_shadow.rt — vertical spot above a sphere over a plane, camera off to the side: sphere, plane and the cast shadow all visible. Say: the shadow is not painted — it is the absence of the diffuse term where the shadow ray finds the sphere first (§R6); the edges are clean because of SHADOW_BIAS + EPSILON (no acne).
• The complex scene — scenes/full_mandatory.rt (the illustration-V.6-style scene): several objects, all shadows consistent.

Bonus — gated, then one point each

All five implemented — details, syntax and defense phrasing per feature in §B1. Run the bonus tour with ./miniRT_bonus; the mandatory binary must (and does) reject every bonus-only scene element.

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 — if vectors/angles/light are new to you, read Level zero (Z1–Z5) first — especially the worked pixel in Z3 — then Foundations (M1–M9), doing each "check yourself" by hand. Everything else assumes them.
2. Hour 0-1 — read §00 + §02 twice. Draw the pipeline from memory once.
3. 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.
4. 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.
5. Hour 6-8 — camera + render. Recompute half_w for FOV = 70 on paper; explain the y-flip and the 4-ray averaging. Then walk R1–R5 — the render path line by line, exactly as you'd narrate it in the defense.
6. 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.
7. 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.
8. Hour 11-12 — decide about §12 bug #1 (fix it or prepare to own it).
9. 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.
• The eval scene pack is ready-made: scenes/eval/t1…t9, one file per control test (runbook: §E2) — plus heredoc skills for anything improvised (§E1).
• ./miniRT_bonus scenes/bonus/showcase.rt (+ the others) for the bonus tour.
• ./miniRT_bonus scenes/bonus/bump_sphere.rt — bump mapping, cratered vs smooth; have a broken .pgm ready to show the clean error handling.
• 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