ruby-sfml 3.0.0.0

data/lib/sfml/audio/listener.rb

@@ -0,0 +1,55 @@
+module SFML
+  # The "ear" — a global, single-instance object that defines from
+  # where the player hears the world. Sounds positioned via Sound#position=
+  # attenuate based on their distance from this point.
+  #
+  #   SFML::Listener.position = [400, 300, 0]   # follow your camera
+  #   SFML::Listener.global_volume = 80         # 0..100, master gain
+  #
+  # For 2D games keep z = 0 and treat x, y as world coords. For
+  # first-person stuff also set Listener.direction to point along the
+  # camera forward.
+  module Listener
+    module_function
+
+    # Master volume in the range [0, 100]. Affects all sounds, music, etc.
+    def global_volume
+      C::Audio.sfListener_getGlobalVolume
+    end
+
+    def global_volume=(value)
+      C::Audio.sfListener_setGlobalVolume(value.to_f)
+    end
+
+    def position
+      Vector3.from_native(C::Audio.sfListener_getPosition)
+    end
+
+    def position=(value)
+      vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
+      C::Audio.sfListener_setPosition(vec.to_native_f)
+    end
+
+    # The forward direction of the listener (unit-length, doesn't have to be).
+    # Default: (0, 0, -1) — looking into the screen.
+    def direction
+      Vector3.from_native(C::Audio.sfListener_getDirection)
+    end
+
+    def direction=(value)
+      vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
+      C::Audio.sfListener_setDirection(vec.to_native_f)
+    end
+
+    # The "up" direction. Default: (0, 1, 0). Together with `direction`
+    # it determines listener orientation for stereo panning.
+    def up_vector
+      Vector3.from_native(C::Audio.sfListener_getUpVector)
+    end
+
+    def up_vector=(value)
+      vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
+      C::Audio.sfListener_setUpVector(vec.to_native_f)
+    end
+  end
+end

data/lib/sfml/audio/music.rb

@@ -0,0 +1,88 @@
+module SFML
+  # A streamed audio source. Use this for long tracks (background music) so
+  # the file isn't loaded into memory all at once.
+  #
+  #   bgm = SFML::Music.load("assets/track.ogg", looping: true, volume: 60)
+  #   bgm.play
+  class Music
+    def self.load(path, **opts)
+      ptr = C::Audio.sfMusic_createFromFile(path.to_s)
+      raise Error, "Could not load music from #{path.inspect}" if ptr.null?
+
+      m = allocate
+      m.send(:_take_ownership, ptr)
+      m.instance_variable_set(:@looping, false)
+      m.volume  = opts[:volume]  if opts.key?(:volume)
+      m.pitch   = opts[:pitch]   if opts.key?(:pitch)
+      m.looping = opts[:looping] if opts.key?(:looping)
+      m
+    end
+
+    def play   = C::Audio.sfMusic_play(@handle)
+    def pause  = C::Audio.sfMusic_pause(@handle)
+    def stop   = C::Audio.sfMusic_stop(@handle)
+
+    def status   = C::Audio::STATUSES[C::Audio.sfMusic_getStatus(@handle)]
+    def playing? = status == :playing
+    def paused?  = status == :paused
+    def stopped? = status == :stopped
+
+    def duration = Time.from_native(C::Audio.sfMusic_getDuration(@handle))
+
+    # Cached on the Ruby side; see Sound#looping? for the why.
+    def looping?
+      @looping
+    end
+
+    def looping=(value)
+      @looping = value ? true : false
+      C::Audio.sfMusic_setLooping(@handle, @looping)
+    end
+
+    def volume = C::Audio.sfMusic_getVolume(@handle)
+
+    def volume=(value)
+      C::Audio.sfMusic_setVolume(@handle, value.to_f)
+    end
+
+    def pitch = C::Audio.sfMusic_getPitch(@handle)
+
+    def pitch=(value)
+      C::Audio.sfMusic_setPitch(@handle, value.to_f)
+    end
+
+    # 3D positional audio — see SFML::Sound for the why.
+    def position
+      Vector3.from_native(C::Audio.sfMusic_getPosition(@handle))
+    end
+
+    def position=(value)
+      vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
+      C::Audio.sfMusic_setPosition(@handle, vec.to_native_f)
+    end
+
+    def attenuation = C::Audio.sfMusic_getAttenuation(@handle)
+
+    def attenuation=(value)
+      C::Audio.sfMusic_setAttenuation(@handle, value.to_f)
+    end
+
+    def min_distance = C::Audio.sfMusic_getMinDistance(@handle)
+
+    def min_distance=(value)
+      C::Audio.sfMusic_setMinDistance(@handle, value.to_f)
+    end
+
+    def relative_to_listener? = C::Audio.sfMusic_isRelativeToListener(@handle)
+
+    def relative_to_listener=(value)
+      C::Audio.sfMusic_setRelativeToListener(@handle, value ? true : false)
+    end
+
+    private
+
+    def _take_ownership(ptr)
+      @handle = FFI::AutoPointer.new(ptr, C::Audio.method(:sfMusic_destroy))
+    end
+  end
+end

