We had to come up with a small patch release. We are documenting it because the mistake is easy to repeat and instructive if you are learning facing tests.

Version 0.0.7 on GitHub

What you will see

The tumbling animation looks almost the same at a glance — still a faceted cube, still six colors, still back faces culled. The difference is which facets count as “back.” Believe it or not, we were culling wrong faces up until now!

The bug is really subtle to spot on a simple scene like this. Only when we started to work on lighting did we spot oddities between what we expected to see and what was actually rendered.

How we spotted the bug

At first, everything went according to plan. Right after the filled-cube release we started on the next item in the project breakdown: Cube: basic shading — simple lighting on the faceted cube.

While placing a directional light in the scene, Sergey got confused and then suspicious. No matter how he aimed it, the cube would not read as lit from the front the way he expected. That felt wrong long before we had a precise diagnosis — the nudge to stop tuning light vectors and ask whether the pipeline was showing the faces he thought it was.

Eventually we stepped back from lighting and investigated our back-face culling. To make the picture clear, we added still-unit-cube — a small export binary that renders the default unit cube in the identity pose, square-on through the same orthographic camera as the main exporters, with no tumble and no extra transform. We also changed CUBE_FACE_PALETTE so the faces toward and away from the camera are impossible to confuse: deep blue on the −Z face (slot 0, the near face) and red on the +Z face (slot 1, the back face).

We ran the binary and opened the WebP. We expected a blue square in the middle of the frame; it was red — we were painting the back of the box!

Only then did we go hunting in the is_back helper we added in 0.0.5 and the tests that had been feeding the wrong view vector into the facing check. The sections below are that chase.

Our convention for face culling

Our orthographic camera looks into the scene along +Z, matching Camera::direction.

Each CubeFace stores an outward unit normal $\mathbf{n}$. For the cap closest to the eye (the −Z side of a unit cube centered at the origin), $\mathbf{n}$ points toward −Z — opposite to $\mathbf{v}$.

So for a facet that should be drawn when you look down +Z:

The outward normal and the into-scene view direction point against each other. That is front-facing in our setup.

What went wrong

CubeFace::is_back had the sign convention backwards from the day we introduced it in 0.0.5. It returned true when $\mathbf{n} \cdot \mathbf{v} < 0$ — but that is exactly the condition we just agreed means front-facing. In other words, is_back labeled front-facing facets as back-facing and treated genuinely back-facing facets as “not back.”

Cube::visible_edges skipped edges on faces where is_back was true. When we added fills in 0.0.6, Cube::visible_faces kept every face with !is_back, i.e. $\mathbf{n} \cdot \mathbf{v} \geq 0$. Either way, the pipeline culled the faces toward the camera and kept the faces on the far side of the box.

With $\mathbf{v} = +Z$ as in production:

The helper was not merely misnamed: its predicate was the inverse of back-facing for outward normals and an into-scene view vector. We were filling the back of the box and dropping the side facing the viewer — exactly what the blue/red still had shown.

Why the tests did not catch it sooner

The tests and production disagreed because they used opposite view vectors: several unit tests passed Vec3::NEG_Z as $\mathbf{v}$ and asserted counts like five visible faces from the front, while the camera supplies +Z through Camera::direction. With −Z as $\mathbf{v}$, the wrong inequality accidentally labels the near cap as visible and the far cap as back — so the tests passed while production painted the wrong side.

An older check only required that some visible quad matched the −Z corner layout, using the same inverted view vector. It never required that only the near cap survived culling with the real camera axis.

Sergey added looking_at_cube_from_front: default cube, look_along_z_axis = Vec3::Z, exactly one visible face, and that face’s corners are the −Z quad. That test failed immediately and pinned the bug.

The fix

We replaced the inverted rule with an explicit is_front_facing on 0.0.7:

Cube::visible_faces filters on that predicate only. Grazing facets ($\mathbf{n} \cdot \mathbf{v} = 0$) are excluded as well, which matters for fills: from a cardinal view you should see one cap, not five side faces edge-on.

Cube::visible_edges now uses the same front-facing rule as fills, so wireframe and face culling finally match Camera::direction. We first noticed the mistake in the filled exporters; the old is_back helper is gone.

Tests that describe “from the front” now take Vec3::Z, matching the camera. An integration test renders the default unit cube through draw_faces and compares the framebuffer to a hand-built golden image — one blue square for palette slot 0 (−Z cap), no WebP snapshot required.

What comes next

This release was a small detour: correct facing, then back to basic shading on the project breakdown — a light direction and a simple diffuse term on the faceted cube, still with quads and no depth buffer.

Version 0.0.6 on GitHub

What you will see

Same orthographic camera, same Euler tumble, 360 frames at 50 fps — but the cube is a faceted solid: different colors on the six hull sides. Back faces are still culled before rasterization; only front-facing quads reach the framebuffer.

Compared with the wireframe era, the motion reads as a colored block tumbling in space, not a line drawing. That is the milestone we wanted before we touch diffuse lighting or triangles.

Why quads first (and triangles later)

