rgame 0.1.0

data/ext/rgame_core/graphics/image.c

@@ -0,0 +1,304 @@
+/*
+ * image.c — decode a PNG, upload it to the GPU, hand back a handle.
+ *
+ * This is "layer 3" in CLAUDE.md's abstraction strategy: the thin shim where
+ * real calls happen. Everything interesting about images — which rectangle of
+ * a sheet a sprite covers, how that becomes texture coordinates, when the
+ * shared upload may be deleted — is in texture.{c,h}, is pure, and is covered
+ * by test/test_texture.c with no GPU in sight. What is left here is a file
+ * read, one stb call and four GL calls, and it is kept this thin precisely so
+ * that "we don't unit-test it directly" is an honest position rather than a
+ * gap. `spec_core/rgame/core/image_spec.rb` exercises it end to end against a
+ * real GL context under Xvfb.
+ *
+ * ---------------------------------------------------------------------------
+ * What a handle is
+ * ---------------------------------------------------------------------------
+ *
+ * `struct rgame_image` is one `rgame_texture` view on the heap, plus the app it
+ * was uploaded into. The heap part exists only so the public API can be an
+ * opaque pointer; the view itself is a small value. Subimages and tiles
+ * allocate another one of these pointing at the same sheet, which is why
+ * slicing is cheap.
+ *
+ * The app pointer is carried because deleting a GL texture, like creating one,
+ * acts on whatever context is current — so freeing an image has to say which
+ * context it means. Each handle *retains* the app struct (not the window) for
+ * as long as it lives, which is what makes that pointer safe to follow even
+ * when the app was destroyed first. In that case the context is already gone,
+ * `rgame_app_gl_make_current` says so, and the deletion is skipped — correctly,
+ * because destroying a GL context frees every texture in it.
+ *
+ * That ordering is not hypothetical: Ruby can collect an app and its images in
+ * the same pass, and nothing specifies which is swept first.
+ */
+
+#include "rgame/core.h"
+
+#include "app/app_gl.h"
+#include "graphics/texture.h"
+#include "vendor/stb_image.h"
+
+#include <SDL2/SDL_opengl.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+struct rgame_image {
+    rgame_app *app; /* borrowed — the app owns the context these pixels live in */
+    rgame_texture view;
+};
+
+/* Writes a message into the caller's buffer, if they asked for one. Every
+ * failure path below goes through this so none of them can forget. */
+static void set_error(char *err, size_t err_size, const char *format, const char *detail) {
+    if (err && err_size > 0) {
+        snprintf(err, err_size, format, detail);
+    }
+}
+
+/*
+ * Reads a whole file into a malloc'd buffer.
+ *
+ * stb is built with STBI_NO_STDIO (see stb_image_impl.c) so that reading the
+ * file is our decision rather than the decoder's: one place decides how a
+ * missing file is reported, and the same code path will serve data that never
+ * was a file — an archive entry, or an asset baked into the gem.
+ */
+static unsigned char *read_whole_file(const char *path, long *out_size) {
+    FILE *file = fopen(path, "rb");
+    if (!file) {
+        return NULL;
+    }
+
+    /* Seek to the end and ask where we are: the portable way to get a file's
+     * size without a stat() that differs per platform. */
+    if (fseek(file, 0, SEEK_END) != 0) {
+        fclose(file);
+        return NULL;
+    }
+    long size = ftell(file);
+    if (size <= 0) {
+        fclose(file);
+        return NULL;
+    }
+    rewind(file);
+
+    unsigned char *bytes = malloc((size_t)size);
+    if (!bytes) {
+        fclose(file);
+        return NULL;
+    }
+
+    /* A short read means a truncated or vanishing file; treat it as a failure
+     * rather than handing the decoder a partly-filled buffer. */
+    size_t got = fread(bytes, 1, (size_t)size, file);
+    fclose(file);
+    if (got != (size_t)size) {
+        free(bytes);
+        return NULL;
+    }
+
+    *out_size = size;
+    return bytes;
+}
+
+/*
+ * Uploads RGBA8 pixels and returns the GL texture name, or 0 on failure.
+ *
+ * `pixels` is tightly packed, top row first — which is the order stb decodes
+ * in, and the order texture.c's UVs assume (v increases downwards). Uploading
+ * bottom-up instead is the classic way every sprite ends up mirrored.
+ */
+static unsigned int upload_rgba(const unsigned char *pixels, int width, int height) {
+    unsigned int name = 0;
+    glGenTextures(1, &name);
+    if (name == 0) {
+        return 0;
+    }
+
+    glBindTexture(GL_TEXTURE_2D, name);
+
+    /* Rows are 4 bytes per pixel so they are already 4-byte aligned, but GL's
+     * default alignment of 4 is a trap waiting for the day something uploads
+     * 3-byte or 1-byte pixels; saying 1 makes the upload independent of it. */
+    glPixelStorei(GL_UNPACK_ALIGNMENT, 1);
+
+    /* Nearest-neighbour, always: this engine draws pixel art, and there is no
+     * case where blurring it on scale-up is what was wanted. */
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_NEAREST);
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_NEAREST);
+
+    /* Clamp rather than repeat. Sprites come from a shared sheet, so a UV that
+     * slips a hair past an edge should pick up that edge's own pixel — with
+     * GL_REPEAT it wraps to the far side of the *sheet* and paints a stripe of
+     * an unrelated sprite. */
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_S, GL_CLAMP_TO_EDGE);
+    glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_WRAP_T, GL_CLAMP_TO_EDGE);
+
+    glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA, width, height, 0, GL_RGBA, GL_UNSIGNED_BYTE, pixels);
+    glBindTexture(GL_TEXTURE_2D, 0);
+
+    return name;
+}
+
+/* Wraps a view in a handle, releasing the view again if the allocation fails —
+ * so a failed subimage does not strand a reference on the sheet forever. */
+static rgame_image *wrap(rgame_app *app, rgame_texture view) {
+    rgame_image *image = malloc(sizeof(rgame_image));
+    if (!image) {
+        unsigned int orphan = 0;
+        if (rgame_texture_destroy(&view, &orphan)) {
+            rgame_gl_context_save saved;
+            if (rgame_app_gl_make_current(app, &saved)) {
+                glDeleteTextures(1, &orphan);
+            }
+            rgame_app_gl_restore(&saved);
+        }
+        return NULL;
+    }
+
+    rgame_app_gl_retain(app);
+    image->app = app;
+    image->view = view;
+    return image;
+}
+
+rgame_image *rgame_image_load(rgame_app *app, const char *path, char *err, size_t err_size) {
+    if (!app || !path) {
+        set_error(err, err_size, "%s", "no app or path given");
+        return NULL;
+    }
+
+    /* Loading is allowed mid-frame, and a game with two windows may well be
+     * mid-frame in the *other* one, so whatever was current goes back at every
+     * exit below. */
+    rgame_gl_context_save saved;
+    if (!rgame_app_gl_make_current(app, &saved)) {
+        rgame_app_gl_restore(&saved);
+        set_error(err, err_size, "%s", "could not make the app's GL context current");
+        return NULL;
+    }
+
+    long size = 0;
+    unsigned char *bytes = read_whole_file(path, &size);
+    if (!bytes) {
+        rgame_app_gl_restore(&saved);
+        set_error(err, err_size, "could not read %s", path);
+        return NULL;
+    }
+
+    /* The trailing 4 asks stb for four channels whatever the file has, so a
+     * greyscale or palette PNG arrives as RGBA too and the upload below has
+     * exactly one format to handle. */
+    int width = 0, height = 0, channels_in_file = 0;
+    unsigned char *pixels = stbi_load_from_memory(bytes, (int)size, &width, &height,
+                                                  &channels_in_file, 4);
+    free(bytes);
+    if (!pixels) {
+        rgame_app_gl_restore(&saved);
+        set_error(err, err_size, "could not decode %s", path);
+        return NULL;
+    }
+
+    unsigned int name = upload_rgba(pixels, width, height);
+    stbi_image_free(pixels);
+    if (name == 0) {
+        rgame_app_gl_restore(&saved);
+        set_error(err, err_size, "%s", "GL refused to allocate a texture");
+        return NULL;
+    }
+
+    rgame_texture_sheet *sheet = rgame_texture_sheet_create(name, width, height);
+    if (!sheet) {
+        glDeleteTextures(1, &name);
+        rgame_app_gl_restore(&saved);
+        set_error(err, err_size, "%s", "out of memory");
+        return NULL;
+    }
+
+    /* The sheet is created with one reference and the view takes a second, so
+     * hand back the creation reference: from here the handles own it. */
+    rgame_texture view = rgame_texture_whole(sheet);
+    rgame_texture_sheet_release(sheet, NULL);
+
+    rgame_image *image = wrap(app, view);
+    rgame_app_gl_restore(&saved);
+    if (!image) {
+        set_error(err, err_size, "%s", "out of memory");
+    }
+    return image;
+}
+
+rgame_image *rgame_image_subimage(const rgame_image *image, int x, int y, int width, int height) {
+    if (!image) {
+        return NULL;
+    }
+
+    rgame_texture view = {0};
+    if (!rgame_texture_subimage(&image->view, x, y, width, height, &view)) {
+        return NULL;
+    }
+
+    return wrap(image->app, view);
+}
+
+int rgame_image_tile_count(const rgame_image *image, int tile_width, int tile_height) {
+    return image ? rgame_texture_tile_count(&image->view, tile_width, tile_height) : 0;
+}
+
+rgame_image *rgame_image_tile(const rgame_image *image, int tile_width, int tile_height,
+                              int index) {
+    if (!image) {
+        return NULL;
+    }
+
+    rgame_texture view = {0};
+    if (!rgame_texture_tile(&image->view, tile_width, tile_height, index, &view)) {
+        return NULL;
+    }
+
+    return wrap(image->app, view);
+}
+
+int rgame_image_width(const rgame_image *image) {
+    return image ? rgame_texture_width(&image->view) : 0;
+}
+
+int rgame_image_height(const rgame_image *image) {
+    return image ? rgame_texture_height(&image->view) : 0;
+}
+
+const rgame_texture *rgame_image_view(const rgame_image *image) {
+    return image ? &image->view : NULL;
+}
+
+rgame_app *rgame_image_owner(const rgame_image *image) {
+    return image ? image->app : NULL;
+}
+
+void rgame_image_destroy(rgame_image *image) {
+    if (!image) {
+        return;
+    }
+
+    /* Only the *last* handle on a sheet gets a name back to delete, which is
+     * how dropping a sprite sheet while its tiles are still alive stays safe.
+     *
+     * make_current fails when the app was destroyed first, and skipping the
+     * deletion is then the right answer rather than a leak: tearing down a GL
+     * context takes its textures with it. */
+    unsigned int name = 0;
+    if (rgame_texture_destroy(&image->view, &name)) {
+        rgame_gl_context_save saved;
+        if (rgame_app_gl_make_current(image->app, &saved)) {
+            glDeleteTextures(1, &name);
+        }
+        /* Always restored, including when the switch failed: a collector runs
+         * this at an arbitrary moment, quite possibly in the middle of another
+         * window's frame, and that frame still has to be submitted into its own
+         * context. */
+        rgame_app_gl_restore(&saved);
+    }
+    rgame_app_gl_release(image->app);
+    free(image);
+}

