The MICROCOSM toolkit: API reference
The public mc_ API, module by module

The engine is a set of small C modules, all with the mc_ prefix, and each has its own header in include/microcosm/. Structs are plain value types, passed and returned by value where that's cheap. The modules that allocate have an explicit _free.

Every frame runs the same sequence:

mc_renderer_frame(R, t);                      // TAA: this frame's time
mc_m4 vp = mc_renderer_camera(R, proj, view); // proj * view, jittered for the TAA
mc_renderer_begin(R, clear_rgb);              // bind the HDR scene target, clear
/* ... upload your frame block, bind shaders, set uniforms, draw ... */
mc_renderer_end(R, mc_window_output_fbo(win), w, h, post); // post stack -> output
mc_window_swap(win);

The internals explain how the modules depend on each other, why the engine links no GL library, how the two platform backends differ and what the renderer does between begin and end.

• Coordinates are right-handed. mc_m4_look_at builds a view in which the camera looks down -Z, with +X to the right and +Y up, so everything in front of the camera has a negative view-space z.
• Matrices are column-major and multiply column vectors, as in GLSL: proj * view * model * p.
• Front faces wind counter-clockwise, and mc_renderer_begin culls back faces.
• Angles are in radians, including mc_camera's fovy.
• mc_m4_perspective and mc_m4_ortho produce GL's clip space, with depth running from -1 at the near plane to +1 at the far plane. The engine keeps GL's default depth range, so the depth buffer holds 0 at the near plane and 1 at the far plane.

• mc_renderer_depth is a 24-bit depth texture (GL_DEPTH_COMPONENT24, nearest filtering) of that depth, which isn't linear: most of its precision sits close to the camera. To turn a sample into a distance along the view axis, undo the projection with the camera's near and far planes, as src/shaders/ao_blur.frag does:

  float view_depth(float d, float zn, float zf) {   // d: a depth-texture sample
      float z = d * 2.0 - 1.0;                       // back to GL's [-1, 1]
      return 2.0 * zn * zf / (zf + zn - z * (zf - zn));
  }
  

• Texture and window coordinates follow GL, with (0, 0) at the bottom left. tiny64's uv runs from (0, 0) at the bottom left to (1, 1) at the top right. Only the read-back (mc_window_read_pixels, mc_window_save_png) turns rows around so that the top row comes first.
• The code is C11 with GNU extensions, and the Makefile builds it with -std=gnu11. Strict -std=c11 hides the POSIX declarations that the platform and audio code need, such as clock_gettime, so src/platform_common.c and src/audio.c fail to compile under it.

Everything after this section is the real engine API. A full intro needs that much control, but it's more than you want when all you're after is a fragment shader on the screen. For that there's include/microcosm/tiny64.h, a header-only wrapper around the platform and the renderer, and with it an animated single-shader demo in a window takes about ten lines. Define TINY64_IMPL in exactly one translation unit to compile the implementation there, and include the header without it everywhere else.

#define TINY64_IMPL
#include <microcosm/tiny64.h>

int main(void) {
    t64_open(1280, 720, "demo");
    t64_shader("#version 450 core\n"
               "in vec2 uv; out vec4 o; uniform float t;"
               "void main(){ o = vec4(uv, 0.5+0.5*sin(t), 1.0); }");
    while (t64_running()) {
        t64_set1f("t", (float)t64_time());
        t64_quad();
        t64_swap();
    }
    t64_close();
}

The fragment shader gets in vec2 uv in [0,1], with (0, 0) at the bottom left, and you pass in everything else as uniforms. If a recompile fails, the previous program stays, so a typo never blanks the screen. Define TINY64_SHORT_NAMES before the include to also get the bare names running(), swap(), shader(), fullscreen_quad() and uniform1f(). They're off by default because they can clash with names in ordinary code. There's no bare time(), which would clash with <time.h>, so use t64_time() for that.

tiny64 has no HDR, mesh or post path. When you need those, use mc_render.h directly instead. tiny64 is only the engine with the setup hidden, so there's nothing to unpick when you move off it.

