XRViewerPose

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Secure context: This feature is available only insecure contexts (HTTPS), in some or allsupporting browsers.

The WebXR Device API interfaceXRViewerPose represents the pose (the position and orientation) of a viewer's point of view on the scene. EachXRViewerPose can have multiple views to represent, for example, the slight separation between the left and right eye.

This view can represent anything from the point-of-view of a user's XR headset to the viewpoint represented by a player's movement of an avatar using mouse and keyboard, presented on the screen, to a virtual camera capturing the scene for a spectator.

Instance properties

In addition to the properties inherited fromXRPose,XRViewerPose includes the following:

viewsRead only: An array ofXRView objects, one for each viewpoint on the scene which is needed to represent the scene to the user. A typical headset provides a viewer pose with two views whoseeye property is eitherleft orright, indicating which eye that view represents. Taken together, these views can reproduce the 3D effect when displayed on the XR device.

Usage notes

TheXRViewerPose object is used to describe the state of a viewer of a WebXR scene as it's tracked by the user's XR hardware. The viewer may be the virtual representation of the user, or it may represent another device or interface which may serve as the source of a position and orientation that make up a view upon the scene. For example, every player in a MMORPG might have an instance ofXRViewerPose to provide a way to calculate what they can see; if the game provides a mechanism that tells the player if another player sees them, or that they see another player, this information becomes crucial.

AnXRViewerPose is always obtained and referenced relative to an existingXRReferenceSpace. This ensures that positions and orientations are reported using the expected relative coordinate system.

To render a scene using theXRViewerPose representing the user's head, one would iterate over the views in theviews array, rendering them one after another. By callingviewport() on the WebGL context, specifying theXRView as input, you can get the viewport to use when rendering in order to draw the frame for that eye into the correct part of the drawing surface.

Also, when rendering the scene for spectators or other players in a multiplayer game, thetransform of theXRViewerPose can be used to determine both placement and facing direction of the other players in the game, so that they can be drawn in the correct place with the correct facing.

The viewer's pose for the animation frame represented byXRFrame can be obtained by calling the frame'sgetViewerPose() method, specifying the reference space in which the origin's position should be computed. The returnedXRViewerPose tells you where the viewer is and what direction they're facing at the time at which the frame takes place.

Examples

In this example—part of the code to render anXRFrame,getViewerPose() is called to get anXRViewerPose using thesame reference space the code is using as its base reference space. If a valid pose isreturned, the frame is rendered by clearing the backbuffer and then rendering each ofthe views in the pose; these are most likely the views for the left and right eyes.

const pose = frame.getViewerPose(xrReferenceSpace);if (pose) {  const glLayer = xrSession.renderState.baseLayer;  gl.bindFrameBuffer(gl.FRAMEBUFFER, glLayer.framebuffer);  gl.clearColor(0, 0, 0, 1);  gl.clearDepth(1);  gl.clear(gl.COLOR_BUFFER_BIT, gl.DEPTH_BUFFER_BIT);  for (const view of pose.views) {    const viewport = glLayer.getViewport(view);    gl.viewport(viewport.x, viewport.y, viewport.width, viewport.height);    /* render the scene for the eye view.eye */  }}

Passing eachview togetViewport() returns the WebGL viewport to apply in order to cause the renderedoutput to be positioned correctly in the framebuffer for rendering to the corresponding eye on the output device.

This code is derived fromDrawing a frame in our "Movement and motion" WebXR example.You can see more context and see much more on that page.