rgame 0.1.0

data/ext/rgame_core/graphics/draw_queue.c

@@ -0,0 +1,216 @@
+#include "graphics/draw_queue.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+/*
+ * Grow a buffer to hold at least `needed` items, doubling so that repeated
+ * appends are amortised constant time. Returns 0 if the allocation failed, in
+ * which case the existing buffer is untouched and still usable — realloc only
+ * frees the old block on success.
+ */
+static int ensure_capacity(void **items, unsigned int *capacity, unsigned int needed,
+                           size_t item_size) {
+    if (*capacity >= needed) {
+        return 1;
+    }
+
+    unsigned int next = *capacity ? *capacity : 1;
+    while (next < needed) {
+        unsigned int doubled = next * 2;
+        if (doubled < next) { /* would overflow; give up rather than wrap */
+            return 0;
+        }
+        next = doubled;
+    }
+
+    void *grown = realloc(*items, (size_t)next * item_size);
+    if (!grown) {
+        return 0;
+    }
+    *items = grown;
+    *capacity = next;
+    return 1;
+}
+
+void rgame_draw_queue_init(rgame_draw_queue *queue) {
+    memset(queue, 0, sizeof(*queue));
+}
+
+void rgame_draw_queue_destroy(rgame_draw_queue *queue) {
+    free(queue->commands);
+    free(queue->vertices);
+    free(queue->sorted);
+    free(queue->batches);
+    free(queue->discard);
+    memset(queue, 0, sizeof(*queue));
+}
+
+void rgame_draw_queue_reset(rgame_draw_queue *queue) {
+    /* Counts only — the buffers stay, which is the whole point. */
+    queue->command_count = 0;
+    queue->vertex_count = 0;
+    queue->sorted_count = 0;
+    queue->batch_count = 0;
+}
+
+/* Somewhere writable for a dropped command's vertices to go. */
+static rgame_vertex *discard_span(rgame_draw_queue *queue, unsigned int count) {
+    /* At least one, even for a zero-vertex request: the contract is that this
+     * never hands back NULL, and ensure_capacity(0) would short-circuit before
+     * allocating anything at all. */
+    unsigned int needed = count ? count : 1;
+    if (!ensure_capacity((void **)&queue->discard, &queue->discard_capacity, needed,
+                         sizeof(rgame_vertex))) {
+        /*
+         * Even the scratch could not grow. Returning NULL here would hand the
+         * caller a pointer it does not check; instead keep whatever scratch we
+         * already have. Writing past it is only reachable if the very first
+         * allocation in the process failed, at which point nothing works
+         * anyway — but the pointer stays valid, which is what matters.
+         */
+        return queue->discard;
+    }
+    return queue->discard;
+}
+
+rgame_vertex *rgame_draw_queue_alloc(rgame_draw_queue *queue, unsigned int count, double z,
+                                     unsigned int texture, rgame_rect clip) {
+    /* Nothing to draw, or nowhere to draw it: drop before reserving anything. */
+    if (count == 0 || rgame_rect_is_empty(clip)) {
+        return discard_span(queue, count);
+    }
+
+    /*
+     * A NaN z makes the comparator intransitive, and qsort with a comparator
+     * that is not a total order is undefined behaviour rather than merely a
+     * wrong order. Concretely, with A(NaN, order 1), B(5.0, order 0) and
+     * C(1.0, order 2) the comparator reports B<A and A<C but also C<B.
+     * `z != z` is true only for NaN.
+     */
+    if (z != z) {
+        z = 0.0;
+    }
+
+    /* Reserve both buffers before committing to either, so a failure leaves
+     * the queue exactly as it was. */
+    if (!ensure_capacity((void **)&queue->vertices, &queue->vertex_capacity,
+                         queue->vertex_count + count, sizeof(rgame_vertex)) ||
+        !ensure_capacity((void **)&queue->commands, &queue->command_capacity,
+                         queue->command_count + 1, sizeof(rgame_draw_command))) {
+        return discard_span(queue, count);
+    }
+
+    rgame_draw_command *command = &queue->commands[queue->command_count];
+    command->z = z;
+    command->order = queue->command_count;
+    command->texture = texture;
+    command->clip = clip;
+    command->first_vertex = queue->vertex_count;
+    command->vertex_count = count;
+
+    rgame_vertex *span = &queue->vertices[queue->vertex_count];
+    queue->vertex_count += count;
+    queue->command_count++;
+    return span;
+}
+
+/*
+ * Order by z, then by insertion order.
+ *
+ * The tiebreak is what makes the result deterministic; because `order` is
+ * unique the comparison is a total order, so an unstable sort like qsort still
+ * produces the one correct answer. Stability comes from the comparator, not
+ * from the algorithm.
+ */
+int rgame_draw_command_compare(const void *lhs, const void *rhs) {
+    const rgame_draw_command *a = lhs;
+    const rgame_draw_command *b = rhs;
+
+    if (a->z < b->z) {
+        return -1;
+    }
+    if (a->z > b->z) {
+        return 1;
+    }
+    if (a->order < b->order) {
+        return -1;
+    }
+    return a->order > b->order ? 1 : 0;
+}
+
+/* Two commands can share a draw call only if both the texture and the clip
+ * match — see the note on `clip` in the header for why the clip is part of it. */
+static int batchable_with(const rgame_draw_batch *batch, const rgame_draw_command *command) {
+    return batch->texture == command->texture && rgame_rect_equals(batch->clip, command->clip);
+}
+
+void rgame_draw_queue_prepare(rgame_draw_queue *queue) {
+    queue->sorted_count = 0;
+    queue->batch_count = 0;
+    if (queue->command_count == 0) {
+        return;
+    }
+
+    qsort(queue->commands, queue->command_count, sizeof(rgame_draw_command),
+          rgame_draw_command_compare);
+
+    if (!ensure_capacity((void **)&queue->sorted, &queue->sorted_capacity, queue->vertex_count,
+                         sizeof(rgame_vertex)) ||
+        !ensure_capacity((void **)&queue->batches, &queue->batch_capacity,
+                         queue->command_count, sizeof(rgame_draw_batch))) {
+        return; /* nothing prepared; the frame draws nothing rather than crashing */
+    }
+
+    for (unsigned int i = 0; i < queue->command_count; i++) {
+        const rgame_draw_command *command = &queue->commands[i];
+
+        /* Copy this command's vertices into the contiguous output. */
+        memcpy(&queue->sorted[queue->sorted_count], &queue->vertices[command->first_vertex],
+               (size_t)command->vertex_count * sizeof(rgame_vertex));
+
+        rgame_draw_batch *open_batch =
+            queue->batch_count ? &queue->batches[queue->batch_count - 1] : NULL;
+
+        if (open_batch && batchable_with(open_batch, command)) {
+            open_batch->vertex_count += command->vertex_count;
+        } else {
+            rgame_draw_batch *batch = &queue->batches[queue->batch_count++];
+            batch->texture = command->texture;
+            batch->clip = command->clip;
+            batch->first_vertex = queue->sorted_count;
+            batch->vertex_count = command->vertex_count;
+        }
+
+        queue->sorted_count += command->vertex_count;
+    }
+}
+
+unsigned int rgame_draw_queue_batch_count(const rgame_draw_queue *queue) {
+    return queue->batch_count;
+}
+
+const rgame_draw_batch *rgame_draw_queue_batch(const rgame_draw_queue *queue,
+                                               unsigned int index) {
+    return index < queue->batch_count ? &queue->batches[index] : NULL;
+}
+
+const rgame_vertex *rgame_draw_queue_vertices(const rgame_draw_queue *queue) {
+    return queue->sorted;
+}
+
+unsigned int rgame_draw_queue_vertex_count(const rgame_draw_queue *queue) {
+    return queue->sorted_count;
+}
+
+unsigned int rgame_draw_queue_command_count(const rgame_draw_queue *queue) {
+    return queue->command_count;
+}
+
+unsigned int rgame_draw_queue_command_capacity(const rgame_draw_queue *queue) {
+    return queue->command_capacity;
+}
+
+unsigned int rgame_draw_queue_vertex_capacity(const rgame_draw_queue *queue) {
+    return queue->vertex_capacity;
+}