tiny64 is for windowed and dev builds, and it can't be packed into the 64k payload. The payload's compile (MC_IMPORT_HASH) doesn't declare mc_uniform, mc_set_f or mc_set_v3, which the uniform setters call, or mc_window_close, which t64_close calls, so the implementation doesn't compile there. A demo that's going to be packed uses the full API and sets its uniforms by layout(location). The tutorial shows how to build a tiny64 program.

mc.h has the common types and macros. Every other header includes it.

Integer type aliases

typedef uint8_t  mc_u8;
typedef uint32_t mc_u32;
typedef int32_t  mc_i32;
typedef uint64_t mc_u64;

Scalar constants

#define MC_PI      3.14159265358979323846f
#define MC_TAU     6.28318530717958647692f
#define MC_DEG2RAD (MC_PI / 180.0f)
#define MC_RAD2DEG (180.0f / MC_PI)

Utility macros

Logging and asserts (mc_log and mc_assert compile to nothing in release)

Teardown

MC_TIDY(...) wraps the cleanup a program does before it returns or exits, after a failed start or at the end of a run. In every build but one it expands to the statements as written, inside a do { } while (0). In the packed payload (MC_IMPORT_HASH) it's ((void)0), because the process ends right after and the OS releases everything.

mc_window_close, mc_audio_stop and mc_mesh_gpu_free are declared only outside the payload, and so is mc_gl_context_release. In code that goes into the payload, every call to them must sit inside MC_TIDY(...), or the payload doesn't compile. Code that never goes into it, such as a headless main(), can call them directly.

if (!d) { MC_TIDY(mc_window_close(w)); return 1; }   // a failed start
/* ... the show ... */
MC_TIDY(if (audio) mc_audio_stop(audio); mc_synth_free(synth); mc_window_close(w));

Vectors and matrices are plain value types. Matrices are 4x4 and column-major in m[16], which is the OpenGL layout, so element (row r, col c) is m[c*4 + r]. Angles are in radians unless the name says otherwise.

Types

typedef struct { float x, y; }       mc_v2;
typedef struct { float x, y, z; }    mc_v3;
typedef struct { float x, y, z, w; } mc_v4;
typedef struct { float m[16]; }      mc_m4;   /* column-major */
typedef struct { float x, y, z, w; } mc_quat; /* (x,y,z,w), w is the scalar */

Constructors

mc_v2 mc_vec2(float x, float y);
mc_v3 mc_vec3(float x, float y, float z);
mc_v4 mc_vec4(float x, float y, float z, float w);
mc_v3 mc_v3_splat(float s);               // {s, s, s}

Scalar helpers

float mc_absf(float x);
float mc_signf(float x);                   // -1 / 0 / +1
float mc_minf(float a, float b);
float mc_maxf(float a, float b);
float mc_clampf(float x, float lo, float hi);
float mc_saturatef(float x);               // clamp to [0,1]
float mc_lerpf(float a, float b, float t);
float mc_fractf(float x);                  // x - floor(x)
float mc_modf_pos(float x, float m);       // positive modulo
float mc_smoothstepf(float e0, float e1, float x);
float mc_radians(float deg);
float mc_degrees(float rad);
float mc_remapf(float x, float a0, float a1, float b0, float b1);

vec2 / vec3 / vec4

mc_v2 mc_v2_add(mc_v2 a, mc_v2 b);
mc_v2 mc_v2_sub(mc_v2 a, mc_v2 b);
mc_v2 mc_v2_scale(mc_v2 a, float s);
float mc_v2_dot(mc_v2 a, mc_v2 b);
float mc_v2_len(mc_v2 a);
mc_v2 mc_v2_normalize(mc_v2 a);

