glfw-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e48fb1ff8edb79abc14e6e0ae76ccc89954f459a97c109b385fbffe0f566c55
+  data.tar.gz: 58042deb5b8f9a4d3316dde069de3a37bb39a0665c79b0ca37760cef08d94649
+SHA512:
+  metadata.gz: 4c8c65d86740fe3db5f8a6e58aebdb5e3d3b738507e4eb0f9ff63a0699fb1e70c0794c2fd402f67ae8278b64c89414fc0ced80ab27d4e136aba45e286f28238e
+  data.tar.gz: 93560ee8ede49b87eaada628f23601ecb0a3e719a4c79af19fa8b69f2bf0929bdacf2caed240eac832209a4b28bf52030c008d3066d66778c31828a239542f29

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,243 @@
+# glfw-ruby
+
+Pure Ruby FFI bindings for GLFW 3.3/3.4.
+
+This gem exposes:
+
+- `GLFW::API` for low-level access that stays close to the C API
+- Ruby-friendly wrappers such as `GLFW::Window`, `GLFW::Monitor`, `GLFW::Cursor`, `GLFW::Joystick`, and `GLFW::Gamepad`
+- GLFW 3.4 additions including platform queries, allocator support, and Vulkan loader hooks
+
+The gem does not bundle GLFW itself. You need a native GLFW shared library installed on the machine.
+
+## Requirements
+
+- Ruby `>= 3.1`
+- A native GLFW 3.3 or 3.4 shared library available to the dynamic linker
+
+If the loader cannot find the library automatically, set `GLFW_LIB_PATH` to the full path of the shared library.
+
+## Installation
+
+Add the gem:
+
+```bash
+bundle add glfw
+```
+
+Or install it directly:
+
+```bash
+gem install glfw
+```
+
+Install the native GLFW library separately:
+
+### macOS
+
+```bash
+brew install glfw
+```
+
+### Ubuntu / Debian
+
+```bash
+sudo apt-get install libglfw3
+```
+
+### Windows
+
+Install a GLFW DLL and make sure it is on `PATH`, or point `GLFW_LIB_PATH` at the DLL file.
+
+## Quick Start
+
+```ruby
+require "glfw"
+
+GLFW.on_error do |code, description|
+  warn "[GLFW #{code}] #{description}"
+end
+
+GLFW.init
+
+begin
+  window = GLFW::Window.new(
+    800,
+    600,
+    "Hello GLFW",
+    visible: false,
+    context_version_major: 3,
+    context_version_minor: 3
+  )
+
+  window.make_context_current
+  window.show
+
+  until window.should_close?
+    # draw here
+    window.swap_buffers
+    GLFW.poll_events
+  end
+ensure
+  window&.destroy
+  GLFW.terminate
+end
+```
+
+## Examples
+
+Example scripts live in `examples/` and can be run from a source checkout.
+
+```bash
+bundle exec ruby examples/01_minimal_window.rb
+```
+
+Available examples:
+
+- `examples/01_minimal_window.rb` - smallest window + event loop example
+- `examples/02_input_callbacks.rb` - keyboard, mouse, cursor, scroll, and drop callbacks
+- `examples/03_window_attributes.rb` - window title, size, position, opacity, and attribute changes
+- `examples/04_monitor_info.rb` - monitor enumeration and video mode inspection
+- `examples/05_custom_cursor_and_icon.rb` - generated cursor and window icon data
+- `examples/06_gamepad_inspector.rb` - joystick and gamepad state inspector
+- `examples/07_glfw_34_features.rb` - platform queries and other GLFW 3.4 runtime-only features
+
+On headless Linux, run windowed examples under Xvfb.
+
+## High-Level API
+
+The high-level layer wraps common GLFW concepts in plain Ruby objects.
+
+### `GLFW`
+
+- `GLFW.init` / `GLFW.terminate`
+- `GLFW.version`
+- `GLFW.version_at_least?(major, minor)`
+- `GLFW.poll_events`
+- `GLFW.wait_events(timeout: nil)`
+- `GLFW.post_empty_event`
+- `GLFW.time` / `GLFW.time=`
+- `GLFW.clipboard` / `GLFW.clipboard=`
+- `GLFW.platform` (`GLFW 3.4+` runtime only)
+- `GLFW.platform_supported?(platform_constant)` (`GLFW 3.4+` runtime only)
+- `GLFW.on_error { |code, description| ... }`
+
+### `GLFW::Window`
+
+Supports window creation, context management, input polling, attributes, and callbacks.
+
+Examples of supported operations:
+
+- title, size, position, framebuffer size, frame size, content scale, opacity
+- show / hide / focus / maximize / restore / iconify
+- fullscreen and windowed transitions
+- icon updates via `set_icon` / `clear_icon`
+- cursor assignment and cursor position access
+- keyboard and mouse input queries
+- callbacks such as `on_key`, `on_char`, `on_mouse_button`, `on_cursor_pos`, `on_scroll`, `on_drop`, `on_resize`, `on_close`, and more
+
+Window hints are passed as keyword arguments:
+
+```ruby
+window = GLFW::Window.new(
+  1280,
+  720,
+  "Example",
+  visible: false,
+  resizable: true,
+  opengl_profile: :core,
+  context_version_major: 4,
+  context_version_minor: 1
+)
+```
+
+### `GLFW::Monitor`
+
+- `GLFW::Monitor.all`
+- `GLFW::Monitor.primary`
+- monitor name, position, workarea, physical size, content scale
+- video modes and current video mode
+- gamma and gamma ramps
+- hotplug callback via `GLFW::Monitor.on_connect`
+
+### `GLFW::Cursor` and `GLFW::Image`
+
+- create standard cursors with `GLFW::Cursor.standard`
+- create custom cursors from RGBA image data with `GLFW::Cursor.create`
+- build image payloads with `GLFW::Image.from_rgba`
+
+### `GLFW::Joystick` and `GLFW::Gamepad`
+
+- joystick presence, name, GUID, axes, buttons, hats
+- gamepad detection and state access
+- gamepad mapping updates
+- joystick connection callback via `GLFW::Joystick.on_connect`
+
+## Low-Level API
+
+`GLFW::API` mirrors the native C API through FFI `attach_function` declarations. Use it when you want direct access to GLFW without the object wrappers.
+
+```ruby
+require "glfw"
+
+puts GLFW::API.glfwGetVersionString
+puts GLFW::API.glfwPlatformSupported(GLFW::GLFW_PLATFORM_X11)
+```
+
+Low-level types live under `GLFW::API`, including:
+
+- `GLFWvidmode`
+- `GLFWgammaramp`
+- `GLFWimage`
+- `GLFWgamepadstate`
+- `GLFWallocator`
+
+The binding also exposes the usual GLFW constants, error codes, window hints, platform constants, input constants, and cursor shapes.
+
+## Errors
+
+Base error classes:
+
+- `GLFW::Error`
+- `GLFW::LibraryNotFoundError`
+- `GLFW::InitError`
+- `GLFW::NotSupportedError`
+- `GLFW::APIError`
+
+If no custom error callback is registered, `GLFW.init` installs a default callback that prints GLFW error messages to stderr.
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Or run the default task:
+
+```bash
+bundle exec rake
+```
+
+On headless Linux, run specs under Xvfb:
+
+```bash
+xvfb-run -a bundle exec rspec
+```
+
+## Contributing
+
+Issues and pull requests are welcome at:
+
+- https://github.com/ydah/glfw-ruby
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/01_minimal_window.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "example_runtime"
+
+GLFWExample.with_window(title: "Minimal Window", width: 800, height: 600, visible: true) do |window|
+  GLFWExample.print_banner("01 Minimal Window", [
+    "Esc: close the window",
+    "Use the window close button to exit as well."
+  ])
+
+  window.make_context_current
+  GLFW::API.glfwSwapInterval(1)
+
+  window.on_key do |current_window, key, _scancode, action, _mods|
+    current_window.should_close = true if key == GLFW::GLFW_KEY_ESCAPE && action == :press
+  end
+
+  window.on_close do |_current_window|
+    puts "Close requested."
+  end
+
+  frame = 0
+
+  GLFWExample.loop_until_closed(window) do
+    frame += 1
+
+    if (frame % 120).zero?
+      seconds = format("%.1f", frame / 60.0)
+      window.title = "Minimal Window (#{seconds}s)"
+    end
+
+    window.swap_buffers
+  end
+end

