diff --git a/hit-testing-explainer.md b/hit-testing-explainer.md index 851b468..39098bc 100644 --- a/hit-testing-explainer.md +++ b/hit-testing-explainer.md @@ -75,19 +75,47 @@ The `XRSession.requestHitTestSourceForTransientInput()` method accepts a diction * `offsetRay` is optional and specifies an `XRRay` for which the hit test should be performed. The ray will be interpreted as if relative to `targetRaySpace` of the transient input source that matches `targetRayMode`. ### Hit test results -To get synchronous hit test results for a particular frame, developers call `XRFrame.getHitTestResults()` passing in a `XRHitTestSource` as the `hitTestSource` parameter. This function will return a `FrozenArray` in which `XRHitTestResult`s are ordered by distance from the `XRHitTestSource`, with the nearest in the 0th position. If no results exist, the array will have a length of zero. The `XRHitTestResult` interface will expose a method, `getPose(XRSpace baseSpace)` that can be used to query the result's pose. If, in the current frame, the relationship between `XRSpace` passed in to `baseSpace` parameter cannot be located relative to the hit test result, the function will return `null`. +To get synchronous hit test results for a particular frame, developers call `XRFrame.getHitTestResults()` passing in a `XRHitTestSource` as the `hitTestSource` parameter. This function will return a `FrozenArray` in which `XRHitTestResult`s are ordered by distance along the `XRRay` used to perform the hit test, with the nearest in the 0th position. If no results exist, the array will have a length of zero. The `XRHitTestResult` interface will expose a method, `getPose(XRSpace baseSpace)` that can be used to query the result's pose. If, in the current frame, the relationship between `XRSpace` passed in to `baseSpace` parameter cannot be located relative to the hit test result, the function will return `null`. ```js +// Input source returned from a call to XRSession.requestHitTestSource(...): +let hitTestSource = ...; + function updateScene(timestamp, xrFrame) { // Scene update logic ... - let hitTestResults = xrFrame.getHitTestResults(hitTestSources[preferredInputSource]); - if (hitTestResults && hitTestResults.length > 0) { + let hitTestResults = xrFrame.getHitTestResults(hitTestSource); + if (hitTestResults.length > 0) { // Do something with the results } // Other scene update logic ... } ``` +In order to obtain hit test results for transient input source hit test subscriptions in a particular frame, developers call `XRFrame.getHitTestResultsForTransientInput()` passing in a `XRTransientInputHitTestSource` as the `hitTestSource` parameter. This function will return a `FrozenArray`. Each element of the array will contain an instance of the input source that was used to obtain the results, and the actual hit test results will be contained in `FrozenArray results`, ordered by the distance along the ray used to perform the hit test, with the closest result at 0th position. + +```js +// Input source returned from a call to +// XRSession.requestHitTestSourceForTransientInput(...): +let transientInputHitTestSource = ...; + +function updateScene(timestamp, xrFrame) { + // Scene update logic ... + let hitTestResultsPerInputSource = xrFrame.getHitTestResultsForTransientInput(transientInputHitTestSource); + + hitTestResultsPerInputSource.forEach(resultsPerInputSource => { + if(!isInteresting(resultsPerInputSource.inputSource)) { + return; // Application can perform additional + // filtering based on the input source. + } + + if (resultsPerInputSource.results.length > 0) { + // Do something with the results + } + }); + // Other scene update logic ... +} +``` + #### Rays An `XRRay` object includes both an `origin` and `direction`, both given as `DOMPointReadOnly`s. The `origin` represents a 3D coordinate in space with a `w` component that must be equal to 1, and the `direction` represents a normalized 3D directional vector with a `w` component that must be equal to 0. The `XRRay` also defines a `matrix` which represents the transform from a ray originating at `[0, 0, 0]` and extending down the negative Z axis to the ray described by the `XRRay`'s `origin` and `direction`. This is useful for positioning graphical representations of the ray. @@ -128,18 +156,19 @@ This is a partial IDL and is considered additive to the core IDL found in the ma // partial interface XRSession { Promise requestHitTestSource(XRHitTestOptionsInit options); - Promise requestHitTestSourceForTransientInput(XRTransientInputHitTestOptionsInit options); + Promise requestHitTestSourceForTransientInput(XRTransientInputHitTestOptionsInit options); }; // // Frame // partial interface XRFrame { - FrozenArray? getHitTestResults(XRHitTestSource hitTestSource); + FrozenArray getHitTestResults(XRHitTestSource hitTestSource); + FrozenArray getHitTestResultsForTransientInput(XRHitTestSource hitTestSource); }; // -// Hit Testing +// Hit Testing Options // dictionary XRHitTestOptionsInit { required XRSpace space; @@ -151,10 +180,28 @@ dictionary XRTransientInputHitTestOptionsInit { XRRay offsetRay = new XRRay(); }; +// +// Hit Test Sources +// + [SecureContext, Exposed=Window] interface XRHitTestSource { }; +[SecureContext, Exposed=Window] +interface XRTransientInputHitTestSource { +}; + +// +// Hit Test Results +// + +[SecureContext, Exposed=Window] +interface XRTransientInputHitTestResult { + XRInputSource inputSource; + FrozenArray results; +}; + [SecureContext, Exposed=Window] interface XRHitTestResult { XRPose? getPose(XRSpace baseSpace);