The project breakdown still pointed at an honest triangle mesh next — refactor the cube into a real triangle stream before any filled raster, not just the twelve hull edges we knew from wireframe. Sergey pushed back on that ordering: we could stay on quad faces longer, as long as we had a routine to fill four-vertex convex polygons in screen space.

Cursor walked through the usual options — triangulation into two triangle fills, scanline edge intersections, bounding box plus half-plane inside tests, and so on. Sergey narrowed the scope: only approaches that do not require a filled-triangle primitive first. Among those, he wanted bounding box plus inside test (half-space / cross-product signs on each edge). That matched the cube: each hull side is already a quad in CubeFace; project four corners, test inside a 2D convex polygon, paint one RGB per face — enough for the “rainbow-ish” milestone without standing up general triangle fill yet.

A planning pass caught up: quad fill is interim; when the sphere milestone lands, refactor the cube to two triangles per face, implement one triangle rasterizer, and delete the quad path. Sergey was explicit that we must not keep two fill implementations side by side.

The algorithm for polygon fills

To paint a flat facet we treat it as a convex polygon in screen space — for the cube, a projected quad — and assign one RGB value to every pixel that lies inside it. The idea is two layers: a bounding-box scan, then a point-in-polygon test. We do not triangulate the face and we do not build a scanline edge-intersection table.

How it works

First, wrap the projected corners in an axis-aligned bounding box — the smallest rectangle aligned with the pixel grid that contains them all. Only pixels inside that box can belong to the polygon; everything outside is discarded immediately.

Second, for each pixel in the box, ask whether its sample point $p$ lies inside the polygon. On a convex shape, “inside” means the same thing as lying on one side of every edge: each directed edge $(v_i, v_{i+1})$ defines a half-plane, and the interior is where all of those agree (half-plane view of convex polygons).

That sidedness is a signed 2D cross product. For edge $i$, with $e_i = v_{i+1} - v_i$ and $w_i = p - v_i$,

For a point strictly inside a strictly convex polygon, every $z_i$ has the same sign — all positive or all negative, depending on vertex winding and which side you call “inside.” If any $z_i$ disagrees, $p$ is outside. Each candidate pixel on a quad face runs four such tests.

Our code implements this algorithm in the FillQuad ($n = 4$) drawing primitive.

Why we chose it

It is the simplest filling algorithm we could adopt with math that stays transparent: a box, a nested loop, and consistent signs on the edges. Scanline fills, triangulation into triangles, and other standard options all work, but they carry more ceremony before the first correct pixel lands. That mattered while we were still learning the raster path and wanted the cube milestone done without getting stuck in the implementation details.

Trade-offs

The algorithm only applies to convex polygons. That sounds like a restriction, but our cube faces are convex quads after projection, so it is not a practical problem for this release.

The real cost is performance: visiting every pixel in the bounding rectangle is wasteful when the shape is skinny or tilted — many candidates fail the inside test after you have already walked to them. A scanline approach that fills only the spans between edge intersections does less throwaway work on a large framebuffer. We have not measured that yet; seeing whether that overhead matters is a job for later, once the filled cube is settled.

Putting it all together

At the crate root we now have two ways to draw the cube: draw_edges for wireframe strokes, and draw_faces for filled facets. Both take the same camera and mesh, apply the same back-face culling, and project through the orthographic camera — one emits line segments, the other filled quads.

draw_faces is the general entry point for this milestone. It walks visible faces, fills each with FillQuad, and tints each side from a fixed CUBE_FACE_PALETTE (six deliberate RGB values, one per hull face). That is not a lighting model; it is just enough color variety to show that the full pipeline — cull, project, fill, export — actually works. The still and animated exporters call draw_faces instead of draw_edges.

draw_edges remains for convenience and debugging. We expect to drop it once filled geometry is all the cube exporters need.

What comes next

We still defer a depth buffer. For a single convex cube drawn back-to-front by face culling alone, sort-free fills are safe enough. Overlap fights return when we have self-occluding meshes (torus tube, multiple objects) — that is the depth-buffer milestone, after the cube and sphere share a unified triangle path.

The immediate follow-on is cube basic shading: keep quads for a while, add a simple diffuse term so facets read as planes under a light direction — still on the CPU, still orthographic. After that, the sphere milestone forces the triangle refactor and retires FillQuad from steady-state rendering.

Version 0.0.5 fixes that with the simplest trick that works on a convex cube: back-face culling on the wireframe. We still raster only lines; we just stop drawing edges that both adjacent faces agree are hidden.

Version 0.0.5 on GitHub

What you will see

Side by side with 0.0.4, the difference is obvious. The tumble and the cornflower blue stroke are the same; what changes is which edges survive. Back faces no longer leak through — it finally looks like a cube you’re looking at from the outside, not a glass box you can see straight through.

Fewer lines per frame also shrinks the animated WebP on disk (~300 KB vs ~387 KB at 0.0.4) — a side effect, not the goal.

Wireframe is fine — hidden faces are not

