ruby-sfml 3.0.0.4 → 3.0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02adbbc1dc50cc42127dc845ad9be68829ee07c100cb915e83f15d2e8deb8df7
-  data.tar.gz: 59e6cadd1e7a325e70b7ad92b162f7ba3d73035fc482317e3ad0f28d8b7afcb6
+  metadata.gz: c20f8dbdc29ef33bf370ea4a7fbadf09f9652acc84834dc47f3ca9e325635d5d
+  data.tar.gz: f65b6a2c2799e01c45071e5801cb33056cdec961d3c52a1b4ffd209538868f51
 SHA512:
-  metadata.gz: da0f1e034c77f9a78fb202e4e40e90099aafac7fbe5b2261e94bd693e51f937098c5113491f723eefc45acc731f983b39cc6a27e372c81e6391f8b2777aee99e
-  data.tar.gz: a494f581e0cf1975c5233705838cc9f29f0f99fe88a793cd580478772c5170a0c440330c40f464947a689849d43b8e2c16b4b247c0cf4350eea5e35616d9ec90
+  metadata.gz: 4ef7eabaab2ffe015f2e2325926d4d41f6f941f49392d9d3d72570198d1e5df9873aeec8d4a82a32aeea3dddd2174010b0993ca0c9cfc4070eb6b6630394ec70
+  data.tar.gz: 0d8d30d9bae64f2c84ecef83acbaebf7eda423133c362e0d7b397c90a531ad72477bbe64c61d80f10cdfc1e8a316612a2d8ca71f14fd1fe4581b5eee66510218

data/CHANGELOG.md

@@ -8,6 +8,105 @@ ruby-sfml's own patch level.
 
 ## [Unreleased]
 
