WebXR Depth Sensing Module を使って Occlusion してみた

# はじめに

先日、株式会社 STYLY にて社内ハッカソンが開催されました。お題は自由ということだったので、どうしようかなと思っていたところ、去年の 12 月に X にて、このようなポストを見かけたのを思い出しました。

https://twitter.com/rcabanier/status/1735419174791319829

内容はフラグを有効化すれば Quest のブラウザで Occlusion ができるというものです。
11 月頃に Depth Sensing を試そうとした時は、エラーで使えなくてしょんぼりしていたのですが、確かにエラーが出ないようになっていたので、本格的に WebXR Depth Sensing Module を触ってみることにしました！

そしてできたものがこちらになります！！

https://x.com/shilaca_/status/1752172482151506345?s=20

以下のサイトで実際に動いているところを見ることができます。

[Demo サイト](https://webxr-depth-occlusion.shilaca.me/)

:::note warn
Demo サイトは現在(2024.01) Android でしか動作しません。

Quest のブラウザで動作させたかったのですが、うまく depth sensing から texture を取得することができませんでした（出来次第更新しようと思っております）。

この記事の内容は `cpu-optimized` + `luminance-alpha` の組み合わせで動くものになっております。

また WebXR Device API, WebXR Depth Sensing Module 共に標準化には至っていません。
WebXR Depth Sensing Module については Demo サイト実装時点では草案段階です。
そのためこの記事の内容は動かなくなる可能性があります。
:::

# WebXR Depth Sensing Module を使って Occlusion するまでの流れ

Rendering 方法はよくある Post Processing と同じ流れで Occlusion を実現してみました。

手順は以下です。

1. WebXR の baseLayer の framebuffer とは別に framebuffer を用意
2. framebuffer に通常のシーンをレンダリング
3. Depth Sensing Module から depth data が入った WebGLTexture を取得
4. baseLayer に 2 の depth buffer と 3 で作成した texture を比較して 2 の color buffer を出力

![Occlusion の流れ](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3584802/5fd34d31-ee2c-56a1-52bb-79bbe5dc4aba.jpeg)

# いざ、実装！

WebXR Device API や WebXR Depth Sensing Module の仕様について、一番正しいのは W3C の仕様書です。こちらを適宜確認しながら実装を進めます。
また実装時点では仕様書は Draft 状態でしたので仕様が変更になっている可能性があります。

https://immersive-web.github.io/webxr/

https://www.w3.org/TR/webxr-depth-sensing-1/#support-depth-sensing-usage

## WebXR Depth Sensing Module を有効化する

`navigator.xr.requestSession` の requiredFeatures (or optionalFeatures) で `depth-sensing` を指定すると共に、 `depthSensing` option にリクエストする使用方法やデータ形式を指定することで有効化できます。

requiredFeatures と optionalFeatures の違いとしては、指定した機能が端末のブラウザ（以降ユーザーエージェント）上で対応していない場合、前者ではエラーが投げられ、後者では warning が console に表示される（エラーは発生しない）という違いがあります。

```typescript
const session = await navigator.xr.requestSession("immersive-ar", {
  requiredFeatures: ["depth-sensing"],
  depthSensing: {
    usagePreference: ["cpu-optimized", "gpu-optimized"],
    dataFormatPreference: ["luminance-alpha", "float32"],
  },
});
```

depthSensing Option で指定する各パラメーターはでは、深度情報をどのように扱うかを指定します。

`usagePreference` では深度情報が CPU か GPU どちらで使用されることを意図しているか指定でき、`dataFormatPreference` では深度情報のデータの形式を指定できます。

それぞれのデータフォーマットが CPU や GPU でどのように振る舞うのかについては仕様書に表が用意されていました。

> https://www.w3.org/TR/webxr-depth-sensing-1/#usage-and-formats
>
> ![W3C, WebXR Depth Sensing の Intended data usage and data formats より](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3584802/9205dd61-de1d-70e0-dd3e-6c34310b1304.png)

ユーザーエージェントによってサポートされている使用方法やデータ形式は異なります。それぞれ片方しかサポートしていなかったりします。

W3C の仕様書によると `requestSession` の `depthSensing` で指定したものがサポートされていない場合はエラーが投げられるとありますが、 Quest3 では特にエラーは発生せず、こちらの指定とは関係なしに起動していました（Android ではちゃんとエラーが発生しました）。

> https://www.w3.org/TR/webxr-depth-sensing-1/#session-configuration

私が確認した各端末の対応フォーマットなどは以下のようになっていました。

|  端末   |  depthUsage   | depthDataFormat |
| :-----: | :-----------: | :-------------: |
| Android | cpu-optimized | luminance-alpha |
| Quest3  | gpu-optimized |     float32     |

`depthSensing` が有効な `XRSession` には以下のメソッドが追加されるので Depth の使用方法やデータ形式を確認することができます。

```typescript
console.log("depth usage:", session.depthUsage);
console.log("depth format: ", session.depthDataFormat);
```

## BaseLayer とは別に framebuffer を用意する

Depth Sensing を有効化することができたので次のステップ framebuffer の作成をしていきます。

レンダリング結果として Color Buffer と Depth Buffer の情報を扱いたいのでそれぞれ texture を作成し、作成した framebuffer の Color Buffer と Depth Buffer にアタッチします。

```typescript:framebuffer を作成する関数
export const createFramebuffer = (
  gl: WebGL2RenderingContext,
  width: number,
  height: number
) => {
  const framebuffer = gl.createFramebuffer();
  gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);

  const colorTexture = gl.createTexture();
  gl.bindTexture(gl.TEXTURE_2D, colorTexture);
  gl.texImage2D(
    gl.TEXTURE_2D,
    0,
    gl.RGBA,
    width,
    height,
    0,
    gl.RGBA,
    gl.UNSIGNED_BYTE,
    null
  );
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
  gl.framebufferTexture2D(
    gl.FRAMEBUFFER,
    gl.COLOR_ATTACHMENT0,
    gl.TEXTURE_2D,
    colorTexture,
    0
  );

  const depthTexture = gl.createTexture();
  gl.bindTexture(gl.TEXTURE_2D, depthTexture);
  gl.texImage2D(
    gl.TEXTURE_2D,
    0,
    gl.DEPTH_COMPONENT16,
    width,
    height,
    0,
    gl.DEPTH_COMPONENT,
    gl.UNSIGNED_SHORT,
    null
  );
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
  gl.framebufferTexture2D(
    gl.FRAMEBUFFER,
    gl.DEPTH_ATTACHMENT,
    gl.TEXTURE_2D,
    depthTexture,
    0
  );

  return { framebuffer, colorTexture, depthTexture };
};
```

注意しないといけないのは texture のサイズです。
スマートフォンなどディスプレイが 1 枚の場合は Window のサイズで作成してもまあ問題はないのですが、 HMD のように両目にディスプレイがある場合 Window のサイズでは適切なサイズを取得できません。

そこで、それぞれのディスプレイ用の viewport のサイズに合わせた texture を作成することにします。

それぞれのディスプレイの viewport は `XRFrameRequestCallback` の `XRFrame` から `XRViewerPose` を取得し、その中の `XRView` から各 viewport が取得できます。

`requestAnimationFrame` の callback でしか `XRFrame` にアクセスできないので、ループ毎に framebuffer を作成しないように注意しましょう（めっっっちゃ重くなります）。

_ここではスマートフォンか両眼ディスプレイかしか考慮していないので雑に width と height を計算しています。_

```typescript
// reference space について
// https://developer.mozilla.org/ja/docs/Web/API/WebXR_Device_API/Geometry#%E5%8F%82%E7%85%A7%E7%A9%BA%E9%96%93
const refSpace = await session.requestReferenceSpace("local");

session.requestAnimationFrame(onXRFrame);

let framebuffer = null;

const onXRFrame: XRFrameRequestCallback = (time: number, frame: XRFrame) => {
  session.requestAnimationFrame(onXRFrame);

  const pose = frame.getViewerPose(refSpace);
  const glLayer = session.renderState.baseLayer;

  // 複数回作成しないように注意
  if (!framebuffer) {
    // width と height を計算する
    // HMD における viewport(x, y, width, height) の値は以下のようになる(仮の値です)
    // 左目: (0, 0, 200, 200)
    // 右目: (0, 200, 0, 0)
    // ここでは単純に width を足している
    const [w, h] = pose.views.reduce(
      (acc, cur) => {
        // baseLayer における各 view の viewport を取得する
        const vp = glLayer.getViewport(cur);
        if (vp) {
          acc[0] += vp.width;
          acc[1] = vp.height;
        }
        return acc;
      },
      [0, 0]
    );

    // 求めた width と height を使って framebuffer を作成する
    framebuffer = createFramebuffer(_gl, w, h);
  }
};
```

## レンダリング

framebuffer が用意できたところで、レンダリングに入っていきます！
レンダリングも `XRView` 毎に行います。

### 大まかな流れ

コードでのレンダリングの流れは以下です。

```typescript:XRFrameRequestCallback 内で処理
const session = frame.session;

pose.views.forEach((view) => {
  const vp = glLayer.getViewport(view);
  if (vp) {
    gl.viewport(vp.x, vp.y, vp.width, vp.height);

    // 先ほど作成した framebuffer をバインド
    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);

    // clear する
    gl.clearColor(0.0, 0.0, 0.0, 0.0);
    gl.clearDepth(1.0);
    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);

    // 普通にシーンをレンダリングする
    draw(gl, frame, view);

    // baseLayer の framebuffer をバインド
    gl.bindFramebuffer(gl.FRAMEBUFFER, glLayer.framebuffer);

    // clear する
    gl.clearColor(0.0, 0.0, 0.0, 0.0);
    gl.clear(gl.COLOR_BUFFER_BIT);

    // Depth Sensing からデータを取得
    const depthData = getDepthData(gl, frame, view);

    // Occlusion する！
    drawOcclusion(gl, framebuffer, depthData, view.eye, ...);
  }
});
```

### 深度情報取得部分について詳しく

取得できる深度情報は `cpu-optimized` と `gpu-optimized` の場合とで違うので注意が必要です。
今回は WebGLTexture として fragment shader に送る必要があるので取得した深度情報をもとに WebGLTexture を作成します。

```typescript
export const getDepthData = (
  gl: WebGL2RenderingContext,
  frame: XRFrame,
  view: XRView
) => {
  const session = frame.session;

  let depthTexture: WebGLTexture | null = null;

  if (session.depthUsage === "cpu-optimized") {
    // cpu-optimized の場合
    // https://www.w3.org/TR/webxr-depth-sensing-1/#xr-cpu-depth-info-section
    // XRFrame から深度情報を取得できる
    const depthInfo = frame.getDepthInformation(view);

    if (depthInfo) {
      const w = depthInfo.width;
      const h = depthInfo.height;

      // 深度情報は depthInfo.data に格納されている
      const _dataArr = new Int16Array(depthInfo.data);
      const dataArr = new Array(w * h);
      for (let i = 0; i < w; i++) {
        for (let j = 0; j < h; j++) {
          // そのままだと縦と横が逆になっており、さらに反転していたので調整
          const _idx = w - 1 - i + j * w;
          const idx = h - 1 - j + i * h;
          // depthInfo.rawValueToMeters を掛けることでメートルに変換できる
          // https://www.w3.org/TR/webxr-depth-sensing-1/#xr-depth-info-section
          dataArr[idx] = _dataArr[_idx] * depthInfo.rawValueToMeters;
        }
      }

      // WebGLTexture に変換するために ImageData に変換する
      const colorArray = dataArr
        .map((val) =>
          val <= 0.0 || val >= 1.0 ? Array(4).fill(1.0) : [val, val, val, 1.0]
        )
        .flat()
        .map((val) => val * 255.0);
      const colorBuffer = new Uint8ClampedArray(colorArray);
      const imageData = new ImageData(colorBuffer, h);

      // WebGLTexture に変換
      depthTexture = gl.createTexture();
      gl.bindTexture(gl.TEXTURE_2D, depthTexture);
      gl.texImage2D(
        gl.TEXTURE_2D,
        0,
        gl.RGBA,
        gl.RGBA,
        gl.UNSIGNED_BYTE,
        imageData
      );
      gl.generateMipmap(gl.TEXTURE_2D);

      rawValueToMeters = depthInfo.rawValueToMeters;
    }
  } else if (session.depthUsage === "gpu-optimized") {
    // gpu-optimized の場合
    // https://www.w3.org/TR/webxr-depth-sensing-1/#xr-gpu-depth-info-section
    // XRWebGLBinding から深度情報を取得できる
    const glBinding = new XRWebGLBinding(session, gl);
    const depthInfo = glBinding.getDepthInformation(view);

    // gpu-optimized の場合は WebGLTexture が取得できる
    // この部分については 2024.01 現在、うまく動作確認ができていません・・・！
    depthTexture = depthInfo.texture;

    rawValueToMeters = depthInfo.rawValueToMeters;
  }

  return {
    depthTexture,
    rawValueToMeters,
  };
};
```

### Occlusion 部分について詳しく

Occlusion 部分のコードです、 js 側では必要な情報を Shader に送る処理を書くくらいであまり変わったことはしていません。

```typescript
const drawOcclusion = (
  gl: WebGL2RenderingContext,
  screenFramebuffer: CustomFramebuffer,
  depthData: DepthData,
  eye: XREye,
  ...
) => {
  // よくある Post Processing の要領で平行投影を用いて画面いっぱいの Plane を生成します
  // ここでは行列の生成に gl-matrix というライブラリを使用しています。
  // https://github.com/toji/gl-matrix
  const projectionMatrix = mat4.create();
  mat4.ortho(projectionMatrix, -1, 1, 1, -1, 0.1, 1);

  const viewMatrix = mat4.create();
  mat4.lookAt(viewMatrix, [0.0, 0.0, 0.5], [0.0, 0.0, 0.0], [0.0, 1.0, 0.0]);

  const modelMatrix = mat4.create();

  setOcclusionPositionAttribute(gl, occlusionBuffers, occlusionProgramInfo);
  setOcclusionTextureCoordAttribute(gl, occlusionBuffers, occlusionProgramInfo);

  gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, occlusionBuffers.indices);

  gl.useProgram(occlusionProgramInfo.program);

  gl.uniformMatrix4fv(
    occlusionProgramInfo.uniformLocations.projectionMatrix,
    false,
    projectionMatrix,
  );
  gl.uniformMatrix4fv(
    occlusionProgramInfo.uniformLocations.viewMatrix,
    false,
    viewMatrix,
  );
  gl.uniformMatrix4fv(
    occlusionProgramInfo.uniformLocations.modelMatrix,
    false,
    modelMatrix,
  );

  // 生成した Plane に今まで生成してきた texture 達を用いて Occlusion するために shader に必要な情報を渡します。

  // color buffer
  gl.activeTexture(gl.TEXTURE0);
  gl.bindTexture(gl.TEXTURE_2D, screenFramebuffer.colorTexture);
  gl.uniform1i(occlusionProgramInfo.uniformLocations.screen, 0);

  // depth buffer
  gl.activeTexture(gl.TEXTURE1);
  gl.bindTexture(gl.TEXTURE_2D, screenFramebuffer.depthTexture);
  gl.uniform1i(occlusionProgramInfo.uniformLocations.screenDepth, 1);

  // depth sensing
  gl.activeTexture(gl.TEXTURE2);
  gl.bindTexture(gl.TEXTURE_2D, depthData.depthTexture);
  gl.uniform1i(occlusionProgramInfo.uniformLocations.depthSensingTexture, 2);

  // shader 側で左右どちらの XRView か判断するための情報です。
  // XRView に eye というプロパティが格納されています。
  const eyeNum = (() => {
    switch (eye) {
      case "left":
        return -1;
      case "right":
        return 1;
      default:
        return 0;
    }
  })();
  gl.uniform1i(occlusionProgramInfo.uniformLocations.eye, eyeNum);

  gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
};
```

vertex shader は gl_Position を計算して、fragment shader に texture の座標を渡しているだけなので、ここでは fragment shader のみみていきます。

難しいことはしていません、レンダリングしたシーンの depth と Depth Sensing で得られた depth とを比較して color を決定します。

```glsl
precision mediump float;

uniform int uEye;
uniform sampler2D uScreen;
uniform sampler2D uScreenDepth;
uniform sampler2D uDepthSensingTexture;

varying highp vec2 vTextureCoord;

void main() {
  vec2 texCoord = vTextureCoord;

  // HMD の場合、右目用と左目用で texture を分割してあげる必要があります。
  if (uEye != 0) {
    texCoord = vec2(texCoord.x / 2.0, texCoord.y);
  }
  if (uEye == 1) {
    texCoord = vec2(texCoord.x + 0.5, texCoord.y);
  }

  vec4 screenColor = texture2D(uScreen,  texCoord);

  float screenDepth = texture2D(uScreenDepth, texCoord).r;
  float sensorDepth = texture2D(uDepthSensingTexture, texCoord).r;

  // 作成した framebuffer の depth と Depth Sensing Module によって取得した depth の値を比較し、
  // 近ければ color buffer の色を、遠ければ透明を渡す。
  gl_FragColor = screenDepth < sensorDepth ? screenColor : vec4(0.0);
}


```

## 完成！

上記の工程を経て無事 Occlusion できました！

![demo.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3584802/b0d66375-e78a-0e6c-b24d-237240c82b94.gif)

繰り返しになりますが、以下のサイトで動いているところを見ることができます。

[Demo サイト](https://webxr-depth-occlusion.shilaca.me/)
_Android のみ動作確認済みです_

# その他 Tips

本編には直接関係ないけど、 WebXR 絡みでちょっと詰まったこと

## TypeScript で書きたいが TypeError や eslint の　 not defined が出てしまうので、どうにかする。

TypeScript で書こうと思うと必ず TypeError の壁にぶち当たります。
仕様が Draft であることもあり、型が準備されていないのです。

でもどうしても TypeScript で書きたい・・・！
そんな時は自分で型を書いてしまいましょう！
幸い W3C の仕様書に型が全部書いてあるのでそれをなぞるだけです！
仕様の理解にもつながるしで一石二鳥！？？

例えば、XRSession の requestSession で depthSensing オプションを追加しようとすると、 `Object literal may only specify known properties, and 'depthSensing' does not exist in type 'XRSessionInit'.` と怒られます。

W3C の仕様書を見に行くと Depth Sensing で追加される型の情報が書いてあります。
https://www.w3.org/TR/webxr-depth-sensing-1/#session-configuration

```2.3. Session configuration より
dictionary XRDepthStateInit {
  required sequence<XRDepthUsage> usagePreference;
  required sequence<XRDepthDataFormat> dataFormatPreference;
};
```

```2.3. Session configuration より
partial dictionary XRSessionInit {
  XRDepthStateInit depthSensing;
};
```

上記の情報をもとに型ファイルを作成すると TypeError が消えます。
_書き間違えると不幸になるので注意しましょう。_

```typescript:WebXR.d.ts
export declare global {
  type XRDepthUsage = "cpu-optimized" | "gpu-optimized";
  type XRDepthDataFormat = "luminance-alpha" | "float32";

  interface XRDepthStateInit {
    usagePreference: XRDepthUsage[];
    dataFormatPreference: XRDepthDataFormat[];
  }

  interface XRSessionInit {
    depthSensing?: XRDepthStateInit;
  }
}
```

ライブラリを使うとライブラリ側でこの辺りも吸収してくれることが多いですが、それでもたまに TypeError に遭遇することがあるので覚えておくと幸せになります。

eslint(flat config)の方は `languageOptions.globals` でプロパティ名を true にしてあげると出なくなります。 globals に定義されていないものは以下の方法で解決できます。
_とはいえ、むやみやたらと握りつぶすのはやめましょう。_

```javascript
const config = {
  languageOptions: {
    globals: {
      ...globals.browser,
      ...globals.node,
      // 以下の様に記述していく
      XRWebGLLayer: true,
    },
  },
};
```

## WebXR 空間に何もレンダリングされない、、XRSession に baseLayer をセットする必要があった！

`navigator.xr.requestSession` をして `session.requestAnimationFrame` を呼ぶと全画面表示になります。
画面が明らかに切り替わるので、これで好きなように空間にレンダリングできるぞぉーと思い込んでいました。
が、一向に何もレンダリングされません。
最初は position がおかしいのかな？と思っていました、が違いました。
`WebGLContext` を XR として使用するためには XR 互換として作成された WebGLContext で `XRWebGLLayer` を作り `XRSession の baseLayer` をセットしてあげる必要がありました。

> https://immersive-web.github.io/webxr/#contextcompatibility

```typescript
// option xrCompatible を true にする
const gl = canvas.getContext("webgl2", { xrCompatible: true });

...

// baseLayer にセットする
session.updateRenderState({ baseLayer: new XRWebGLLayer(session, gl) });
```

## WebXR 空間のカメラはどうなっているのか、XRSession の Projection Matrix と View Matrix

Projection Matrix と View Matrix は `XRView` に格納されており、いわゆるカメラの情報はこれをそのまま使います。

XRView ごとに格納されているので両眼ディスプレイの場合も右と左の差を気にする必要はなくなります。

```typescript
const projectionMatrix = view.projectionMatrix;
// 逆行列を使う必要があることに注意
const viewMatrix = view.transform.inverse.matrix;
```

# おわりに

今回初めて WebXR Device API をそのまま書きました。
当初ライブラリを使って試してみる予定でしたが、 WebXR Depth Sensing Module が草案状態なこともあり、低レイヤー部分でエラーになることが多く、これはもう WebXR Device API の仕様から理解しないと厳しいなとなり、このようになりました。
結果ライブラリに用意されている機能でなんとなく使っていた部分の理解が深まり良い経験になりました。
（でも実際は対応端末も少ないしライブラリに実装されるのを待つ方がいい気はしています）

そんなこんなで、至らぬ部分もあったかもですが、気になった点やおかしな点などがありましたらお気軽にコメントや X 等にてリプライいただければと思います！

# 宣伝

株式会社 STYLY では Unity エンジニア・サーバーサイドエンジニアを募集しています！！ご応募お待ちしています！！

https://www.wantedly.com/projects/1360135

https://www.wantedly.com/projects/1360123