teek-sdl2 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42e232c86750e8313a051b00099dc677fa26888e8f0eace2a0fd2101b4d5aebd
-  data.tar.gz: ae409b3dae88d5b89c3f5c4552fbd761ae627200c5c7a1ed6859682d5aa61197
+  metadata.gz: 723f31c93fcc52c30a208ef8ab42ed0d7ade64ac45bfda38cddad93cb18877c4
+  data.tar.gz: 1611a57531d9731651dec9391d93148a98a772106cbbcd044899c184d7cf65c4
 SHA512:
-  metadata.gz: 89acada5767fe800d184cc8881053b4b76a0f75cb0742eb150d43567005a4f0474f8ccbad012bc991496e01cbf6c416519f1904c2451dbc866903aac9dad1c12
-  data.tar.gz: dbbbb729914e2c17321889c958a4381547ba4944c7ab3f0c313ee8e91ae42695ebc077b0520d5dea4574fc583d9cb2d0dd30545c1c1d6a896ceab4223f561c72
+  metadata.gz: 6cdbf88dae339da4bbcd88181dc04292f7edc82c7f48a6256d29d3cc728803264eaba6a0e64984dd7031c90eaf545ff27c7a7857207c3dfcf0ef7cc95c8a9a64
+  data.tar.gz: 4f4176408fc19ecb389e02b478fac2028980965b3910ff93a326e75449f66a00ccbae6d600c3cf686a7a4c67595047a3a54534a6366110a8ca37bde033cf7b2f

data/ext/teek_sdl2/extconf.rb

