ruby-sfml 3.0.0.4 → 3.0.0.5

data/lib/sfml/graphics/shape.rb

@@ -0,0 +1,114 @@
+module SFML
+  # Abstract callback-driven shape — for when neither CircleShape,
+  # RectangleShape, nor ConvexShape fits. Subclass and override
+  # `#point_count` (returns Integer) and `#point(i)` (returns a
+  # Vector2 or `[x, y]`). CSFML asks Ruby every frame for the point
+  # list, so you can drive geometry from live data.
+  #
+  #   class Pentagon < SFML::Shape
+  #     def point_count = 5
+  #     def point(i)
+  #       angle = i * 2 * Math::PI / 5 - Math::PI / 2
+  #       [Math.cos(angle) * 50, Math.sin(angle) * 50]
+  #     end
+  #   end
+  #
+  #   pent = Pentagon.new(fill_color: SFML::Color.red, position: [400, 300])
+  #   window.draw(pent)
+  #
+  # When your underlying geometry changes (e.g. the data feeding
+  # `#point` updates), call `#update` to invalidate the cached
+  # outline / bounds — otherwise the next draw will still use the
+  # previously sampled points.
+  #
+  # CAVEATS
+  # * Callbacks run on whichever thread invokes the draw. With
+  #   single-threaded rendering (the SFML default) this is fine; if
+  #   you're driving the renderer from a different thread, make sure
+  #   `#point_count` / `#point` are thread-safe.
+  # * Keep a Ruby reference to the Shape — if it's GC'd while CSFML
+  #   still holds the function pointers, the next draw crashes.
+  class Shape
+    include Graphics::Transformable
+    include Graphics::ShapeInspectable
+    CSFML_PREFIX = :sfShape
+
+    def initialize(**opts)
+      # Hold strong refs so the GC doesn't disappear our FFI callbacks.
+      @get_point_count_cb = FFI::Function.new(:size_t, [:pointer]) do |_user|
+        Integer(point_count)
+      end
+      @get_point_cb = FFI::Function.new(C::System::Vector2f.by_value, [:size_t, :pointer]) do |i, _user|
+        p = point(i)
+        pt = p.is_a?(Vector2) ? p : Vector2.new(*p)
+        v  = C::System::Vector2f.new
+        v[:x] = pt.x.to_f; v[:y] = pt.y.to_f
+        v
+      end
+
+      ptr = C::Graphics.sfShape_create(@get_point_count_cb, @get_point_cb, nil)
+      raise Error, "sfShape_create returned NULL" if ptr.null?
+      @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfShape_destroy))
+
+      self.fill_color         = opts[:fill_color]         if opts.key?(:fill_color)
+      self.outline_color      = opts[:outline_color]      if opts.key?(:outline_color)
+      self.outline_thickness  = opts[:outline_thickness]  if opts.key?(:outline_thickness)
+      self.texture            = opts[:texture]            if opts.key?(:texture)
+      self.texture_rect       = opts[:texture_rect]       if opts.key?(:texture_rect)
+      self.position           = opts[:position]           if opts.key?(:position)
+      self.origin             = opts[:origin]             if opts.key?(:origin)
+      self.rotation           = opts[:rotation]           if opts.key?(:rotation)
+      self.scale              = opts[:scale]              if opts.key?(:scale)
+    end
+
+    # ---- Subclass hooks ----
+
+    def point_count
+      raise NoMethodError, "#{self.class} must override #point_count"
+    end
+
+    def point(_index)
+      raise NoMethodError, "#{self.class} must override #point(index)"
+    end
+
+    # ---- Public API ----
+
+    def fill_color = Color.from_native(C::Graphics.sfShape_getFillColor(@handle))
+
+    def fill_color=(c)
+      C::Graphics.sfShape_setFillColor(@handle, c.to_native)
+    end
+
+    def outline_color = Color.from_native(C::Graphics.sfShape_getOutlineColor(@handle))
+
+    def outline_color=(c)
+      C::Graphics.sfShape_setOutlineColor(@handle, c.to_native)
+    end
+
+    def outline_thickness = C::Graphics.sfShape_getOutlineThickness(@handle)
+
+    def outline_thickness=(t)
+      C::Graphics.sfShape_setOutlineThickness(@handle, t.to_f)
+    end
+
+    # Recompute the outline + bounds from the current `#point_count` /
+    # `#point(i)`. Call after the data driving your callbacks changes.
+    # No-op on construction (CSFML samples the points once at the
+    # first draw).
+    def update
+      C::Graphics.sfShape_update(@handle)
+      self
+    end
+
+    def draw_on(target, states_ptr = nil) # :nodoc:
+      target._draw_native(:Shape, @handle, states_ptr)
+    end
+
+    # Abstract Shape doesn't implement #dup — every subclass has its
+    # own state and copy semantics. (CSFML has no `sfShape_copy`.)
+    undef_method :dup
+    undef_method :clone
+
+    attr_reader :handle # :nodoc:
+  end
+end

