webxr 0.1.0

data/lib/webxr/hand/hand.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module WebXR
+  module Hand
+    # Joint names as defined in WebXR Hand Input specification
+    JOINTS = %w[
+      wrist
+      thumb-metacarpal
+      thumb-phalanx-proximal
+      thumb-phalanx-distal
+      thumb-tip
+      index-finger-metacarpal
+      index-finger-phalanx-proximal
+      index-finger-phalanx-intermediate
+      index-finger-phalanx-distal
+      index-finger-tip
+      middle-finger-metacarpal
+      middle-finger-phalanx-proximal
+      middle-finger-phalanx-intermediate
+      middle-finger-phalanx-distal
+      middle-finger-tip
+      ring-finger-metacarpal
+      ring-finger-phalanx-proximal
+      ring-finger-phalanx-intermediate
+      ring-finger-phalanx-distal
+      ring-finger-tip
+      pinky-finger-metacarpal
+      pinky-finger-phalanx-proximal
+      pinky-finger-phalanx-intermediate
+      pinky-finger-phalanx-distal
+      pinky-finger-tip
+    ].freeze
+
+    # Number of joints in a hand
+    JOINT_COUNT = 25
+
+    # XRHand - Represents a tracked hand with 25 joints
+    class Hand < JSWrapper
+      include Enumerable
+
+      # @param js_hand [JS::Object] The XRHand JavaScript object
+      def initialize(js_hand)
+        super(js_hand)
+      end
+
+      # Get the number of joints
+      # @return [Integer] Always 25 for a complete hand
+      def size
+        js_int(:size) || JOINT_COUNT
+      end
+      alias length size
+
+      # Get a joint space by name or index
+      # @param key [String, Integer] Joint name or index
+      # @return [JointSpace, nil]
+      def [](key)
+        js_joint = case key
+                   when Integer
+                     joint_name = JOINTS[key]
+                     return nil unless joint_name
+
+                     js_call(:get, joint_name)
+                   when String, Symbol
+                     js_call(:get, key.to_s)
+                   end
+
+        return nil if js_joint.nil?
+
+        JointSpace.new(js_joint)
+      end
+
+      # Get a joint space by name
+      # @param name [String] The joint name
+      # @return [JointSpace, nil]
+      def get(name)
+        js_joint = js_call(:get, name)
+        return nil if js_joint.nil?
+
+        JointSpace.new(js_joint)
+      end
+
+      # Iterate over all joint spaces
+      # @yield [String, JointSpace] Joint name and joint space
+      # @return [Enumerator, void]
+      def each(&block)
+        return enum_for(:each) unless block_given?
+
+        JOINTS.each do |name|
+          joint = get(name)
+          yield name, joint if joint
+        end
+      end
+
+      # Get all joint spaces as an array
+      # @return [Array<JointSpace>]
+      def to_a
+        JOINTS.map { |name| get(name) }.compact
+      end
+
+      # Get the wrist joint
+      # @return [JointSpace, nil]
+      def wrist
+        get("wrist")
+      end
+
+      # Get thumb joints
+      # @return [Array<JointSpace>]
+      def thumb
+        %w[thumb-metacarpal thumb-phalanx-proximal thumb-phalanx-distal thumb-tip].map { |n| get(n) }.compact
+      end
+
+      # Get the thumb tip
+      # @return [JointSpace, nil]
+      def thumb_tip
+        get("thumb-tip")
+      end
+
+      # Get index finger joints
+      # @return [Array<JointSpace>]
+      def index_finger
+        %w[
+          index-finger-metacarpal
+          index-finger-phalanx-proximal
+          index-finger-phalanx-intermediate
+          index-finger-phalanx-distal
+          index-finger-tip
+        ].map { |n| get(n) }.compact
+      end
+
+      # Get the index finger tip
+      # @return [JointSpace, nil]
+      def index_finger_tip
+        get("index-finger-tip")
+      end
+
+      # Get middle finger joints
+      # @return [Array<JointSpace>]
+      def middle_finger
+        %w[
+          middle-finger-metacarpal
+          middle-finger-phalanx-proximal
+          middle-finger-phalanx-intermediate
+          middle-finger-phalanx-distal
+          middle-finger-tip
+        ].map { |n| get(n) }.compact
+      end
+
+      # Get the middle finger tip
+      # @return [JointSpace, nil]
+      def middle_finger_tip
+        get("middle-finger-tip")
+      end
+
+      # Get ring finger joints
+      # @return [Array<JointSpace>]
+      def ring_finger
+        %w[
+          ring-finger-metacarpal
+          ring-finger-phalanx-proximal
+          ring-finger-phalanx-intermediate
+          ring-finger-phalanx-distal
+          ring-finger-tip
+        ].map { |n| get(n) }.compact
+      end
+
+      # Get the ring finger tip
+      # @return [JointSpace, nil]
+      def ring_finger_tip
+        get("ring-finger-tip")
+      end
+
+      # Get pinky finger joints
+      # @return [Array<JointSpace>]
+      def pinky_finger
+        %w[
+          pinky-finger-metacarpal
+          pinky-finger-phalanx-proximal
+          pinky-finger-phalanx-intermediate
+          pinky-finger-phalanx-distal
+          pinky-finger-tip
+        ].map { |n| get(n) }.compact
+      end
+
+      # Get the pinky finger tip
+      # @return [JointSpace, nil]
+      def pinky_finger_tip
+        get("pinky-finger-tip")
+      end
+
+      # Get all finger tips
+      # @return [Array<JointSpace>]
+      def finger_tips
+        [thumb_tip, index_finger_tip, middle_finger_tip, ring_finger_tip, pinky_finger_tip].compact
+      end
+    end
+  end
+end

