MICROCOSM internals
How the engine is put together, and why

The primitives (mc_mesh_box, mc_mesh_plane, mc_mesh_uv_sphere, mc_mesh_icosphere, mc_mesh_torus, mc_mesh_cylinder, mc_mesh_cone and mc_mesh_rounded_box) are generated the usual way, from grids, swept angles and stacked rings. mc_mesh_icosphere is different. It starts from a 20-triangle icosahedron and subdivides, so its triangles stay roughly the same size instead of bunching at the poles as a UV sphere's do. That matters once you displace it with noise, because uneven triangles show up as uneven bumps. Two more constructors make whole shapes: mc_mesh_terrain raises a subdivided plane into an fBm landscape, and mc_mesh_torus_knot sweeps a tube along a (p, q) knot.

On top of the primitives sit modifiers that change a mesh in place:

• mc_mesh_subdivide splits every triangle into four, giving you more vertices to push around.
• mc_mesh_displace_noise moves each vertex along its normal by a noise field. That's what turns a smooth sphere into something that looks grown.
• mc_mesh_spherify blends vertices toward a sphere, for morphing.
• mc_mesh_scale scales the positions, for a stretched copy.
• mc_mesh_recompute_normals rebuilds smooth normals as the area-weighted average of the adjacent face normals. Call it after any displacement so the lighting follows the new shape.

mc_mesh_append stamps one mesh into another through a rigid transform or a uniform scale. Take an icosphere and append 18 cones pointing outward along directions spread by the golden angle, and you have a spiky sea urchin in about a dozen lines of C. mc_mesh_grid stitches a block of vertices into triangles, and every swept surface, from a torus to a tube, is stitched with it.

mesh.c keeps every primitive as toolkit API, and a payload pays nothing for what it doesn't call (--gc-sections).

Meshes stay on the CPU until you hand them to mc_mesh_upload, which is in render.c because that's where GL lives. A mesh can also skip the CPU altogether: mc_mesh_procedural makes one with no vertex buffer, and its vertex shader builds each vertex from gl_VertexID. It's drawn either as a plain triangle list of a given number of vertices, or through an index buffer of vertex ids so that a vertex shared by several triangles is shaded once.

The reference demo doesn't call mesh.c at all. All of its geometry is made on the GPU, where it costs no C. Most of it is built in vertex shaders from gl_VertexID, with a mesh that's only a vertex count. That covers Scene 1's six solids (the urchin included), its floor, the blob, the planet, Scene 2's sea, the coral and the weed, and everything in Scene 3 except the tyrannosaurus. Every animal, the tyrannosaurus included, is sculpted at load by a compute shader, the creature kit (jr.comp).

Scene 2's seabed and boulders are worked out once at load by the seabed's placement shader, uwplace.comp, which writes them into a buffer it leaves bound for the frames. They're drawn by index through grids of vertex ids. The seabed matches mc_mesh_terrain's heightfield to a tenth of a millimetre. It uses the same hash, quintic value noise, six fBm octaves at the seed's offsets and smoothstep shaping, written in GLSL. Each vertex gets the normal of its six triangles, summed the way mc_mesh_recompute_normals sums them, and the checks test the GPU's heights against the engine's. The boulder is mc_mesh_displace_noise's three layers of the same noise at the same offsets, each pushed out along the ball's radius over a cube's six grids. See What draws it in the making-of for the details.

• scene is the HDR target: RGBA16F colour plus a 24-bit depth texture. Everything in your scene draws here in linear light, with nothing clamped to 1.0 yet, so bright things stay bright for the bloom pass to find. The depth is a texture rather than a renderbuffer so that the ambient occlusion, the depth of field, the motion blur and the TAA can sample it. The alpha isn't coverage. It holds the ambient share of the pixel's light (below).
• last is last frame's scene. The two swap every frame, so the TAA can compare this frame's depth with the last one's.
• bloom[0..5] is the bloom's mip chain, from half resolution down to 1/64.
• ao and ao_b are half-resolution RGBA8 targets holding ambient occlusion in .r and contact shadows in .g. The depth-aware filter ping-pongs between them.
• dof_a and dof_b are quarter-resolution HDR. The first holds the scene with its circles of confusion, the second the depth-of-field gather.
• ldr is an RGBA16F target that holds the tonemapped image just before the TAA, still at the scene's size. It uses half floats although the picture is already display-ready, because at RGBA8 a fade's smooth glow would reach the history in 8-bit steps, and no dither after the TAA can undo that.
• hist[2] is the TAA's history, ping-ponged. It's RGBA16F at the output size, or at the scene's size when that's larger.

