rgame 0.1.0

data/ext/rgame_core/graphics/backend.c

@@ -0,0 +1,52 @@
+#include "graphics/backend.h"
+
+void rgame_draw_submit(const rgame_draw_queue *queue, const rgame_draw_backend *backend,
+                       int width, int height) {
+    if (!queue || !backend) {
+        return;
+    }
+
+    if (backend->begin_frame) {
+        backend->begin_frame(backend->ctx, width, height);
+    }
+
+    /*
+     * Track the clip actually in force rather than assuming each batch needs a
+     * fresh one. `have_clip` distinguishes "no clip set yet" from "the current
+     * clip happens to equal the zero rect", which a plain comparison against a
+     * zeroed variable could not.
+     *
+     * No batch can currently carry the zero rect — an empty clip makes the
+     * queue drop the command before it ever becomes a batch — so the flag is
+     * unreachable today, and a test cannot distinguish it. It is kept because
+     * the invariant that saves it lives in *another* module: if the queue ever
+     * stopped dropping empty-clipped commands, the first batch of a frame would
+     * silently go unscissored.
+     */
+    rgame_rect current_clip = { 0, 0, 0, 0 };
+    int have_clip = 0;
+
+    const rgame_vertex *vertices = rgame_draw_queue_vertices(queue);
+    unsigned int batches = rgame_draw_queue_batch_count(queue);
+
+    for (unsigned int i = 0; i < batches; i++) {
+        const rgame_draw_batch *batch = rgame_draw_queue_batch(queue, i);
+
+        if (!have_clip || !rgame_rect_equals(current_clip, batch->clip)) {
+            if (backend->set_clip) {
+                backend->set_clip(backend->ctx, batch->clip);
+            }
+            current_clip = batch->clip;
+            have_clip = 1;
+        }
+
+        if (backend->draw_batch) {
+            backend->draw_batch(backend->ctx, batch->texture, &vertices[batch->first_vertex],
+                                batch->vertex_count);
+        }
+    }
+
+    if (backend->end_frame) {
+        backend->end_frame(backend->ctx);
+    }
+}

data/ext/rgame_core/graphics/backend.h

@@ -0,0 +1,64 @@
+#ifndef RGAME_BACKEND_H
+#define RGAME_BACKEND_H
+
+#include "graphics/clip.h"
+#include "graphics/draw_queue.h"
+
+/*
+ * The drawing backend seam — "layer 2" in CLAUDE.md's abstraction strategy.
+ *
+ * Everything up to here is arithmetic: the canvas positions vertices, the queue
+ * sorts and batches them. This is where that stops and real GL calls begin, so
+ * this is where the function-pointer table goes — added at the point real calls
+ * appear rather than speculatively ahead of it.
+ *
+ * Two implementations exist by design: the real one that talks to OpenGL, and a
+ * recording one the Check suite substitutes to assert that the right primitive
+ * calls happened in the right order, with no display anywhere in sight.
+ *
+ * ---------------------------------------------------------------------------
+ * What the seam is *not* for
+ * ---------------------------------------------------------------------------
+ *
+ * It is not how the queue and canvas get tested. Those hand back their prepared
+ * batches directly and are exercised without any backend at all, which keeps
+ * the dependency one-directional: draw_queue and canvas do not include this
+ * header. What is genuinely worth a fake is the submit loop below — the small
+ * amount of logic that sits between a prepared frame and the GPU.
+ */
+
+/*
+ * Every member may be NULL, in which case that call is skipped. `ctx` is the
+ * implementation's own state, passed back to each function.
+ *
+ * Fixed arity throughout, like the app callbacks: a variadic convention on a
+ * per-frame path marshals arguments for no benefit.
+ */
+typedef struct {
+    void (*begin_frame)(void *ctx, int width, int height);
+    void (*set_clip)(void *ctx, rgame_rect clip);
+    void (*draw_batch)(void *ctx, unsigned int texture, const rgame_vertex *vertices,
+                       unsigned int count);
+    void (*end_frame)(void *ctx);
+    void *ctx;
+} rgame_draw_backend;
+
+/*
+ * Walks a *prepared* queue and drives the backend:
+ *
+ *     begin_frame
+ *       set_clip / draw_batch ... (per batch, clip only when it changes)
+ *     end_frame
+ *
+ * `set_clip` is issued only when the rectangle actually differs from the last
+ * one set. Batches split on either texture or clip, so two adjacent batches
+ * often share a clip and differ only in texture — re-issuing an identical
+ * scissor for each would be a wasted state change every frame.
+ *
+ * begin_frame and end_frame are called even for an empty queue: the real
+ * backend still has to clear and present the frame.
+ */
+void rgame_draw_submit(const rgame_draw_queue *queue, const rgame_draw_backend *backend,
+                       int width, int height);
+
+#endif /* RGAME_BACKEND_H */