data/lib/sfml/graphics/shape_inspectable.rb

@@ -0,0 +1,92 @@
+module SFML
+  module Graphics
+    # Methods shared across CircleShape / RectangleShape / ConvexShape:
+    # texture binding, geometry introspection, transform readout, dup.
+    # Including class must define CSFML_PREFIX (Symbol) and hold the FFI
+    # handle in @handle (same contract as Graphics::Transformable).
+    #
+    # Texture binding follows the Sprite pattern: keep a Ruby reference
+    # to the bound texture in @texture so the GC doesn't collect the GPU
+    # resource while the shape still draws with it.
+    module ShapeInspectable
+      def texture
+        ptr = _csfml(:getTexture, @handle)
+        return nil if ptr.null?
+        Texture.send(:_borrow, ptr)
+      end
+
+      # `reset_rect: true` snaps the texture-rect to the full texture size,
+      # which is usually what you want when binding a fresh texture.
+      def set_texture(tex, reset_rect: false)
+        raise ArgumentError, "expected SFML::Texture or nil" unless tex.nil? || tex.is_a?(Texture)
+        _csfml(:setTexture, @handle, tex ? tex.handle : nil, reset_rect)
+        @texture = tex
+        self
+      end
+
+      def texture=(tex)
+        set_texture(tex, reset_rect: false)
+      end
+
+      def texture_rect
+        Rect.from_native(_csfml(:getTextureRect, @handle))
+      end
+
+      def texture_rect=(rect)
+        raise ArgumentError, "texture_rect= requires a SFML::Rect" unless rect.is_a?(Rect)
+        native = C::Graphics::IntRect.new
+        native[:position][:x] = Integer(rect.x)
+        native[:position][:y] = Integer(rect.y)
+        native[:size][:x]     = Integer(rect.width)
+        native[:size][:y]     = Integer(rect.height)
+        _csfml(:setTextureRect, @handle, native)
+      end
+
+      # Single polygon vertex by index. The full list is exposed by the
+      # subclass-specific `#points` method on ConvexShape; CircleShape
+      # synthesises N points from its radius+point_count.
+      def point(index)
+        Vector2.from_native(_csfml(:getPoint, @handle, Integer(index)))
+      end
+
+      # Centroid of the polygon's vertex list (CSFML 3.0+).
+      def geometric_center
+        Vector2.from_native(_csfml(:getGeometricCenter, @handle))
+      end
+
+      # AABB before transform — the rectangle the geometry would occupy
+      # if the shape were drawn at the origin with no rotation/scale.
+      def local_bounds
+        Rect.from_native(_csfml(:getLocalBounds, @handle))
+      end
+
+      # AABB after the shape's full transform — the world-space rect the
+      # renderer uses for culling and hit-tests.
+      def global_bounds
+        Rect.from_native(_csfml(:getGlobalBounds, @handle))
+      end
+
+      def transform
+        _csfml(:getTransform, @handle)
+      end
+
+      def inverse_transform
+        _csfml(:getInverseTransform, @handle)
+      end
+
+      # Deep copy. Texture binding is shared (textures are GPU objects,
+      # cheap to alias); transform/colour state is independent.
+      def dup
+        ptr = _csfml(:copy, @handle)
+        raise Error, "#{self.class.name}#dup returned NULL" if ptr.null?
+
+        destroy_fn = C::Graphics.method(:"#{self.class::CSFML_PREFIX}_destroy")
+        copy = self.class.allocate
+        copy.instance_variable_set(:@handle, FFI::AutoPointer.new(ptr, destroy_fn))
+        copy.instance_variable_set(:@texture, @texture) if defined?(@texture)
+        copy
+      end
+      alias clone dup
+    end
+  end
+end

