rgame 0.1.0

data/ext/rgame_core/graphics/recording.c

@@ -0,0 +1,119 @@
+/*
+ * recording.c — copying a prepared frame out of the queue and keeping it.
+ * See recording.h for what a recording is for and what it does not capture.
+ */
+
+#include "graphics/recording.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+void rgame_recording_destroy(rgame_recording *recording) {
+    if (!recording) {
+        return;
+    }
+
+    free(recording->vertices);
+    free(recording->batches);
+    /* Zeroed rather than merely freed, so a second destroy is a no-op and a
+     * replay after destroy draws nothing instead of reading freed memory. */
+    recording->vertices = NULL;
+    recording->batches = NULL;
+    recording->vertex_count = 0;
+    recording->batch_count = 0;
+}
+
+int rgame_recording_capture(rgame_recording *out, const rgame_draw_queue *queue) {
+    if (!out || !queue) {
+        return 0;
+    }
+
+    out->vertices = NULL;
+    out->batches = NULL;
+    out->vertex_count = 0;
+    out->batch_count = 0;
+
+    unsigned int batch_count = rgame_draw_queue_batch_count(queue);
+    unsigned int vertex_count = rgame_draw_queue_vertex_count(queue);
+    if (batch_count == 0 || vertex_count == 0) {
+        return 1; /* nothing was drawn; an empty recording is a valid one */
+    }
+
+    /* Exact allocations, not the queue's growth strategy: a recording is
+     * written once and read for the rest of the level, so the spare capacity
+     * that makes a per-frame queue cheap would just be a level-long leak. */
+    rgame_vertex *vertices = malloc(sizeof(rgame_vertex) * vertex_count);
+    rgame_recording_batch *batches = malloc(sizeof(rgame_recording_batch) * batch_count);
+    if (!vertices || !batches) {
+        free(vertices);
+        free(batches);
+        return 0;
+    }
+
+    memcpy(vertices, rgame_draw_queue_vertices(queue), sizeof(rgame_vertex) * vertex_count);
+
+    /*
+     * The queue's batches carry a clip as well; only the texture and the span
+     * come across. See recording.h — a clip recorded at one place on screen is
+     * wrong at every other place the recording is replayed.
+     */
+    for (unsigned int i = 0; i < batch_count; i++) {
+        const rgame_draw_batch *source = rgame_draw_queue_batch(queue, i);
+        batches[i].texture = source->texture;
+        batches[i].first_vertex = source->first_vertex;
+        batches[i].vertex_count = source->vertex_count;
+    }
+
+    out->vertices = vertices;
+    out->vertex_count = vertex_count;
+    out->batches = batches;
+    out->batch_count = batch_count;
+    return 1;
+}
+
+unsigned int rgame_recording_batch_count(const rgame_recording *recording) {
+    return recording ? recording->batch_count : 0;
+}
+
+unsigned int rgame_recording_vertex_count(const rgame_recording *recording) {
+    return recording ? recording->vertex_count : 0;
+}
+
+void rgame_recording_bounds(const rgame_recording *recording, float *min_x, float *min_y,
+                            float *max_x, float *max_y) {
+    float left = 0.0f, top = 0.0f, right = 0.0f, bottom = 0.0f;
+
+    if (recording && recording->vertex_count > 0) {
+        left = right = recording->vertices[0].x;
+        top = bottom = recording->vertices[0].y;
+
+        for (unsigned int i = 1; i < recording->vertex_count; i++) {
+            const rgame_vertex *vertex = &recording->vertices[i];
+            if (vertex->x < left) {
+                left = vertex->x;
+            }
+            if (vertex->x > right) {
+                right = vertex->x;
+            }
+            if (vertex->y < top) {
+                top = vertex->y;
+            }
+            if (vertex->y > bottom) {
+                bottom = vertex->y;
+            }
+        }
+    }
+
+    if (min_x) {
+        *min_x = left;
+    }
+    if (min_y) {
+        *min_y = top;
+    }
+    if (max_x) {
+        *max_x = right;
+    }
+    if (max_y) {
+        *max_y = bottom;
+    }
+}

