webxr 0.1.0

data/lib/webxr/core/system.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module WebXR
+  # XRSystem - Entry point for WebXR API
+  # Accessed via navigator.xr in JavaScript
+  class System < JSWrapper
+    @instance = nil
+
+    class << self
+      # Get the singleton XRSystem instance
+      # @return [System, nil] The XRSystem instance, or nil if WebXR is not available
+      def instance
+        @instance ||= begin
+          js_xr = JS.global[:navigator][:xr]
+          js_xr.nil? ? nil : new(js_xr)
+        end
+      end
+
+      # Check if WebXR is available in the current environment
+      # @return [Boolean]
+      def available?
+        !instance.nil?
+      end
+
+      # Reset the singleton instance (useful for testing)
+      # @api private
+      def reset_instance!
+        @instance = nil
+      end
+    end
+
+    # @param js_xr [JS::Object] The navigator.xr JavaScript object
+    def initialize(js_xr)
+      super(js_xr)
+      @device_change_callbacks = []
+    end
+
+    # Check if a session mode is supported
+    # @param mode [String] The session mode ("inline", "immersive-vr", "immersive-ar")
+    # @return [Boolean]
+    def session_supported?(mode)
+      promise = js_call(:isSessionSupported, mode)
+      result = js_await(promise)
+      !!result
+    end
+
+    # Request a new XR session
+    # @param mode [String] The session mode
+    # @param required_features [Array<String>] Required features for the session
+    # @param optional_features [Array<String>] Optional features for the session
+    # @return [Session] The created XR session
+    # @raise [NotSupportedError] If the session mode is not supported
+    # @raise [NotAllowedError] If the user denies the session request
+    def request_session(mode, required_features: [], optional_features: [])
+      js_options = build_session_options(
+        required_features: required_features,
+        optional_features: optional_features
+      )
+
+      promise = js_call(:requestSession, mode, js_options)
+      js_session = js_await(promise)
+      Session.new(js_session)
+    rescue JS::Error => e
+      handle_js_error(e)
+    end
+
+    # Register a callback for device change events
+    # @yield Called when XR devices are connected or disconnected
+    # @return [void]
+    def on_device_change(&block)
+      return unless block_given?
+
+      @device_change_callbacks << block
+      setup_device_change_listener if @device_change_callbacks.size == 1
+    end
+
+    private
+
+    def build_session_options(required_features:, optional_features:)
+      js_options = JS.eval("({})")
+
+      unless required_features.empty?
+        js_required = to_js_array(required_features)
+        js_options[:requiredFeatures] = js_required
+      end
+
+      unless optional_features.empty?
+        js_optional = to_js_array(optional_features)
+        js_options[:optionalFeatures] = js_optional
+      end
+
+      js_options
+    end
+
+    def setup_device_change_listener
+      callback = ->(event) { dispatch_device_change(event) }
+      js_callback = JS.eval("(function(event) { return $callback.call(event); })")
+      js_call(:addEventListener, "devicechange", js_callback)
+    end
+
+    def dispatch_device_change(event)
+      @device_change_callbacks.each { |cb| cb.call(event) }
+    end
+
+    def handle_js_error(error)
+      message = error.message.to_s
+
+      case message
+      when /NotSupportedError/
+        raise NotSupportedError, message
+      when /SecurityError/
+        raise SecurityError, message
+      when /NotAllowedError/
+        raise NotAllowedError, message
+      when /InvalidStateError/
+        raise InvalidStateError, message
+      else
+        raise Error, message
+      end
+    end
+  end
+end

data/lib/webxr/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module WebXR
+  # Base error class for all WebXR-related errors
+  class Error < StandardError; end
+
+  # Raised when the requested feature is not supported by the browser or device
+  class NotSupportedError < Error; end
+
+  # Raised when a security policy prevents the operation
+  class SecurityError < Error; end
+
+  # Raised when an operation is performed in an invalid state
+  class InvalidStateError < Error; end
+
+  # Raised when the user or system denies the operation
+  class NotAllowedError < Error; end
+end

