Home /Modules/bash/RENDER_MATH.md

RENDER_MATH.md

bash/model-3D/RENDER_MATH.md · 130 line(s) · markdown

Rendering math & the rendering group

Part of SleelaTerminal™ (Phraign™ City 3D), SLeeLa's terminal product, built on GNU Bash (GPL, © Free Software Foundation).

Phraign™ City 3D's rendering is split into three small, layered pieces so the geometry/color math is reusable and testable on its own, separate from both Phraign and the city model:

render_math    pure geometry + color + projection + scanline fill  (no Phraign)
    ▲
render_group   RenderSink over a Phraign frame + an ordered item container
    ▲
city_renderer  turns a City into a group of quads and draws it

1. Rendering math (render_math.hpp/.cpp, namespace sleela::render)

Basic, dependency-free primitives.

Vectors

Color

Rgba { r, g, b, a } packed as 0xRRGGBBAA to match the Phraign pixel word.

Projection — ObliqueCamera

An oblique/dimetric camera: the scene is seen from above and slightly to the side. World axes are x = east, y = depth, z = up. A world point maps to the screen by:

screen.x = origin_x + x*scale_x + y*tilt_x
screen.y = origin_y + y*tilt_y - z*scale_height
FieldMeaning
tilt_xscreen-x skew per unit of depth (the side angle)
tilt_yscreen-y advance per unit of depth (how top-down it looks)
scale_xscreen px per unit east
scale_heightscreen px per unit up (taller skyline)
origin_x, origin_yscreen px where world (0,0,0) lands

project(Vec3) -> Vec2 performs the mapping. It is intentionally affine (no perspective divide), which keeps parallel building edges parallel — the classic "toy city" look.

Screen geometry & fill

2. The rendering group (render_group.hpp/.cpp)

A rendering group is an ordered collection of drawable items submitted to a target and drawn in a controlled order. Because the city view has no z-buffer, correct occlusion comes from draw order (the painter's algorithm).

PhraignSink

A RenderSink implemented over a Phraign PixelTerminal. Each plot() writes one pixel of the Phraign frame via setPixel, keeping rendering strictly per pixel on the Phraign surface.

QuadItem and RenderGroup

QuadItem { Quad geom; uint32 color; double depth; }.

RenderGroup collects items and draws them:

Note: draw(sortByDepth = true) reorders the group's items in place, so a later unsorted draw() observes the already-sorted order.

3. How city_renderer uses them

For each block with height h, the renderer builds three world-space quads — the lit side (east face), the shaded side (front face), and the roof (top face) — projects them with the ObliqueCamera, and adds them to a RenderGroup:

The camera is derived from the City Viewpoint: block_pitch is folded into tilt_x/tilt_y so one grid cell maps to one world unit while preserving the on-screen spacing.

Testing

render_smoke.cpp (built by make and run by make smoke) exercises the math against a plain buffer sink and the group ordering/PhraignSink against a real Phraign frame: vector ops, color pack/shade/lerp, projection direction checks, quad bounds/centroid, fillQuad pixel counts and clipping, and depth-sorted vs. insertion-order draw.