rugl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4dd4f813b58ccae38822027f48263c23a4e2e89a19a4f45a04c10542eee35784
+  data.tar.gz: 0bc5750099f8ce7d8f087bda51996ae9480efea9972065d0f403d2f07bfc090e
+SHA512:
+  metadata.gz: 6047ff624719eb0a15179a639ff12765d041e36ce30823ca7ad43e01c4dcd91498eceab9c5ddfbf1fa1e317893f5e229e3358570a8f4dd1fc4d2d1352d486b02
+  data.tar.gz: efd1efe350e4233e2f6327ba0c9befc2b0c15b9f27b2b80214c5378bd87336ba4b113bdbd54c375d2cc0fa0d92a4d23f0d3fbe29949b94f254aab64668a969a1

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,293 @@
+# Rugl
+
+Functional OpenGL for Ruby.
+
+Rugl is a small command-oriented rendering layer on top of OpenGL bindings. You describe draw calls as immutable Ruby hashes, resolve dynamic values at execution time, and let Rugl handle shader compilation, VAO setup, resource tracking, and render-state diffing.
+
+## Current Feature Set
+
+- `Rugl.create` builds a rendering context and can bootstrap a default GLFW window/context
+- `rugl.command(...)` compiles reusable draw commands from shader source plus draw/state options
+- dynamic values can come from runtime props, frame context, scoped props, or procs
+- commands support single draws, batched draws, indexed draws, instancing, scoped execution, and framebuffer targets
+- GPU resources include buffers, element buffers, textures, renderbuffers, and framebuffers
+- render state diffing covers `depth`, `blend`, `stencil`, `scissor`, `cull`, `polygon_offset`, `color_mask`, `front_face`, `line_width`, `dither`, `sample`, and `viewport`
+- context helpers include `clear`, `read`, `limits`, and `has_extension?`
+
+## Installation
+
+### Runtime requirements
+
+- Ruby 3.1+
+- [`opengl-bindings`](https://rubygems.org/gems/opengl-bindings) for OpenGL symbols
+- `glfw` only if you want `Rugl.create` to open a default window/context for you
+
+### System dependencies
+
+If you want Rugl to create its own window/context via GLFW, install GLFW and OpenGL development libraries first.
+
+```bash
+# Ubuntu / Debian
+sudo apt-get install libglfw3-dev libgl1-mesa-dev
+
+# macOS
+brew install glfw
+```
+
+### Gem install
+
+```bash
+gem install rugl
+gem install glfw # optional, only for the default window/context path
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem "rugl", git: "https://github.com/ydah/rugl"
+gem "glfw" # optional
+```
+
+## Quick Start
+
+```ruby
+require "rugl"
+
+rugl = Rugl.create(width: 800, height: 600, title: "Rugl Triangle")
+
+draw_triangle = rugl.command(
+  vert: <<~GLSL,
+    #version 410 core
+    layout(location = 0) in vec2 position;
+    void main() {
+      gl_Position = vec4(position, 0.0, 1.0);
+    }
+  GLSL
+  frag: <<~GLSL,
+    #version 410 core
+    uniform vec4 color;
+    out vec4 fragColor;
+    void main() {
+      fragColor = color;
+    }
+  GLSL
+  attributes: {
+    position: rugl.buffer([[-2, -2], [4, -2], [4, 4]])
+  },
+  uniforms: {
+    color: Rugl.prop(:color)
+  },
+  count: 3
+)
+
+rugl.frame do |ctx|
+  rugl.clear(color: [0.0, 0.0, 0.0, 1.0], depth: 1.0)
+
+  t = ctx[:time]
+  draw_triangle.call(
+    color: [Math.cos(t), Math.sin(t * 0.8), Math.cos(t * 0.3), 1.0]
+  )
+end
+```
+
+## Core Concepts
+
+### Context
+
+`Rugl.create(**opts)` returns a `Rugl::Context`.
+
+Important context options:
+
+- `width:`, `height:`, `title:` control the default GLFW window
+- `version:` defaults to `[4, 1]`
+- `profile:` defaults to `:core`
+- `samples:` enables multisample hints when GLFW is available
+- `debug:` enables shader/program/GL error checks
+- `gl:`, `glfw:`, and `window:` let you inject your own backends
+- `auto_init: false` disables default backend/window setup
+
+Useful context methods:
+
+- `rugl.command(opts)` compiles a command
+- `rugl.frame(max_frames: nil) { |ctx| ... }` runs the frame loop
+- `rugl.clear(color: nil, depth: nil, stencil: nil)` clears active buffers
+- `rugl.read(x: 0, y: 0, width: nil, height: nil)` reads RGBA pixels into a binary string
+- `rugl.limits` queries a few common GL limits
+- `rugl.has_extension?("GL_EXT_name")` checks extension support
+- `rugl.destroy` destroys the window/context and warns about leaked resources
+
+If no window is present, `frame` runs a single iteration by default. That makes `auto_init: false` useful for tests and offscreen/headless flows.
+
+### Commands
+
+Commands are compiled once and executed many times:
+
+```ruby
+draw = rugl.command(
+  vert: "...",
+  frag: "...",
+  attributes: { position: rugl.buffer([...]) },
+  uniforms: { color: Rugl.prop(:color) },
+  count: 3,
+  primitive: :triangles,
+  depth: { enable: true },
+  blend: { enable: true }
+)
+
+draw.call(color: [1, 0, 0, 1])
+draw.call([{ color: [1, 0, 0, 1] }, { color: [0, 1, 0, 1] }])
+```
+
+Supported top-level command keys:
+
+- shaders: `:vert`, `:frag`
+- draw inputs: `:attributes`, `:uniforms`, `:elements`
+- draw params: `:count`, `:primitive`, `:offset`, `:instances`
+- targets: `:framebuffer`
+- state: `:depth`, `:blend`, `:stencil`, `:scissor`, `:cull`, `:polygon_offset`, `:color_mask`, `:front_face`, `:line_width`, `:dither`, `:sample`, `:viewport`
+
+Programs are cached per context by identical vertex/fragment shader source pairs.
+
+### Dynamic Values
+
+Rugl resolves dynamic values at draw time:
+
+```ruby
+Rugl.prop(:color)       # runtime props passed to command.call
+Rugl.context(:time)     # per-frame context from rugl.frame
+Rugl.this(:model)       # current scoped/merged props
+-> { 1.0 }              # arity 0
+->(ctx) { ctx[:tick] }  # arity 1
+->(ctx, props) { ... }  # arity 2+
+```
+
+Dynamic markers can be used in uniforms, attributes, draw params, framebuffer targets, and state blocks.
+
+### Scoped Execution
+
+Passing a block to `command.call` turns the command into a scope. The command applies its state and props, then child commands inherit those merged props through `Rugl.this(...)` and normal prop lookup.
+
+```ruby
+scope.call(color: [1, 0.5, 0.2, 1]) do
+  child.call
+end
+```
+
+## Resources
+
+### Buffers
+
+```ruby
+positions = rugl.buffer([[-1, -1], [1, -1], [0, 1]])
+dynamic = rugl.buffer(data: [0, 1, 2, 3], usage: :dynamic, type: :float)
+empty = rugl.buffer(byte_length: 4096, usage: :stream)
+```
+
+`buffer` accepts either raw array data, an integer byte size, or a hash with `data:`, `byte_length:`, `usage:`, and `type:`.
+
+### Element Buffers
+
+```ruby
+indices = rugl.elements(data: [0, 1, 2], type: :uint16, primitive: :triangles)
+```
+
+`elements` accepts raw index data or a hash with `data:`, `usage:`, `type:`, and `primitive:`.
+
+### Textures
+
+```ruby
+texture = rugl.texture(
+  width: 256,
+  height: 256,
+  data: Array.new(256 * 256 * 4, 255),
+  min_filter: :linear,
+  mag_filter: :linear,
+  wrap_s: :clamp_to_edge,
+  wrap_t: :clamp_to_edge,
+  mipmap: true
+)
+```
+
+Current texture support is intentionally small:
+
+- `Texture` expects a hash source with `width:` and `height:`
+- pixel data can be raw binary or array-like numeric data
+- `format:` currently supports `:rgba`
+- loading image files by path is not built in
+
+### Renderbuffers and Framebuffers
+
+```ruby
+depth = rugl.renderbuffer(width: 512, height: 512, format: :depth_component24)
+
+fbo = rugl.framebuffer(
+  width: 512,
+  height: 512,
+  color: true,
+  depth: depth
+)
+```
+
+Framebuffer defaults:
+
+- `color: true` creates and owns an RGBA texture attachment
+- `depth: true` creates and owns a depth renderbuffer
+- `stencil:` defaults to `false`
+- `depth_stencil:` can be used instead of separate depth/stencil attachments
+
+Framebuffer instances expose `color_attachment`, `depth_attachment`, `stencil_attachment`, `depth_stencil_attachment`, `use`, `bind`, `unbind`, `resize`, and `destroy`.
+
+## Headless And Injected Backends
+
+You can skip GLFW/window creation and inject your own GL backend:
+
+```ruby
+require "rugl"
+
+gl = MyOpenGLBackend
+rugl = Rugl.create(gl: gl, auto_init: false, width: 256, height: 256)
+
+draw = rugl.command(
+  vert: "...",
+  frag: "...",
+  count: 0
+)
+
+rugl.frame(max_frames: 1) do
+  draw.call
+end
+
+pixels = rugl.read(width: 256, height: 256)
+```
+
+This is also how most of the test suite exercises the library: with a fake GL backend rather than a real window.
+
+## Examples
+
+Examples assume `glfw` is installed and available.
+
+```bash
+bundle exec ruby examples/triangle.rb
+bundle exec ruby examples/batch.rb
+bundle exec ruby examples/framebuffer.rb
+bundle exec ruby examples/scope.rb
+```
+
+- `examples/triangle.rb`: minimal animated triangle
+- `examples/batch.rb`: batched draws with per-instance props
+- `examples/framebuffer.rb`: offscreen render target and texture feedback
+- `examples/scope.rb`: scoped props/state inheritance
+
+## Development
+
+```bash
+bundle install
+bundle exec rake      # default task: spec_unit (`--tag ~gl`)
+bundle exec rake spec # full suite
+```
+
+The specs are mostly built around fake GL backends, so they are fast to run without a real OpenGL window.
+
+## License
+
+MIT License.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+RSpec::Core::RakeTask.new(:spec_unit) do |task|
+  task.rspec_opts = "--tag ~gl"
+end
+
+task default: :spec_unit

data/examples/batch.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "example_helper"
+
+rugl = Rugl.create(width: 960, height: 640, title: "Rugl Batch")
+
+draw_triangle = rugl.command(
+  vert: <<~GLSL,
+    #version 410 core
+    layout(location = 0) in vec2 position;
+    uniform vec2 offset;
+    void main() {
+      gl_Position = vec4(position * 0.08 + offset, 0.0, 1.0);
+    }
+  GLSL
+  frag: <<~GLSL,
+    #version 410 core
+    uniform vec4 color;
+    out vec4 fragColor;
+    void main() {
+      fragColor = color;
+    }
+  GLSL
+  attributes: {
+    position: rugl.buffer([[-1, -1], [1, -1], [0, 1]])
+  },
+  uniforms: {
+    color: Rugl.prop(:color),
+    offset: Rugl.prop(:offset)
+  },
+  count: 3,
+  blend: {
+    enable: true,
+    func: { src: :src_alpha, dst: :one_minus_src_alpha }
+  }
+)
+
+grid_size = 10
+cells = grid_size * grid_size
+
+rugl.frame do |ctx|
+  rugl.clear(color: [0.06, 0.08, 0.12, 1.0], depth: 1.0)
+  t = ctx[:time]
+
+  props = Array.new(cells) do |i|
+    x = i % grid_size
+    y = i / grid_size
+    nx = (x.to_f / (grid_size - 1)) * 2.0 - 1.0
+    ny = (y.to_f / (grid_size - 1)) * 2.0 - 1.0
+
+    {
+      offset: [nx, ny],
+      color: [
+        0.5 + 0.5 * Math.cos(t + x * 0.4),
+        0.5 + 0.5 * Math.sin(t * 0.8 + y * 0.5),
+        0.5 + 0.5 * Math.cos(t * 0.6 + i * 0.1),
+        0.85
+      ]
+    }
+  end
+
+  draw_triangle.call(props)
+end

data/examples/example_helper.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+lib_path = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib_path) unless $LOAD_PATH.include?(lib_path)
+
+require "rugl"

