Class NeedleXRSession

This class manages an XRSession to provide helper methods and events. It provides easy access to the XRInputSources (controllers and hands)

  • Start a XRSession with NeedleXRSession.start(...)
  • Stop a XRSession with NeedleXRSession.stop()
  • Access a running XRSession with NeedleXRSession.active

If a XRSession is active you can use all XR-related event methods on your components to receive XR events e.g. onEnterXR, onUpdateXR, onLeaveXR

export class MyComponent extends Behaviour {
   // callback invoked whenever the XRSession is started or your component is added to a scene with an active XRSession
   onEnterXR(args: NeedleXREventArgs) {
      console.log("Entered XR");
     // access the NeedleXRSession via args.xr
   }
   // callback invoked whenever a controller is added (or you switch from controller to hand tracking)
   onControllerAdded(args: NeedleXRControllerEventArgs) {  }
}

XRRig

The XRRig can be accessed via the rig property
Set a custom XRRig via NeedleXRSession.addRig(...) or NeedleXRSession.removeRig(...)
By default the active XRRig with the highest priority in the scene is used

Implements

  • INeedleXRSession

Properties

context controllers mode session

Accessors

environmentBlendMode frame interactionMode isAR isPassThrough isScreenBasedAR isSystemKeyboardSupported isTrackingImages isVR isVisibleBlurred leftController poseOrientation posePosition referenceSpace rig rigScale rightController running sync transition viewerPose visibilityState active activeMode currentSessionRequest xrSystem

Methods

addRig convertSpace end fadeTransition getController getHitTest getUserOffsetInRig removeRig setRigActive getDefaultSessionInit getXRSync isARSupported isSessionSupported isVRSupported isXRSupported offControllerAdded offControllerRemoved offSessionRequestEnd offSessionRequestStart offXRSessionEnd offXRSessionStart offerSession onControllerAdded onControllerRemoved onSessionRequestEnd onSessionRequestStart onXRSessionEnd onXRSessionStart setSession start stop

Properties

Readonly context

context: Context

The needle engine context this session was started from

Readonly controllers

controllers: NeedleXRController[] = []

The currently active/connected controllers

Readonly mode

mode: XRSessionMode

XR Session Mode: AR or VR

Readonly session

session: XRSession

Link

https://developer.mozilla.org/en-US/docs/Web/API/XRSession

Accessors

environmentBlendMode

frame

interactionMode

  • get interactionMode(): "screen-space" | "world-space"

  • The XRSession interface's read-only interactionMode property describes the best space (according to the user agent) for the application to draw an interactive UI for the current session.

    Returns "screen-space" | "world-space"

    Link

    https://developer.mozilla.org/en-US/docs/Web/API/XRSession/interactionMode

isAR

  • get isAR(): boolean

  • Returns boolean

isPassThrough

  • get isPassThrough(): boolean

  • Returns true if running in pass through mode in immersive AR (e.g. user is wearing a headset while in AR)

    Returns boolean

isScreenBasedAR

  • get isScreenBasedAR(): boolean

  • If the AR mode is not immersive (meaning the user is e.g. holding a phone instead of wearing a AR passthrough headset)

    Returns boolean

isSystemKeyboardSupported

  • get isSystemKeyboardSupported(): boolean

  • Check if the session has system keyboard support

    Returns boolean

isTrackingImages

  • get isTrackingImages(): boolean

  • returns true if images are currently being tracked

    Returns boolean

isVR

  • get isVR(): boolean

  • Returns boolean

isVisibleBlurred

  • get isVisibleBlurred(): boolean

  • Check if the session is visible-blurred - this means e.g. the keyboard is shown

    Returns boolean

leftController

  • get leftController(): NeedleXRController

  • shorthand to query the left controller. Use controllers to get access to all connected controllers

    Returns NeedleXRController

poseOrientation

  • get poseOrientation(): Quaternion

  • Returns Quaternion

posePosition

  • get posePosition(): Vector3

  • Returns Vector3

referenceSpace

  • get referenceSpace(): XRSpace

  • Returns XRSpace

    the context.renderer.xr.getReferenceSpace() result

rig

  • get rig(): IXRRig

  • The currently active XR rig

    Returns IXRRig

rigScale

  • get rigScale(): number

  • get the XR rig worldscale

    Returns number

rightController

  • get rightController(): NeedleXRController

  • shorthand to query the right controller. Use controllers to get access to all connected controllers

    Returns NeedleXRController

running

  • get running(): boolean

  • Returns true if the xr session is still active

    Returns boolean

sync

transition

  • get transition(): SceneTransition

  • Returns SceneTransition

viewerPose

  • get viewerPose(): XRViewerPose

  • Returns XRViewerPose

    the XRFrame viewerpose using the xr referenceSpace

visibilityState

Static active

Static activeMode

  • get activeMode(): XRSessionMode

  • The active xr session mode (if any xr session is active)

    Returns XRSessionMode

Static currentSessionRequest

  • get currentSessionRequest(): XRSessionMode

  • Returns XRSessionMode

Static xrSystem

Methods

addRig

  • addRig(rig): void

  • add a rig to the available XR rigs - if it's priority is higher than the currently active rig it will be enabled

    Parameters

    • rig: IXRRig

    Returns void