data/examples/02_input_callbacks.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "example_runtime"
+
+GLFWExample.with_window(title: "Input Callbacks", width: 900, height: 600, visible: true) do |window|
+  GLFWExample.print_banner("02 Input Callbacks", [
+    "Type, click, scroll, move the cursor, or drop files onto the window.",
+    "Esc: close the window"
+  ])
+
+  window.make_context_current
+  GLFW::API.glfwSwapInterval(1)
+
+  last_cursor_report_at = 0.0
+
+  window.on_key do |current_window, key, scancode, action, mods|
+    puts "key=#{key} scancode=#{scancode} action=#{action} mods=0x#{mods.to_s(16)}"
+    current_window.should_close = true if key == GLFW::GLFW_KEY_ESCAPE && action == :press
+  end
+
+  window.on_char do |_current_window, codepoint|
+    character = codepoint.chr(Encoding::UTF_8)
+    puts "char=#{character.inspect} codepoint=U+#{codepoint.to_s(16).upcase.rjust(4, '0')}"
+  rescue RangeError
+    puts "char=<invalid> codepoint=#{codepoint}"
+  end
+
+  window.on_mouse_button do |_current_window, button, action, mods|
+    puts "mouse_button=#{button} action=#{action} mods=0x#{mods.to_s(16)}"
+  end
+
+  window.on_cursor_enter do |_current_window, entered|
+    puts "cursor_enter=#{entered}"
+  end
+
+  window.on_cursor_pos do |_current_window, x, y|
+    now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    next if now - last_cursor_report_at < 0.10
+
+    last_cursor_report_at = now
+    puts format("cursor_pos=(%.1f, %.1f)", x, y)
+  end
+
+  window.on_scroll do |_current_window, xoffset, yoffset|
+    puts format("scroll=(%.2f, %.2f)", xoffset, yoffset)
+  end
+
+  window.on_drop do |_current_window, paths|
+    puts "drop=#{paths.join(', ')}"
+  end
+
+  GLFWExample.loop_until_closed(window) do
+    window.swap_buffers
+  end
+end