data/examples/framebuffer.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "example_helper"
+
+rugl = Rugl.create(width: 800, height: 600, title: "Rugl Framebuffer")
+offscreen = rugl.framebuffer(width: 512, height: 512)
+
+draw_scene = rugl.command(
+  vert: <<~GLSL,
+    #version 410 core
+    layout(location = 0) in vec2 position;
+    uniform float time;
+    void main() {
+      float a = time;
+      mat2 r = mat2(cos(a), -sin(a), sin(a), cos(a));
+      vec2 p = r * position;
+      gl_Position = vec4(p, 0.0, 1.0);
+    }
+  GLSL
+  frag: <<~GLSL,
+    #version 410 core
+    out vec4 fragColor;
+    void main() {
+      fragColor = vec4(0.2, 0.8, 0.5, 1.0);
+    }
+  GLSL
+  attributes: {
+    position: rugl.buffer([[-0.7, -0.6], [0.7, -0.6], [0.0, 0.8]])
+  },
+  uniforms: {
+    time: Rugl.context(:time)
+  },
+  count: 3,
+  framebuffer: offscreen
+)
+
+draw_quad = rugl.command(
+  vert: <<~GLSL,
+    #version 410 core
+    layout(location = 0) in vec2 position;
+    layout(location = 1) in vec2 uv;
+    out vec2 vUv;
+    void main() {
+      vUv = uv;
+      gl_Position = vec4(position, 0.0, 1.0);
+    }
+  GLSL
+  frag: <<~GLSL,
+    #version 410 core
+    in vec2 vUv;
+    uniform sampler2D tex;
+    out vec4 fragColor;
+    void main() {
+      fragColor = texture(tex, vUv);
+    }
+  GLSL
+  attributes: {
+    position: rugl.buffer([[-1, -1], [1, -1], [1, 1], [-1, 1]]),
+    uv: rugl.buffer([[0, 0], [1, 0], [1, 1], [0, 1]])
+  },
+  uniforms: {
+    tex: offscreen.color_attachment
+  },
+  primitive: :triangle_fan,
+  count: 4
+)
+
+rugl.frame do
+  offscreen.use do
+    rugl.clear(color: [0.0, 0.0, 0.0, 1.0], depth: 1.0)
+    draw_scene.call
+  end
+
+  rugl.clear(color: [0.03, 0.03, 0.05, 1.0], depth: 1.0)
+  draw_quad.call
+end

