rgame 0.1.0 → 0.2.0

data/ext/rgame_core/app/app.c

@@ -227,14 +227,168 @@ void rgame_app_gl_restore(const rgame_gl_context_save *saved) {
  * the compiler checks — it must not include SDL. These assertions close that
  * gap at compile time, so the two can never drift apart silently.
  */
-_Static_assert(RGAME_KEY_RETURN == SDL_SCANCODE_RETURN, "key id must match SDL scancode");
-_Static_assert(RGAME_KEY_ESCAPE == SDL_SCANCODE_ESCAPE, "key id must match SDL scancode");
-_Static_assert(RGAME_KEY_SPACE == SDL_SCANCODE_SPACE, "key id must match SDL scancode");
-_Static_assert(RGAME_KEY_F1 == SDL_SCANCODE_F1, "key id must match SDL scancode");
-_Static_assert(RGAME_KEY_RIGHT == SDL_SCANCODE_RIGHT, "key id must match SDL scancode");
-_Static_assert(RGAME_KEY_LEFT == SDL_SCANCODE_LEFT, "key id must match SDL scancode");
-_Static_assert(RGAME_KEY_DOWN == SDL_SCANCODE_DOWN, "key id must match SDL scancode");
-_Static_assert(RGAME_KEY_UP == SDL_SCANCODE_UP, "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_A == SDL_SCANCODE_A,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_B == SDL_SCANCODE_B,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_C == SDL_SCANCODE_C,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_D == SDL_SCANCODE_D,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_E == SDL_SCANCODE_E,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F == SDL_SCANCODE_F,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_G == SDL_SCANCODE_G,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_H == SDL_SCANCODE_H,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_I == SDL_SCANCODE_I,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_J == SDL_SCANCODE_J,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_K == SDL_SCANCODE_K,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_L == SDL_SCANCODE_L,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_M == SDL_SCANCODE_M,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_N == SDL_SCANCODE_N,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_O == SDL_SCANCODE_O,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_P == SDL_SCANCODE_P,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_Q == SDL_SCANCODE_Q,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_R == SDL_SCANCODE_R,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_S == SDL_SCANCODE_S,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_T == SDL_SCANCODE_T,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_U == SDL_SCANCODE_U,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_V == SDL_SCANCODE_V,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_W == SDL_SCANCODE_W,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_X == SDL_SCANCODE_X,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_Y == SDL_SCANCODE_Y,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_Z == SDL_SCANCODE_Z,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_1 == SDL_SCANCODE_1,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_2 == SDL_SCANCODE_2,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_3 == SDL_SCANCODE_3,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_4 == SDL_SCANCODE_4,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_5 == SDL_SCANCODE_5,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_6 == SDL_SCANCODE_6,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_7 == SDL_SCANCODE_7,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_8 == SDL_SCANCODE_8,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_9 == SDL_SCANCODE_9,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_0 == SDL_SCANCODE_0,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_RETURN == SDL_SCANCODE_RETURN,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_ESCAPE == SDL_SCANCODE_ESCAPE,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_BACKSPACE == SDL_SCANCODE_BACKSPACE,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_TAB == SDL_SCANCODE_TAB,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_SPACE == SDL_SCANCODE_SPACE,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_MINUS == SDL_SCANCODE_MINUS,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_EQUALS == SDL_SCANCODE_EQUALS,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_LEFTBRACKET == SDL_SCANCODE_LEFTBRACKET,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_RIGHTBRACKET == SDL_SCANCODE_RIGHTBRACKET,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_BACKSLASH == SDL_SCANCODE_BACKSLASH,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_SEMICOLON == SDL_SCANCODE_SEMICOLON,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_APOSTROPHE == SDL_SCANCODE_APOSTROPHE,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_GRAVE == SDL_SCANCODE_GRAVE,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_COMMA == SDL_SCANCODE_COMMA,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_PERIOD == SDL_SCANCODE_PERIOD,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_SLASH == SDL_SCANCODE_SLASH,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_CAPSLOCK == SDL_SCANCODE_CAPSLOCK,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F1 == SDL_SCANCODE_F1,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F2 == SDL_SCANCODE_F2,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F3 == SDL_SCANCODE_F3,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F4 == SDL_SCANCODE_F4,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F5 == SDL_SCANCODE_F5,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F6 == SDL_SCANCODE_F6,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F7 == SDL_SCANCODE_F7,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F8 == SDL_SCANCODE_F8,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F9 == SDL_SCANCODE_F9,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F10 == SDL_SCANCODE_F10,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F11 == SDL_SCANCODE_F11,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_F12 == SDL_SCANCODE_F12,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_INSERT == SDL_SCANCODE_INSERT,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_HOME == SDL_SCANCODE_HOME,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_PAGEUP == SDL_SCANCODE_PAGEUP,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_DELETE == SDL_SCANCODE_DELETE,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_END == SDL_SCANCODE_END,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_PAGEDOWN == SDL_SCANCODE_PAGEDOWN,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_RIGHT == SDL_SCANCODE_RIGHT,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_LEFT == SDL_SCANCODE_LEFT,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_DOWN == SDL_SCANCODE_DOWN,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_UP == SDL_SCANCODE_UP,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_LCTRL == SDL_SCANCODE_LCTRL,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_LSHIFT == SDL_SCANCODE_LSHIFT,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_LALT == SDL_SCANCODE_LALT,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_RCTRL == SDL_SCANCODE_RCTRL,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_RSHIFT == SDL_SCANCODE_RSHIFT,
+               "key id must match SDL scancode");
+_Static_assert(RGAME_KEY_RALT == SDL_SCANCODE_RALT,
+               "key id must match SDL scancode");
 
 /* The snapshot array must be exactly as long as SDL's keyboard state array,
  * since filling it is a straight copy. */
@@ -400,6 +554,9 @@ void rgame_app_run(rgame_app *app, const rgame_app_callbacks *cb) {
 
             rgame_draw_backend backend = rgame_gl_backend_table(&app->gl);
             rgame_canvas_submit(&app->canvas, &backend);
+            if (cb->frame_end) {
+                cb->frame_end(cb->userdata);
+            }
             SDL_GL_SwapWindow(app->window);
         }
     }