data/ext/rgame_core/graphics/draw_queue.h

@@ -0,0 +1,174 @@
+#ifndef RGAME_DRAW_QUEUE_H
+#define RGAME_DRAW_QUEUE_H
+
+#include "graphics/clip.h"
+
+/*
+ * The draw queue: z-ordering and batching — pure arithmetic, no SDL, no GL.
+ *
+ * ---------------------------------------------------------------------------
+ * Why this exists at all
+ * ---------------------------------------------------------------------------
+ *
+ * Every draw call carries a `z`, and the renderer must sort by it *regardless
+ * of the order the calls were made in*. UI draws above gameplay, overlays above
+ * UI, all by z value rather than by anyone remembering to draw in the right
+ * sequence. The layer being replaced depends on this everywhere.
+ *
+ * The obvious shortcut — enable the depth buffer and let the GPU sort it out —
+ * does not work here, and it is worth being clear why: depth testing and alpha
+ * blending are mutually exclusive. A depth-tested translucent quad *rejects*
+ * the fragments behind it instead of blending with them, so anything drawn
+ * later at a lower z simply vanishes. Every UI panel in this engine is
+ * translucent chrome over gameplay, so the depth buffer would break exactly the
+ * case it was supposed to help. Hence: collect commands, sort them on the CPU,
+ * and draw back-to-front with blending on.
+ *
+ * ---------------------------------------------------------------------------
+ * How it is arranged
+ * ---------------------------------------------------------------------------
+ *
+ * Vertices go in one big array; commands index into it. That keeps the records
+ * being sorted small (a command is ~40 bytes, not six vertices), and lets
+ * triangles and quads sit in the same queue without a variant type.
+ *
+ * `prepare` then does two things: sorts the commands, and walks them building a
+ * *second*, sorted vertex array plus a list of batches. The copy is necessary —
+ * after sorting, a batch's commands are adjacent but their vertices are still
+ * scattered through the original array, and a GL draw call needs one contiguous
+ * run.
+ *
+ * Nothing here talks to a backend. `prepare` leaves batches and vertices for
+ * someone else to walk, which keeps the dependency one-directional and means
+ * the whole module is testable with no fake and no display.
+ */
+
+/*
+ * One vertex, 20 bytes: position, texture coordinate, colour.
+ *
+ * The colour is four *bytes* in R, G, B, A order rather than a packed 32-bit
+ * word, and that is deliberate. glColorPointer(4, GL_UNSIGNED_BYTE, ...) reads
+ * them in memory order, and the bytes of a packed 0xRRGGBBAA come out A, B, G,
+ * R on a little-endian machine — GL would read alpha as red. Storing bytes
+ * sidesteps the question and is endian-independent. See rgame_color_bytes.
+ */
+typedef struct {
+    float x, y; /* screen space: already transformed when it arrives here */
+    float u, v; /* texture coordinates; ignored when texture == 0 */
+    unsigned char rgba[4];
+} rgame_vertex;
+
+typedef struct {
+    double z;
+    /*
+     * Insertion index. The sort compares (z, order), so commands with equal z
+     * keep the order they were issued in — without
+     * it same-z sprites would swap places between frames as the sort reshuffled
+     * them, which reads as flicker. Note the *comparator* provides stability
+     * here, so the sort algorithm itself does not have to be stable.
+     */
+    unsigned int order;
+    unsigned int texture; /* GL texture name; 0 means untextured */
+    /*
+     * The clip travels with the command rather than being ambient state,
+     * because sorting reorders commands across viewports. A clip left "current"
+     * at draw time would end up scissoring whichever quads happened to sort
+     * next to it — the bug a single-viewport renderer cannot see and cannot fix
+     * without being rebuilt.
+     */
+    rgame_rect clip;
+    unsigned int first_vertex, vertex_count;
+} rgame_draw_command;
+
+/* A run of adjacent sorted commands that share a texture and a clip, and can
+ * therefore go to the GPU as one call. */
+typedef struct {
+    unsigned int texture;
+    rgame_rect clip;
+    unsigned int first_vertex, vertex_count; /* into the prepared vertex array */
+} rgame_draw_batch;
+
+typedef struct {
+    rgame_draw_command *commands;
+    unsigned int command_count, command_capacity;
+
+    rgame_vertex *vertices; /* as submitted */
+    unsigned int vertex_count, vertex_capacity;
+
+    rgame_vertex *sorted; /* rebuilt by prepare, contiguous per batch */
+    unsigned int sorted_count, sorted_capacity;
+
+    rgame_draw_batch *batches;
+    unsigned int batch_count, batch_capacity;
+
+    /*
+     * Where vertices go when a command is dropped (empty clip, or a failed
+     * grow). The caller still gets somewhere writable, so it never has to
+     * null-check and can never write through a null pointer; the vertices are
+     * simply never referenced. Bounded by the largest single request.
+     */
+    rgame_vertex *discard;
+    unsigned int discard_capacity;
+} rgame_draw_queue;
+
+void rgame_draw_queue_init(rgame_draw_queue *queue);
+
+/* Releases every buffer. The queue is reusable after a fresh init. */
+void rgame_draw_queue_destroy(rgame_draw_queue *queue);
+
+/*
+ * Empties the queue for a new frame while *keeping* the buffers it has grown.
+ * After a few frames the capacities settle and a steady frame allocates
+ * nothing at all, which is the difference between a smooth 60fps and a GC-style
+ * hitch every time the heap grows.
+ */
+void rgame_draw_queue_reset(rgame_draw_queue *queue);
+
+/*
+ * Reserves `count` vertices for one primitive and returns a writable span for
+ * the caller to fill in place — no temporary array, no copy.
+ *
+ * Never returns NULL. A command with an empty clip, a zero vertex count, or one
+ * that could not be stored is silently dropped, and the returned span points at
+ * scratch. That is deliberate: a caller that forgets to check a return value
+ * should get a draw that does not appear, not a crash.
+ */
+rgame_vertex *rgame_draw_queue_alloc(rgame_draw_queue *queue, unsigned int count, double z,
+                                     unsigned int texture, rgame_rect clip);
+
+/*
+ * Sorts the commands and builds the batch list and the contiguous vertex array
+ * that goes with it. Call once per frame, after all drawing and before handing
+ * the result to a backend.
+ */
+void rgame_draw_queue_prepare(rgame_draw_queue *queue);
+
+/* Valid after prepare. */
+unsigned int rgame_draw_queue_batch_count(const rgame_draw_queue *queue);
+const rgame_draw_batch *rgame_draw_queue_batch(const rgame_draw_queue *queue,
+                                               unsigned int index);
+const rgame_vertex *rgame_draw_queue_vertices(const rgame_draw_queue *queue);
+unsigned int rgame_draw_queue_vertex_count(const rgame_draw_queue *queue);
+
+/*
+ * The ordering `prepare` sorts by: ascending z, ties broken by insertion order.
+ *
+ * Exposed rather than kept static because it cannot be tested through the
+ * sort: the C library's qsort is free to be stable, and glibc's is, so a
+ * missing tiebreak would still *look* correct here while being undefined
+ * anywhere else. Signature matches qsort's comparator.
+ */
+int rgame_draw_command_compare(const void *lhs, const void *rhs);
+
+/* How many commands are waiting. Mostly for tests and diagnostics. */
+unsigned int rgame_draw_queue_command_count(const rgame_draw_queue *queue);
+
+/*
+ * Current buffer capacities. Exposed so a test can assert that a second
+ * identical frame grows nothing — the "no per-frame allocation" property is
+ * invisible otherwise, and would rot without something watching it.
+ */
+unsigned int rgame_draw_queue_command_capacity(const rgame_draw_queue *queue);
+unsigned int rgame_draw_queue_vertex_capacity(const rgame_draw_queue *queue);
+
+#endif /* RGAME_DRAW_QUEUE_H */