@@ -128,6 +128,16 @@ unless pkg_config('SDL2_mixer') || have_library('SDL2_mixer', 'Mix_OpenAudio', '
   MSG
 end
 
-$srcs = ['teek_sdl2.c', 'sdl2surface.c', 'sdl2bridge.c', 'sdl2text.c', 'sdl2pixels.c', 'sdl2image.c', 'sdl2mixer.c', 'sdl2gamepad.c']
+# SDL2_gfx for drawing primitives (circles, ellipses, polygons, etc.)
+unless pkg_config('SDL2_gfx') || have_library('SDL2_gfx', 'filledCircleRGBA', 'SDL2/SDL2_gfxPrimitives.h')
+  abort <<~MSG
+    SDL2_gfx not found. Install it:
+      macOS:   brew install sdl2_gfx
+      Debian:  sudo apt-get install libsdl2-gfx-dev
+      Windows: pacman -S #{msys2_pkg_prefix}-SDL2_gfx  (MSYS2)
+  MSG
+end
+
+$srcs = ['teek_sdl2.c', 'sdl2surface.c', 'sdl2bridge.c', 'sdl2text.c', 'sdl2pixels.c', 'sdl2image.c', 'sdl2mixer.c', 'sdl2audio.c', 'sdl2gamepad.c']
 
 create_makefile('teek_sdl2')

data/ext/teek_sdl2/sdl2audio.c

@@ -0,0 +1,433 @@
+#include "teek_sdl2.h"
+
+/* ---------------------------------------------------------
+ * SDL2 AudioStream — push-based real-time PCM audio output
+ *
+ * Wraps SDL_OpenAudioDevice + SDL_QueueAudio for streaming
+ * raw PCM data (emulators, synthesizers, procedural audio).
+ * Independent of SDL2_mixer — uses a separate audio device.
+ * --------------------------------------------------------- */
+
+static VALUE cAudioStream;
+
+static void
+ensure_sdl_audio_init(void)
+{
+    if (!(SDL_WasInit(SDL_INIT_AUDIO) & SDL_INIT_AUDIO)) {
+        if (SDL_InitSubSystem(SDL_INIT_AUDIO) < 0) {
+            rb_raise(rb_eRuntimeError, "SDL_InitSubSystem(AUDIO) failed: %s",
+                     SDL_GetError());
+        }
+    }
+}
+
+/* ---------------------------------------------------------
+ * AudioStream (wraps SDL_AudioDeviceID)
+ * --------------------------------------------------------- */
+
+struct sdl2_audio_stream {
+    SDL_AudioDeviceID device_id;
+    int frequency;
+    int channels;
+    SDL_AudioFormat format;
+    int bytes_per_sample;
+    int destroyed;
+};
+
+static void
+audio_stream_free(void *ptr)
+{
+    struct sdl2_audio_stream *a = ptr;
+    if (!a->destroyed && a->device_id > 0) {
+        SDL_CloseAudioDevice(a->device_id);
+        a->device_id = 0;
+        a->destroyed = 1;
+    }
+    xfree(a);
+}
+
+static size_t
+audio_stream_memsize(const void *ptr)
+{
+    return sizeof(struct sdl2_audio_stream);
+}
+
+static const rb_data_type_t audio_stream_type = {
+    .wrap_struct_name = "TeekSDL2::AudioStream",
+    .function = {
+        .dmark = NULL,
+        .dfree = audio_stream_free,
+        .dsize = audio_stream_memsize,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE
+audio_stream_alloc(VALUE klass)
+{
+    struct sdl2_audio_stream *a;
+    VALUE obj = TypedData_Make_Struct(klass, struct sdl2_audio_stream,
+                                     &audio_stream_type, a);
+    a->device_id = 0;
+    a->frequency = 0;
+    a->channels = 0;
+    a->format = 0;
+    a->bytes_per_sample = 0;
+    a->destroyed = 0;
+    return obj;
+}
+
+static struct sdl2_audio_stream *
+get_audio_stream(VALUE self)
+{
+    struct sdl2_audio_stream *a;
+    TypedData_Get_Struct(self, struct sdl2_audio_stream, &audio_stream_type, a);
+    if (a->destroyed || a->device_id == 0) {
+        rb_raise(rb_eRuntimeError, "audio stream has been destroyed");
+    }
+    return a;
+}
+
+/* Helper: map Ruby symbol to SDL_AudioFormat + bytes_per_sample */
+static int
+resolve_format(VALUE sym, SDL_AudioFormat *out_fmt, int *out_bps)
+{
+    ID id;
+    if (NIL_P(sym) || sym == Qundef) {
+        *out_fmt = AUDIO_S16SYS;
+        *out_bps = 2;
+        return 1;
+    }
+    if (!SYMBOL_P(sym)) return 0;
+
+    id = SYM2ID(sym);
+    if (id == rb_intern("s16")) {
+        *out_fmt = AUDIO_S16SYS;
+        *out_bps = 2;
+    } else if (id == rb_intern("f32")) {
+        *out_fmt = AUDIO_F32SYS;
+        *out_bps = 4;
+    } else if (id == rb_intern("u8")) {
+        *out_fmt = AUDIO_U8;
+        *out_bps = 1;
+    } else {
+        return 0;
+    }
+    return 1;
+}
+
+/*
+ * AudioStream.new(frequency: 44100, format: :s16, channels: 2)
+ *
+ * Opens a push-based audio output device. Starts paused —
+ * call #resume after queuing initial data.
+ */
+static VALUE
+audio_stream_initialize(int argc, VALUE *argv, VALUE self)
+{
+    struct sdl2_audio_stream *a;
+    TypedData_Get_Struct(self, struct sdl2_audio_stream, &audio_stream_type, a);
+
+    ensure_sdl_audio_init();
+
+    /* Defaults */
+    int frequency = 44100;
+    int channels = 2;
+    SDL_AudioFormat format = AUDIO_S16SYS;
+    int bps = 2;
+
+    /* Parse keyword arguments */
+    VALUE kwargs;
+    rb_scan_args(argc, argv, ":", &kwargs);
+
+    if (!NIL_P(kwargs)) {
+        ID keys[3];
+        VALUE vals[3];
+        keys[0] = rb_intern("frequency");
+        keys[1] = rb_intern("format");
+        keys[2] = rb_intern("channels");
+
+        rb_get_kwargs(kwargs, keys, 0, 3, vals);
+
+        if (vals[0] != Qundef) {
+            frequency = NUM2INT(vals[0]);
+            if (frequency <= 0) {
+                rb_raise(rb_eArgError, "frequency must be positive");
+            }
+        }
+
+        if (vals[1] != Qundef) {
+            if (!resolve_format(vals[1], &format, &bps)) {
+                rb_raise(rb_eArgError,
+                         "format must be :s16, :f32, or :u8");
+            }
+        }
+
+        if (vals[2] != Qundef) {
+            channels = NUM2INT(vals[2]);
+            if (channels < 1 || channels > 2) {
+                rb_raise(rb_eArgError, "channels must be 1 or 2");
+            }
+        }
+    }
+
+    /* Open audio device */
+    SDL_AudioSpec desired;
+    SDL_memset(&desired, 0, sizeof(desired));
+    desired.freq = frequency;
+    desired.format = format;
+    desired.channels = (Uint8)channels;
+    desired.samples = 2048;
+
+    SDL_AudioDeviceID dev = SDL_OpenAudioDevice(
+        NULL, 0, &desired, NULL, 0);
+    if (dev == 0) {
+        rb_raise(rb_eRuntimeError, "SDL_OpenAudioDevice failed: %s",
+                 SDL_GetError());
+    }
+
+    a->device_id = dev;
+    a->frequency = frequency;
+    a->channels = channels;
+    a->format = format;
+    a->bytes_per_sample = bps;
+
+    return self;
+}
+
+/*
+ * stream.queue(data) -> nil
+ *
+ * Push raw PCM data to the audio device.
+ * +data+ must be a binary String matching the stream's format and channels.
+ */
+static VALUE
+audio_stream_queue(VALUE self, VALUE data)
+{
+    struct sdl2_audio_stream *a = get_audio_stream(self);
+
+    StringValue(data);
+    if (RSTRING_LEN(data) == 0) return Qnil;
+
+    if (SDL_QueueAudio(a->device_id, RSTRING_PTR(data),
+                       (Uint32)RSTRING_LEN(data)) < 0) {
+        rb_raise(rb_eRuntimeError, "SDL_QueueAudio failed: %s",
+                 SDL_GetError());
+    }
+    return Qnil;
+}
+
+/*
+ * stream.queued_bytes -> Integer
+ *
+ * Bytes of audio data currently queued for playback.
+ */
+static VALUE
+audio_stream_queued_bytes(VALUE self)
+{
+    struct sdl2_audio_stream *a = get_audio_stream(self);
+    Uint32 bytes = SDL_GetQueuedAudioSize(a->device_id);
+    return UINT2NUM(bytes);
+}
+
+/*
+ * stream.queued_samples -> Integer
+ *
+ * Number of audio samples (frames) currently queued.
+ * One sample = one value per channel.
+ */
+static VALUE
+audio_stream_queued_samples(VALUE self)
+{
+    struct sdl2_audio_stream *a = get_audio_stream(self);
+    Uint32 bytes = SDL_GetQueuedAudioSize(a->device_id);
+    int frame_size = a->bytes_per_sample * a->channels;
+    return UINT2NUM(bytes / (Uint32)frame_size);
+}
+
+/*
+ * stream.resume -> nil
+ *
+ * Start or unpause audio playback.
+ */
+static VALUE
+audio_stream_resume(VALUE self)
+{
+    struct sdl2_audio_stream *a = get_audio_stream(self);
+    SDL_PauseAudioDevice(a->device_id, 0);
+    return Qnil;
+}
+
+/*
+ * stream.pause -> nil
+ *
+ * Pause audio playback. Queued data is preserved.
+ */
+static VALUE
+audio_stream_pause(VALUE self)
+{
+    struct sdl2_audio_stream *a = get_audio_stream(self);
+    SDL_PauseAudioDevice(a->device_id, 1);
+    return Qnil;
+}
+
+/*
+ * stream.playing? -> Boolean
+ *
+ * Whether the audio device is currently playing (not paused).
+ */
+static VALUE
+audio_stream_playing_p(VALUE self)
+{
+    struct sdl2_audio_stream *a = get_audio_stream(self);
+    SDL_AudioStatus status = SDL_GetAudioDeviceStatus(a->device_id);
+    return status == SDL_AUDIO_PLAYING ? Qtrue : Qfalse;
+}
+
+/*
+ * stream.clear -> nil
+ *
+ * Flush all queued audio data.
+ */
+static VALUE
+audio_stream_clear(VALUE self)
+{
+    struct sdl2_audio_stream *a = get_audio_stream(self);
+    SDL_ClearQueuedAudio(a->device_id);
+    return Qnil;
+}
+
+/*
+ * stream.frequency -> Integer
+ *
+ * Sample rate in Hz.
+ */
+static VALUE
+audio_stream_frequency(VALUE self)
+{
+    struct sdl2_audio_stream *a = get_audio_stream(self);
+    return INT2NUM(a->frequency);
+}
+
+/*
+ * stream.channels -> Integer
+ *
+ * Number of audio channels (1 = mono, 2 = stereo).
+ */
+static VALUE
+audio_stream_channels(VALUE self)
+{
+    struct sdl2_audio_stream *a = get_audio_stream(self);
+    return INT2NUM(a->channels);
+}
+
+/*
+ * stream.format -> Symbol
+ *
+ * Audio sample format (:s16, :f32, or :u8).
+ */
+static VALUE
+audio_stream_format(VALUE self)
+{
+    struct sdl2_audio_stream *a = get_audio_stream(self);
+    if (a->format == AUDIO_S16SYS) return ID2SYM(rb_intern("s16"));
+    if (a->format == AUDIO_F32SYS) return ID2SYM(rb_intern("f32"));
+    if (a->format == AUDIO_U8)     return ID2SYM(rb_intern("u8"));
+    return ID2SYM(rb_intern("unknown"));
+}
+
+/*
+ * stream.destroy -> nil
+ *
+ * Close the audio device. Further method calls will raise.
+ */
+static VALUE
+audio_stream_destroy(VALUE self)
+{
+    struct sdl2_audio_stream *a;
+    TypedData_Get_Struct(self, struct sdl2_audio_stream, &audio_stream_type, a);
+    if (!a->destroyed && a->device_id > 0) {
+        SDL_CloseAudioDevice(a->device_id);
+        a->device_id = 0;
+        a->destroyed = 1;
+    }
+    return Qnil;
+}
+
+/*
+ * stream.destroyed? -> Boolean
+ *
+ * Whether the audio stream has been destroyed.
+ */
+static VALUE
+audio_stream_destroyed_p(VALUE self)
+{
+    struct sdl2_audio_stream *a;
+    TypedData_Get_Struct(self, struct sdl2_audio_stream, &audio_stream_type, a);
+    return a->destroyed ? Qtrue : Qfalse;
+}
+
+/*
+ * AudioStream.available? -> Boolean
+ *
+ * Returns true if at least one audio output device is available.
+ * Use this to probe before opening a stream on headless/CI systems.
+ */
+static VALUE
+audio_stream_available_p(VALUE klass)
+{
+    ensure_sdl_audio_init();
+    return SDL_GetNumAudioDevices(0) > 0 ? Qtrue : Qfalse;
+}
+
+/*
+ * AudioStream.device_count -> Integer
+ *
+ * Number of audio output devices detected by SDL2.
+ */
+static VALUE
+audio_stream_device_count(VALUE klass)
+{
+    ensure_sdl_audio_init();
+    return INT2NUM(SDL_GetNumAudioDevices(0));
+}
+
+/*
+ * AudioStream.driver_name -> String or nil
+ *
+ * Name of the current SDL2 audio driver (e.g. "wasapi", "dummy"),
+ * or nil if audio is not initialized.
+ */
+static VALUE
+audio_stream_driver_name(VALUE klass)
+{
+    const char *name = SDL_GetCurrentAudioDriver();
+    return name ? rb_str_new_cstr(name) : Qnil;
+}
+
+/* --------------------------------------------------------- */
+
+void
+Init_sdl2audio(VALUE mTeekSDL2)
+{
+    cAudioStream = rb_define_class_under(mTeekSDL2, "AudioStream", rb_cObject);
+    rb_define_alloc_func(cAudioStream, audio_stream_alloc);
+
+    rb_define_method(cAudioStream, "initialize", audio_stream_initialize, -1);
+    rb_define_method(cAudioStream, "queue", audio_stream_queue, 1);
+    rb_define_method(cAudioStream, "queued_bytes", audio_stream_queued_bytes, 0);
+    rb_define_method(cAudioStream, "queued_samples", audio_stream_queued_samples, 0);
+    rb_define_method(cAudioStream, "resume", audio_stream_resume, 0);
+    rb_define_method(cAudioStream, "pause", audio_stream_pause, 0);
+    rb_define_method(cAudioStream, "playing?", audio_stream_playing_p, 0);
+    rb_define_method(cAudioStream, "clear", audio_stream_clear, 0);
+    rb_define_method(cAudioStream, "frequency", audio_stream_frequency, 0);
+    rb_define_method(cAudioStream, "channels", audio_stream_channels, 0);
+    rb_define_method(cAudioStream, "format", audio_stream_format, 0);
+    rb_define_method(cAudioStream, "destroy", audio_stream_destroy, 0);
+    rb_define_method(cAudioStream, "destroyed?", audio_stream_destroyed_p, 0);
+
+    rb_define_singleton_method(cAudioStream, "available?", audio_stream_available_p, 0);
+    rb_define_singleton_method(cAudioStream, "device_count", audio_stream_device_count, 0);
+    rb_define_singleton_method(cAudioStream, "driver_name", audio_stream_driver_name, 0);
+}

data/ext/teek_sdl2/sdl2bridge.c

@@ -9,18 +9,28 @@
  * --------------------------------------------------------- */
 
 /*
- * Teek::SDL2.create_renderer_from_handle(native_handle) -> Renderer
+ * Teek::SDL2.create_renderer_from_handle(native_handle, vsync=true) -> Renderer
  *
  * Creates an SDL2 window embedded in the native window identified by
  * native_handle (from Tk's 'winfo id'), then creates a GPU-accelerated
  * renderer on it.
  *
+ * When +vsync+ is true (the default), SDL_RENDERER_PRESENTVSYNC is set
+ * so SDL_RenderPresent blocks until the next display refresh. Pass false
+ * for applications that manage their own frame pacing (e.g. emulators
+ * syncing to an audio clock).
+ *
  * The Ruby Viewport class is responsible for getting the handle and
  * calling this. This C function just does the SDL2 work.
  */
 static VALUE
-bridge_create_renderer_from_handle(VALUE self, VALUE handle_val)
+bridge_create_renderer_from_handle(int argc, VALUE *argv, VALUE self)
 {
+    VALUE handle_val, vsync_val;
+    rb_scan_args(argc, argv, "11", &handle_val, &vsync_val);
+
+    int use_vsync = NIL_P(vsync_val) ? 1 : RTEST(vsync_val);
+
     ensure_sdl2_init();
 
     /*
@@ -40,8 +50,10 @@ bridge_create_renderer_from_handle(VALUE self, VALUE handle_val)
         rb_raise(rb_eRuntimeError, "SDL_CreateWindowFrom failed: %s", SDL_GetError());
     }
 
-    SDL_Renderer *sdl_ren = SDL_CreateRenderer(window, -1,
-        SDL_RENDERER_ACCELERATED | SDL_RENDERER_PRESENTVSYNC);
+    Uint32 flags = SDL_RENDERER_ACCELERATED;
+    if (use_vsync) flags |= SDL_RENDERER_PRESENTVSYNC;
+
+    SDL_Renderer *sdl_ren = SDL_CreateRenderer(window, -1, flags);
     if (!sdl_ren) {
         /* Fall back to software if GPU not available */
         sdl_ren = SDL_CreateRenderer(window, -1, SDL_RENDERER_SOFTWARE);
@@ -135,7 +147,7 @@ void
 Init_sdl2bridge(VALUE mTeekSDL2)
 {
     rb_define_module_function(mTeekSDL2, "create_renderer_from_handle",
-                             bridge_create_renderer_from_handle, 1);
+                             bridge_create_renderer_from_handle, -1);
     rb_define_module_function(mTeekSDL2, "poll_events", bridge_poll_events, 0);
     rb_define_module_function(mTeekSDL2, "_event_check_fn_ptr", bridge_event_check_fn_ptr, 0);
     rb_define_module_function(mTeekSDL2, "sdl_quit", bridge_sdl_quit, 0);

data/ext/teek_sdl2/sdl2gamepad.c

@@ -33,6 +33,15 @@ ensure_gc_init(void)
     if (gc_subsystem_initialized) return;
 
     if (!(SDL_WasInit(SDL_INIT_GAMECONTROLLER) & SDL_INIT_GAMECONTROLLER)) {
+        /*
+         * By default SDL drops joystick/gamecontroller events when its
+         * window doesn't have focus. Since we embed SDL inside Tk, other
+         * Tk windows (e.g. Settings) can take focus while the user still
+         * needs gamepad input. Allow events regardless of focus.
+         * https://wiki.libsdl.org/SDL2/SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS
+         */
+        SDL_SetHint(SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS, "1");
+
         if (SDL_InitSubSystem(SDL_INIT_GAMECONTROLLER) < 0) {
             rb_raise(rb_eRuntimeError,
                      "SDL_InitSubSystem(GAMECONTROLLER) failed: %s",
@@ -340,6 +349,24 @@ gamepad_name(VALUE self)
     return rb_str_new_cstr(name);
 }
 
+/*
+ * Gamepad#guid -> String
+ *
+ * Returns the GUID string that identifies this controller's model/type.
+ * Same model controllers share the same GUID. Useful as a config key
+ * for persisting per-controller settings.
+ */
+static VALUE
+gamepad_guid(VALUE self)
+{
+    struct sdl2_gamepad *gp = get_gamepad(self);
+    SDL_Joystick *joy = SDL_GameControllerGetJoystick(gp->controller);
+    SDL_JoystickGUID guid = SDL_JoystickGetGUID(joy);
+    char buf[33];
+    SDL_JoystickGetGUIDString(guid, buf, sizeof(buf));
+    return rb_str_new_cstr(buf);
+}
+
 /*
  * Gamepad#attached? -> true or false
  *
@@ -544,6 +571,30 @@ gamepad_s_poll_events(VALUE klass)
     return INT2NUM(count);
 }
 
+/*
+ * Gamepad.update_state -> nil
+ *
+ * Refreshes the internal state of all open game controllers
+ * WITHOUT pumping the platform event loop.
+ *
+ * SDL_PollEvent → SDL_PumpEvents → pumps the Cocoa run loop on macOS,
+ * which steals events from other UI toolkits (e.g. Tk).
+ * SDL_GameControllerUpdate → SDL_JoystickUpdate only (no event pump).
+ * See: https://github.com/libsdl-org/SDL/blob/SDL2/src/joystick/SDL_gamecontroller.c
+ *
+ * After calling this, Gamepad#button? and Gamepad#axis return
+ * updated values. Use this instead of poll_events when you only
+ * need fresh controller state and don't need event callbacks.
+ */
+static VALUE
+gamepad_s_update_state(VALUE klass)
+{
+    if (gc_subsystem_initialized) {
+        SDL_GameControllerUpdate();
+    }
+    return Qnil;
+}
+
 /* ---------------------------------------------------------
  * Callback registration
  * --------------------------------------------------------- */
@@ -838,6 +889,8 @@ Init_sdl2gamepad(VALUE mTeekSDL2)
     rb_define_singleton_method(cGamepad, "all", gamepad_s_all, 0);
     rb_define_singleton_method(cGamepad, "poll_events",
                                gamepad_s_poll_events, 0);
+    rb_define_singleton_method(cGamepad, "update_state",
+                               gamepad_s_update_state, 0);
     rb_define_singleton_method(cGamepad, "buttons", gamepad_s_buttons, 0);
     rb_define_singleton_method(cGamepad, "axes", gamepad_s_axes, 0);
 
@@ -857,6 +910,7 @@ Init_sdl2gamepad(VALUE mTeekSDL2)
 
     /* Instance methods */
     rb_define_method(cGamepad, "name", gamepad_name, 0);
+    rb_define_method(cGamepad, "guid", gamepad_guid, 0);
     rb_define_method(cGamepad, "attached?", gamepad_attached_p, 0);
     rb_define_method(cGamepad, "button?", gamepad_button_p, 1);
     rb_define_method(cGamepad, "axis", gamepad_axis, 1);