webxr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cd0e42685794b12081b40602d78cfb5edf0ff103f259972bcf2a61354e9ce239
+  data.tar.gz: 28c6fe4cca40ea53a9ad9441e8b14ac197aa82f570882cfd728940ebddc9b6cc
+SHA512:
+  metadata.gz: b0e714b7fdcccfa04bbded4421483ca981cbe59b23f784adb3c03ec1f3eee92e18b829f984b4e9076d8b66c7797d6aeb7cfbacd63d6576f89e4047a9a381791b
+  data.tar.gz: 27dc069631dbe704579dd6b664388bf8154d588cc136eca63a127a389572e9c72225f4dfaceb504e4868ab885b48322acd7ed7f8f8208e58f982f5a41cc58dec

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 - 2026-01-03
+
+- Initial release.

data/README.md

@@ -0,0 +1,138 @@
+# WebXR Ruby
+
+[![CI](https://github.com/ydah/webxr-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/ydah/webxr-ruby/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/webxr.svg)](https://badge.fury.io/rb/webxr)
+
+WebXR Device API bindings for Ruby. Build VR/AR applications in Ruby using [ruby.wasm](https://github.com/ruby/ruby.wasm).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "webxr"
+```
+
+Or install it directly:
+
+```bash
+gem install webxr
+```
+
+## Requirements
+
+- Ruby 3.2+
+- [ruby.wasm](https://github.com/ruby/ruby.wasm) runtime (for browser execution)
+- WebXR-compatible browser (Chrome, Edge, Firefox, etc.)
+
+## Usage
+
+### Basic VR Session
+
+```ruby
+require "webxr"
+
+# Check WebXR availability
+if WebXR::System.available?
+  system = WebXR::System.instance
+
+  # Check VR support
+  if system.session_supported?("immersive-vr")
+    # Request VR session
+    session = system.request_session("immersive-vr")
+
+    # Get reference space
+    space = session.request_reference_space("local-floor")
+
+    # Animation loop
+    session.request_animation_frame do |time, frame|
+      pose = frame.viewer_pose(space)
+      # Render your scene using pose.views
+    end
+  end
+end
+```
+
+### Using Helpers
+
+```ruby
+require "webxr"
+
+# SessionManager for simplified session handling
+manager = WebXR::Helpers::SessionManager.new
+
+manager.start_vr do |session, space|
+  # Automatically handles setup and cleanup
+  session.request_animation_frame do |time, frame|
+    # Your render loop
+  end
+end
+```
+
+### Input Handling
+
+```ruby
+# Access controllers
+session.input_sources.each do |source|
+  puts "Controller: #{source.handedness}"  # "left", "right", "none"
+
+  if source.gamepad
+    source.gamepad.buttons.each_with_index do |button, i|
+      puts "Button #{i} pressed" if button.pressed?
+    end
+  end
+end
+
+# Input events
+session.on(:select) do |event|
+  source = event.input_source
+  puts "Select from #{source.handedness} controller"
+end
+```
+
+### AR with Hit Testing
+
+```ruby
+session = system.request_session("immersive-ar", required_features: ["hit-test"])
+space = session.request_reference_space("local")
+viewer_space = session.request_reference_space("viewer")
+
+hit_test_source = session.request_hit_test_source(space: viewer_space)
+
+session.request_animation_frame do |time, frame|
+  results = frame.get_hit_test_results(hit_test_source)
+
+  results.each do |result|
+    pose = result.get_pose(space)
+    # Place objects at hit position
+  end
+end
+```
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rake spec
+
+# Generate documentation
+bundle exec rake doc
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/webxr-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Resources
+
+- [WebXR Device API Specification](https://www.w3.org/TR/webxr/)
+- [MDN WebXR Documentation](https://developer.mozilla.org/en-US/docs/Web/API/WebXR_Device_API)
+- [ruby.wasm](https://github.com/ruby/ruby.wasm)
+- [Immersive Web Emulator](https://github.com/nickolinko/webxr-emulator-extension) - Browser extension for testing

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+desc "Generate YARD documentation"
+task :doc do
+  sh "bundle exec yard doc"
+end
+
+desc "Open YARD documentation server"
+task :doc_server do
+  sh "bundle exec yard server --reload"
+end
+
+desc "Run all checks"
+task check: :spec

data/examples/ar_demo.html

@@ -0,0 +1,238 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>WebXR Ruby - AR Hit Test Demo</title>
+  <style>
+    body {
+      margin: 0;
+      background: #1a1a2e;
+      color: white;
+      font-family: system-ui, sans-serif;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      min-height: 100vh;
+    }
+    h1 { color: #e94560; }
+    #xr-canvas {
+      width: 100%;
+      height: 100%;
+      position: absolute;
+      top: 0;
+      left: 0;
+      display: none;
+    }
+    .container {
+      text-align: center;
+      padding: 2rem;
+    }
+    button {
+      background: #e94560;
+      color: white;
+      border: none;
+      padding: 1rem 2rem;
+      font-size: 1.2rem;
+      border-radius: 8px;
+      cursor: pointer;
+      margin: 0.5rem;
+      transition: background 0.3s;
+    }
+    button:hover { background: #ff6b6b; }
+    button:disabled {
+      background: #444;
+      cursor: not-allowed;
+    }
+    #status {
+      margin-top: 1rem;
+      padding: 1rem;
+      background: rgba(255,255,255,0.1);
+      border-radius: 8px;
+    }
+    #log {
+      margin-top: 1rem;
+      padding: 1rem;
+      background: #0f0f23;
+      border-radius: 8px;
+      text-align: left;
+      max-height: 300px;
+      overflow-y: auto;
+      font-family: monospace;
+      font-size: 0.85rem;
+      width: 80%;
+      max-width: 600px;
+    }
+    .log-entry { margin: 0.25rem 0; }
+    .log-info { color: #4ecdc4; }
+    .log-warn { color: #ffe66d; }
+    .log-error { color: #ff6b6b; }
+  </style>
+</head>
+<body>
+  <canvas id="xr-canvas"></canvas>
+
+  <div class="container" id="ui">
+    <h1>WebXR Ruby - AR Demo</h1>
+    <p>AR Hit Test and Anchor Placement</p>
+
+    <div id="status">Checking WebXR support...</div>
+
+    <div id="buttons" style="display: none;">
+      <button id="ar-btn" disabled>Start AR Session</button>
+    </div>
+
+    <div id="log"></div>
+  </div>
+
+  <script type="module">
+    const statusDiv = document.getElementById("status");
+    const buttonsDiv = document.getElementById("buttons");
+    const arBtn = document.getElementById("ar-btn");
+    const logDiv = document.getElementById("log");
+
+    function log(message, type = "info") {
+      const entry = document.createElement("div");
+      entry.className = `log-entry log-${type}`;
+      const time = new Date().toLocaleTimeString();
+      entry.textContent = `[${time}] ${message}`;
+      logDiv.appendChild(entry);
+      logDiv.scrollTop = logDiv.scrollHeight;
+      console.log(message);
+    }
+
+    async function main() {
+      try {
+        log("Initializing AR demo...");
+
+        buttonsDiv.style.display = "block";
+
+        // Check WebXR availability
+        if (!navigator.xr) {
+          statusDiv.textContent = "WebXR is not supported in this browser";
+          log("WebXR not available", "error");
+          return;
+        }
+
+        log("WebXR API detected");
+
+        // Check AR support
+        const arSupported = await navigator.xr.isSessionSupported("immersive-ar");
+        if (arSupported) {
+          arBtn.disabled = false;
+          log("Immersive AR supported");
+          statusDiv.textContent = "AR is supported! Click the button to start.";
+        } else {
+          log("Immersive AR not supported on this device", "warn");
+          statusDiv.textContent = "AR is not supported on this device";
+        }
+
+        // AR button handler
+        arBtn.addEventListener("click", async () => {
+          try {
+            log("Requesting AR session...");
+            arBtn.disabled = true;
+
+            const session = await navigator.xr.requestSession("immersive-ar", {
+              requiredFeatures: ["local", "hit-test"]
+            });
+
+            log(`AR session started: ${session.mode}`);
+            statusDiv.textContent = "AR session active - tap surfaces to place objects";
+
+            // Get reference spaces
+            const localSpace = await session.requestReferenceSpace("local");
+            const viewerSpace = await session.requestReferenceSpace("viewer");
+
+            log("Reference spaces acquired");
+
+            // Request hit test source
+            const hitTestSource = await session.requestHitTestSource({ space: viewerSpace });
+            log("Hit test source created");
+
+            // Setup WebGL
+            const canvas = document.getElementById("xr-canvas");
+            canvas.style.display = "block";
+            const gl = canvas.getContext("webgl2", { xrCompatible: true });
+
+            const layer = new XRWebGLLayer(session, gl, { alpha: true });
+            session.updateRenderState({ baseLayer: layer });
+
+            log(`Framebuffer: ${layer.framebufferWidth}x${layer.framebufferHeight}`);
+
+            // Track anchors
+            const anchors = [];
+
+            // Handle select events
+            session.addEventListener("select", async (event) => {
+              const frame = event.frame;
+              const results = frame.getHitTestResults(hitTestSource);
+
+              if (results.length > 0) {
+                const hit = results[0];
+                const pose = hit.getPose(localSpace);
+
+                if (pose) {
+                  const pos = pose.transform.position;
+                  log(`Tap at: (${pos.x.toFixed(3)}, ${pos.y.toFixed(3)}, ${pos.z.toFixed(3)})`);
+
+                  try {
+                    const anchor = await hit.createAnchor();
+                    anchors.push(anchor);
+                    log(`Created anchor #${anchors.length}`, "info");
+                  } catch (e) {
+                    log(`Failed to create anchor: ${e.message}`, "error");
+                  }
+                }
+              }
+            });
+
+            // Render loop
+            let frameCount = 0;
+            session.requestAnimationFrame(function onFrame(time, frame) {
+              session.requestAnimationFrame(onFrame);
+              frameCount++;
+
+              const pose = frame.getViewerPose(localSpace);
+              if (!pose) return;
+
+              gl.bindFramebuffer(gl.FRAMEBUFFER, layer.framebuffer);
+              gl.clearColor(0, 0, 0, 0);
+              gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+
+              // Render views
+              for (const view of pose.views) {
+                const viewport = layer.getViewport(view);
+                gl.viewport(viewport.x, viewport.y, viewport.width, viewport.height);
+              }
+            });
+
+            // Handle session end
+            session.addEventListener("end", () => {
+              log(`Session ended. Total anchors: ${anchors.length}`);
+              statusDiv.textContent = "AR session ended";
+              canvas.style.display = "none";
+              arBtn.disabled = false;
+
+              // Clean up
+              hitTestSource.cancel();
+              anchors.forEach(a => a.delete());
+            });
+
+          } catch (e) {
+            log(`Error: ${e.message}`, "error");
+            arBtn.disabled = false;
+          }
+        });
+
+      } catch (e) {
+        statusDiv.textContent = `Error: ${e.message}`;
+        log(`Initialization error: ${e.message}`, "error");
+      }
+    }
+
+    main();
+  </script>
+</body>
+</html>