data/lib/webxr/hand/joint_pose.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module WebXR
+  module Hand
+    # XRJointPose - Represents the pose of a hand joint
+    # Includes radius information for collision detection
+    class JointPose < Pose
+      # @param js_joint_pose [JS::Object] The XRJointPose JavaScript object
+      def initialize(js_joint_pose)
+        super(js_joint_pose)
+      end
+
+      # Get the radius of the joint in meters
+      # This can be used for collision detection or visualization
+      # @return [Float]
+      def radius
+        js_float(:radius) || 0.0
+      end
+
+      # Get the diameter of the joint in meters
+      # @return [Float]
+      def diameter
+        radius * 2
+      end
+
+      # Check if the joint pose is valid (has meaningful data)
+      # @return [Boolean]
+      def valid?
+        radius > 0
+      end
+    end
+  end
+end

data/lib/webxr/hand/joint_space.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module WebXR
+  module Hand
+    # XRJointSpace - Represents a joint's coordinate space
+    # Each joint has its own space that can be used for pose calculations
+    class JointSpace < Space
+      # @param js_joint_space [JS::Object] The XRJointSpace JavaScript object
+      def initialize(js_joint_space)
+        super(js_joint_space)
+      end
+
+      # Get the joint name
+      # @return [String]
+      def joint_name
+        js_string(:jointName) || ""
+      end
+
+      # Get the space type
+      # @return [String]
+      def type
+        "joint-space"
+      end
+
+      # Check if this is a wrist joint
+      # @return [Boolean]
+      def wrist?
+        joint_name == "wrist"
+      end
+
+      # Check if this is a thumb joint
+      # @return [Boolean]
+      def thumb?
+        joint_name.start_with?("thumb")
+      end
+
+      # Check if this is an index finger joint
+      # @return [Boolean]
+      def index_finger?
+        joint_name.start_with?("index-finger")
+      end
+
+      # Check if this is a middle finger joint
+      # @return [Boolean]
+      def middle_finger?
+        joint_name.start_with?("middle-finger")
+      end
+
+      # Check if this is a ring finger joint
+      # @return [Boolean]
+      def ring_finger?
+        joint_name.start_with?("ring-finger")
+      end
+
+      # Check if this is a pinky finger joint
+      # @return [Boolean]
+      def pinky_finger?
+        joint_name.start_with?("pinky-finger")
+      end
+
+      # Check if this is a finger tip
+      # @return [Boolean]
+      def tip?
+        joint_name.end_with?("-tip")
+      end
+
+      # Check if this is a metacarpal joint
+      # @return [Boolean]
+      def metacarpal?
+        joint_name.end_with?("-metacarpal")
+      end
+    end
+  end
+end

