Class: XRDeviceCamera
Defined in: src/camera/XRDeviceCamera.ts:49
Handles video capture from a device camera, manages the device list, and reports its state using VideoStream's event model.
Extends
VideoStream<XRDeviceCameraDetails>
Constructors
Constructor
new XRDeviceCamera(
options):XRDeviceCamera
Defined in: src/camera/XRDeviceCamera.ts:82
Parameters
options
The configuration options.
Returns
XRDeviceCamera
Overrides
Properties
aspectRatio?
optionalaspectRatio:number
Defined in: src/video/VideoStream.ts:107
Inherited from
height?
optionalheight:number
Defined in: src/video/VideoStream.ts:106
Inherited from
isXRScript
isXRScript:
boolean=true
Defined in: src/core/Script.ts:100
Inherited from
loaded
loaded:
boolean=false
Defined in: src/video/VideoStream.ts:104
Inherited from
rgbToDepthParams
rgbToDepthParams:
RgbToDepthParams
Defined in: src/camera/XRDeviceCamera.ts:53
simulatorCamera?
optionalsimulatorCamera:SimulatorCameraSource
Defined in: src/camera/XRDeviceCamera.ts:52
state
state:
StreamState=StreamState.IDLE
Defined in: src/video/VideoStream.ts:109
Inherited from
stream_
protectedstream_:MediaStream|null=null
Defined in: src/video/VideoStream.ts:111
Inherited from
texture
texture:
Texture
Defined in: src/video/VideoStream.ts:108
Inherited from
video_
protectedvideo_:HTMLVideoElement
Defined in: src/video/VideoStream.ts:112
Inherited from
videoConstraints_
protectedvideoConstraints_:MediaTrackConstraints
Defined in: src/camera/XRDeviceCamera.ts:54
width?
optionalwidth:number
Defined in: src/video/VideoStream.ts:105
Inherited from
xb?
optionalxb:XBObjectOptions
Defined in: src/interaction/InteractionTypes.ts:34
Inherited from
Accessors
isUsingXRCameraAccess
Get Signature
get isUsingXRCameraAccess():
boolean
Defined in: src/camera/XRDeviceCamera.ts:378
Whether the camera is using the WebXR Raw Camera Access API fallback.
Returns
boolean
targetDevice
Get Signature
get targetDevice():
string
Defined in: src/camera/XRDeviceCamera.ts:99
The DEVICE_CAMERA_PARAMETERS profile used for this camera's intrinsics
and pose, resolved once from ?camera=, options.targetDevice and the
user agent (see resolveDeviceCameraTarget). Assign an exact profile key
to switch it at runtime; unknown keys throw.
Returns
string
Set Signature
set targetDevice(
targetDevice):void
Defined in: src/camera/XRDeviceCamera.ts:103
Parameters
targetDevice
string
Returns
void
video
Get Signature
get video():
HTMLVideoElement
Defined in: src/video/VideoStream.ts:113
Returns
Inherited from
Methods
captureSnapshot()
Call Signature
captureSnapshot():
Promise<Texture<unknown,TextureEventMap> |null>
Defined in: src/camera/XRDeviceCamera.ts:396
Captures a snapshot from the active camera source.
In the normal video path this resolves from getSnapshot
immediately. In the WebXR Raw Camera Access fallback, the browser camera
image is only valid during the XR frame that produced it, so this queues a
one-shot GPU readback for the next updateXRCamera call and then
resolves through getSnapshot. Concurrent camera-access calls share
that next XR-frame readback, but each resolves with its own requested
format. If no XR camera frame arrives within about one second, or the raw
camera path is stopped, the promise resolves to null. Synchronous
getSnapshot on that fallback path returns the most recently
captured one-shot frame, or null when no capture has completed yet.
Returns
Promise<Texture<unknown, TextureEventMap> | null>
Call Signature
Defined in: src/camera/XRDeviceCamera.ts:397
Captures a snapshot from the active camera source.
In the normal video path this resolves from getSnapshot
immediately. In the WebXR Raw Camera Access fallback, the browser camera
image is only valid during the XR frame that produced it, so this queues a
one-shot GPU readback for the next updateXRCamera call and then
resolves through getSnapshot. Concurrent camera-access calls share
that next XR-frame readback, but each resolves with its own requested
format. If no XR camera frame arrives within about one second, or the raw
camera path is stopped, the promise resolves to null. Synchronous
getSnapshot on that fallback path returns the most recently
captured one-shot frame, or null when no capture has completed yet.
Parameters
options
VideoStreamGetSnapshotImageDataOptions
Returns
Call Signature
captureSnapshot(
options):Promise<string|null>
Defined in: src/camera/XRDeviceCamera.ts:400
Captures a snapshot from the active camera source.
In the normal video path this resolves from getSnapshot
immediately. In the WebXR Raw Camera Access fallback, the browser camera
image is only valid during the XR frame that produced it, so this queues a
one-shot GPU readback for the next updateXRCamera call and then
resolves through getSnapshot. Concurrent camera-access calls share
that next XR-frame readback, but each resolves with its own requested
format. If no XR camera frame arrives within about one second, or the raw
camera path is stopped, the promise resolves to null. Synchronous
getSnapshot on that fallback path returns the most recently
captured one-shot frame, or null when no capture has completed yet.
Parameters
options
VideoStreamGetSnapshotBase64Options
Returns
Promise<string | null>
Call Signature
captureSnapshot(
options):Promise<Texture<unknown,TextureEventMap> |null>
Defined in: src/camera/XRDeviceCamera.ts:403
Captures a snapshot from the active camera source.
In the normal video path this resolves from getSnapshot
immediately. In the WebXR Raw Camera Access fallback, the browser camera
image is only valid during the XR frame that produced it, so this queues a
one-shot GPU readback for the next updateXRCamera call and then
resolves through getSnapshot. Concurrent camera-access calls share
that next XR-frame readback, but each resolves with its own requested
format. If no XR camera frame arrives within about one second, or the raw
camera path is stopped, the promise resolves to null. Synchronous
getSnapshot on that fallback path returns the most recently
captured one-shot frame, or null when no capture has completed yet.
Parameters
options
VideoStreamGetSnapshotTextureOptions
Returns
Promise<Texture<unknown, TextureEventMap> | null>
Call Signature
Defined in: src/camera/XRDeviceCamera.ts:406
Captures a snapshot from the active camera source.
In the normal video path this resolves from getSnapshot
immediately. In the WebXR Raw Camera Access fallback, the browser camera
image is only valid during the XR frame that produced it, so this queues a
one-shot GPU readback for the next updateXRCamera call and then
resolves through getSnapshot. Concurrent camera-access calls share
that next XR-frame readback, but each resolves with its own requested
format. If no XR camera frame arrives within about one second, or the raw
camera path is stopped, the promise resolves to null. Synchronous
getSnapshot on that fallback path returns the most recently
captured one-shot frame, or null when no capture has completed yet.
Parameters
options
VideoStreamGetSnapshotBlobOptions
Returns
Call Signature
captureSnapshot(
options):Promise<string|Texture<unknown,TextureEventMap> |Blob|ImageData|null>
Defined in: src/camera/XRDeviceCamera.ts:409
Captures a snapshot from the active camera source.
In the normal video path this resolves from getSnapshot
immediately. In the WebXR Raw Camera Access fallback, the browser camera
image is only valid during the XR frame that produced it, so this queues a
one-shot GPU readback for the next updateXRCamera call and then
resolves through getSnapshot. Concurrent camera-access calls share
that next XR-frame readback, but each resolves with its own requested
format. If no XR camera frame arrives within about one second, or the raw
camera path is stopped, the promise resolves to null. Synchronous
getSnapshot on that fallback path returns the most recently
captured one-shot frame, or null when no capture has completed yet.
Parameters
options
Returns
Promise<string | Texture<unknown, TextureEventMap> | Blob | ImageData | null>
dispose()
dispose():
void
Defined in: src/camera/XRDeviceCamera.ts:545
Disposes of all resources used by this stream.
Returns
void
Overrides
drawSnapshotSource_()
protecteddrawSnapshotSource_(context,width,height):void
Defined in: src/camera/XRDeviceCamera.ts:454
Draws the current snapshot source into context at the requested size.
Subclasses may override this to provide pixels from another source.
Parameters
context
width
number
height
number
Returns
void
Overrides
VideoStream.drawSnapshotSource_
getAvailableDevices()
getAvailableDevices():
MediaOrSimulatorMediaDeviceInfo[]
Defined in: src/camera/XRDeviceCamera.ts:347
Gets the list of enumerated video devices.
Returns
MediaOrSimulatorMediaDeviceInfo[]
getAvailableVideoDevices()
getAvailableVideoDevices():
Promise<MediaOrSimulatorMediaDeviceInfo[]>
Defined in: src/camera/XRDeviceCamera.ts:113
Retrieves the list of available video input devices.
Returns
Promise<MediaOrSimulatorMediaDeviceInfo[]>
A promise that resolves with an array of video devices.
getCurrentDevice()
getCurrentDevice():
MediaOrSimulatorMediaDeviceInfo|undefined
Defined in: src/camera/XRDeviceCamera.ts:354
Gets the currently active device info, if available.
Returns
MediaOrSimulatorMediaDeviceInfo | undefined
getCurrentDeviceIndex()
getCurrentDeviceIndex():
number
Defined in: src/camera/XRDeviceCamera.ts:371
Gets the index of the currently active device.
Returns
number
getCurrentTrackSettings()
getCurrentTrackSettings():
MediaTrackSettings|undefined
Defined in: src/camera/XRDeviceCamera.ts:364
Gets the settings of the currently active video track.
Returns
MediaTrackSettings | undefined
getDeviceIdFromLabel()
protectedgetDeviceIdFromLabel(label):string|null
Defined in: src/camera/XRDeviceCamera.ts:173
Parameters
label
string
Returns
string | null
getSnapshot()
Call Signature
getSnapshot(
options):ImageData
Defined in: src/video/VideoStream.ts:264
Captures the current video frame.
Parameters
options
VideoStreamGetSnapshotImageDataOptions
The options for the snapshot.
Returns
The captured data.
Inherited from
Call Signature
getSnapshot(
options):Promise<string|null>
Defined in: src/video/VideoStream.ts:265
Captures the current video frame.
Parameters
options
VideoStreamGetSnapshotBase64Options
The options for the snapshot.
Returns
Promise<string | null>
The captured data.
Inherited from
Call Signature
getSnapshot(
options):Texture
Defined in: src/video/VideoStream.ts:268
Captures the current video frame.
Parameters
options
VideoStreamGetSnapshotTextureOptions
The options for the snapshot.
Returns
The captured data.
Inherited from
Call Signature
Defined in: src/video/VideoStream.ts:269
Captures the current video frame.
Parameters
options
VideoStreamGetSnapshotBlobOptions
The options for the snapshot.
Returns
The captured data.
Inherited from
handleVideoStreamLoadedMetadata()
protectedhandleVideoStreamLoadedMetadata(resolve,reject,allowRetry):void
Defined in: src/video/VideoStream.ts:174
Processes video metadata, sets dimensions, and resolves a promise.
Parameters
resolve
() => void
The resolve function of the wrapping Promise.
reject
(_) => void
The reject function of the wrapping Promise.
allowRetry
boolean = false
Whether to allow a retry attempt on failure.
Returns
void
Inherited from
VideoStream.handleVideoStreamLoadedMetadata
init()
init():
Promise<void>
Defined in: src/camera/XRDeviceCamera.ts:140
Initializes the camera based on the initial constraints.
Returns
Promise<void>
Overrides
initPhysics()
initPhysics(
_physics):void|Promise<void>
Defined in: src/core/Script.ts:119
Enables depth-aware interactions with physics. See /samples/advanced/ballpit
Parameters
_physics
Returns
void | Promise<void>
Inherited from
initStream_()
protectedinitStream_():Promise<void>
Defined in: src/camera/XRDeviceCamera.ts:184
Initializes the media stream from the user's camera. After the stream starts, it updates the current device index based on the stream's active track.
Returns
Promise<void>
onHoverEnter()
onHoverEnter(
_event):void
Defined in: src/core/Script.ts:222
Called when a source starts hovering over this object.
Parameters
_event
The hover source, target, surface, and intersection.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Returns
void
Inherited from
onHoverExit()
onHoverExit(
_event):void
Defined in: src/core/Script.ts:228
Called when a source stops hovering over this object.
Parameters
_event
The hover source, target, surface, and intersection.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Returns
void
Inherited from
onHovering()
onHovering(
_event):void
Defined in: src/core/Script.ts:234
Called while a source hovers over this object.
Parameters
_event
The hover source, target, surface, and intersection.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Returns
void
Inherited from
onKeyDown()
onKeyDown(
_event):void
Defined in: src/core/Script.ts:159
Called on keyboard keypress.
Parameters
_event
Event containing .code to read the keyboard key.
Returns
void
Inherited from
onKeyUp()
onKeyUp(
_event):void
Defined in: src/core/Script.ts:160
Parameters
_event
Returns
void
Inherited from
onLongSelect()
onLongSelect(
_event):void
Defined in: src/core/Script.ts:153
Called when an object selection reaches the long-select delay.
Parameters
_event
Returns
void
Inherited from
onObjectGrabbing()
onObjectGrabbing(
_event):void
Defined in: src/core/Script.ts:260
Called every frame a hand is grabbing this object.
Parameters
_event
Returns
void
Inherited from
onObjectGrabEnd()
onObjectGrabEnd(
_event):void
Defined in: src/core/Script.ts:265
Called when a hand stops grabbing this object. This ends built-in direct-touch manipulation without ending contact.
Parameters
_event
Returns
void
Inherited from
onObjectGrabStart()
onObjectGrabStart(
_event):void
Defined in: src/core/Script.ts:256
Called when a hand starts grabbing this object (touching + pinching). A grab starts built-in direct-touch manipulation when enabled.
Parameters
_event
Returns
void
Inherited from
onObjectLongSelect()
onObjectLongSelect(
_event):void
Defined in: src/core/Script.ts:210
Called once when a captured selection is held for the long-select delay. Manipulation captures do not emit this callback.
Parameters
_event
The controller and completed hold duration.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Call event.stopGlobalPropagation() to suppress global selection callbacks
for the rest of this capture
Returns
void
Inherited from
VideoStream.onObjectLongSelect
onObjectManipulate()
onObjectManipulate(
_event):void
Defined in: src/core/Script.ts:216
Called for each phase of an automatic object manipulation. Call
event.stopPropagation() to stop bubbling. Calling preventDefault()
on a start event suppresses the automatic action.
Parameters
_event
Returns
void
Inherited from
VideoStream.onObjectManipulate
onObjectSelectEnd()
onObjectSelectEnd(
_event):void
Defined in: src/core/Script.ts:201
Called when a source stops selecting the object this Script represents.
Parameters
_event
The completed state and end reason.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Call event.stopGlobalPropagation() to suppress global selection callbacks
for the rest of this capture
Returns
void
Inherited from
onObjectSelectStart()
onObjectSelectStart(
_event):void
Defined in: src/core/Script.ts:193
Called when a source starts selecting the object this Script represents.
Parameters
_event
event.target is the logical object and
event.source.controller identifies the controller.
Call event.stopPropagation() to stop bubbling to ancestor Scripts.
Call event.stopGlobalPropagation() to suppress global selection callbacks
for the rest of this capture
Returns
void
Inherited from
VideoStream.onObjectSelectStart
onObjectTouchEnd()
onObjectTouchEnd(
_event):void
Defined in: src/core/Script.ts:251
Called when a hand's index finger stops touching this object. This ends the default selection lifecycle after the touch callback.
Parameters
_event
Returns
void
Inherited from
onObjectTouching()
onObjectTouching(
_event):void
Defined in: src/core/Script.ts:246
Called every frame that a hand's index finger is touching this object. The object remains selected during these frames unless touch selection was prevented when contact started.
Parameters
_event
Returns
void
Inherited from
onObjectTouchStart()
onObjectTouchStart(
_event):void
Defined in: src/core/Script.ts:240
Called when a hand's index finger starts touching this object.
Direct touch starts the object's selection lifecycle by default. Call
event.preventDefault() to handle contact without selecting.
Parameters
_event
Returns
void
Inherited from
VideoStream.onObjectTouchStart
onSelect()
onSelect(
_event):void
Defined in: src/core/Script.ts:145
Called whenever pinch / mouse click successfully completes, globally.
Parameters
_event
The interaction source and completed target.
Returns
void
Inherited from
onSelectEnd()
onSelectEnd(
_event):void
Defined in: src/core/Script.ts:139
Called whenever pinch / mouse click discontinues, globally.
Parameters
_event
The completed state and end reason.
Returns
void
Inherited from
onSelecting()
onSelecting(
_event):void
Defined in: src/core/Script.ts:150
Called whenever pinch / mouse click is happening, globally.
Parameters
_event
Returns
void
Inherited from
onSelectStart()
onSelectStart(
_event):void
Defined in: src/core/Script.ts:133
Called whenever pinch / mouse click starts, globally.
Parameters
_event
The interaction source and optional captured target.
Returns
void
Inherited from
onSimulatorStarted()
onSimulatorStarted():
void
Defined in: src/core/Script.ts:125
Returns
void
Inherited from
VideoStream.onSimulatorStarted
onSqueeze()
onSqueeze(
_event):void
Defined in: src/core/Script.ts:182
Called whenever gamepad trigger successfully completes, globally.
Parameters
_event
event.source.controller identifies the controller.
Returns
void
Inherited from
onSqueezeEnd()
onSqueezeEnd(
_event):void
Defined in: src/core/Script.ts:171
Called whenever gamepad trigger stops, globally.
Parameters
_event
event.source.controller identifies the controller.
Returns
void
Inherited from
onSqueezeStart()
onSqueezeStart(
_event):void
Defined in: src/core/Script.ts:166
Called whenever gamepad trigger starts, globally.
Parameters
_event
event.source.controller identifies the controller.
Returns
void
Inherited from
onSqueezing()
onSqueezing(
_event):void
Defined in: src/core/Script.ts:176
Called whenever gamepad is being triggered, globally.
Parameters
_event
Returns
void
Inherited from
onXRSessionEnded()
onXRSessionEnded():
void
Defined in: src/camera/XRDeviceCamera.ts:718
Returns
void
Overrides
onXRSessionStarted()
onXRSessionStarted(
_session?):void
Defined in: src/core/Script.ts:122
Parameters
_session?
Returns
void
Inherited from
VideoStream.onXRSessionStarted
physicsStep()
physicsStep():
void
Defined in: src/core/Script.ts:120
Returns
void
Inherited from
registerSimulatorCamera()
registerSimulatorCamera(
simulatorCamera?):void
Defined in: src/camera/XRDeviceCamera.ts:541
Parameters
simulatorCamera?
SimulatorCameraSource
Returns
void
setDeviceId()
setDeviceId(
deviceId):Promise<void>
Defined in: src/camera/XRDeviceCamera.ts:317
Sets the active camera by its device ID. Removes potentially conflicting constraints such as facingMode.
Parameters
deviceId
string
Device ID
Returns
Promise<void>
setFacingMode()
setFacingMode(
facingMode):Promise<void>
Defined in: src/camera/XRDeviceCamera.ts:337
Sets the active camera by its facing mode ('user' or 'environment').
Parameters
facingMode
VideoFacingModeEnum
facing mode
Returns
Promise<void>
setRenderer()
setRenderer(
renderer):void
Defined in: src/camera/XRDeviceCamera.ts:133
Sets the renderer reference, needed for WebXR camera access fallback.
Parameters
renderer
Returns
void
setState_()
protectedsetState_(state,details):void
Defined in: src/video/VideoStream.ts:155
Sets the stream's state and dispatches a 'statechange' event.
Parameters
state
The new state.
details
Additional data for the event payload.
VideoStreamDetails | XRDeviceCameraDetails
Returns
void
Inherited from
snapshotSourceAvailable_()
protectedsnapshotSourceAvailable_():boolean
Defined in: src/camera/XRDeviceCamera.ts:448
Whether the current snapshot source has pixels available. Subclasses may override this to provide non-video sources while preserving getSnapshot's format handling.
Returns
boolean
Overrides
VideoStream.snapshotSourceAvailable_
stop_()
protectedstop_():void
Defined in: src/video/VideoStream.ts:343
Stops the current video stream tracks.
Returns
void
Inherited from
update()
update(
_time?,_frame?):void
Defined in: src/core/Script.ts:114
Runs per frame.
Parameters
_time?
number
_frame?
Returns
void
Inherited from
updateXRCamera()
updateXRCamera(
frame):void
Defined in: src/camera/XRDeviceCamera.ts:477
Updates the camera texture from the WebXR Raw Camera Access API. Must be called each frame from the render loop when in XR camera mode.
Parameters
frame
Returns
void
waitForFreshFrame()
waitForFreshFrame(
timeoutMs):Promise<VideoFrameMetadata|null>
Defined in: src/video/VideoStream.ts:216
Waits for the next new video frame before returning, so a subsequent
getSnapshot reads fresh pixels instead of whatever (possibly
stale) frame the <video> element currently holds. Hidden or
non-composited video elements — the normal situation inside an immersive
XR session — can be throttled by the browser, in which case the held
frame may be arbitrarily old.
Resolves with the frame's metadata (whose captureTime, when present,
dates the pixels in the performance.now() timebase), or null when the
signal is unavailable (requestVideoFrameCallback unsupported, no active
media stream) or no frame arrived within timeoutMs.
Parameters
timeoutMs
number = 400
Returns
Promise<VideoFrameMetadata | null>