data/examples/03_window_attributes.rb

@@ -0,0 +1,116 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "example_runtime"
+
+GLFWExample.with_window(
+  title: "Window Attributes",
+  width: 960,
+  height: 640,
+  visible: true,
+  resizable: true,
+  decorated: true
+) do |window|
+  GLFWExample.print_banner("03 Window Attributes", [
+    "Esc: close",
+    "P: print current state",
+    "T: update title with a timestamp",
+    "Arrow keys: move the window",
+    "= / -: resize the window",
+    "1 / 2 / 3: set opacity",
+    "F: toggle floating",
+    "M / R / I: maximize, restore, iconify"
+  ])
+
+  window.make_context_current
+  GLFW::API.glfwSwapInterval(1)
+
+  print_state = lambda do
+    puts "title=#{window.title.inspect}"
+    puts "size=#{window.size.inspect} position=#{window.position.inspect}"
+    puts "framebuffer=#{window.framebuffer_size.inspect} content_scale=#{window.content_scale.inspect}"
+    puts "frame=#{window.frame_size.inspect} opacity=#{window.opacity.round(2)}"
+    puts "decorated=#{window.decorated?} resizable=#{window.resizable?} " \
+         "floating=#{window.floating?} focus_on_show=#{window.focus_on_show?}"
+    puts
+  end
+
+  print_state.call
+
+  window.on_resize do |_current_window, width, height|
+    puts "resized to #{width}x#{height}"
+  end
+
+  window.on_focus do |_current_window, focused|
+    puts "focused=#{focused}"
+  end
+
+  window.on_iconify do |_current_window, iconified|
+    puts "iconified=#{iconified}"
+  end
+
+  window.on_maximize do |_current_window, maximized|
+    puts "maximized=#{maximized}"
+  end
+
+  window.on_key do |current_window, key, _scancode, action, _mods|
+    next unless action == :press || action == :repeat
+
+    case key
+    when GLFW::GLFW_KEY_ESCAPE
+      current_window.should_close = true
+    when GLFW::GLFW_KEY_P
+      print_state.call
+    when GLFW::GLFW_KEY_T
+      current_window.title = "Window Attributes @ #{Time.now.strftime('%H:%M:%S')}"
+      print_state.call
+    when GLFW::GLFW_KEY_UP
+      x, y = current_window.position
+      current_window.position = [x, y - 20]
+      print_state.call
+    when GLFW::GLFW_KEY_DOWN
+      x, y = current_window.position
+      current_window.position = [x, y + 20]
+      print_state.call
+    when GLFW::GLFW_KEY_LEFT
+      x, y = current_window.position
+      current_window.position = [x - 20, y]
+      print_state.call
+    when GLFW::GLFW_KEY_RIGHT
+      x, y = current_window.position
+      current_window.position = [x + 20, y]
+      print_state.call
+    when GLFW::GLFW_KEY_EQUAL, GLFW::GLFW_KEY_KP_ADD
+      width, height = current_window.size
+      current_window.size = [width + 20, height + 20]
+      print_state.call
+    when GLFW::GLFW_KEY_MINUS, GLFW::GLFW_KEY_KP_SUBTRACT
+      width, height = current_window.size
+      current_window.size = [[width - 20, 240].max, [height - 20, 180].max]
+      print_state.call
+    when GLFW::GLFW_KEY_1
+      current_window.opacity = 1.0
+      print_state.call
+    when GLFW::GLFW_KEY_2
+      current_window.opacity = 0.8
+      print_state.call
+    when GLFW::GLFW_KEY_3
+      current_window.opacity = 0.6
+      print_state.call
+    when GLFW::GLFW_KEY_F
+      value = current_window.floating? ? GLFW::GLFW_FALSE : GLFW::GLFW_TRUE
+      current_window.set_attrib(GLFW::GLFW_FLOATING, value)
+      print_state.call
+    when GLFW::GLFW_KEY_M
+      current_window.maximize
+    when GLFW::GLFW_KEY_R
+      current_window.restore
+    when GLFW::GLFW_KEY_I
+      current_window.iconify
+    end
+  end
+
+  GLFWExample.loop_until_closed(window) do
+    window.swap_buffers
+  end
+end

