rgame 0.1.0 → 0.3.0

data/ext/rgame_core/example.rb

@@ -1,30 +1,5 @@
 # frozen_string_literal: true
 
-# Manual/visual smoke test for the core extension (layer 3 — the real
-# SDL/GL path). Build it first, then run this from the project root:
-#
-#   make ext-core
-#   ruby ext/rgame_core/example.rb
-#
-# It opens a window with one of each drawing primitive in it. Arrow keys (or a
-# controller's dpad/stick) move the marker; Escape or closing the window quits.
-# This is the Ruby-side mirror of src/main.c, and it exists to exercise every
-# callback and every draw call the engine offers.
-#
-# Pass a sound file (Ogg Vorbis or WAV) to check audio as well:
-#
-#   ruby ext/rgame_core/example.rb assets/theme.ogg
-#
-# Space plays it as a one-shot sample, Return starts and stops it as looping
-# music. There is no asset here to default to, and that is on purpose: this is
-# the only place a *real* sound device is driven — every automated test runs
-# against a null or offline one — so what it is worth checking is your own
-# file, out of your own speakers.
-#
-# The load path points at lib/, not at this directory: `make ext-core`
-# copies the built core_ext.so to lib/rgame/, so this runs against exactly
-# the layout a user of the library would see.
-
 $LOAD_PATH.unshift File.expand_path('../../lib', __dir__)
 require 'rgame'
 require 'rgame/core'
@@ -41,8 +16,6 @@ class Example < RGame::Core::App
   YELLOW = Color.new(224, 192, 64)
   TRANSLUCENT_WHITE = Color.new(255, 255, 255, 128)
 
-  # Frozen and chosen between rather than built: #draw runs sixty times a
-  # second, and a string per frame is a garbage collection waiting to happen.
   AUDIO_HINT_NONE = 'audio: pass a sound file on the command line to try it'
   AUDIO_HINT_STOPPED = 'audio: Space plays a sample, Return starts the music'
   AUDIO_HINT_PLAYING = 'audio: Space plays a sample, Return stops the music'
@@ -62,10 +35,6 @@ class Example < RGame::Core::App
     @baked = nil
     @device = Controls::KEYBOARD
 
-    # The device is opened whether or not there is anything to play through it,
-    # so that starting with no sound card takes the same path as starting with
-    # one. Nothing here is tied to the window: audio has no GL context and
-    # survives one being recreated.
     @audio = RGame::Core::Audio.new
     puts "audio backend: #{@audio.backend}"
     return unless sound_path
@@ -78,8 +47,6 @@ class Example < RGame::Core::App
   # here rather than per tick is the pattern the engine is shaped around — one
   # sample per frame, reused by however many catch-up ticks follow.
   def frame_begin
-    # Poll rather than track: Gamepad answers straight from the engine, so
-    # there is no local copy of the connection state to keep in step.
     @device = @pads.connected?(0) ? @pads.device(0) : Controls::KEYBOARD
   end
 
@@ -88,51 +55,48 @@ 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)
-
-    # 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 -= 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)
+
+    @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.
   def draw
     r = @renderer
 
-    # Baked on the first frame and replayed after that: forty rectangles cost
-    # one call per frame instead of forty. A real game bakes its tile layers
-    # this way. Recording has to happen inside #draw, which is why it is here
-    # rather than in initialize.
     @baked ||= r.record do
       40.times { |i| r.rect(i * 18, 0, 12, 12, color: GREEN, z: 0) }
     end
-    # Scrolls with the same value the spinning square turns by, so it is
-    # visibly the *replay* moving and not a rebake.
     @baked.draw((@spin % 18) - 18, 560)
     r.rect(40, 40, 160, 100, color: RED, z: 0)
-    # Higher z wins wherever they overlap, whatever order the calls came in.
     r.rect(120, 90, 160, 100, color: TRANSLUCENT_WHITE, z: 1)
     r.triangle(400, 40, 480, 180, 320, 180, color: GREEN, z: 0)
     r.circle(620, 110, 70, color: BLUE, z: 0)
     r.line(40, 240, 760, 240, thickness: 6, color: YELLOW, z: 0)
 
-    # The transform stack: a square turning about its own centre.
     r.rotated(@spin, 400, 380) { r.rect(340, 320, 120, 120, color: GREEN, z: 0) }
 
-    # The clip stack: the rectangle is twice the size of what shows.
     r.clipped(60, 480, 200, 80) { r.rect(60, 440, 400, 160, color: RED, z: 0) }
 
-    # The cursor the arrow keys move.
     r.debug_box(@cursor_x - 8, @cursor_y - 8, 16, 16)
 