data/ext/rgame_core/graphics/image_internal.h

@@ -0,0 +1,30 @@
+#ifndef RGAME_IMAGE_INTERNAL_H
+#define RGAME_IMAGE_INTERNAL_H
+
+#include "rgame/core.h"
+#include "graphics/texture.h"
+
+/*
+ * The texture view inside an image handle.
+ *
+ * `rgame_image` is opaque in the public header, and stays that way: a caller
+ * outside this extension has no business knowing what a texture view is. But
+ * the drawing path does — app.c has to hand the view to primitives.c — so the
+ * accessor lives here, in a header that is not under include/ and therefore
+ * cannot leave ext/rgame_core/.
+ *
+ * Returns NULL for a NULL image. The view belongs to the image; it must not be
+ * destroyed by the caller.
+ */
+const rgame_texture *rgame_image_view(const rgame_image *image);
+
+/*
+ * The app whose GL context this image was uploaded into, or NULL.
+ *
+ * Textures are not shared between contexts, so drawing an image through a
+ * *different* app samples nothing and paints a plain white quad — no GL error,
+ * no clue. The draw path compares owners so that this can be reported instead.
+ */
+rgame_app *rgame_image_owner(const rgame_image *image);
+
+#endif /* RGAME_IMAGE_INTERNAL_H */