data/lib/sfml/graphics/texture.rb

@@ -5,8 +5,17 @@ module SFML
   #   tex = SFML::Texture.load("assets/hero.png")
   #   tex = SFML::Texture.load("assets/tile.png", smooth: true, repeated: true)
   class Texture
-    def self.load(path, smooth: false, repeated: false)
-      ptr = C::Graphics.sfTexture_createFromFile(path.to_s, nil)
+    # Load a texture from a file on disk.
+    #
+    # Pass `srgb: true` if the source pixels are in sRGB-encoded
+    # gamma space (most photo/PNG art assets) and you want the GPU
+    # to gamma-decode on sample so blending happens in linear space.
+    # Pair with `RenderWindow#new(..., srgb_capable: true)` and your
+    # final framebuffer will gamma-encode on present.
+    def self.load(path, smooth: false, repeated: false, srgb: false)
+      ptr = srgb \
+        ? C::Graphics.sfTexture_createSrgbFromFile(path.to_s, nil) \
+        : C::Graphics.sfTexture_createFromFile(path.to_s, nil)
       raise Error, "Could not load texture from #{path.inspect}" if ptr.null?
 
       tex = allocate
@@ -20,10 +29,10 @@ module SFML
     # `update(image)` afterwards to upload pixels. Useful when
     # you'll be filling the texture from a procedurally-generated
     # Image or repeatedly streaming pixel data into it.
-    def self.create(width, height)
+    def self.create(width, height, srgb: false)
       size = C::System::Vector2u.new
       size[:x] = Integer(width); size[:y] = Integer(height)
-      ptr = C::Graphics.sfTexture_create(size)
+      ptr = srgb ? C::Graphics.sfTexture_createSrgb(size) : C::Graphics.sfTexture_create(size)
       raise Error, "sfTexture_create returned NULL — out of GPU memory?" if ptr.null?
 
       tex = allocate
@@ -34,12 +43,14 @@ module SFML
     # Decode + upload a Ruby String of bytes (PNG, JPG, BMP, …) as
     # a texture. Useful for embedded assets / network responses
     # that bypass the disk.
-    def self.from_memory(bytes, smooth: false, repeated: false)
+    def self.from_memory(bytes, smooth: false, repeated: false, srgb: false)
       raise ArgumentError, "expected a String, got #{bytes.class}" unless bytes.is_a?(String)
 
       buf = FFI::MemoryPointer.new(:uint8, bytes.bytesize)
       buf.write_bytes(bytes)
-      ptr = C::Graphics.sfTexture_createFromMemory(buf, bytes.bytesize, nil)
+      ptr = srgb \
+        ? C::Graphics.sfTexture_createSrgbFromMemory(buf, bytes.bytesize, nil) \
+        : C::Graphics.sfTexture_createFromMemory(buf, bytes.bytesize, nil)
       raise Error, "sfTexture_createFromMemory returned NULL — unsupported format?" if ptr.null?
 
       tex = allocate
@@ -49,12 +60,32 @@ module SFML
       tex
     end
 
+    # Load a texture from any Ruby IO-like object (File, StringIO,
+    # or anything answering read/seek/pos/size). Useful for assets
+    # inside a zip archive, served over a socket, or generated on
+    # the fly.
+    def self.from_stream(io, smooth: false, repeated: false, srgb: false)
+      stream = SFML::InputStream.new(io)
+      ptr = srgb \
+        ? C::Graphics.sfTexture_createSrgbFromStream(stream.to_ptr, nil) \
+        : C::Graphics.sfTexture_createFromStream(stream.to_ptr, nil)
+      raise Error, "sfTexture_createFromStream returned NULL — unsupported format?" if ptr.null?
+
+      tex = allocate
+      tex.send(:_take_ownership, ptr)
+      tex.smooth   = smooth
+      tex.repeated = repeated
+      tex
+    end
+
     # Upload a CPU-side SFML::Image to the GPU as a new Texture. Keeps
     # the RGBA byte order and dimensions of the source image.