data/examples/04_monitor_info.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "example_runtime"
+
+GLFWExample.with_glfw do
+  runtime_version = GLFW.version.join(".")
+  platform_line = if GLFW.version_at_least?(3, 4)
+                    "Current platform: #{GLFW.platform}"
+                  else
+                    "Current platform: unavailable on GLFW #{runtime_version}"
+                  end
+
+  GLFWExample.print_banner("04 Monitor Info", [
+    "Loaded GLFW runtime: #{runtime_version}",
+    platform_line
+  ])
+
+  monitors = GLFW::Monitor.all
+  primary = GLFW::Monitor.primary
+
+  if monitors.empty?
+    puts "No monitors reported by GLFW."
+    next
+  end
+
+  monitors.each_with_index do |monitor, index|
+    marker = primary && primary.handle.address == monitor.handle.address ? "*" : " "
+    mode = monitor.current_video_mode
+    sample_modes = monitor.video_modes.uniq.first(5)
+
+    puts "#{marker} Monitor #{index}: #{monitor.name || '(unnamed)'}"
+    puts "  position: #{monitor.position.inspect}"
+    puts "  workarea: #{monitor.workarea.inspect}"
+    puts "  physical_size_mm: #{monitor.physical_size.inspect}"
+    puts "  content_scale: #{monitor.content_scale.inspect}"
+    puts "  current_mode: #{mode ? GLFWExample.format_video_mode(mode) : '(none)'}"
+    puts "  sample_modes:"
+
+    if sample_modes.empty?
+      puts "    (none)"
+    else
+      sample_modes.each do |video_mode|
+        puts "    - #{GLFWExample.format_video_mode(video_mode)}"
+      end
+    end
+
+    puts
+  end
+
+  puts "* marks the primary monitor."
+end