data/lib/webxr/events/input_source_event.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module WebXR
+  # XRInputSourceEvent - Event for input source actions (select, squeeze)
+  class InputSourceEvent < SessionEvent
+    # Get the input source that triggered this event
+    # @return [InputSource]
+    def input_source
+      InputSource.new(js_prop(:inputSource))
+    end
+
+    # Get the frame at the time of the event
+    # @return [Frame]
+    def frame
+      Frame.new(js_prop(:frame))
+    end
+
+    # Convenience method to get the handedness
+    # @return [String] "none", "left", or "right"
+    def handedness
+      input_source.handedness
+    end
+
+    # Check if this event is from the left controller
+    # @return [Boolean]
+    def left?
+      input_source.left?
+    end
+
+    # Check if this event is from the right controller
+    # @return [Boolean]
+    def right?
+      input_source.right?
+    end
+
+    # Get the pose of the input source at the time of the event
+    # @param reference_space [ReferenceSpace] The reference space
+    # @return [Pose, nil]
+    def pose(reference_space)
+      frame.pose(input_source.target_ray_space, reference_space)
+    end
+
+    # Get the grip pose of the input source at the time of the event
+    # @param reference_space [ReferenceSpace] The reference space
+    # @return [Pose, nil]
+    def grip_pose(reference_space)
+      grip = input_source.grip_space
+      return nil if grip.nil?
+
+      frame.pose(grip, reference_space)
+    end
+  end
+end

data/lib/webxr/events/reference_space_event.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module WebXR
+  # XRReferenceSpaceEvent - Event fired when a reference space is reset
+  class ReferenceSpaceEvent < JSWrapper
+    # @param js_event [JS::Object] The JavaScript event object
+    def initialize(js_event)
+      super(js_event)
+    end
+
+    # Get the event type
+    # @return [String]
+    def type
+      js_string(:type) || ""
+    end
+
+    # Get the reference space that was reset
+    # @return [ReferenceSpace]
+    def reference_space
+      ReferenceSpace.new(js_prop(:referenceSpace))
+    end
+
+    # Get the transform representing the change in origin
+    # @return [RigidTransform, nil]
+    def transform
+      js_transform = js_prop(:transform)
+      return nil if js_transform.nil?
+
+      RigidTransform.new(js_transform)
+    end
+
+    # Get the event timestamp
+    # @return [Float]
+    def time_stamp
+      js_float(:timeStamp) || 0.0
+    end
+
+    # Check if the event is trusted
+    # @return [Boolean]
+    def trusted?
+      js_bool(:isTrusted)
+    end
+  end
+end

data/lib/webxr/events/session_event.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module WebXR
+  # XRSessionEvent - Base event for session-related events
+  class SessionEvent < JSWrapper
+    # @param js_event [JS::Object] The JavaScript event object
+    def initialize(js_event)
+      super(js_event)
+    end
+
+    # Get the event type
+    # @return [String]
+    def type
+      js_string(:type) || ""
+    end
+
+    # Get the session associated with this event
+    # @return [Session]
+    def session
+      Session.new(js_prop(:session))
+    end
+
+    # Get the event timestamp
+    # @return [Float]
+    def time_stamp
+      js_float(:timeStamp) || 0.0
+    end
+
+    # Check if the event is trusted
+    # @return [Boolean]
+    def trusted?
+      js_bool(:isTrusted)
+    end
+  end
+
+  # XRInputSourcesChangeEvent - Event fired when input sources change
+  class InputSourcesChangeEvent < SessionEvent
+    # Get the added input sources
+    # @return [Array<InputSource>]
+    def added
+      js_added = js_prop(:added)
+      return [] if js_added.nil?
+
+      js_array_to_a(js_added).map { |s| InputSource.new(s) }
+    end
+
+    # Get the removed input sources
+    # @return [Array<InputSource>]
+    def removed
+      js_removed = js_prop(:removed)
+      return [] if js_removed.nil?
+
+      js_array_to_a(js_removed).map { |s| InputSource.new(s) }
+    end
+  end
+end