-    def self.from_image(image, smooth: false, repeated: false)
+    def self.from_image(image, smooth: false, repeated: false, srgb: false)
       raise ArgumentError, "Texture.from_image needs a SFML::Image" unless image.is_a?(Image)
 
-      ptr = C::Graphics.sfTexture_createFromImage(image.handle, nil)
+      ptr = srgb \
+        ? C::Graphics.sfTexture_createSrgbFromImage(image.handle, nil) \
+        : C::Graphics.sfTexture_createFromImage(image.handle, nil)
       raise Error, "sfTexture_createFromImage returned NULL" if ptr.null?
 
       tex = allocate
@@ -144,10 +175,15 @@ module SFML
     # Reallocate this texture's GPU memory at a new size. Returns
     # `false` if the GPU rejects the size (driver limit / OOM);
     # the texture's contents become undefined on success.
-    def resize(width, height)
+    # Pass `srgb: true` to re-allocate as an sRGB-encoded texture.
+    def resize(width, height, srgb: false)
       size = C::System::Vector2u.new
       size[:x] = Integer(width); size[:y] = Integer(height)
-      C::Graphics.sfTexture_resize(@handle, size)
+      if srgb
+        C::Graphics.sfTexture_resizeSrgb(@handle, size)
+      else
+        C::Graphics.sfTexture_resize(@handle, size)
+      end
     end
 
     # Atomically swap the GPU memory between two textures —

data/lib/sfml/graphics/transformable_object.rb

@@ -0,0 +1,48 @@
+module SFML
+  # Standalone transformable — a pure CSFML transform container (no
+  # geometry attached). Useful as a base for custom drawables that
+  # combine a transform with their own rendering: parent the child's
+  # vertices to this object's `#transform` and you get position /
+  # rotation / scale / origin for free.
+  #
+  # Most users want the `Graphics::Transformable` mixin instead — this
+  # standalone class exists for symmetry with the C++ API.
+  #
+  #   t = SFML::TransformableObject.new(position: [400, 300], rotation: 45)
+  #   t.transform   #=> SFML::C::Graphics::Transform (use via RenderStates)
+  class TransformableObject
+    include Graphics::Transformable
+    CSFML_PREFIX = :sfTransformable
+
+    def initialize(**opts)
+      ptr = C::Graphics.sfTransformable_create
+      raise Error, "sfTransformable_create returned NULL" if ptr.null?
+      @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfTransformable_destroy))
+
+      self.position = opts[:position] if opts.key?(:position)
+      self.origin   = opts[:origin]   if opts.key?(:origin)
+      self.rotation = opts[:rotation] if opts.key?(:rotation)
+      self.scale    = opts[:scale]    if opts.key?(:scale)
+    end
+
+    def transform
+      C::Graphics.sfTransformable_getTransform(@handle)
+    end
+
+    def inverse_transform
+      C::Graphics.sfTransformable_getInverseTransform(@handle)
+    end
+
+    def dup
+      ptr = C::Graphics.sfTransformable_copy(@handle)
+      raise Error, "sfTransformable_copy returned NULL" if ptr.null?
+      copy = self.class.allocate
+      copy.instance_variable_set(:@handle,
+        FFI::AutoPointer.new(ptr, C::Graphics.method(:sfTransformable_destroy)))
+      copy
+    end
+    alias clone dup
+
+    attr_reader :handle # :nodoc:
+  end
+end

data/lib/sfml/graphics/vertex_array.rb

@@ -109,6 +109,18 @@ module SFML
       target._draw_native(:VertexArray, @handle, states_ptr)
     end
 
+    # Independent copy — vertices duplicated, future appends to one
+    # don't affect the other.
+    def dup
+      ptr = C::Graphics.sfVertexArray_copy(@handle)
+      raise Error, "sfVertexArray_copy returned NULL" if ptr.null?
+      copy = self.class.allocate
+      copy.instance_variable_set(:@handle,
+        FFI::AutoPointer.new(ptr, C::Graphics.method(:sfVertexArray_destroy)))
+      copy
+    end
+    alias clone dup
+
     attr_reader :handle # :nodoc:
   end
 end

data/lib/sfml/graphics/vertex_buffer.rb

@@ -108,6 +108,18 @@ module SFML
 
     def native_handle = C::Graphics.sfVertexBuffer_getNativeHandle(@handle)
 