The scene targets run at an internal percentage of the output, from 25% to 200% (below).

Your scene is drawn between mc_renderer_begin(R, clear) and mc_renderer_end(...). begin binds the HDR target and sets up depth and back-face culling. One line in it matters more than it looks:

glDepthMask(GL_TRUE);     /* <-- before the clear, on purpose */
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);

The post passes leave depth writes disabled. If begin cleared the depth buffer while the mask was still off, the clear would silently do nothing, every frame would inherit last frame's depth, and the geometry would tear itself apart for no obvious reason. So the mask is forced on before the clear, and end turns it back on when it's done.

For the TAA, the camera is jittered. Two calls set this up: mc_renderer_frame(R, t) at the start of the frame, with the frame's time, and mc_renderer_camera(R, proj, view) where you'd otherwise use proj * view. The second call shifts the projection by a sub-pixel step from the Halton (2, 3) sequence. It uses eight positions per pixel, in sixteenths of a pixel, so over eight frames every pixel is sampled at eight places. The history follows the frame's first camera. It carries on while time runs smoothly forward (0 < dt < 0.25 s), and starts over, with no jitter, on a jump, a pause, a step back, a resize or the first frame. So the jitter depends only on the time. A frame rendered on its own, or twice at the same t, is the same plain frame, which keeps the headless checks deterministic. A caller that never makes these calls just gets plain frames.

mc_renderer_end runs the post chain (below) and writes the result into the framebuffer it's handed. The last frame's view-projection is kept for the next frame's reprojection, and scene and last swap.

Instancing is how you draw 182 bodies in a handful of draw calls. An uploaded mesh's vertices carry a position (location 0), a normal (1) and a texture coordinate (7). The UV is 0 unless the mesh's builder set one, and shaders that don't read it ignore it. A procedural mesh's vertices carry nothing, and all the demo's meshes are procedural. Any mc_gpu_mesh can also carry a per-instance buffer, whose attributes are the four columns of a model matrix (locations 2-5) and an RGB+emissive colour (location 6). Each is set with glVertexAttribDivisor(., 1), so it advances once per instance instead of once per vertex.

You fill a flat array of mc_instance on the CPU, call mc_mesh_set_instances, then mc_mesh_draw_instanced. The buffer only ever grows, and a VAO keeps its buffer binding when the storage is replaced. The range-draw helper, mc_mesh_draw_instance_range, changes the instance offset to draw a subset for the camera or the light, and sets it back to zero afterwards. Ordinary data uploads don't redefine the attribute pointers.

mc_renderer_end runs the post chain. Ambient occlusion, depth of field and bloom are gated by their strengths in mc_post, and their draws are skipped when they're off. The AO pass also runs when there's a sun, for the contact shadows. Scene 2 ramps its ambient occlusion in over its run, as part of how its look grows (The renderer evolves), and Scene 3 turns the depth of field on for the ladybug. The passes run in this order:

1. ambient occlusion and contact shadows, at half resolution (optional);
2. depth of field, at quarter resolution (optional);
3. the bright pass and the bloom's mip chain (optional);
4. the composite, which grades the frame into ldr;
5. the TAA, which folds it into the history;
6. the present, which puts the history on the output with the grain on top.

A pixel's light is part sun and part sky, and ambient occlusion only applies to the sky's part, since a sunlit patch of floor under a leaf shouldn't grey over. So scene shaders write the ambient share of the pixel's radiance (0..1) in alpha, and the composite applies col *= a * mix(1, ao, ssao) + (1 - a) * contact. Scenes 1 and 2 write 1, so there the AO applies to everything and there are no contact shadows. Scene 3's lighting writes the true share, and additive passes leave alpha alone.

Each of the post passes is a single mc_fullscreen_triangle(): one triangle big enough to cover the screen, its vertices computed from gl_VertexID, with no vertex buffer at all. Core-profile GL still insists that a VAO is bound, so the GL context owns one empty VAO for the purpose, created lazily and deleted before the context is torn down. The engine supports one current engine context at a time, and reopening it can't reuse an old context's object name. tiny64.h draws its full-screen passes with the same trick.

