https://github.com/ydah/glfw-ruby
Pure Ruby FFI bindings for GLFW 3.3/3.4.
https://github.com/ydah/glfw-ruby
2d-graphics 3d-graphics bindings ffi glfw glfw3 graphics ruby
Last synced: 24 days ago
JSON representation
Pure Ruby FFI bindings for GLFW 3.3/3.4.
- Host: GitHub
- URL: https://github.com/ydah/glfw-ruby
- Owner: ydah
- License: mit
- Created: 2026-03-06T13:35:11.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-07T12:00:08.000Z (4 months ago)
- Last Synced: 2026-03-07T17:09:00.799Z (4 months ago)
- Topics: 2d-graphics, 3d-graphics, bindings, ffi, glfw, glfw3, graphics, ruby
- Language: Ruby
- Homepage:
- Size: 51.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# 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).