@@ -599,6 +756,23 @@ int rgame_app_push_clip(rgame_app *app, int x, int y, int width, int height) {
     return 1;
 }
 
+void rgame_app_push_layer(rgame_app *app, double base) {
+    rgame_canvas *canvas = drawing_canvas(app);
+    if (canvas) {
+        rgame_canvas_push_layer(canvas, base);
+    }
+}
+
+double rgame_app_layer(rgame_app *app) {
+    rgame_canvas *canvas = drawing_canvas(app);
+    return canvas ? rgame_canvas_layer(canvas) : 0.0;
+}
+
+unsigned int rgame_app_next_layer_slot(rgame_app *app, int band) {
+    rgame_canvas *canvas = drawing_canvas(app);
+    return canvas ? rgame_canvas_next_slot(canvas, band) : 0;
+}
+
 void rgame_app_pop(rgame_app *app) {
     rgame_canvas *canvas = drawing_canvas(app);
     if (canvas) {

data/ext/rgame_core/audio/audio.c

@@ -44,6 +44,15 @@
 struct rgame_audio {
     ma_resource_manager resources;
     ma_engine engine;
+    /*
+     * Set only on Windows, only when construction fell back to `noDevice`
+     * because there was nothing to open — see create_audio. Exists so
+     * rgame_audio_backend can still answer "Null" for this engine, matching
+     * what every other no-hardware case on every platform already reports,
+     * even though this engine has no `ma_device` at all for the normal
+     * lookup to find.
+     */
+    int forced_no_device;
 };
 
 struct rgame_sample {
@@ -131,6 +140,43 @@ static rgame_audio *create_audio(int offline, unsigned int sample_rate, char *er
      * no sound card — a build server, a container — gets a working engine that
      * plays silence rather than an error a game has to handle. Verified: with
      * ALSA and PulseAudio unavailable, the chosen backend is "Null".
+     *
+     * That fallback is *inside* the real backend's own device-open attempt —
+     * it only helps if opening fails cleanly. Verified on Linux, which is the
+     * one platform where it demonstrably does, and where an earlier attempt to
+     * generalise the workaround below broke a leg that had been working.
+     *
+     * On Windows, a machine with zero playback devices at all (every GitHub
+     * Actions Windows runner, among others: confirmed via
+     * `Get-CimInstance Win32_SoundDevice`) crashes instead of failing inside
+     * WASAPI's default-device lookup, so the fallback above never gets a
+     * chance to run.
+     *
+     * Windows alone gets an extra step first: enumerate devices (read-only,
+     * does not attempt to open anything, so it does not hit whatever WASAPI's
+     * own open path gets wrong with no endpoint to find) and, when there are
+     * none, fall back to `noDevice` — the same mode the offline constructor
+     * below uses — rather than the auto-detect list's own real-backend open
+     * attempt.
+     *
+     * macOS looks like the same bug and is not, which is worth stating because
+     * extending this branch to it does nothing. A device-less Mac still
+     * enumerates a playback device, so a zero-device test never fires there;
+     * its equivalent crash is CoreAudio being initialised in a **forked
+     * child**, which macOS forbids outright. That belongs to the test harness
+     * rather than here — see test/test_main.c.
+     *
+     * An *explicit* null-backend device was tried first and rejected: it still
+     * spins up a real background device thread, and that thread crashed inside
+     * a Ruby process in a way the plain-C Check build of the same code never
+     * did. `noDevice` sidesteps the question entirely: with no device and no
+     * background thread, there is nothing left that could crash the way a
+     * thread can.
+     *
+     * Linux is deliberately excluded rather than merely untested. Generalising
+     * this to every platform is what broke its leg once already, and its own
+     * fallback is proven — so the rule here is that a platform opts in on the
+     * strength of a measured crash, not on the logic looking harmless.
      */
     ma_engine_config engine = ma_engine_config_init();
     engine.pResourceManager = &audio->resources;
@@ -141,6 +187,24 @@ static rgame_audio *create_audio(int offline, unsigned int sample_rate, char *er
         engine.channels = 2;
         engine.sampleRate = sample_rate;
     }
+#ifdef _WIN32
+    else {
+        ma_context probe;
+        if (ma_context_init(NULL, 0, NULL, &probe) == MA_SUCCESS) {
+            ma_uint32 playback_count = 0;
+            ma_result enum_result =
+                ma_context_get_devices(&probe, NULL, &playback_count, NULL, NULL);
+            ma_context_uninit(&probe);
+
+            if (enum_result == MA_SUCCESS && playback_count == 0) {
+                engine.noDevice = MA_TRUE;
+                engine.channels = 2;
+                engine.sampleRate = 44100;
+                audio->forced_no_device = 1;
+            }
+        }
+    }
+#endif
 
     if (ma_engine_init(&engine, &audio->engine) != MA_SUCCESS) {
         ma_resource_manager_uninit(&audio->resources);
@@ -199,6 +263,16 @@ const char *rgame_audio_backend(const rgame_audio *audio) {
         return "none";
     }
 
+    /* The forced-noDevice fallback (see create_audio) has no ma_device for
+     * the normal lookup below to find, but it is standing in for exactly what
+     * the Null backend already means elsewhere — no hardware, silence — so it
+     * answers the same way rather than the more literal but less useful
+     * "none", which every other caller of this function reserves for "there
+     * is no audio object at all". */
+    if (audio->forced_no_device) {
+        return "Null";
+    }
+
     ma_device *device = ma_engine_get_device((ma_engine *)&audio->engine);
     return device ? ma_get_backend_name(device->pContext->backend) : "none";
 }

data/ext/rgame_core/example.rb

@@ -88,16 +88,27 @@ class Example < RGame::Core::App
     @ticks += 1
     @spin += dt * 45.0
     speed = 200.0 * dt
-    @cursor_x -= speed if @input.down?(:left, device: @device)
-    @cursor_x += speed if @input.down?(:right, device: @device)
-    @cursor_y -= speed if @input.down?(:up, device: @device)
-    @cursor_y += speed if @input.down?(:down, device: @device)
+    @cursor_x -= speed if held?(Controls::KEY_LEFT, Controls::PAD_DPAD_LEFT)
+    @cursor_x += speed if held?(Controls::KEY_RIGHT, Controls::PAD_DPAD_RIGHT)
+    @cursor_y -= speed if held?(Controls::KEY_UP, Controls::PAD_DPAD_UP)
+    @cursor_y += speed if held?(Controls::KEY_DOWN, Controls::PAD_DPAD_DOWN)
 
     # Analog sticks are additive on top of the dpad; the keyboard reads 0.0.
-    @cursor_x += @input.axis(:move_x, device: @device) * speed
-    @cursor_y += @input.axis(:move_y, device: @device) * speed
+    @cursor_x += @input.axis(Controls::AXIS_LEFT_X, device: @device) * speed
+    @cursor_y += @input.axis(Controls::AXIS_LEFT_Y, device: @device) * speed
   end
 
+  # Core is the raw layer: Input answers "is this scancode down on this device",
+  # and naming the key *and* the pad button for one intent is the caller's job.
+  # Asking both costs nothing, because a device only answers for its own kind of
+  # input — a gamepad reads false for a scancode.
+  #
+  # A game does not write this. RGame::Engine::InputMap is a table of exactly
+  # these pairs, one entry per action, and the scene graph reads named actions
+  # instead. This example is here to exercise Core on its own, so it does
+  # without that and shows what the layer above is for.
+  def held?(key, pad) = @input.down?(key, device: @device) || @input.down?(pad, device: @device)
+
   # One of everything, so a look at the window checks the whole drawing path.
   # Colours are RGame::Util::Color values rather than arrays: a Color is frozen
   # and allocates nothing when it is drawn, which is what per-frame code wants.

data/ext/rgame_core/extconf.rb

@@ -68,38 +68,66 @@ $INCFLAGS << ' -I$(srcdir)/../rgame_util'
 # later compile error.
 abort 'SDL2 not found (pkg-config --exists sdl2 failed). Install libsdl2-dev.' unless pkg_config('sdl2')
 
-# OpenGL + libm, matching the link line in the root Makefile. append_library
-# adds `-lGL`/`-lm` in the right spot on the link command.
+# The GL header, probed as the sources actually spell it: SDL's own
+# <SDL2/SDL_opengl.h>, which resolves to GL/gl.h, OpenGL/gl.h or the Windows SDK's
+# per platform. Probing GL/gl.h directly would ask the wrong question off Linux.
 #
-# Checked rather than assumed, unlike in the root Makefile. This script is what
-# runs on someone else's machine during `gem install`, and a missing OpenGL
-# development package is a routine thing to hit there. Without a check it
-# surfaces as a linker error about an undefined `glClear` at the end of a long
-# build; with one, the install stops on a sentence naming the package to
-# install. Same reasoning as the SDL2 abort above.
-#
-# The header probed is the one the sources actually include — SDL's own
-# <SDL2/SDL_opengl.h>, which resolves to GL/gl.h or OpenGL/gl.h per platform, so
-# probing GL/gl.h directly would ask the wrong question off Linux. It needs
-# SDL's cflags, which pkg_config folded into $CFLAGS just above.
+# It needs SDL's cflags, which pkg_config folded into $CFLAGS just above — this
+# is also what makes the probe a real check of the include path rather than of
+# the filesystem.
 abort 'SDL2 OpenGL header not found (SDL2/SDL_opengl.h). Install libsdl2-dev.' unless have_header('SDL2/SDL_opengl.h')
 
-# `-lGL` is how OpenGL is linked on Linux and the BSDs; macOS wants
-# `-framework OpenGL` instead. Only the first is implemented — as in the root
-# Makefile, which hardcodes -lGL — so this aborts on a platform it cannot link
-# rather than emitting undefined symbols for every gl* call. have_library
-# appends -lGL to $libs itself when the probe succeeds.
-unless have_library('GL', 'glClear')
-  abort 'OpenGL library not found (-lGL). Install libgl1-mesa-dev. ' \
-        '(macOS needs -framework OpenGL, which is not implemented yet.)'
+# Three platforms, three different ways to link the same OpenGL — the one place
+# in this file that has to branch, and the mirror of the root Makefile's own
+# branch (see its GL_LIBS). The engine calls only GL 1.1 entry points, which all
+# three expose directly, so no extension loader (GLAD/GLEW) is involved anywhere;
+# see CLAUDE.md's Conventions on why the legacy profile is deliberate.
+#
+# Probed rather than assumed, because this script is what runs on someone else's
+# machine during `gem install` and a missing OpenGL is a routine thing to hit
+# there. Without a probe it surfaces as a linker error about an undefined
+# `glClear` at the end of a long build; with one, the install stops on a
+# sentence naming what to install. Same reasoning as the SDL2 abort above — and
+# the message is per-platform, since "install libgl1-mesa-dev" is useless advice
+# on a Mac.
+#
+# `have_library` appends `-lGL`/`-lopengl32` to $libs on success; `have_framework`
+# appends `-framework OpenGL` to $LDFLAGS. Both end up on the link line.
+case RbConfig::CONFIG['host_os']
+when /darwin/
+  # macOS ships OpenGL as a framework rather than a library, so there is no
+  # `-lGL` to find. It is part of the OS — a failure here means the toolchain
+  # is missing, not the graphics stack.
+  unless have_framework('OpenGL')
+    abort 'OpenGL framework not found. It ships with macOS, so this usually means ' \
+          'the command line tools are missing: xcode-select --install'
+  end
+when /mingw|mswin|cygwin/
+  # Windows' OpenGL is an OS component: opengl32.dll is in system32 on every
+  # installation, and the import library comes with the toolchain. Nothing to
+  # install from a graphics vendor.
+  unless have_library('opengl32', 'glClear')
+    abort 'opengl32 not found. It is part of Windows itself, so this means an ' \
+          'incomplete MSYS2 toolchain: pacman -S mingw-w64-ucrt-x86_64-gcc'
+  end
+else
+  # Linux and the BSDs.
+  unless have_library('GL', 'glClear')
+    abort 'OpenGL library not found (-lGL). Install the OpenGL development package: ' \
+          'libgl1-mesa-dev on Debian/Ubuntu, mesa-libGL-devel on Fedora.'
+  end
 end
 
 $libs = append_library($libs, 'm')
 
 # miniaudio's threading, and the dlopen it uses to find ALSA or PulseAudio at
-# runtime — the property that makes audio cost no new system dependency. Both
-# live in glibc on Linux/BSD. Windows and macOS need neither, and appending them
-# unconditionally would fail the link there, so each is probed first.
+# runtime — the property that makes audio cost no new system dependency.
+#
+# Probed rather than branched, because unlike OpenGL above the *answer* differs
+# per platform but the question does not: link them where they exist. On
+# glibc both are system libraries nobody installs; macOS resolves `-lpthread`
+# into libSystem and needs no `-ldl`; MSYS2 supplies winpthreads. Appending
+# either unconditionally would break the link wherever it is absent.
 $libs = append_library($libs, 'pthread') if have_library('pthread')
 $libs = append_library($libs, 'dl') if have_library('dl')
 

data/ext/rgame_core/graphics/canvas.c

@@ -6,15 +6,26 @@
 enum {
     RGAME_PUSH_TRANSFORM,
     RGAME_PUSH_CLIP,
+    RGAME_PUSH_LAYER,
     /* 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
 };
 
+/* The layer stack and the per-band counters, both back to their frame start. */
+static void reset_layers(rgame_canvas *canvas) {
+    canvas->layers[0] = 0.0;
+    canvas->layer_depth = 0;
+    for (int i = 0; i < RGAME_LAYER_BANDS; i++) {
+        canvas->slots[i] = 0;
+    }
+}
+
 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);
+    reset_layers(canvas);
     canvas->push_depth = 0;
     canvas->unrecorded_pushes = 0;
     canvas->width = 0;
@@ -29,6 +40,7 @@ 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);
+    reset_layers(canvas);
     canvas->push_depth = 0;
     canvas->unrecorded_pushes = 0;
     canvas->width = width;
@@ -126,6 +138,26 @@ void rgame_canvas_push_clip(rgame_canvas *canvas, rgame_rect rect) {
     account_push(canvas, ok, RGAME_PUSH_CLIP);
 }
 
+void rgame_canvas_push_layer(rgame_canvas *canvas, double base) {
+    int ok = canvas->layer_depth + 1 < RGAME_LAYER_STACK_DEPTH;
+    if (ok) {
+        /* Replaces rather than accumulates: see canvas.h. */
+        canvas->layers[++canvas->layer_depth] = base;
+    }
+    account_push(canvas, ok, RGAME_PUSH_LAYER);
+}
+
+double rgame_canvas_layer(const rgame_canvas *canvas) {
+    return canvas->layers[canvas->layer_depth];
+}
+
+unsigned int rgame_canvas_next_slot(rgame_canvas *canvas, int band) {
+    if (band < 0 || band >= RGAME_LAYER_BANDS) {
+        return 0;
+    }
+    return canvas->slots[band]++;
+}
+
 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. */
@@ -144,11 +176,20 @@ void rgame_canvas_pop(rgame_canvas *canvas) {
     case RGAME_PUSH_CLIP:
         rgame_clip_pop(&canvas->clips);
         break;
+    case RGAME_PUSH_LAYER:
+        canvas->layer_depth--;
+        break;
     default:
         break; /* RGAME_PUSH_NOTHING: the push never took effect */
     }
 }
 
+/* Every z that reaches the queue is an offset from the current layer base. One
+ * addition, in the one place all four queueing paths pass through. */
+static double layer_z(const rgame_canvas *canvas, double z) {
+    return canvas->layers[canvas->layer_depth] + z;
+}
+
 /* 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,
@@ -161,7 +202,7 @@ static void write_vertex(const rgame_canvas *canvas, rgame_vertex *vertex, float
 
 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_vertex *out = rgame_draw_queue_alloc(&canvas->queue, 3, layer_z(canvas, 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);
@@ -172,7 +213,7 @@ void rgame_canvas_triangle(rgame_canvas *canvas, const float *xy6, rgame_color c
 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_vertex *out = rgame_draw_queue_alloc(&canvas->queue, 6, layer_z(canvas, z), 0,
                                                rgame_clip_current(&canvas->clips));
     for (int i = 0; i < 6; i++) {
         int corner = RGAME_QUAD_TRIANGLES[i];
@@ -183,7 +224,7 @@ void rgame_canvas_quad(rgame_canvas *canvas, const float *xy8, rgame_color 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_vertex *out = rgame_draw_queue_alloc(&canvas->queue, 6, layer_z(canvas, z), texture,
                                                rgame_clip_current(&canvas->clips));
     for (int i = 0; i < 6; i++) {
         int corner = RGAME_QUAD_TRIANGLES[i];
@@ -213,7 +254,7 @@ void rgame_canvas_replay(rgame_canvas *canvas, const rgame_recording *recording,
         /* 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,
+        rgame_vertex *out = rgame_draw_queue_alloc(&canvas->queue, batch->vertex_count, layer_z(canvas, z),
                                                    batch->texture,
                                                    rgame_clip_current(&canvas->clips));
 

data/ext/rgame_core/graphics/canvas.h

@@ -46,25 +46,67 @@
  * rotates a clip today.
  *
  * ---------------------------------------------------------------------------
+ * The layer stack: where a caller's z is measured from
+ * ---------------------------------------------------------------------------
+ *
+ * A `z` handed to a primitive is an *offset*, added to whatever base is on top
+ * of the layer stack. The stack starts at 0, so a caller that never pushes one
+ * gets exactly the z it passed.
+ *
+ * What it is for: the scene graph gives every node its own narrow window of z
+ * values, so a node's drawing can only ever be ordered against its own other
+ * drawing — never against another node's, and never out of the band it is in.
+ * Composing that is one addition here, and the alternative is every caller
+ * remembering to add the same number to every z it passes.
+ *
+ * `rgame_canvas_next_slot` is the other half: a small set of counters, one per
+ * band, reset at the start of each frame and handing out increasing indices. It
+ * is deliberately ignorant of what a band *is* — that vocabulary lives in
+ * RGame::Util::Z, a layer up — and does nothing but count, because "which node
+ * comes next" is already the order the draw traversal visits nodes in.
+ *
+ * A push *replaces* rather than adds. Nesting bases would re-introduce the
+ * additive relative z this design exists to remove: the point is that a node's
+ * window is decided by where the traversal reached it, not by summing what its
+ * ancestors happened to pick.
+ *
+ * ---------------------------------------------------------------------------
  * 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.
+ * `push_translate`, `push_rotate`, `push_scale`, `push_clip` and `push_layer`
+ * 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)
+/* Deep enough for any sane scene graph, like the two stacks it sits beside. */
+#define RGAME_LAYER_STACK_DEPTH 32
+
+/* How many independent slot counters a frame has. RGame::Util::Z uses four;
+ * the spare room costs four unsigned ints. */
+#define RGAME_LAYER_BANDS 8
+
+/* Deep enough that it cannot fill before all three 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 + RGAME_LAYER_STACK_DEPTH)
 
 typedef struct {
     rgame_transform_stack transforms;
     rgame_clip_stack clips;
     rgame_draw_queue queue;
 
+    /* entries[0] is 0 — the base an un-layered draw sits on — so `layer_depth`
+     * is the number of pushes outstanding and entries[layer_depth] is current. */
+    double layers[RGAME_LAYER_STACK_DEPTH];
+    int layer_depth;
+
+    /* Slots handed out per band this frame. Reset by begin_frame. */
+    unsigned int slots[RGAME_LAYER_BANDS];
+
     /* Which stack each outstanding push went to, so pop can undo the right one. */
     unsigned char pushes[RGAME_CANVAS_STACK_DEPTH];
     int push_depth;
@@ -79,8 +121,8 @@ 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
+ * Starts a frame: empties the queue (keeping its buffers), resets all three
+ * stacks and the slot counters, 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);
@@ -97,6 +139,19 @@ void rgame_canvas_push_scale(rgame_canvas *canvas, float sx, float sy);
  * transform before narrowing the clip. */
 void rgame_canvas_push_clip(rgame_canvas *canvas, rgame_rect rect);
 
+/* Sets the base every subsequent z is measured from, until the matching pop. */
+void rgame_canvas_push_layer(rgame_canvas *canvas, double base);
+
+/* The base currently in effect. */
+double rgame_canvas_layer(const rgame_canvas *canvas);
+
+/*
+ * The next slot index in `band`, counting from 0 each frame. Out-of-range bands
+ * answer 0 rather than reading past the array — a caller with a bad band gets
+ * everything piled in one slot, which is wrong but bounded.
+ */
+unsigned int rgame_canvas_next_slot(rgame_canvas *canvas, int band);
+
 void rgame_canvas_pop(rgame_canvas *canvas);
 
 /*