mc_v3 mc_v3_add(mc_v3 a, mc_v3 b);
mc_v3 mc_v3_sub(mc_v3 a, mc_v3 b);
mc_v3 mc_v3_mul(mc_v3 a, mc_v3 b);         // component-wise
mc_v3 mc_v3_scale(mc_v3 a, float s);
mc_v3 mc_v3_neg(mc_v3 a);
float mc_v3_dot(mc_v3 a, mc_v3 b);
mc_v3 mc_v3_cross(mc_v3 a, mc_v3 b);
float mc_v3_len(mc_v3 a);
float mc_v3_len2(mc_v3 a);                  // squared length
float mc_v3_dist(mc_v3 a, mc_v3 b);
mc_v3 mc_v3_mad(mc_v3 a, mc_v3 b, float s); // a + b * s
mc_v3 mc_v3_dir(mc_v3 a, mc_v3 b);         // normalize(a - b): from b towards a
mc_v3 mc_v3_normalize(mc_v3 a);            // safe: {0,0,0} if ~zero
mc_v3 mc_v3_lerp(mc_v3 a, mc_v3 b, float t);
mc_v3 mc_v3_min(mc_v3 a, mc_v3 b);
mc_v3 mc_v3_max(mc_v3 a, mc_v3 b);
mc_v3 mc_v3_abs(mc_v3 a);
mc_v3 mc_v3_reflect(mc_v3 i, mc_v3 n);
mc_v3 mc_v3_clamp(mc_v3 v, float lo, float hi);

mc_v4 mc_v4_add(mc_v4 a, mc_v4 b);
mc_v4 mc_v4_scale(mc_v4 a, float s);
float mc_v4_dot(mc_v4 a, mc_v4 b);

mc_v3_mad is the step you take most often: mc_v3_mad(p, v, dt) moves p along v for dt. mc_v3_dir(a, b) is the unit vector that points from b towards a, so mc_v3_dir(target, eye) is a camera's forward direction. Like mc_v3_normalize, it returns the zero vector when the two points coincide.

mat4

mc_m4 mc_m4_identity(void);
mc_m4 mc_m4_mul(mc_m4 a, mc_m4 b);         // a * b
mc_m4 mc_m4_transpose(mc_m4 a);
mc_m4 mc_m4_inverse(mc_m4 a);              // general inverse (identity if singular)
mc_m4 mc_m4_translate(mc_v3 t);
mc_m4 mc_m4_scale(mc_v3 s);
mc_m4 mc_m4_scale1(float s);
mc_m4 mc_m4_rotate(mc_v3 axis, float angle);
mc_m4 mc_m4_from_quat(mc_quat q);
mc_m4 mc_m4_trs(mc_v3 t, mc_quat r, mc_v3 s);  // translate * rotate * scale
mc_m4 mc_m4_look_at(mc_v3 eye, mc_v3 center, mc_v3 up);
mc_m4 mc_m4_perspective(float fovy, float aspect, float znear, float zfar);
mc_m4 mc_m4_ortho(float l, float r, float b, float t, float n, float f);
mc_v4 mc_m4_mul_v4(mc_m4 a, mc_v4 v);
mc_v3 mc_m4_transform_point(mc_m4 a, mc_v3 p);  // w-divides
mc_v3 mc_m4_transform_dir(mc_m4 a, mc_v3 d);    // ignores translation

Quaternions ((x,y,z,w), w scalar)

mc_quat mc_quat_identity(void);
mc_quat mc_quat_axis_angle(mc_v3 axis, float angle);
mc_quat mc_quat_euler(float x, float y, float z);   // radians, XYZ order
mc_quat mc_quat_mul(mc_quat a, mc_quat b);
mc_quat mc_quat_normalize(mc_quat q);
mc_quat mc_quat_slerp(mc_quat a, mc_quat b, float t);
mc_v3   mc_quat_rotate(mc_quat q, mc_v3 v);

Hash & deterministic PRNG

mc_u32 mc_hash_u32(mc_u32 x);
mc_u32 mc_hash2(mc_u32 x, mc_u32 y);

typedef struct { mc_u32 s; } mc_rng;       // user-held state
mc_rng mc_rng_seed(mc_u32 seed);
mc_u32 mc_rng_next(mc_rng *r);
float  mc_rng_f(mc_rng *r);                 // [0,1)
float  mc_rng_range(mc_rng *r, float lo, float hi);
mc_v3  mc_rng_unit_v3(mc_rng *r);          // uniform point on the unit sphere

The PRNG is a 32-bit xorshift whose state lives in mc_rng, and a seed of 0 is replaced by a fixed non-zero constant. It's deterministic, so procedural content comes out the same from frame to frame and on every machine.

Noise (value/fBm in [-1,1])

float mc_noise2(float x, float y);
float mc_noise3(float x, float y, float z);
float mc_fbm2(float x, float y, int octaves, float lacunarity, float gain);
float mc_fbm3(mc_v3 p, int octaves, float lacunarity, float gain);
mc_v3 mc_curl3(mc_v3 p);                    // divergence-free flow direction