data/ext/rgame_core/graphics/recording.h

@@ -0,0 +1,88 @@
+#ifndef RGAME_RECORDING_H
+#define RGAME_RECORDING_H
+
+#include "graphics/draw_queue.h"
+
+/*
+ * A baked block of drawing, kept between frames and replayed as a few calls.
+ *
+ * The problem it solves is the tile map. A screen of 16px tiles is a couple of
+ * thousand quads, and while the batching queue already merges them into one GL
+ * call, the *CPU* still walks every tile, transforms four corners and appends a
+ * command — sixty times a second, for a layer that has not changed since the
+ * level loaded.
+ *
+ * A recording captures that work once. What comes out is the finished vertex
+ * array, already sorted and grouped by texture, so replaying it is one command
+ * per texture instead of one per tile:
+ *
+ *     bake once      2000 tiles -> 2000 commands -> 1 batch
+ *     replay         1 command  -> 1 batch, every frame
+ *
+ * ---------------------------------------------------------------------------
+ * What is captured, and what is not
+ * ---------------------------------------------------------------------------
+ *
+ * Positions and texture coordinates are baked. Transforms *inside* the recorded
+ * block are baked with them — a rotated sprite records its rotated corners —
+ * and the transform in effect at *replay* time is applied on top, which is what
+ * lets a baked layer scroll under a camera.
+ *
+ * Clips are not captured at all: a batch carries a texture and a span of
+ * vertices, and nothing else. Clipping happens at rasterisation, so it cannot
+ * be baked into a vertex, and a clip rectangle recorded in one place would be
+ * wrong everywhere the recording is later replayed. Pushing a clip inside a
+ * recorded block is therefore refused rather than silently dropped; clip the
+ * *replay* instead, which does exactly what the caller meant.
+ *
+ * Colours are baked, but a replay may tint them — multiplying each recorded
+ * component by the tint's. The layer being replaced could not do this (its
+ * recorded images drew white-only, and callers worked around it); there is no
+ * reason to inherit the limitation.
+ */
+
+/* A run of recorded vertices sharing one texture — one GL call's worth. */
+typedef struct {
+    unsigned int texture; /* 0 means untextured */
+    unsigned int first_vertex, vertex_count;
+} rgame_recording_batch;
+
+/* Tagged so the public header can forward-declare the same type without
+ * seeing what is in it — src/main.c and the Ruby binding only ever hold a
+ * pointer. */
+typedef struct rgame_recording {
+    rgame_vertex *vertices; /* in painter order, grouped by batch */
+    unsigned int vertex_count;
+
+    rgame_recording_batch *batches;
+    unsigned int batch_count;
+} rgame_recording;
+
+/*
+ * Copies a *prepared* draw queue into `out`, which must be uninitialised or
+ * already destroyed. Returns 1 on success, 0 if out of memory — in which case
+ * `out` is left empty and is still safe to destroy.
+ *
+ * "Prepared" means rgame_draw_queue_prepare has run: the sorting and grouping
+ * is exactly the work being saved, so a recording captures its result rather
+ * than the raw command list.
+ *
+ * An empty queue records successfully and replays as nothing.
+ */
+int rgame_recording_capture(rgame_recording *out, const rgame_draw_queue *queue);
+
+/* Frees the buffers. Safe on a zeroed struct, and safe to call twice. */
+void rgame_recording_destroy(rgame_recording *recording);
+
+unsigned int rgame_recording_batch_count(const rgame_recording *recording);
+unsigned int rgame_recording_vertex_count(const rgame_recording *recording);
+
+/*
+ * The bounding box of everything recorded, in the recording's own coordinates.
+ * Zero-sized for an empty recording. Games use it to decide whether a baked
+ * layer is on screen at all before replaying it.
+ */
+void rgame_recording_bounds(const rgame_recording *recording, float *min_x, float *min_y,
+                            float *max_x, float *max_y);
+
+#endif /* RGAME_RECORDING_H */