data/lib/sfml/audio/sound.rb

@@ -0,0 +1,102 @@
+module SFML
+  # A short sound that plays from a SoundBuffer held entirely in memory.
+  # Cheap to create, suitable for game SFX (blips, hits, footsteps).
+  #
+  #   buffer = SFML::SoundBuffer.load("blip.wav")
+  #   sound  = SFML::Sound.new(buffer, volume: 80, pitch: 1.2, looping: true)
+  #   sound.play
+  class Sound
+    def initialize(buffer, volume: 100.0, pitch: 1.0, looping: false)
+      raise ArgumentError, "Sound requires a SFML::SoundBuffer" unless buffer.is_a?(SoundBuffer)
+
+      ptr = C::Audio.sfSound_create(buffer.handle)
+      raise Error, "sfSound_create returned NULL" if ptr.null?
+      @handle = FFI::AutoPointer.new(ptr, C::Audio.method(:sfSound_destroy))
+      @buffer  = buffer # keep alive
+      # @looping mirrors the loop flag because SFML 3's isLooping reads
+      # through an OpenAL source that may be unallocated on systems
+      # without an audio device (some CI runners). Caching on the Ruby
+      # side keeps observable behaviour deterministic regardless.
+      @looping = false
+
+      self.volume  = volume
+      self.pitch   = pitch
+      self.looping = looping
+    end
+
+    attr_reader :buffer
+
+    def buffer=(new_buffer)
+      raise ArgumentError, "Sound#buffer= requires a SFML::SoundBuffer" unless new_buffer.is_a?(SoundBuffer)
+      C::Audio.sfSound_setBuffer(@handle, new_buffer.handle)
+      @buffer = new_buffer
+    end
+
+    def play   = C::Audio.sfSound_play(@handle)
+    def pause  = C::Audio.sfSound_pause(@handle)
+    def stop   = C::Audio.sfSound_stop(@handle)
+
+    def status      = C::Audio::STATUSES[C::Audio.sfSound_getStatus(@handle)]
+    def playing?    = status == :playing
+    def paused?     = status == :paused
+    def stopped?    = status == :stopped
+
+    def looping?
+      @looping
+    end
+
+    def looping=(value)
+      @looping = value ? true : false
+      C::Audio.sfSound_setLooping(@handle, @looping)
+    end
+
+    def volume      = C::Audio.sfSound_getVolume(@handle)
+
+    def volume=(value)
+      C::Audio.sfSound_setVolume(@handle, value.to_f)
+    end
+
+    def pitch       = C::Audio.sfSound_getPitch(@handle)
+
+    def pitch=(value)
+      C::Audio.sfSound_setPitch(@handle, value.to_f)
+    end
+
+    # ---- 3D positional audio ----
+    #
+    # Sounds have a 3D position; the SFML::Listener acts as the "ear".
+    # Volume falls off with distance from min_distance outward, scaled
+    # by attenuation (0 = no falloff, 1 = realistic, higher = sharper).
+    # By default a Sound's position is in world coordinates; flip
+    # `relative_to_listener = true` and the position becomes relative
+    # to the listener — useful for "stuck to the camera" UI sounds.
+    #
+    # For 2D games, set z = 0 and listener.position to your camera.
+    def position
+      Vector3.from_native(C::Audio.sfSound_getPosition(@handle))
+    end
+
+    def position=(value)
+      vec = value.is_a?(Vector3) ? value : Vector3.new(*value)
+      C::Audio.sfSound_setPosition(@handle, vec.to_native_f)
+    end
+
+    def attenuation = C::Audio.sfSound_getAttenuation(@handle)
+
+    def attenuation=(value)
+      C::Audio.sfSound_setAttenuation(@handle, value.to_f)
+    end
+
+    def min_distance = C::Audio.sfSound_getMinDistance(@handle)
+
+    def min_distance=(value)
+      C::Audio.sfSound_setMinDistance(@handle, value.to_f)
+    end
+
+    def relative_to_listener? = C::Audio.sfSound_isRelativeToListener(@handle)
+
+    def relative_to_listener=(value)
+      C::Audio.sfSound_setRelativeToListener(@handle, value ? true : false)
+    end
+  end
+end