convertSpace

  • convertSpace(transform): {
        position: Vector3;
        quaternion: Quaternion;
    }

  • convert a XRRigidTransform from XR session space to threejs / Needle Engine XR space

    Parameters

    • transform: XRRigidTransform

    Returns {
        position: Vector3;
        quaternion: Quaternion;
    }

end

  • end(): void

  • End the XR Session

    Returns void

fadeTransition

  • fadeTransition(): Promise<void>

  • Call to fade rendering to black for a short moment (the returned promise will be resolved when fully black)
    This can be used to mask scene transitions or teleportation

    Returns Promise<void>

    a promise that is resolved when the screen is fully black

    Example

    `fadeTransition().then(() => { <fully_black> })`

getController

  • getController(side): NeedleXRController

  • Parameters

    • side: number | XRHandedness

    Returns NeedleXRController

    the given controller if it is connected

getHitTest

  • getHitTest(source?): NeedleXRHitTestResult

  • Returns a XR hit test result (if hit-testing is available) in rig space

    Parameters

    • Optional source: NeedleXRController

      If provided, the hit test will be performed for the given controller

    Returns NeedleXRHitTestResult

getUserOffsetInRig

  • getUserOffsetInRig(): Vector3

  • Returns Vector3

    the user position in the rig space

removeRig

  • removeRig(rig): void

  • Remove a rig from the available XR Rigs

    Parameters

    • rig: IXRRig

    Returns void

setRigActive

  • setRigActive(rig): void

  • Sets a XRRig to be active which will parent the camera to this rig

    Parameters

    • rig: IXRRig

    Returns void

Static getDefaultSessionInit

  • getDefaultSessionInit(mode): XRSessionInit

  • Parameters

    • mode: Omit<XRSessionMode, "inline">

    Returns XRSessionInit

    a new XRSession init object with defaults

Static getXRSync

Static isARSupported

Static isSessionSupported

  • isSessionSupported(mode): Promise<boolean>

  • Parameters

    • mode: XRSessionMode

    Returns Promise<boolean>

Static isVRSupported

Static isXRSupported

Static offControllerAdded

  • offControllerAdded(evt): void

  • Unsubscribe from controller added evts

    Parameters

    Returns void

Static offControllerRemoved

  • offControllerRemoved(evt): void

  • Unsubscribe from controller removed events

    Parameters

    Returns void

Static offSessionRequestEnd

  • offSessionRequestEnd(evt): void

  • Unsubscribe from request end evt

    Parameters

    • evt: SessionRequestedEndEvent

    Returns void

Static offSessionRequestStart

  • offSessionRequestStart(evt): void

  • Parameters

    • evt: SessionRequestedEvent

    Returns void

Static offXRSessionEnd

  • offXRSessionEnd(evt): void

  • Unsubscribe from XRSession started events

    Parameters

    • evt: SessionChangedEvt

    Returns void

Static offXRSessionStart

  • offXRSessionStart(evt): void

  • Unsubscribe from XRSession started events

    Parameters

    • evt: SessionChangedEvt

    Returns void

Static offerSession

  • offerSession(mode, init, context): boolean

  • If the browser supports offerSession - creating a VR or AR button in the browser navigation bar

    Parameters

    • mode: XRSessionMode
    • init: XRSessionInit | "default"
    • context: Context

    Returns boolean

Static onControllerAdded

  • onControllerAdded(evt): void

  • Listen to controller added events. Events are cleared when starting a new session

    Parameters

    Returns void

Static onControllerRemoved

  • onControllerRemoved(evt): void

  • Listen to controller removed events Events are cleared when starting a new session

    Parameters

    Returns void

Static onSessionRequestEnd

  • onSessionRequestEnd(evt): void

  • Called after the session request has finished

    Parameters

    • evt: SessionRequestedEndEvent

    Returns void

Static onSessionRequestStart

  • onSessionRequestStart(evt): void

  • Parameters

    • evt: SessionRequestedEvent

    Returns void

Static onXRSessionEnd

  • onXRSessionEnd(evt): void

  • Listen to XR session ended. Unsubscribe with offXRSessionEnd

    Parameters

    • evt: SessionChangedEvt

    Returns void

Static onXRSessionStart

  • onXRSessionStart(evt): void

  • Listen to XR session started. Unsubscribe with offXRSessionStart

    Parameters

    • evt: SessionChangedEvt

    Returns void

Static setSession

Static start

Static stop

  • stop(): void

  • stops the active XR session

    Returns void

Settings

Member Visibility

Theme

On This Page

contextcontrollersmodesessionenvironmentBlendModeframeinteractionModeisARisPassThroughisScreenBasedARisSystemKeyboardSupportedisTrackingImagesisVRisVisibleBlurredleftControllerposeOrientationposePositionreferenceSpacerigrigScalerightControllerrunningsynctransitionviewerPosevisibilityStateactiveactiveModecurrentSessionRequestxrSystemaddRigconvertSpaceendfadeTransitiongetControllergetHitTestgetUserOffsetInRigremoveRigsetRigActivegetDefaultSessionInitgetXRSyncisARSupportedisSessionSupportedisVRSupportedisXRSupportedoffControllerAddedoffControllerRemovedoffSessionRequestEndoffSessionRequestStartoffXRSessionEndoffXRSessionStartofferSessiononControllerAddedonControllerRemovedonSessionRequestEndonSessionRequestStartonXRSessionEndonXRSessionStartsetSessionstartstop

Generated using TypeDoc