XRSession: requestHitTestSource() method
Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.
The requestHitTestSource()
method of the
XRSession
interface returns a Promise
that resolves with an XRHitTestSource
object that can be passed to XRFrame.getHitTestResults()
.
Syntax
js
requestHitTestSource(options)
Parameters
options
-
An object containing configuration options, specifically:
space
-
The
XRSpace
that will be tracked by the hit test source. entityTypes
Optional-
An
Array
specifying the types of entities to be used for hit test source creation. If no entity type is specified, the array defaults to a single element with theplane
type. Possible types:point
: Compute hit test results based on characteristic points detected.plane
: Compute hit test results based on real-world planes detected.mesh
: Compute hit test results based on meshes detected.
offsetRay
Optional-
The
XRRay
object that will be used to perform hit test. If noXRRay
object has been provided, a newXRRay
object is constructed without any parameters.
Return value
A Promise
that resolves with an XRHitTestSource
object.
Exceptions
Rather than throwing true exceptions, requestHitTestSource()
rejects the
returned promise with a DOMException
, specifically, one of the following:
NotSupportedError
DOMException
-
Thrown if
hit-test
is not an enabled feature inXRSystem.requestSession()
. InvalidStateError
DOMException
-
Thrown if the session has already ended.
NotAllowedError
DOMException
-
Thrown if there is an unreasonable amount of requests. Some user agents might limit usage for privacy reasons.
Examples
Requesting a hit test source
To request a hit test source, start an XRSession
with the hit-test
session feature enabled. Next, configure the hit test source and store it for later use in the frame loop and call XRFrame.getHitTestResults()
to obtain the result.
js
const xrSession = navigator.xr.requestSession("immersive-ar", {
requiredFeatures: ["local", "hit-test"],
});
let hitTestSource = null;
xrSession
.requestHitTestSource({
space: viewerSpace, // obtained from xrSession.requestReferenceSpace("viewer");
offsetRay: new XRRay({ y: 0.5 }),
})
.then((viewerHitTestSource) => {
hitTestSource = viewerHitTestSource;
});
// frame loop
function onXRFrame(time, xrFrame) {
let hitTestResults = xrFrame.getHitTestResults(hitTestSource);
// do things with the hit test results
}
Specifications
Specification |
---|
WebXR Hit Test Module # dom-xrsession-requesthittestsource |
Browser compatibility
BCD tables only load in the browser