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

Index

Properties

context controllers mode session

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

get environmentBlendMode(): XREnvironmentBlendMode
Returns XREnvironmentBlendMode
Link
https://developer.mozilla.org/en-US/docs/Web/API/XRSession/environmentBlendMode

Implementation of INeedleXRSession.environmentBlendMode

frame

get frame(): NeedleXRFrame
The current XR frame

Returns NeedleXRFrame
Link
https://developer.mozilla.org/en-US/docs/Web/API/XRFrame

Implementation of INeedleXRSession.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

Implementation of INeedleXRSession.interactionMode

isAR

get isAR(): boolean
Returns boolean
Implementation of INeedleXRSession.isAR

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
Implementation of INeedleXRSession.isPassThrough

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
Implementation of INeedleXRSession.isScreenBasedAR

isSystemKeyboardSupported

get isSystemKeyboardSupported(): boolean
Check if the session has system keyboard support

Returns boolean
Implementation of INeedleXRSession.isSystemKeyboardSupported

isTrackingImages

get isTrackingImages(): boolean
returns true if images are currently being tracked

Returns boolean
Implementation of INeedleXRSession.isTrackingImages

isVisibleBlurred

get isVisibleBlurred(): boolean
Check if the session is visible-blurred - this means e.g. the keyboard is shown

Returns boolean
Implementation of INeedleXRSession.isVisibleBlurred

isVR

get isVR(): boolean
Returns boolean
Implementation of INeedleXRSession.isVR

leftController

get leftController(): undefined | NeedleXRController
shorthand to query the left controller. Use controllers to get access to all connected controllers

Returns undefined | NeedleXRController
Implementation of INeedleXRSession.leftController

poseOrientation

get poseOrientation(): Quaternion
Returns Quaternion
Implementation of INeedleXRSession.poseOrientation

posePosition

get posePosition(): Vector3
Returns Vector3
Implementation of INeedleXRSession.posePosition

referenceSpace

get referenceSpace(): null | XRSpace
Returns null | XRSpace
the context.renderer.xr.getReferenceSpace() result

Implementation of INeedleXRSession.referenceSpace

rig

get rig(): null | IXRRig
The currently active XR rig

Returns null | IXRRig
Implementation of INeedleXRSession.rig

rightController

get rightController(): undefined | NeedleXRController
shorthand to query the right controller. Use controllers to get access to all connected controllers

Returns undefined | NeedleXRController
Implementation of INeedleXRSession.rightController

rigScale

get rigScale(): number
Get the XR Rig worldscale.

For AR
If you want to modify the scale in AR at runtime get the WebARSessionRoot component via findObjectOfType(WebARSessionRoot) and then set the arScale value.

Returns number
Implementation of INeedleXRSession.rigScale

running

get running(): boolean
Returns true if the xr session is still active

Returns boolean
Implementation of INeedleXRSession.running

sync

get sync(): null | NeedleXRSync
Returns null | NeedleXRSync
Implementation of INeedleXRSession.sync

transition

get transition(): SceneTransition
Returns SceneTransition
Implementation of INeedleXRSession.transition

viewerPose

get viewerPose(): undefined | XRViewerPose
Returns undefined | XRViewerPose
the XRFrame viewerpose using the xr referenceSpace

Implementation of INeedleXRSession.viewerPose

visibilityState

get visibilityState(): XRVisibilityState
Returns XRVisibilityState
The visibility state of the XRSession

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

Implementation of INeedleXRSession.visibilityState

`Static`active

get active(): null | NeedleXRSession
Returns null | NeedleXRSession
the active

`Static`activeMode

get activeMode(): null | XRSessionMode
The active xr session mode (if any xr session is active)

Returns null | XRSessionMode
Link
https://developer.mozilla.org/en-US/docs/Web/API/XRSessionMode

`Static`currentSessionRequest

get currentSessionRequest(): null | XRSessionMode
Returns null | XRSessionMode

`Static`xrSystem

get xrSystem(): undefined | XRSystem
XRSystem via navigator.xr access

Returns undefined | XRSystem
Link
https://developer.mozilla.org/en-US/docs/Web/API/XRSystem

Methods

addRig

addRig(rig: IXRRig): 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
Implementation of INeedleXRSession.addRig

convertSpace

convertSpace(
transform: XRRigidTransform,
): { 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 }
Implementation of INeedleXRSession.convertSpace

end

end(): void
End the XR Session

Returns void
Implementation of INeedleXRSession.end

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> })`
```
Implementation of INeedleXRSession.fadeTransition