data/lib/webxr/helpers/input_helper.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module WebXR
+  module Helpers
+    # InputHelper - Simplifies XR input handling
+    class InputHelper
+      # @return [Session] The XR session
+      attr_reader :session
+
+      # @return [ReferenceSpace] The reference space
+      attr_reader :reference_space
+
+      # @param session [Session] The XR session
+      # @param reference_space [ReferenceSpace] The reference space for pose calculations
+      def initialize(session, reference_space)
+        @session = session
+        @reference_space = reference_space
+        @select_callbacks = []
+        @squeeze_callbacks = []
+      end
+
+      # Register a callback for select events
+      # @yield [InputSource, InputSourceEvent, Pose] Called on select
+      # @return [void]
+      def on_select(&block)
+        return unless block_given?
+
+        @select_callbacks << block
+        setup_select_listener if @select_callbacks.size == 1
+      end
+
+      # Register a callback for squeeze events
+      # @yield [InputSource, InputSourceEvent, Pose] Called on squeeze
+      # @return [void]
+      def on_squeeze(&block)
+        return unless block_given?
+
+        @squeeze_callbacks << block
+        setup_squeeze_listener if @squeeze_callbacks.size == 1
+      end
+
+      # Iterate over each controller (tracked pointers)
+      # @yield [InputSource] Each controller input source
+      # @return [void]
+      def each_controller(&block)
+        @session.input_sources.each do |source|
+          next unless source.tracked_pointer?
+
+          block.call(source)
+        end
+      end
+
+      # Get the left controller
+      # @return [InputSource, nil]
+      def left_controller
+        @session.input_sources.left
+      end
+
+      # Get the right controller
+      # @return [InputSource, nil]
+      def right_controller
+        @session.input_sources.right
+      end
+
+      # Get the primary controller (first available)
+      # @return [InputSource, nil]
+      def primary_controller
+        left_controller || right_controller || @session.input_sources.first
+      end
+
+      # Get the pose of an input source
+      # @param source [InputSource] The input source
+      # @param frame [Frame] The current frame
+      # @return [Pose, nil]
+      def pose_for(source, frame)
+        frame.pose(source.target_ray_space, @reference_space)
+      end
+
+      # Get the grip pose of an input source
+      # @param source [InputSource] The input source
+      # @param frame [Frame] The current frame
+      # @return [Pose, nil]
+      def grip_pose_for(source, frame)
+        grip = source.grip_space
+        return nil if grip.nil?
+
+        frame.pose(grip, @reference_space)
+      end
+
+      # Get button state for a controller
+      # @param source [InputSource] The input source
+      # @return [Hash] Hash with button states
+      def button_states(source)
+        gamepad = source.gamepad
+        return {} if gamepad.nil?
+
+        {
+          trigger: {
+            pressed: gamepad.trigger&.pressed?,
+            touched: gamepad.trigger&.touched?,
+            value: gamepad.trigger&.value || 0.0
+          },
+          squeeze: {
+            pressed: gamepad.squeeze&.pressed?,
+            touched: gamepad.squeeze&.touched?,
+            value: gamepad.squeeze&.value || 0.0
+          },
+          thumbstick: {
+            x: gamepad.thumbstick_x,
+            y: gamepad.thumbstick_y,
+            pressed: gamepad.thumbstick&.pressed?,
+            touched: gamepad.thumbstick&.touched?
+          },
+          touchpad: {
+            x: gamepad.touchpad_x,
+            y: gamepad.touchpad_y,
+            pressed: gamepad.touchpad&.pressed?,
+            touched: gamepad.touchpad&.touched?
+          }
+        }
+      end
+
+      private
+
+      def setup_select_listener
+        @session.on(:select) do |event|
+          source = event.input_source
+          pose = event.pose(@reference_space)
+          @select_callbacks.each { |cb| cb.call(source, event, pose) }
+        end
+      end
+
+      def setup_squeeze_listener
+        @session.on(:squeeze) do |event|
+          source = event.input_source
+          pose = event.pose(@reference_space)
+          @squeeze_callbacks.each { |cb| cb.call(source, event, pose) }
+        end
+      end
+    end
+  end
+end