data/ext/rgame_core/graphics/texture.c

@@ -0,0 +1,181 @@
+/*
+ * texture.c — sheet refcounting, sub-rectangle composition, pixel-to-UV.
+ * See texture.h for what the two structs are and why the refcount lives here.
+ */
+
+#include "graphics/texture.h"
+
+#include <stdlib.h>
+
+/* See rgame_texture_live_sheets in the header for why this exists. */
+static long live_sheets = 0;
+
+long rgame_texture_live_sheets(void) {
+    return live_sheets;
+}
+
+rgame_texture_sheet *rgame_texture_sheet_create(unsigned int name, int width, int height) {
+    if (width <= 0 || height <= 0) {
+        return NULL;
+    }
+
+    rgame_texture_sheet *sheet = malloc(sizeof(rgame_texture_sheet));
+    if (!sheet) {
+        return NULL;
+    }
+
+    sheet->name = name;
+    sheet->width = width;
+    sheet->height = height;
+    sheet->refs = 1;
+    live_sheets++;
+    return sheet;
+}
+
+void rgame_texture_sheet_retain(rgame_texture_sheet *sheet) {
+    if (sheet) {
+        sheet->refs++;
+    }
+}
+
+int rgame_texture_sheet_release(rgame_texture_sheet *sheet, unsigned int *out_name) {
+    if (!sheet) {
+        return 0;
+    }
+
+    if (--sheet->refs > 0) {
+        return 0;
+    }
+
+    /* Read the name out before freeing — after free(sheet) it is gone, and
+     * reading it back is the classic use-after-free this ordering avoids. */
+    unsigned int name = sheet->name;
+    free(sheet);
+    live_sheets--;
+    if (out_name) {
+        *out_name = name;
+    }
+    return 1;
+}
+
+rgame_texture rgame_texture_whole(rgame_texture_sheet *sheet) {
+    rgame_texture view = {0};
+    if (!sheet) {
+        return view;
+    }
+
+    rgame_texture_sheet_retain(sheet);
+    view.sheet = sheet;
+    view.rect = rgame_rect_make(0, 0, sheet->width, sheet->height);
+    return view;
+}
+
+int rgame_texture_destroy(rgame_texture *view, unsigned int *out_name) {
+    if (!view || !view->sheet) {
+        return 0;
+    }
+
+    int died = rgame_texture_sheet_release(view->sheet, out_name);
+    /* Clearing the pointer makes a second destroy a no-op rather than a double
+     * free. Ruby's GC and an explicit close can both reach the same view. */
+    view->sheet = NULL;
+    view->rect = rgame_rect_make(0, 0, 0, 0);
+    return died;
+}
+
+rgame_texture rgame_texture_clone(const rgame_texture *view) {
+    rgame_texture copy = {0};
+    if (!view || !view->sheet) {
+        return copy;
+    }
+
+    rgame_texture_sheet_retain(view->sheet);
+    copy = *view;
+    return copy;
+}
+
+int rgame_texture_subimage(const rgame_texture *view, int x, int y, int w, int h,
+                           rgame_texture *out) {
+    if (!view || !view->sheet || !out || w <= 0 || h <= 0 || x < 0 || y < 0) {
+        return 0;
+    }
+
+    /* Compared against the *view's* size, not the sheet's: a sub-rect is
+     * relative to what it is being cut from, so a tile of a tile can never
+     * wander outside the tile it came from. */
+    if (x + w > view->rect.w || y + h > view->rect.h) {
+        return 0;
+    }
+
+    rgame_texture_sheet_retain(view->sheet);
+    out->sheet = view->sheet;
+    out->rect = rgame_rect_make(view->rect.x + x, view->rect.y + y, w, h);
+    return 1;
+}
+
+unsigned int rgame_texture_name(const rgame_texture *view) {
+    return view && view->sheet ? view->sheet->name : 0;
+}
+
+int rgame_texture_width(const rgame_texture *view) {
+    return view && view->sheet ? view->rect.w : 0;
+}
+
+int rgame_texture_height(const rgame_texture *view) {
+    return view && view->sheet ? view->rect.h : 0;
+}
+
+int rgame_texture_tile_count(const rgame_texture *view, int tile_width, int tile_height) {
+    if (!view || !view->sheet || tile_width <= 0 || tile_height <= 0) {
+        return 0;
+    }
+
+    return (view->rect.w / tile_width) * (view->rect.h / tile_height);
+}
+
+int rgame_texture_tile(const rgame_texture *view, int tile_width, int tile_height, int index,
+                       rgame_texture *out) {
+    /* `index < 0` is redundant today and deliberately kept: a negative index
+     * yields negative offsets, which rgame_texture_subimage refuses anyway, so
+     * mutating it away survives the suite. Half a range check is still the
+     * wrong thing to read at the place the range is computed. */
+    if (index < 0 || index >= rgame_texture_tile_count(view, tile_width, tile_height)) {
+        return 0;
+    }
+
+    int columns = view->rect.w / tile_width;
+    return rgame_texture_subimage(view, (index % columns) * tile_width,
+                                  (index / columns) * tile_height, tile_width, tile_height, out);
+}
+
+void rgame_texture_uv(const rgame_texture *view, float *uv8) {
+    if (!uv8) {
+        return;
+    }
+
+    /* A view with no sheet has no pixels to sample; hand back a degenerate
+     * 0,0 square rather than dividing by a zero sheet size. */
+    if (!view || !view->sheet) {
+        for (int i = 0; i < 8; i++) {
+            uv8[i] = 0.0f;
+        }
+        return;
+    }
+
+    /* Normalise against the *sheet*: UVs address the whole uploaded texture,
+     * so a 16px tile in a 512px sheet spans 1/32 of the coordinate space, not
+     * all of it. Dividing by the view size instead is the mistake this
+     * function exists to make impossible to repeat. */
+    float sheet_w = (float)view->sheet->width;
+    float sheet_h = (float)view->sheet->height;
+
+    float u0 = (float)view->rect.x / sheet_w;
+    float v0 = (float)view->rect.y / sheet_h;
+    float u1 = (float)(view->rect.x + view->rect.w) / sheet_w;
+    float v1 = (float)(view->rect.y + view->rect.h) / sheet_h;
+
+    uv8[0] = u0; uv8[1] = v0; /* top-left */
+    uv8[2] = u1; uv8[3] = v0; /* top-right */
+    uv8[4] = u1; uv8[5] = v1; /* bottom-right */
+    uv8[6] = u0; uv8[7] = v1; /* bottom-left */
+}

