ruby-sfml 3.0.0.0 → 3.0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8688630fa5286e1b5c28ed9c5cda8aa635a197fe74dc422859253f45f11f111a
-  data.tar.gz: bcb83c0e0667fcae607fa3d3b0ca32527d25dec96fd8726ae697b1b5340c68f9
+  metadata.gz: 7f6e44279278680f06163024e2dd2f1eecbc8e8624960d589ec74e591849c9b3
+  data.tar.gz: 23fc48fc06aa0f7e6807b681c2601784de0159d9429055617e87d1e7977d20fa
 SHA512:
-  metadata.gz: d2a0d250ee6f2a7ca62d7da0305f3345bed8170be02f7700074ae1dbb76a24379687c13e64488ab6cbea5eed78821aa9554ecac6501a76ca16eb3febcbe8ca47
-  data.tar.gz: f9b7399e3e2b6168e217292573ef54a15a6217c4675f21f3718a4786787590fda2900d6795b68cd422ca1a5859962aa75d51371305f3ca1584914d5d4e0d13e2
+  metadata.gz: d351b03bb583fb5bb7ddd469da17838d876d7f5c99cbdae5387c94dfbf933f7299362d70bc8360c71b1b5737c49622bb55795869f2bd49d1784aab910f16d32d
+  data.tar.gz: d5b91cdb38ee758ca2fc76daf52f2aba4c6172b7d6798d51783caa677a10684d394881dca6e01e704e8db9d1be372ef38035de43e4f49b3bab26a9066d5728f5

data/CHANGELOG.md

@@ -8,6 +8,136 @@ ruby-sfml's own patch level.
 
 ## [Unreleased]
 