data/lib/webxr/helpers/rendering_helper.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module WebXR
+  module Helpers
+    # RenderingHelper - Simplifies WebXR rendering setup and loop
+    class RenderingHelper
+      # @return [WebGLLayer, nil] The WebGL layer
+      attr_reader :layer
+
+      # @return [Session] The XR session
+      attr_reader :session
+
+      # @return [ReferenceSpace] The reference space
+      attr_reader :reference_space
+
+      # @param session [Session] The XR session
+      # @param gl_context [JS::Object] The WebGL rendering context
+      # @param reference_space [ReferenceSpace] The reference space
+      def initialize(session, gl_context, reference_space)
+        @session = session
+        @gl = gl_context
+        @reference_space = reference_space
+        @layer = nil
+        @running = false
+      end
+
+      # Setup the WebGL layer
+      # @param options [Hash] Layer options
+      # @return [WebGLLayer]
+      def setup_layer(**options)
+        @layer = WebGLLayer.new(@session, @gl, **options)
+        @session.update_render_state(base_layer: @layer)
+        @layer
+      end
+
+      # Run the rendering frame loop
+      # @yield [Float, Frame, View, Viewport] Called for each view each frame
+      # @return [void]
+      def run_frame_loop(&render_callback)
+        @running = true
+
+        frame_callback = proc do |time, js_frame|
+          next unless @running && !@session.ended?
+
+          # Request next frame
+          @session.request_animation_frame(&frame_callback)
+
+          # Wrap the frame
+          frame = Frame.new(js_frame)
+
+          # Get viewer pose
+          pose = frame.viewer_pose(@reference_space)
+          next unless pose
+
+          # Bind framebuffer
+          @gl.call(:bindFramebuffer, @gl[:FRAMEBUFFER], @layer.framebuffer)
+
+          # Render each view
+          pose.views.each do |view|
+            viewport = @layer.viewport(view)
+            @gl.call(:viewport, viewport.x, viewport.y, viewport.width, viewport.height)
+
+            render_callback.call(time.to_f, frame, view, viewport)
+          end
+        end
+
+        @session.request_animation_frame(&frame_callback)
+      end
+
+      # Stop the rendering loop
+      # @return [void]
+      def stop
+        @running = false
+      end
+
+      # Check if the rendering loop is running
+      # @return [Boolean]
+      def running?
+        @running
+      end
+
+      # Clear the framebuffer
+      # @param r [Float] Red (0.0 to 1.0)
+      # @param g [Float] Green (0.0 to 1.0)
+      # @param b [Float] Blue (0.0 to 1.0)
+      # @param a [Float] Alpha (0.0 to 1.0)
+      # @return [void]
+      def clear(r: 0.0, g: 0.0, b: 0.0, a: 1.0)
+        @gl.call(:clearColor, r, g, b, a)
+        @gl.call(:clear, @gl[:COLOR_BUFFER_BIT] | @gl[:DEPTH_BUFFER_BIT])
+      end
+    end
+  end
+end

data/lib/webxr/helpers/session_manager.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module WebXR
+  module Helpers
+    # SessionManager - Simplifies XR session lifecycle management
+    class SessionManager
+      # @return [Session, nil] The current session
+      attr_reader :session
+
+      # @return [ReferenceSpace, nil] The current reference space
+      attr_reader :reference_space
+
+      def initialize
+        @session = nil
+        @reference_space = nil
+        @xr_system = System.instance
+      end
+
+      # Check if WebXR is available
+      # @return [Boolean]
+      def available?
+        !@xr_system.nil?
+      end
+
+      # Check if a session mode is supported
+      # @param mode [String] The session mode to check
+      # @return [Boolean]
+      def supports?(mode)
+        return false unless available?
+
+        @xr_system.session_supported?(mode)
+      end
+
+      # Start an XR session
+      # @param mode [String] The session mode ("inline", "immersive-vr", "immersive-ar")
+      # @param reference_space_type [String] The reference space type
+      # @param required_features [Array<String>] Required features
+      # @param optional_features [Array<String>] Optional features
+      # @yield [Session, ReferenceSpace] Optional block for auto-cleanup
+      # @return [Session]
+      def start_session(mode, reference_space_type: ReferenceSpaceType::LOCAL_FLOOR,
+                        required_features: [], optional_features: [])
+        raise NotSupportedError, "WebXR not available" unless available?
+
+        @session = @xr_system.request_session(
+          mode,
+          required_features: required_features,
+          optional_features: optional_features
+        )
+
+        @reference_space = @session.request_reference_space(reference_space_type)
+
+        if block_given?
+          begin
+            yield @session, @reference_space
+          ensure
+            end_session
+          end
+        end
+
+        @session
+      end
+
+      # End the current session
+      # @return [void]
+      def end_session
+        @session&.end_session
+        @session = nil
+        @reference_space = nil
+      end
+
+      # Check if a session is currently active
+      # @return [Boolean]
+      def active?
+        @session && !@session.ended?
+      end
+
+      # Start an immersive VR session
+      # @param options [Hash] Session options
+      # @yield [Session, ReferenceSpace] Optional block
+      # @return [Session]
+      def start_vr(**options, &block)
+        start_session(SessionMode::IMMERSIVE_VR, **options, &block)
+      end
+
+      # Start an immersive AR session
+      # @param options [Hash] Session options
+      # @yield [Session, ReferenceSpace] Optional block
+      # @return [Session]
+      def start_ar(**options, &block)
+        options[:reference_space_type] ||= ReferenceSpaceType::LOCAL
+        start_session(SessionMode::IMMERSIVE_AR, **options, &block)
+      end
+
+      # Start an inline session
+      # @param options [Hash] Session options
+      # @yield [Session, ReferenceSpace] Optional block
+      # @return [Session]
+      def start_inline(**options, &block)
+        options[:reference_space_type] ||= ReferenceSpaceType::VIEWER
+        start_session(SessionMode::INLINE, **options, &block)
+      end
+    end
+  end
+end