data/lib/sfml/audio/sound_buffer.rb

@@ -0,0 +1,38 @@
+module SFML
+  # Decoded audio data held in memory. Use it to back one or more Sound
+  # instances. Loaded from .wav, .ogg, .flac, .mp3 (depends on CSFML build).
+  #
+  #   buffer = SFML::SoundBuffer.load("assets/blip.wav")
+  #   sound  = SFML::Sound.new(buffer)
+  #   sound.play
+  class SoundBuffer
+    def self.load(path)
+      ptr = C::Audio.sfSoundBuffer_createFromFile(path.to_s)
+      raise Error, "Could not load sound buffer from #{path.inspect}" if ptr.null?
+      buf = allocate
+      buf.send(:_take_ownership, ptr)
+      buf
+    end
+
+    def duration      = Time.from_native(C::Audio.sfSoundBuffer_getDuration(@handle))
+    def sample_rate   = C::Audio.sfSoundBuffer_getSampleRate(@handle)
+    def channel_count = C::Audio.sfSoundBuffer_getChannelCount(@handle)
+
+    # Write the buffer out to disk. Format is inferred from the file
+    # extension (.wav / .ogg / .flac, depends on what CSFML was built
+    # with).
+    def save(path)
+      ok = C::Audio.sfSoundBuffer_saveToFile(@handle, path.to_s)
+      raise Error, "could not save SoundBuffer to #{path.inspect}" unless ok
+      path
+    end
+
+    attr_reader :handle # :nodoc:
+
+    private
+
+    def _take_ownership(ptr)
+      @handle = FFI::AutoPointer.new(ptr, C::Audio.method(:sfSoundBuffer_destroy))
+    end
+  end
+end

data/lib/sfml/audio/sound_buffer_recorder.rb

@@ -0,0 +1,71 @@
+module SFML
+  # Records audio from the system input (microphone) directly into a
+  # SoundBuffer. Quickest path for a "record audio" feature — start,
+  # speak, stop, save:
+  #
+  #   recorder = SFML::SoundBufferRecorder.new
+  #   recorder.start(sample_rate: 44100)
+  #   sleep 3
+  #   recorder.stop
+  #   recorder.buffer.save("memo.wav")
+  #
+  # Recording requires a working input device; SFML::SoundRecorder.available?
+  # tells you whether one is present before you start.
+  class SoundBufferRecorder
+    def initialize
+      ptr = C::Audio.sfSoundBufferRecorder_create
+      raise Error, "sfSoundBufferRecorder_create returned NULL" if ptr.null?
+      @handle = FFI::AutoPointer.new(ptr, C::Audio.method(:sfSoundBufferRecorder_destroy))
+    end
+
+    # Begin capturing samples at the given sample rate. Returns true on
+    # success, false if the device couldn't be opened.
+    def start(sample_rate: 44_100)
+      C::Audio.sfSoundBufferRecorder_start(@handle, Integer(sample_rate))
+    end
+
+    def stop
+      C::Audio.sfSoundBufferRecorder_stop(@handle)
+      self
+    end
+
+    def sample_rate
+      C::Audio.sfSoundBufferRecorder_getSampleRate(@handle)
+    end
+
+    def channel_count
+      C::Audio.sfSoundBufferRecorder_getChannelCount(@handle)
+    end
+
+    def channel_count=(value)
+      C::Audio.sfSoundBufferRecorder_setChannelCount(@handle, Integer(value))
+    end
+
+    # The captured audio so far. Returned as a borrowed SoundBuffer
+    # owned by the recorder — copy it (via #save or by feeding to a
+    # Sound) before destroying the recorder, or build a Sound that
+    # outlives the recorder via the buffer's data.
+    def buffer
+      ptr = C::Audio.sfSoundBufferRecorder_getBuffer(@handle)
+      raise Error, "sfSoundBufferRecorder_getBuffer returned NULL" if ptr.null?
+      # Borrowed — recorder owns the underlying sf::SoundBuffer.
+      buf = SoundBuffer.allocate
+      buf.instance_variable_set(:@handle, ptr)
+      buf
+    end
+
+    # Currently selected input device name (or nil).
+    def device
+      name = C::Audio.sfSoundBufferRecorder_getDevice(@handle)
+      name unless name.nil? || name.empty?
+    end
+
+    def device=(name)
+      ok = C::Audio.sfSoundBufferRecorder_setDevice(@handle, name.to_s)
+      raise Error, "could not select recording device #{name.inspect}" unless ok
+      name
+    end
+
+    attr_reader :handle # :nodoc:
+  end
+end