data/lib/webxr/geometry/pose.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module WebXR
+  # XRPose - Represents the position and orientation of a tracked object
+  class Pose < JSWrapper
+    # @param js_pose [JS::Object] The XRPose JavaScript object
+    def initialize(js_pose)
+      super(js_pose)
+    end
+
+    # Get the rigid transform for this pose
+    # @return [RigidTransform]
+    def transform
+      RigidTransform.new(js_prop(:transform))
+    end
+
+    # Check if the position is emulated (not directly tracked)
+    # @return [Boolean]
+    def emulated_position?
+      js_bool(:emulatedPosition)
+    end
+
+    # Get the linear velocity in m/s
+    # @return [Hash, nil] Hash with :x, :y, :z keys, or nil if not available
+    def linear_velocity
+      v = js_prop(:linearVelocity)
+      return nil if v.nil?
+
+      {
+        x: v[:x].to_f,
+        y: v[:y].to_f,
+        z: v[:z].to_f
+      }
+    end
+
+    # Get the angular velocity in rad/s
+    # @return [Hash, nil] Hash with :x, :y, :z keys, or nil if not available
+    def angular_velocity
+      v = js_prop(:angularVelocity)
+      return nil if v.nil?
+
+      {
+        x: v[:x].to_f,
+        y: v[:y].to_f,
+        z: v[:z].to_f
+      }
+    end
+  end
+end

data/lib/webxr/geometry/rigid_transform.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module WebXR
+  # XRRigidTransform - Represents a position and orientation in 3D space
+  # Immutable transform consisting of a position and quaternion orientation
+  class RigidTransform < JSWrapper
+    # Create a new rigid transform
+    # @param js_transform [JS::Object, nil] Existing JS transform to wrap
+    # @param position [Hash, nil] Position hash with :x, :y, :z, :w keys
+    # @param orientation [Hash, nil] Orientation quaternion hash with :x, :y, :z, :w keys
+    def initialize(js_transform = nil, position: nil, orientation: nil)
+      if js_transform
+        super(js_transform)
+      else
+        js_position = position ? create_dom_point(position) : nil
+        js_orientation = orientation ? create_dom_point(orientation) : nil
+        js_obj = JS.global[:XRRigidTransform].new(js_position, js_orientation)
+        super(js_obj)
+      end
+    end
+
+    # Get the position as a hash
+    # @return [Hash] Hash with :x, :y, :z, :w keys
+    def position
+      p = js_prop(:position)
+      {
+        x: p[:x].to_f,
+        y: p[:y].to_f,
+        z: p[:z].to_f,
+        w: p[:w].to_f
+      }
+    end
+
+    # Get the orientation quaternion as a hash
+    # @return [Hash] Hash with :x, :y, :z, :w keys
+    def orientation
+      o = js_prop(:orientation)
+      {
+        x: o[:x].to_f,
+        y: o[:y].to_f,
+        z: o[:z].to_f,
+        w: o[:w].to_f
+      }
+    end
+
+    # Get the 4x4 transformation matrix
+    # @return [Array<Float>] 16-element array in column-major order
+    def matrix
+      js_matrix = js_prop(:matrix)
+      js_array_to_a(js_matrix).map(&:to_f)
+    end
+
+    # Get the inverse transform
+    # @return [RigidTransform]
+    def inverse
+      RigidTransform.new(js_prop(:inverse))
+    end
+
+    # Get the position as a 3-element array [x, y, z]
+    # @return [Array<Float>]
+    def position_array
+      p = position
+      [p[:x], p[:y], p[:z]]
+    end
+
+    # Get the orientation as a 4-element array [x, y, z, w]
+    # @return [Array<Float>]
+    def orientation_array
+      o = orientation
+      [o[:x], o[:y], o[:z], o[:w]]
+    end
+  end
+end