data/ext/rgame_core/graphics/texture.h

@@ -0,0 +1,165 @@
+#ifndef RGAME_TEXTURE_H
+#define RGAME_TEXTURE_H
+
+#include "graphics/clip.h"
+
+/*
+ * Textures: what part of an uploaded image a draw call should sample, and who
+ * owns the upload. Pure arithmetic and pure bookkeeping — no GL, no stb, no
+ * I/O. The decode-and-upload half lives in image.c, which is deliberately as
+ * dumb as it can be (CLAUDE.md's layer 3).
+ *
+ * ---------------------------------------------------------------------------
+ * Two structs, because there are two lifetimes
+ * ---------------------------------------------------------------------------
+ *
+ * A sprite sheet is decoded and uploaded to the GPU *once*, and then sliced
+ * into dozens of sprites. Each of those sprites is an ordinary object a game
+ * holds, drops and garbage-collects on its own schedule — but the pixels
+ * behind them are one shared allocation on the GPU.
+ *
+ * So:
+ *
+ *   rgame_texture_sheet   one GL texture. Reference-counted, heap-allocated,
+ *                         shared by every view into it.
+ *   rgame_texture         a *view*: a sheet plus the sub-rectangle of it this
+ *                         particular sprite occupies. Small, copyable, holds
+ *                         one reference to its sheet.
+ *
+ * `subimage` therefore costs a rectangle intersection and a refcount bump —
+ * no second decode and no second upload. Slicing a 512x512 sheet into 1024
+ * tiles produces 1024 views over one texture.
+ *
+ * ---------------------------------------------------------------------------
+ * Why the refcount is here and not in image.c
+ * ---------------------------------------------------------------------------
+ *
+ * "Free the GPU texture exactly when the last sprite using it goes away" is
+ * the kind of rule that is wrong in one branch and leaks for a year. It is
+ * also, written out, pure integer bookkeeping — nothing about it needs a GPU.
+ * So it lives here, where `test/test_texture.c` can drop views in every order
+ * and assert the sheet dies once and only once.
+ *
+ * The one thing this module cannot do is call `glDeleteTextures`. Instead
+ * `rgame_texture_sheet_release` *reports* that the last reference went away
+ * and hands back the GL name it was holding; the caller in image.c does the
+ * one-line deletion. That keeps the decision here and the syscall there.
+ *
+ * ---------------------------------------------------------------------------
+ * Pixels in, UVs out
+ * ---------------------------------------------------------------------------
+ *
+ * Callers talk in pixels — "the tile at 32,16, sixteen by sixteen" — because
+ * that is how sprite sheets are drawn and described. OpenGL samples in
+ * normalised texture coordinates, 0..1 across the whole texture. Converting
+ * between them is one division that is easy to get subtly wrong (by the sheet
+ * size, not the view size), so it happens in exactly one place:
+ * `rgame_texture_uv`.
+ */
+
+typedef struct {
+    /* The GL texture name. Opaque here: this module never calls GL, it only
+     * carries the number so that release can hand it back for deletion. */
+    unsigned int name;
+    int width, height; /* the whole uploaded image, in pixels */
+    int refs;
+} rgame_texture_sheet;
+
+typedef struct {
+    rgame_texture_sheet *sheet;
+    /* The part of the sheet this view samples, in sheet pixels. */
+    rgame_rect rect;
+} rgame_texture;
+
+/*
+ * Creates a sheet with one reference, or NULL if out of memory or given a
+ * degenerate size. `name` is whatever the GL layer allocated; this module
+ * treats it as an opaque token, so tests can pass any number they like.
+ */
+rgame_texture_sheet *rgame_texture_sheet_create(unsigned int name, int width, int height);
+
+void rgame_texture_sheet_retain(rgame_texture_sheet *sheet);
+
+/*
+ * Drops one reference. Returns 1 if that was the last one — in which case the
+ * sheet has been freed and `*out_name` holds the GL name the caller must now
+ * delete — and 0 if others remain (`*out_name` untouched).
+ *
+ * Returning the name rather than deleting it is what keeps this file free of
+ * GL. `out_name` may not be NULL when the caller intends to honour the
+ * deletion; passing NULL is allowed and simply discards it, which is what the
+ * tests that only care about lifetimes do.
+ */
+int rgame_texture_sheet_release(rgame_texture_sheet *sheet, unsigned int *out_name);
+
+/*
+ * A view covering the whole sheet, retaining it. Every view — this one
+ * included — must eventually be passed to rgame_texture_destroy.
+ */
+rgame_texture rgame_texture_whole(rgame_texture_sheet *sheet);
+
+/* Drops this view's reference. Same return contract as sheet_release, so a
+ * caller can delete the GL texture when the last view goes. */
+int rgame_texture_destroy(rgame_texture *view, unsigned int *out_name);
+
+/* An independent view of the same region — retains the sheet. */
+rgame_texture rgame_texture_clone(const rgame_texture *view);
+
+/*
+ * A sub-rectangle of `view`, in coordinates *relative to that view* — so
+ * slicing a slice composes without the caller tracking absolute offsets.
+ *
+ * Returns 1 on success. Returns 0, leaving `*out` untouched, if the rect is
+ * degenerate or reaches outside the view: garbage UVs sample a neighbouring
+ * sprite, which looks like a drawing bug rather than the indexing bug it is,
+ * so this refuses instead of clamping.
+ */
+int rgame_texture_subimage(const rgame_texture *view, int x, int y, int w, int h,
+                           rgame_texture *out);
+
+/* The GL texture name to bind when drawing this view, or 0 if it has no sheet
+ * — which the draw queue reads as "untextured". */
+unsigned int rgame_texture_name(const rgame_texture *view);
+
+int rgame_texture_width(const rgame_texture *view);
+int rgame_texture_height(const rgame_texture *view);
+
+/*
+ * How many whole `tile_width` x `tile_height` tiles fit, row-major. A partial
+ * tile at the right or bottom edge is not counted — a sheet whose size is not
+ * a multiple of the tile size has a strip of padding, and half a sprite is
+ * never what was meant. Zero or negative tile sizes yield 0.
+ */
+int rgame_texture_tile_count(const rgame_texture *view, int tile_width, int tile_height);
+
+/* The `index`-th tile, counting left to right then top to bottom. Returns 1 on
+ * success, 0 if the index is outside the count above. */
+int rgame_texture_tile(const rgame_texture *view, int tile_width, int tile_height, int index,
+                       rgame_texture *out);
+
+/*
+ * The view's four corners in normalised texture coordinates, written to `uv8`
+ * as x,y pairs in the same corner order the canvas takes a quad's points:
+ * top-left, top-right, bottom-right, bottom-left.
+ *
+ * v runs downwards, matching the pixel rect and the screen: image row 0 is
+ * v = 0. That holds because image.c uploads the decoded rows in the order stb
+ * produces them (top row first), rather than flipping them the way a
+ * bottom-left-origin convention would need.
+ */
+void rgame_texture_uv(const rgame_texture *view, float *uv8);
+
+/*
+ * How many sheets are alive right now — for tests, not for gameplay.
+ *
+ * A leaked GPU texture is invisible: the game runs, the frame rate is fine,
+ * and video memory fills up over an hour of play. This counter makes "the
+ * texture went away when the last sprite using it did" an assertion, both in
+ * the Check suite and from Ruby, where the collector chooses the order in
+ * which an app and its images are swept.
+ *
+ * Single-threaded, like the rest of the engine.
+ */
+long rgame_texture_live_sheets(void);
+
+#endif /* RGAME_TEXTURE_H */