data/ext/rgame_core/graphics/canvas.c

@@ -0,0 +1,247 @@
+#include "graphics/canvas.h"
+
+#include <math.h>
+
+/* What a recorded push has to undo. */
+enum {
+    RGAME_PUSH_TRANSFORM,
+    RGAME_PUSH_CLIP,
+    /* The underlying stack was full. Nothing to undo, but it still occupies a
+     * slot so that the caller's matching pop stays paired with this push. */
+    RGAME_PUSH_NOTHING
+};
+
+void rgame_canvas_init(rgame_canvas *canvas) {
+    rgame_draw_queue_init(&canvas->queue);
+    rgame_transform_stack_init(&canvas->transforms);
+    rgame_clip_stack_init(&canvas->clips, 0, 0);
+    canvas->push_depth = 0;
+    canvas->unrecorded_pushes = 0;
+    canvas->width = 0;
+    canvas->height = 0;
+}
+
+void rgame_canvas_destroy(rgame_canvas *canvas) {
+    rgame_draw_queue_destroy(&canvas->queue);
+}
+
+void rgame_canvas_begin_frame(rgame_canvas *canvas, int width, int height) {
+    rgame_draw_queue_reset(&canvas->queue);
+    rgame_transform_stack_init(&canvas->transforms);
+    rgame_clip_stack_init(&canvas->clips, width, height);
+    canvas->push_depth = 0;
+    canvas->unrecorded_pushes = 0;
+    canvas->width = width;
+    canvas->height = height;
+}
+
+void rgame_canvas_end_frame(rgame_canvas *canvas) {
+    rgame_draw_queue_prepare(&canvas->queue);
+}
+
+/* Records what a successful push has to undo. Returns 0 when there is no room
+ * to record it, in which case the caller counts it as unrecorded instead. */
+static int record_push(rgame_canvas *canvas, unsigned char kind) {
+    if (canvas->push_depth >= RGAME_CANVAS_STACK_DEPTH) {
+        return 0;
+    }
+    canvas->pushes[canvas->push_depth++] = kind;
+    return 1;
+}
+
+/*
+ * Shared tail of every push: if the underlying stack accepted it, remember
+ * which one to undo; otherwise remember that there is nothing to undo. Either
+ * way a push is accounted for, so pop always has something to consume.
+ */
+static void account_push(rgame_canvas *canvas, int accepted, unsigned char kind) {
+    if (!record_push(canvas, accepted ? kind : RGAME_PUSH_NOTHING)) {
+        canvas->unrecorded_pushes++;
+    }
+}
+
+void rgame_canvas_push_translate(rgame_canvas *canvas, float dx, float dy) {
+    int ok = rgame_transform_push_translate(&canvas->transforms, dx, dy);
+    account_push(canvas, ok, RGAME_PUSH_TRANSFORM);
+}
+
+void rgame_canvas_push_rotate(rgame_canvas *canvas, float degrees, float pivot_x,
+                              float pivot_y) {
+    int ok = rgame_transform_push_rotate(&canvas->transforms, degrees, pivot_x, pivot_y);
+    account_push(canvas, ok, RGAME_PUSH_TRANSFORM);
+}
+
+void rgame_canvas_push_scale(rgame_canvas *canvas, float sx, float sy) {
+    int ok = rgame_transform_push_scale(&canvas->transforms, sx, sy);
+    account_push(canvas, ok, RGAME_PUSH_TRANSFORM);
+}
+
+/*
+ * Maps a rect through the current transform and takes the axis-aligned bounding
+ * box of the result.
+ *
+ * All four corners are mapped, not just two: under rotation the box is decided
+ * by whichever corners happen to be extreme, and under a mirroring scale the
+ * "top-left" corner is no longer top-left. Bounds are rounded outwards so a
+ * partially covered pixel is kept rather than clipped away.
+ */
+static rgame_rect transformed_bounds(const rgame_canvas *canvas, rgame_rect rect) {
+    float corners[4][2] = { { (float)rect.x, (float)rect.y },
+                            { (float)(rect.x + rect.w), (float)rect.y },
+                            { (float)(rect.x + rect.w), (float)(rect.y + rect.h) },
+                            { (float)rect.x, (float)(rect.y + rect.h) } };
+
+    float min_x = 0.0f, min_y = 0.0f, max_x = 0.0f, max_y = 0.0f;
+    for (int i = 0; i < 4; i++) {
+        float x, y;
+        rgame_transform_apply(&canvas->transforms, corners[i][0], corners[i][1], &x, &y);
+        if (i == 0) {
+            min_x = max_x = x;
+            min_y = max_y = y;
+            continue;
+        }
+        if (x < min_x) {
+            min_x = x;
+        }
+        if (x > max_x) {
+            max_x = x;
+        }
+        if (y < min_y) {
+            min_y = y;
+        }
+        if (y > max_y) {
+            max_y = y;
+        }
+    }
+
+    int left = (int)floorf(min_x);
+    int top = (int)floorf(min_y);
+    int right = (int)ceilf(max_x);
+    int bottom = (int)ceilf(max_y);
+    return rgame_rect_make(left, top, right - left, bottom - top);
+}
+
+void rgame_canvas_push_clip(rgame_canvas *canvas, rgame_rect rect) {
+    int ok = rgame_clip_push(&canvas->clips, transformed_bounds(canvas, rect));
+    account_push(canvas, ok, RGAME_PUSH_CLIP);
+}
+
+void rgame_canvas_pop(rgame_canvas *canvas) {
+    /* Unrecorded pushes unwind first: they are the most recent ones, since a
+     * push is only left unrecorded once the record stack is already full. */
+    if (canvas->unrecorded_pushes > 0) {
+        canvas->unrecorded_pushes--;
+        return;
+    }
+    if (canvas->push_depth == 0) {
+        return; /* unbalanced pop; harmless */
+    }
+
+    switch (canvas->pushes[--canvas->push_depth]) {
+    case RGAME_PUSH_TRANSFORM:
+        rgame_transform_pop(&canvas->transforms);
+        break;
+    case RGAME_PUSH_CLIP:
+        rgame_clip_pop(&canvas->clips);
+        break;
+    default:
+        break; /* RGAME_PUSH_NOTHING: the push never took effect */
+    }
+}
+
+/* Fills one vertex: map the point into screen space, copy through the texture
+ * coordinate, and write the colour as the four bytes GL reads. */
+static void write_vertex(const rgame_canvas *canvas, rgame_vertex *vertex, float x, float y,
+                         float u, float v, rgame_color color) {
+    rgame_transform_apply(&canvas->transforms, x, y, &vertex->x, &vertex->y);
+    vertex->u = u;
+    vertex->v = v;
+    rgame_color_bytes(color, vertex->rgba);
+}
+
+void rgame_canvas_triangle(rgame_canvas *canvas, const float *xy6, rgame_color color,
+                           double z) {
+    rgame_vertex *out = rgame_draw_queue_alloc(&canvas->queue, 3, z, 0,
+                                               rgame_clip_current(&canvas->clips));
+    for (int i = 0; i < 3; i++) {
+        write_vertex(canvas, &out[i], xy6[i * 2], xy6[(i * 2) + 1], 0.0f, 0.0f, color);
+    }
+}
+
+/* Corner indices for the two triangles a quad becomes. */
+static const int RGAME_QUAD_TRIANGLES[6] = { 0, 1, 2, 0, 2, 3 };
+
+void rgame_canvas_quad(rgame_canvas *canvas, const float *xy8, rgame_color color, double z) {
+    rgame_vertex *out = rgame_draw_queue_alloc(&canvas->queue, 6, z, 0,
+                                               rgame_clip_current(&canvas->clips));
+    for (int i = 0; i < 6; i++) {
+        int corner = RGAME_QUAD_TRIANGLES[i];
+        write_vertex(canvas, &out[i], xy8[corner * 2], xy8[(corner * 2) + 1], 0.0f, 0.0f,
+                     color);
+    }
+}
+
+void rgame_canvas_textured_quad(rgame_canvas *canvas, unsigned int texture, const float *xy8,
+                                const float *uv8, rgame_color color, double z) {
+    rgame_vertex *out = rgame_draw_queue_alloc(&canvas->queue, 6, z, texture,
+                                               rgame_clip_current(&canvas->clips));
+    for (int i = 0; i < 6; i++) {
+        int corner = RGAME_QUAD_TRIANGLES[i];
+        write_vertex(canvas, &out[i], xy8[corner * 2], xy8[(corner * 2) + 1], uv8[corner * 2],
+                     uv8[(corner * 2) + 1], color);
+    }
+}
+
+/* Multiplies two colour components, 0..255 in and out: 255 leaves the other
+ * untouched, which is what makes WHITE the "no tint" value. */
+static unsigned char modulate(unsigned char value, int tint) {
+    return (unsigned char)((value * tint) / 255);
+}
+
+void rgame_canvas_replay(rgame_canvas *canvas, const rgame_recording *recording, float dx,
+                         float dy, rgame_color color, double z) {
+    if (!recording) {
+        return;
+    }
+
+    int tint[4] = { rgame_color_r(color), rgame_color_g(color), rgame_color_b(color),
+                    rgame_color_a(color) };
+
+    for (unsigned int b = 0; b < recording->batch_count; b++) {
+        const rgame_recording_batch *batch = &recording->batches[b];
+
+        /* One command per baked batch, rather than one per original draw call:
+         * the whole point of a recording is that the per-tile work happened
+         * once, at bake time. */
+        rgame_vertex *out = rgame_draw_queue_alloc(&canvas->queue, batch->vertex_count, z,
+                                                   batch->texture,
+                                                   rgame_clip_current(&canvas->clips));
+
+        for (unsigned int i = 0; i < batch->vertex_count; i++) {
+            const rgame_vertex *baked = &recording->vertices[batch->first_vertex + i];
+
+            /* Offset first, then the current transform — so the offset is in
+             * the recording's own coordinates and the transform is the world's,
+             * which is the order a camera needs. */
+            rgame_transform_apply(&canvas->transforms, baked->x + dx, baked->y + dy, &out[i].x,
+                                  &out[i].y);
+            out[i].u = baked->u;
+            out[i].v = baked->v;
+            for (int c = 0; c < 4; c++) {
+                out[i].rgba[c] = modulate(baked->rgba[c], tint[c]);
+            }
+        }
+    }
+}
+
+void rgame_canvas_submit(const rgame_canvas *canvas, const rgame_draw_backend *backend) {
+    rgame_draw_submit(&canvas->queue, backend, canvas->width, canvas->height);
+}
+
+const rgame_draw_queue *rgame_canvas_queue(const rgame_canvas *canvas) {
+    return &canvas->queue;
+}
+
+int rgame_canvas_depth(const rgame_canvas *canvas) {
+    return canvas->push_depth + canvas->unrecorded_pushes;
+}