Easing

typedef enum {
    MC_EASE_LINEAR = 0,
    MC_EASE_IN_QUAD, MC_EASE_OUT_QUAD, MC_EASE_INOUT_QUAD,
    MC_EASE_IN_CUBIC, MC_EASE_OUT_CUBIC, MC_EASE_INOUT_CUBIC,
    MC_EASE_OUT_BACK, MC_EASE_OUT_ELASTIC, MC_EASE_OUT_BOUNCE,
    MC_EASE_INOUT_SINE,
    MC_EASE_COUNT
} mc_ease_kind;

float mc_ease(mc_ease_kind kind, float t);  // t is clamped to [0,1]

Splines

mc_v3 mc_catmull_rom(mc_v3 p0, mc_v3 p1, mc_v3 p2, mc_v3 p3, float t);
mc_v3 mc_bezier3(mc_v3 p0, mc_v3 p1, mc_v3 p2, mc_v3 p3, float t);
// Sample a Catmull-Rom path through n control points at u in [0,1].
// loop != 0 wraps the path; otherwise the endpoints are duplicated.
mc_v3 mc_spline_sample(const mc_v3 *pts, int n, float u, int loop);

// example: a looping camera path
static const mc_v3 path[] = { /* ... control points ... */ };
mc_v3 p = mc_spline_sample(path, MC_ARRAY_COUNT(path), mc_fractf(t / DUR), 1);

MICROCOSM doesn't link libGL. Every OpenGL entry point is resolved at runtime into one table, mcgl, and each of the usual gl* names is a #define into that table. Call sites read like ordinary OpenGL, but the binary imports no GL symbols.

One X-macro list, MC_GL_FUNCS(X), names every entry point once, as X(Name, PFN type) where Name is the GL name without its gl. The list generates both the typed members of mc_gl_api and the loader's NUL-separated name blob, and mc_gl_load fills the table in one loop over the union's slot[] array. Adding a function takes one line in the list plus its #define.

The list holds only what the engine and the reference demo call, so some entries serve a single job. glDrawArraysInstanced draws geometry grown from vertex ids with no vertex buffer, glUniform4fv uploads the jungle's placement tables, and glClearDepth and glScissor clear a patch of the cached sun map. glDispatchCompute and glMemoryBarrier run the compute shaders that sculpt the animals and place the seabed, and glGetBufferSubData reads back their triangle counts and the placed props. The sampler calls let one depth map be read both with comparison and raw. glCopyTexSubImage2D takes the jelly's copy of the picture, and glTexImage3D makes the shaders' noise volume.

A second list, MC_GL_TOOLS(X), holds the calls that are left out of the payload (MC_IMPORT_HASH), so using one there by mistake fails to compile. First come the calls only the tools need: info logs, renderbuffers, glFinish, glGetError, glGetString, glReadPixels and glPixelStorei. The list also has uniform lookup by name with the float and vec3 setters (glGetUniformLocation, glUniform1f, glUniform3f) and the teardown the payload skips (glDeleteShader, glDeleteVertexArrays). The non-instanced glDrawElements is there too, because the engine draws every mesh through the instanced calls. The split is enforced the other way as well: the payload's link fails if MC_GL_FUNCS holds an entry point the payload never calls (tools/importcheck.py). A demo that needs one of the tools' calls in its payload moves that line up into MC_GL_FUNCS. mcgl1 is an alias of mcgl, which some of the checks use.

<GL/gl.h> and <GL/glext.h> are included only for the GLenum=/=GLuint types, the GL_* enum values, and the PFNGL*PROC typedefs. GL_GLEXT_PROTOTYPES is never defined, so no GL symbol is referenced at link time.

extern mc_gl_api mcgl;

typedef void (*mc_gl_proc)(void);
// Resolve all entry points; returns 1 on success, 0 if any are missing.
// `getproc` is eglGetProcAddress, passed in so this file needs no EGL.
int mc_gl_load(mc_gl_proc (*getproc)(const char *name));