data/examples/ar_hit_test.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+# AR Hit Test Example
+# This example demonstrates how to use AR hit testing in WebXR Ruby.
+#
+# IMPORTANT: This code runs ONLY in a browser via ruby.wasm.
+# It cannot be executed with standard Ruby (e.g., `ruby examples/ar_hit_test.rb`).
+#
+# To run this example:
+# 1. Use the ar_demo.html file which loads ruby.wasm
+# 2. Or embed this code in an HTML page with ruby.wasm runtime
+#
+# Prerequisites:
+# - A WebXR-compatible browser with AR support
+# - A device with AR capabilities (e.g., smartphone with ARCore/ARKit)
+# - ruby.wasm runtime loaded in the browser
+
+require "webxr"
+
+# Check WebXR availability
+unless WebXR.available?
+  puts "WebXR is not available"
+  exit
+end
+
+xr = WebXR.system
+
+# Check AR support
+unless xr.session_supported?(WebXR::SessionMode::IMMERSIVE_AR)
+  puts "AR is not supported"
+  exit
+end
+
+# Get WebGL context
+canvas = JS.global[:document].call(:getElementById, "xr-canvas")
+gl = canvas.call(:getContext, "webgl2", JS.eval("{ xrCompatible: true }"))
+
+# Request AR session with hit testing
+session = xr.request_session(
+  WebXR::SessionMode::IMMERSIVE_AR,
+  required_features: ["local", "hit-test"],
+  optional_features: ["dom-overlay", "light-estimation"]
+)
+
+puts "AR Session started"
+puts "Enabled features: #{session.enabled_features.join(', ')}"
+puts "Environment blend mode: #{session.environment_blend_mode}"
+
+# Get reference space
+reference_space = session.request_reference_space(WebXR::ReferenceSpaceType::LOCAL)
+viewer_space = session.request_reference_space(WebXR::ReferenceSpaceType::VIEWER)
+
+# Create WebGL layer
+layer = WebXR::WebGLLayer.new(session, gl, alpha: true)
+session.update_render_state(base_layer: layer)
+
+# Request hit test source
+# This will test rays cast from the viewer (screen center)
+hit_test_source = nil
+
+# In a real implementation, you would use the session's requestHitTestSource method
+# hit_test_promise = session.js.call(:requestHitTestSource, JS.eval("{ space: viewerSpace.js }"))
+# hit_test_source = WebXR::AR::HitTestSource.new(JS.await(hit_test_promise))
+
+# Store placed anchors
+anchors = []
+
+# Handle select events to place anchors
+session.on(:select) do |event|
+  frame = event.frame
+  source = event.input_source
+
+  # Get the pose where the user selected
+  pose = event.pose(reference_space)
+  next unless pose
+
+  position = pose.transform.position
+  puts "Select at position: (#{position[:x].round(3)}, #{position[:y].round(3)}, #{position[:z].round(3)})"
+
+  # Create an anchor at this position
+  begin
+    anchor = frame.create_anchor(pose.transform, reference_space)
+    anchors << anchor
+    puts "Created anchor ##{anchors.length}"
+  rescue => e
+    puts "Failed to create anchor: #{e.message}"
+  end
+end
+
+# Rendering loop
+render_frame = proc do |time, js_frame|
+  session.request_animation_frame(&render_frame)
+
+  frame = WebXR::Frame.new(js_frame)
+  pose = frame.viewer_pose(reference_space)
+
+  next unless pose
+
+  # Clear with transparent background for AR
+  gl.call(:bindFramebuffer, gl[:FRAMEBUFFER], layer.framebuffer)
+  gl.call(:clearColor, 0.0, 0.0, 0.0, 0.0)
+  gl.call(:clear, gl[:COLOR_BUFFER_BIT] | gl[:DEPTH_BUFFER_BIT])
+
+  # Process hit test results (if hit test source is available)
+  if hit_test_source
+    results = frame.hit_test_results(hit_test_source)
+
+    if results.any?
+      # Get the first (closest) hit
+      hit = results.first
+      hit_pose = hit.pose(reference_space)
+
+      if hit_pose
+        position = hit_pose.transform.position
+        # Draw a reticle at the hit position
+        # puts "Hit at: (#{position[:x].round(3)}, #{position[:y].round(3)}, #{position[:z].round(3)})"
+      end
+    end
+  end
+
+  # Get tracked anchors and render objects at their positions
+  frame.tracked_anchors.each do |anchor|
+    anchor_pose = frame.pose(anchor.anchor_space, reference_space)
+    next unless anchor_pose
+
+    position = anchor_pose.transform.position
+    # Render your 3D object at this position
+    # In a real app, you would draw a cube, model, etc.
+  end
+
+  # Render each view
+  pose.each_view do |view|
+    viewport = layer.viewport(view)
+    gl.call(:viewport, viewport.x, viewport.y, viewport.width, viewport.height)
+
+    projection = view.projection_matrix
+    view_matrix = view.view_matrix
+
+    # Your 3D rendering code here
+    # Render anchored objects, reticle, etc.
+  end
+end
+
+# Start render loop
+session.request_animation_frame(&render_frame)
+
+# Handle session end
+session.on(:end) do
+  puts "AR Session ended"
+  puts "Total anchors created: #{anchors.length}"
+
+  # Clean up anchors
+  anchors.each(&:delete)
+end
+
+puts "AR hit test demo started"
+puts "Tap on surfaces to place anchors"