data/ext/rgame_core/graphics/canvas.h

@@ -0,0 +1,143 @@
+#ifndef RGAME_CANVAS_H
+#define RGAME_CANVAS_H
+
+#include "graphics/backend.h"
+#include "graphics/clip.h"
+#include "color.h"
+#include "graphics/draw_queue.h"
+#include "graphics/recording.h"
+#include "graphics/transform.h"
+
+/*
+ * The canvas: where the transform stack, the clip stack and the draw queue meet
+ * — and still pure arithmetic, with no SDL and no GL.
+ *
+ * Each of the three pieces below it does one thing and knows nothing of the
+ * others. This is the layer that composes them, and it is the seam the drawing
+ * API is actually written against: everything above (the Ruby renderer, and
+ * eventually the scene graph) speaks to a canvas, and everything below is
+ * arithmetic that can be tested without a window.
+ *
+ * ---------------------------------------------------------------------------
+ * Vertices are transformed on the way in
+ * ---------------------------------------------------------------------------
+ *
+ * A primitive's points are mapped through the current transform *before* they
+ * reach the queue, so the queue stores screen-space coordinates. That is what
+ * lets it sort freely: once a vertex is positioned, reordering commands cannot
+ * change where anything lands. Storing untransformed points and applying the
+ * transform at flush time would mean re-associating each command with the
+ * transform that was current when it was issued — which is exactly the
+ * bookkeeping this design exists to avoid.
+ *
+ * ---------------------------------------------------------------------------
+ * Clips are transformed too
+ * ---------------------------------------------------------------------------
+ *
+ * A clip pushed inside a translate moves with it — measured against the layer
+ * being replaced, where a clip at x 0..20 inside a translate of 50 clips
+ * x 50..70. So `push_clip` maps the caller's rect through the current transform
+ * before handing it to the clip stack, which works purely in screen space.
+ *
+ * Under translation and scaling that mapping is exact. Under rotation it cannot
+ * be: a scissor rectangle is axis-aligned and a rotated rectangle is not, so
+ * the axis-aligned bounding box is used instead. That errs towards clipping
+ * *less* than asked, which is the safe direction, and nothing in the engine
+ * rotates a clip today.
+ *
+ * ---------------------------------------------------------------------------
+ * One pop for any push
+ * ---------------------------------------------------------------------------
+ *
+ * `push_translate`, `push_rotate`, `push_scale` and `push_clip` are all undone
+ * by the same `pop`. The canvas remembers which stack each push went to, so a
+ * caller never has to — and cannot pop the wrong one. Pushes that could not be
+ * honoured (a full stack) are still counted, so pop stays balanced and the
+ * drawing comes out untransformed rather than desynchronised.
+ */
+
+/* Deep enough that it cannot fill before both underlying stacks have; pushes
+ * beyond that are counted rather than recorded, so balance always holds. */
+#define RGAME_CANVAS_STACK_DEPTH (RGAME_TRANSFORM_STACK_DEPTH + RGAME_CLIP_STACK_DEPTH)
+
+typedef struct {
+    rgame_transform_stack transforms;
+    rgame_clip_stack clips;
+    rgame_draw_queue queue;
+
+    /* Which stack each outstanding push went to, so pop can undo the right one. */
+    unsigned char pushes[RGAME_CANVAS_STACK_DEPTH];
+    int push_depth;
+    /* Pushes with nowhere to be recorded. Counted so pop still balances. */
+    int unrecorded_pushes;
+
+    /* Remembered from begin_frame, so submit needs no repeat of the size. */
+    int width, height;
+} rgame_canvas;
+
+void rgame_canvas_init(rgame_canvas *canvas);
+void rgame_canvas_destroy(rgame_canvas *canvas);
+
+/*
+ * Starts a frame: empties the queue (keeping its buffers), resets both stacks,
+ * and sets the clip base to the window. Re-stating the size every frame is also
+ * how a resize takes effect, so there is no separate path to forget.
+ */
+void rgame_canvas_begin_frame(rgame_canvas *canvas, int width, int height);
+
+/* Sorts and batches what was drawn. Read the result through rgame_canvas_queue. */
+void rgame_canvas_end_frame(rgame_canvas *canvas);
+
+void rgame_canvas_push_translate(rgame_canvas *canvas, float dx, float dy);
+void rgame_canvas_push_rotate(rgame_canvas *canvas, float degrees, float pivot_x,
+                              float pivot_y);
+void rgame_canvas_push_scale(rgame_canvas *canvas, float sx, float sy);
+
+/* `rect` is in the caller's local coordinates and is mapped through the current
+ * transform before narrowing the clip. */
+void rgame_canvas_push_clip(rgame_canvas *canvas, rgame_rect rect);
+
+void rgame_canvas_pop(rgame_canvas *canvas);
+
+/*
+ * Primitives. Points arrive as flat coordinate pairs in the caller's local
+ * space: `xy6` is three points, `xy8` four. A quad's points are taken in loop
+ * order (for a rectangle: top-left, top-right, bottom-right, bottom-left) and
+ * split into triangles 0-1-2 and 0-2-3.
+ *
+ * `uv8` is the matching four texture coordinates, in the same corner order.
+ */
+void rgame_canvas_triangle(rgame_canvas *canvas, const float *xy6, rgame_color color,
+                           double z);
+void rgame_canvas_quad(rgame_canvas *canvas, const float *xy8, rgame_color color, double z);
+void rgame_canvas_textured_quad(rgame_canvas *canvas, unsigned int texture, const float *xy8,
+                                const float *uv8, rgame_color color, double z);
+
+/*
+ * Replays a baked recording (see recording.h) offset by (dx, dy), at `z`, tinted
+ * by `color` — RGAME_COLOR_WHITE leaves the recorded colours alone.
+ *
+ * The offset is applied *before* the current transform, so a baked layer moves
+ * with the camera it is drawn under and can be placed anywhere without being
+ * re-baked. Every batch becomes one command at the same z, and because equal z
+ * keeps insertion order, the painter order baked into the recording survives.
+ *
+ * The clip is the one current at replay time; recordings do not carry their own
+ * (recording.h says why).
+ */
+void rgame_canvas_replay(rgame_canvas *canvas, const rgame_recording *recording, float dx,
+                         float dy, rgame_color color, double z);
+
+/*
+ * Hands the finished frame to a backend. Call after end_frame; equivalent to
+ * rgame_draw_submit with the size this frame was begun at.
+ */
+void rgame_canvas_submit(const rgame_canvas *canvas, const rgame_draw_backend *backend);
+
+const rgame_draw_queue *rgame_canvas_queue(const rgame_canvas *canvas);
+
+/* How many pushes are outstanding, counting ones that could not be recorded.
+ * A balanced frame ends at zero. */
+int rgame_canvas_depth(const rgame_canvas *canvas);
+
+#endif /* RGAME_CANVAS_H */