We are not abandoning wireframe. Orthographic projection, the Euler tumble, 360 frames at 50 fps, lossless WebP — all of that stays. The raster path is still draw_line end to end.

What felt wrong was semantic: when you watch the cube spin, edges on the rear faces are still there. Your brain knows those faces are turned away; drawing them anyway makes the object feel see-through in the wrong way — not artistic x-ray wireframe, just incomplete occlusion. For a convex cube, that is the easiest visual lie to fix before we add perspective, triangle fills, or a depth buffer.

The usual name for that fix is back-face culling — here is how we apply it on a line-only cube.

What is back-face culling?

In real-time graphics, the idea is simple: do not spend work on geometry that faces away from the camera.

Each flat face of a mesh has an outward normal — a unit vector perpendicular to the surface, pointing out of the solid. Compare that normal to the view direction (from the surface toward the eye, or equivalently the direction you treat as “into the scene”). The dot product $\mathbf{n} \cdot \mathbf{v}$ tells you which way the face points relative to the viewer:

• Front-facing: $\mathbf{n} \cdot \mathbf{v} > 0$ — the face points somewhat toward the camera; draw it (or, for us, allow its edges).
• Back-facing: $\mathbf{n} \cdot \mathbf{v} < 0$ — the face points away; cull it.
• Edge-on (grazing): $\mathbf{n} \cdot \mathbf{v} = 0$ — the face is sideways to the view. We treat that as not back-facing so silhouette edges do not vanish awkwardly.

For filled rasterization you usually cull whole triangles before shading. We are not filling yet; we cull at the level of faces vs edges:

On each hull edge shared by two faces, draw the edge unless both faces are strictly back-facing.

In practice that means keeping silhouette and front hull wiring while dropping edges that exist only on the back of a convex solid. It is the same facing test as triangle culling, applied to which line segments we emit.

A concrete check: after a π/4 tilt on X and Y with 0.5 uniform scale (camera down +Z), visible_edges emits nine segments instead of twelve. The three dropped edges are hull segments where both incident faces are back-facing. A silhouette edge between a front face and a back face still draws — only one side is culled.

Our fixed orthographic camera looks down +Z; Camera::direction returns that axis so draw_edges and the cube use one consistent $\mathbf{v}$.

Implementation: why we introduced CubeFace

Until 0.0.4, the cube was enough to describe as vertices and edges: eight corners, twelve undirected segments, pose them with a matrix, hand them to the line rasterizer. That model was fine while we drew every edge every frame.

Back-face culling adds a requirement edges alone do not carry: which way each side of the box faces. You need a face — not as a filled polygon yet, but as a record that owns an outward normal and knows which corners bound that side. Normals do not live naturally on a bare edge list; they belong to facets.

We extracted CubeFace into its own module so that logic stays in one place and the rest of the code reads in terms of “a face” instead of scattered dot products and adjacency tables. The goal was simpler reasoning, not a bigger public API.

What CubeFace is responsible for

Each CubeFace is one quad of the hull. It stores:

• an outward unit normal (updated when the cube is posed), and
• four vertex indices into the parent cube’s corner array (which corners form this side).

Its methods mirror those responsibilities:

• transform — rotate the normal with the same pose matrix as the cube; leave indices unchanged (0 … 7 always refer to the same corners).
• is_back — run the facing test ($\mathbf{n} \cdot \mathbf{v} < 0$).
• edges — list the four boundary segments of this quad (index pairs along the winding).

Cube itself changed shape: it now stores vertices and faces, not vertices and edges.

Cube::default builds a unit cube — edge length 1, centered at the origin (0, 0, 0) — as eight corners and six CubeFace records (outward normals along $\pm X$, $\pm Y$, $\pm Z$). That default is the template; exporters customize the pose by calling Cube::transform, which returns a new cube with moved corners and updated face normals (the animation’s Euler tumble and the 0.5 uniform scale go through here).

We still need edges to draw the wireframe. They are no longer stored on the cube — we derive them from the faces. visible_edges skips back-facing faces, walks the boundary of each remaining face, and emits Edge pairs for the rasterizer. Each interior hull edge belongs to two faces, so without deduplication we would emit it twice; canonical $(\min,\max)$ index keys collapse those duplicates.

wireframe::draw_edges is unchanged in spirit: project through Camera::transform, call draw_line. It now sources segments from visible_edges, passing camera.direction(), instead of the old always-twelve edges() path from 0.0.4.

Our next move

With orthographic projection, animation, and back-face–aware edges in place, the wireframe line of milestones feels complete for now.

The next chapter is solid geometry: a filled cube whose faces have color — six sides, six deliberate RGB values, rasterized as flat facets rather than strokes. Same pose and camera; the framebuffer gets triangles instead of segment lists. That is not lighting yet (no diffuse term, no light direction), but it is the bridge from “edges only” to surfaces you can later shade.

After the colored solid reads correctly, shading and lighting are the natural follow-on — faces that change brightness with orientation and a simple light model, still on the CPU before we tackle spheres, depth buffers, or perspective. The wireframe era taught projection and facing; the fill era is where the cube starts to look like an object. That solid, faceted cube is live in 0.0.6.