+    # Bind this VBO as the active vertex buffer for the GL pipeline.
+    # Useful when mixing raw GL with SFML rendering — pair with
+    # `SFML::VertexBuffer.unbind` (or any other draw) to release.
+    def bind
+      C::Graphics.sfVertexBuffer_bind(@handle)
+      self
+    end
+
+    def self.unbind
+      C::Graphics.sfVertexBuffer_bind(nil)
+    end
+
     def draw_on(target, states_ptr = nil) # :nodoc:
       target._draw_native(:VertexBuffer, @handle, states_ptr)
     end

data/lib/sfml/network/packet.rb

@@ -0,0 +1,123 @@
+module SFML
+  module Network
+    # Binary serializer with explicit, typed read/write — wire-compatible
+    # with SFML's `sf::Packet`. Used by Tcp/UdpSocket's `send_packet`
+    # /`receive_packet` (the network layer prepends a 4-byte length header
+    # for TCP framing, so the receiver always gets a whole packet).
+    #
+    # All read calls consume bytes in FIFO order. After a write you can
+    # always re-read by sending the packet over the wire; the local
+    # read position only advances on the receive side. To rewind a
+    # locally-built packet, just construct a new one.
+    #
+    #   pkt = SFML::Network::Packet.new
+    #   pkt.write_int32(42)
+    #   pkt.write_string("hello")
+    #   pkt.write_float(0.5)
+    #
+    #   # … send over a TcpSocket, receive on the other end …
+    #
+    #   incoming.read_int32     #=> 42
+    #   incoming.read_string    #=> "hello"
+    #   incoming.read_float     #=> 0.5
+    class Packet
+      def initialize
+        ptr = C::Network.sfPacket_create
+        raise Error, "sfPacket_create returned NULL" if ptr.null?
+        @handle = FFI::AutoPointer.new(ptr, C::Network.method(:sfPacket_destroy))
+      end
+
+      def clear
+        C::Network.sfPacket_clear(@handle)
+        self
+      end
+
+      # Append a raw byte buffer (no length prefix, no type tag) — for
+      # interop with hand-crafted binary protocols. Most callers want
+      # `write_string` / `write_int32` etc. instead.
+      def append(bytes)
+        s = bytes.to_s
+        buf = FFI::MemoryPointer.new(:uint8, s.bytesize)
+        buf.write_bytes(s)
+        C::Network.sfPacket_append(@handle, buf, s.bytesize)
+        self
+      end
+
+      # Returns the full packet as a binary String. Includes any length
+      # prefixes / type encoding sfPacket added on write.
+      def data
+        size = C::Network.sfPacket_getDataSize(@handle)
+        return "".b if size.zero?
+        ptr = C::Network.sfPacket_getData(@handle)
+        ptr.read_bytes(size).force_encoding(Encoding::ASCII_8BIT)
+      end
+
+      def size            = C::Network.sfPacket_getDataSize(@handle)
+      def read_position   = C::Network.sfPacket_getReadPosition(@handle)
+      def end_of_packet?  = C::Network.sfPacket_endOfPacket(@handle)
+
+      # `false` if the last read overran the packet — sfPacket "fails"
+      # quietly rather than raising, and subsequent reads return zero.
+      # Check this after a read sequence to validate the frame.
+      def ok? = C::Network.sfPacket_canRead(@handle)
+
+      # ---- typed writers ----
+      def write_bool(v)
+        C::Network.sfPacket_writeBool(@handle, v ? true : false); self
+      end
+      def write_int8(v)   = (C::Network.sfPacket_writeInt8(@handle,   Integer(v)); self)
+      def write_uint8(v)  = (C::Network.sfPacket_writeUint8(@handle,  Integer(v)); self)
+      def write_int16(v)  = (C::Network.sfPacket_writeInt16(@handle,  Integer(v)); self)
+      def write_uint16(v) = (C::Network.sfPacket_writeUint16(@handle, Integer(v)); self)
+      def write_int32(v)  = (C::Network.sfPacket_writeInt32(@handle,  Integer(v)); self)
+      def write_uint32(v) = (C::Network.sfPacket_writeUint32(@handle, Integer(v)); self)
+      def write_int64(v)  = (C::Network.sfPacket_writeInt64(@handle,  Integer(v)); self)
+      def write_uint64(v) = (C::Network.sfPacket_writeUint64(@handle, Integer(v)); self)
+      def write_float(v)  = (C::Network.sfPacket_writeFloat(@handle,  Float(v));   self)
+      def write_double(v) = (C::Network.sfPacket_writeDouble(@handle, Float(v));   self)
+
+      def write_string(str)
+        C::Network.sfPacket_writeString(@handle, str.to_s)
+        self
+      end
+
+      # ---- typed readers ----
+      def read_bool   = C::Network.sfPacket_readBool(@handle)
+      def read_int8   = C::Network.sfPacket_readInt8(@handle)
+      def read_uint8  = C::Network.sfPacket_readUint8(@handle)
+      def read_int16  = C::Network.sfPacket_readInt16(@handle)
+      def read_uint16 = C::Network.sfPacket_readUint16(@handle)
+      def read_int32  = C::Network.sfPacket_readInt32(@handle)
+      def read_uint32 = C::Network.sfPacket_readUint32(@handle)
+      def read_int64  = C::Network.sfPacket_readInt64(@handle)
+      def read_uint64 = C::Network.sfPacket_readUint64(@handle)
+      def read_float  = C::Network.sfPacket_readFloat(@handle)
+      def read_double = C::Network.sfPacket_readDouble(@handle)
+
+      # Read a length-prefixed string. CSFML expects a caller-allocated
+      # C buffer of "string length + 1 NUL" bytes — we size it from the
+      # remaining packet bytes, which is always an upper bound.
+      def read_string
+        remaining = size - read_position
+        return "" if remaining <= 0
+
+        buf = FFI::MemoryPointer.new(:char, remaining + 1)
+        C::Network.sfPacket_readString(@handle, buf)
+        buf.read_string.force_encoding(Encoding::UTF_8)
+      end
+
+      def dup
+        ptr = C::Network.sfPacket_copy(@handle)
+        raise Error, "sfPacket_copy returned NULL" if ptr.null?
+
+        copy = self.class.allocate
+        copy.instance_variable_set(:@handle,
+          FFI::AutoPointer.new(ptr, C::Network.method(:sfPacket_destroy)))
+        copy
+      end
+      alias clone dup
+
+      attr_reader :handle # :nodoc:
+    end
+  end
+end