Nothing is looked up by name. The post passes' parameters ride in one std140 block, Post, which mc_renderer_end uploads once a frame, once the scene is drawn, into the same uniform buffer as the demo's Frame block (mc_gl_frame_block, binding 0). The passes' few uniforms of their own, such as a blur's direction, and every texture unit are fixed in the GLSL with layout(location) and layout(binding), so the renderer sets no unit and fetches no location. The demo does the same with every uniform it sets, and that's the convention for new code. Each uniform gets a location that's unique in its program (an array takes consecutive locations), every sampler not on unit 0 gets a binding, and the C side sets them by number.

GL's switches work the same way: mc_gl_switch(bits) sets the depth test, depth writes, culling and blending in one call, with two bits each (leave, on, off). The public header documents the GL state that the passes own. Callers must leave scissor, stencil and polygon offset disabled, and leave full colour writes and fill mode on.

The caller can add its own passes to a frame. Between mc_renderer_begin and the lit draws it can bind a target of its own, draw into it, and call mc_renderer_bind_scene, which hands the framebuffer back to the HDR target. mc_renderer_depth and mc_renderer_color hand out the scene's depth texture and the picture drawn so far. mc_renderer_blur is the renderer's depth-aware filter, for a buffer of one's own at half or quarter resolution. The demo uses all of them.

Scene 2's sun shadow map is one such pass. The demo binds its own depth-texture FBO, renders the big casters from the light's point of view, and hands the framebuffer back. The lit shaders sample that depth texture in compare mode, with 3x3 taps of bilinear PCF. Scene 2 redraws the map on every frame that draws the sea below, starting with the first frame of the crossing. Its object shader, which draws the bubbles, the eyes and the marine snow, reads the map whatever the realism ramp says.

Scene 1 and the end card borrow the same map for their key light, since they never share a frame with Scene 2. s1_draw draws the shapes into it before mc_renderer_begin, which hands the framebuffer back, so no shadow_end is needed. Scene 1's lighting tells how the glass casts a third of a shadow there. The scenes' depth passes share shadow_begin and shadow_end in main.c, as all three scenes share camera_vp, frame_basics and post_depth.

The jelly blob is a clear ball lens. It casts no shadow, but it focuses the sun, and uwsurf.frag works out its caustic from the ball's centre and radius, which ride in the Frame block's uGlow and uGlowAmt. Each scene gives that block's fields its own meanings, and where two uses meet, the block is sent again between draws. Scene 2 re-sends it with uGlowAmt 0 before it draws its bubbles, eyes and marine snow with Scene 1's object shader, whose glow light reads the same two fields. Scene 1 uses uAtmo, Scene 2's sky ramp, for its bang's shock front and the dark of its outro. So the end card, which draws through the same s1_draw, sets uAtmo back to 1 itself instead of relying on whatever ran before it.

Scene 2's dive into the sea is another custom pass. For the 0.34 s the lens takes to go under, a frame first draws the sea above and copies the picture to a texture (jelly_copy, unit 9). Then it clears, draws the sea below, and lays the sea above back over it, above a waterline that sweeps up the lens (dip.frag). The frame builds its first camera, the one the TAA and the motion blur follow, from the sea below, so that it matches the depth buffer.

The jellies of Scenes 2 and 3 and Scene 1's glass bodies are drawn last, and they look through that same copy. The copy is always the whole frame, one glCopyTexSubImage2D. Scene 2's ball lens reads up to about 2.3 radii from its centre, so a rectangle round the ball would be most of the frame anyway. s1_shapes sorts each shape type's glass to the end of its instances and draws the two ranges separately, with mc_mesh_draw_instance_range. The instances are uploaded once a frame, by the first of its four passes. In Scene 2, whatever must not be in the copy draws after the jelly: the bubbles, the blob's eyes and the marine snow. The making-of's Scene 2 section, What draws it, has that order and the depths the jelly writes.

The copy's texture is made again when the renderer's size changes. Scene 2 checks for that on its first frame, which is near-black, so the re-allocation (37 MB at 1620 lines) doesn't land on the dip in full view.