data/ext/rgame_core/graphics/clip.c

@@ -0,0 +1,87 @@
+#include "graphics/clip.h"
+
+/* The canonical empty rect. Every path that produces "nothing" produces this
+ * exact value, so two empties compare equal and cannot split a batch. */
+static const rgame_rect RGAME_EMPTY_RECT = { 0, 0, 0, 0 };
+
+rgame_rect rgame_rect_make(int x, int y, int w, int h) {
+    if (w <= 0 || h <= 0) {
+        return RGAME_EMPTY_RECT;
+    }
+    rgame_rect r = { x, y, w, h };
+    return r;
+}
+
+int rgame_rect_is_empty(rgame_rect r) {
+    return r.w <= 0 || r.h <= 0;
+}
+
+int rgame_rect_equals(rgame_rect a, rgame_rect b) {
+    return a.x == b.x && a.y == b.y && a.w == b.w && a.h == b.h;
+}
+
+int rgame_rect_contains_point(rgame_rect r, int x, int y) {
+    return !rgame_rect_is_empty(r) && x >= r.x && y >= r.y && x < r.x + r.w && y < r.y + r.h;
+}
+
+rgame_rect rgame_rect_intersect(rgame_rect a, rgame_rect b) {
+    if (rgame_rect_is_empty(a) || rgame_rect_is_empty(b)) {
+        return RGAME_EMPTY_RECT;
+    }
+
+    /*
+     * Edges are computed in `long` rather than `int`. A caller can legitimately
+     * pass a very large width to mean "as wide as possible", and x + w would
+     * then overflow — which is undefined behaviour, not merely a wrong answer.
+     * The result always fits back in an int because it is bounded by the
+     * smaller of the two inputs.
+     */
+    long left = a.x > b.x ? a.x : b.x;
+    long top = a.y > b.y ? a.y : b.y;
+    long a_right = (long)a.x + a.w;
+    long b_right = (long)b.x + b.w;
+    long a_bottom = (long)a.y + a.h;
+    long b_bottom = (long)b.y + b.h;
+    long right = a_right < b_right ? a_right : b_right;
+    long bottom = a_bottom < b_bottom ? a_bottom : b_bottom;
+
+    if (right <= left || bottom <= top) {
+        return RGAME_EMPTY_RECT;
+    }
+
+    rgame_rect result = { (int)left, (int)top, (int)(right - left), (int)(bottom - top) };
+    return result;
+}
+
+void rgame_clip_stack_init(rgame_clip_stack *stack, int width, int height) {
+    stack->depth = 0;
+    stack->entries[0] = rgame_rect_make(0, 0, width, height);
+}
+
+int rgame_clip_push(rgame_clip_stack *stack, rgame_rect rect) {
+    if (stack->depth + 1 >= RGAME_CLIP_STACK_DEPTH) {
+        return 0;
+    }
+    stack->entries[stack->depth + 1] =
+        rgame_rect_intersect(stack->entries[stack->depth], rect);
+    stack->depth++;
+    return 1;
+}
+
+void rgame_clip_pop(rgame_clip_stack *stack) {
+    if (stack->depth > 0) {
+        stack->depth--;
+    }
+}
+
+rgame_rect rgame_clip_current(const rgame_clip_stack *stack) {
+    return stack->entries[stack->depth];
+}
+
+int rgame_clip_is_empty(const rgame_clip_stack *stack) {
+    return rgame_rect_is_empty(stack->entries[stack->depth]);
+}
+
+int rgame_clip_depth(const rgame_clip_stack *stack) {
+    return stack->depth;
+}