getController

getController(side: number | XRHandedness): null | NeedleXRController
Parameters
- side: number | XRHandedness
Returns null | NeedleXRController
the given controller if it is connected

Implementation of INeedleXRSession.getController

getHitTest

getHitTest(source?: NeedleXRController): null | NeedleXRHitTestResult
Returns a XR hit test result (if hit-testing is available) in rig space
Parameters
- Optionalsource: NeedleXRController
  If provided, the hit test will be performed for the given controller
Returns null | NeedleXRHitTestResult
Implementation of INeedleXRSession.getHitTest

getUserOffsetInRig

getUserOffsetInRig(): Vector3
Returns Vector3
the user position in the rig space

Implementation of INeedleXRSession.getUserOffsetInRig

removeRig

removeRig(rig: IXRRig): void
Remove a rig from the available XR Rigs
Parameters
- rig: IXRRig
Returns void
Implementation of INeedleXRSession.removeRig

setRigActive

setRigActive(rig: IXRRig): void
Sets a XRRig to be active which will parent the camera to this rig
Parameters
- rig: IXRRig
Returns void
Implementation of INeedleXRSession.setRigActive

`Static`getDefaultSessionInit

getDefaultSessionInit(mode: Omit<XRSessionMode, "inline">): XRSessionInit
Parameters
- mode: Omit<XRSessionMode, "inline">
Returns XRSessionInit
a new XRSession init object with defaults

`Static`getXRSync

getXRSync(context: Context): NeedleXRSync
Parameters
- context: Context
Returns NeedleXRSync

`Static`isARSupported

isARSupported(): Promise<boolean>
Returns Promise<boolean>
true if the browser supports immersive-ar (WebXR)

Link
https://developer.mozilla.org/en-US/docs/Web/API/XRSystem/isSessionSupported

`Static`isSessionSupported

isSessionSupported(mode: XRSessionMode): Promise<boolean>
Parameters
- mode: XRSessionMode
  The XRSessionMode to check if it is supported
Returns Promise<boolean>
true if the browser supports the given XRSessionMode

`Static`isVRSupported

isVRSupported(): Promise<boolean>
Returns Promise<boolean>
true if the browser supports immersive-vr (WebXR)

Link
https://developer.mozilla.org/en-US/docs/Web/API/XRSystem/isSessionSupported

`Static`isXRSupported

isXRSupported(): Promise<boolean>
Returns Promise<boolean>
true if the browser supports WebXR (immersive-vr or immersive-ar)

Link
https://developer.mozilla.org/en-US/docs/Web/API/XRSystem/isSessionSupported

`Static`offControllerAdded

offControllerAdded(evt: ControllerChangedEvt): void
Unsubscribe from controller added evts
Parameters
- evt: ControllerChangedEvt
Returns void

`Static`offControllerRemoved

offControllerRemoved(evt: ControllerChangedEvt): void
Unsubscribe from controller removed events
Parameters
- evt: ControllerChangedEvt
Returns void

`Static`offerSession

offerSession(
    mode: XRSessionMode,
    init: "default" | XRSessionInit,
    context: Context,
): boolean
If the browser supports offerSession - creating a VR or AR button in the browser navigation bar
Parameters
- mode: XRSessionMode
- init: "default" | XRSessionInit
- context: Context
Returns boolean

`Static`offSessionRequestEnd

offSessionRequestEnd(evt: SessionRequestedEndEvent): void
Unsubscribe from request end evt
Parameters
- evt: SessionRequestedEndEvent
Returns void

`Static`offSessionRequestStart

offSessionRequestStart(evt: SessionRequestedEvent): void
Unsubscribe from request start evt. Register with onSessionRequestStart
Parameters
- evt: SessionRequestedEvent
Returns void

`Static`offXRSessionEnd

offXRSessionEnd(evt: SessionChangedEvt): void
Unsubscribe from XRSession started events
Parameters
- evt: SessionChangedEvt
Returns void

`Static`offXRSessionStart

offXRSessionStart(evt: SessionChangedEvt): void
Unsubscribe from XRSession started events
Parameters
- evt: SessionChangedEvt
Returns void

`Static`onControllerAdded

onControllerAdded(evt: ControllerChangedEvt): void
Listen to controller added events. Events are cleared when starting a new session
Parameters
- evt: ControllerChangedEvt
Returns void

`Static`onControllerRemoved