data/ext/rgame_core/graphics/gl_backend.c

@@ -0,0 +1,122 @@
+/*
+ * gl_backend.c — the real GL calls. See gl_backend.h for what this is and
+ * which OpenGL it targets.
+ */
+
+#include "graphics/gl_backend.h"
+
+#include <SDL2/SDL_opengl.h>
+
+/* The colour an un-drawn pixel ends up. Not configurable yet — when a game
+ * needs its own background it should become an app-level setting rather than a
+ * constant here. */
+#define RGAME_CLEAR_R 0.1f
+#define RGAME_CLEAR_G 0.1f
+#define RGAME_CLEAR_B 0.15f
+
+static void gl_begin_frame(void *ctx, int width, int height) {
+    rgame_gl_backend *state = ctx;
+    state->width = width;
+    state->height = height;
+
+    glViewport(0, 0, width, height);
+
+    /*
+     * Screen coordinates, not GL's. glOrtho's near/far arguments are given as
+     * (left, right, bottom, top): passing height as *bottom* and 0 as *top*
+     * flips the y axis, so (0,0) is the top-left corner and y grows downwards —
+     * the convention every coordinate in this engine already uses.
+     */
+    glMatrixMode(GL_PROJECTION);
+    glLoadIdentity();
+    glOrtho(0.0, (double)width, (double)height, 0.0, -1.0, 1.0);
+    glMatrixMode(GL_MODELVIEW);
+    glLoadIdentity();
+
+    /*
+     * No depth testing. The draw queue has already sorted by z on the CPU, and
+     * that is not an optimisation to undo: depth testing and alpha blending do
+     * not mix. A translucent pixel that passes the depth test writes depth, so
+     * whatever should have shown through it is discarded — which is why
+     * translucent UI over gameplay needs a painter's-algorithm sort instead.
+     */
+    glDisable(GL_DEPTH_TEST);
+
+    glEnable(GL_BLEND);
+    glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
+
+    /* Clear before the scissor test goes on: glClear obeys the scissor, so
+     * clearing afterwards would only clear whatever region was last set. */
+    glDisable(GL_SCISSOR_TEST);
+    glClearColor(RGAME_CLEAR_R, RGAME_CLEAR_G, RGAME_CLEAR_B, 1.0f);
+    glClear(GL_COLOR_BUFFER_BIT);
+    glEnable(GL_SCISSOR_TEST);
+
+    /* Client-side vertex arrays: the vertex data stays in our own buffer and GL
+     * reads it at draw time. Switching these on once per frame rather than once
+     * per batch is the whole reason they are here and not in draw_batch. */
+    glEnableClientState(GL_VERTEX_ARRAY);
+    glEnableClientState(GL_TEXTURE_COORD_ARRAY);
+    glEnableClientState(GL_COLOR_ARRAY);
+}
+
+static void gl_set_clip(void *ctx, rgame_rect clip) {
+    rgame_gl_backend *state = ctx;
+
+    /*
+     * GL measures the scissor box from the *bottom* of the window; every
+     * rectangle in this engine is measured from the top. Flipping it is one
+     * line and getting it wrong puts the clip in the mirror-image place, which
+     * on a centred test rectangle looks correct.
+     */
+    glScissor(clip.x, state->height - (clip.y + clip.h), clip.w, clip.h);
+}
+
+static void gl_draw_batch(void *ctx, unsigned int texture, const rgame_vertex *vertices,
+                          unsigned int count) {
+    (void)ctx;
+
+    if (texture == 0) {
+        /* Untextured: the colour array alone decides the pixel. */
+        glDisable(GL_TEXTURE_2D);
+    } else {
+        glEnable(GL_TEXTURE_2D);
+        glBindTexture(GL_TEXTURE_2D, texture);
+    }
+
+    /*
+     * The three arrays are interleaved in one `rgame_vertex`, so all three
+     * pointers walk the same buffer with the same stride at different offsets.
+     * One allocation per frame, one pass over it per batch.
+     */
+    glVertexPointer(2, GL_FLOAT, sizeof(rgame_vertex), &vertices[0].x);
+    glTexCoordPointer(2, GL_FLOAT, sizeof(rgame_vertex), &vertices[0].u);
+    glColorPointer(4, GL_UNSIGNED_BYTE, sizeof(rgame_vertex), vertices[0].rgba);
+
+    /* Everything is triangles by the time it reaches here — quads were split
+     * upstream, so there is one primitive type to issue. */
+    glDrawArrays(GL_TRIANGLES, 0, (GLsizei)count);
+}
+
+static void gl_end_frame(void *ctx) {
+    (void)ctx;
+
+    /* Leave GL as it was found. The window's own buffer swap is the app's job,
+     * not the backend's — the backend has no window. */
+    glDisableClientState(GL_VERTEX_ARRAY);
+    glDisableClientState(GL_TEXTURE_COORD_ARRAY);
+    glDisableClientState(GL_COLOR_ARRAY);
+    glDisable(GL_SCISSOR_TEST);
+    glDisable(GL_TEXTURE_2D);
+}
+
+rgame_draw_backend rgame_gl_backend_table(rgame_gl_backend *state) {
+    rgame_draw_backend backend = {
+        .begin_frame = gl_begin_frame,
+        .set_clip = gl_set_clip,
+        .draw_batch = gl_draw_batch,
+        .end_frame = gl_end_frame,
+        .ctx = state,
+    };
+    return backend;
+}

