ruby-sfml 3.0.0.2 → 3.0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8136e14f0f8d0f777f7649e15a61e6017e386f7e80e023d5a2b8000191db9213
-  data.tar.gz: f6fed33adc435dcbe67777499d0aae14e58ae670a7a04fc94cb58b23805e8fc8
+  metadata.gz: 3261668821d3742648968ea78730bf09a83c72a428e69fe9fc5f2492f13f8557
+  data.tar.gz: 860208fab91bf28c6825948892bca54478defebdc29c596cb30088e394a7f516
 SHA512:
-  metadata.gz: 62d6d8965915bfe6e95161ae8580a3b2d84eca6334a33387238073de069839dae4f08829f82f42042f43850899ed24329e3d49610ac6ec95092b53685ed49d2e
-  data.tar.gz: a4f6805ba848b00c623ae4f1b0029b97423f154058e472e3208c48873c9f2be229707aed0ac2934483256c03f048fc06bf3f6c9c8001712ab7e764d8aa23bba4
+  metadata.gz: 2cae71d47e55c1d1fa1b39c8c18d7362fff927224ae410449ef33444fe07060ef2cf8c8c3c6b0b65beffd7d2f9c99e6cd89c6d2558a5573817150c636493375b
+  data.tar.gz: 5a4e5a8f78ae23ed08d72bc62df15587787e172000abd53b8fe1b9869952f98348d9c775f37c606555f25e5c5b26f2009685e136a26b788ae4ce9123817090be

data/CHANGELOG.md

@@ -8,6 +8,83 @@ ruby-sfml's own patch level.
 
 ## [Unreleased]
 