Version 0.0.4 on GitHub

What you will see

The still image from 0.0.3 — white edges, tilted cube, black background — is still there via the still-cube binary. The headline artifact for this release is motion: a cornflower blue wireframe tumbling smoothly in orthographic projection.

Same twelve edges and fixed camera as before.

Refactoring: a unit cube we can pose

In 0.0.3 the cube lived as raw vertex lists and edge pairs in main. This milestone extracts that into a Cube: a unit cube (edge length 1, centered at the origin) that we place however we need via set_transform. Scale it, tilt it, spin it — the mesh definition stays fixed; only the matrix changes.

Wireframe drawing walks edges(), which yields the twelve segments after the current transform. Each export path picks a matrix, hands the cube to draw_edges, and the line rasterizer does not care which pose we chose.

This looks like the birthplace of a generic Mesh abstraction: something that can expose edges in world space whether the mesh is a cube, a sphere, or a torus later. We are deferring that extraction until we have a second shape worth generalizing over; a concrete Cube is enough while projection and animation are still in flux.

We also split 0.0.3’s single main into two export binaries — still-cube for the golden still and animated-cube for the frame loop — so each artifact has a clear entry point.

From one frame to many

Until now WebpEncoder accepted a single framebuffer and wrote one still image. WebP is not only a still image codec: the same container can hold an animated image — a sequence of frames with per-frame timing, like a compact GIF. We picked lossless animated WebP over GIF to keep the same RGB encode path we use for stills, built with the webp-animation crate.

Animation needs a time loop: clear the bitmap, set a new transform on the cube, draw edges, append a frame, repeat. animated-cube runs that loop ANIMATED_CUBE_FRAME_COUNT times.

Frame count

We picked 360 frames so one full orientation lap samples the Euler angle about once per degree — smooth enough to eyeball, still a round number to reason about. The count lives once in the library as ANIMATED_CUBE_FRAME_COUNT so the binary, integration test, and any future caller cannot disagree. Frame index $i$ maps to

when we build the model matrix (see below) — one full turn in radians.

Playback at 50 fps

Playback speed is not implicit in “360 frames”; the animated WebP format stores an explicit timestamp in milliseconds on each frame. WebpEncoder::with_frame_spacing wraps webp_animation::Encoder: on each add_frame we pass the current timestamp, then advance it by FRAME_SPACING_MS (20 ms). That is 1000 / 20 → 50 fps.

Timestamps must be strictly increasing (0, 20, 40, …), which the encoder enforces. At finalize we pass the next timestamp so the last frame’s display duration matches the spacing between frames (frame 359 at 7180 ms).

One lap of motion over 360 samples at 50 fps is 7.2 s of video — long enough to see the tumble, short enough to iterate quickly.

How the cube moves

Early in the milestone we prototyped a spin around world $+\mathrm{Y}$ alone — legible motion, but it reads as a flat carousel. The breakdown called for a three-axis Euler tumble; after a quick side-by-side with the WebP, we shipped that instead.

What “three-axis Euler” means

The name comes from Leonhard Euler, who studied how rigid bodies rotate in 3D. An Euler angle decomposition expresses orientation as several successive rotations, each about a coordinate axis, instead of one big matrix chosen from scratch. Three-axis means three such steps — typically one turn about $X$, one about $Y$, and one about $Z$, each with its own angle ($\alpha$, $\beta$, $\gamma$ in the usual notation).

Why rotation order matters

A product like $R_z(\gamma)\, R_y(\beta)\, R_x(\alpha)$ is not a menu of three independent spins you can list in any order. It means: apply the rotations one after another, and in our column-vector convention the rightmost factor hits the vertex first — so $R_x(\alpha)$, then $R_y(\beta)$, then $R_z(\gamma)$.

The core reason is that 3D rotations do not commute: in general

when $A$ and $B$ are different axes (here $X$, $Y$, $Z$). Swapping the order changes the composite matrix, so the cube ends up in a different orientation even with the same three angles.

A quick check: start at $+X$, apply 90° about $Y$ then 90° about $X$ and you land on $+Y$; swap the order and you end on $-Z$ instead — same angles, different final axis. (In 2D all rotations share one axis, so order barely matters; in 3D the intermediate axes tilt with each step.)

So $R_z(\gamma)\, R_y(\beta)\, R_x(\alpha)$ and $R_x(\alpha)\, R_y(\beta)\, R_z(\gamma)$ are different poses for almost every choice of $\alpha$, $\beta$, $\gamma$.

Graphics and robotics texts therefore pick one convention — axis order and whether angles are measured in a fixed world frame or in a frame that rotates with the object — and stick to it. Our animation applies rotations in $X \rightarrow Y \rightarrow Z$ order (about the fixed world axes).

Our animation is a deliberate simplification: we use one time-varying angle for all three axes ($\alpha = \beta = \gamma = t$), so the cube “tumbles” through combined $X$, $Y$, and $Z$ motion in one smooth lap — less general than arbitrary Euler angles, but enough for this milestone.