data/lib/webxr/geometry/view.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module WebXR
+  # XRView - Represents a single view (eye) for rendering
+  class View < JSWrapper
+    # @param js_view [JS::Object] The XRView JavaScript object
+    def initialize(js_view)
+      super(js_view)
+    end
+
+    # Get the eye this view is for
+    # @return [String] "left", "right", or "none"
+    def eye
+      js_string(:eye) || Eye::NONE
+    end
+
+    # Get the 4x4 projection matrix
+    # @return [Array<Float>] 16-element array in column-major order
+    def projection_matrix
+      js_matrix = js_prop(:projectionMatrix)
+      js_array_to_a(js_matrix).map(&:to_f)
+    end
+
+    # Get the view transform
+    # @return [RigidTransform]
+    def transform
+      RigidTransform.new(js_prop(:transform))
+    end
+
+    # Get the recommended viewport scale
+    # @return [Float, nil]
+    def recommended_viewport_scale
+      js_float(:recommendedViewportScale)
+    end
+
+    # Request a specific viewport scale
+    # @param scale [Float] Scale factor (0.0 to 1.0)
+    # @return [void]
+    def request_viewport_scale(scale)
+      js_call(:requestViewportScale, scale)
+    end
+
+    # Check if this is the left eye
+    # @return [Boolean]
+    def left?
+      eye == Eye::LEFT
+    end
+
+    # Check if this is the right eye
+    # @return [Boolean]
+    def right?
+      eye == Eye::RIGHT
+    end
+
+    # Check if this is a mono view (no stereo)
+    # @return [Boolean]
+    def mono?
+      eye == Eye::NONE
+    end
+
+    # Get the view matrix (inverse of transform)
+    # Useful for rendering calculations
+    # @return [Array<Float>] 16-element array in column-major order
+    def view_matrix
+      transform.inverse.matrix
+    end
+  end
+end

data/lib/webxr/geometry/viewer_pose.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module WebXR
+  # XRViewerPose - The pose of the user's head/viewer
+  # Contains one or more views (eyes) for rendering
+  class ViewerPose < Pose
+    # @param js_viewer_pose [JS::Object] The XRViewerPose JavaScript object
+    def initialize(js_viewer_pose)
+      super(js_viewer_pose)
+    end
+
+    # Get all views (typically one per eye)
+    # @return [Array<View>]
+    def views
+      js_views = js_prop(:views)
+      return [] if js_views.nil?
+
+      js_array_to_a(js_views).map { |v| View.new(v) }
+    end
+
+    # Get the left eye view
+    # @return [View, nil]
+    def left_view
+      views.find { |v| v.eye == Eye::LEFT }
+    end
+
+    # Get the right eye view
+    # @return [View, nil]
+    def right_view
+      views.find { |v| v.eye == Eye::RIGHT }
+    end
+
+    # Iterate over each view
+    # @yield [View] Each view
+    # @return [void]
+    def each_view(&block)
+      views.each(&block)
+    end
+  end
+end

data/lib/webxr/geometry/viewport.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module WebXR
+  # XRViewport - Defines a rectangular region for rendering
+  class Viewport < JSWrapper
+    # @param js_viewport [JS::Object] The XRViewport JavaScript object
+    def initialize(js_viewport)
+      super(js_viewport)
+    end
+
+    # Get the X offset in pixels
+    # @return [Integer]
+    def x
+      js_int(:x) || 0
+    end
+
+    # Get the Y offset in pixels
+    # @return [Integer]
+    def y
+      js_int(:y) || 0
+    end
+
+    # Get the width in pixels
+    # @return [Integer]
+    def width
+      js_int(:width) || 0
+    end
+
+    # Get the height in pixels
+    # @return [Integer]
+    def height
+      js_int(:height) || 0
+    end
+
+    # Convert to a hash
+    # @return [Hash] Hash with :x, :y, :width, :height keys
+    def to_h
+      { x: x, y: y, width: width, height: height }
+    end
+
+    # Convert to an array [x, y, width, height]
+    # @return [Array<Integer>]
+    def to_a
+      [x, y, width, height]
+    end
+
+    # Calculate the aspect ratio
+    # @return [Float]
+    def aspect_ratio
+      return 0.0 if height.zero?
+
+      width.to_f / height.to_f
+    end
+  end
+end