+## [3.0.0.1] — 2026-05-07
+
+### Added
+- `Window#icon=` and `RenderWindow#icon=` — set the window's title-bar /
+  taskbar icon from any `SFML::Image`. Wraps `sfWindow_setIcon` /
+  `sfRenderWindow_setIcon`. New example
+  [21_window_icon](examples/21_window_icon/window_icon.rb) builds a
+  procedural 32×32 ruby-style icon to demo the API.
+- `Image#save_to_memory(format)` — encode an image to a Ruby String of
+  bytes in the given format (`"png"`, `"jpg"`, `"bmp"`, `"tga"`),
+  without touching the disk. Useful for screenshots over the network,
+  data: URLs, or piping into other image-processing libraries. Wraps
+  `sfImage_saveToMemory` plus the `sfBuffer_*` helpers in
+  libcsfml-system.
+- Shader array uniforms — `shader[:positions] = [[x, y], ...]` and
+  similar for vec3 / vec4 arrays; also accepts `Vector2` / `Vector3`
+  elements interchangeably. New explicit `Shader#set_float_array` for
+  `uniform float arr[N];` (which can't be inferred via `[]=` because
+  it'd collide with the vec3 case). Wraps the
+  `sfShader_set{Float,Vec2,Vec3,Vec4}UniformArray` family.
+- `Window#minimum_size=` / `#maximum_size=` and the same on
+  `RenderWindow` — clamp how small or large the OS lets the user
+  drag the window. Accepts `[w, h]`, `Vector2`, or `nil` (clears the
+  limit). Wraps `sfWindow_setMinimumSize` / `setMaximumSize` and the
+  RenderWindow equivalents.
+- `Listener.velocity` and `Listener.cone` — finish the 3D-audio
+  surface on the listener side. Velocity feeds the Doppler effect
+  for sources whose `doppler_factor` is non-zero; cone (a
+  `SoundCone`, or a Hash convertible to one) attenuates sources
+  outside a directional pickup pattern.
+- 3D-audio polish for `Sound` and `Music` — now expose `velocity`,
+  `doppler_factor`, `direction`, and `cone` (via the new
+  `SFML::SoundCone` value class — `inner_angle`, `outer_angle`,
+  `outer_gain`). Cone setter accepts both a `SoundCone` and a
+  Hash. Plus `effect_processor=` for installing a real-time DSP
+  Ruby callable on the audio thread (`->(samples, channels) {
+  ... }`); pass `nil` to remove it. The DSP path is documented as
+  Ruby+GVL-limited and best for very light effects only. Wraps
+  the corresponding `sfSound_*` and `sfMusic_*` setters/getters
+  plus `setEffectProcessor`.
+- `SFML::VertexBuffer` — GPU-resident vertex buffer (VBO). Same
+  shape as `VertexArray` but vertices live on the GPU, so a draw
+  call ships only an OpenGL handle instead of re-uploading every
+  frame. `new(vertices, primitive_type:, usage:)` (one of `:stream`
+  / `:dynamic` / `:static`), `update(vertices, offset:)` for
+  partial uploads, `draw_range_on(target, first, count)` to draw a
+  slice. `VertexBuffer.available?` reports whether the GPU
+  supports VBOs at all (fall back to `VertexArray` if it doesn't).
+  Wraps the `sfVertexBuffer_*` family plus the
+  `sfRender{Window,Texture}_drawVertexBuffer{,Range}` draw paths.
+- `Window.from_handle` / `RenderWindow.from_handle` — wrap an
+  existing OS-level window (HWND, NSView*, X11 Window xid). The
+  outside framework owns the window's lifecycle; SFML just renders
+  into it. Pair with `#native_handle` to interop in the other
+  direction. Wraps `sfWindow_createFromHandle` /
+  `sfRenderWindow_createFromHandle` and the matching
+  `getNativeHandle` getters.
+- `SFML::SoundStream` — procedural audio source. Subclass it and
+  override `#on_get_data` to return an Array of `Int16` PCM samples
+  (or `nil` to stop); optionally override `#on_seek(time)` to
+  support `playing_offset=`. Same playback / 3D-positional API as
+  `Sound` and `Music` (volume, pitch, looping, position,
+  attenuation, min_distance, relative_to_listener). Wraps the full
+  `sfSoundStream_*` family. Includes example
+  [23_sound_stream](examples/23_sound_stream/sound_stream.rb) — a
+  real-time sine synth with arrow-key pitch / volume control.
+- `SFML::Network::SocketSelector` — multiplex many sockets onto one
+  blocking `wait`. `add` / `remove` / `clear` / `wait(timeout:)`
+  / `ready?(socket)`. Polymorphic across `TcpListener`, `TcpSocket`,
+  `UdpSocket`. The `wait` call releases the GVL, so other Ruby
+  threads keep running during the syscall. Wraps the
+  `sfSocketSelector_*` family.
+- `SFML::Network::Ftp` — CSFML's FTP client wrapped as idiomatic Ruby:
+  `connect`, `login` / `login_anonymous`, `working_directory`,
+  `directory_listing`, `change_directory`, `parent_directory`,
+  `create_directory`, `delete_directory`, `rename_file`,
+  `delete_file`, `download`, `upload`, `send_command`, `keep_alive`,
+  `disconnect`. Each call returns a `Response` (or
+  `DirectoryResponse` / `ListingResponse`) with `#ok?`, `#status`,
+  `#status_symbol`, `#message`, plus `#directory` or `#names`
+  where applicable. Network calls release the GVL.
+  Same caveat as Http — Ruby stdlib `Net::FTP` is the better choice
+  in production.
+- `SFML::Network::Http` — CSFML's HTTP/1.x client in idiomatic Ruby
+  form. `Http.new(host, port:)` plus `#send_request(method:, uri:,
+  fields:, body:, http_version:, timeout:)` returns an `Http::Response`
+  with `#status` (Integer) / `#status_symbol` (`:ok`, `:not_found`,
+  `:connection_failed`, …), `#body`, `#field(name)`, `#http_version`.
+  Marked `blocking: true` so the GVL is released during the network
+  round-trip and concurrent Ruby threads can run. Wraps
+  `sfHttp_*`, `sfHttpRequest_*`, `sfHttpResponse_*`. Note: for any
+  non-trivial use (TLS, redirects, JSON, retries), Ruby's stdlib
+  `Net::HTTP` is the better tool — this binding exists for parity
+  with CSFML, not because we recommend it.
+- `SFML::Sensor` polling module — `available?(type)`, `enable(type)`,
+  `disable(type)`, `value(type)` for the six sensor types
+  (`:accelerometer`, `:gyroscope`, `:magnetometer`, `:gravity`,
+  `:user_acceleration`, `:orientation`). The `:sensor_changed` event
+  variant now decodes its `sensor:` and `value:` payloads. Wraps
+  `sfSensor_isAvailable` / `sfSensor_setEnabled` /
+  `sfSensor_getValue`.
+- `SFML::Touch` polling module — `down?(finger)` and
+  `position(finger, relative_to: window)`. Touch event variants
+  (`:touch_began`, `:touch_moved`, `:touch_ended`) now decode their
+  `finger:` and `position:` payloads (previously fell through to
+  empty data). Wraps `sfTouch_isDown` / `sfTouch_getPosition` /
+  `sfTouch_getPositionRenderWindow`.
+- `Sound#playing_offset` / `playing_offset=` and `Music#playing_offset`
+  / `playing_offset=` — read or seek the playback head as a
+  `SFML::Time`. Setter also accepts a Numeric (interpreted as
+  seconds). Wraps `sfSound_setPlayingOffset` /
+  `sfMusic_setPlayingOffset` and the matching getters.
+- Stencil buffer support — new `SFML::StencilMode` value class with
+  symbolic comparisons (`:equal`, `:always`, etc.) and update
+  operations (`:replace`, `:keep`, etc.). Pass it via `stencil_mode:`
+  to `RenderTarget#draw` for two-pass mask/clip effects, and clear
+  the stencil with `target.clear(color, stencil: N)` or
+  `target.clear(stencil: N)`. Wraps `sfRenderWindow_clearStencil` /
+  `clearColorAndStencil` (and the RenderTexture twins) plus the
+  existing `stencil_mode` slot in `sfRenderStates`. New example
+  [22_stencil_mask](examples/22_stencil_mask/stencil_mask.rb)
+  demonstrates a cursor-following spotlight that clips an animated
+  rainbow background.
+
+### Fixed
+- `at_exit` hook now writes the unhandled exception (message, class,
+  backtrace) to stderr before calling `exit!`. Previously `exit!`
+  short-circuited Ruby's terminal exception reporter, so an error in
+  `setup` or any other top-level user code looked like a silent exit.
+
 ## [3.0.0.0] — initial release
 
 First public cut. Targets **CSFML 3.0.0** (released March 2025) and

data/README.md

@@ -2,7 +2,7 @@
 
 Modern, idiomatic Ruby bindings for [SFML 3.x](https://www.sfml-dev.org/) via [CSFML](https://github.com/SFML/CSFML) and [Ruby FFI](https://github.com/ffi/ffi).
 
-> **Status:** the API surface is complete for SFML 3.0 — system, window, graphics, audio, network, plus the higher-level `Game` and `Assets` helpers. 287 RSpec examples, 20 runnable example folders. Some details (gem-build verification, RBS signatures, hosted docs) are still pending.
+> **Status:** the API surface is complete for SFML 3.0 — system, window, graphics (incl. stencil buffer + VBOs), audio (incl. 3D positional + custom DSP + procedural streams), network (incl. HTTP / FTP / socket selector), input (keyboard, mouse, joystick, touch, sensors), plus the higher-level `Game` and `Assets` helpers. 387 RSpec examples, 23 runnable example folders. RBS signatures are the main remaining engineering item.
 
 ## Why
 
@@ -76,61 +76,47 @@ end
 | Area     | Classes                                                      |
 | -------- | ------------------------------------------------------------ |
 | System   | `Vector2`, `Vector3`, `Rect`, `Time`, `Clock`                |
-| Window   | `RenderWindow`, `Window` (bare, GL-only), `VideoMode`, `Event`, `Keyboard`, `Mouse`, `Joystick`, `Cursor`, `Clipboard` |
-| Graphics | `Color`, `Image`, `Texture`, `RenderTexture`, `Sprite`, `CircleShape`, `RectangleShape`, `ConvexShape`, `Vertex`, `VertexArray`, `Font`, `Text`, `View`, `BlendMode`, `RenderStates`, `Shader`, `Transform` |
-| Audio    | `SoundBuffer`, `Sound`, `Music`, `Listener`, `SoundRecorder`, `SoundBufferRecorder` (3D positional audio supported on Sound and Music) |
+| Window   | `RenderWindow`, `Window` (bare, GL-only), `VideoMode`, `Event`, `Keyboard`, `Mouse`, `Joystick`, `Touch`, `Sensor`, `Cursor`, `Clipboard` |
+| Graphics | `Color`, `Image`, `Texture`, `RenderTexture`, `Sprite`, `CircleShape`, `RectangleShape`, `ConvexShape`, `Vertex`, `VertexArray`, `VertexBuffer`, `Font`, `Text`, `View`, `BlendMode`, `StencilMode`, `RenderStates`, `Shader`, `Transform` |
+| Audio    | `SoundBuffer`, `Sound`, `Music`, `Listener`, `SoundCone`, `SoundStream`, `SoundRecorder`, `SoundBufferRecorder` (3D positional + cones + Doppler + custom DSP via `effect_processor=`) |
 | Helpers  | `Assets` (search-path + cache), `Game` (lifecycle main loop) |
 
-**Network**: `IpAddress`, `TcpSocket`, `TcpListener`, `UdpSocket` for stream / datagram networking.
+**Network**: `IpAddress`, `TcpSocket`, `TcpListener`, `UdpSocket`, `SocketSelector` for stream / datagram networking, plus the niche `Http` and `Ftp` clients (use Ruby's `Net::HTTP` / `Net::FTP` if you have the choice — these exist for parity with CSFML).
 
 ## What's intentionally *not* wrapped
 
-CSFML 3 has a few corners we deliberately don't expose. Each is either
-(a) niche enough not to justify the surface area, (b) better served by
-a Ruby standard library, or (c) requires patterns that don't translate
-cleanly to FFI.
-
-**Use Ruby stdlib instead**
-- `sf::Http` — `Net::HTTP` is a better Ruby fit
-- `sf::Ftp` — `Net::FTP` likewise
-- `sf::SocketSelector` — `IO.select` or [Async](https://github.com/socketry/async)
-
-**Callback-based APIs that fight FFI / the GVL**
-- Raw `sf::SoundRecorder` (per-buffer callbacks on the audio thread) —
-  use `SFML::SoundBufferRecorder` for "record into memory, save on stop"
-- `sf::SoundStream` (custom audio source via inheritance) — niche; if
-  you need it, generate samples to a file and play via `Music`
-
-**Mobile / niche inputs** (SFML 3 itself treats these as experimental)
-- `sf::Touch`, `sf::Sensor` (accelerometer, gyro, etc.)
-
-**Advanced graphics features**
-- `sf::VertexBuffer` (static GPU vertex buffer) — `VertexArray` covers
-  the common case; if you need static-mesh perf, open an issue
-- Geometry shaders — only vertex and fragment stages on `SFML::Shader`
-- `sf::Shader#setUniformArray` (bulk uniforms) — set elements one by one
-- Stencil buffer ops (`clearStencil`, custom `StencilMode`) — accept
-  CSFML defaults
-- `sf::Image#saveToMemory` — only `Image#save(path)` is wrapped
-
-**Advanced audio features**
-- Sound / Music cones, velocity, Doppler factor, custom DSP via
-  `setEffectProcessor` — basic 3D positional + attenuation is in;
-  the rest is rarely used in 2D gamedev
-- `sf::Listener` cone — same reasoning
-
-**Embedding / integration corners**
-- `RenderWindow.createFromHandle` (embed in another framework's window)
-- Custom `sf::InputStream` for loading assets from non-file sources
-- Window icon, min/max size, native handle accessors on `SFML::Window`
+A handful of CSFML 3 corners deliberately stay out:
+
+- **Geometry shaders** — CSFML doesn't expose them at all (only vertex
+  and fragment stages); nothing for us to wrap.
+- **Raw `sf::SoundRecorder`** (per-buffer callbacks on the audio
+  thread) — use `SFML::SoundBufferRecorder` for the common "record
+  into memory, save on stop" path. The raw callback variant fights
+  the GVL hard.
+- **Custom `sf::InputStream`** for loading assets from non-file
+  sources — Ruby has `IO`, just read into memory and use the
+  byte-string constructors.
+
+**An aside on `Http` / `Ftp` / `SocketSelector`** — these *are*
+wrapped (matches CSFML for parity), but for any non-trivial use
+Ruby's stdlib `Net::HTTP` / `Net::FTP` and `IO.select` are better
+tools.
+
+**An aside on `SoundStream` and `effect_processor=`** — both *are*
+wrapped, but their callbacks run on the SFML audio thread and
+must reacquire the GVL each invocation. Fine for trivial DSP;
+expect glitches for anything heavier.
 
 **Other Ruby bindings worth knowing about**
+
 - SFML 2.x is *not* covered. The previous-generation gem
   [rbSFML](https://github.com/Groogy/rbSFML) targets SFML 2; it's
   unmaintained and only works with Ruby ≤ 2.2.
+- **RubySFML3** (Andy P., 2026) — a thin FFI wrapper that exposes
+  the CSFML C API directly. If you want raw bindings (no idiomatic
+  Ruby layer, no auto-cleanup), check that project instead.
 
-If anything in the list above is blocking you, **open an issue** —
-"niche" is just a default, not a closed door.
+If anything missing here is blocking you, **open an issue**.
 
 ## Examples
 
@@ -164,6 +150,9 @@ bundle exec ruby examples/<NN_name>/<name>.rb
 | 18  | [draw_primitives](examples/18_draw_primitives/draw_primitives.rb)              | Raw `draw_primitives` — line burst rebuilt every frame             |
 | 19  | [udp_loopback](examples/19_udp_loopback/udp_loopback.rb)                       | UDP send/receive on localhost via `Network::UdpSocket`             |
 | 20  | [bare_window](examples/20_bare_window/bare_window.rb)                          | `SFML::Window` (no 2D batcher) — events for raw-OpenGL apps        |
+| 21  | [window_icon](examples/21_window_icon/window_icon.rb)                          | Procedural 32×32 icon set as the window/taskbar icon              |
+| 22  | [stencil_mask](examples/22_stencil_mask/stencil_mask.rb)                       | Two-pass `StencilMode` masking — cursor spotlight clip            |
+| 23  | [sound_stream](examples/23_sound_stream/sound_stream.rb)                       | Real-time sine synth via `SFML::SoundStream` subclass             |
 
 ## Idioms baked in
 

data/lib/sfml/audio/internal.rb

@@ -0,0 +1,41 @@
+module SFML
+  module Audio
+    # Internal helpers shared between Sound, Music, and SoundStream.
+    # Not part of the public API.
+    module_function
+
+    # Build an FFI::Function that adapts CSFML's effect-processor
+    # signature (raw float buffers, in/out frame counts) to a Ruby
+    # callable taking `(samples, channels)` and returning samples.
+    #
+    # Returns the FFI::Function — callers must keep a strong Ruby
+    # reference to it for as long as it's installed (otherwise GC
+    # collects the closure and the audio thread crashes).
+    def _build_effect_processor(callable)
+      FFI::Function.new(
+        :void,
+        [:pointer, :pointer, :pointer, :pointer, :uint32, :pointer],
+      ) do |in_ptr, in_cnt_ptr, out_ptr, out_cnt_ptr, channels, _user|
+        in_count  = in_cnt_ptr.read_uint32
+        out_count = out_cnt_ptr.read_uint32
+
+        written = 0
+        if in_count > 0
+          input = in_ptr.read_array_of_float(in_count * channels)
+          output =
+            begin
+              callable.call(input, channels) || []
+            rescue => e
+              warn "ruby-sfml effect_processor raised: #{e.class}: #{e.message}"
+              []
+            end
+
+          written = [output.length / channels, out_count].min
+          out_ptr.write_array_of_float(output.first(written * channels)) if written.positive?
+        end
+
+        out_cnt_ptr.write_uint32(written)
+      end
+    end
+  end
+end

data/lib/sfml/audio/listener.rb

@@ -51,5 +51,36 @@ module SFML
       vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
       C::Audio.sfListener_setUpVector(vec.to_native_f)
     end
+
+    # Listener velocity in world units / second — used by the
+    # Doppler effect on sources whose `doppler_factor` is non-zero.
+    def velocity
+      Vector3.from_native(C::Audio.sfListener_getVelocity)
+    end
+
+    def velocity=(value)
+      vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
+      C::Audio.sfListener_setVelocity(vec.to_native_f)
+    end
+
+    # Directional cone for the listener — same shape as the cone on
+    # individual sound sources (see SFML::SoundCone). Used for
+    # cone-shaped attenuation when the listener faces a particular
+    # direction (think headphones turning to follow a character's
+    # head).
+    def cone
+      SoundCone.from_native(C::Audio.sfListener_getCone)
+    end
+
+    def cone=(value)
+      cone =
+        case value
+        when SoundCone then value
+        when Hash      then SoundCone.new(**value)
+        else
+          raise ArgumentError, "Listener.cone= expects SoundCone or Hash; got #{value.class}"
+        end
+      C::Audio.sfListener_setCone(cone.to_native)
+    end
   end
 end

data/lib/sfml/audio/music.rb

@@ -29,6 +29,70 @@ module SFML
 
     def duration = Time.from_native(C::Audio.sfMusic_getDuration(@handle))
 
+    # Current playback head as a SFML::Time. Reads from the underlying
+    # OpenAL source — only meaningful while the music is playing or
+    # paused (not after #stop).
+    def playing_offset
+      Time.from_native(C::Audio.sfMusic_getPlayingOffset(@handle))
+    end
+
+    # Seek to `value` (a SFML::Time, or seconds as a Numeric). Works
+    # while the music is playing, paused, or stopped.
+    def playing_offset=(value)
+      t = value.is_a?(Time) ? value : Time.seconds(value.to_f)
+      C::Audio.sfMusic_setPlayingOffset(@handle, t.to_native)
+    end
+
+    # 3D velocity, Doppler factor, direction, cone — see Sound for
+    # the same methods on the simpler buffered source.
+    def velocity
+      v = C::Audio.sfMusic_getVelocity(@handle)
+      Vector3.new(v[:x], v[:y], v[:z])
+    end
+
+    def velocity=(value)
+      vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
+      packed = C::System::Vector3f.new
+      packed[:x] = vec.x.to_f; packed[:y] = vec.y.to_f; packed[:z] = vec.z.to_f
+      C::Audio.sfMusic_setVelocity(@handle, packed)
+    end
+
+    def doppler_factor    = C::Audio.sfMusic_getDopplerFactor(@handle)
+    def doppler_factor=(v) C::Audio.sfMusic_setDopplerFactor(@handle, v.to_f); end
+
+    def direction
+      v = C::Audio.sfMusic_getDirection(@handle)
+      Vector3.new(v[:x], v[:y], v[:z])
+    end
+
+    def direction=(value)
+      vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
+      packed = C::System::Vector3f.new
+      packed[:x] = vec.x.to_f; packed[:y] = vec.y.to_f; packed[:z] = vec.z.to_f
+      C::Audio.sfMusic_setDirection(@handle, packed)
+    end
+
+    def cone
+      SoundCone.from_native(C::Audio.sfMusic_getCone(@handle))
+    end
+
+    def cone=(value)
+      cone =
+        case value
+        when SoundCone then value
+        when Hash      then SoundCone.new(**value)
+        else
+          raise ArgumentError, "Music#cone= expects SoundCone or Hash; got #{value.class}"
+        end
+      C::Audio.sfMusic_setCone(@handle, cone.to_native)
+    end
+
+    # See Sound#effect_processor= — same audio-thread DSP callback.
+    def effect_processor=(callable)
+      @effect_cb = callable.nil? ? nil : Audio._build_effect_processor(callable)
+      C::Audio.sfMusic_setEffectProcessor(@handle, @effect_cb, nil)
+    end
+
     # Cached on the Ruby side; see Sound#looping? for the why.
     def looping?
       @looping

data/lib/sfml/audio/sound.rb

@@ -41,6 +41,88 @@ module SFML
     def paused?     = status == :paused
     def stopped?    = status == :stopped
 
+    # Current playback head as a SFML::Time. Reads from the underlying
+    # OpenAL source — only meaningful while the sound is playing or
+    # paused (not after #stop).
+    def playing_offset
+      Time.from_native(C::Audio.sfSound_getPlayingOffset(@handle))
+    end
+
+    # Seek to `value` (a SFML::Time, or seconds as a Numeric). Works
+    # while the sound is playing, paused, or stopped — calling #play
+    # afterwards resumes from the new offset.
+    def playing_offset=(value)
+      t = value.is_a?(Time) ? value : Time.seconds(value.to_f)
+      C::Audio.sfSound_setPlayingOffset(@handle, t.to_native)
+    end
+
+    # 3D velocity in world units / second — used by the Doppler
+    # effect to shift pitch as the source approaches or recedes from
+    # the listener.
+    def velocity
+      v = C::Audio.sfSound_getVelocity(@handle)
+      Vector3.new(v[:x], v[:y], v[:z])
+    end
+
+    def velocity=(value)
+      vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
+      packed = C::System::Vector3f.new
+      packed[:x] = vec.x.to_f; packed[:y] = vec.y.to_f; packed[:z] = vec.z.to_f
+      C::Audio.sfSound_setVelocity(@handle, packed)
+    end
+
+    # Per-source Doppler scale. 1.0 is realistic; bump it up for an
+    # exaggerated Doppler shift, drop to 0 to disable per-source.
+    def doppler_factor    = C::Audio.sfSound_getDopplerFactor(@handle)
+    def doppler_factor=(v) C::Audio.sfSound_setDopplerFactor(@handle, v.to_f); end
+
+    # The direction the sound's cone points. Used together with
+    # #cone= for directional attenuation.
+    def direction
+      v = C::Audio.sfSound_getDirection(@handle)
+      Vector3.new(v[:x], v[:y], v[:z])
+    end
+
+    def direction=(value)
+      vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
+      packed = C::System::Vector3f.new
+      packed[:x] = vec.x.to_f; packed[:y] = vec.y.to_f; packed[:z] = vec.z.to_f
+      C::Audio.sfSound_setDirection(@handle, packed)
+    end
+
+    # Directional-attenuation cone — see SFML::SoundCone.
+    def cone
+      SoundCone.from_native(C::Audio.sfSound_getCone(@handle))
+    end
+
+    def cone=(value)
+      cone =
+        case value
+        when SoundCone then value
+        when Hash      then SoundCone.new(**value)
+        else
+          raise ArgumentError, "Sound#cone= expects SoundCone or Hash; got #{value.class}"
+        end
+      C::Audio.sfSound_setCone(@handle, cone.to_native)
+    end
+
+    # Install a real-time DSP filter. The callable is invoked from the
+    # CSFML audio thread once per audio frame batch with:
+    #   * `input` — Array<Float> of interleaved samples (signed [-1, 1])
+    #   * `channels` — Integer channel count (e.g. 2 for stereo)
+    # and should return an Array<Float> of the same length (or shorter
+    # if the effect produces fewer frames). Pass `nil` to remove an
+    # installed processor.
+    #
+    # CAVEAT: the callback runs on a real-time audio thread and is
+    # called every few milliseconds. Ruby + GVL is rarely fast enough
+    # for non-trivial DSP — expect glitches for anything heavier than
+    # a constant-gain or simple IIR. For real DSP, do it offline.
+    def effect_processor=(callable)
+      @effect_cb = callable.nil? ? nil : Audio._build_effect_processor(callable)
+      C::Audio.sfSound_setEffectProcessor(@handle, @effect_cb, nil)
+    end
+
     def looping?
       @looping
     end

data/lib/sfml/audio/sound_cone.rb

@@ -0,0 +1,56 @@
+module SFML
+  # Directional-attenuation cone for a 3D sound source. Inside the
+  # `inner_angle` cone the sound plays at full volume; outside the
+  # `outer_angle` cone it's attenuated by `outer_gain`; between the
+  # two it's smoothly interpolated.
+  #
+  # Angles are in degrees, measured from the source's `direction`
+  # axis. `outer_gain` is a scalar in [0, 1] (0 = silent outside).
+  #
+  #   sound.direction = [0, 0, -1]
+  #   sound.cone = SFML::SoundCone.new(
+  #     inner_angle: 30, outer_angle: 90, outer_gain: 0.2,
+  #   )
+  class SoundCone
+    attr_reader :inner_angle, :outer_angle, :outer_gain
+
+    def initialize(inner_angle:, outer_angle:, outer_gain:)
+      @inner_angle = inner_angle.to_f
+      @outer_angle = outer_angle.to_f
+      @outer_gain  = outer_gain.to_f
+      freeze
+    end
+
+    def ==(other)
+      other.is_a?(SoundCone) &&
+        inner_angle == other.inner_angle &&
+        outer_angle == other.outer_angle &&
+        outer_gain  == other.outer_gain
+    end
+    alias eql? ==
+    def hash = [inner_angle, outer_angle, outer_gain].hash
+
+    def to_s
+      "SoundCone(inner=#{inner_angle}°, outer=#{outer_angle}°, outer_gain=#{outer_gain})"
+    end
+    alias inspect to_s
+
+    # @!visibility private
+    def to_native
+      s = C::Audio::SoundSourceCone.new
+      s[:inner_angle] = @inner_angle
+      s[:outer_angle] = @outer_angle
+      s[:outer_gain]  = @outer_gain
+      s
+    end
+
+    # @!visibility private
+    def self.from_native(struct)
+      new(
+        inner_angle: struct[:inner_angle],
+        outer_angle: struct[:outer_angle],
+        outer_gain:  struct[:outer_gain],
+      )
+    end
+  end
+end