data/lib/sfml/audio/sound_recorder.rb

@@ -0,0 +1,30 @@
+module SFML
+  # Static helpers for audio capture. Use SFML::SoundBufferRecorder
+  # to actually record; these tell you what hardware is available.
+  #
+  #   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?
+      C::Audio.sfSoundRecorder_isAvailable
+    end
+
+    def 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
+      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
+  end
+end

data/lib/sfml/c/audio.rb

@@ -0,0 +1,106 @@
+module SFML
+  module C
+    module Audio
+      extend FFI::Library
+
+      ffi_lib LIB_CANDIDATES[:audio]
+
+      typedef :pointer, :sound_buffer_t
+      typedef :pointer, :sound_t
+      typedef :pointer, :music_t
+
+      # sfSoundStatus = { sfStopped, sfPaused, sfPlaying } in that order.
+      STATUSES = %i[stopped paused playing].freeze
+
+      # ---- SoundBuffer ----
+      attach_function :sfSoundBuffer_createFromFile, [:string], :sound_buffer_t
+      attach_function :sfSoundBuffer_destroy,        [:sound_buffer_t], :void
+      attach_function :sfSoundBuffer_saveToFile,     [:sound_buffer_t, :string], :bool
+      attach_function :sfSoundBuffer_getDuration,    [:sound_buffer_t], System::Time.by_value
+      attach_function :sfSoundBuffer_getSampleRate,  [:sound_buffer_t], :uint32
+      attach_function :sfSoundBuffer_getChannelCount,[:sound_buffer_t], :uint32
+
+      # ---- Sound ----
+      attach_function :sfSound_create,        [:sound_buffer_t], :sound_t
+      attach_function :sfSound_destroy,       [:sound_t], :void
+      attach_function :sfSound_play,          [:sound_t], :void
+      attach_function :sfSound_pause,         [:sound_t], :void
+      attach_function :sfSound_stop,          [:sound_t], :void
+      attach_function :sfSound_setBuffer,     [:sound_t, :sound_buffer_t], :void
+      attach_function :sfSound_setLooping,    [:sound_t, :bool], :void
+      attach_function :sfSound_isLooping,     [:sound_t], :bool
+      attach_function :sfSound_getStatus,     [:sound_t], :int
+      attach_function :sfSound_setVolume,     [:sound_t, :float], :void
+      attach_function :sfSound_getVolume,     [:sound_t], :float
+      attach_function :sfSound_setPitch,      [:sound_t, :float], :void
+      attach_function :sfSound_getPitch,      [:sound_t], :float
+
+      # 3D positional audio
+      attach_function :sfSound_setPosition,           [:sound_t, System::Vector3f.by_value], :void
+      attach_function :sfSound_getPosition,           [:sound_t], System::Vector3f.by_value
+      attach_function :sfSound_setMinDistance,        [:sound_t, :float], :void
+      attach_function :sfSound_getMinDistance,        [:sound_t], :float
+      attach_function :sfSound_setAttenuation,        [:sound_t, :float], :void
+      attach_function :sfSound_getAttenuation,        [:sound_t], :float
+      attach_function :sfSound_setRelativeToListener, [:sound_t, :bool], :void
+      attach_function :sfSound_isRelativeToListener,  [:sound_t], :bool
+
+      # ---- Music ----
+      attach_function :sfMusic_createFromFile, [:string], :music_t
+      attach_function :sfMusic_destroy,        [:music_t], :void
+      attach_function :sfMusic_play,           [:music_t], :void
+      attach_function :sfMusic_pause,          [:music_t], :void
+      attach_function :sfMusic_stop,           [:music_t], :void
+      attach_function :sfMusic_setLooping,     [:music_t, :bool], :void
+      attach_function :sfMusic_isLooping,      [:music_t], :bool
+      attach_function :sfMusic_getStatus,      [:music_t], :int
+      attach_function :sfMusic_setVolume,      [:music_t, :float], :void
+      attach_function :sfMusic_getVolume,      [:music_t], :float
+      attach_function :sfMusic_setPitch,       [:music_t, :float], :void
+      attach_function :sfMusic_getPitch,       [:music_t], :float
+      attach_function :sfMusic_getDuration,    [:music_t], System::Time.by_value
+
+      attach_function :sfMusic_setPosition,           [:music_t, System::Vector3f.by_value], :void
+      attach_function :sfMusic_getPosition,           [:music_t], System::Vector3f.by_value
+      attach_function :sfMusic_setMinDistance,        [:music_t, :float], :void
+      attach_function :sfMusic_getMinDistance,        [:music_t], :float
+      attach_function :sfMusic_setAttenuation,        [:music_t, :float], :void
+      attach_function :sfMusic_getAttenuation,        [:music_t], :float
+      attach_function :sfMusic_setRelativeToListener, [:music_t, :bool], :void
+      attach_function :sfMusic_isRelativeToListener,  [:music_t], :bool
+
+      # ---- SoundBufferRecorder ----
+      # The simple "record into a SoundBuffer" path. Raw sfSoundRecorder
+      # (callback-based) and sfSoundStream (custom audio source via
+      # callbacks) need Ruby callbacks running on the SFML audio thread —
+      # not worth the complexity for a niche feature.
+      typedef :pointer, :sound_buffer_recorder_t
+
+      attach_function :sfSoundBufferRecorder_create,           [], :sound_buffer_recorder_t
+      attach_function :sfSoundBufferRecorder_destroy,          [:sound_buffer_recorder_t], :void
+      attach_function :sfSoundBufferRecorder_start,            [:sound_buffer_recorder_t, :uint32], :bool
+      attach_function :sfSoundBufferRecorder_stop,             [:sound_buffer_recorder_t], :void
+      attach_function :sfSoundBufferRecorder_getSampleRate,    [:sound_buffer_recorder_t], :uint32
+      attach_function :sfSoundBufferRecorder_getBuffer,        [:sound_buffer_recorder_t], :sound_buffer_t
+      attach_function :sfSoundBufferRecorder_setDevice,        [:sound_buffer_recorder_t, :string], :bool
+      attach_function :sfSoundBufferRecorder_getDevice,        [:sound_buffer_recorder_t], :string
+      attach_function :sfSoundBufferRecorder_setChannelCount,  [:sound_buffer_recorder_t, :uint32], :void
+      attach_function :sfSoundBufferRecorder_getChannelCount,  [:sound_buffer_recorder_t], :uint32
+
+      # SoundRecorder static helpers — query mic availability and devices.
+      attach_function :sfSoundRecorder_isAvailable,            [], :bool
+      attach_function :sfSoundRecorder_getDefaultDevice,       [], :string
+      attach_function :sfSoundRecorder_getAvailableDevices,    [:pointer], :pointer
+
+      # ---- Listener (the "ear" — global, no handle) ----
+      attach_function :sfListener_setGlobalVolume, [:float], :void
+      attach_function :sfListener_getGlobalVolume, [], :float
+      attach_function :sfListener_setPosition,     [System::Vector3f.by_value], :void
+      attach_function :sfListener_getPosition,     [], System::Vector3f.by_value
+      attach_function :sfListener_setDirection,    [System::Vector3f.by_value], :void
+      attach_function :sfListener_getDirection,    [], System::Vector3f.by_value
+      attach_function :sfListener_setUpVector,     [System::Vector3f.by_value], :void
+      attach_function :sfListener_getUpVector,     [], System::Vector3f.by_value
+    end
+  end
+end