data/examples/basic_vr.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Basic VR Session Example
+# This example demonstrates how to create a simple VR session using WebXR Ruby bindings.
+#
+# IMPORTANT: This code runs ONLY in a browser via ruby.wasm.
+# It cannot be executed with standard Ruby (e.g., `ruby examples/basic_vr.rb`).
+#
+# To run this example:
+# 1. Include the ruby.wasm runtime in an HTML page
+# 2. Load this Ruby script using <script type="text/ruby">
+# 3. Use a WebXR-compatible browser and VR headset
+#
+# See hello_webxr.html for a working browser example.
+
+require "webxr"
+
+# Check if WebXR is available
+unless WebXR.available?
+  puts "WebXR is not available in this browser"
+  exit
+end
+
+xr = WebXR.system
+
+# Check VR support
+unless xr.session_supported?(WebXR::SessionMode::IMMERSIVE_VR)
+  puts "Immersive VR is not supported"
+  exit
+end
+
+# Get the WebGL canvas and context
+canvas = JS.global[:document].call(:getElementById, "xr-canvas")
+gl = canvas.call(:getContext, "webgl2", JS.eval("{ xrCompatible: true }"))
+
+# Request VR session
+session = xr.request_session(
+  WebXR::SessionMode::IMMERSIVE_VR,
+  required_features: ["local-floor"],
+  optional_features: ["bounded-floor", "hand-tracking"]
+)
+
+puts "VR Session started: #{session.mode}"
+puts "Enabled features: #{session.enabled_features.join(', ')}"
+
+# Get reference space
+reference_space = session.request_reference_space(WebXR::ReferenceSpaceType::LOCAL_FLOOR)
+
+# Create WebGL layer
+layer = WebXR::WebGLLayer.new(session, gl, antialias: true)
+session.update_render_state(base_layer: layer)
+
+puts "Framebuffer size: #{layer.framebuffer_width}x#{layer.framebuffer_height}"
+
+# Setup event handlers
+session.on(:end) do
+  puts "VR Session ended"
+end
+
+session.on(:select) do |event|
+  puts "Select event from #{event.handedness} controller"
+end
+
+session.on(:inputsourceschange) do |event|
+  puts "Input sources changed"
+  puts "  Added: #{event.added.length}"
+  puts "  Removed: #{event.removed.length}"
+end
+
+# Rendering loop
+render_frame = proc do |time, js_frame|
+  session.request_animation_frame(&render_frame)
+
+  frame = WebXR::Frame.new(js_frame)
+  pose = frame.viewer_pose(reference_space)
+
+  return unless pose
+
+  # Bind XR framebuffer
+  gl.call(:bindFramebuffer, gl[:FRAMEBUFFER], layer.framebuffer)
+  gl.call(:clearColor, 0.1, 0.1, 0.2, 1.0)
+  gl.call(:clear, gl[:COLOR_BUFFER_BIT] | gl[:DEPTH_BUFFER_BIT])
+
+  # Render each view (left and right eye)
+  pose.each_view do |view|
+    viewport = layer.viewport(view)
+    gl.call(:viewport, viewport.x, viewport.y, viewport.width, viewport.height)
+
+    projection_matrix = view.projection_matrix
+    view_matrix = view.view_matrix
+
+    # Your 3D rendering code here
+    # Use projection_matrix and view_matrix for rendering
+  end
+
+  # Process input sources
+  session.input_sources.each do |source|
+    next unless source.gamepad
+
+    # Check trigger state
+    if source.gamepad.trigger&.pressed?
+      puts "#{source.handedness} trigger pressed"
+    end
+  end
+end
+
+# Start the render loop
+session.request_animation_frame(&render_frame)
+
+puts "VR rendering started"