data/lib/sfml/network/tcp_socket.rb

@@ -55,6 +55,25 @@ module SFML
         [status, buf.read_bytes(n)]
       end
 
+      # Send a structured SFML::Network::Packet. CSFML frames the wire
+      # bytes with a length prefix so the peer's receive_packet always
+      # gets a whole packet (no need to handle TCP boundary fragments
+      # at the Ruby layer).
+      def send_packet(packet)
+        raise ArgumentError, "expected SFML::Network::Packet" unless packet.is_a?(Packet)
+        code = C::Network.sfTcpSocket_sendPacket(@handle, packet.handle)
+        C::Network::STATUSES[code]
+      end
+
+      # Receive into a fresh Packet. Returns [status, packet]; the
+      # packet is nil for non-:done statuses.
+      def receive_packet
+        pkt  = Packet.new
+        code = C::Network.sfTcpSocket_receivePacket(@handle, pkt.handle)
+        status = C::Network::STATUSES[code]
+        [status, status == :done ? pkt : nil]
+      end
+
       def blocking? = C::Network.sfTcpSocket_isBlocking(@handle)
 
       def blocking=(value)

data/lib/sfml/network/udp_socket.rb

@@ -57,6 +57,29 @@ module SFML
         [status, buf.read_bytes(n), sip, sport]
       end
 
+      # Send a structured SFML::Network::Packet to (to, port).
+      def send_packet(packet, to:, port:)
+        raise ArgumentError, "expected SFML::Network::Packet" unless packet.is_a?(Packet)
+        addr = to.is_a?(IpAddress) ? to : IpAddress.from_string(to)
+        code = C::Network.sfUdpSocket_sendPacket(@handle, packet.handle, addr.struct, Integer(port))
+        C::Network::STATUSES[code]
+      end
+
+      # Returns [status, packet, sender_ip, sender_port]. Packet is nil
+      # for non-:done statuses.
+      def receive_packet
+        pkt         = Packet.new
+        sender_addr = C::Network::IpAddress.new
+        sender_port = FFI::MemoryPointer.new(:uint16)
+
+        code = C::Network.sfUdpSocket_receivePacket(
+          @handle, pkt.handle, sender_addr.pointer, sender_port,
+        )
+        status = C::Network::STATUSES[code]
+        return [status, nil, nil, nil] unless status == :done
+        [status, pkt, IpAddress.wrap(sender_addr), sender_port.read(:uint16)]
+      end
+
       def blocking? = C::Network.sfUdpSocket_isBlocking(@handle)
 
       def blocking=(value)

