XRSession: requestHitTestSourceForTransientInput() method

Limited availability

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

Experimental:This is anexperimental technology
Check theBrowser compatibility table carefully before using this in production.

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

TherequestHitTestSourceForTransientInput() method of theXRSession interface returns aPromise that resolves with anXRTransientInputHitTestSource object that can be passed toXRFrame.getHitTestResultsForTransientInput().

Syntax

requestHitTestSourceForTransientInput(options)

Parameters

options

An object containing configuration options, specifically:

profile

A string specifying theinput profile name of the transient input source that will be used to compute hit test results.

entityTypesOptional

AnArray 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.

offsetRayOptional

TheXRRay 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

APromise that resolves with anXRTransientInputHitTestSource object.

Exceptions

Rather than throwing true exceptions,requestHitTestSourceForTransientInput() rejects thereturned promise with aDOMException, specifically, one of the following:

NotSupportedErrorDOMException: Thrown ifhit-test is not an enabled feature inXRSystem.requestSession().
InvalidStateErrorDOMException: Thrown if the session has already ended.
NotAllowedErrorDOMException: Thrown if there is an unreasonable amount of requests. Some user agents might limit usage for privacy reasons.

To request a hit test source, start anXRSession with thehit-test session feature enabled. Next, configure the hit test source and store it for later use in the frame loop and callXRFrame.getHitTestResultsForTransientInput() to obtain the result.

const xrSession = navigator.xr.requestSession("immersive-ar", {  requiredFeatures: ["local", "hit-test"],});let transientHitTestSource = null;xrSession  .requestHitTestSourceForTransientInput({    profile: "generic-touchscreen",    offsetRay: new XRRay(),  })  .then((touchScreenHitTestSource) => {    transientHitTestSource = touchScreenHitTestSource;  });// frame loopfunction onXRFrame(time, xrFrame) {  let hitTestResults = xrFrame.getHitTestResultsForTransientInput(    transientHitTestSource,  );  // do things with the transient hit test results}