-    # Text, including accents and punctuation the shipped font has to cover, so
-    # a look at the window checks kerning and coverage at once. The second line
-    # is centred using text_width, which is what a UI actually does with it.
     r.text('rgame — Grüße, œuvre, 5 €', 40, 270, color: YELLOW)
     label = format('%d fps', fps)
     r.text(label, 400 - (r.text_width(label) / 2), 270 + r.text_height)
@@ -144,8 +108,6 @@ class Example < RGame::Core::App
   def button_down(id)
     case id
     when Controls::KEY_ESCAPE then close
-    # Held down, this is the overlap check: each press is another voice rather
-    # than a restart, so a fast run of them should pile up rather than stutter.
     when Controls::KEY_SPACE then @sample&.play
     when Controls::KEY_RETURN then toggle_music
     end

data/ext/rgame_core/extconf.rb

@@ -1,136 +1,51 @@
 # frozen_string_literal: true
 
-# extconf.rb — run by `ruby extconf.rb` to generate a Makefile via mkmf.
-#
-# mkmf is Ruby's "make makefile" library. It probes the system (headers,
-# libraries, pkg-config) and writes a Makefile that knows how to compile a
-# loadable extension (`core_ext.so`) against the running Ruby's headers.
-# This is the same tool that `gem install` uses under the hood, which is why the
-# root Makefile was written to look like what mkmf emits — the mental model
-# carries straight over.
-#
-# This is the SDL/OpenGL half of the project: everything under RGame::Core.
-# The graphics-free half lives in ../rgame_util (RGame::Util) and links none of
-# these libraries.
-
 require 'mkmf'
 
-# The engine sources live in this directory rather than a top-level src/:
-# `gem install` unpacks the gem and runs this script, and an extension must be
-# buildable from its own directory.
-#
-# They are grouped into subdirectories by subsystem (app, graphics, text, input,
-# audio) plus ruby/ for the Ruby-facing glue and vendor/ for third-party code.
-# mkmf's default is to compile every .c in the extension's *own* directory and
-# nothing deeper, so the source list has to be spelled out — which is what
-# $srcs and $VPATH below do.
-#
-#   $srcs  — what to compile. mkmf names each object after the source's
-#            *basename*, so the .o files land flat in this directory no matter
-#            how deep the .c was. Basenames therefore have to be unique across
-#            the subdirectories; mkmf aborts with "source files duplication" if
-#            they ever aren't, so that rule enforces itself.
-#   $VPATH — where make looks for a source when a rule names it by basename.
-#            The generic `.c.o` rule mkmf emits does exactly that, so without
-#            this every object would come up as a missing prerequisite.
-#
-# vendor/ contributes only its <name>_impl.c translation units. The libraries
-# themselves are #included *by* those files (stb_vorbis even ships as a .c), so
-# compiling them separately would duplicate every symbol in them.
 SOURCE_DIRS = %w[app graphics text input audio ruby].freeze
 
-# Dir.glob sorts its results, so the object list is the same on every machine.
 $srcs = SOURCE_DIRS.flat_map { |dir| Dir.glob("#{$srcdir}/#{dir}/*.c") } +
         Dir.glob("#{$srcdir}/vendor/*_impl.c")
 
 (SOURCE_DIRS + %w[vendor]).each { |dir| $VPATH << "$(srcdir)/#{dir}" }
 
-# The extension directory itself, so a cross-subsystem include names the folder
-# it comes from: graphics/canvas.c says `#include "graphics/clip.h"`, and text/
-# reaching into graphics/ is visible in the source rather than hidden in a
-# search path. It is also what resolves `#include "vendor/stb_image.h"`.
-# $(srcdir) stays literal here — make expands it, not Ruby.
 $INCFLAGS << ' -I$(srcdir)'
 
-# Public API header (include/rgame/core.h), so `#include "rgame/core.h"`
-# resolves.
 $INCFLAGS << ' -I$(srcdir)/include'
 
-# RGame::Util's colour header, for the RGBA byte order the renderer writes into
-# every vertex. It is header-only (static inline), so this creates no link
-# dependency between the two extensions — they stay separate .so files. Both
-# directories ship together in the gem, so the relative path holds there too.
 $INCFLAGS << ' -I$(srcdir)/../rgame_util'
 
-# SDL2: pkg_config("sdl2") shells out to pkg-config and folds the resulting
-# cflags and libs into mkmf's globals ($CFLAGS/$libs) for us. Returns nil if
-# SDL2 isn't found, so we can fail with a clear message instead of a confusing
-# 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.
-#
-# 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.
 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.)'
