sfml3-rb 0.0.1 → 0.2.2

data/TODO.md

@@ -0,0 +1,199 @@
+# Roadmap: SFML 3 API port to Ruby
+
+Tracks porting coverage of the SFML 3 API into this gem, module by module and class by class.
+
+This binding wraps **CSFML 3** (the C API), not SFML's C++ API directly, so the scope below is
+CSFML 3.0.0's actual header set — not every C++-only construct in the
+[reference docs](https://www.sfml-dev.org/documentation/3.1.0/annotated.html). Out of scope for that
+reason: `String`/`Utf`/`Literals` (SFML C++ uses `std::string`; CSFML takes plain C strings),
+`Exception` (CSFML reports errors via return codes, not C++ exceptions), and C++-utility-only types
+(`SuspendAwareClock`, `TimeoutWithPredicate`, `U8StringCharTraits`). `Glsl` is handled as plain
+`set_*_uniform` calls (its types are CSFML structs, not a templated class), and `InputStream`'s C
+struct form *is* bound (`SFML::InputStream`). `Sftp` is also out of scope: it was added to SFML in
+3.1, and the CSFML 3.0.0 this gem vendors predates it.
+
+Status legend: `[x]` bound and tested · `[~]` compiled but not exposed to Ruby, or exposed as an
+internal helper only · `[ ]` not started.
+
+**Coverage is tracked per function, not per class.** Every `sf*` entry point in
+`ports/<target>/include/CSFML` is accounted for: bound, or listed in "Deliberately unbound" at the
+bottom. Re-derive the list with:
+
+```sh
+grep -rhoE '\bsf[A-Za-z0-9_]+\s*\(' ports/<target>/include/CSFML --include='*.h' \
+  | tr -d ' (' | sort -u > /tmp/api.txt
+grep -rhoE '\bsf[A-Za-z0-9_]+' ext --include='*.c' --include='*.h' --include='*.inc' \
+  | sort -u > /tmp/used.txt
+comm -23 /tmp/api.txt /tmp/used.txt
+```
+
+Mind the false positives: functions reached through token paste (`sfSound_*`, `sfMusic_*`,
+`sfSoundStream_*` from `ext/audio/sound_source.inc`; `sfPacket_read*`/`write*` from the macro in
+`ext/network/packet.c`; the shared `sfRenderWindow_*`/`sfRenderTexture_*` render-target methods
+from `ext/graphics/render_target.inc`) never appear literally in the sources and so show up as
+"missing" every time.
+
+## System
+
+Base module: time, vectors, clocks, streams.
+
+- [x] **Clock** — `SFML::Clock` (`ext/system/clock.c`); `elapsed_time`, `restart!`, `reset!`,
+      `start!`, `stop!`, `running?`, `copy`
+- [x] **Vector2** — `SFML::Vector2` (`ext/system/vec2.c`); setters still accept `[x, y]`
+- [x] **Vector3** — `SFML::Vector3` (`ext/system/vec3.c`)
+- [x] **Time** — `SFML::Time` (`ext/system/time.c`); arithmetic, comparison, unit conversions
+- [x] **Sleep** — `SFML.sleep` (`ext/system/sleep.c`)
+- [x] **InputStream** — `SFML::InputStream` (`ext/system/input_stream.c`); wraps any `#read`-able
+      object and is accepted by every `from_stream` constructor
+- [x] **Buffer** — `SFML::Buffer` (`ext/system/buffer.c`); returned by `Image#save_to_memory`
+
+## Window
+
+OpenGL-based windows, events, input handling.
+
+- [x] **Window** — `SFML::Window` (`ext/window/window.c`); wraps `sfRenderWindow`, so this single
+      class covers what SFML splits into `WindowBase` + `Window` + `RenderWindow`. Accepts style,
+      state and `ContextSettings`; exposes min/max size, icon, cursor, native handle, settings.
+- [x] **VideoMode** — `SFML::VideoMode` (`ext/window/video_mode.c`); includes `desktop_mode` and
+      `fullscreen_modes`
+- [x] **Event** — `SFML::Event` (`ext/window/event.c`, `ext/window/event_name.c`); every payload is
+      exposed — text, key, mouse move/raw/button/wheel, joystick move/button/connect, touch, sensor
+- [x] **Keyboard** — `SFML::Keyboard` (`ext/window/keyboard.c`); real-time `pressed?`,
+      `scancode_pressed?`, `localize`, `delocalize`, `description`, virtual-keyboard toggle
+- [x] **Mouse** — `SFML::Mouse` (`ext/window/mouse.c`)
+- [x] **Joystick** — `SFML::Joystick` (`ext/window/joystick.c`)
+- [x] **Touch** — `SFML::Touch` (`ext/window/touch.c`)
+- [x] **Sensor** — `SFML::Sensor` (`ext/window/sensor.c`)
+- [x] **Clipboard** — `SFML::Clipboard` (`ext/window/clipboard.c`)
+- [x] **Cursor** — `SFML::Cursor` (`ext/window/cursor.c`)
+- [x] **Context** / **ContextSettings** — `SFML::Context`, `SFML::ContextSettings`
+      (`ext/window/context.c`, `ext/window/context_settings.c`)
+- [x] **Vulkan** — `SFML::Vulkan` (`ext/window/vulkan.c`)
+
+## Graphics
+
+2D rendering: shapes, sprites, text, render targets.
+
+- [x] **Transform** — `SFML::Transform` (`ext/graphics/transform.c`); a class wrapping
+      `sfTransform` by value. `identity`/`IDENTITY` (frozen), `from_a`, `to_a`/`matrix` (3x3),
+      `gl_matrix` (the 16-float 4x4 for `glLoadMatrixf`), `==`, `translate!`, `rotate!`, `scale!`
+      (both taking an optional centre), non-mutating `translate`/`rotate`/`scale`,
+      `transform_point`, `transform_rect`, `combine!`, `*`, `inverse`, `copy`. The old module
+      functions `Transform.combine`/`Transform.inverse` remain, Array-in/Array-out. Every class
+      that exposes `#transform` still returns a plain 9-element Array, and anything that *takes*
+      a transform accepts either form
+- [x] **Transformable** — `SFML::Transformable` (`ext/graphics/transformable.c`); including
+      `inverse_transform` and `copy`
+- [x] **Drawable** — `SFML::Drawable` mixin (`ext/graphics/drawable.c`)
+- [x] **RenderStates** — `SFML::RenderState` (`ext/graphics/render_state.c`); blend mode, stencil
+      mode, coordinate type, texture, shader and transform are all settable
+- [x] **RenderTarget** — `SFML::Target` (`ext/graphics/target.c`) dispatches to `sfRenderWindow_*`
+      or `sfRenderTexture_*` at runtime for `Drawable#draw`. The methods each concrete target owns
+      directly — `map_pixel_to_coords`, `map_coords_to_pixel`, `push_gl_states`, `pop_gl_states`,
+      `reset_gl_states`, `draw_primitives`, `draw_vertex_buffer_range`, `clear_stencil`,
+      `clear_color_and_stencil`, `viewport`, `scissor`, `srgb?` — are generated once for both
+      `Window` and `RenderTexture` from `ext/graphics/render_target.inc`
+- [x] **RenderWindow** — folded into `SFML::Window` (see Window module above)
+- [x] **RenderTexture** — `SFML::RenderTexture` (`ext/graphics/render_texture.c`)
+- [x] **View** — `SFML::View` (`ext/graphics/view.c`); including `View.from_rect` and
+      `scissor`/`scissor=`
+- [x] **CircleShape** — `SFML::Circle` (`ext/graphics/circle.c`)
+- [x] **RectangleShape** — `SFML::RectangleShape` (`ext/graphics/rectangle.c`)
+- [x] **ConvexShape** — `SFML::ConvexShape` (`ext/graphics/polygon.c`)
+- [x] **Shape** — `SFML::Shape` (`ext/graphics/shape.c`); subclass and define `point_count`/`point`
+- [x] **Sprite** — `SFML::Sprite` (`ext/graphics/sprite.c`)
+- [x] **Texture** — `SFML::Texture` (`ext/graphics/texture.c`); every constructor in both linear
+      and sRGB form, plus `resize`/`resize_srgb` and `swap`
+- [x] **Image** — `SFML::Image` (`ext/graphics/image.c`)
+- [x] **Font** — `SFML::Font` (`ext/graphics/font.c`)
+- [x] **Text** — `SFML::Text` (`ext/graphics/text.c`); `#string` goes through the UTF-32 entry
+      points, so non-ASCII round-trips exactly
+- [x] **Glyph** — `SFML::Glyph` (`ext/graphics/glyph.c`)
+- [x] **Shader** — `SFML::Shader` (`ext/graphics/shader.c`); scalar/vector/color/int/bool/matrix
+      uniforms, all six array uniforms (float, vec2-4, mat3, mat4), plus a generic `uniform=`
+- [x] **Color** — `SFML::Color` (`ext/graphics/color.c`)
+- [x] **Rect** — `SFML::Rect` (`ext/graphics/rect.c`); `sfFloatRect` and `sfIntRect`
+- [x] **BlendMode** — `SFML::BlendMode` (`ext/graphics/blend_mode.c`)
+- [x] **StencilMode** — `SFML::StencilMode` (`ext/graphics/stencil_mode.c`)
+- [x] **Vertex** / **VertexArray** / **VertexBuffer** — `ext/graphics/vertex*.c`
+
+## Audio
+
+Sounds, streaming, recording, spatialization.
+
+- [x] **Listener** — `SFML::Listener` (`ext/audio/listener.c`); global volume plus
+      position/direction/velocity/up-vector/cone
+- [x] **ListenerCone** / **SoundSourceCone** — `SFML::SoundSourceCone` (`ext/audio/sound_source_cone.c`)
+- [x] **SoundSource** — the shared play/pause/stop/status, pitch, pan, volume, spatialization,
+      position/direction/velocity, cone, doppler/directional-attenuation, min/max distance/gain,
+      attenuation, playing-offset and effect-processor surface, generated per class from
+      `ext/audio/sound_source.inc`
+- [x] **SoundStatus** / **SoundChannel** — `SFML::SoundStatus`, `SFML::SoundChannel`
+      (`ext/audio/audio_enums.c`)
+- [x] **SoundBuffer** — `SFML::SoundBuffer` (`ext/audio/sound_buffer.c`); loading from file, memory,
+      stream and raw samples, saving, sample access and channel map
+- [x] **Sound** — `SFML::Sound` (`ext/audio/sound.c`)
+- [x] **SoundStream** — `SFML::SoundStream` (`ext/audio/sound_stream.c`); subclass and implement
+      `#on_get_data` (and optionally `#on_seek`)
+- [x] **SoundBufferRecorder** — `SFML::SoundBufferRecorder` (`ext/audio/sound_buffer_recorder.c`)
+- [x] **SoundRecorder** — `SFML::SoundRecorder` (`ext/audio/sound_recorder.c`); subclass and
+      implement `#on_process` (and optionally `#on_start`/`#on_stop`)
+- [x] **Music** — `SFML::Music` (`ext/audio/music.c`); file, memory and stream sources, loop points
+- [x] **EffectProcessor** — `SFML::SoundSource#effect_processor=`; a Ruby proc is dispatched through
+      a bounded pool of C thunks (`ext/audio/effect_processor.c`), because `sfEffectProcessor` has
+      no `userData` to identify the source
+- [x] **Build support** — `ext/ports.rb` builds Ogg 1.3.5, Vorbis 1.3.7 and FLAC 1.4.3 as pinned,
+      static, position-independent ports (SFML 3's audio backend is miniaudio, so no OpenAL), and
+      enables `SFML_BUILD_AUDIO` / `CSFML_BUILD_AUDIO`
+
+## Network
+
+Socket-based communication and higher-level protocols.
+
+- [x] **IpAddress** — `SFML::IpAddress` (`ext/network/ip_address.c`); string/bytes/integer
+      constructors, `NONE`/`ANY`/`LOCAL_HOST`/`BROADCAST`, local and public address lookup
+- [x] **Packet** — `SFML::Packet` (`ext/network/packet.c`); raw data plus every typed reader/writer
+      (booleans, all integer widths, floats, string)
+- [x] **SocketSelector** — `SFML::SocketSelector` (`ext/network/socket_selector.c`); add/remove for
+      each socket type, wait and readiness checks
+- [x] **TcpSocket** / **TcpListener** — `SFML::TcpSocket`, `SFML::TcpListener`
+      (`ext/network/tcp_socket.c`, `ext/network/tcp_listener.c`); connect/accept, blocking control,
+      raw and packet sends/receives
+- [x] **UdpSocket** — `SFML::UdpSocket` (`ext/network/udp_socket.c`); bind/send/receive and packet
+      variants, datagram size and any-port helpers
+- [x] **Http** — `SFML::Http`, `SFML::HttpRequest`, `SFML::HttpResponse` (`ext/network/http.c`)
+- [x] **Ftp** — `SFML::Ftp`, `SFML::FtpResponse`, `SFML::FtpDirectoryResponse`,
+      `SFML::FtpListingResponse` (`ext/network/ftp.c`)
+- [x] **SocketStatus** / **HttpMethod** / **HttpStatus** / **FtpStatus** / **FtpTransferMode** —
+      enum modules (`ext/network/network_enums.c`)
+- [x] **Build support** — `ext/ports.rb` enables `SFML_BUILD_NETWORK` / `CSFML_BUILD_NETWORK`; the
+      module needs no external dependency (just `ws2_32` on Windows)
+
+Note that CSFML exposes no `sfSocket` base class, so there is nothing to bind for "Socket base" —
+only the concrete TCP/UDP sockets and the selector.
+
+## Deliberately unbound
+
+These CSFML entry points have no Ruby surface on purpose. Listed so a coverage diff can be read
+without re-deriving the reasoning each time.
+
+| Symbols | Why |
+| --- | --- |
+| `sfWindow_*`, `sfWindowBase_*` (~55 functions) | `SFML::Window` wraps `sfRenderWindow`, which subsumes both a plain window and a base window. |
+| `sfMouse_*WindowBase`, `sfTouch_getPositionWindowBase` | Superseded by the `*RenderWindow` forms, which need no downcast. |
+| `sfRenderWindow_create`, `sfText_getString`/`setString`, `sfRenderWindow_setTitle`, `sfFtpDirectoryResponse_getDirectory` | Superseded by their `*Unicode` counterparts; the narrow forms decode through the C locale and mangle non-ASCII. |
+| `sfColor_add`/`subtract`/`modulate`/`fromRGB`/`fromRGBA`/`fromInteger`/`toInteger`, `sfIntRect_contains`/`intersects` | Reimplemented directly in C in `color.c` / `rect.c`; the Ruby methods exist. |
+| `sfSprite_getTexture`, `sfText_getFont`, `sf*Shape_getTexture` | The Ruby getters return the cached wrapper object. CSFML returns a non-owning pointer, so re-wrapping it would hand Ruby an object it must not free. |
+| `sfShape_getPoint`, `sfShape_getPointCount` | `SFML::Shape` reads these from the Ruby subclass, which is where they are defined. |
+| `sfTexture_updateFromWindow` | `Texture#update_from_window` uses `sfTexture_updateFromRenderWindow`, since `SFML::Window` is a render window. |
+| `sfFree` | CSFML's allocator hook; nothing in a Ruby binding should call it. |
+| `sfGlslVec4_fromsfColor`, `sfGlslIvec4_fromsfColor` | Documentation-only helpers; `Shader#set_color` does the conversion. |
+
+## References
+
+- [SFML 3.1.0 module topics](https://www.sfml-dev.org/documentation/3.1.0/topics.html)
+- [SFML 3.1.0 class index](https://www.sfml-dev.org/documentation/3.1.0/annotated.html)
+- [SFML 3.1.0 namespace index](https://www.sfml-dev.org/documentation/3.1.0/namespaces.html)
+- [CSFML 3.0.0 headers](https://github.com/SFML/CSFML/tree/3.0.0/include/CSFML) — the actual C API
+  surface this gem binds against, vendored locally under `ports/<target>/include/CSFML/`
+  once `rake ports` has run

data/ext/audio/audio_enums.c

@@ -0,0 +1,131 @@
+#include "audio/audio_enums.h"
+
+#include <ruby.h>
+#include <string.h>
+
+static const char *sound_status_names[] = {"stopped", "paused", "playing"};
+
+/* Designated initializers, indexed by the enum constant rather than by
+   position: CSFML 3 defines the channel order, and a positional table would
+   silently return the wrong name if a future release inserted a value. */
+static const char *sound_channel_names[] = {
+    [sfSoundChannelUnspecified] = "unspecified",
+    [sfSoundChannelMono] = "mono",
+    [sfSoundChannelFrontLeft] = "front_left",
+    [sfSoundChannelFrontRight] = "front_right",
+    [sfSoundChannelFrontCenter] = "front_center",
+    [sfSoundChannelFrontLeftOfCenter] = "front_left_of_center",
+    [sfSoundChannelFrontRightOfCenter] = "front_right_of_center",
+    [sfSoundChannelLowFrequencyEffects] = "low_frequency_effects",
+    [sfSoundChannelBackLeft] = "back_left",
+    [sfSoundChannelBackRight] = "back_right",
+    [sfSoundChannelBackCenter] = "back_center",
+    [sfSoundChannelSideLeft] = "side_left",
+    [sfSoundChannelSideRight] = "side_right",
+    [sfSoundChannelTopCenter] = "top_center",
+    [sfSoundChannelTopFrontLeft] = "top_front_left",
+    [sfSoundChannelTopFrontRight] = "top_front_right",
+    [sfSoundChannelTopFrontCenter] = "top_front_center",
+    [sfSoundChannelTopBackLeft] = "top_back_left",
+    [sfSoundChannelTopBackRight] = "top_back_right",
+    [sfSoundChannelTopBackCenter] = "top_back_center"
+};
+
+static int symbol_index(VALUE rb_symbol, const char *const *names, size_t count) {
+    const char *name;
+    size_t i;
+
+    if (!SYMBOL_P(rb_symbol)) {
+        return -1;
+    }
+
+    name = rb_id2name(SYM2ID(rb_symbol));
+
+    for (i = 0; i < count; i++) {
+        if (names[i] != NULL && strcmp(name, names[i]) == 0) {
+            return (int) i;
+        }
+    }
+
+    return -1;
+}
+
+const char *sound_status_name(sfSoundStatus status) {
+    if (status >= sfStopped && status <= sfPlaying) {
+        return sound_status_names[status];
+    }
+
+    return "stopped";
+}
+
+sfSoundStatus sound_status_from_rb(VALUE rb_status) {
+    int index;
+
+    if (RB_INTEGER_TYPE_P(rb_status)) {
+        return (sfSoundStatus) NUM2INT(rb_status);
+    }
+
+    index = symbol_index(rb_status, sound_status_names, 3);
+
+    if (index < 0) {
+        rb_raise(rb_eArgError, "unknown sound status");
+    }
+
+    return (sfSoundStatus) index;
+}
+
+const char *sound_channel_name(sfSoundChannel channel) {
+    if (channel >= sfSoundChannelUnspecified && channel <= sfSoundChannelTopBackCenter &&
+        sound_channel_names[channel] != NULL) {
+        return sound_channel_names[channel];
+    }
+
+    return "unspecified";
+}
+
+sfSoundChannel sound_channel_from_rb(VALUE rb_channel) {
+    int index;
+
+    if (RB_INTEGER_TYPE_P(rb_channel)) {
+        return (sfSoundChannel) NUM2INT(rb_channel);
+    }
+
+    index = symbol_index(rb_channel, sound_channel_names,
+                         sizeof(sound_channel_names) / sizeof(sound_channel_names[0]));
+
+    if (index < 0) {
+        rb_raise(rb_eArgError, "unknown sound channel");
+    }
+
+    return (sfSoundChannel) index;
+}
+
+void Init_AudioEnums(VALUE rb_module) {
+    VALUE rb_mSoundStatus = rb_define_module_under(rb_module, "SoundStatus");
+    VALUE rb_mSoundChannel = rb_define_module_under(rb_module, "SoundChannel");
+
+    rb_define_const(rb_mSoundStatus, "STOPPED", INT2NUM(sfStopped));
+    rb_define_const(rb_mSoundStatus, "PAUSED", INT2NUM(sfPaused));
+    rb_define_const(rb_mSoundStatus, "PLAYING", INT2NUM(sfPlaying));
+
+    rb_define_const(rb_mSoundChannel, "UNSPECIFIED", INT2NUM(sfSoundChannelUnspecified));
+    rb_define_const(rb_mSoundChannel, "MONO", INT2NUM(sfSoundChannelMono));
+    rb_define_const(rb_mSoundChannel, "FRONT_LEFT", INT2NUM(sfSoundChannelFrontLeft));
+    rb_define_const(rb_mSoundChannel, "FRONT_RIGHT", INT2NUM(sfSoundChannelFrontRight));
+    rb_define_const(rb_mSoundChannel, "FRONT_CENTER", INT2NUM(sfSoundChannelFrontCenter));
+    rb_define_const(rb_mSoundChannel, "FRONT_LEFT_OF_CENTER", INT2NUM(sfSoundChannelFrontLeftOfCenter));
+    rb_define_const(rb_mSoundChannel, "FRONT_RIGHT_OF_CENTER", INT2NUM(sfSoundChannelFrontRightOfCenter));
+    rb_define_const(rb_mSoundChannel, "LOW_FREQUENCY_EFFECTS", INT2NUM(sfSoundChannelLowFrequencyEffects));
+    rb_define_const(rb_mSoundChannel, "BACK_LEFT", INT2NUM(sfSoundChannelBackLeft));
+    rb_define_const(rb_mSoundChannel, "BACK_RIGHT", INT2NUM(sfSoundChannelBackRight));
+    rb_define_const(rb_mSoundChannel, "BACK_CENTER", INT2NUM(sfSoundChannelBackCenter));
+    rb_define_const(rb_mSoundChannel, "SIDE_LEFT", INT2NUM(sfSoundChannelSideLeft));
+    rb_define_const(rb_mSoundChannel, "SIDE_RIGHT", INT2NUM(sfSoundChannelSideRight));
+    rb_define_const(rb_mSoundChannel, "TOP_CENTER", INT2NUM(sfSoundChannelTopCenter));
+    rb_define_const(rb_mSoundChannel, "TOP_FRONT_LEFT", INT2NUM(sfSoundChannelTopFrontLeft));
+    rb_define_const(rb_mSoundChannel, "TOP_FRONT_RIGHT", INT2NUM(sfSoundChannelTopFrontRight));
+    rb_define_const(rb_mSoundChannel, "TOP_FRONT_CENTER", INT2NUM(sfSoundChannelTopFrontCenter));
+    rb_define_const(rb_mSoundChannel, "TOP_BACK_LEFT", INT2NUM(sfSoundChannelTopBackLeft));
+    rb_define_const(rb_mSoundChannel, "TOP_BACK_RIGHT", INT2NUM(sfSoundChannelTopBackRight));
+    rb_define_const(rb_mSoundChannel, "TOP_BACK_CENTER", INT2NUM(sfSoundChannelTopBackCenter));
+}

data/ext/audio/audio_enums.h

@@ -0,0 +1,18 @@
+#ifndef SFML_RB_AUDIO_AUDIO_ENUMS_H
+#define SFML_RB_AUDIO_AUDIO_ENUMS_H
+
+#include <ruby.h>
+
+#include "core/sfml.h"
+
+void Init_AudioEnums(VALUE rb_module);
+
+const char *sound_status_name(sfSoundStatus status);
+
+sfSoundStatus sound_status_from_rb(VALUE rb_status);
+
+const char *sound_channel_name(sfSoundChannel channel);
+
+sfSoundChannel sound_channel_from_rb(VALUE rb_channel);
+
+#endif //SFML_RB_AUDIO_AUDIO_ENUMS_H

data/ext/audio/effect_processor.c

@@ -0,0 +1,233 @@
+#include "audio/effect_processor.h"
+
+#include <ruby.h>
+#include <string.h>
+
+#include "core/foreign_thread.h"
+
+/* Slots are process-global because a C callback cannot carry context. Each
+   entry is either Qnil (free) or the Proc assigned to that slot. */
+static VALUE effect_processors[EFFECT_PROCESSOR_SLOTS];
+
+typedef struct {
+    int slot;
+    const float* input;
+    unsigned int input_count;
+    float* output;
+    unsigned int output_count;
+    unsigned int requested_output_count;
+    unsigned int channels;
+} EffectContext;
+
+/* Fills the output buffer with silence for the full frame count the audio
+   engine asked for. Used whenever the processor cannot produce real output
+   (an exception, or a timed-out worker): reporting output_count 0 instead of
+   this was observed to make miniaudio's node graph re-invoke this callback
+   in an immediate, unbounded retry loop (tens of thousands of calls/second)
+   rather than treat it as one completed (silent) buffer - which in turn
+   starved SFML's AudioDevice::waitForReadingComplete() on the main thread,
+   since the audio thread never stopped re-acquiring its internal mutex. */
+static void effect_output_silence(EffectContext* ctx) {
+    unsigned int i;
+
+    for (i = 0; i < ctx->requested_output_count * ctx->channels; i++) {
+        ctx->output[i] = 0.0f;
+    }
+
+    ctx->output_count = ctx->requested_output_count;
+}
+
+#define EFFECT_JOB_TIMEOUT_MS 50
+
+void Init_EffectProcessor(void) {
+    int i;
+
+    for (i = 0; i < EFFECT_PROCESSOR_SLOTS; i++) {
+        effect_processors[i] = Qnil;
+        rb_gc_register_address(&effect_processors[i]);
+    }
+}
+
+static VALUE effect_yield(VALUE raw) {
+    EffectContext* ctx = (EffectContext*)raw;
+    VALUE rb_input;
+    VALUE rb_result;
+    unsigned int i;
+    unsigned int c;
+    long produced;
+
+    rb_input = rb_ary_new_capa((long)ctx->input_count);
+
+    for (i = 0; i < ctx->input_count; i++) {
+        VALUE frame = rb_ary_new_capa((long)ctx->channels);
+
+        for (c = 0; c < ctx->channels; c++) {
+            rb_ary_push(frame, DBL2NUM((double)ctx->input[i * ctx->channels + c]));
+        }
+
+        rb_ary_push(rb_input, frame);
+    }
+
+    rb_result = rb_funcall(effect_processors[ctx->slot], rb_intern("call"), 2, rb_input,
+                           UINT2NUM(ctx->channels));
+
+    if (!RB_TYPE_P(rb_result, T_ARRAY)) {
+        rb_raise(rb_eTypeError, "effect processor must return an Array of frames");
+    }
+
+    produced = RARRAY_LEN(rb_result);
+
+    if (produced > (long)ctx->output_count) {
+        produced = (long)ctx->output_count;
+    }
+
+    for (i = 0; i < (unsigned int)produced; i++) {
+        VALUE frame = rb_ary_entry(rb_result, (long)i);
+
+        if (!RB_TYPE_P(frame, T_ARRAY)) {
+            rb_raise(rb_eTypeError, "effect processor frames must be Arrays");
+        }
+
+        for (c = 0; c < ctx->channels; c++) {
+            ctx->output[i * ctx->channels + c] = (float)NUM2DBL(rb_ary_entry(frame, (long)c));
+        }
+    }
+
+    ctx->output_count = (unsigned int)produced;
+
+    return Qnil;
+}
+
+/* Runs on the shared foreign-thread worker, which holds the GVL. */
+static void effect_run(void* raw) {
+    EffectContext* ctx = (EffectContext*)raw;
+    int state = 0;
+
+    rb_protect(effect_yield, (VALUE)ctx, &state);
+
+    if (state) {
+        /* An exception must not unwind through the audio engine: drop the
+           output and let playback continue silently. */
+        rb_set_errinfo(Qnil);
+        effect_output_silence(ctx);
+    }
+}
+
+static void effect_invoke(int slot, const float* input, unsigned int* input_count, float* output,
+                          unsigned int* output_count, unsigned int channels) {
+    EffectContext ctx;
+
+    if (slot < 0 || slot >= EFFECT_PROCESSOR_SLOTS || NIL_P(effect_processors[slot]) ||
+        *output_count == 0) {
+        *output_count = 0;
+        return;
+    }
+
+    ctx.slot = slot;
+    ctx.input = input;
+    ctx.input_count = (input != NULL) ? *input_count : 0;
+    ctx.output = output;
+    ctx.output_count = *output_count;
+    ctx.requested_output_count = *output_count;
+    ctx.channels = channels;
+
+    if (!run_on_ruby_thread(effect_run, &ctx, EFFECT_JOB_TIMEOUT_MS)) {
+        /* Timed out before the worker even claimed the job (e.g. GVL
+           contention): degrade to silence for this callback rather than
+           stall the audio thread. */
+        effect_output_silence(&ctx);
+    }
+
+    /* The processor consumed every input frame it was offered. */
+    *input_count = ctx.input_count;
+    *output_count = ctx.output_count;
+}
+
+#define EFFECT_THUNK(n)                                                                            \
+    static void effect_thunk_##n(const float* input, unsigned int* input_count, float* output,     \
+                                 unsigned int* output_count, unsigned int channels) {              \
+        effect_invoke(n, input, input_count, output, output_count, channels);                      \
+    }
+
+EFFECT_THUNK(0)
+EFFECT_THUNK(1)
+EFFECT_THUNK(2)
+EFFECT_THUNK(3)
+EFFECT_THUNK(4)
+EFFECT_THUNK(5)
+EFFECT_THUNK(6)
+EFFECT_THUNK(7)
+EFFECT_THUNK(8)
+EFFECT_THUNK(9)
+EFFECT_THUNK(10)
+EFFECT_THUNK(11)
+EFFECT_THUNK(12)
+EFFECT_THUNK(13)
+EFFECT_THUNK(14)
+EFFECT_THUNK(15)
+EFFECT_THUNK(16)
+EFFECT_THUNK(17)
+EFFECT_THUNK(18)
+EFFECT_THUNK(19)
+EFFECT_THUNK(20)
+EFFECT_THUNK(21)
+EFFECT_THUNK(22)
+EFFECT_THUNK(23)
+EFFECT_THUNK(24)
+EFFECT_THUNK(25)
+EFFECT_THUNK(26)
+EFFECT_THUNK(27)
+EFFECT_THUNK(28)
+EFFECT_THUNK(29)
+EFFECT_THUNK(30)
+EFFECT_THUNK(31)
+
+static sfEffectProcessor effect_thunks[EFFECT_PROCESSOR_SLOTS] = {
+    effect_thunk_0,  effect_thunk_1,  effect_thunk_2,  effect_thunk_3,  effect_thunk_4,
+    effect_thunk_5,  effect_thunk_6,  effect_thunk_7,  effect_thunk_8,  effect_thunk_9,
+    effect_thunk_10, effect_thunk_11, effect_thunk_12, effect_thunk_13, effect_thunk_14,
+    effect_thunk_15, effect_thunk_16, effect_thunk_17, effect_thunk_18, effect_thunk_19,
+    effect_thunk_20, effect_thunk_21, effect_thunk_22, effect_thunk_23, effect_thunk_24,
+    effect_thunk_25, effect_thunk_26, effect_thunk_27, effect_thunk_28, effect_thunk_29,
+    effect_thunk_30, effect_thunk_31};
+
+sfEffectProcessor effect_processor_acquire(VALUE rb_proc, int* slot) {
+    int i;
+
+    /* Replacing the processor on a source that already has one reuses its
+       slot, so a source never leaks slots across repeated assignment. */
+    if (*slot >= 0 && *slot < EFFECT_PROCESSOR_SLOTS) {
+        if (NIL_P(rb_proc)) {
+            effect_processors[*slot] = Qnil;
+            return NULL;
+        }
+
+        effect_processors[*slot] = rb_proc;
+
+        return effect_thunks[*slot];
+    }
+
+    if (NIL_P(rb_proc)) {
+        *slot = -1;
+        return NULL;
+    }
+
+    for (i = 0; i < EFFECT_PROCESSOR_SLOTS; i++) {
+        if (NIL_P(effect_processors[i])) {
+            effect_processors[i] = rb_proc;
+            *slot = i;
+
+            return effect_thunks[i];
+        }
+    }
+
+    rb_raise(rb_eRuntimeError, "all %d effect-processor slots are in use", EFFECT_PROCESSOR_SLOTS);
+
+    return NULL;
+}
+
+void effect_processor_release(int slot) {
+    if (slot >= 0 && slot < EFFECT_PROCESSOR_SLOTS) {
+        effect_processors[slot] = Qnil;
+    }
+}

data/ext/audio/effect_processor.h

@@ -0,0 +1,25 @@
+#ifndef SFML_RB_AUDIO_EFFECT_PROCESSOR_H
+#define SFML_RB_AUDIO_EFFECT_PROCESSOR_H
+
+#include <ruby.h>
+
+#include "core/sfml.h"
+
+/* sfEffectProcessor carries no userData, so a single C callback cannot tell
+   which sound source invoked it. Instead the binding keeps a fixed pool of
+   identical C thunks, each hard-wired to one slot; assigning a processor to a
+   source hands it the thunk for that source's slot. Slots are bounded, and
+   exceeding the pool raises rather than silently sharing one callback. */
+#define EFFECT_PROCESSOR_SLOTS 32
+
+/* Registers every slot as a GC root. Must run before any acquire. */
+void Init_EffectProcessor(void);
+
+/* Stores rb_proc in a free slot, writes its index to *slot and returns the
+   matching thunk. Passing nil returns NULL (no processor). */
+sfEffectProcessor effect_processor_acquire(VALUE rb_proc, int *slot);
+
+/* Frees a slot previously handed out, clearing the Ruby reference. */
+void effect_processor_release(int slot);
+
+#endif //SFML_RB_AUDIO_EFFECT_PROCESSOR_H