data/ext/rgame_core/graphics/clip.h

@@ -0,0 +1,89 @@
+#ifndef RGAME_CLIP_H
+#define RGAME_CLIP_H
+
+/*
+ * Rectangles and the clip stack — pure arithmetic, no SDL, no GL, no I/O.
+ *
+ * Clipping restricts drawing to a rectangle. The engine needs it in two very
+ * different places: tiling a 9-slice texture's edges without overdraw, and
+ * giving each player their own screen region in split-screen. Both want the
+ * same thing — a stack where pushing *narrows* the visible area and popping
+ * restores it.
+ *
+ * ---------------------------------------------------------------------------
+ * Screen space, and whose job the transform is
+ * ---------------------------------------------------------------------------
+ *
+ * Everything here is in screen pixels. That is deliberate, and it is *not* the
+ * whole story for callers: in the layer being replaced, a clip pushed inside a
+ * translate moves with it (measured — a clip at x 0..20 inside translate(50,0)
+ * clips x 50..70). Reproducing that is the canvas's job: it maps the caller's
+ * rect through the current transform and pushes the screen-space result here.
+ *
+ * Keeping the two apart is what lets this module stay pure integer arithmetic
+ * with no idea that transforms exist.
+ *
+ * ---------------------------------------------------------------------------
+ * Empty is a real answer
+ * ---------------------------------------------------------------------------
+ *
+ * Two disjoint rects intersect to nothing, and "nothing" has to be
+ * representable — the draw queue uses it to drop commands before they ever
+ * reach the GPU. An empty result is canonicalised to {0,0,0,0} so that two
+ * different ways of ending up with nothing compare equal, which matters
+ * because the clip rect is part of the queue's batch key.
+ */
+
+typedef struct {
+    int x, y, w, h;
+} rgame_rect;
+
+/* Deep enough for any sane scene; a bounded stack cannot run away. */
+#define RGAME_CLIP_STACK_DEPTH 32
+
+typedef struct {
+    /* entries[0] is the window bounds — the widest anything may draw — so
+     * every command has a meaningful clip and there is no "no clip" case. */
+    rgame_rect entries[RGAME_CLIP_STACK_DEPTH];
+    int depth;
+} rgame_clip_stack;
+
+rgame_rect rgame_rect_make(int x, int y, int w, int h);
+
+/* The overlap of two rects, or {0,0,0,0} if they do not overlap. */
+rgame_rect rgame_rect_intersect(rgame_rect a, rgame_rect b);
+
+int rgame_rect_is_empty(rgame_rect r);
+
+/* Exact equality. The draw queue compares clips to decide whether two commands
+ * can share a batch, so this needs to be cheap and total. */
+int rgame_rect_equals(rgame_rect a, rgame_rect b);
+
+int rgame_rect_contains_point(rgame_rect r, int x, int y);
+
+/*
+ * Resets the stack with the window bounds as its base. Called at the start of
+ * every frame, which is also how a window resize takes effect — there is no
+ * separate "the window changed size" path to forget.
+ */
+void rgame_clip_stack_init(rgame_clip_stack *stack, int width, int height);
+
+/*
+ * Narrows the clip to `rect` intersected with the current one, and pushes the
+ * result. Returns 1, or 0 if the stack is full — in which case nothing is
+ * pushed and no matching pop must be issued.
+ *
+ * Note this always *narrows*: a pushed rect larger than the current clip
+ * cannot widen it. That is what makes nesting safe — a child can never draw
+ * outside the region its parent allowed.
+ */
+int rgame_clip_push(rgame_clip_stack *stack, rgame_rect rect);
+
+/* Pops the current clip. Popping the base is a no-op rather than an underflow. */
+void rgame_clip_pop(rgame_clip_stack *stack);
+
+rgame_rect rgame_clip_current(const rgame_clip_stack *stack);
+int rgame_clip_is_empty(const rgame_clip_stack *stack);
+int rgame_clip_depth(const rgame_clip_stack *stack);
+
+#endif /* RGAME_CLIP_H */