data/ext/rgame_core/graphics/transform.c

@@ -0,0 +1,128 @@
+#include "graphics/transform.h"
+
+#include <math.h>
+
+/* Degrees in, radians out — the C library's trig wants radians, the API takes
+ * degrees because that is what callers already pass. */
+#define RGAME_DEGREES_TO_RADIANS (3.14159265358979323846f / 180.0f)
+
+/* Tolerance for "is this the identity". Composing and un-composing transforms
+ * accumulates float error, so an exact == would answer "no" for a stack that is
+ * identity in every way that matters. */
+#define RGAME_IDENTITY_EPSILON 1e-6f
+
+rgame_transform rgame_transform_identity(void) {
+    rgame_transform t = { .a = 1.0f, .b = 0.0f, .c = 0.0f, .d = 1.0f, .tx = 0.0f, .ty = 0.0f };
+    return t;
+}
+
+rgame_transform rgame_transform_multiply(rgame_transform outer, rgame_transform inner) {
+    /*
+     * Substituting inner's output into outer's formula and collecting terms:
+     *
+     *   x' = outer.a*(inner.a*x + inner.c*y + inner.tx)
+     *      + outer.c*(inner.b*x + inner.d*y + inner.ty) + outer.tx
+     *
+     * and likewise for y'. Written out rather than looped, because six named
+     * multiplies read better than a 2x3 loop and this is the hot path.
+     */
+    rgame_transform result;
+    result.a = (outer.a * inner.a) + (outer.c * inner.b);
+    result.b = (outer.b * inner.a) + (outer.d * inner.b);
+    result.c = (outer.a * inner.c) + (outer.c * inner.d);
+    result.d = (outer.b * inner.c) + (outer.d * inner.d);
+    result.tx = (outer.a * inner.tx) + (outer.c * inner.ty) + outer.tx;
+    result.ty = (outer.b * inner.tx) + (outer.d * inner.ty) + outer.ty;
+    return result;
+}
+
+void rgame_transform_stack_init(rgame_transform_stack *stack) {
+    stack->depth = 0;
+    stack->entries[0] = rgame_transform_identity();
+}
+
+/* Shared tail of the three pushes: compose with the current top, store, and
+ * report whether there was room. */
+static int push_composed(rgame_transform_stack *stack, rgame_transform step) {
+    if (stack->depth + 1 >= RGAME_TRANSFORM_STACK_DEPTH) {
+        return 0;
+    }
+    stack->entries[stack->depth + 1] =
+        rgame_transform_multiply(stack->entries[stack->depth], step);
+    stack->depth++;
+    return 1;
+}
+
+int rgame_transform_push_translate(rgame_transform_stack *stack, float dx, float dy) {
+    rgame_transform step = rgame_transform_identity();
+    step.tx = dx;
+    step.ty = dy;
+    return push_composed(stack, step);
+}
+
+int rgame_transform_push_scale(rgame_transform_stack *stack, float sx, float sy) {
+    rgame_transform step = rgame_transform_identity();
+    step.a = sx;
+    step.d = sy;
+    return push_composed(stack, step);
+}
+
+int rgame_transform_push_rotate(rgame_transform_stack *stack, float degrees,
+                                float pivot_x, float pivot_y) {
+    float radians = degrees * RGAME_DEGREES_TO_RADIANS;
+    float cosine = cosf(radians);
+    float sine = sinf(radians);
+
+    /*
+     * Rotating about a pivot is three steps: move the pivot to the origin,
+     * rotate, move it back. Composed here rather than pushed as three entries,
+     * so one push still matches one pop.
+     *
+     * The rotation itself is the textbook matrix. In screen space, where y
+     * points down, it turns *clockwise* for a positive angle — see the header.
+     */
+    rgame_transform rotation = { .a = cosine, .b = sine, .c = -sine, .d = cosine,
+                                 .tx = 0.0f, .ty = 0.0f };
+
+    rgame_transform to_origin = rgame_transform_identity();
+    to_origin.tx = -pivot_x;
+    to_origin.ty = -pivot_y;
+
+    rgame_transform back = rgame_transform_identity();
+    back.tx = pivot_x;
+    back.ty = pivot_y;
+
+    rgame_transform step =
+        rgame_transform_multiply(back, rgame_transform_multiply(rotation, to_origin));
+    return push_composed(stack, step);
+}
+
+void rgame_transform_pop(rgame_transform_stack *stack) {
+    if (stack->depth > 0) {
+        stack->depth--;
+    }
+}
+
+rgame_transform rgame_transform_current(const rgame_transform_stack *stack) {
+    return stack->entries[stack->depth];
+}
+
+int rgame_transform_depth(const rgame_transform_stack *stack) {
+    return stack->depth;
+}
+
+void rgame_transform_apply(const rgame_transform_stack *stack, float x, float y,
+                           float *out_x, float *out_y) {
+    const rgame_transform *t = &stack->entries[stack->depth];
+    *out_x = (t->a * x) + (t->c * y) + t->tx;
+    *out_y = (t->b * x) + (t->d * y) + t->ty;
+}
+
+int rgame_transform_is_identity(const rgame_transform_stack *stack) {
+    const rgame_transform *t = &stack->entries[stack->depth];
+    return fabsf(t->a - 1.0f) < RGAME_IDENTITY_EPSILON &&
+           fabsf(t->b) < RGAME_IDENTITY_EPSILON &&
+           fabsf(t->c) < RGAME_IDENTITY_EPSILON &&
+           fabsf(t->d - 1.0f) < RGAME_IDENTITY_EPSILON &&
+           fabsf(t->tx) < RGAME_IDENTITY_EPSILON && fabsf(t->ty) < RGAME_IDENTITY_EPSILON;
+}