Add WebXR Hit Test reference docs - pt 1 (#8042)

* Add WebXR Hit Test reference docs - pt 1 * Apply suggestions from code review Co-authored-by: Joe Medley <[email protected]> * Remove unstable entityTypes from code example Co-authored-by: Joe Medley <[email protected]>
mdn · Aug 19, 2021 · b8962e5 · b8962e5
1 parent a2e7e2e
commit b8962e5
Show file tree

Hide file tree

Showing 4 changed files with 199 additions and 0 deletions.
diff --git a/files/en-us/web/api/xrsession/index.md b/files/en-us/web/api/xrsession/index.md
@@ -52,6 +52,10 @@ _`XRSession` provides the following methods in addition to those inherited from
   - : Ends the WebXR session. Returns a {{jsxref("promise")}} which resolves when the session has been shut down.
 - {{DOMxRef("XRSession.requestAnimationFrame", "requestAnimationFrame()")}}
   - : Schedules the specified method to be called the next time the {{glossary("user agent")}} is working on rendering an animation frame for the WebXR device. Returns an integer value which can be used to identify the request for the purposes of canceling the callback using `cancelAnimationFrame()`. This method is comparable to the {{domxref("Window.requestAnimationFrame()")}} method.
+- {{DOMxRef("XRSession.requestHitTestSource", "requestHitTestSource()")}}
+  - : Requests an {{domxref("XRHitTestSource")}} object that handles hit test subscription.
+- {{DOMxRef("XRSession.requestHitTestSourceForTransientInput", "requestHitTestSourceForTransientInput()")}}
+  - : Requests an {{domxref("XRTransientInputHitTestSource")}} object that handles hit test subscription for a transient input source.
 - {{DOMxRef("XRSession.requestLightProbe", "requestLightProbe()")}}
   - : Requests an {{domxref("XRLightProbe")}} that estimates lighting information at a given point in the user's environment.
 - {{DOMxRef("XRSession.requestReferenceSpace", "requestReferenceSpace()")}}

diff --git a/files/en-us/web/api/xrsession/requesthittestsource/index.md b/files/en-us/web/api/xrsession/requesthittestsource/index.md
@@ -0,0 +1,96 @@
+---
+title: XRSession.requestHitTestSource()
+slug: Web/API/XRSession/requestHitTestSource
+tags:
+  - API
+  - AR
+  - Augmented Reality
+  - Experimental
+  - Method
+  - Reference
+  - VR
+  - Virtual Reality
+  - WebXR
+  - WebXR Device API
+  - XR
+  - XRSession
+browser-compat: api.XRSession.requestHitTestSource
+---
+{{APIRef("WebXR Device API")}}
+
+The **`requestHitTestSource()`** method of the
+{{domxref("XRSession")}} interface returns a {{jsxref("Promise")}} that resolves with an {{domxref("XRHitTestSource")}} object that can be passed to {{domxref("XRFrame.getHitTestResults()")}}.
+
+## Syntax
+
+```js
+requestHitTestSource(options);
+```
+
+### Parameters
+
+- `options`
+  - : An object containing configuration options, specifically:
+    - `space`: The {{domxref("XRSpace")}} that will be tracked by the hit test source.
+    - `entityTypes`: {{optional_inline}} An {{jsxref("Array")}} specifying the types of entities to be used for hit test source creation. If no no entity type is specified, the array defaults to a single element with the `plane` 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_inline}} The {{domxref("XRRay")}} object that will be used to perform hit test. If no `XRRay` object has been provided, a new `XRRay` object is constructed without any parameters.
+
+### Return value
+
+A {{jsxref("Promise")}} that resolves with an {{domxref("XRHitTestSource")}} object.
+
+### Exceptions
+
+Rather than throwing true exceptions, `requestHitTestSource()` rejects the
+returned promise with a {{domxref("DOMException")}}, specifically, one of the following:
+
+- `NotSupportedError`
+  - : If `hit-test` is not an enabled feature in {{domxref("XRSystem.requestSession()")}}.
+- `InvalidStateError`
+  - : If the session has already ended.
+- `NotAllowedError`
+  - : 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 {{domxref("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 {{domxref("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
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("XRSession.requestHitTestSourceForTransientInput()")}}
diff --git a/files/en-us/web/api/xrsession/requesthittestsourcefortransientinput/index.md b/files/en-us/web/api/xrsession/requesthittestsourcefortransientinput/index.md
@@ -0,0 +1,96 @@
+---
+title: XRSession.requestHitTestSourceForTransientInput()
+slug: Web/API/XRSession/requestHitTestSourceForTransientInput
+tags:
+  - API
+  - AR
+  - Augmented Reality
+  - Experimental
+  - Method
+  - Reference
+  - VR
+  - Virtual Reality
+  - WebXR
+  - WebXR Device API
+  - XR
+  - XRSession
+browser-compat: api.XRSession.requestHitTestSourceForTransientInput
+---
+{{APIRef("WebXR Device API")}}
+
+The **`requestHitTestSourceForTransientInput()`** method of the
+{{domxref("XRSession")}} interface returns a {{jsxref("Promise")}} that resolves with an {{domxref("XRTransientInputHitTestSource")}} object that can be passed to {{domxref("XRFrame.getHitTestResultsForTransientInput()")}}.
+
+## Syntax
+
+```js
+requestHitTestSourceForTransientInput(options);
+```
+
+### Parameters
+
+- `options`
+  - : An object containing configuration options, specifically:
+    - `profile`: A string specifying the [input profile name](/en-US/docs/Web/API/XRInputSource) of the transient input source that will be used to compute hit test results.
+    - `entityTypes`: {{optional_inline}} An {{jsxref("Array")}} specifying the types of entities to be used for hit test source creation. If no no entity type is specified, the array defaults to a single element with the `plane` 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_inline}} The {{domxref("XRRay")}} object that will be used to perform hit test. If no `XRRay` object has been provided, a new `XRRay` object is constructed without any parameters.
+
+### Return value
+
+A {{jsxref("Promise")}} that resolves with an {{domxref("XRTransientInputHitTestSource")}} object.
+
+### Exceptions
+
+Rather than throwing true exceptions, `requestHitTestSourceForTransientInput()` rejects the
+returned promise with a {{domxref("DOMException")}}, specifically, one of the following:
+
+- `NotSupportedError`
+  - : If `hit-test` is not an enabled feature in {{domxref("XRSystem.requestSession()")}}.
+- `InvalidStateError`
+  - : If the session has already ended.
+- `NotAllowedError`
+  - : If there is an unreasonable amount of requests. Some user agents might limit usage for privacy reasons.
+
+## Examples
+
+### Requesting a transient hit test source
+
+To request a hit test source, start an {{domxref("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 {{domxref("XRFrame.getHitTestResultsForTransientInput()")}} to obtain the result.
+
+```js
+
+const xrSession = navigator.xr.requestSession("immersive-ar", {
+   requiredFeatures: ["local", "hit-test"]
+});
+
+let transientHitTestSource = null;
+
+xrSession.requestHitTestSourceForTransientInput({
+  space : "generic-touchscreen",
+  offsetRay : new XRRay()
+}).then((touchScreenHitTestSource) => {
+  transientHitTestSource = touchScreenHitTestSource;
+});
+
+// frame loop
+function onXRFrame(time, xrFrame) {
+  let hitTestResults = xrFrame.getHitTestResultsForTransientInput(transientHitTestSource);
+
+  // do things with the transient hit test results
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("XRSession.requestHitTestSource()")}}
diff --git a/files/en-us/web/api/xrsystem/requestsession/index.md b/files/en-us/web/api/xrsystem/requestsession/index.md
@@ -99,6 +99,8 @@ following:
   - : Enable the ability to obtain depth information using {{domxref("XRDepthInformation")}} objects.
 - `dom-overlay`
   - : Enable allowing to specify a DOM overlay element that will be displayed to the user.
+- `hit-test`
+  - : Enable hit testing features for performing hit tests against real world geometry.
 - `light-estimation`
   - : Enable the ability to estimate environmental lighting conditions using {{domxref("XRLightEstimate")}} objects.
 - `local`
@@ -120,6 +122,7 @@ Each reference space or feature type has minimum safety requirements. By session
 | --------------- | ----------------------------------- | -------------------------- |
 | `bounded-floor` | Always required                     | `xr-spatial-tracking`      |
 | `depth-sensing` | —                                   | `xr-spatial-tracking`      |
+| `hit-test`      | —                                   | `xr-spatial-tracking`      |
 | `local`         | Always required for inline sessions | `xr-spatial-tracking`      |
 | `local-floor`   | Always required                     | `xr-spatial-tracking`      |
 | `unbounded`     | Always required                     | `xr-spatial-tracking`      |