+## [3.0.0.3] — 2026-05-09
+
+### Added — typography
+- `Font#family` — human-readable family name from `sfFont_getInfo`.
+- `Font#has_glyph?(codepoint)` — accepts an Integer codepoint or
+  a single-character String.
+- `Font#kerning(a, b, character_size:, bold: false)` — wraps
+  `sfFont_getKerning` / `getBoldKerning` for accurate glyph
+  pairing. Used in advanced text layout.
+- `Font#line_spacing(size)`, `Font#underline_position(size)`,
+  `Font#underline_thickness(size)` — typography metrics for the
+  given character size.
+- `Font#texture(size)` — borrowed `SFML::Texture` of the glyph
+  atlas (handy for debug visualisations of what's been rasterised).
+- `Font#dup` / `#clone` — independent deep copy.
+- `Font.from_memory(bytes)` — load from a Ruby String (embedded
+  assets, network responses, `data:` URLs).
+- `Text#find_character_pos(index)` — exact `Vector2` position of
+  the character at the given byte index. Critical for caret /
+  selection rendering in text inputs.
+- `Text#letter_spacing` / `#line_spacing` getters (the setters
+  were already there).
+- `Text#dup` / `#clone` — independent copy with the same string
+  and font reference.
+- `Text#transform` / `#inverse_transform` — the `SFML::Transform`
+  the renderer applies when drawing this Text.
+
+### Added — Image / Texture / RenderTexture
+- `Image.from_memory(bytes)` — decode PNG / JPG / BMP / TGA /
+  GIF / HDR / PSD from a Ruby String. Mirror of
+  `Image#save_to_memory`.
+- `Image#copy_from(source, at:, source_rect: nil, apply_alpha: false)`
+  — stamp a region of `source` into self. Useful for hand-built
+  texture atlases or composite images.
+- `Texture.create(width, height)` — allocate a blank GPU
+  texture; pair with `Texture#update(image)` to stream pixels.
+- `Texture.maximum_size` / `Texture.unbind` — class-level
+  helpers.
+- `Texture#bind(coord:)` — manually bind for raw OpenGL interop.
+- `Texture#srgb?`, `Texture#generate_mipmap`, `Texture#dup`.
+- `RenderTexture.maximum_anti_aliasing_level`,
+  `RenderTexture#srgb?`, `RenderTexture#generate_mipmap`.
+- `RenderTexture#active=`, `#push_gl_states`, `#pop_gl_states`,
+  `#reset_gl_states` — same GL-state machinery as RenderWindow.
+
+### Added — Window / RenderWindow polish
+- `RenderWindow#focused?` / `#request_focus` / `#position` /
+  `#position=` / `#srgb?`.
+- `RenderWindow#visible=`, `#key_repeat_enabled=`,
+  `#joystick_threshold=`.
+- `RenderWindow#active=`, `#push_gl_states`, `#pop_gl_states`,
+  `#reset_gl_states` — for mixing raw OpenGL calls with SFML
+  rendering. Surround custom GL with push/pop so SFML's
+  internal state survives.
+- `RenderWindow#wait_event(timeout:)` — block until the next
+  event or `timeout` elapses (a `SFML::Time`). For low-power /
+  event-driven apps that don't need a 60Hz update loop.
+- `Window#cursor=`, `#cursor_visible=`, `#cursor_grabbed=` —
+  parity with the same setters that already existed on
+  `RenderWindow`.
+- `Window#joystick_threshold=`, `Window#context_settings`,
+  `Window#wait_event(timeout:)`.
+
+### Added — Shader
+- `Shader#bind`, `Shader.unbind`, `Shader#native_handle` — for
+  raw GL interop and debug introspection.
+
+### Fixed
+- `SFML::App._dispatch` now forwards `:resized` events to *both*
+  `on_resize(width, height)` *and* `on_event(event)`. The 3.0.0.2
+  refactor accidentally routed `:resized` only through the
+  structured hook, which broke any app that forwarded
+  `on_event` to a sub-system (e.g. `def on_event(e) =
+  @gui.on_event(e)`) — the GUI never got told to refresh its
+  view + reflow on resize. Both hooks now receive the event;
+  apps that already use `on_resize` are unaffected.
+
 ## [3.0.0.2] — 2026-05-09
 
 ### Added

data/lib/sfml/app.rb

@@ -224,7 +224,12 @@ module SFML
       in {type: :closed}
         quit
       in {type: :resized, size: {x:, y:}}
+        # `:resized` fires BOTH the structured hook and the generic
+        # event sink — apps that forward `on_event` to a sub-system
+        # (`@gui.on_event(event)`, etc.) keep getting the event,
+        # while apps that just want clean (w, h) override the hook.
         on_resize(x, y)
+        on_event(event)
       in {type: :key_pressed, code:}
         # Scene-level bindings win over app-level (CSS-style cascade:
         # the more-specific layer overrides the more-general one).

data/lib/sfml/c/graphics.rb

@@ -108,6 +108,19 @@ module SFML
       attach_function :sfRenderWindow_setMaximumSize,         [:render_window_t, :pointer], :void
       attach_function :sfRenderWindow_createFromHandle,       [:pointer, :pointer], :render_window_t
       attach_function :sfRenderWindow_getNativeHandle,        [:render_window_t], :pointer
+      attach_function :sfRenderWindow_hasFocus,               [:render_window_t], :bool
+      attach_function :sfRenderWindow_requestFocus,           [:render_window_t], :void
+      attach_function :sfRenderWindow_getPosition,            [:render_window_t], System::Vector2i.by_value
+      attach_function :sfRenderWindow_setPosition,            [:render_window_t, System::Vector2i.by_value], :void
+      attach_function :sfRenderWindow_setVisible,             [:render_window_t, :bool], :void
+      attach_function :sfRenderWindow_setKeyRepeatEnabled,    [:render_window_t, :bool], :void
+      attach_function :sfRenderWindow_setJoystickThreshold,   [:render_window_t, :float], :void
+      attach_function :sfRenderWindow_setActive,              [:render_window_t, :bool], :bool
+      attach_function :sfRenderWindow_pushGLStates,           [:render_window_t], :void
+      attach_function :sfRenderWindow_popGLStates,            [:render_window_t], :void
+      attach_function :sfRenderWindow_resetGLStates,          [:render_window_t], :void
+      attach_function :sfRenderWindow_isSrgb,                 [:render_window_t], :bool
+      attach_function :sfRenderWindow_waitEvent,              [:render_window_t, System::Time.by_value, :pointer], :bool
 
       typedef :pointer, :texture_t
       typedef :pointer, :render_texture_t
@@ -205,8 +218,16 @@ module SFML
                       System::Vector2i.by_value
 
       # ---- Texture ----
+      attach_function :sfTexture_create,         [System::Vector2u.by_value], :texture_t
       attach_function :sfTexture_createFromFile, [:string, :pointer], :texture_t
       attach_function :sfTexture_createFromImage,[:image_t, :pointer], :texture_t
+      attach_function :sfTexture_copy,           [:texture_t], :texture_t
+      attach_function :sfTexture_isSrgb,         [:texture_t], :bool
+      attach_function :sfTexture_generateMipmap, [:texture_t], :bool
+      attach_function :sfTexture_getMaximumSize, [], :uint
+      # `sfTexture_bind` takes a CoordinateType enum (0 = normalised,
+      # 1 = pixels). Pass NULL to unbind.
+      attach_function :sfTexture_bind,           [:texture_t, :int], :void
       attach_function :sfTexture_destroy,        [:texture_t], :void
       attach_function :sfTexture_getSize,        [:texture_t], System::Vector2u.by_value
       attach_function :sfTexture_setSmooth,      [:texture_t, :bool], :void
@@ -223,7 +244,9 @@ module SFML
       attach_function :sfImage_createFromColor,   [System::Vector2u.by_value, Color.by_value], :image_t
       attach_function :sfImage_createFromPixels,  [System::Vector2u.by_value, :pointer], :image_t
       attach_function :sfImage_createFromFile,    [:string], :image_t
+      attach_function :sfImage_createFromMemory,  [:pointer, :size_t], :image_t
       attach_function :sfImage_copy,              [:image_t], :image_t
+      attach_function :sfImage_copyImage,         [:image_t, :image_t, System::Vector2u.by_value, IntRect.by_value, :bool], :bool
       attach_function :sfImage_destroy,           [:image_t], :void
       attach_function :sfImage_saveToFile,        [:image_t, :string], :bool
       attach_function :sfImage_saveToMemory,      [:image_t, :pointer, :string], :bool
@@ -356,6 +379,12 @@ module SFML
       attach_function :sfRenderTexture_isSmooth,        [:render_texture_t], :bool
       attach_function :sfRenderTexture_setRepeated,     [:render_texture_t, :bool], :void
       attach_function :sfRenderTexture_isRepeated,      [:render_texture_t], :bool
+      attach_function :sfRenderTexture_isSrgb,          [:render_texture_t], :bool
+      attach_function :sfRenderTexture_generateMipmap,  [:render_texture_t], :bool
+      attach_function :sfRenderTexture_getMaximumAntiAliasingLevel, [], :uint
+      attach_function :sfRenderTexture_pushGLStates,    [:render_texture_t], :void
+      attach_function :sfRenderTexture_popGLStates,     [:render_texture_t], :void
+      attach_function :sfRenderTexture_resetGLStates,   [:render_texture_t], :void
 
       attach_function :sfRenderTexture_mapPixelToCoords,
                       [:render_texture_t, System::Vector2i.by_value, :view_t],
@@ -386,6 +415,8 @@ module SFML
       attach_function :sfShader_createFromMemory, [:string, :string, :string], :shader_t
       attach_function :sfShader_destroy,          [:shader_t], :void
       attach_function :sfShader_isAvailable,      [], :bool
+      attach_function :sfShader_bind,             [:shader_t], :void
+      attach_function :sfShader_getNativeHandle,  [:shader_t], :uint
       attach_function :sfShader_isGeometryAvailable, [], :bool
 
       attach_function :sfShader_setFloatUniform,  [:shader_t, :string, :float], :void
@@ -429,10 +460,28 @@ module SFML
       attach_function :sfShader_setVec4UniformArray,  [:shader_t, :string, :pointer, :size_t], :void
 
       # ---- Font ----
-      attach_function :sfFont_createFromFile, [:string], :font_t
-      attach_function :sfFont_destroy,        [:font_t], :void
-      attach_function :sfFont_setSmooth,      [:font_t, :bool], :void
-      attach_function :sfFont_isSmooth,       [:font_t], :bool
+      # `sfFontInfo` carries one field — the human-readable font
+      # family. CSFML 3 expanded this struct's surface area only
+      # through the existing `getInfo` getter; new fields would
+      # arrive as additional struct members.
+      class FontInfo < FFI::Struct
+        layout :family, :pointer   # C string; copy out before the font is destroyed
+      end
+
+      attach_function :sfFont_createFromFile,        [:string], :font_t
+      attach_function :sfFont_createFromMemory,      [:pointer, :size_t], :font_t
+      attach_function :sfFont_copy,                  [:font_t], :font_t
+      attach_function :sfFont_destroy,               [:font_t], :void
+      attach_function :sfFont_setSmooth,             [:font_t, :bool], :void
+      attach_function :sfFont_isSmooth,              [:font_t], :bool
+      attach_function :sfFont_getInfo,               [:font_t], FontInfo.by_value
+      attach_function :sfFont_hasGlyph,              [:font_t, :uint32], :bool
+      attach_function :sfFont_getKerning,            [:font_t, :uint32, :uint32, :uint], :float
+      attach_function :sfFont_getBoldKerning,        [:font_t, :uint32, :uint32, :uint], :float
+      attach_function :sfFont_getLineSpacing,        [:font_t, :uint], :float
+      attach_function :sfFont_getUnderlinePosition,  [:font_t, :uint], :float
+      attach_function :sfFont_getUnderlineThickness, [:font_t, :uint], :float
+      attach_function :sfFont_getTexture,            [:font_t, :uint], :texture_t
 
       # ---- Text ----
       attach_function :sfText_create,             [:font_t], :text_t
@@ -455,7 +504,15 @@ module SFML
       attach_function :sfText_setStyle,           [:text_t, :uint32], :void
       attach_function :sfText_getStyle,           [:text_t], :uint32
       attach_function :sfText_setLetterSpacing,   [:text_t, :float], :void
+      attach_function :sfText_getLetterSpacing,   [:text_t], :float
       attach_function :sfText_setLineSpacing,     [:text_t, :float], :void
+      attach_function :sfText_getLineSpacing,     [:text_t], :float
+      attach_function :sfText_findCharacterPos,   [:text_t, :size_t], System::Vector2f.by_value
+      attach_function :sfText_getFont,            [:text_t], :font_t
+      attach_function :sfText_copy,               [:text_t], :text_t
+      attach_function :sfText_getString,          [:text_t], :string
+      attach_function :sfText_getTransform,       [:text_t], Transform.by_value
+      attach_function :sfText_getInverseTransform,[:text_t], Transform.by_value
       attach_function :sfText_setPosition,        [:text_t, System::Vector2f.by_value], :void
       attach_function :sfText_getPosition,        [:text_t], System::Vector2f.by_value
       attach_function :sfText_setRotation,        [:text_t, :float], :void

data/lib/sfml/c/window.rb

@@ -241,8 +241,15 @@ module SFML
       attach_function :sfWindow_setKeyRepeatEnabled,    [:raw_window_t, :bool], :void
       attach_function :sfWindow_requestFocus,  [:raw_window_t], :void
       attach_function :sfWindow_hasFocus,      [:raw_window_t], :bool
+      attach_function :sfWindow_requestFocus,  [:raw_window_t], :void
       attach_function :sfWindow_setActive,     [:raw_window_t, :bool], :bool
       attach_function :sfWindow_setIcon,       [:raw_window_t, System::Vector2u.by_value, :pointer], :void
+      attach_function :sfWindow_setMouseCursor,        [:raw_window_t, :pointer], :void
+      attach_function :sfWindow_setMouseCursorVisible, [:raw_window_t, :bool], :void
+      attach_function :sfWindow_setMouseCursorGrabbed, [:raw_window_t, :bool], :void
+      attach_function :sfWindow_setJoystickThreshold,  [:raw_window_t, :float], :void
+      attach_function :sfWindow_getSettings,           [:raw_window_t], ContextSettings.by_value
+      attach_function :sfWindow_waitEvent,             [:raw_window_t, System::Time.by_value, :pointer], :bool
       # NULL pointer clears the limit. Pass a Vector2u* to set it.
       attach_function :sfWindow_setMinimumSize, [:raw_window_t, :pointer], :void
       attach_function :sfWindow_setMaximumSize, [:raw_window_t, :pointer], :void

data/lib/sfml/graphics/font.rb

@@ -27,6 +27,23 @@ module SFML
       font
     end
 
+    # Load a font from a Ruby String of bytes — useful when the
+    # font lives inside a `data:` URL, an embedded asset, or a
+    # network response. The bytes are copied by SFML before this
+    # call returns; the caller's String can be GC'd safely.
+    def self.from_memory(bytes)
+      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.sfFont_createFromMemory(buf, bytes.bytesize)
+      raise Error, "sfFont_createFromMemory returned NULL" if ptr.null?
+
+      font = allocate
+      font.send(:_take_ownership, ptr)
+      font
+    end
+
     # The default font bundled with ruby-sfml. Use this when you don't
     # care which typeface as long as you can render text — examples,
     # debug HUDs, prototypes. Memoized so subsequent calls return the
@@ -56,6 +73,69 @@ module SFML
       C::Graphics.sfFont_setSmooth(@handle, !!value)
     end
 
+    # Human-readable family name (e.g. "DejaVu Sans"). Read once
+    # via `sfFont_getInfo` — CSFML returns a static C string from
+    # FreeType so we copy out into a Ruby String.
+    def family
+      info = C::Graphics.sfFont_getInfo(@handle)
+      info[:family].null? ? nil : info[:family].read_string
+    end
+
+    # `true` if the font has a glyph for the given Unicode codepoint
+    # (Integer) or single-character String.
+    def has_glyph?(codepoint)
+      cp = codepoint.is_a?(String) ? codepoint.codepoints.first : Integer(codepoint)
+      C::Graphics.sfFont_hasGlyph(@handle, cp || 0)
+    end
+
+    # Horizontal kerning offset between two adjacent glyphs at the
+    # given character size. Float, in pixels (often negative — the
+    # kern pulls the second glyph leftward).
+    def kerning(first, second, character_size:, bold: false)
+      a = first.is_a?(String)  ? first.codepoints.first  : Integer(first)
+      b = second.is_a?(String) ? second.codepoints.first : Integer(second)
+      fn = bold ? :sfFont_getBoldKerning : :sfFont_getKerning
+      C::Graphics.send(fn, @handle, a || 0, b || 0, Integer(character_size))
+    end
+
+    # Distance between two consecutive baselines for the given
+    # character size. Float, in pixels.
+    def line_spacing(character_size)
+      C::Graphics.sfFont_getLineSpacing(@handle, Integer(character_size))
+    end
+
+    # Vertical offset of the underline from the baseline (positive
+    # values point downward). Float, in pixels.
+    def underline_position(character_size)
+      C::Graphics.sfFont_getUnderlinePosition(@handle, Integer(character_size))
+    end
+
+    # Thickness of the underline stroke. Float, in pixels.
+    def underline_thickness(character_size)
+      C::Graphics.sfFont_getUnderlineThickness(@handle, Integer(character_size))
+    end
+
+    # The internal glyph atlas as a `SFML::Texture` (read-only — we
+    # don't own the pointer; CSFML keeps it alive as long as the
+    # font does).
+    def texture(character_size)
+      ptr = C::Graphics.sfFont_getTexture(@handle, Integer(character_size))
+      return nil if ptr.null?
+      Texture.send(:_borrow, ptr)
+    end
+
+    # Deep copy. The returned font has its own atlas state; mutate
+    # one without affecting the other.
+    def dup
+      ptr = C::Graphics.sfFont_copy(@handle)
+      raise Error, "sfFont_copy returned NULL" if ptr.null?
+
+      font = self.class.allocate
+      font.send(:_take_ownership, ptr)
+      font
+    end
+    alias clone dup
+
     attr_reader :handle # :nodoc:
 
     private

data/lib/sfml/graphics/image.rb

@@ -41,6 +41,23 @@ module SFML
       img
     end
 
+    # Decode an image from a Ruby String of bytes (PNG, JPG, BMP,
+    # TGA, GIF, HDR, PSD — whatever stb_image / SFML's loader
+    # supports). Mirror of `Image#save_to_memory` for round-trips
+    # without touching the disk.
+    def self.from_memory(bytes)
+      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.sfImage_createFromMemory(buf, bytes.bytesize)
+      raise Error, "sfImage_createFromMemory returned NULL — unsupported format?" if ptr.null?
+
+      img = allocate
+      img.send(:_take_ownership, ptr)
+      img
+    end
+
     # Build an image from a raw RGBA byte string. `pixels` must be
     # exactly width*height*4 bytes, row-major from the top-left.
     def self.from_pixels(width, height, pixels)
@@ -90,6 +107,36 @@ module SFML
       ptr.read_bytes(width * height * 4)
     end
 
+    # Copy a rectangular region of `source` into this image. The
+    # source region is `source_rect` (a `SFML::Rect` or `[x, y, w,
+    # h]` Array; defaults to the entire source); the destination
+    # top-left in this image is `at` (`[x, y]`). When `apply_alpha`
+    # is true, the source's alpha channel blends with this image's
+    # existing pixels; otherwise the copy is opaque.
+    #
+    # Useful for stamping sprites onto an atlas, blitting one
+    # image into a sub-rect of another, or hand-building a
+    # composite before uploading to GPU.
+    def copy_from(source, at:, source_rect: nil, apply_alpha: false)
+      raise ArgumentError, "Image#copy_from needs a SFML::Image" unless source.is_a?(Image)
+
+      dest = C::System::Vector2u.new
+      dest[:x] = Integer(at[0]); dest[:y] = Integer(at[1])
+
+      sr_struct = C::Graphics::IntRect.new
+      x, y, w, h =
+        case source_rect
+        when nil   then [0, 0, 0, 0]   # zeroes = "entire source" in CSFML
+        when Rect  then [source_rect.x, source_rect.y, source_rect.width, source_rect.height]
+        when Array then source_rect
+        else raise ArgumentError, "source_rect must be a SFML::Rect or [x, y, w, h]"
+        end
+      sr_struct[:position][:x] = Integer(x); sr_struct[:position][:y] = Integer(y)
+      sr_struct[:size][:x]     = Integer(w); sr_struct[:size][:y]     = Integer(h)
+      C::Graphics.sfImage_copyImage(@handle, source.handle, dest, sr_struct, !!apply_alpha)
+      self
+    end
+
     def save(path)
       ok = C::Graphics.sfImage_saveToFile(@handle, path.to_s)
       raise Error, "Could not save image to #{path.inspect}" unless ok

data/lib/sfml/graphics/render_texture.rb

@@ -51,6 +51,33 @@ module SFML
       C::Graphics.sfRenderTexture_setRepeated(@handle, !!value)
     end
 
+    # `true` if the framebuffer is sRGB-capable.
+    def srgb? = C::Graphics.sfRenderTexture_isSrgb(@handle)
+
+    # Generate mipmaps for the underlying texture. Useful when the
+    # texture will be sampled at a downscaled size — without
+    # mipmaps you get aliasing on minification. Returns `true` if
+    # the GPU honoured the request (NPOT or unsupported drivers
+    # return `false`).
+    def generate_mipmap
+      C::Graphics.sfRenderTexture_generateMipmap(@handle)
+    end
+
+    # Maximum MSAA level the driver can apply to a RenderTexture
+    # at this moment. Class-level — independent of the instance.
+    def self.maximum_anti_aliasing_level
+      C::Graphics.sfRenderTexture_getMaximumAntiAliasingLevel
+    end
+
+    # ---- GL interop (mirror of RenderWindow's) ----
+
+    def active=(value)
+      C::Graphics.sfRenderTexture_setActive(@handle, value ? true : false)
+    end
+    def push_gl_states  = C::Graphics.sfRenderTexture_pushGLStates(@handle)
+    def pop_gl_states   = C::Graphics.sfRenderTexture_popGLStates(@handle)
+    def reset_gl_states = C::Graphics.sfRenderTexture_resetGLStates(@handle)
+
     # The Texture this RenderTexture is rendering into. Borrowed — its
     # lifetime is bounded by `self`. Memoised so repeated calls return
     # the same Ruby wrapper.

data/lib/sfml/graphics/render_window.rb

@@ -162,6 +162,68 @@ module SFML
       C::Graphics.sfRenderWindow_getNativeHandle(@handle)
     end
 
+    # ---- Focus ----
+    def focused?       = C::Graphics.sfRenderWindow_hasFocus(@handle)
+    def request_focus  = C::Graphics.sfRenderWindow_requestFocus(@handle)
+
+    # ---- OS-window state ----
+    def visible=(value)
+      C::Graphics.sfRenderWindow_setVisible(@handle, value ? true : false)
+    end
+
+    def key_repeat_enabled=(value)
+      C::Graphics.sfRenderWindow_setKeyRepeatEnabled(@handle, value ? true : false)
+    end
+
+    def joystick_threshold=(value)
+      C::Graphics.sfRenderWindow_setJoystickThreshold(@handle, Float(value))
+    end
+
+    # Top-left corner in desktop coordinates.
+    def position
+      Vector2.from_native(C::Graphics.sfRenderWindow_getPosition(@handle))
+    end
+
+    def position=(value)
+      vec = value.is_a?(Vector2) ? value : Vector2.new(*value)
+      v = C::System::Vector2i.new
+      v[:x] = Integer(vec.x); v[:y] = Integer(vec.y)
+      C::Graphics.sfRenderWindow_setPosition(@handle, v)
+    end
+
+    # `true` if the framebuffer is sRGB-capable (i.e. the GL
+    # context was created with the sRGB attribute and the driver
+    # honoured it).
+    def srgb? = C::Graphics.sfRenderWindow_isSrgb(@handle)
+
+    # ---- GL interop ----
+    #
+    # When mixing raw OpenGL calls with SFML rendering, surround
+    # the OpenGL block with `push_gl_states` / `pop_gl_states` so
+    # SFML's internal state survives. `reset_gl_states` is a
+    # heavier "throw away whatever's been changed" reset.
+    # `active=` toggles the GL context's activation on the
+    # current thread — the only way to use SFML rendering from a
+    # non-main thread.
+
+    def active=(value)
+      C::Graphics.sfRenderWindow_setActive(@handle, value ? true : false)
+    end
+    def push_gl_states  = C::Graphics.sfRenderWindow_pushGLStates(@handle)
+    def pop_gl_states   = C::Graphics.sfRenderWindow_popGLStates(@handle)
+    def reset_gl_states = C::Graphics.sfRenderWindow_resetGLStates(@handle)
+
+    # Block until an event arrives or `timeout` (a SFML::Time)
+    # elapses. Returns the next pending Event or nil on timeout.
+    # Useful for low-power apps that don't need to redraw at
+    # 60fps — wake on input.
+    def wait_event(timeout: nil)
+      t = timeout || Time.zero
+      ok = C::Graphics.sfRenderWindow_waitEvent(@handle, t.to_native, @event_buffer)
+      return nil unless ok
+      Event.from_native(@event_buffer)
+    end
+
     # Wrap an existing OS-level window. `handle` is a platform native
     # handle (Integer address or FFI::Pointer). Useful for embedding
     # the renderer inside another framework's window (Qt, Gtk, raw

data/lib/sfml/graphics/shader.rb

@@ -139,6 +139,19 @@ module SFML
       C::Graphics.sfShader_setFloatUniformArray(@handle, name.to_s, buf, values.length)
     end
 
+    # Bind this shader as the active GL program. Useful when you
+    # want to issue raw GL draw calls under SFML's context. Pair
+    # with `Shader.unbind` to restore SFML's default. Most users
+    # don't need this — just pass the shader to `target.draw(...,
+    # render_states: SFML::RenderStates.new(shader: self))`.
+    def bind = C::Graphics.sfShader_bind(@handle)
+
+    def self.unbind = C::Graphics.sfShader_bind(nil)
+
+    # The OpenGL program ID. Useful for debug printf / interop
+    # with raw GL libraries.
+    def native_handle = C::Graphics.sfShader_getNativeHandle(@handle)
+
     attr_reader :handle # :nodoc:
 
     private

data/lib/sfml/graphics/text.rb

@@ -123,6 +123,53 @@ module SFML
       C::Graphics.sfText_setStyle(@handle, bits)
     end
 
+    # The character spacing modifier — a multiplier on the font's
+    # natural advance. Read with no args, set with a Float (1.0 =
+    # default).
+    def letter_spacing = C::Graphics.sfText_getLetterSpacing(@handle)
+
+    def letter_spacing=(value)
+      C::Graphics.sfText_setLetterSpacing(@handle, Float(value))
+    end
+
+    # The line-spacing multiplier (1.0 = default).
+    def line_spacing = C::Graphics.sfText_getLineSpacing(@handle)
+
+    def line_spacing=(value)
+      C::Graphics.sfText_setLineSpacing(@handle, Float(value))
+    end
+
+    # The screen-space position of the character at byte index
+    # `index` in the Text's current string. Returns a `Vector2`.
+    # Useful for positioning a caret in a text field, drawing
+    # selection highlights, or anchoring tooltips.
+    def find_character_pos(index)
+      Vector2.from_native(C::Graphics.sfText_findCharacterPos(@handle, Integer(index)))
+    end
+
+    # Combined translation/scale/rotation as a SFML::Transform.
+    # Same matrix the renderer uses to draw the Text.
+    def transform
+      C::Graphics.sfText_getTransform(@handle)
+    end
+
+    def inverse_transform
+      C::Graphics.sfText_getInverseTransform(@handle)
+    end
+
+    # Deep copy. The returned Text holds the same Font reference
+    # (Fonts are shareable; each owns its own glyph atlas).
+    def dup
+      ptr = C::Graphics.sfText_copy(@handle)
+      raise Error, "sfText_copy returned NULL" if ptr.null?
+
+      copy = self.class.allocate
+      copy.instance_variable_set(:@handle, FFI::AutoPointer.new(ptr, C::Graphics.method(:sfText_destroy)))
+      copy.instance_variable_set(:@font, @font)
+      copy
+    end
+    alias clone dup
+
     # Bounding box of the text in its own (untransformed) coordinate system.
     # Use this to centre or align glyphs precisely:
     #   text.origin = [text.local_bounds.width / 2, 0]

data/lib/sfml/graphics/texture.rb

@@ -16,6 +16,21 @@ module SFML
       tex
     end
 
+    # Allocate a blank texture on the GPU at the given size — use
+    # `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)
+      size = C::System::Vector2u.new
+      size[:x] = Integer(width); size[:y] = Integer(height)
+      ptr = C::Graphics.sfTexture_create(size)
+      raise Error, "sfTexture_create returned NULL — out of GPU memory?" if ptr.null?
+
+      tex = allocate
+      tex.send(:_take_ownership, ptr)
+      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)
@@ -68,8 +83,58 @@ module SFML
       C::Graphics.sfTexture_setRepeated(@handle, !!value)
     end
 