data/examples/05_custom_cursor_and_icon.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "example_runtime"
+
+def checkerboard_rgba(size, color_a, color_b, cell_size: 4)
+  data = String.new(capacity: size * size * 4, encoding: Encoding::BINARY)
+
+  size.times do |y|
+    size.times do |x|
+      color = ((x / cell_size) + (y / cell_size)).even? ? color_a : color_b
+      data << color.pack("C4")
+    end
+  end
+
+  data
+end
+
+def crosshair_rgba(size, foreground, border)
+  center = size / 2
+  data = String.new(capacity: size * size * 4, encoding: Encoding::BINARY)
+
+  size.times do |y|
+    size.times do |x|
+      color =
+        if x == center || y == center
+          foreground
+        elsif x.zero? || y.zero? || x == size - 1 || y == size - 1
+          border
+        else
+          [0, 0, 0, 0]
+        end
+
+      data << color.pack("C4")
+    end
+  end
+
+  data
+end
+
+GLFWExample.with_window(title: "Custom Cursor and Icon", width: 840, height: 520, visible: true) do |window|
+  GLFWExample.print_banner("05 Custom Cursor and Icon", [
+    "Esc: close",
+    "C: toggle custom and standard cursors",
+    "I: toggle custom window icons"
+  ])
+
+  window.make_context_current
+  GLFW::API.glfwSwapInterval(1)
+
+  icon_16 = GLFW::Image.from_rgba(16, 16, checkerboard_rgba(16, [255, 138, 0, 255], [32, 32, 32, 255]))
+  icon_32 = GLFW::Image.from_rgba(32, 32, checkerboard_rgba(32, [255, 196, 64, 255], [16, 16, 16, 255], cell_size: 8))
+  cursor_image = GLFW::Image.from_rgba(24, 24, crosshair_rgba(24, [80, 220, 255, 255], [255, 255, 255, 255]))
+
+  custom_cursor = GLFW::Cursor.create(cursor_image, 12, 12)
+  standard_cursor = GLFW::Cursor.standard(GLFW::GLFW_POINTING_HAND_CURSOR)
+
+  window.set_icon([icon_16, icon_32])
+  window.cursor = custom_cursor
+
+  using_custom_cursor = true
+  icon_enabled = true
+
+  window.on_key do |current_window, key, _scancode, action, _mods|
+    next unless action == :press
+
+    case key
+    when GLFW::GLFW_KEY_ESCAPE
+      current_window.should_close = true
+    when GLFW::GLFW_KEY_C
+      using_custom_cursor = !using_custom_cursor
+      current_window.cursor = using_custom_cursor ? custom_cursor : standard_cursor
+      puts "Cursor is now #{using_custom_cursor ? 'custom' : 'standard'}."
+    when GLFW::GLFW_KEY_I
+      icon_enabled = !icon_enabled
+
+      if icon_enabled
+        current_window.set_icon([icon_16, icon_32])
+        puts "Custom icon restored."
+      else
+        current_window.clear_icon
+        puts "Window icon cleared."
+      end
+    end
+  end
+
+  GLFWExample.loop_until_closed(window) do
+    window.swap_buffers
+  end
+ensure
+  custom_cursor&.destroy
+  standard_cursor&.destroy
+end