data/ext/rgame_core/graphics/gl_backend.h

@@ -0,0 +1,43 @@
+#ifndef RGAME_GL_BACKEND_H
+#define RGAME_GL_BACKEND_H
+
+#include "graphics/backend.h"
+
+/*
+ * The real OpenGL implementation of the `rgame_draw_backend` table — layer 3,
+ * and the only file in the drawing path that calls `gl*`.
+ *
+ * Everything above it has already decided what to draw and in what order:
+ * primitives.c turned shapes into quads, canvas.c transformed and clipped them,
+ * draw_queue.c sorted and batched them. What is left here is issuing the calls,
+ * which is why the file is short and why it is verified by looking at the
+ * screen (`make run`, `rake spec:core`'s pixel checks) rather than by unit
+ * tests — the same calls in the same order are already checked against
+ * `test/support/recording_backend.c`.
+ *
+ * ---------------------------------------------------------------------------
+ * Which OpenGL this is
+ * ---------------------------------------------------------------------------
+ *
+ * Fixed-function, compatibility-profile GL 1.1: `glOrtho`, client-side vertex
+ * arrays, `glDrawArrays`. No shaders and no extension loader (GLAD/GLEW),
+ * because none of it needs one — every function used here is in the 1.1 core
+ * that ships with the platform's GL library. Moving to core-profile modern GL
+ * would be a deliberate decision with a loader attached; see CLAUDE.md.
+ */
+
+typedef struct {
+    /* Remembered from begin_frame so set_clip can flip a screen-space rectangle
+     * into GL's bottom-up scissor coordinates. */
+    int width, height;
+} rgame_gl_backend;
+
+/*
+ * A backend table driving real GL, over caller-owned state.
+ *
+ * `state` must outlive the returned table — it is the `ctx` every callback
+ * receives. Typically both live in the app.
+ */
+rgame_draw_backend rgame_gl_backend_table(rgame_gl_backend *state);
+
+#endif /* RGAME_GL_BACKEND_H */