rgame 0.2.0 → 0.3.1

data/ext/rgame_core/app/locale.c

@@ -0,0 +1,67 @@
+/*
+ * locale.c — the user's preferred locales, as the operating system reports
+ * them through SDL.
+ *
+ * rgame_preferred_locales is a thin shim over SDL_GetPreferredLocales; the
+ * joining and the buffer contract are rgame_locale_append, which is pure and
+ * Check-tested. Choosing among the locales is not here at all: it is
+ * RGame::Engine::I18n.choose, specced headless.
+ *
+ * SDL answers without SDL_Init (measured on 2.0.20 under Linux, where it reads
+ * LANG and then LANGUAGE), so none of this belongs to an app.
+ */
+
+#include "app/locale.h"
+
+#include <SDL2/SDL.h>
+#include <string.h>
+
+#include "rgame/core.h"
+
+static size_t append_text(char *out, size_t capacity, size_t length, const char *text) {
+    for (; *text; text++, length++) {
+        if (length + 1 < capacity) {
+            out[length] = *text;
+        }
+    }
+    return length;
+}
+
+size_t rgame_locale_append(char *out, size_t capacity, size_t length, const char *language,
+                           const char *country) {
+    if (language == NULL || language[0] == '\0') {
+        return length;
+    }
+
+    if (length > 0) {
+        length = append_text(out, capacity, length, ",");
+    }
+    length = append_text(out, capacity, length, language);
+    if (country != NULL && country[0] != '\0') {
+        length = append_text(out, capacity, length, "-");
+        length = append_text(out, capacity, length, country);
+    }
+
+    if (capacity > 0) {
+        out[length < capacity ? length : capacity - 1] = '\0';
+    }
+    return length;
+}
+
+size_t rgame_preferred_locales(char *out, size_t capacity) {
+    if (capacity > 0) {
+        out[0] = '\0';
+    }
+
+    SDL_Locale *locales = SDL_GetPreferredLocales();
+    if (locales == NULL) {
+        return 0;
+    }
+
+    size_t length = 0;
+    for (const SDL_Locale *locale = locales; locale->language != NULL; locale++) {
+        length = rgame_locale_append(out, capacity, length, locale->language, locale->country);
+    }
+    SDL_free(locales);
+    return length;
+}

data/ext/rgame_core/app/locale.h

@@ -0,0 +1,28 @@
+#ifndef RGAME_LOCALE_H
+#define RGAME_LOCALE_H
+
+#include <stddef.h>
+
+/*
+ * The pure half of reading the user's preferred locales: joining them into one
+ * "de-AT,en" string in a caller's buffer. No SDL, so the Check suite covers the
+ * truncation contract on every platform, whatever locales the machine it runs
+ * on happens to prefer. locale.c's rgame_preferred_locales is the SDL shim
+ * that feeds it.
+ */
+
+/*
+ * Appends one locale to a list whose full length so far is `length`: a comma
+ * unless the list is empty, then `language`, then "-" and `country` when a
+ * country is given. Returns the list's new full length.
+ *
+ * It behaves like snprintf: `out` receives as much as fits in `capacity`,
+ * always NUL-terminated when `capacity` is non-zero, and the return value is
+ * the length the whole list needs, so a result >= `capacity` means it was
+ * truncated. `length` may already exceed `capacity`. A NULL or empty
+ * `language` appends nothing.
+ */
+size_t rgame_locale_append(char *out, size_t capacity, size_t length, const char *language,
+                           const char *country);
+
+#endif /* RGAME_LOCALE_H */

data/ext/rgame_core/audio/audio.c

@@ -53,6 +53,11 @@ struct rgame_audio {
      * lookup to find.
      */
     int forced_no_device;
+    /*
+     * How many things still need this engine: the owner counts as one, and so
+     * does every sample and song loaded from it. See audio_release.
+     */
+    int refs;
 };
 
 struct rgame_sample {
@@ -213,6 +218,8 @@ static rgame_audio *create_audio(int offline, unsigned int sample_rate, char *er
         return NULL;
     }
 
+    /* The caller's own claim. Sounds add theirs as they are loaded. */
+    audio->refs = 1;
     return audio;
 }
 