onControllerRemoved(evt: ControllerChangedEvt): void
Listen to controller removed events Events are cleared when starting a new session
Parameters
- evt: ControllerChangedEvt
Returns void

`Static`onSessionRequestEnd

onSessionRequestEnd(evt: SessionRequestedEndEvent): void
Called after the session request has finished
Parameters
- evt: SessionRequestedEndEvent
Returns void

`Static`onSessionRequestStart

onSessionRequestStart(evt: SessionRequestedEvent): void
Register to listen to XRSession start events. Unsubscribe with offXRSessionStart
Parameters
- evt: SessionRequestedEvent
Returns void

`Static`onXRSessionEnd

onXRSessionEnd(evt: SessionChangedEvt): void
Listen to XR session ended. Unsubscribe with offXRSessionEnd
Parameters
- evt: SessionChangedEvt
Returns void

`Static`onXRSessionStart

onXRSessionStart(evt: SessionChangedEvt): void
Listen to XR session started. Unsubscribe with offXRSessionStart
Parameters
- evt: SessionChangedEvt
Returns void

`Static`setSession

setSession(
    mode: XRSessionMode,
    session: XRSession,
    init: XRSessionInit,
    context: Context,
): NeedleXRSession
Parameters
- mode: XRSessionMode
- session: XRSession
- init: XRSessionInit
- context: Context
Returns NeedleXRSession

`Static`start

start(
    mode: XRSessionMode | "ar",
    init?: XRSessionInit,
    context?: Context,
): Promise<null | NeedleXRSession>
start a new webXR session (make sure to stop already running sessions before calling this method)
Parameters
- mode: XRSessionMode | "ar"
  The XRSessionMode to start (e.g. immersive-vr or immersive-ar) or ar to start immersive-ar on supported devices OR on iOS devices it will export an interactive USDZ and open in Quicklook.
  Get more information about WebXR modes: https://developer.mozilla.org/en-US/docs/Web/API/XRSessionMode
- Optionalinit: XRSessionInit
  The XRSessionInit to use (optional), docs: https://developer.mozilla.org/en-US/docs/Web/API/XRSessionInit
- Optionalcontext: Context
  The Needle Engine context to use
Returns Promise<null | NeedleXRSession>

`Static`stop

stop(): void
stops the active XR session

Returns void

Class NeedleXRSession

XRRig

Implements

Index

Properties

Accessors

Methods

Properties

Readonlycontext

Readonlycontrollers

Readonlymode

Readonlysession

Link

Accessors

environmentBlendMode

Returns XREnvironmentBlendMode

Link

frame

Returns NeedleXRFrame

Link

interactionMode

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

Link

isAR

Returns boolean

isPassThrough

Returns boolean

isScreenBasedAR

Returns boolean

isSystemKeyboardSupported

Returns boolean

isTrackingImages

Returns boolean

isVisibleBlurred

Returns boolean

isVR

Returns boolean

leftController

Returns undefined | NeedleXRController

poseOrientation

Returns Quaternion

posePosition

Returns Vector3

referenceSpace

Returns null | XRSpace

rig

Returns null | IXRRig

rightController

Returns undefined | NeedleXRController

rigScale

Returns number

running

Returns boolean

sync

Returns null | NeedleXRSync

transition

Returns SceneTransition

viewerPose

Returns undefined | XRViewerPose

visibilityState

Returns XRVisibilityState

Link

Staticactive

Returns null | NeedleXRSession

StaticactiveMode

Returns null | XRSessionMode

Link

StaticcurrentSessionRequest

Returns null | XRSessionMode

StaticxrSystem

Returns undefined | XRSystem

Link

Methods

addRig

Parameters

Returns void

convertSpace

Parameters

Returns { position: Vector3; quaternion: Quaternion }

end

`Readonly`context

`Readonly`controllers

`Readonly`mode

`Readonly`session

`Static`active

`Static`activeMode

`Static`currentSessionRequest

`Static`xrSystem

`Static`getDefaultSessionInit

`Static`getXRSync

`Static`isARSupported

`Static`isSessionSupported

`Static`isVRSupported

`Static`isXRSupported

`Static`offControllerAdded

`Static`offControllerRemoved

`Static`offerSession

`Static`offSessionRequestEnd

`Static`offSessionRequestStart

`Static`offXRSessionEnd

`Static`offXRSessionStart

`Static`onControllerAdded

`Static`onControllerRemoved

`Static`onSessionRequestEnd

`Static`onSessionRequestStart

`Static`onXRSessionEnd