The pose is a world-fixed tumble. Each frame we build one matrix:

Same convention as above: that product applies $X \rightarrow Y \rightarrow Z$ (rightmost factor first), even though the factors read $Z \rightarrow Y \rightarrow X$ left to right in code.

With $\alpha = \beta = \gamma = t$, where $t$ sweeps across the lap in

(exclusive of $2\pi$ on the last sample). One angle for all three rotations keeps the loop seamless — each factor completes whole turns when $t$ returns to zero.

The per-frame model matrix is

Each frame builds a fresh matrix and passes it through set_transform before edges() runs. The still and animated paths use different poses — the golden still keeps the π/4 tilt from 0.0.3 in white; the animation is a world-fixed Euler tumble in cornflower blue without that extra tilt — but the same Cube type and draw_edges path.

Testing animation without golden pixels

We still compare the still image against snapshots/cube/scene.webp at full RGBA resolution. For the animated path we added a lighter integration check: run animated-cube, decode the output with webp_animation::Decoder, and assert the frame count matches ANIMATED_CUBE_FRAME_COUNT (animated_cube_writes_frames).

Pixel-exact regression on every frame of a 360-frame animation is deferred — eyeballing the sample WebP and the frame-count guardrail are enough for now. When motion bugs get subtle, we can add golden frames or compare raw framebuffer bytes before encode.

Regenerate the still image snapshot after intentional visual changes:

cargo run --quiet -p thorus-forge --bin still-cube -- snapshots/cube/scene.webp

Write a fresh animation (optional output path):

cargo run --quiet -p thorus-forge --bin animated-cube -- doc/output/current.webp

Our next move

We now have the animated orthographic wireframe milestone from the breakdown: time-varying model orientation, multi-frame lossless WebP, same line rasterizer and camera as 0.0.3.

Not in 0.0.4 yet: perspective projection, filled triangles, depth buffer, back-face culling, or lighting.

The breakdown had perspective wireframe next. Sergey is changing that order: perspective is still on the list, but first he wants the cube to stop drawing invisible sides. Back-face culling on the wireframe (drop edges that belong only to faces pointing away from the camera) should make the tumbling shape read more solid before we touch homogeneous divide math. Perspective and filled raster with a depth buffer can wait until that looks right — the follow-up post covers that culling milestone.

Version 0.0.3 on GitHub

What you will see

The radial spoke pattern from 0.0.2 is gone. In its place is a tilted cube: twelve white edges on black, readable as three dimensions at a glance.

Not a demo pattern for line quality anymore — geometry we care about, projected onto the framebuffer.

Let’s talk about projections first.

What orthographic projection is

Until now we drew directly in screen space: endpoints were already pixel coordinates. This milestone is the first time we place geometry in 3D world space and need a deliberate map from there onto a 2D bitmap.

Why we need projection at all

A rasterizer ultimately writes pixels: a flat grid of (column, row) addresses. Our cube lives in three coordinates per vertex — width, height, and depth in the scene. Something has to answer: given a point in the world, which pixel (if any) should we touch?

That map is projection. In a full renderer it usually sits in a short chain:

1. Model — put mesh vertices where the object sits (position, rotation, scale).
2. View — express the scene relative to the camera (where the eye is, which way it looks).
3. Projection — collapse the remaining depth information into the 2D image plane (orthographic or perspective).
4. Viewport — scale and shift into framebuffer pixels (our 800×600 grid, Y flip, aspect correction).

We are only partway into that chain in 0.0.3 — fixed view, minimal projection, viewport math in ortho_camera — but the question is the same: 3D in, 2D out. Without projection, we would have to hand-place every line in pixel space and could not rotate a cube in world coordinates.

In practice the two 3D projection types you meet most often are orthographic (parallel view rays) and perspective (rays through an eye). This milestone uses orthographic; we will add perspective for the cube later.

What orthographic projection does

Orthographic projection is the parallel case.

• Imagine view rays all perpendicular to the image plane — like a very distant viewer where lines of sight never converge.
• A point is projected by sliding it along its ray until it hits the plane. Depth along the view direction does not change where the point lands on the plane — only the position within that plane matters.

Equivalently: drop the coordinate along the view axis and keep the other two. In our conventions (+Z forward, camera looking down +Z), screen position depends on x and y only; moving a vertex forward or backward along z does not slide it left or right or up and down on the image.

That is why orthographic views feel like technical drawings or blueprints: parallel edges in the world stay parallel on screen, and objects do not grow larger when they move closer. Two cubes at different depths but the same (x, y) paint the same pixel. There is no vanishing point and no foreshortening from distance.

Perspective projection does the opposite: rays meet at the eye, distant objects look smaller, and parallel lines (railroad tracks) appear to converge. For now, orthographic matches “true size on the drawing sheet” and keeps the math small while we wire up transforms and tests.

From lines to a scene

The rendering loop stays small. We keep draw_line from 0.0.2; main now owns the scene:

• eight corner vertices in model space (CUBE_VERTS, edge length 0.5 centered at the origin),
• twelve undirected edge pairs (CUBE_EDGES),
• for each edge: rotate the cube, transform both endpoints with Camera::transform, then rasterize.

draw_cube_wireframe walks that edge list. No triangle fill, no depth buffer — only segments.

We also added glam for Vec3, Mat3, Mat4, and UVec2. The custom Point(u32, u32) wrapper went away; pixel endpoints are glam::UVec2 end to end so types stay consistent as the scene grows.

Why the cube must be tilted

Our 0.0.3 orthographic path ignores z when placing pixels (see below). Without a model rotation, an axis-aligned cube collapses: the front face fills the square, and edges that differ only in z share the same (x, y) — they never show up.

We tried a face-on, axis-aligned pass first to sanity-check aspect ratio (one square on screen — expected). The shipped pose tilts the cube π/4 about Y, then X (Mat3::from_rotation_x * Mat3::from_rotation_y), documented in draw_cube_wireframe. That is enough for depth-only edges to appear while the camera math stays simple.

The camera stays fixed for this release; only the model rotation changes the picture.

Mapping world space to the framebuffer

Module ortho_camera defines a Camera built once per framebuffer size. It maps world coordinates → pixel coordinates under conventions documented in the module: left-handed scene, +Y up, +Z forward, bitmap origin top-left with +y down.

A deliberately simple camera

We are not building a general camera system yet. The scene assumes one fixed pose, aligned with the project spec:

• Eye at (0, 0, −1)
• Look-at the origin (0, 0, 0)
• Up along +Y

One unit back on −Z, looking down +Z, sky in +Y. There is no look_at view matrix in code — with this pose, world x and y feed projection as-is, and z is dropped for screen placement.

Camera::transform still does the framebuffer work: scale (shared factor from the shorter edge, centered), flip y (bitmap rows grow downward), round to integers. The simplification is the fixed camera pose, not skipping viewport math.

We chose that on purpose. Movable eyes, arbitrary targets, and full view matrices are useful later, but they add sign conventions we do not need while learning wireframes. For now: rotate the cube in model space, project xy, draw lines. We may add look_at, orthographic frustum boxes, or a moving viewpoint once the pipeline feels familiar.

Aspect ratio

Early on we hit aspect distortion: mapping [-1, 1]² independently onto 800×600 stretches a world-square into a 4:3 rectangle. The fix uses one scale from the shorter edge, centered:

scale = min(width − 1, height − 1) / 2
px    = world.x * scale + (width − 1) / 2
py    = −world.y * scale + (height − 1) / 2

On a non-square viewport that letterboxes or pillarboxes so equal world spans along x and y occupy equal pixel spans.

Under the hood this is a precomputed Mat4 (ndc_viewport_matrix): homogeneous multiply, then round. Same mapping, clearer composition when we add more matrix stages.

A unit test (world_z_shift_does_not_change_screen_xy) locks in that z does not affect xy pixels yet — no depth buffer in this milestone.

How we got here

Between 0.0.2 and 0.0.3 we explored orthographic projection the hard way: integration tests, NDC conventions, viewport mapping, even depth packing — then peeled back scope when the milestone picture cleared.

There was briefly a richer stack: mesh modules, triangle soup, wireframe edges from triangulation, look_at_lh, orthographic frustum parameters, fractional line endpoints, a golden WebP with JSON metadata. Sergey kept the tests, planning notes, and reference image, but deleted the implementation and rebuilt step by step rather than inheriting a large diff.

Version 0.0.3 is that slimmer rebuild: cube data in main, projection in ortho_camera, the line rasterizer unchanged. Same diary lesson as before — use agents heavily, but own the code you will maintain six months from now.

Testing the full scene

Line tests still use ASCII art helpers. For the whole image we compare decoded RGBA bytes against a committed snapshot at snapshots/cube/scene.webp.

Regenerate after intentional visual changes:

cargo run --quiet -- snapshots/cube/scene.webp

Two levels of feedback again: local geometry in unit tests, pixel-exact scene stability at integration scope.

What this version unlocks

We now have the orthographic wireframe backbone from the milestone breakdown: fixed camera, twelve edges, one model orientation, still image only.

Not in 0.0.3 yet: animation, perspective, filled triangles, depth buffer, culling, or lighting.

Next up was animated orthographic wireframe — the cube starts spinning in the follow-up post. After that: perspective, then filled raster with depth.

Version 0.0.2 on GitHub

What changed in practice

Version 0.0.1 proved the output pipeline. Version 0.0.2 expands our drawing capability from single points to full line segments. The key change is a line primitive, draw_line, implemented on top of the existing framebuffer and guarded set_pixel.

The result is still intentionally simple and easy to inspect:

Line drawing algorithm

A notable decision in this milestone was the line algorithm itself. We briefly had an integer Bresenham path while iterating, then switched to DDA: Digital Differential Analyzer.