// Shared per-context objects: an empty VAO for full-screen passes, and the
// per-frame std140 uniform block on binding point 0 (re-upload between draws
// freely; every program's blocks start on binding 0 after each link).
GLuint mc_gl_fullscreen_vao(void);
void   mc_gl_frame_block(const void *data, GLsizeiptr bytes);
void   mc_gl_context_release(void);   // the platform calls this for you (not in the payload)

You don't normally call mc_gl_load yourself. The platform backend calls it right after it makes the context current, and from then on you can call glClear, glEnable, glDrawArrays and the rest directly.

There's one per-frame block, and the engine shares it with you. mc_renderer_end uploads the post stack's own data to it, so after end, binding 0 holds that instead of your block. Upload yours each frame before the first draw that reads it, and again after any pass that changes it, such as a shadow pass drawn from the light.

OpenGL 4.5 core was picked over Vulkan or D3D12 to save size, because the GL driver carries functionality that would otherwise end up in your binary. Every context is 4.5 core, and every shader starts with #version 450 core. The pipeline doc gives the full argument.

Dev-only error check

#if defined(MC_DEV)
void mc_gl_check_(const char *where);
#define MC_GL_CHECK() mc_gl_check_(__func__)   // logs any pending GL error
#else
#define MC_GL_CHECK() ((void)0)
#endif

This is one API with two backends, and you link one of them (see Headless rendering below). Opening a window makes a GL 4.5 core context current and loads the GL table.

Types

typedef struct mc_window mc_window;

typedef struct {
    int         width;
    int         height;
    const char *title;
    int         vsync;       // 1: swaps wait for the display; 0: they don't
    int         fullscreen;  // 0: a window; 1: the screen's size, the EWMH
                             // fullscreen hint, a blank pointer
} mc_window_desc;

Both flags are plain switches, so a zeroed desc means no vsync and no fullscreen. Set .vsync = 1 for a real-time window. The headless backend ignores both.

Lifecycle

mc_window *mc_window_open(const mc_window_desc *desc);  // NULL on failure
void       mc_window_close(mc_window *w);   // not in the payload: call it inside MC_TIDY

With fullscreen set, the windowed backend ignores width and height and creates the window at the screen's size from the first frame. It also sets the _NET_WM_STATE_FULLSCREEN hint but doesn't rely on it, so fullscreen works on a server with no window manager to honour the hint. The pointer is hidden by giving the cursor an empty 1x1 bitmap for its picture and mask. If a window manager resizes the window anyway, that's handled like any other resize, through mc_window_size. The headless backend has no screen and ignores the flag.

mc_window_close, mc_audio_stop, mc_mesh_gpu_free and mc_gl_context_release aren't declared in the payload's compile (MC_IMPORT_HASH). The payload never tears anything down, so the imports and GL entry points these calls would need are left out too. Call them inside MC_TIDY(...) (see mc.h).

Per-frame

int    mc_window_pump(mc_window *w);   // process events; 0 => quit (closed or ESC)
void   mc_window_swap(mc_window *w);   // present (swap buffers; glFinish when headless)
void   mc_window_size(mc_window *w, int *width, int *height);
GLuint mc_window_output_fbo(mc_window *w); // 0 on-screen; a readable RGBA8 FBO headless

Time

double mc_time_seconds(void);          // monotonic seconds since first call

Input

typedef enum {
    MC_KEY_ESCAPE = 0, MC_KEY_SPACE,
    MC_KEY_LEFT, MC_KEY_RIGHT, MC_KEY_UP, MC_KEY_DOWN,
    MC_KEY_COUNT
} mc_key;
int mc_key_down(mc_window *w, mc_key key);

On the windowed backend, pressing ESC also makes the next mc_window_pump return 0. The headless backend reports no keys and never asks to quit.

Headless read-back

// Read the output framebuffer as tightly-packed top-left-origin RGBA8.
// `rgba` must hold width*height*4 bytes. Returns 1 on success. Not in the payload.
int mc_window_read_pixels(mc_window *w, unsigned char *rgba);
// Save the output framebuffer as a PNG (dev builds only; no-op in release).
int mc_window_save_png(mc_window *w, const char *path);

GL's rows start at the bottom left. Both backends flip them into image rows that start at the top left, so saved PNGs are upright. mc_window_save_png writes a lossless RGBA PNG with uncompressed DEFLATE blocks. The files are large, but the writer is simple to get right, and it only runs in dev builds.