data/ext/rgame_core/graphics/primitives.c

@@ -0,0 +1,189 @@
+/*
+ * primitives.c — rectangles, lines, circles and images, in terms of the
+ * canvas's triangles and quads. Pure; see primitives.h.
+ */
+
+#include "graphics/primitives.h"
+
+#include <math.h>
+
+/* math.h only promises M_PI under POSIX, and -std=c17 asks for strict ISO C,
+ * which hides it. Spelling it out here is one line and portable. */
+#define RGAME_TWO_PI 6.283185307179586f
+
+void rgame_prim_rect(rgame_canvas *canvas, float x, float y, float width, float height,
+                     rgame_color color, double z) {
+    float xy8[8] = {
+        x, y,
+        x + width, y,
+        x + width, y + height,
+        x, y + height,
+    };
+    rgame_canvas_quad(canvas, xy8, color, z);
+}
+
+void rgame_prim_line(rgame_canvas *canvas, float x1, float y1, float x2, float y2,
+                     float thickness, rgame_color color, double z) {
+    float dx = x2 - x1;
+    float dy = y2 - y1;
+    float length = sqrtf((dx * dx) + (dy * dy));
+    if (length == 0.0f) {
+        return;
+    }
+
+    /* Half the thickness, perpendicular to the direction of travel. Rotating a
+     * vector by 90 degrees swaps its components and negates one, which is where
+     * (dy, dx) comes from — and why the two corners on each end use opposite
+     * signs. */
+    float scale = (thickness / 2.0f) / length;
+    float ox = dy * scale;
+    float oy = dx * scale;
+
+    /* Loop order around the quad: the two corners at the start, then the two at
+     * the end, coming back along the other side. Listing them 1a, 2a, 2b, 1b
+     * (rather than 1a, 1b, 2a, 2b) is what keeps it a rectangle instead of an
+     * hourglass. */
+    float xy8[8] = {
+        x1 - ox, y1 + oy,
+        x2 - ox, y2 + oy,
+        x2 + ox, y2 - oy,
+        x1 + ox, y1 - oy,
+    };
+    rgame_canvas_quad(canvas, xy8, color, z);
+}
+
+void rgame_prim_circle(rgame_canvas *canvas, float cx, float cy, float radius, int segments,
+                       rgame_color color, double z) {
+    if (segments < 3 || radius <= 0.0f) {
+        return;
+    }
+
+    float step = RGAME_TWO_PI / (float)segments;
+    for (int i = 0; i < segments; i++) {
+        float a0 = step * (float)i;
+        float a1 = step * (float)(i + 1);
+
+        /* Every wedge starts at the centre, so the fan closes exactly: the last
+         * wedge's far edge is computed from segment count, not accumulated, and
+         * cannot drift into a visible gap. */
+        float xy6[6] = {
+            cx, cy,
+            cx + (cosf(a0) * radius), cy + (sinf(a0) * radius),
+            cx + (cosf(a1) * radius), cy + (sinf(a1) * radius),
+        };
+        rgame_canvas_triangle(canvas, xy6, color, z);
+    }
+}
+
+/*
+ * The four corners of `width` x `height` at (x, y), plus the view's texture
+ * coordinates, in the one corner order everything here uses.
+ *
+ * `flip_x`/`flip_y` mirror the *coordinates*, not the geometry: the corners are
+ * in loop order — TL, TR, BR, BL — so a horizontal mirror exchanges the `u` of
+ * the two top corners and of the two bottom ones. Doing it here rather than by
+ * handing in a negative width is what keeps the drawn rectangle exactly where
+ * the caller put it.
+ */
+static void textured_rect(rgame_canvas *canvas, const rgame_texture *view, float x, float y,
+                          float width, float height, int flip_x, int flip_y, rgame_color color,
+                          double z) {
+    float xy8[8] = {
+        x, y,
+        x + width, y,
+        x + width, y + height,
+        x, y + height,
+    };
+    float uv8[8];
+    rgame_texture_uv(view, uv8);
+
+    float swap;
+    if (flip_x) {
+        swap = uv8[0]; uv8[0] = uv8[2]; uv8[2] = swap; /* u of TL and TR */
+        swap = uv8[6]; uv8[6] = uv8[4]; uv8[4] = swap; /* u of BL and BR */
+    }
+    if (flip_y) {
+        swap = uv8[1]; uv8[1] = uv8[7]; uv8[7] = swap; /* v of TL and BL */
+        swap = uv8[3]; uv8[3] = uv8[5]; uv8[5] = swap; /* v of TR and BR */
+    }
+
+    rgame_canvas_textured_quad(canvas, rgame_texture_name(view), xy8, uv8, color, z);
+}
+
+void rgame_prim_glyph(rgame_canvas *canvas, unsigned int texture, rgame_rect source,
+                      int page_width, int page_height, float x, float y, rgame_color color,
+                      double z) {
+    if (source.w <= 0 || source.h <= 0 || page_width <= 0 || page_height <= 0) {
+        return;
+    }
+
+    float xy8[8] = {
+        x, y,
+        x + (float)source.w, y,
+        x + (float)source.w, y + (float)source.h,
+        x, y + (float)source.h,
+    };
+
+    /* Normalised against the page, not the glyph — the same division
+     * rgame_texture_uv does, for the same reason: dividing by the glyph's own
+     * size would stretch every letter across the whole page. */
+    float u0 = (float)source.x / (float)page_width;
+    float v0 = (float)source.y / (float)page_height;
+    float u1 = (float)(source.x + source.w) / (float)page_width;
+    float v1 = (float)(source.y + source.h) / (float)page_height;
+
+    float uv8[8] = { u0, v0, u1, v0, u1, v1, u0, v1 };
+
+    rgame_canvas_textured_quad(canvas, texture, xy8, uv8, color, z);
+}
+
+void rgame_prim_image(rgame_canvas *canvas, const rgame_texture *view, float x, float y,
+                      rgame_color color, double z) {
+    rgame_prim_image_scaled(canvas, view, x, y, 1.0f, 1.0f, color, z);
+}
+
+void rgame_prim_image_scaled(rgame_canvas *canvas, const rgame_texture *view, float x, float y,
+                             float scale_x, float scale_y, rgame_color color, double z) {
+    if (!view || !view->sheet || scale_x == 0.0f || scale_y == 0.0f) {
+        return;
+    }
+
+    /* The sign selects the mirror and the magnitude the size, so the rectangle
+     * is always well-formed and the caller never has to work out which corner
+     * the arithmetic landed on. */
+    textured_rect(canvas, view, x, y, (float)rgame_texture_width(view) * fabsf(scale_x),
+                  (float)rgame_texture_height(view) * fabsf(scale_y), scale_x < 0.0f,
+                  scale_y < 0.0f, color, z);
+}
+
+void rgame_prim_image_rot(rgame_canvas *canvas, const rgame_texture *view, float cx, float cy,
+                          float angle_degrees, float scale, rgame_color color, double z) {
+    if (!view || !view->sheet) {
+        return;
+    }
+
+    float width = (float)rgame_texture_width(view);
+    float height = (float)rgame_texture_height(view);
+
+    /* The common case — a sprite drawn upright at its natural size — is one
+     * quad and no stack traffic at all. */
+    if (angle_degrees == 0.0f && scale == 1.0f) {
+        textured_rect(canvas, view, cx - (width / 2.0f), cy - (height / 2.0f), width, height, 0,
+                      0, color, z);
+        return;
+    }
+
+    /* Otherwise place the quad at the origin and move the *world* to it:
+     * translate to the centre, rotate about it, scale. Reusing the transform
+     * stack means the direction a positive angle turns is decided in exactly
+     * one place (transform.c), not re-derived here with a sign to get wrong. */
+    rgame_canvas_push_translate(canvas, cx, cy);
+    rgame_canvas_push_rotate(canvas, angle_degrees, 0.0f, 0.0f);
+    rgame_canvas_push_scale(canvas, scale, scale);
+
+    textured_rect(canvas, view, -width / 2.0f, -height / 2.0f, width, height, 0, 0, color, z);
+
+    rgame_canvas_pop(canvas);
+    rgame_canvas_pop(canvas);
+    rgame_canvas_pop(canvas);
+}