+## [3.0.0.5] — 2026-05-11
+
+Round-trip release: closes every remaining CSFML 3.0 gap that's
+useful from Ruby. The library now covers the surface area you'd
+expect for porting a CSFML application straight across.
+
+### Added — graphics
+
+- `Color#+`, `Color#-`, `Color#*` (alias `modulate`),
+  `Color#to_integer` / `Color.from_integer(value)` — channel-wise
+  saturating arithmetic, plus packed 0xRRGGBBAA round-trips.
+- Texture binding + geometric introspection on the three concrete
+  shapes via the new `Graphics::ShapeInspectable` mixin:
+  `CircleShape`/`RectangleShape`/`ConvexShape` all gain
+  `texture` / `texture=` / `set_texture(tex, reset_rect:)`,
+  `texture_rect` / `texture_rect=`, `point(i)`, `geometric_center`,
+  `local_bounds`, `global_bounds`, `transform`, `inverse_transform`,
+  `dup` / `clone`. `RectangleShape` additionally exposes
+  `point_count`.
+- `SFML::Shape` — callback-driven abstract shape. Subclass and
+  override `#point_count` / `#point(i)` to drive geometry from
+  live Ruby data; call `#update` after the source data changes.
+- `SFML::TransformableObject` — standalone transform container
+  (CSFML's `sfTransformable*`). Useful as a base for custom
+  drawables that combine a transform with their own rendering.
+- `VertexArray#dup` / `#clone` — independent deep copy.
+- `VertexBuffer#bind` / `VertexBuffer.unbind` — bind a VBO as the
+  active GL vertex buffer (for mixing raw GL with SFML rendering).
+- Texture sRGB variants via the `srgb:` kwarg on
+  `Texture.load`, `Texture.create`, `Texture.from_memory`,
+  `Texture.from_image`, and `Texture#resize`.
+- `Shader#set_mat3` / `#set_mat4` / `#set_mat3_array` /
+  `#set_mat4_array` and `Shader#set_bvec(name, *components)` —
+  matrix and bool-vector uniforms.
+- `Shader.from_stream(vertex:, geometry:, fragment:)`,
+  `Font.from_stream(io)`, `Image.from_stream(io)`,
+  `Texture.from_stream(io, srgb:, ...)` — load any of these from a
+  Ruby IO-like object (File, StringIO, network reader). Backed by
+  the new `SFML::InputStream` adapter that wraps a Ruby IO as
+  CSFML's `sfInputStream*`.
+
+### Added — audio
+
+- Full 3D-audio surface on `SoundStream` (mirror of Sound / Music):
+  `pan`, `min_gain` / `max_gain`, `max_distance`,
+  `spatialization_enabled?`, `direction`, `cone`, `velocity`,
+  `doppler_factor`, `directional_attenuation_factor`,
+  `effect_processor=` (real-time DSP filter), `channel_map` — and
+  the `=` setters.
+- `SoundRecorder#channel_map` — read the channel layout the
+  recorder is producing.
+- `SFML::SoundRecorder` — callback-based mic capture. Subclass
+  and override `#on_start` / `#on_process_samples(samples,
+  channels)` / `#on_stop`. The pre-existing module-level helpers
+  (`SoundRecorder.available?` / `.devices` / `.default_device`)
+  are preserved as class methods.
+- `Music.from_stream(io, **opts)` and
+  `SoundBuffer.from_stream(io)` — stream-backed audio loaders.
+
+### Added — network
+
+- `SFML::Network::Packet` — wire-compatible with `sf::Packet`. Typed
+  read / write for `Bool`, `Int8`–`Int64`, `Uint8`–`Uint64`,
+  `Float`, `Double`, `String`; `#data` / `#size` / `#read_position`
+  / `#end_of_packet?` / `#ok?` / `#clear` / `#dup`.
+- `TcpSocket#send_packet` / `#receive_packet` and
+  `UdpSocket#send_packet(packet, to:, port:)` /
+  `#receive_packet` — structured framing on top of the existing
+  raw byte send/receive.
+
+### Added — window
+
+- `Keyboard::SCAN_CODES` — full layout-independent scancode table
+  (146 entries matching `sfScancode`).
+- `Keyboard.scancode_pressed?(:scan_w)` — query the physical key
+  regardless of keyboard layout (the standard for WASD-style games).
+- `Keyboard.localize(scancode)` / `.delocalize(key)` /
+  `.description(scancode)` — convert between physical scancodes
+  and logical keys under the current OS layout, plus the
+  human-readable description string.
+- `Keyboard.virtual_keyboard_visible=` — on-screen keyboard toggle
+  for touchscreen / mobile builds (no-op on desktop).
+- `VideoMode.fullscreen_modes` — all video modes the display
+  supports for true-fullscreen window creation, sorted from most
+  to least pixels.
+- `VideoMode#valid?` — does the display actually support this mode
+  at fullscreen?
+- `SFML::Context` — headless GL context. Activate it on a thread
+  to compile shaders / make raw GL calls without a window. Static
+  `Context.active_context_id`, `.extension_available?(name)`,
+  `.gl_function(name)`.
+
+### Added — system
+
+- `SFML::InputStream(io)` — wraps a Ruby IO-like object (anything
+  answering `read` / `seek` / `pos` / `size`) as the
+  `sfInputStream*` argument CSFML loader functions take. Used
+  internally by every `*.from_stream` factory.
+
 ## [3.0.0.4] — 2026-05-09
 
 ### Added — graphics

data/lib/sfml/audio/music.rb

@@ -29,6 +29,20 @@ module SFML
       m
     end
 
+    # Stream music straight from a Ruby IO-like object. CSFML reads
+    # the audio lazily on its decoding thread — keep the IO open
+    # until you stop the Music.
+    def self.from_stream(io, **opts)
+      stream = SFML::InputStream.new(io)
+      ptr = C::Audio.sfMusic_createFromStream(stream.to_ptr)
+      raise Error, "sfMusic_createFromStream returned NULL — unsupported format?" if ptr.null?
+
+      m = _wrap(ptr, opts)
+      m.instance_variable_set(:@_stream_pin, stream)
+      m.instance_variable_set(:@_io_pin, io)
+      m
+    end
+
     # Internal — finish initialising a Music from an already-built
     # CSFML pointer.
     def self._wrap(ptr, opts)

data/lib/sfml/audio/sound_buffer.rb

@@ -29,6 +29,19 @@ module SFML
       buf
     end
 
+    # Load fully-decoded audio from any Ruby IO-like object. The
+    # whole stream is decoded into RAM — for streaming playback,
+    # use `Music.from_stream` instead.
+    def self.from_stream(io)
+      stream = SFML::InputStream.new(io)
+      ptr = C::Audio.sfSoundBuffer_createFromStream(stream.to_ptr)
+      raise Error, "sfSoundBuffer_createFromStream returned NULL — unsupported format?" if ptr.null?
+
+      buf = allocate
+      buf.send(:_take_ownership, ptr)
+      buf
+    end
+
     # Default channel-layout map for the common 1- and 2-channel
     # cases — saves callers from spelling out the SoundChannel
     # enum just to build a mono blip or stereo waveform.

data/lib/sfml/audio/sound_recorder.rb

@@ -1,30 +1,143 @@
 module SFML
-  # Static helpers for audio capture. Use SFML::SoundBufferRecorder
-  # to actually record; these tell you what hardware is available.
+  # Callback-based audio-capture base class. Subclass and override
+  # `#on_start` (initialise capture state, return `true` to begin),
+  # `#on_process_samples(samples, channels)` (called every audio chunk
+  # with an Array<Integer> of interleaved int16 PCM, return `true` to
+  # keep recording or `false` to stop), and `#on_stop` (release any
+  # resources).
   #
-  #   SFML::SoundRecorder.available?           #=> true / false
-  #   SFML::SoundRecorder.devices              #=> ["alsa_input.pci-...", ...]
-  #   SFML::SoundRecorder.default_device       #=> "alsa_input.pci-..."
-  module SoundRecorder
-    module_function
-
-    # Is at least one audio input device present on the host?
-    def available?
+  # The simpler "record to a SoundBuffer" path lives in
+  # SFML::SoundBufferRecorder — reach for SoundRecorder only when you
+  # need to stream samples somewhere else (file, socket, DSP pipeline).
+  #
+  #   class LevelMeter < SFML::SoundRecorder
+  #     def on_start
+  #       @peak = 0
+  #       true
+  #     end
+  #
+  #     def on_process_samples(samples, _channels)
+  #       @peak = [@peak, *samples.map(&:abs)].max
+  #       true
+  #     end
+  #
+  #     def on_stop
+  #       puts "Peak: #{@peak}"
+  #     end
+  #   end
+  #
+  #   meter = LevelMeter.new
+  #   meter.start(sample_rate: 44_100)
+  #   sleep 2
+  #   meter.stop
+  #
+  # CAVEATS
+  # * All three callbacks run on CSFML's audio thread; heavy Ruby work
+  #   on the audio thread will glitch the capture.
+  # * Always keep a reference to the SoundRecorder object — if the Ruby
+  #   object is GC'd while CSFML is mid-capture, the process crashes.
+  class SoundRecorder
+    # ---- Static helpers (work without a recorder instance) ------------
+
+    def self.available?
       C::Audio.sfSoundRecorder_isAvailable
     end
 
-    def default_device
+    def self.default_device
       C::Audio.sfSoundRecorder_getDefaultDevice
     end
 
     # All input devices the OS exposes to SFML, as an Array of String
-    # names. Pass any of them to SoundBufferRecorder#device= to switch.
-    def devices
+    # names. Pass any of them to SoundRecorder#device= or
+    # SoundBufferRecorder#device= to switch.
+    def self.devices
       count_buf = FFI::MemoryPointer.new(:size_t)
       array_ptr = C::Audio.sfSoundRecorder_getAvailableDevices(count_buf)
       n = count_buf.read(:size_t)
       return [] if array_ptr.null? || n.zero?
       array_ptr.read_array_of_pointer(n).map { |p| p.read_string }
     end
+
+    # ---- Instance API -------------------------------------------------
+
+    def initialize
+      # Strong refs so the GC doesn't disappear callbacks under CSFML.
+      @start_cb = FFI::Function.new(:bool, [:pointer]) do |_user|
+        on_start ? true : false
+      end
+      @process_cb = FFI::Function.new(:bool, [:pointer, :size_t, :pointer]) do |samples_ptr, count, _user|
+        samples = count.zero? ? [] : samples_ptr.read_array_of_int16(count)
+        on_process_samples(samples, channel_count) ? true : false
+      end
+      @stop_cb = FFI::Function.new(:void, [:pointer]) do |_user|
+        on_stop
+        nil
+      end
+
+      ptr = C::Audio.sfSoundRecorder_create(@start_cb, @process_cb, @stop_cb, nil)
+      raise Error, "sfSoundRecorder_create returned NULL" if ptr.null?
+
+      @handle = FFI::AutoPointer.new(ptr, C::Audio.method(:sfSoundRecorder_destroy))
+    end
+
+    # ---- Subclass hooks ----
+
+    # Called once before the capture starts. Return `true` to begin
+    # the capture or `false` to abort. Default does nothing and
+    # accepts the start.
+    def on_start
+      true
+    end
+
+    # Called with each chunk of captured audio. `samples` is an
+    # Array<Integer> of interleaved int16 PCM (length = frames *
+    # channels). Return `true` to keep capturing or `false` to stop.
+    # Default raises so subclasses must implement it.
+    def on_process_samples(_samples, _channels)
+      raise NoMethodError, "#{self.class} must override #on_process_samples"
+    end
+
+    # Called once after the capture is done. Default is a no-op.
+    def on_stop; end
+
+    # ---- Public recorder API ----
+
+    def start(sample_rate: 44_100)
+      C::Audio.sfSoundRecorder_start(@handle, Integer(sample_rate)) ||
+        raise(Error, "sfSoundRecorder_start failed (no input device or driver error)")
+      self
+    end
+
+    def stop
+      C::Audio.sfSoundRecorder_stop(@handle)
+      self
+    end
+
+    def sample_rate   = C::Audio.sfSoundRecorder_getSampleRate(@handle)
+    def channel_count = C::Audio.sfSoundRecorder_getChannelCount(@handle)
+
+    def channel_count=(n)
+      C::Audio.sfSoundRecorder_setChannelCount(@handle, Integer(n))
+    end
+
+    def device = C::Audio.sfSoundRecorder_getDevice(@handle)
+
+    def device=(name)
+      C::Audio.sfSoundRecorder_setDevice(@handle, name.to_s) ||
+        raise(Error, "sfSoundRecorder_setDevice failed for #{name.inspect}")
+    end
+
+    # The channel layout the recorder is producing, as an Array of
+    # `sfSoundChannel` enum values (1 = Mono, 2 = FrontLeft,
+    # 3 = FrontRight, etc — see SoundBuffer::DEFAULT_CHANNEL_MAPS).
+    def channel_map
+      count_buf = FFI::MemoryPointer.new(:size_t)
+      ptr = C::Audio.sfSoundRecorder_getChannelMap(@handle, count_buf)
+      n = count_buf.read(:size_t)
+      return [] if ptr.null? || n.zero?
+      ptr.read_array_of_int32(n)
+    end
+
+    attr_reader :handle # :nodoc:
   end
 end

data/lib/sfml/audio/sound_stream.rb

@@ -169,6 +169,109 @@ module SFML
       C::Audio.sfSoundStream_setRelativeToListener(@handle, !!value)
     end
 
+    # ---- 3D-audio surface (mirror of Sound / Music) -------------------
+
+    def pan = C::Audio.sfSoundStream_getPan(@handle)
+
+    def pan=(value)
+      C::Audio.sfSoundStream_setPan(@handle, value.to_f)
+    end
+
+    def max_distance = C::Audio.sfSoundStream_getMaxDistance(@handle)
+
+    def max_distance=(value)
+      C::Audio.sfSoundStream_setMaxDistance(@handle, value.to_f)
+    end
+
+    def min_gain = C::Audio.sfSoundStream_getMinGain(@handle)
+
+    def min_gain=(value)
+      C::Audio.sfSoundStream_setMinGain(@handle, value.to_f)
+    end
+
+    def max_gain = C::Audio.sfSoundStream_getMaxGain(@handle)
+
+    def max_gain=(value)
+      C::Audio.sfSoundStream_setMaxGain(@handle, value.to_f)
+    end
+
+    def spatialization_enabled? = C::Audio.sfSoundStream_isSpatializationEnabled(@handle)
+
+    def spatialization_enabled=(value)
+      C::Audio.sfSoundStream_setSpatializationEnabled(@handle, !!value)
+    end
+
+    def direction
+      v = C::Audio.sfSoundStream_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.sfSoundStream_setDirection(@handle, packed)
+    end
+
+    def cone
+      SoundCone.from_native(C::Audio.sfSoundStream_getCone(@handle))
+    end
+
+    def cone=(value)
+      cone =
+        case value
+        when SoundCone then value
+        when Hash      then SoundCone.new(**value)
+        else
+          raise ArgumentError, "SoundStream#cone= expects SoundCone or Hash; got #{value.class}"
+        end
+      C::Audio.sfSoundStream_setCone(@handle, cone.to_native)
+    end
+
+    def velocity
+      v = C::Audio.sfSoundStream_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.sfSoundStream_setVelocity(@handle, packed)
+    end
+
+    def doppler_factor = C::Audio.sfSoundStream_getDopplerFactor(@handle)
+
+    def doppler_factor=(value)
+      C::Audio.sfSoundStream_setDopplerFactor(@handle, value.to_f)
+    end
+
+    def directional_attenuation_factor
+      C::Audio.sfSoundStream_getDirectionalAttenuationFactor(@handle)
+    end
+
+    def directional_attenuation_factor=(value)
+      C::Audio.sfSoundStream_setDirectionalAttenuationFactor(@handle, value.to_f)
+    end
+
+    # Install a real-time DSP filter (same contract as Sound /
+    # Music — see Sound#effect_processor=). Pass `nil` to remove.
+    def effect_processor=(callable)
+      @effect_cb = callable.nil? ? nil : Audio._build_effect_processor(callable)
+      C::Audio.sfSoundStream_setEffectProcessor(@handle, @effect_cb, nil)
+    end
+
+    # The channel layout the stream is producing, as an Array of
+    # `sfSoundChannel` enum values (1 = Mono, 2 = FrontLeft,
+    # 3 = FrontRight, etc — see SoundBuffer::DEFAULT_CHANNEL_MAPS).
+    def channel_map
+      count_buf = FFI::MemoryPointer.new(:size_t)
+      ptr = C::Audio.sfSoundStream_getChannelMap(@handle, count_buf)
+      n = count_buf.read(:size_t)
+      return [] if ptr.null? || n.zero?
+      ptr.read_array_of_int32(n)
+    end
+
     attr_reader :handle # :nodoc:
 
     private

data/lib/sfml/c/audio.rb

@@ -28,6 +28,7 @@ module SFML
       attach_function :sfSoundBuffer_getChannelCount,[:sound_buffer_t], :uint32
       attach_function :sfSoundBuffer_copy,           [:sound_buffer_t], :sound_buffer_t
       attach_function :sfSoundBuffer_createFromMemory, [:pointer, :size_t], :sound_buffer_t
+      attach_function :sfSoundBuffer_createFromStream, [:pointer], :sound_buffer_t
       attach_function :sfSoundBuffer_createFromSamples,
                       [:pointer, :uint64, :uint32, :uint32, :pointer, :size_t], :sound_buffer_t
       attach_function :sfSoundBuffer_getSampleCount, [:sound_buffer_t], :uint64
@@ -94,6 +95,7 @@ module SFML
 
       attach_function :sfMusic_createFromFile, [:string], :music_t
       attach_function :sfMusic_createFromMemory, [:pointer, :size_t], :music_t
+      attach_function :sfMusic_createFromStream, [:pointer], :music_t
       attach_function :sfMusic_destroy,        [:music_t], :void
       attach_function :sfMusic_getChannelCount, [:music_t], :uint32
       attach_function :sfMusic_getSampleRate,   [:music_t], :uint32
@@ -187,6 +189,30 @@ module SFML
       attach_function :sfSoundStream_setRelativeToListener, [:sound_stream_t, :bool], :void
       attach_function :sfSoundStream_isRelativeToListener,  [:sound_stream_t], :bool
 
+      # 3D-audio surface — symmetric with sfSound / sfMusic.
+      attach_function :sfSoundStream_setPan,                          [:sound_stream_t, :float], :void
+      attach_function :sfSoundStream_getPan,                          [:sound_stream_t], :float
+      attach_function :sfSoundStream_setMaxDistance,                  [:sound_stream_t, :float], :void
+      attach_function :sfSoundStream_getMaxDistance,                  [:sound_stream_t], :float
+      attach_function :sfSoundStream_setMinGain,                      [:sound_stream_t, :float], :void
+      attach_function :sfSoundStream_getMinGain,                      [:sound_stream_t], :float
+      attach_function :sfSoundStream_setMaxGain,                      [:sound_stream_t, :float], :void
+      attach_function :sfSoundStream_getMaxGain,                      [:sound_stream_t], :float
+      attach_function :sfSoundStream_setSpatializationEnabled,        [:sound_stream_t, :bool], :void
+      attach_function :sfSoundStream_isSpatializationEnabled,         [:sound_stream_t], :bool
+      attach_function :sfSoundStream_setDirection,                    [:sound_stream_t, System::Vector3f.by_value], :void
+      attach_function :sfSoundStream_getDirection,                    [:sound_stream_t], System::Vector3f.by_value
+      attach_function :sfSoundStream_setCone,                         [:sound_stream_t, SoundSourceCone.by_value], :void
+      attach_function :sfSoundStream_getCone,                         [:sound_stream_t], SoundSourceCone.by_value
+      attach_function :sfSoundStream_setVelocity,                     [:sound_stream_t, System::Vector3f.by_value], :void
+      attach_function :sfSoundStream_getVelocity,                     [:sound_stream_t], System::Vector3f.by_value
+      attach_function :sfSoundStream_setDopplerFactor,                [:sound_stream_t, :float], :void
+      attach_function :sfSoundStream_getDopplerFactor,                [:sound_stream_t], :float
+      attach_function :sfSoundStream_setDirectionalAttenuationFactor, [:sound_stream_t, :float], :void
+      attach_function :sfSoundStream_getDirectionalAttenuationFactor, [:sound_stream_t], :float
+      attach_function :sfSoundStream_setEffectProcessor,              [:sound_stream_t, :sf_effect_processor, :pointer], :void
+      attach_function :sfSoundStream_getChannelMap,                   [:sound_stream_t, :pointer], :pointer
+
       # ---- SoundBufferRecorder ----
       # The simple "record into a SoundBuffer" path. Raw sfSoundRecorder
       # (callback-based) and sfSoundStream (custom audio source via
@@ -210,6 +236,27 @@ module SFML
       attach_function :sfSoundRecorder_getDefaultDevice,       [], :string
       attach_function :sfSoundRecorder_getAvailableDevices,    [:pointer], :pointer
 
+      # Callback-based recorder. The three callbacks run on CSFML's
+      # audio thread; the Ruby SoundRecorder must hold strong refs to
+      # the FFI::Function objects for the lifetime of the recorder.
+      typedef :pointer, :sound_recorder_t
+      callback :sound_recorder_start,   [:pointer], :bool
+      callback :sound_recorder_process, [:pointer, :size_t, :pointer], :bool
+      callback :sound_recorder_stop,    [:pointer], :void
+
+      attach_function :sfSoundRecorder_create,
+                      [:sound_recorder_start, :sound_recorder_process, :sound_recorder_stop, :pointer],
+                      :sound_recorder_t
+      attach_function :sfSoundRecorder_destroy,         [:sound_recorder_t], :void
+      attach_function :sfSoundRecorder_start,           [:sound_recorder_t, :uint32], :bool
+      attach_function :sfSoundRecorder_stop,            [:sound_recorder_t], :void
+      attach_function :sfSoundRecorder_getSampleRate,   [:sound_recorder_t], :uint32
+      attach_function :sfSoundRecorder_setDevice,       [:sound_recorder_t, :string], :bool
+      attach_function :sfSoundRecorder_getDevice,       [:sound_recorder_t], :string
+      attach_function :sfSoundRecorder_setChannelCount, [:sound_recorder_t, :uint32], :void
+      attach_function :sfSoundRecorder_getChannelCount, [:sound_recorder_t], :uint32
+      attach_function :sfSoundRecorder_getChannelMap,   [:sound_recorder_t, :pointer], :pointer
+
       # ---- Listener (the "ear" — global, no handle) ----
       attach_function :sfListener_setGlobalVolume, [:float], :void
       attach_function :sfListener_getGlobalVolume, [], :float