// opening a window
mc_window_desc desc = { .width = 1280, .height = 720,
                        .title = "demo", .vsync = 1 };
mc_window *w = mc_window_open(&desc);
if (!w) return 1;

mc_mesh.h builds meshes on the CPU. A mesh is an indexed triangle list of interleaved (position, normal, uv) vertices, held in heap arrays that grow as needed. Build meshes once at startup, upload them to the GPU (mc_mesh_upload, in mc_render.h), then free the CPU copy. Triangles wind counter-clockwise seen from outside, normals point outwards, and primitives are centred at the origin.

Types

typedef struct { mc_v3 pos; mc_v3 normal; mc_v2 uv; } mc_vertex;

typedef struct {
    mc_vertex *verts;  int vert_count;  int vert_cap;
    mc_u32    *indices; int index_count; int index_cap;  // 3 per face
} mc_mesh;

Low-level build

mc_mesh mc_mesh_new(void);
void    mc_mesh_free(mc_mesh *m);          // frees arrays, zeroes the struct
int     mc_mesh_push_vertex(mc_mesh *m, mc_v3 pos, mc_v3 normal);  // returns index
void    mc_mesh_push_tri(mc_mesh *m, mc_u32 a, mc_u32 b, mc_u32 c);
void    mc_mesh_recompute_normals(mc_mesh *m);  // area-weighted, smooth
void    mc_mesh_append(mc_mesh *dst, const mc_mesh *src, mc_m4 xform);
void    mc_mesh_grid(mc_mesh *m, int base, int rows, int cols);  // stitch a vertex grid

mc_mesh_append keeps the source's UVs. Its normals are only correct for a rigid transform or a positive uniform scale, so for a non-uniform scale, apply mc_mesh_scale to the source first. Subdivision interpolates UVs, so keep seam vertices separate.

mc_mesh_grid is the one stitcher behind every lofted or swept surface, such as the torus and the cylinder wall. Push a row-major block of (rows+1) x (cols+1) vertices, with vertex (i,j) at base + i*(cols+1) + j, then call it once. Each cell becomes the two triangles (i,j) (i,j+1) (i+1,j) and (i,j+1) (i+1,j+1) (i+1,j). They face front when (i,j), (i,j+1), (i+1,j) run counter-clockwise seen from outside. A strip of (bottom, top) vertex pairs is just cols = 1. The reference demo calls nothing in mc_mesh.h. It grows its shapes in vertex shaders from gl_VertexID over the same two-triangle cells, and it sculpts its animals and works out its seabed and boulders on the GPU.

Primitives (all centred at the origin, all return an owned mesh)

mc_mesh mc_mesh_box(mc_v3 half_extents);
mc_mesh mc_mesh_plane(float size, int subdivisions);            // XZ plane, +Y normal
mc_mesh mc_mesh_uv_sphere(float radius, int slices, int stacks);
mc_mesh mc_mesh_icosphere(float radius, int subdivisions);
mc_mesh mc_mesh_torus(float major_r, float minor_r, int major_seg, int minor_seg);
mc_mesh mc_mesh_cylinder(float radius, float height, int segments, int caps);
mc_mesh mc_mesh_cone(float radius, float height, int segments);
mc_mesh mc_mesh_rounded_box(mc_v3 half_extents, float round, int subdivisions);
mc_mesh mc_mesh_terrain(float size, int subdivisions, float amp, mc_u32 seed);
mc_mesh mc_mesh_torus_knot(float scale, float tube, int p, int q,
                           int curve_seg, int tube_sides);

Notes on behaviour (from src/mesh.c):