data/ext/rgame_core/graphics/primitives.h

@@ -0,0 +1,111 @@
+#ifndef RGAME_PRIMITIVES_H
+#define RGAME_PRIMITIVES_H
+
+#include "graphics/canvas.h"
+#include "color.h"
+#include "graphics/texture.h"
+
+/*
+ * The shapes a game actually asks for, expressed in the two the canvas knows.
+ *
+ * A canvas draws triangles and quads. A game draws rectangles, lines, circles
+ * and sprites. This module is the translation, and it is pure — every function
+ * here turns arguments into `rgame_canvas_*` calls and touches nothing else,
+ * so `test/test_primitives.c` can check what a circle produces by reading the
+ * draw queue, with no GPU and no window.
+ *
+ * It sits between the Ruby renderer and the canvas rather than inside either,
+ * for the usual reason: a line's corner arithmetic is exactly the kind of thing
+ * that is wrong by a factor of two and looks *almost* right, and it should be
+ * checkable without a display.
+ *
+ * ---------------------------------------------------------------------------
+ * Corner order
+ * ---------------------------------------------------------------------------
+ *
+ * Everything here hands the canvas its four points in loop order — top-left,
+ * top-right, bottom-right, bottom-left — matching `rgame_canvas_quad` and the
+ * UV order `rgame_texture_uv` writes. Keeping one order everywhere is what
+ * makes textured drawing work without a second convention to translate.
+ */
+
+/* An axis-aligned filled rectangle. */
+void rgame_prim_rect(rgame_canvas *canvas, float x, float y, float width, float height,
+                     rgame_color color, double z);
+
+/*
+ * A line of real thickness from (x1,y1) to (x2,y2), as a quad offset
+ * perpendicular to its direction. GL's own line width is a suggestion drivers
+ * are free to ignore beyond 1px, so a line worth seeing has to be a shape.
+ *
+ * A zero-length line draws nothing rather than dividing by zero.
+ */
+void rgame_prim_line(rgame_canvas *canvas, float x1, float y1, float x2, float y2,
+                     float thickness, rgame_color color, double z);
+
+/*
+ * A filled circle as a fan of `segments` triangles around its centre.
+ *
+ * The layer being replaced cached a unit-circle *texture* and drew it scaled,
+ * because every triangle was a separate draw call there. With a batching queue
+ * the fan costs one batch, so the texture — and the render-to-texture support
+ * it needed — buys nothing. Fewer than 3 segments draws nothing.
+ */
+void rgame_prim_circle(rgame_canvas *canvas, float cx, float cy, float radius, int segments,
+                       rgame_color color, double z);
+
+/*
+ * An image with its *top-left* at (x, y), at its natural size. This is the
+ * backdrop case: no rotation, no scale, nothing to decide.
+ */
+void rgame_prim_image(rgame_canvas *canvas, const rgame_texture *view, float x, float y,
+                      rgame_color color, double z);
+
+/*
+ * An image with its top-left at (x, y), scaled independently per axis. The tile
+ * and sprite-frame case: a nine-slice corner drawn at 3x, a walk frame facing
+ * the other way.
+ *
+ * **A negative scale mirrors the image inside the same rectangle; it does not
+ * move it.** The drawn area is always (x, y) to (x + |w·scale_x|, y +
+ * |h·scale_y|), so the anchor means what it says whatever the sign — and
+ * `scale_x = -1` is "the same sprite, facing left", not "the same sprite, one
+ * width to the left". The layer being replaced had the other convention (Gosu
+ * mirrors *about* the anchor) and every caller of it compensated by adding a
+ * width back, which is a correction that is silently wrong the one time it is
+ * forgotten.
+ *
+ * A zero scale on either axis draws nothing rather than a degenerate quad.
+ */
+void rgame_prim_image_scaled(rgame_canvas *canvas, const rgame_texture *view, float x, float y,
+                             float scale_x, float scale_y, rgame_color color, double z);
+
+/*
+ * An image *centred* on (cx, cy), rotated `angle_degrees` clockwise about that
+ * centre and uniformly scaled — the sprite case, and the shape the layer being
+ * replaced exposed as `draw_rot`.
+ *
+ * The rotation goes through the canvas's own transform stack rather than a
+ * second sin/cos here, so there is exactly one place in the engine that decides
+ * which way a positive angle turns. An unrotated, unscaled image skips the
+ * stack entirely and emits the quad directly.
+ */
+void rgame_prim_image_rot(rgame_canvas *canvas, const rgame_texture *view, float cx, float cy,
+                          float angle_degrees, float scale, rgame_color color, double z);
+
+/*
+ * One glyph out of an atlas page, drawn 1:1 at (x, y).
+ *
+ * Separate from `rgame_prim_image` because a glyph's source is a rectangle of a
+ * shared page rather than a texture view — the page has no `rgame_texture`
+ * wrapped around it, and giving it one would mean a refcounted sheet per font
+ * page for no benefit. `page_width` and `page_height` are what the source rect
+ * is normalised against.
+ *
+ * A source rect with no pixels (a space) draws nothing.
+ */
+void rgame_prim_glyph(rgame_canvas *canvas, unsigned int texture, rgame_rect source,
+                      int page_width, int page_height, float x, float y, rgame_color color,
+                      double z);
+
+#endif /* RGAME_PRIMITIVES_H */