Scene 3 runs passes of its own too. It has three sun maps: one round the clearing and one round the beach, drawn once, and a third, drawn every frame, tight round the character on show. It marches its light shafts at quarter resolution into a target of its own, reading the scene's depth through mc_renderer_depth. It smooths them with mc_renderer_blur and hands them to the composite as mc_post.vol_tex. Its atmospheric sky and thin horizon wisps come from a 64x32 radiance table, also sampled by the sea and wet sand for their sky reflections. There are no cloud history targets, jungle dust particles or screen-space reflections of nearby objects in the current build. How it's put together and Light, in the making-of's Scene 3 section, have the details.

The scene targets run at an internal percentage of the output, from 25% to 200%, set with mc_renderer_set_scale (100% when the renderer is made). Presentation and the camera's aspect follow the renderer's output size, which mc_renderer_resize sets. The TAA resolves the internal-resolution samples into its output-size history or, above 100%, into one at the frame's size for the present to filter down. mc_renderer_end centres that output in the framebuffer it's handed, with opaque black around it when the framebuffer is larger.

The windowed main uses both the output size and the scale. Every frame it sizes the renderer to the largest 16:9 rectangle in the window (demo_fit, which the load's warm-up shares), such as 1920x1080 on a 1920x1200 or a 2560x1080 screen. Every shot is composed for 16:9, including the two trunks that frame the beach, so on a screen of another shape the picture is letterboxed or pillarboxed and the camera keeps its aspect.

The windowed main also supersamples by lines, not by a percentage. Scene 1 and the end card, the cheap frames, render 2160 lines, and Scenes 2 and 3 render

1. That's 200% and 150% of a 1080p picture, or 100% and 75% of a 4K one, so

a 4K screen gets the same frames instead of four times the work. It never goes past 200%, and a picture under 1080 lines gets the percentages a 1080-line one does. The scale switches on the near-black cuts at either side, and a resize starts the TAA's history over anyway.

MC_RENDER_SCALE fixes one percentage, 25-200, for the whole show, and 80 suits an integrated GPU. The headless main and tools/verify.py keep one size and scale throughout, 960x540 at 80% by default. The capture main renders 1920x1080 frames at one scale for the whole show (MC_CAP_SCALE, 200 by default, so every frame comes from 2160 lines). The GTAO and bloom sample counts are compile-time constants in their shaders.

The post shaders live in src/shaders/ and are baked into the generated mc_engine_shaders.h, which render.c includes, so they ship inside the engine instead of as loose files. In release they're minified together with the demo's shaders, and in dev they're kept verbatim (genshaders.py). The demo's scene shaders are separate (demos/hello-world/shaders/), because they belong to the demo, not the engine.

There are three mains, chosen at compile time. The windowed main runs the show in real time. In the release it's fullscreen with a 16:9 picture inside, and the screen is black from the moment the window opens, because one cleared frame is swapped in before the load. -DMC_HEADLESS swaps in a main that dumps a PNG for each key moment of the show, at 960x540, and quits. Only main.c reads that macro, and the engine never does, so a headless build also links the surfaceless backend.

-DMC_CAPTURE swaps in one that renders the whole show offline at 1920x1080 and 60 fps and streams raw RGBA frames to stdout, ready to pipe into ffmpeg. It renders every frame from 2160 lines unless MC_CAP_SCALE picks another percentage, 25-200, and MC_CAP_DUR can cut the show short. With MC_CAP_AUDIO it writes the soundtrack to a file instead. It's built headless, on the surfaceless backend. make capture builds it and records the show with it (tools/capture.sh, and the pipeline doc has the recipe).

The load is everything demo_make does before the show. It makes the renderer and the demo's 32³ noise volume, which the bakes and the seabed's placement read. Then it builds the procedural meshes and Scene 1's bodies and logo, compiles every shader, sculpts the animals and bakes Scene 2's materials. It places the seabed's props and makes Scene 3, with its baked tiles, the far forest's impostors and the tyrannosaurus. With a warm shader cache that takes about a second on a UHD 620. The load's last step is the warm-up below, and the music starts only after it.

A driver may finish building a program only at its first draw, and Mesa's Intel driver builds it again there if the target is of another kind (INTEL_DEBUG=perf logs "Recompiling fragment shader"). Other first uses cost time too, such as the glass's copy of the picture (66 MB at 4K inside) and the targets sized to the picture. Left to the show, those first uses would drop frames with a cold shader cache: at the show's first frame, at the bang, where the glass first goes into the key light's map, and under Scene 3's white.

So the windowed main's last step before the music, demo_warm, draws eight of the show's frames without showing them. It draws them at the sizes the show uses (demo_fit), at half bars 64, 72, 95, 105, 162, 227, 246 and 38, and in that order they cover:

• the planet and its moon (61.9 s);
• the dip: both seas, the waterline, the milky blob, its bubbles and the occlusion (69.7 s);
• the whale overhead (91.9 s);
• the reef: weed, fish, coral, boulders, their sun map, the jelly and the moon jellies (101.6 s);
• Scene 3's first light: the forest, its sun maps, the sky, the shafts, the birds and the ladybug (156.8 s);
• the tyrannosaurus, the beach and the sea (219.7 s);
• the blob ashore, its sun map and the depth of field (238.1 s);
• and Scene 1 last (36.8 s), which leaves the renderer at the size the show opens with.

A scan of that earlier version at 60 fps, with the GL calls instrumented, found 47 programs drawn in 56 pairings of program, kind of target and blending. Those counts predate the removal of the cloud, dust and reflection programs. The eight warm-up frames cover the scenes' different targets and blending. No two of the planet, the dip, the whale in view and the coral are ever on screen together, and the same goes for the birds, the tyrannosaurus and the blob's depth of field. The frame at 156.8 s also draws Scene 3's two still sun maps, which the show then keeps. They're drawn with the world as the show has it in the white's last half second, whichever frame draws them, so they are the show's own.

Afterwards, anything later frames read is put back as the load left it, so the show draws the same frames it would have drawn without the warm-up. That means the Frame block (Scene 1 sets only its own terms) and the boulders' detail levels, which have hysteresis. The TAA's history needs nothing. The show's first frame comes earlier in the clock than the last warm-up frame, and a step back in the clock starts the history over. A caller starting within a quarter second after 36.8 s would carry it on, but this main, the only caller, never does. The warm-up doesn't run Scene 1's collision sim, so the shapes it draws stand where they start. The audio, whose clock is the picture's, starts after the warm-up (mc_audio_start publishes t = 0), so the show still starts at 0 s with the music.

The warm-up adds about a second to the load with the cache warm, and 1.2-2.1 s cold. The show's first frame gives about 0.2 s of that back, because the renderer's targets already exist. With a cold cache no program is rebuilt during the show, and the four rebuilds Mesa still makes all happen in the load. On a UHD 620 with a cold cache, each event frame's excess over the median of its ten neighbours on either side (median of 3 runs) is -9 ms for the first frame and +15 ms for the bang. The frame under Scene 3's white that draws the still maps comes to +70 ms. The dip's +26-29 ms is its own cost (two seas and the copy), and the ladybug, the tyrannosaurus and the blob stay within 15 ms.

The windowed main reads the clock once a frame, at the top of its loop. With audio it's mc_audio_time(), the position of the sample that's being heard. After each write to ALSA, the audio thread takes the frames submitted so far, subtracts the delay the device reports, and publishes the result with a timestamp from the monotonic clock. mc_audio_time() adds the time since that stamp. It never runs past the audio already submitted and never goes backwards. It reads 0 until the device starts playing, which happens once its 100 ms buffer is full.

If ALSA won't open, or a write fails for good, the thread keeps rendering the song and throws it away, sleeping to absolute deadlines on the monotonic clock. The clock then runs at the pace the music would have played. If the synth can't be created at all, there's no audio thread, and the main falls back to the wall clock (mc_time_seconds() since the start).

The picture follows the sound, never the other way round. When a frame runs long, the next one jumps to where the music is, because a dropped frame is much easier to forgive than a stutter in the audio. Nothing else syncs the two: there are no cues passed between the threads, only the shared clock. The music starts after the load and its warm-up frames (see above), so show time 0 is the song's first sample.

The clock is monotonic and never wraps. The main clamps it at TOTAL_DUR and hands it to render_frame, which picks the scene. When the clock reaches the end, the release build exits, and the dev build stops the music once and holds on a black frame.

The other two mains have no audio clock. The capture main renders frame n at exactly n / 60 s, and writes the soundtrack separately (MC_CAP_AUDIO) from the same synth and seed, so the two line up exactly when they're muxed. The headless main renders a fixed list of show times.

The song is in 4/4 at 124 BPM throughout, so a bar (BAR_S, 240 / BPM) is 1.935 s. Each scene starts on the first bar of its music and lasts a whole number of bars:

render_frame hands each scene its local time, the show time minus the scene's start. Scene 1's cues are bars of the song. Its section starts, T_BANG, T_HOOKA, T_BREAK, T_HOOKB and T_OUTRO, are bars 4, 8, 12, 16 and 23. The moments of its story, such as T_LOGO_IN, T_COLLAPSE, T_BLACK and T_WINK, are offsets in seconds from those. The end card counts beats from its start. Scenes 2 and 3 are choreographed on clocks of their own, described below.

No hand-off shows a cut. Scene 1 is black round its seed by T_BLACK (49.2 s), and the seed, by then a star, ends where Scene 2's sun rises. Scene 2 burns out to white over its last 2.5 s (S2_END_FADE). Scene 3 holds the white for a bar (S3_J0) and opens out of it over 2.4 jungle seconds (S3_REVEAL). It fades to black over its last 2 s (S3_OUT). The end card fades up over its first beat and out over its last three, as the coda dies away.

The tempo and the song's layout are written down twice: for the picture in demos/hello-world/main.c and scene3.c, and for the music in src/synth.c. Neither is derived from the other, and nothing checks that they agree. If you change one, change the other to match, or the picture slides off the music from that point on.

In synth.c the S3_ and SCENE3 names belong to the third movement, Scene 2's finale, and not to the demo's Scene 3. The jungle's cues are counted there in bars of the song after BAR_WOODS, bar 81, where S3_J0 ends the white. So they include Scene 3's stretch and its hold.

The jungle's shaders can't see the C constants, so they carry their timing as literals. s3j0 in the shared block is one bar (1.9354839). The blob's shaders subtract the hold as 7.7419355, four bars, and the surf's phase has it as 6.9677419. Some cues are written as literal jungle seconds too, such as the tyrannosaurus's prints in ju_ground.frag. A new tempo or a moved cue has to be carried into the GLSL by hand. How to change the music itself is in The soundtrack.

Scenes 2 and 3 are each choreographed on a story clock of their own and played stretched. The story is counted in story bars, and the show gives some of its parts more bars of the song than the story has. A slow part, such as a look round or a ladybug's walk, plays a little slower and lasts longer, while the music keeps its tempo. stretch() in main.c does the conversion for both scenes.

Its table lists the parts in order as pairs: bars of the show, then bars of the story. A pair of 8 and 7 plays seven story bars over eight bars of the song, at 7/8 pace. A 0 ends the table, and the last pace holds on after it. stretch(y, seg) takes y, bars of the show since the act's origin, and returns bars of the story. unstretch() goes the other way, by bisection.

The pace never changes in a step. Each change is eased linearly over half a bar, from a quarter bar before the part's boundary to a quarter bar after it, and the story clock is the integral of that pace. So nothing on screen changes speed with a jolt. Outside that half bar, the clock is exactly the piecewise-linear one, which gives two guarantees:

• Each part starts on the bar of the song and the story bar its table gives, within 30 ms at the boundary itself.
• In a part played one for one, every bar line of the song is a bar line of the story, so whatever the story times to the beat lands on the music's beat.

Scene 2 runs on its local time until the breach. The underwater act, from S2_BREACH to the end of the scene, is choreographed on a story clock. uw_u(t) turns scene-local seconds into story seconds since the breach, and uw_t(u) turns them back. The blob's path, the scatter of the props, the predator, the cameras and every cue of the act (ENC_IN, PANIC_IN, TRANS_IN, FLIGHT_IN and the rest) are written in story seconds. The whole story is UW_SPAN, 104.5 story seconds, divided into 40 story bars of UW_BAR, 2.6125 s.

A story bar isn't the song's bar. It's 2.6125 story seconds long and plays over at least one bar of the song, 1.935 s. So even in a part played one for one, story seconds pass 1.35 times as fast as the show's. Treat a story time as a place in the act, not a length of time, and convert it with uw_t() before you compare it with the music.

The act's 44 bars of the song hold its 40 story bars. S2_SEG splits them into six parts, the first three at the music's section changes:

The stalk and the chase play one for one so that the heartbeat's kick stays on the near miss. ENC_PEAK, at 64 story seconds, lands at 122.9 s, on the third beat of bar 63.

Only the choreography is stretched. In Scene 2 the Frame block's uTime is scene-local seconds, so the water, the fish's swimming and everything else that simply moves runs at the show's own speed. The shaders that need the story, such as the reef bed and the big school, get uw_u() of the frame's time in a uniform.

Scene 3 is choreographed in jungle seconds, counted from the end of the white. Its cues, from S3_UP at 7 bars to S3_END at 54, are written as whole bars of BAR_S, so a jungle bar is as long as the song's bar.

render_scene3 stretches the time once, at its top. The scene-local time t becomes S3_J0 + BAR_S * stretch((t - S3_J0) / BAR_S, S3_SEG), and s3_setup sets c->j to that minus S3_J0. The Frame block's uTime gets the stretched time too, so every package and every jungle shader sees story time, and a shader gets jungle seconds as uTime - s3j0. The look round's pace applies before it as well, so during the white c->j runs from -1.69 to 0. The jungle is drawn under the white, unseen, from -0.5, the white's last 0.57 s.

S3_SEG stretches the forest. From the beach's hush on, the story runs one for one, four bars behind the song:

From bar 111 on, show time is SCENE3_START + S3_J0 + four bars + j, which is 164.516 s + j.

S3_HOLD is a pause written into the cues, not a stretch. As the tyrannosaurus turns away and resumes walking (S3_SHORE, 31 jungle bars), the camera stays crouched for four more bars. Every later cue is its bar plus S3_HOLD: S3_CLEAR, S3_BLOB, S3_END and the blob's first hop (JO_HOP0 in s3_blob.c). The blob's and the surf's shaders count their own cues from before the hold and subtract it as a literal. So a change to S3_HOLD moves Scene 3's length, the synth's later cues and those shaders, all together.

The making-of's timeline and its scene sections describe what happens on screen between these beats, and its soundtrack section what the music does.

The windowed dev build lets you take the clock over. SPACE pauses, LEFT and RIGHT jump 5 s back or forward, and UP and DOWN double or halve the speed, between 1/8 and 4 times. The first key press switches the picture from the audio clock to a manual timeline. It starts where the clock was, and then advances with the wall clock times the speed. Each press logs the new show time, the speed, and the name of the section the time falls in, from the SECTIONS[] table in main.c.

The music isn't moved. Once the transport has the clock, the song plays on from where it was, and the picture and the music part company. Use it to look at the picture, and judge the sync on a run you haven't touched. Seeking past the end stops the music, as reaching the end does, and it doesn't come back when you seek earlier.

Seeking backwards is safe for the picture. Scene 1's collision sim only runs forward, in fixed steps, so on a step back sim_seek reseeds it and replays it from the start to the new time. The transport is compiled only into the windowed dev build. The release, headless and capture builds have none of it, and the shipped file pays nothing for it.

Nothing the demo draws comes from a data file. Most of its geometry is grown in vertex shaders (see Building geometry out of arithmetic), and the load makes the rest on the GPU:

• The demo's 32³ noise volume comes first. It sits on unit 1's 3D binding for every scene, so the shaders' value noise is a single fetch.
• The creature kit (jr.comp) sculpts five animals: Scene 2's fish, crab, predator and whale, and Scene 3's tyrannosaurus. Each is a smooth union of round cones, ellipsoids and fins on a grid of its own (5 cm for the tyrannosaurus), meshed with surface nets. Each vertex is tagged with the two bones that hold it.
• The kit writes the meshes straight into GPU buffers: one vertex buffer for all five, bound for good on storage-buffer binding 5, and an index buffer each, whose triangle count is read back. jr.vert and fish.vert then pose and draw them as ordinary meshes. The kit takes about 60 ms of GPU time.
• uwplace.comp works out Scene 2's sand and boulder, then places every boulder, weed blade, coral head and crab, checking clearance against the blob, camera and predator paths and resolving conflicts between props. Each prop grows in where the camera can't see it. The current cell recipe shares its scatter rules; the 18 larger landmarks and all 21 placement passes remain. The earlier 64,365-byte version took about 155 ms for this work.
• Scene 3 bakes its bark, leaf and sand tiles, and an impostor atlas of four of its trees for the far forest. The warm-up also draws its two still sun maps, which the release build keeps. They always show the world at one frozen moment, half a jungle second before the jungle opens, whichever frame draws them.

The shaders name every texture unit with layout(binding = N), so no C code sets a sampler uniform. Scene 2 and Scene 3 have the details.