+    def srgb? = C::Graphics.sfTexture_isSrgb(@handle)
+
+    # Generate mipmaps for this texture. Returns `true` if the
+    # GPU honoured it. Required for the `_MIPMAP_*` minification
+    # filters; otherwise downscaled samples alias.
+    def generate_mipmap = C::Graphics.sfTexture_generateMipmap(@handle)
+
+    # Bind this texture to the active OpenGL texture unit. `coord`
+    # is one of `:normalized` (default — UVs in [0..1]) or
+    # `:pixels` (UVs in [0..size]). Useful when mixing raw
+    # OpenGL with SFML rendering. Pass `nil` to unbind:
+    #   `SFML::Texture.unbind`.
+    COORDINATE_TYPES = {normalized: 0, pixels: 1}.freeze
+
+    def bind(coord: :normalized)
+      raise ArgumentError, "coord must be :normalized or :pixels" unless COORDINATE_TYPES.key?(coord)
+      C::Graphics.sfTexture_bind(@handle, COORDINATE_TYPES[coord])
+    end
+
+    def self.unbind
+      C::Graphics.sfTexture_bind(nil, 0)
+    end
+
+    # Maximum texture dimension the driver will allocate. Tied to
+    # the GL state, so it's a class-level call (no instance).
+    def self.maximum_size
+      C::Graphics.sfTexture_getMaximumSize
+    end
+
+    # Deep copy. The returned texture has its own GPU memory.
+    def dup
+      ptr = C::Graphics.sfTexture_copy(@handle)
+      raise Error, "sfTexture_copy returned NULL" if ptr.null?
+
+      tex = self.class.allocate
+      tex.send(:_take_ownership, ptr)
+      tex
+    end
+    alias clone dup
+
     attr_reader :handle # :nodoc:
 