data/examples/scope.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "example_helper"
+
+rugl = Rugl.create(width: 800, height: 600, title: "Rugl Scope")
+
+draw_triangle = rugl.command(
+  vert: <<~GLSL,
+    #version 410 core
+    layout(location = 0) in vec2 position;
+    uniform vec2 offset;
+    void main() {
+      gl_Position = vec4(position + offset, 0.0, 1.0);
+    }
+  GLSL
+  frag: <<~GLSL,
+    #version 410 core
+    uniform vec4 color;
+    out vec4 fragColor;
+    void main() {
+      fragColor = color;
+    }
+  GLSL
+  attributes: {
+    position: rugl.buffer([[-0.2, -0.2], [0.2, -0.2], [0.0, 0.2]])
+  },
+  uniforms: {
+    offset: Rugl.prop(:offset),
+    color: Rugl.prop(:color)
+  },
+  count: 3
+)
+
+scope = rugl.command(
+  vert: <<~GLSL,
+    #version 410 core
+    void main() {
+      gl_Position = vec4(0.0);
+    }
+  GLSL
+  frag: <<~GLSL,
+    #version 410 core
+    uniform vec4 color;
+    out vec4 fragColor;
+    void main() {
+      fragColor = color;
+    }
+  GLSL
+  uniforms: {
+    color: Rugl.prop(:color)
+  },
+  count: 0,
+  viewport: { x: 0, y: 0, width: Rugl.context(:viewport_width), height: Rugl.context(:viewport_height) },
+  depth: { enable: false }
+)
+
+rugl.frame do |ctx|
+  rugl.clear(color: [0.08, 0.08, 0.1, 1.0], depth: 1.0)
+  t = ctx[:time]
+
+  scope.call(color: [0.95, 0.6, 0.2, 1.0]) do
+    draw_triangle.call(offset: [Math.cos(t) * 0.35, 0.0], color: [0.9, 0.2, 0.3, 1.0])
+    draw_triangle.call(offset: [0.0, Math.sin(t * 1.3) * 0.35], color: [0.2, 0.8, 0.9, 1.0])
+  end
+end

data/examples/triangle.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "example_helper"
+
+rugl = Rugl.create(width: 800, height: 600, title: "Rugl Triangle")
+
+draw_triangle = rugl.command(
+  vert: <<~GLSL,
+    #version 410 core
+    layout(location = 0) in vec2 position;
+    void main() {
+      gl_Position = vec4(position, 0.0, 1.0);
+    }
+  GLSL
+  frag: <<~GLSL,
+    #version 410 core
+    uniform vec4 color;
+    out vec4 fragColor;
+    void main() {
+      fragColor = color;
+    }
+  GLSL
+  attributes: {
+    position: rugl.buffer([[-2, -2], [4, -2], [4, 4]])
+  },
+  uniforms: {
+    color: Rugl.prop(:color)
+  },
+  count: 3
+)
+
+rugl.frame do |ctx|
+  rugl.clear(color: [0.0, 0.0, 0.0, 1.0], depth: 1.0)
+  t = ctx[:time]
+  draw_triangle.call(color: [Math.cos(t), Math.sin(t * 0.8), Math.cos(t * 0.3), 1.0])
+end