This was also a deliberate learning choice from Sergey: instead of spending time learning Bresenham in depth right away (a nice exercise, but not our focus right now), we picked the approach that felt closer to the math. We acknowledged this is likely a performance penalty versus a tighter integer-heavy implementation, but at this stage that cost is not very important for us. Better to use an algorithm we understand clearly, then optimize later if profiling says it matters.

What DDA is

A Digital Differential Analyzer is a way to turn a continuous curve into discrete pixel steps. For line drawing, it works like this:

• treat the segment as a parametric function over $t \in [0,1]$
• sample $t$ at evenly spaced values
• compute continuous $(x,y)$ at each sample
• round to the nearest pixel and plot it

DDA implementation for lines

The math is small but useful. Given endpoints $P_0 = (x_0, y_0)$ and $P_1 = (x_1, y_1)$, define:

Here, $N$ is the number of equal sampling intervals we use along the segment (so we evaluate $N+1$ points including both endpoints). We choose $N$ based on the dominant axis.

By dominant axis, we mean the coordinate that changes more over the whole segment:

• if $\lvert\Delta x\rvert \ge \lvert\Delta y\rvert$, the line is more horizontal, so $x$ is dominant
• if $\lvert\Delta y\rvert > \lvert\Delta x\rvert$, the line is more vertical, so $y$ is dominant.

For example, from $(2,3)$ to $(12,7)$ we have $\Delta x=10$ and $\Delta y=4$, so $x$ is dominant and we use $N=10$. From $(5,1)$ to $(8,13)$ we have $\Delta x=3$ and $\Delta y=12$, so $y$ is dominant and we use $N=12$.

First, let’s write the segment in parametric form for each coordinate:

Then sample:

Each $(x_i, y_i)$ is still continuous (floating point), so rasterization needs one more decision: map to a pixel center. Here we use rounding:

Those integer $(p^x_i, p^y_i)$ coordinates are what set_pixel writes. Because $i$ runs from $0$ through $N$, the segment is endpoint-inclusive by construction.

The key intuition is that $N = \max(\lvert\Delta x\rvert, \lvert\Delta y\rvert)$ guarantees we advance no more than one pixel per step along the dominant axis, which avoids visible gaps in the rasterized line. If a rounded sample lands outside the framebuffer, set_pixel safely ignores it, so we get simple clipping behavior without a separate clipping algorithm yet.

For this milestone, that trade-off is exactly what we wanted: readable geometry-first code, predictable testable output, and a direct bridge from line equations to pixels before we optimize anything.

Testing the shape, not just the function

This milestone also improved tests in a useful way. Instead of only checking individual bytes, we added several line-focused unit tests and a tiny ASCII view helper so expected pixel patterns are readable at a glance.

That gave us confidence in the cases that matter right now:

• horizontal, vertical, and diagonal segments,
• endpoint inclusivity (forward and reverse),
• clipping behavior when endpoints land outside the framebuffer.

Here is the style of unit test we used to verify shape directly:

#[test]
fn draw_diagonal_line_slope_one() {
    let mut fb = FrameBuffer::new(10, 5);
    fb.draw_line(Point(1, 0), Point(4, 3), Rgb::WHITE);

    #[rustfmt::skip]
    let expected = concat!(
        " +        ",
        "  +       ",
        "   +      ",
        "    +     ",
        "          ",
    );
    assert_eq!(fb.to_ascii_art(), expected);
}

This style made expected output much easier to read in code review than raw byte arrays. It also made adding new test cases faster: in many cases, we only needed to change the expected ASCII pattern while keeping the same assertion structure.

The broader integration test still verifies that the binary writes a decodable WebP, so we keep both levels of feedback: local geometry correctness and end-to-end artifact validity.

Why the new output uses radial spokes

The rendered scene is now a radial-spoke pattern: many segments from the image center to a circle. In code, that happens in draw_flower by iterating angles over the entire circle and issuing one draw_line per spoke.

We originally discussed a crossed square for this milestone. That remains a good regression-style scene, but the radial image turned out to be better for quick visual checks:

• missing pixels are obvious,
• endpoint handling is easier to spot,
• small directional asymmetries stand out immediately.

The original plan, a crossed square, would not give us enough visual feedback on line quality. A few simple vertical, horizontal, and diagonal lines provide less information than many radial directions. So Sergey chose to switch the output to radial spokes.

What this version unlocks

This release does not yet include projection, meshes, or triangle filling. But it gives us a dependable primitive that all of that will rely on. The next milestone was orthographic cube projection, where this line path becomes the first wireframe backbone instead of a standalone demo — we shipped that in a cube takes shape.

That makes it a good first checkpoint.

Version 0.0.1 on GitHub

What you will see

Take a look at the center of this image: do you see a white dot? That’s it!

Why Start With WebP?

The original project plan is about learning 3D rasterization: line drawing, projection, cubes, filled triangles, depth buffering, shading, and eventually more complex shapes. But before any of that, we needed an output path.

Sergey chose a deliberately small first step: instead of jumping straight to a cube, or even a line, we would write a still image. At first, the idea was a full black frame. Then we grew it into the planned milestone artifact: a black 800x600 image with a single visible center pixel.