@@ -234,8 +241,28 @@ unsigned int rgame_audio_read(rgame_audio *audio, float *out, unsigned int frame
     return (unsigned int)read;
 }
 
-void rgame_audio_destroy(rgame_audio *audio) {
-    if (!audio) {
+/*
+ * Drops one claim on the device, and tears it down when the last one goes.
+ *
+ * The device has to outlive every sound made from it, and a refcount is what
+ * makes that true regardless of the order things are released in. That order is
+ * not ours to choose: Ruby's collector frees unreachable objects in whatever
+ * order it sweeps them, so a Song and the Audio it came from can be freed in
+ * the same pass with the Audio going first. Tearing down a *streaming* voice
+ * then asks the resource manager's job thread to acknowledge it — and that
+ * thread went with the engine, so the wait never returns and the process hangs
+ * rather than crashing.
+ *
+ * Marking the device from the sound, which audio_ext.c does, is a different
+ * guarantee: it keeps the device alive while a sound is still *reachable*. It
+ * says nothing about two objects that became garbage together.
+ *
+ * So the owner holds a reference, every sound holds one, and the last one out
+ * does the uninit. Same shape as the refcounted texture sheet in
+ * graphics/texture.c, and for the same kind of reason.
+ */
+static void audio_release(rgame_audio *audio) {
+    if (!audio || --audio->refs > 0) {
         return;
     }
 
@@ -246,6 +273,10 @@ void rgame_audio_destroy(rgame_audio *audio) {
     free(audio);
 }
 
+void rgame_audio_destroy(rgame_audio *audio) {
+    audio_release(audio);
+}
+
 void rgame_audio_set_volume(rgame_audio *audio, float volume) {
     if (audio) {
         ma_engine_set_volume(&audio->engine, clamp_volume(volume));
@@ -367,6 +398,7 @@ rgame_sample *rgame_sample_load(rgame_audio *audio, const char *path, char *err,
     strcpy(sample->path, path);
 
     sample->audio = audio;
+    audio->refs++;
     live_sounds++;
     return sample;
 }
@@ -394,8 +426,10 @@ void rgame_sample_destroy(rgame_sample *sample) {
      * same file hold their own, so the last one out frees it. */
     ma_sound_uninit(&sample->decoded);
     free(sample->path);
+    rgame_audio *audio = sample->audio;
     free(sample);
     live_sounds--;
+    audio_release(audio);
 }
 
 void rgame_sample_play(rgame_sample *sample) {
@@ -470,6 +504,7 @@ rgame_song *rgame_song_load(rgame_audio *audio, const char *path, char *err, siz
     }
 
     song->audio = audio;
+    audio->refs++;
     live_sounds++;
     return song;
 }
@@ -480,8 +515,10 @@ void rgame_song_destroy(rgame_song *song) {
     }
 
     ma_sound_uninit(&song->sound);
+    rgame_audio *audio = song->audio;
     free(song);
     live_sounds--;
+    audio_release(audio);
 }
 
 void rgame_song_play(rgame_song *song, int looping) {

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
 
@@ -93,7 +60,6 @@ class Example < RGame::Core::App
     @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(Controls::AXIS_LEFT_X, device: @device) * speed
     @cursor_y += @input.axis(Controls::AXIS_LEFT_Y, device: @device) * speed
   end
@@ -115,35 +81,22 @@ class Example < RGame::Core::App
   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)
@@ -155,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,117 +1,36 @@
 # 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')
 
-# 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.
-#
-# 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')
 
-# 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.'
@@ -120,45 +39,13 @@ 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.
-#
-# 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')
 
-# 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',
@@ -176,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/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);
@@ -272,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);
@@ -317,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

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

@@ -61,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
@@ -110,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 */
@@ -119,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");
     }
@@ -363,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
@@ -482,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
@@ -501,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);
@@ -526,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);