• mc_mesh_box is six flat faces, each its own grid (add_cube_faces), and each face can be subdivided for the rounded-box path.
• mc_mesh_icosphere starts from a 12-vertex icosahedron, applies mc_mesh_subdivide subdivisions times, then projects every vertex onto the sphere, so each normal is the normalised position.
• mc_mesh_cylinder's caps is a flag (nonzero adds top and bottom caps).
• mc_mesh_rounded_box clamps round to [0,1]. The shape is the Minkowski sum of an inner box and a sphere of radius round * min(half_extents), so flat faces stay flat and the edges and corners are rounded. With round == 1 it degenerates to a sphere of radius min(half_extents).
• mc_mesh_terrain raises an XZ plane (subdivisions cells per side) by fBm of amplitude amp, shaped with a smootherstep so valleys come out flat and ridges stay sharp, and then recomputes the normals. This is the shape of Scene 2's seabed. The demo computes the same terrain on the GPU (uwplace.comp), and the checks keep the two in agreement.
• mc_mesh_torus_knot sweeps a round tube of radius tube along the (p,q) knot curve, with curve_seg samples along the curve and tube_sides around each cross-section. The normal is the tube's radial direction, so it's correct without recomputing. The terrain and the knot are both textured by triplanar projection, so they carry no UVs.
• Resolution parameters are floored to safe minimums. A sphere, for example, clamps to slices >= 3 and stacks >= 2.

Modifiers (in place)

void mc_mesh_subdivide(mc_mesh *m, int iterations);     // split each tri into 4, welded
void mc_mesh_displace_noise(mc_mesh *m, float amount, float frequency, mc_u32 seed);
void mc_mesh_spherify(mc_mesh *m, float radius, float t);  // blend toward a sphere, t in [0,1]
void mc_mesh_scale(mc_mesh *m, mc_v3 s);                 // scales positions; fixes normals

mc_mesh_subdivide caches midpoints in a hash, so shared edges split the same way and the mesh stays welded. mc_mesh_displace_noise pushes vertices along their normals by amount * fbm, and mc_mesh_spherify blends toward a sphere. Both recompute the normals afterwards. mc_mesh_scale transforms normals by the inverse transpose of the diagonal scale, which is exact under non-uniform scale and keeps hard edges.

// build an organic blob and hand it to the GPU
mc_mesh m = mc_mesh_icosphere(1.0f, 3);
mc_mesh_displace_noise(&m, 0.15f, 1.5f, 0xBEEFu);
mc_gpu_mesh gpu = mc_mesh_upload(&m);   // mc_render.h
mc_mesh_free(&m);                        // CPU copy no longer needed

The renderer owns the HDR scene target and the fixed post shaders. The lower-level helpers for shaders, GPU meshes and render targets are public, so you can draw whatever you like between begin and end.

Small, allocation-free helpers that turn time into camera matrices and animated values.

Camera

typedef struct {
    mc_v3 pos; mc_v3 target; mc_v3 up;
    float fovy;   // radians
    float znear; float zfar;
} mc_camera;

mc_camera mc_camera_default(void);
mc_m4     mc_camera_view(const mc_camera *c);
mc_m4     mc_camera_proj(const mc_camera *c, float aspect);

mc_camera_default puts the eye at (0, 1.5, 6) looking at the origin with +Y up, with a 55° fovy, the near plane at 0.05 and the far plane at 200. mc_camera_view is mc_m4_look_at and mc_camera_proj is mc_m4_perspective with the camera's own values. Pass mc_renderer_aspect(R) as the aspect, and give the post stack the same camera (see Post-processing).

Frustum culling

typedef struct { mc_v4 plane[6]; } mc_frustum;
mc_frustum mc_frustum_make(mc_m4 view_proj);
int mc_frustum_sphere(const mc_frustum *f, mc_v3 center, float radius);

mc_frustum_make takes the six planes of a view-projection matrix's clip volume: left, right, bottom, top, near and far, for GL's -w..w range. Each plane is normalised, so a point's distance from it comes out in world units. mc_frustum_sphere returns 0 when the sphere is wholly outside one of the planes, and 1 otherwise. The test is conservative: a sphere just off a corner of the frustum can still pass, but a visible one never fails. The demo culls both against the camera and against the sun's view, to keep shadow casters that are off screen.

mc_frustum fr = mc_frustum_make(vp);          // once per frame, per camera
if (mc_frustum_sphere(&fr, pos, gpu.radius * scale))
    mc_mesh_draw(gpu);

Keyframe tracks (keys sorted by .t, and .ease selects the curve into that key)

typedef struct { float t; float v; int ease; } mc_key_f;
typedef struct { float t; mc_v3 v; int ease; } mc_key_v3;

float mc_track_f (const mc_key_f  *keys, int n, float t);
mc_v3 mc_track_v3(const mc_key_v3 *keys, int n, float t);

