XRSession: updateRenderState() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The updateRenderState()
method of the XRSession
interface of the WebXR API schedules changes to be applied to the active render state (XRRenderState
) prior to rendering of the next frame.
Syntax
js
updateRenderState()
updateRenderState(state)
Parameters
state
Optional-
An optional object to configure the
XRRenderState
. If none is provided, a default configuration will be used.baseLayer
Optional: AnXRWebGLLayer
object from which the WebXR compositor will obtain imagery. This isnull
by default. To specify other (or multiple) layers, see thelayers
option.depthFar
Optional: A floating-point value specifying the distance in meters from the viewer to the far clip plane, which is a plane parallel to the display surface beyond which no further rendering will occur. All rendering will take place between the distances specified bydepthNear
anddepthFar
. This is 1000 meters (1 kilometer) by default.depthNear
Optional: A floating-point value indicating the distance in meters from the viewer to a plane parallel to the display surface to be the near clip plane. No part of the scene on the viewer's side of this plane will be rendered. This is 0.1 meters (10 centimeters) by default.inlineVerticalFieldOfView
Optional: A floating-point value indicating the default field of view, in radians, to be used when computing the projection matrix for aninline
XRSession
. The projection matrix calculation also takes into account the output canvas's aspect ratio. This property must not be specified for immersive sessions, so the value isnull
by default for immersive sessions. The default value is otherwise π * 0.5 (half of the value of pi).layers
Optional: An ordered array ofXRLayer
objects specifying the layers that should be presented to the XR device. Settinglayers
will override thebaseLayer
if one is present, withbaseLayer
reportingnull
. The order of the layers given is "back-to-front". For alpha blending of layers, see theXRCompositionLayer.blendTextureSourceAlpha
property.
Return value
None (undefined
).
Exceptions
InvalidStateError
DOMException
-
Thrown in any of the following situations:
- The
XRSession
has already ended, so you cannot change its render state. - The
baseLayer
was created by anXRSession
other than the one on whichupdateRenderState()
was called. - The
inlineVerticalFieldOfView
option was set, but the session is immersive, and therefore, does not allow this property to be used.
- The
NotSupportedError
DOMException
-
Thrown in any of the following situations:
- The
layers
option is used in a session that has been created without thelayers
feature. - Both the
baseLayer
andlayers
options are specified.
- The
TypeError
-
Thrown if the
layers
option contains duplicate instances.
Examples
Adding a baseLayer
This example creates a WebGL context that is compatible with an immersive XR device and then uses it to create an XRWebGLLayer
. The method updateRenderState()
is then called to associate the new XRWebGLLayer
.
js
function onXRSessionStarted(xrSession) {
let glCanvas = document.createElement("canvas");
let gl = glCanvas.getContext("webgl", { xrCompatible: true });
loadWebGLResources();
xrSession.updateRenderState({
baseLayer: new XRWebGLLayer(xrSession, gl),
});
}
Setting the layers
array
To use WebXR layers, the XR session needs to be created with the layers
feature descriptor (see XRSystem.requestSession()
). You can then create various WebXR layers such as
Other layers, such as XRProjectionLayer
or XRWebGLLayer
are also available.
Layers will be presented in the order they are given in the layers
array, with layers being given in "back-to-front" order.
js
const xrSession = navigator.xr.requestSession("immersive-ar", {
optionalFeatures: ["layers"],
});
function onXRSessionStarted(xrSession) {
const glCanvas = document.createElement("canvas");
const gl = glCanvas.getContext("webgl", { xrCompatible: true });
const xrGlBinding = new XRWebGLBinding(xrSession, gl);
const projectionLayer = new XRWebGLLayer(xrSession, gl);
const quadLayer = xrGlBinding.createQuadLayer({
pixelWidth: 1024,
pixelHeight: 1024,
});
xrSession.updateRenderState({
layers: [projectionLayer, quadLayer],
});
}
Specifications
Specification |
---|
WebXR Device API # dom-xrsession-updaterenderstate |
Browser compatibility
BCD tables only load in the browser