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.

• 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.

Add the gem:

bundle add glfw

Or install it directly:

gem install glfw

Install the native GLFW library separately:

brew install glfw

sudo apt-get install libglfw3

Install a GLFW DLL and make sure it is on PATH, or point GLFW_LIB_PATH at the DLL file.

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

Example scripts live in examples/ and can be run from a source checkout.

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.

The high-level layer wraps common GLFW concepts in plain Ruby objects.

• 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| ... }

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:

window = GLFW::Window.new(
  1280,
  720,
  "Example",
  visible: false,
  resizable: true,
  opengl_profile: :core,
  context_version_major: 4,
  context_version_minor: 1
)

• 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

• 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

• joystick presence, name, GUID, axes, buttons, hats
• gamepad detection and state access
• gamepad mapping updates
• joystick connection callback via GLFW::Joystick.on_connect

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.

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.

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.

Install dependencies:

bundle install

Run the test suite:

bundle exec rspec

Or run the default task:

bundle exec rake

On headless Linux, run specs under Xvfb:

xvfb-run -a bundle exec rspec

Issues and pull requests are welcome at:

• https://github.com/ydah/glfw-ruby

Released under the MIT License.