data/lib/sfml/system/input_stream.rb

@@ -0,0 +1,88 @@
+module SFML
+  # Bridge between a Ruby IO-like object (anything with `#read(n)`,
+  # `#seek(pos)`, `#pos` / `#tell`, and `#size`) and CSFML's
+  # `sfInputStream*` parameter on `*_createFromStream` loader
+  # functions.
+  #
+  # Typical use is indirect — pass a Ruby IO to the
+  # `.from_stream` factory on Font, Image, Texture, Shader, Music,
+  # or SoundBuffer:
+  #
+  #   File.open("assets/hero.png", "rb") do |io|
+  #     tex = SFML::Texture.from_stream(io)
+  #   end
+  #
+  # Direct use is for advanced cases (custom virtual filesystems,
+  # network streams, etc.). Subclass or build with `.new(io)`:
+  #
+  #   wrapped = SFML::InputStream.new(my_random_access_io)
+  #   font    = SFML::Font.send(:_load_from_stream_handle, wrapped.struct)
+  #
+  # The InputStream object must outlive the loader call — keep a
+  # reference until the CSFML factory returns. The wrapped IO is
+  # not closed automatically; close it yourself.
+  class InputStream
+    # `io` must respond to: read(n), seek(pos, IO::SEEK_SET), pos/tell, size.
+    # Ruby's File, StringIO, and Tempfile all qualify.
+    def initialize(io)
+      @io = io
+
+      # Strong refs so the GC doesn't free our callbacks before CSFML
+      # is done with the struct. CSFML calls them synchronously
+      # during the loader function, but may also call them later
+      # (Music streams from disk on its audio thread).
+      @read_cb = FFI::Function.new(:int64, [:pointer, :size_t, :pointer]) do |buf, size, _user|
+        begin
+          bytes = @io.read(size) || ""
+          buf.write_bytes(bytes) unless bytes.empty?
+          bytes.bytesize
+        rescue StandardError
+          -1
+        end
+      end
+
+      @seek_cb = FFI::Function.new(:int64, [:size_t, :pointer]) do |pos, _user|
+        begin
+          @io.seek(pos, IO::SEEK_SET)
+          pos
+        rescue StandardError
+          -1
+        end
+      end
+
+      @tell_cb = FFI::Function.new(:int64, [:pointer]) do |_user|
+        begin
+          @io.respond_to?(:pos) ? @io.pos : @io.tell
+        rescue StandardError
+          -1
+        end
+      end
+
+      @size_cb = FFI::Function.new(:int64, [:pointer]) do |_user|
+        begin
+          @io.size
+        rescue StandardError
+          -1
+        end
+      end
+
+      @struct = C::System::InputStream.new
+      @struct[:read]      = @read_cb
+      @struct[:seek]      = @seek_cb
+      @struct[:tell]      = @tell_cb
+      @struct[:get_size]  = @size_cb
+      @struct[:user_data] = FFI::Pointer::NULL
+    end
+
+    # @!visibility private
+    def struct
+      @struct
+    end
+
+    # Pointer suitable for the `sfInputStream*` parameter on
+    # `*_createFromStream` loaders.
+    def to_ptr
+      @struct.pointer
+    end
+  end
+end

data/lib/sfml/version.rb

@@ -15,5 +15,5 @@ module SFML
   #   "3.0.1.0"  — CSFML 3.0.1 ships, we re-cut from upstream
   #   "3.0.1.1"  — our patch on top of CSFML 3.0.1
   #   "3.1.0.0"  — CSFML 3.1.0 ships, we add new bindings
-  VERSION = "3.0.0.4"
+  VERSION = "3.0.0.5"
 end