+case RbConfig::CONFIG['host_os']
+when /darwin/
+  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/
+  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
+  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.
 $libs = append_library($libs, 'pthread') if have_library('pthread')
 $libs = append_library($libs, 'dl') if have_library('dl')
 
-# Match the project's C standard and warning flags. Note: gnu17, not plain
-# c17 — Ruby's headers occasionally lean on GNU extensions, and gnu17 is a
-# superset of c17 so core.c (which targets c17) still compiles fine.
 $CFLAGS << ' -std=gnu17 -Wall -Wextra'
 
-# Emits the Makefile. "rgame/core_ext" -> loaded via
-# `require "rgame/core_ext"`, entry point Init_core_ext (the basename)
-# in core_ext.c. Namespacing it under rgame/ mirrors rgame/util_ext, keeps
-# both extensions off the top of the load path, and — importantly — leaves the
-# bare name "rgame" to lib/rgame.rb, which is the pure-Ruby entry point.
 create_makefile('rgame/core_ext')
 
-# The vendored implementations, compiled with warnings off (see
-# vendor/README.md). mkmf has no per-file flag setting, so the rules are
-# appended to the Makefile it just wrote. An explicit rule for a specific
-# target beats mkmf's generic .c.o suffix rule, so these are what get used for
-# those objects and nothing else.
-#
-# Written from one list rather than one block per library: a second hand-copied
-# rule is how the first one drifts. They are explicit rules rather than a `%`
-# pattern because mkmf's Makefiles are meant to work with whatever `make` the
-# platform has, and pattern rules are a GNU extension.
-#
-# `-w` comes last on the command line and switches every warning back off,
-# which is simpler and more robust than trying to subtract -Wall -Wextra from
-# $(CFLAGS) — everything else about how the extension compiles stays identical.
-# Each vendored library's implementation TU (<name>_impl.c) and the file it
-# instantiates. stb_vorbis is the odd one out: it ships as a .c, not a .h.
 VENDORED = {
   'stb_image' => 'stb_image.h',
   'stb_truetype' => 'stb_truetype.h',
@@ -148,18 +63,6 @@ File.open('Makefile', 'a') do |makefile|
     MAKE
   end
 
-  # Rebuild everything when any of our headers changes.
-  #
-  # mkmf emits `$(OBJS): $(HDRS)` for this, but it builds HDRS by globbing the
-  # extension's own directory only — with the headers a level down in
-  # graphics/, text/ and the rest, HDRS comes out empty and editing a header
-  # rebuilds *nothing*. That failure is silent: the build succeeds and links
-  # objects compiled against the previous version of the struct.
-  #
-  # One coarse dependency rather than a real per-object dependency scan, for the
-  # same reason the root Makefile treats the vendored sources as one list: this
-  # is a small project where a full rebuild costs seconds, and a hand-maintained
-  # dependency graph is a thing to get quietly wrong.
   headers = SOURCE_DIRS.flat_map { |dir| Dir.glob("#{$srcdir}/#{dir}/*.h") }
                        .map { |path| "$(srcdir)/#{path.delete_prefix("#{$srcdir}/")}" }
 

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);
 
 /*

data/ext/rgame_core/graphics/clip.c

@@ -1,5 +1,7 @@
 #include "graphics/clip.h"
 
+#include <stdint.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 };
@@ -30,20 +32,27 @@ rgame_rect rgame_rect_intersect(rgame_rect a, rgame_rect b) {
     }
 
     /*
-     * 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.
+     * Edges are computed in `int64_t` 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.
+     *
+     * `int64_t` rather than `long`: `long` is only 32 bits on Windows (LLP64),
+     * the same width as `int` there, so it does not actually buy the extra
+     * headroom this needs — found by UBSan under clang64, which is the only
+     * configuration that caught it (the intermediate overflow this guards
+     * against never occurs in Check's own test values on a 64-bit `long`
+     * platform, so plain Linux/macOS runs never exercise the bug either).
      */
-    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;
+    int64_t left = a.x > b.x ? a.x : b.x;
+    int64_t top = a.y > b.y ? a.y : b.y;
+    int64_t a_right = (int64_t)a.x + a.w;
+    int64_t b_right = (int64_t)b.x + b.w;
+    int64_t a_bottom = (int64_t)a.y + a.h;
+    int64_t b_bottom = (int64_t)b.y + b.h;
+    int64_t right = a_right < b_right ? a_right : b_right;
+    int64_t bottom = a_bottom < b_bottom ? a_bottom : b_bottom;
 
     if (right <= left || bottom <= top) {
         return RGAME_EMPTY_RECT;