This matters because rasterizers are easy to debug poorly. If the only way to observe the program is through internal buffers or println!, then every later bug becomes harder to reason about. A browser-displayable image gives us a simple feedback loop:

1. render into memory,
2. encode the framebuffer,
3. open the file,
4. trust that what we see corresponds to the bytes we produced.

The first milestone was therefore not “draw something impressive.” It was “make future drawing work observable.”

The First Shape: A Framebuffer

The earliest version allocated raw pixel bytes directly in main. That worked for the all-black image, but it made the wrong thing central. main should coordinate the program: choose the dimensions, choose the output path, ask the encoder to write the result. It should not be the long-term home of pixel storage rules.

So we extracted a FrameBuffer.

The framebuffer currently stores RGB bytes: three u8 values per pixel, row-major, fixed dimensions supplied at construction time. The constructor zero-fills the buffer, which gives us a black image by default. On top of that, we added a tiny color type, Rgb:

Rgb(pub u8, pub u8, pub u8)

and the first drawing primitive, set_pixel:

set_pixel(x, y, color)

There is already a design choice hiding in that small API. If a caller tries to write outside the image, set_pixel silently ignores the request. That matches the current rasterization plan: early drawing code can be simple and skip out-of-bounds writes without doing full clipping. Later line drawing will benefit from that. A line can step through points and ask the framebuffer to write each one; points outside the canvas simply do not land.

This is not a universal answer. Some projects should return errors or assert on invalid coordinates. For this rasterizer, at this stage, “skip-only” is the cleaner primitive.

Encoding: Still Image First, Animation Later

The output path uses the webp-animation crate, even for the still image. That may look odd at first: why use an animation encoder for a single frame?

The reason is continuity. The project plan calls for still WebP images first, then animated WebP clips once we start rotating cubes. Using the same crate now means the still path and the future animation path share the same basic machinery.

There was one small trap here: frame timestamps.

The underlying encoder expects strictly increasing timestamps. For a one-frame image, we still need to add a frame and finalize the stream with a valid end timestamp. We wrapped that in a WebpEncoder type that owns the timestamp counter. The public API can stay simple:

• create an encoder with width and height,
• add a frame,
• write the file.

Internally, it handles timestamps as 0, 1, 2, ... milliseconds and finalizes with at least 1 millisecond so a single-frame image is valid. We briefly tried removing the counter and hard-coding a timestamp, but that only made sense for one frame. Sergey asked to roll that back, which was the right call: even in version 0.0.1, the API should point toward the animation milestone instead of painting us into a corner.

Testing the Artifact, Not Just the Code

A useful part of this milestone was deciding what kind of test belongs here.

We did not add golden image tests yet. Pixel-perfect image regression tests are useful, but they also introduce friction: fixture files, decode paths, update workflows, and false confidence if the asserted artifact is too narrow. The planning docs explicitly defer those until eyeballing stops being enough.

Instead, we added an integration test that runs the real binary in a temporary directory and decodes the output WebP. The test checks the most important promise at this layer:

• the command succeeds,
• the output file exists where requested,
• the file is valid WebP.

This gives us a good middle ground. We are not trying to freeze every byte of the encoded file. We are checking that the program a user runs produces a valid artifact with the expected semantic content.

There was also a small Cargo detail: integration tests can find the compiled binary via CARGO_BIN_EXE_<target>. We chose to require that Cargo-provided path instead of maintaining a filesystem fallback based on the test executable location. That keeps the test honest: it is a cargo test integration test, not a general-purpose binary locator.

Pair Programming Notes

This project is also an experiment in AI-assisted programming, so the process matters as much as the code.

The milestone had a useful rhythm:

• Sergey kept the target small and concrete.
• Cursor proposed structure and tests.
• Sergey pushed back when an abstraction or fallback did not match the desired direction.
• Cursor adjusted the implementation and captured the reasoning in session notes.

That back-and-forth already shaped the code. For example, the output path started with an opaque black frame, moved through RGBA details, then settled into an RGB framebuffer feeding a WebP encoder. The FrameBuffer API narrowed after discussion: no width/height getters just because they were easy to add, no redundant out-of-bounds test once the simpler invariant was enough, no binary-location fallback once the Cargo contract was clear.

Those are small choices, but they are exactly the kind of choices that keep a learning project from turning into a pile of plausible-looking code.

What 0.0.1 Means

Version 0.0.1 does not yet contain line rasterization, projection, meshes, cameras, or shading.

It gives us the base surface those things will use:

• a framebuffer with explicit RGB storage,
• a minimal pixel-writing operation,
• a lossless WebP export path,
• a command-line output filename,
• unit tests for buffer behavior,
• an integration test that proves the binary writes a decodable image.

Most importantly, it gives us a visible artifact:

a black 800x600 image with one white pixel in the center.

That pixel is the first sign that bytes are flowing through the whole pipeline correctly.

Next up: drawing lines. The next milestone is a crossed square, which should turn set_pixel from a sanity-check helper into the foundation for the first real rasterization algorithm.