.ease is an mc_ease_kind value. A track can have any number of keys, and when several keys share a timestamp, the last one wins. Outside the keys' range the value is clamped, and seeking backwards works.

Timeline & beat helpers

typedef struct {
    double t;         // current time in seconds
    double duration;  // total length in seconds
    double bpm;       // beats per minute
} mc_timeline;

double mc_beats(const mc_timeline *tl);                        // t, in beats
float  mc_beat_pulse(const mc_timeline *tl, float sharpness);  // 0..1, peaks each beat
int    mc_window_active(const mc_timeline *tl, double start, double len);  // 1 if inside
float  mc_window_phase(const mc_timeline *tl, double start, double len);   // 0..1, clamped

mc_beat_pulse returns a (1-phase)^sharpness falloff from each beat, which suits anything that should bounce on the beat. mc_window_active and mc_window_phase switch scene sections on and off by the clock and give each one a 0..1 phase.

mc_timeline tl = { .t = t, .duration = DUR, .bpm = 124.0 };
float bounce = mc_beat_pulse(&tl, 5.0f);          // snappy per-beat pulse
if (mc_window_active(&tl, 15.48, 7.74)) { /* only during "hook A", bars 8-12 */ }

A software synth that uses no samples, and a real-time backend that runs it on its own thread. The demo syncs its visuals to mc_audio_time(), a monotonic estimate of the playback position: the frames submitted so far minus the ALSA device delay. Between updates it interpolates, but only while playback is running, and never past the submitted position.

#define MC_SAMPLE_RATE 44100
#define MC_CHANNELS    2

Synth

typedef struct mc_synth mc_synth;

mc_synth *mc_synth_make(mc_u32 seed);  // seed perturbs incidental detail only
void      mc_synth_free(mc_synth *s);
// Render `frames` interleaved stereo frames (2*frames floats) in [-1,1].
// Advances internal time. Real-time safe: no allocation, no I/O.
void      mc_synth_render(mc_synth *s, float *out, int frames);
double    mc_synth_bpm(const mc_synth *s);
double    mc_synth_length(const mc_synth *s);   // song length in seconds

The song is fixed: mc_synth_bpm returns 124 and mc_synth_length about 278.7 s, and the song doesn't loop. seed varies only incidental detail, so a given seed always renders the same piece. The soundtrack describes the music and how to change it.

Backend

// Pull callback: fill `out` with `frames` interleaved stereo frames.
// Called from the audio thread; must be real-time safe.
typedef void (*mc_audio_cb)(float *out, int frames, void *user);

typedef struct mc_audio mc_audio;

mc_audio *mc_audio_start(mc_audio_cb cb, void *user);  // spawns the thread; NULL on failure
void      mc_audio_stop(mc_audio *a);  // not in the payload: call it inside MC_TIDY
double    mc_audio_time(mc_audio *a);  // monotonic playback estimate; see fallback limitations below

The backend tries ALSA directly: FLOAT_LE, 44100 Hz, stereo, set up with one snd_pcm_set_params call that asks for a 100 ms buffer in four periods. ALSA resamples if the device runs at another rate. If that fails, the backend falls back to a silent sink that paces the callback in real time, so the clock still advances. mc_audio_time is guarded by a mutex and safe to read from the render thread. Pending samples survive short writes, retryable errors and ALSA's underrun recovery, and a new synth block is only generated once the pending one has been consumed. ALSA writes are nonblocking and every wait is bounded. There is no fallback to a subprocess or a pipe. The silent sink sleeps until absolute monotonic deadlines, so the sleeps don't drift block by block. Each 1024-frame wait is about 23.2 ms. Shutdown needs your audio callback to return promptly, since the engine can't put a time limit on a callback that blocks.

static void audio_pull(float *out, int frames, void *user) {
    mc_synth_render((mc_synth *)user, out, frames);
}

mc_synth *synth = mc_synth_make(0x1234u);
mc_audio *audio = mc_audio_start(audio_pull, synth);  // may be NULL; fall back to a clock
/* ... */
double t = audio ? mc_audio_time(audio) : (mc_time_seconds() - start);
/* ... */
MC_TIDY(if (audio) mc_audio_stop(audio); mc_synth_free(synth));