rgame 0.1.0 → 0.3.0

data/ext/rgame_core/include/rgame/core.h

@@ -19,8 +19,19 @@ extern "C" {
 
 typedef struct rgame_app rgame_app;
 
-/* Creates the window, GL context and internal state. Returns NULL on failure. */
-rgame_app *rgame_app_create(int width, int height, const char *title);
+/*
+ * Creates the window, GL context and internal state. Returns NULL on failure.
+ *
+ * `fullscreen` non-zero opens the window fullscreen straight away, rather than
+ * opening it windowed and switching after. The difference is visible: a switch
+ * made after creation shows one windowed frame first, which is the flash a
+ * player sees when a game starts up wrong.
+ *
+ * `width` and `height` still matter when starting fullscreen — they are the
+ * size the window returns to when it leaves fullscreen, and the size SDL keeps
+ * for it in the meantime.
+ */
+rgame_app *rgame_app_create(int width, int height, const char *title, int fullscreen);
 
 /* Destroys the GL context/window and frees the app. Safe to call with NULL. */
 void rgame_app_destroy(rgame_app *app);
@@ -52,16 +63,93 @@ void rgame_app_destroy(rgame_app *app);
 #define RGAME_BUTTON_GAMEPAD_FIRST 0x1000
 #define RGAME_BUTTON_GAMEPAD_LAST 0x10FF
 
-/* Keyboard ids == SDL scancodes. Only the keys the engine actually binds are
- * named; adding one is a #define plus a _Static_assert in app.c. */
+/* Keyboard ids == SDL scancodes, which are physical *positions* rather than
+ * letters: RGAME_KEY_A is the key marked A on a QWERTY board and Q on AZERTY.
+ * The set is what a Western keyboard can be relied on to have. No numpad (most
+ * laptops have none), no GUI/Windows/Command key, no print-screen cluster, and
+ * nothing whose position depends on the layout. Those can be added when
+ * something needs them; each is a #define plus a _Static_assert in app.c. */
+#define RGAME_KEY_A 4
+#define RGAME_KEY_B 5
+#define RGAME_KEY_C 6
+#define RGAME_KEY_D 7
+#define RGAME_KEY_E 8
+#define RGAME_KEY_F 9
+#define RGAME_KEY_G 10
+#define RGAME_KEY_H 11
+#define RGAME_KEY_I 12
+#define RGAME_KEY_J 13
+#define RGAME_KEY_K 14
+#define RGAME_KEY_L 15
+#define RGAME_KEY_M 16
+#define RGAME_KEY_N 17
+#define RGAME_KEY_O 18
+#define RGAME_KEY_P 19
+#define RGAME_KEY_Q 20
+#define RGAME_KEY_R 21
+#define RGAME_KEY_S 22
+#define RGAME_KEY_T 23
+#define RGAME_KEY_U 24
+#define RGAME_KEY_V 25
+#define RGAME_KEY_W 26
+#define RGAME_KEY_X 27
+#define RGAME_KEY_Y 28
+#define RGAME_KEY_Z 29
+#define RGAME_KEY_1 30
+#define RGAME_KEY_2 31
+#define RGAME_KEY_3 32
+#define RGAME_KEY_4 33
+#define RGAME_KEY_5 34
+#define RGAME_KEY_6 35
+#define RGAME_KEY_7 36
+#define RGAME_KEY_8 37
+#define RGAME_KEY_9 38
+#define RGAME_KEY_0 39
 #define RGAME_KEY_RETURN 40
 #define RGAME_KEY_ESCAPE 41
+#define RGAME_KEY_BACKSPACE 42
+#define RGAME_KEY_TAB 43
 #define RGAME_KEY_SPACE 44
+#define RGAME_KEY_MINUS 45
+#define RGAME_KEY_EQUALS 46
+#define RGAME_KEY_LEFTBRACKET 47
+#define RGAME_KEY_RIGHTBRACKET 48
+#define RGAME_KEY_BACKSLASH 49
+#define RGAME_KEY_SEMICOLON 51
+#define RGAME_KEY_APOSTROPHE 52
+#define RGAME_KEY_GRAVE 53
+#define RGAME_KEY_COMMA 54
+#define RGAME_KEY_PERIOD 55
+#define RGAME_KEY_SLASH 56
+#define RGAME_KEY_CAPSLOCK 57
 #define RGAME_KEY_F1 58
+#define RGAME_KEY_F2 59
+#define RGAME_KEY_F3 60
+#define RGAME_KEY_F4 61
+#define RGAME_KEY_F5 62
+#define RGAME_KEY_F6 63
+#define RGAME_KEY_F7 64
+#define RGAME_KEY_F8 65
+#define RGAME_KEY_F9 66
+#define RGAME_KEY_F10 67
+#define RGAME_KEY_F11 68
+#define RGAME_KEY_F12 69
+#define RGAME_KEY_INSERT 73
+#define RGAME_KEY_HOME 74
+#define RGAME_KEY_PAGEUP 75
+#define RGAME_KEY_DELETE 76
+#define RGAME_KEY_END 77
+#define RGAME_KEY_PAGEDOWN 78
 #define RGAME_KEY_RIGHT 79
 #define RGAME_KEY_LEFT 80
 #define RGAME_KEY_DOWN 81
 #define RGAME_KEY_UP 82
+#define RGAME_KEY_LCTRL 224
+#define RGAME_KEY_LSHIFT 225
+#define RGAME_KEY_LALT 226
+#define RGAME_KEY_RCTRL 228
+#define RGAME_KEY_RSHIFT 229
+#define RGAME_KEY_RALT 230
 
 /* Gamepad button ids: the gamepad range plus SDL's controller button number.
  * app.c asserts each against the SDL constant it mirrors, as with the keys. */
@@ -80,6 +168,12 @@ void rgame_app_destroy(rgame_app *app);
 #define RGAME_PAD_DPAD_DOWN (RGAME_BUTTON_GAMEPAD_FIRST + 12)
 #define RGAME_PAD_DPAD_LEFT (RGAME_BUTTON_GAMEPAD_FIRST + 13)
 #define RGAME_PAD_DPAD_RIGHT (RGAME_BUTTON_GAMEPAD_FIRST + 14)
+#define RGAME_PAD_MISC1 (RGAME_BUTTON_GAMEPAD_FIRST + 15)
+#define RGAME_PAD_PADDLE1 (RGAME_BUTTON_GAMEPAD_FIRST + 16)
+#define RGAME_PAD_PADDLE2 (RGAME_BUTTON_GAMEPAD_FIRST + 17)
+#define RGAME_PAD_PADDLE3 (RGAME_BUTTON_GAMEPAD_FIRST + 18)
+#define RGAME_PAD_PADDLE4 (RGAME_BUTTON_GAMEPAD_FIRST + 19)
+#define RGAME_PAD_TOUCHPAD (RGAME_BUTTON_GAMEPAD_FIRST + 20)
 
 /*
  * Analog axes are their own small id space rather than part of the button
@@ -121,6 +215,7 @@ void rgame_app_destroy(rgame_app *app);
 typedef void (*rgame_frame_begin_fn)(void *userdata);
 typedef void (*rgame_update_fn)(void *userdata, double dt_seconds);
 typedef void (*rgame_draw_fn)(void *userdata);
+typedef void (*rgame_frame_end_fn)(void *userdata);
 typedef int (*rgame_needs_redraw_fn)(void *userdata);
 typedef void (*rgame_button_fn)(void *userdata, int button_id);
 typedef void (*rgame_resize_fn)(void *userdata, int width, int height);
@@ -141,6 +236,12 @@ typedef void (*rgame_gamepad_fn)(void *userdata, int slot);
  *  - `needs_redraw` is polled before drawing; returning 0 skips the draw for
  *    that frame (simulation still advances). NULL means always redraw.
  *  - `draw` renders one frame.
+ *  - `frame_end` runs once per rendered frame, after that frame's drawing has
+ *    been submitted to the GPU but *before* the buffer swap — the only point
+ *    at which the frame just drawn can be read back deterministically. Never
+ *    called when `needs_redraw` skipped the draw. Rarely needed: it exists for
+ *    reading pixels back for a test, not for game code, since a real driver is
+ *    free to swap however it likes once `draw` returns.
  *  - `button_down`/`button_up` report discrete key presses and releases. Key
  *    repeats are filtered out, so holding a key reports exactly one press.
  *  - `resize` reports a new window size; the GL viewport is already updated.
@@ -154,6 +255,7 @@ typedef struct {
     rgame_update_fn update;
     rgame_needs_redraw_fn needs_redraw;
     rgame_draw_fn draw;
+    rgame_frame_end_fn frame_end;
     rgame_button_fn button_down;
     rgame_button_fn button_up;
     rgame_resize_fn resize;
@@ -181,6 +283,19 @@ void rgame_app_close(rgame_app *app);
 int rgame_app_width(const rgame_app *app);
 int rgame_app_height(const rgame_app *app);
 
+/*
+ * Fullscreen, toggled at any time. This is *desktop* fullscreen: the window
+ * takes the whole screen at the screen's own resolution, rather than asking the
+ * display to change mode. That makes the switch instant and reversible, costs
+ * no mode list to choose from, and leaves other windows where they were.
+ *
+ * Switching resizes the window, so the `resize` callback fires with the new
+ * size — the same path a user dragging a window edge takes. Nothing else needs
+ * telling.
+ */
+void rgame_app_set_fullscreen(rgame_app *app, int fullscreen);
+int rgame_app_fullscreen(const rgame_app *app);
+
 /* Window title. The returned string is owned by the window, not the caller. */
 const char *rgame_app_title(const rgame_app *app);
 void rgame_app_set_title(rgame_app *app, const char *title);
@@ -226,6 +341,18 @@ unsigned int rgame_app_ticks_ms(const rgame_app *app);
 /* Most recent frames-per-second reading (updated ~once per second). */
 double rgame_app_fps(const rgame_app *app);
 
+/*
+ * The user's preferred locales, most preferred first, written into `out` as
+ * "de-AT,en": a language, a hyphen and a country when the OS names one, and
+ * no trailing comma. Needs no app.
+ *
+ * Returns the length of the whole list, not counting the NUL, like snprintf:
+ * a result >= `capacity` means `out` holds a truncated prefix, and a buffer of
+ * result + 1 bytes fits it. `out` is always NUL-terminated when `capacity` is
+ * non-zero. Returns 0, with `out` empty, when the OS reports none.
+ */
+size_t rgame_preferred_locales(char *out, size_t capacity);
+
 /*
  * ---------------------------------------------------------------------------
  * Images
@@ -360,7 +487,7 @@ int rgame_app_draw_image_rot(rgame_app *app, const rgame_image *image, float cx,
                              float angle_degrees, float scale, unsigned int color, double z);
 
 /*
- * The transform and clip stacks. Every push is undone by the same
+ * The transform, clip and layer stacks. Every push is undone by the same
  * `rgame_app_pop`, so a caller can never pop the wrong one; a push that cannot
  * be honoured (a full stack) is still counted, so pops stay balanced and the
  * drawing comes out untransformed rather than desynchronised.
@@ -378,6 +505,25 @@ void rgame_app_push_scale(rgame_app *app, float sx, float sy);
  * always succeed as far as the caller is concerned.
  */
 int rgame_app_push_clip(rgame_app *app, int x, int y, int width, int height);
+
+/*
+ * The layer stack: what every subsequent `z` is measured from, until the
+ * matching pop. It *replaces* rather than accumulates, and starts at 0, so a
+ * caller that never pushes one gets exactly the z it passes.
+ *
+ * `rgame_app_next_layer_slot` is the other half: one counter per band, reset at
+ * the start of each frame, handing out increasing indices. It counts and
+ * nothing more — what a band means, and how a slot index becomes a base, is
+ * decided a layer up (RGame::Util::Z). Bands outside 0..7 answer 0.
+ *
+ * Together they are how a scene graph gives each node its own narrow window of
+ * z values: the traversal takes the next slot as it reaches a node, so draw
+ * order is tree order, and a node's `z:` can only reorder its own drawing.
+ */
+void rgame_app_push_layer(rgame_app *app, double base);
+double rgame_app_layer(rgame_app *app);
+unsigned int rgame_app_next_layer_slot(rgame_app *app, int band);
+
 void rgame_app_pop(rgame_app *app);
 
 /*

data/ext/rgame_core/input/gamepad.c

@@ -11,15 +11,69 @@ _Static_assert(RGAME_GAMEPAD_AXIS_COUNT == SDL_CONTROLLER_AXIS_MAX,
 
 /* Gamepad button ids are the gamepad range plus SDL's own button number, so
  * each named id must line up with the SDL constant it mirrors. */
-_Static_assert(RGAME_PAD_A == RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_A,
+_Static_assert(RGAME_PAD_A ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_A,
                "pad id must match SDL controller button");
-_Static_assert(RGAME_PAD_START == RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_START,
+_Static_assert(RGAME_PAD_B ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_B,
                "pad id must match SDL controller button");
-_Static_assert(RGAME_PAD_DPAD_UP == RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_DPAD_UP,
+_Static_assert(RGAME_PAD_X ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_X,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_Y ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_Y,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_BACK ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_BACK,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_GUIDE ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_GUIDE,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_START ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_START,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_LEFT_STICK ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_LEFTSTICK,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_RIGHT_STICK ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_RIGHTSTICK,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_LEFT_SHOULDER ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_LEFTSHOULDER,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_RIGHT_SHOULDER ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_RIGHTSHOULDER,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_DPAD_UP ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_DPAD_UP,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_DPAD_DOWN ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_DPAD_DOWN,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_DPAD_LEFT ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_DPAD_LEFT,
                "pad id must match SDL controller button");
 _Static_assert(RGAME_PAD_DPAD_RIGHT ==
                    RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_DPAD_RIGHT,
                "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_MISC1 ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_MISC1,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_PADDLE1 ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_PADDLE1,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_PADDLE2 ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_PADDLE2,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_PADDLE3 ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_PADDLE3,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_PADDLE4 ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_PADDLE4,
+               "pad id must match SDL controller button");
+_Static_assert(RGAME_PAD_TOUCHPAD ==
+                   RGAME_BUTTON_GAMEPAD_FIRST + SDL_CONTROLLER_BUTTON_TOUCHPAD,
+               "pad id must match SDL controller button");
 _Static_assert(RGAME_AXIS_LEFT_X == SDL_CONTROLLER_AXIS_LEFTX, "axis id must match SDL axis");
 _Static_assert(RGAME_AXIS_TRIGGER_RIGHT == SDL_CONTROLLER_AXIS_TRIGGERRIGHT,
                "axis id must match SDL axis");

data/ext/rgame_core/ruby/audio_ext.c

@@ -114,10 +114,15 @@ static VALUE audio_s_debug_live_sounds(VALUE klass) {
  * ------------------------------------------------------------------------- */
 
 /*
- * Both wrap a C handle plus the Ruby Audio it came from. Marking the device is
- * what stops the collector taking it first: the sound is a voice inside that
- * device's mixer, and freeing the mixer out from under it would be a crash at
- * an unpredictable moment.
+ * Both wrap a C handle plus the Ruby Audio it came from. Marking the device
+ * keeps it alive for as long as any sound made from it is *reachable*: the
+ * sound is a voice inside that device's mixer, and freeing the mixer out from
+ * under a live sound would be a crash at an unpredictable moment.
+ *
+ * It is only half the guarantee, and the half it leaves out is worth knowing.
+ * When a sound and its device become garbage in the same collection, marking
+ * has nothing left to say and the sweep frees them in whatever order it reaches
+ * them. audio.c refcounts the device for that case; see audio_release there.
  */
 typedef struct {
     void *handle; /* rgame_sample * or rgame_song * */
@@ -312,7 +317,7 @@ void rgame_init_audio(VALUE mCore) {
     rb_define_class_under(cSong, "LoadError", rb_eStandardError);
     rb_define_alloc_func(cSong, song_alloc);
     rb_define_method(cSong, "initialize", song_initialize, 2);
-    rb_define_method(cSong, "play_looping", song_play, 1);
+    rb_define_private_method(cSong, "play_looping", song_play, 1);
     rb_define_method(cSong, "stop", song_stop, 0);
     rb_define_method(cSong, "playing?", song_playing_p, 0);
     rb_define_method(cSong, "looping?", song_looping_p, 0);

data/ext/rgame_core/ruby/core_ext.c

@@ -23,6 +23,9 @@
  *     def button_down(id); end   # discrete key press
  *     def button_up(id); end
  *     def frame_begin; end       # once per frame, before the tick batch
+ *     def frame_end; end         # after draw is submitted, before the swap —
+ *                                 # rarely needed; it exists for reading pixels
+ *                                 # back in a test, not for game code
  *     def resize(w, h); end
  *     def gamepad_connected(slot); end
  *     def gamepad_disconnected(slot); end
@@ -47,6 +50,7 @@
 static ID id_frame_begin;
 static ID id_update;
 static ID id_draw;
+static ID id_frame_end;
 static ID id_needs_redraw;
 static ID id_button_down;
 static ID id_button_up;
@@ -57,6 +61,7 @@ static ID id_width;
 static ID id_height;
 static ID id_caption;
 static ID id_media_root;
+static ID id_fullscreen;
 
 /* ------------------------------------------------------------------------- *
  * rgame_app lifetime, wrapped as a Ruby object
@@ -106,8 +111,9 @@ static VALUE app_alloc(VALUE klass) {
     return TypedData_Wrap_Struct(klass, &app_data_type, NULL);
 }
 
-/* App.new(width:, height:, caption:) — keyword arguments, matching the shape a
- * subclass's own initialize will forward to via super. */
+/* App.new(width:, height:, caption:, media_root:, fullscreen:) — keyword
+ * arguments, matching the shape a subclass's own initialize will forward to via
+ * super. The first three are required; the last two have defaults. */
 static VALUE app_initialize(int argc, VALUE *argv, VALUE self) {
     VALUE opts = Qnil;
     rb_scan_args(argc, argv, "0:", &opts); /* no positional args, keywords only */
@@ -115,14 +121,19 @@ static VALUE app_initialize(int argc, VALUE *argv, VALUE self) {
         rb_raise(rb_eArgError, "missing keywords: :width, :height, :caption");
     }
 
-    const ID keys[4] = { id_width, id_height, id_caption, id_media_root };
-    VALUE values[4];
-    /* 3 required, 1 optional: raises on a missing or unknown keyword. An absent
+    const ID keys[5] = { id_width, id_height, id_caption, id_media_root, id_fullscreen };
+    VALUE values[5];
+    /* 3 required, 2 optional: raises on a missing or unknown keyword. An absent
      * optional comes back as Qundef. */
-    rb_get_kwargs(opts, keys, 3, 1, values);
+    rb_get_kwargs(opts, keys, 3, 2, values);
 
+    /* Passed to create rather than set afterwards, so a game that starts
+     * fullscreen never shows a windowed frame first. RTEST treats both nil and
+     * false as off, so `fullscreen: settings[:fullscreen]` works with a key that
+     * is missing. */
     rgame_app *app = rgame_app_create(NUM2INT(values[0]), NUM2INT(values[1]),
-                                      StringValueCStr(values[2]));
+                                      StringValueCStr(values[2]),
+                                      values[4] != Qundef && RTEST(values[4]));
     if (!app) {
         rb_raise(rb_eRuntimeError, "failed to create rgame app");
     }
@@ -265,6 +276,10 @@ static void tramp_draw(void *userdata) {
     protected_call((run_state *)userdata, id_draw, 0, NULL);
 }
 
+static void tramp_frame_end(void *userdata) {
+    protected_call((run_state *)userdata, id_frame_end, 0, NULL);
+}
+
 static int tramp_needs_redraw(void *userdata) {
     VALUE result = protected_call((run_state *)userdata, id_needs_redraw, 0, NULL);
     return RTEST(result) ? 1 : 0;
@@ -308,6 +323,7 @@ static VALUE app_run(VALUE self) {
         .update = tramp_update,
         .needs_redraw = tramp_needs_redraw,
         .draw = tramp_draw,
+        .frame_end = tramp_frame_end,
         .button_down = tramp_button_down,
         .button_up = tramp_button_up,
         .resize = tramp_resize,
@@ -354,6 +370,18 @@ static VALUE app_set_caption(VALUE self, VALUE title) {
     return title;
 }
 
+static VALUE app_fullscreen_p(VALUE self) {
+    return rgame_app_fullscreen(rgame_app_unwrap(self)) ? Qtrue : Qfalse;
+}
+
+/* Returns what it was given, as an assignment must in Ruby — so
+ * `app.fullscreen = settings.fullscreen?` reads back the value that was set,
+ * not the window's state. Read #fullscreen? for that. */
+static VALUE app_set_fullscreen(VALUE self, VALUE on) {
+    rgame_app_set_fullscreen(rgame_app_unwrap(self), RTEST(on));
+    return on;
+}
+
 /*
  * Raw input queries. These take the numeric device and button/axis ids from
  * RGame::Core::Input rather than symbolic action names — turning `:fire` into
@@ -421,6 +449,11 @@ static VALUE app_default_draw(VALUE self) {
     return Qnil;
 }
 
+static VALUE app_default_frame_end(VALUE self) {
+    (void)self;
+    return Qnil;
+}
+
 /* Default is "always redraw", matching a NULL needs_redraw in the C API. */
 static VALUE app_default_needs_redraw(VALUE self) {
     (void)self;
@@ -457,6 +490,7 @@ void Init_core_ext(void) {
     id_frame_begin = rb_intern("frame_begin");
     id_update = rb_intern("update");
     id_draw = rb_intern("draw");
+    id_frame_end = rb_intern("frame_end");
     id_needs_redraw = rb_intern("needs_redraw?");
     id_button_down = rb_intern("button_down");
     id_button_up = rb_intern("button_up");
@@ -467,6 +501,7 @@ void Init_core_ext(void) {
     id_height = rb_intern("height");
     id_caption = rb_intern("caption");
     id_media_root = rb_intern("media_root");
+    id_fullscreen = rb_intern("fullscreen");
 
     /*
      * rb_define_module is idempotent — it returns the existing RGame if some
@@ -486,6 +521,8 @@ void Init_core_ext(void) {
     rb_define_method(cApp, "height", app_height, 0);
     rb_define_method(cApp, "caption", app_caption, 0);
     rb_define_method(cApp, "caption=", app_set_caption, 1);
+    rb_define_method(cApp, "fullscreen?", app_fullscreen_p, 0);
+    rb_define_method(cApp, "fullscreen=", app_set_fullscreen, 1);
     rb_define_method(cApp, "ticks_ms", app_ticks_ms, 0);
     rb_define_method(cApp, "fps", app_fps, 0);
     rb_define_method(cApp, "input_down?", app_input_down_p, 2);
@@ -498,6 +535,7 @@ void Init_core_ext(void) {
     rb_define_method(cApp, "frame_begin", app_default_frame_begin, 0);
     rb_define_method(cApp, "update", app_default_update, 1);
     rb_define_method(cApp, "draw", app_default_draw, 0);
+    rb_define_method(cApp, "frame_end", app_default_frame_end, 0);
     rb_define_method(cApp, "needs_redraw?", app_default_needs_redraw, 0);
     rb_define_method(cApp, "button_down", app_default_button, 1);
     rb_define_method(cApp, "button_up", app_default_button, 1);
@@ -510,4 +548,5 @@ void Init_core_ext(void) {
     rgame_init_recording(mCore);
     rgame_init_font(mCore);
     rgame_init_audio(mCore);
+    rgame_init_locale(mCore);
 }

data/ext/rgame_core/ruby/core_ext.h

@@ -21,6 +21,9 @@ void rgame_init_renderer(VALUE mCore);
 void rgame_init_recording(VALUE mCore);
 void rgame_init_font(VALUE mCore);
 
+/* Not a class: RGame::Core.preferred_locales, a module function. */
+void rgame_init_locale(VALUE mCore);
+
 /* Defines Audio, Sample and Song together — see audio_ext.c for why those three
  * share a file when everything else here does not. */
 void rgame_init_audio(VALUE mCore);

data/ext/rgame_core/ruby/locale_ext.c

@@ -0,0 +1,44 @@
+/*
+ * locale_ext.c — the Ruby binding for RGame::Core.preferred_locales.
+ *
+ *   RGame::Core.preferred_locales   # => ["de-AT", "en"]
+ *
+ * A module function rather than an App method because SDL answers without an
+ * app, or even SDL_Init. The reading is locale.c; this file only sizes a buffer
+ * and splits the list. Choosing a language from the answer is
+ * RGame::Engine::I18n.choose, which the glue calls.
+ */
+
+#include "ruby/core_ext.h"
+
+#include "rgame/core.h"
+
+/*
+ * The user's preferred locales as Strings, most preferred first, or [] when the
+ * OS names none. Never contains nil or an empty String.
+ */
+static VALUE core_preferred_locales(VALUE self) {
+    (void)self;
+
+    char stack[256];
+    size_t length = rgame_preferred_locales(stack, sizeof stack);
+    if (length < sizeof stack) {
+        return rb_str_split(rb_utf8_str_new(stack, (long)length), ",");
+    }
+
+    /* Too long for the stack. The environment is read on every call, so the
+     * list can grow between two of them: size again until what was written fits. */
+    for (;;) {
+        VALUE list = rb_utf8_str_new(NULL, (long)length);
+        size_t written = rgame_preferred_locales(RSTRING_PTR(list), length + 1);
+        if (written <= length) {
+            rb_str_set_len(list, (long)written);
+            return rb_str_split(list, ",");
+        }
+        length = written;
+    }
+}
+
+void rgame_init_locale(VALUE mCore) {
+    rb_define_module_function(mCore, "preferred_locales", core_preferred_locales, 0);
+}

data/ext/rgame_core/ruby/recording_ext.c

@@ -176,7 +176,7 @@ void rgame_init_recording(VALUE mCore) {
 
     rb_define_alloc_func(cRecording, recording_alloc);
     rb_define_singleton_method(cRecording, "new", recording_s_new, -1);
-    rb_define_method(cRecording, "draw_at", recording_draw_at, 4);
+    rb_define_private_method(cRecording, "draw_at", recording_draw_at, 4);
     rb_define_method(cRecording, "batch_count", recording_batch_count, 0);
     rb_define_method(cRecording, "vertex_count", recording_vertex_count, 0);
     rb_define_method(cRecording, "empty?", recording_empty_p, 0);

data/ext/rgame_core/ruby/renderer_ext.c

@@ -297,6 +297,26 @@ static VALUE renderer_push_clip(VALUE self, VALUE x, VALUE y, VALUE width, VALUE
     return self;
 }
 
+/*
+ * #push_layer(base) / #layer — the base every subsequent z is measured from.
+ *
+ * `base` is a whole number well inside a double's exact range (see
+ * RGame::Util::Z), so it crosses as a double and comes back as a Float.
+ */
+static VALUE renderer_push_layer(VALUE self, VALUE base) {
+    rgame_app_push_layer(drawing_app(self), NUM2DBL(base));
+    return self;
+}
+
+static VALUE renderer_layer(VALUE self) {
+    return DBL2NUM(rgame_app_layer(drawing_app(self)));
+}
+
+/* #next_layer_slot(band) -> the next slot index in that band this frame. */
+static VALUE renderer_next_layer_slot(VALUE self, VALUE band) {
+    return UINT2NUM(rgame_app_next_layer_slot(drawing_app(self), NUM2INT(band)));
+}
+
 /* ------------------------------------------------------------------------- *
  * Recording
  *
@@ -354,23 +374,26 @@ void rgame_init_renderer(VALUE mCore) {
     rb_define_method(cRenderer, "drawing?", renderer_drawing_p, 0);
     rb_define_method(cRenderer, "app", renderer_app, 0);
 
-    rb_define_method(cRenderer, "draw_rect", renderer_draw_rect, 6);
-    rb_define_method(cRenderer, "draw_quad", renderer_draw_quad, -1);
-    rb_define_method(cRenderer, "draw_triangle", renderer_draw_triangle, -1);
-    rb_define_method(cRenderer, "draw_line", renderer_draw_line, -1);
-    rb_define_method(cRenderer, "draw_circle", renderer_draw_circle, -1);
-    rb_define_method(cRenderer, "draw_image", renderer_draw_image, 5);
-    rb_define_method(cRenderer, "draw_image_scaled", renderer_draw_image_scaled, -1);
-    rb_define_method(cRenderer, "draw_image_rot", renderer_draw_image_rot, -1);
-    rb_define_method(cRenderer, "draw_text", renderer_draw_text, -1);
-
-    rb_define_method(cRenderer, "push_translate", renderer_push_translate, 2);
-    rb_define_method(cRenderer, "push_rotate", renderer_push_rotate, 3);
-    rb_define_method(cRenderer, "push_scale", renderer_push_scale, 2);
-    rb_define_method(cRenderer, "push_clip", renderer_push_clip, 4);
-    rb_define_method(cRenderer, "pop", renderer_pop, 0);
-
-    rb_define_method(cRenderer, "begin_record", renderer_begin_record, 0);
-    rb_define_method(cRenderer, "end_record", renderer_end_record, 0);
-    rb_define_method(cRenderer, "cancel_record", renderer_cancel_record, 0);
+    rb_define_private_method(cRenderer, "draw_rect", renderer_draw_rect, 6);
+    rb_define_private_method(cRenderer, "draw_quad", renderer_draw_quad, -1);
+    rb_define_private_method(cRenderer, "draw_triangle", renderer_draw_triangle, -1);
+    rb_define_private_method(cRenderer, "draw_line", renderer_draw_line, -1);
+    rb_define_private_method(cRenderer, "draw_circle", renderer_draw_circle, -1);
+    rb_define_private_method(cRenderer, "draw_image", renderer_draw_image, 5);
+    rb_define_private_method(cRenderer, "draw_image_scaled", renderer_draw_image_scaled, -1);
+    rb_define_private_method(cRenderer, "draw_image_rot", renderer_draw_image_rot, -1);
+    rb_define_private_method(cRenderer, "draw_text", renderer_draw_text, -1);
+
+    rb_define_private_method(cRenderer, "push_translate", renderer_push_translate, 2);
+    rb_define_private_method(cRenderer, "push_rotate", renderer_push_rotate, 3);
+    rb_define_private_method(cRenderer, "push_scale", renderer_push_scale, 2);
+    rb_define_private_method(cRenderer, "push_clip", renderer_push_clip, 4);
+    rb_define_private_method(cRenderer, "push_layer", renderer_push_layer, 1);
+    rb_define_method(cRenderer, "layer", renderer_layer, 0);
+    rb_define_private_method(cRenderer, "next_layer_slot", renderer_next_layer_slot, 1);
+    rb_define_private_method(cRenderer, "pop", renderer_pop, 0);
+
+    rb_define_private_method(cRenderer, "begin_record", renderer_begin_record, 0);
+    rb_define_private_method(cRenderer, "end_record", renderer_end_record, 0);
+    rb_define_private_method(cRenderer, "cancel_record", renderer_cancel_record, 0);
 }

data/ext/rgame_util/color_ext.c

@@ -63,10 +63,19 @@ static VALUE color_s_new(int argc, VALUE *argv, VALUE klass) {
                                        NIL_P(a) ? 255 : component(a, "alpha")));
 }
 
-/* Color.from_packed(0xRRGGBBAA) */
+/* Color.from_packed(0xRRGGBBAA)
+ *
+ * The bounds check below needs a C type wider than 32 bits so a
+ * one-bit-too-wide value can be caught rather than silently truncated.
+ * `unsigned long` is that on Linux/macOS (LP64: 64 bits) but not on Windows
+ * (LLP64: `long` stays 32 bits even in a 64-bit build), where NUM2ULONG would
+ * itself raise RangeError on the very value this function means to turn into
+ * a clean ArgumentError. NUM2ULL is unsigned long long, 64 bits on every
+ * platform this project builds for, so the check below runs before either
+ * platform's integer width can get in the way. */
 static VALUE color_s_from_packed(VALUE klass, VALUE packed) {
-    unsigned long value = NUM2ULONG(packed);
-    if (value > 0xFFFFFFFFul) {
+    unsigned long long value = NUM2ULL(packed);
+    if (value > 0xFFFFFFFFull) {
         rb_raise(rb_eArgError, "packed colour must fit in 32 bits");
     }
     return color_wrap(klass, (rgame_color)value);