+    # Internal — borrow a CSFML-owned `sfTexture*` (e.g. one
+    # returned by `sfFont_getTexture`) without registering an
+    # auto-destroy hook. The owning object is responsible for
+    # outliving any draw call that uses this borrowed handle.
+    def self._borrow(ptr)
+      tex = allocate
+      tex.instance_variable_set(:@handle, ptr)
+      tex
+    end
+
     private
 
     def _take_ownership(ptr)

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.2"
+  VERSION = "3.0.0.3"
 end

data/lib/sfml/window/window.rb

@@ -129,6 +129,44 @@ module SFML
       C::Window.sfWindow_setActive(@handle, value ? true : false)
     end
 
+    # ---- Mouse cursor ----
+
+    def cursor=(cursor)
+      raise ArgumentError, "Window#cursor= requires a SFML::Cursor" unless cursor.is_a?(Cursor)
+      C::Window.sfWindow_setMouseCursor(@handle, cursor.handle)
+      @cursor = cursor   # keep alive
+    end
+
+    def cursor_visible=(visible)
+      C::Window.sfWindow_setMouseCursorVisible(@handle, visible ? true : false)
+    end
+
+    def cursor_grabbed=(grabbed)
+      C::Window.sfWindow_setMouseCursorGrabbed(@handle, grabbed ? true : false)
+    end
+
+    # ---- Misc state ----
+
+    def joystick_threshold=(value)
+      C::Window.sfWindow_setJoystickThreshold(@handle, Float(value))
+    end
+
+    # The actual GL context settings the driver gave us — may differ
+    # from what was requested via `ContextSettings`.
+    def context_settings
+      ContextSettings.from_native(C::Window.sfWindow_getSettings(@handle))
+    end
+
+    # Block until the next event arrives or `timeout` (a SFML::Time)
+    # elapses. `nil` timeout = wait forever (matches CSFML's
+    # `sfTime_Zero` / no-timeout convention).
+    def wait_event(timeout: nil)
+      t = timeout || Time.zero
+      ok = C::Window.sfWindow_waitEvent(@handle, t.to_native, @event_buffer)
+      return nil unless ok
+      Event.from_native(@event_buffer)
+    end
+
     # Replace the window's title-bar / taskbar icon with the pixels from
     # the given SFML::Image. The OS scales it as needed; 32×32 RGBA
     # is the typical sweet spot.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-sfml
 version: !ruby/object:Gem::Version
-  version: 3.0.0.2
+  version: 3.0.0.3
 platform: ruby
 authors:
 - Mykhailo Melnyk