WebXR 深度センシングモジュール

1. 序論

Virtual Reality と Augmented Reality がより普及するにつれて、ユーザーがいる環境についてより詳細な情報にアクセスできる新機能が native APIs によって導入されています。Depth Sensing API は、そのような機能の 1 つを WebXR Device API にもたらし、WebXR を利用した体験の作者が、ユーザーのデバイスからユーザー環境内の現実世界の geometry までの距離に関する情報を取得できるようにします。

この文書は、WebXR Device API および WebXR Augmented Reality Module 仕様に読者が精通していることを前提としています。これは、それらの上に構築され、 XRSessions に追加機能を提供するためです。

1.1. 用語

この文書では、AR という略語を Augmented Reality を表すものとして、VR を Virtual Reality を表すものとして使用します。

この文書では、XR device によって返されるか、API 自体によって返される、深度情報を含む byte 配列を指す場合に、 "depth buffer"、"depth buffer data" および "depth data" のような用語を同じ意味で使用します。 depth buffer の具体的な内容についての詳細は、仕様の data および texture entries で確認できます。

この文書では、view の左上隅を原点とし、X 軸が右方向に増加し、Y 軸が下方向に増加する座標系を指す場合に、 normalized view coordinates という用語を使用します。

2. 初期化

2.1. Feature descriptor

アプリケーションは、適切な feature descriptor を渡すことで、XRSession で depth sensing を有効にするよう要求できます。このモジュールは、depth sensing feature の新しい有効な feature descriptor として、新しい文字列 - depth-sensing を導入します。

デバイスが native depth sensing capability を公開している場合、そのデバイスは depth sensing feature を capable of supporting とされます。inline XR device は、depth sensing feature を capable of supporting として扱ってはなりません。

depth sensing feature は feature policy の対象であり、要求元文書の origin で "xr-spatial-tracking" policy が許可されている必要があります。

2.2. 意図される depth type、data usage、および data formats

enum XRDepthType {
  "raw",
  "smooth",
};

"raw" の使用は、depth data に追加処理を行うべきでないことを示します。
"smooth" の使用は、runtime が potential noise を除去するために depth texture に追加処理を行うべきであることを示します。

enum XRDepthUsage {
  "cpu-optimized",
  "gpu-optimized",
};

"cpu-optimized" の使用は、 XRCPUDepthInformation interface とやり取りすることで、depth data が CPU 上で使用されることを意図していることを示します。
"gpu-optimized" の使用は、 XRWebGLDepthInformation interface とやり取りすることで、depth data が GPU 上で使用されることを意図していることを示します。

enum XRDepthDataFormat {
  "luminance-alpha",
  "float32",
  "unsigned-short",
};

"luminance-alpha" または "unsigned-short" の data format は、API から取得された depth data buffers 内の項目が 16 bit unsigned integer values であることを示します。
"float32" data format は、API から取得された depth data buffers 内の項目が 32 bit floating point values であることを示します。

次の表は、さまざまな data formats を利用できる方法を要約します:

Data format	`GLenum` value equivalent	Depth buffer entry のサイズ	CPU での使用	GPU での使用
`"luminance-alpha"`	LUMINANCE_ALPHA	2 times 8 bit	`data` を `Uint16Array` として解釈する	Luminance および Alpha channels を調べ、単一の値を再構成する。
`"float32"`	R32F	32 bit	`data` を `Float32Array` として解釈する	Red channel を調べ、その値を使用する。
`"unsigned-short"`	R16UI	16 bit	`data` を `Uint16Array` として解釈する	Red channel を調べ、その値を使用する。

2.3. Session configuration

dictionary XRDepthStateInit {
  required sequence<XRDepthUsage> usagePreference;
  required sequence<XRDepthDataFormat> dataFormatPreference;
  sequence<XRDepthType> depthTypeRequest;
  boolean matchDepthView = true;
};

usagePreference は、session に望まれる depth sensing usage を記述するために使用される、XRDepthUsage の ordered sequence です。

dataFormatPreference は、session に望まれる depth sensing data format を記述するために使用される、XRDepthDataFormat の ordered sequence です。

depthTypeRequest は、session に望まれる depth sensing type を記述するために使用される、XRDepthType の ordered sequence です。この要求はユーザーエージェントによって無視されてもよいです。

matchDepthView は、depth information の view が XRView と揃っていなければならないことを要求します。これが true の場合、XRSystem は current frame を反映する depth information を返すべきです。これが false の場合、XRSystem は earlier point in time で capture された depth information を返してもよいです。

注: matchDepthView が false の場合、作者は XRDepthInformation からの view を使用して reprojection を行うべきです。

XRSessionInit dictionary は、新しい depthSensing key を追加することで拡張されます。この key は XRSessionInit では optional ですが、depth-sensing が requiredFeatures または optionalFeatures のいずれかに含まれる場合は、提供されなければなりません。

partial dictionary XRSessionInit {
  XRDepthStateInit depthSensing;
};

depth sensing feature が required feature であるにもかかわらず、application が depthSensing key を提供しなかった場合、ユーザーエージェントはこれを unresolved required feature として扱い、requestSession(mode, options) promise を NotSupportedError で reject しなければなりません。 optional feature として要求された場合、ユーザーエージェントはその feature request を無視し、新しく作成された session で depth sensing を有効にしてはなりません。

depth sensing feature が required feature であるにもかかわらず、XRDepthStateInit を用いて呼び出された finding supported configuration combination algorithm の結果が null である場合、ユーザーエージェントはこれを unresolved required feature として扱い、requestSession(mode, options) promise を NotSupportedError で reject しなければなりません。 optional feature として要求された場合、ユーザーエージェントはその feature request を無視し、新しく作成された session で depth sensing を有効にしてはなりません。

XRSession が depth sensing を有効にして作成された場合、depthUsage、 depthDataFormat、および depthType attributes は、XRDepthStateInit を用いて呼び出された finding supported configuration combination algorithm の結果に設定されなければなりません。 depthActive は true を既定値としなければなりません。

注: この algorithm の意図は、 preferences を最も制約の強いものから最も制約の弱いものへ処理することです。したがって、単一の item のみが示されている場合から items の処理を開始し、その後 multiple、最後に preference が示されていない場合を処理します。

depthStateInit dictionary が与えられた depth sensing API について find supported configuration combination するために、ユーザーエージェントは次の algorithm を実行しなければなりません:

depthStateInit で depthTypeRequest key が設定されている場合はそれに含まれる値を、そうでない場合は空の sequence を depthTypeRequest とします。
selectedType を null とします
depthStateInit 内の usagePreference key に含まれる値を usagePreference とします
selectedUsage を null とします。
depthStateInit 内の dataFormatPreference key に含まれる値を dataFormatPreference とします
selectedDataFormat を null とします。
processingOrder を、(preferences, selection) pairs の sequence とします。ここで selection は前の手順で導入された variables の 1 つへの reference です: [(depthTypeRequest, selectedType), (usagePreference,selectedUsage),(dataFormatPreference,selectedDataFormat)]
processingOrder 内の各 (preferences, selection) について、次の手順を実行します
1. preferences が単一の値のみを含む場合、selection をその値に設定します。
processingOrder 内の各 (preferences, selection) について、次の手順を実行します:
1. selection が null でない場合、次の entry に進みます。
2. preferences sequence が空の場合、次の entry に進みます。
3. preferences 内の各 preference について、次の手順を実行します:
4. selectedType,selectedUsage,selectedDataFormat の他の値を伴う preference が、device の native depth sensing capabilities によって supported depth sensing configuration と見なされない場合、次の entry に進みます。
5. selection を preference に設定し、これらの nested steps を中止します。
processingOrder 内の各 (preferences, selection) について、次の手順を実行します:
1. selection が null でない場合、次の entry に進みます。
2. selection を、selectedType,selectedUsage,selectedDataFormat の他の値を伴う preferred native depth sensing capability によって決定される値に設定します。
selectedType,selectedUsage,selectedDataFormat のいずれかが null の場合、null を返し、これらの手順を中止します。
selectedType,selectedUsage,selectedDataFormat が device の native depth sensing capabilities によって supported depth sensing configuration と見なされる場合、 selectedType,selectedUsage,selectedDataFormat の depth sensing configuration を返し、これらの手順を中止します。
depthTypeRequest が空の list でない場合、それを空の list に設定し、これらの手順を繰り返します。
null を返し、これらの手順を中止します。

注: user agents は usages と data formats の既存のすべての組み合わせをサポートする必要はありません。これは、それらが効率的な方法で data を提供できるようにすることを意図しており、underlying platforms に依存します。この決定は application developers に追加の負担を課しますが、 API complexity を隠す libraries の作成により、performance を犠牲にする可能性はあるものの、軽減できる可能性があります。

depth sensing API を capable of supporting なユーザーエージェントは、少なくとも 1 つの XRDepthUsage mode をサポートしなければなりません。depth sensing API を capable of supporting なユーザーエージェントは "luminance-alpha" data format をサポートしなければならず、他の formats をサポートしてもよいです。

次の code は、depth sensing API を必要とする session をどのように要求できるかを示します。この example は、呼び出し元が CPU-optimized usage と GPU-optimized usage の両方、および "luminance-alpha" と "float32" formats の両方を扱うことができ、CPU と "luminance-alpha" を優先することを前提としています:

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

partial interface XRSession {
  readonly attribute XRDepthUsage depthUsage;
  readonly attribute XRDepthDataFormat depthDataFormat;
  readonly attribute XRDepthType? depthType;
  readonly attribute boolean? depthActive;

  undefined pauseDepthSensing();
  undefined resumeDepthSensing();
};

depthUsage は、session が設定された depth sensing usage を記述します。この属性が depth sensing を有効にしていない session でアクセスされた場合、ユーザーエージェントは InvalidStateError を投げなければなりません。

depthDataFormat は、session が設定された depth sensing data format を記述します。この属性が depth sensing を有効にしていない session でアクセスされた場合、ユーザーエージェントは InvalidStateError を投げなければなりません。

depthType は、session が設定された depth sensing type を記述します。この属性が depth sensing を有効にしていない session でアクセスされた場合、ユーザーエージェントは InvalidStateError を投げなければなりません。 runtime が単一の XRDepthType のみをサポートしている場合、または depthTypeRequest を別の理由で無視した場合、これは null を返すことがあります。

depthActive は現在の depth sensing active state を返します。この属性が depth sensing を有効にしていない session でアクセスされた場合、ユーザーエージェントは InvalidStateError を投げなければなりません。この値が false の場合、ユーザーエージェントは depth data を取得する試みを reject しなければなりません。この値が true の場合、ユーザーエージェントは有効な depth data または null を返してもよいです。

resumeDepthSensing() が XRSession session 上で呼び出されたとき、User Agent は次の手順を実行しなければなりません:

session の ended 値が true の場合、InvalidStateError を投げ、これらの手順を中止します。
session の animation frame を frame とします。
frame の active boolean が false の場合、InvalidStateError を投げ、これらの手順を中止します。
depth-sensing feature descriptor が、session の XR device の、session の mode に対する list of enabled features に contained されていない場合、NotSupportedError を投げ、これらの手順を中止します。
depth sensing active state が true の場合、これらの手順を中止します。
depth sensing active state を true に設定します。

pauseDepthSensing() が XRSession session 上で呼び出されたとき、User Agent は次の手順を実行しなければなりません:

session の ended 値が true の場合、InvalidStateError を投げ、これらの手順を中止します。
session の animation frame を frame とします。
frame の active boolean が false の場合、InvalidStateError を投げ、これらの手順を中止します。
depth-sensing feature descriptor が、session の XR device の、session の mode に対する list of enabled features に contained されていない場合、NotSupportedError を投げ、これらの手順を中止します。
depth sensing active state が false の場合、これらの手順を中止します。
depth sensing active state を false に設定します。

3. Depth data の取得

3.1. XRDepthInformation

[SecureContext, Exposed=Window]
interface XRDepthInformation {
  readonly attribute unsigned long width;
  readonly attribute unsigned long height;

  [SameObject] readonly attribute XRRigidTransform normDepthBufferFromNormView;
  readonly attribute float rawValueToMeters;
};

XRDepthInformation includes XRViewGeometry;

width 属性は、depth buffer の幅（すなわち列数）を含みます。

height 属性は、depth buffer の高さ（すなわち行数）を含みます。

normDepthBufferFromNormView 属性は、depth buffer に index する際に適用する必要がある XRRigidTransform を含みます。その matrix が表す transformation は、coordinate system を normalized view coordinates から normalized depth buffer coordinates に変更し、それを depth buffer の width および height で scale することで、absolute depth buffer coordinates を得られるようにします。

注: applications が結果の depth buffer を mesh の texturing に使用する意図がある場合、mesh vertices の texture coordinates が normalized view coordinates で表現されていること、または適切な coordinate system change が shader 内で実行されることを確保するよう注意しなければなりません。

rawValueToMeters 属性は、depth buffer からの raw depth values を meters 単位の depth にするために掛けなければならない scale factor を含みます。

transform は、関連付けられた view の reference space 内で与えられます。

sensor が関連付けられた view と揃っている場合、XRViewGeometry から含まれるすべての値は、関連付けられた view が返すものと同じ値を返さなければなりません。

各 XRDepthInformation は、関連付けられた view を持ち、これは sensor に最も近い XRView であり、XRDepthInformation を取得するために使用されます。

各 XRDepthInformation は、関連付けられた sensor を持ち、これは depth information が取得された XRViewGeometry の containing object です。

各 XRDepthInformation は、関連付けられた depth buffer を持ち、これは depth buffer data を含みます。異なる XRDepthInformation は、depth buffer 内に異なる concrete types の objects を格納することがあります。

XRDepthInformation またはそれを継承する任意の interface の depth buffer にアクセスしようとするとき、ユーザーエージェントは次の手順を実行しなければなりません:

depthInformation を、member がアクセスされた instance とします。
depthInformation の view を view とします。
view の frame を frame とします。
frame が active でない場合、InvalidStateError を投げ、これらの手順を中止します。
frame が animationFrame でない場合、InvalidStateError を投げ、これらの手順を中止します。
depthInformation の member にアクセスするために必要な通常の手順を続行します。

3.2. XRCPUDepthInformation

[Exposed=Window]
interface XRCPUDepthInformation : XRDepthInformation {
  [SameObject] readonly attribute ArrayBuffer data;

  float getDepthInMeters(float x, float y);
};

data 属性は、必要であれば WebGL texture へ upload するのに適した raw format の depth buffer information を含みます。 data は padding なしの row-major format で格納され、各 entry は sensor の near plane から users' environment までの距離に対応し、単位は unspecified です。各 data entry のサイズと type は depthDataFormat によって決定されます。値は rawValueToMeters を掛けることで unspecified units から meters に変換できます。 normDepthBufferFromNormView は、normalized view coordinates から depth buffer の coordinate system へ transform するために使用できます。アクセス時には、depth buffer にアクセスする algorithm を実行しなければなりません。

注: Applications は data array の内容を変更しようとすべきではありません。これは getDepthInMeters(x, y) method によって返される結果を不正確にする可能性があるためです。

getDepthInMeters(x, y) method は、obtain depth at coordinates するために使用できます。呼び出されたとき、 depth buffer にアクセスする algorithm を実行しなければなりません。

getDepthInMeters(x, y) method が、x, y とともに XRCPUDepthInformation depthInformation 上で呼び出されたとき、ユーザーエージェントは次の手順を実行して obtain depth at coordinates しなければなりません:

depthInformation の view を view、view の frame を frame、そして frame の session を session とします。
x が 1.0 より大きい、または 0.0 より小さい場合、RangeError を投げ、これらの手順を中止します。
y が 1.0 より大きい、または 0.0 より小さい場合、RangeError を投げ、これらの手順を中止します。
normalizedViewCoordinates を、space 内の 3-dimensional point を表す vector とします。その x coordinate は x、y coordinate は y、z coordinate は 0.0、w coordinate は 1.0 に設定されます。
normalizedDepthCoordinates を、normalizedViewCoordinates vector を depthInformation の normDepthBufferFromNormView によって左から premultiply した結果とします。
depthCoordinates を、normalizedDepthCoordinates を scale した結果とします。 x coordinate は depthInformation の width で乗算され、y coordinate は depthInformation の height で乗算されます。
depthCoordinates の x coordinate の値を integer に切り捨て、 [0, width-1] integer range に clamp したものを column とします。
depthCoordinates の y coordinate の値を integer に切り捨て、 [0, height-1] integer range に clamp したものを row とします。
row に width を掛け、column を加えた値と等しいものを index とします。
index に depth data format のサイズを掛けたものを byteIndex とします。
data 内の index byteIndex にある値を、session の depthDataFormat に従って number として解釈したものに等しいものを rawDepth とします。
depthInformation の rawValueToMeters に等しいものを rawValueToMeters とします。
rawDepth に rawValueToMeters を掛けた値を返します。

partial interface XRFrame {
  XRCPUDepthInformation? getDepthInformation(XRView view);
};

getDepthInformation(view) method は、XRFrame 上で呼び出されたとき、application が frame に関連する CPU depth information を取得したいことを示します。

getDepthInformation(view) method が、XRFrame frame 上で、XRView view とともに呼び出されたとき、ユーザーエージェントは次の手順を実行して CPU depth information を取得しなければなりません:

frame の session を session とします。
depth-sensing feature descriptor が、session の XR device の、session の mode に対する list of enabled features に contained されていない場合、NotSupportedError を投げ、これらの手順を中止します。
frame の active boolean が false の場合、InvalidStateError を投げ、これらの手順を中止します。
frame の animationFrame boolean が false の場合、 InvalidStateError を投げ、これらの手順を中止します。
frame が view の frame と一致しない場合、InvalidStateError を投げ、これらの手順を中止します。
session の depthUsage が "cpu-optimized" でない場合、InvalidStateError を投げ、これらの手順を中止します。
frame および view が与えられた CPU depth information instance の作成の結果を depthInformation とします。
depthInformation を返します。

XRFrame frame および XRView view が与えられて CPU depth information instance を作成するには、ユーザーエージェントは次の手順を実行しなければなりません:

XRCPUDepthInformation の new instance を result とします。
frame の time を time とします。
frame の session を session とします。
session の XR device を device とします。
depthActive が false である場合、null を返し、これらの手順を中止します。
session の depthType, depthUsage, および depthDataFormat を考慮し、指定された view について time 時点で有効な depth information を device に query した結果を nativeDepthInformation とします。
nativeDepthInformation が null である場合、null を返し、これらの手順を中止します。
nativeDepthInformation 内に存在する depth buffer が、depth data への access を block するための user agent の criteria を満たす場合、null を返し、これらの手順を中止します。
nativeDepthInformation 内に存在する depth buffer が、depth buffer で利用可能な information の量を制限するための user agent の criteria を満たす場合、depth buffer をそれに応じて調整します。
result の width を、nativeDepthInformation で返された depth buffer の width に初期化します。
result の height を、nativeDepthInformation で返された depth buffer の height に初期化します。
result の normDepthBufferFromNormView を、nativeDepthInformation の depth coordinates transformation matrix に基づく new XRRigidTransform に初期化します。
result の data を、nativeDepthInformation で返された raw depth buffer に初期化します。
result の view を view に初期化します。
result の transform を、view の reference space 内の time における sensor の pose に初期化します。
result を返します。

次の code は、XRFrameRequestCallback 内で depth data を取得する方法を示します。 depth sensing が有効で、usage が "cpu-optimized" に設定され、data format が "luminance-alpha" に設定された session であると仮定します:

const session = ...;          // Session created with depth sensing enabled.
const referenceSpace = ...;   // Reference space created from the session.

function requestAnimationFrameCallback(t, frame) {
  session.requestAnimationFrame(requestAnimationFrameCallback);

  const pose = frame.getViewerPose(referenceSpace);
  if (pose) {
    for (const view of pose.views) {
      const depthInformation = frame.getDepthInformation(view);
      if (depthInformation) {
        useCpuDepthInformation(view, depthInformation);
      }
    }
  }
}

XRCPUDepthInformation が取得されると、それを使用して view plane から user’s environment までの距離を調べることができます（詳細は § 4 結果の解釈節を参照）。以下の code は normalized view coordinates (0.25, 0.75) における depth を取得する例を示します:

function useCpuDepthInformation(view, depthInformation) {
  const depthInMeters = depthInformation.getDepthInMeters(0.25, 0.75);
  console.log("Depth at normalized view coordinates (0.25, 0.75) is:",
    depthInMeters);
}

3.3. XRWebGLDepthInformation

[Exposed=Window]
interface XRWebGLDepthInformation : XRDepthInformation {
  [SameObject] readonly attribute WebGLTexture texture;

  readonly attribute XRTextureType textureType;
  readonly attribute unsigned long? imageIndex;
};

texture 属性は、depth buffer information を opaque texture として含みます。各 texel は、sensor の near plane から users' environment までの距離に対応し、単位は unspecified です。各 data entry のサイズと type は depthDataFormat によって決定されます。値は rawValueToMeters を掛けることで unspecified units から meters に変換できます。 normDepthBufferFromNormView は、normalized view coordinates から depth buffer の coordinate system へ transform するために使用できます。アクセス時には、depth buffer にアクセスする algorithm を XRDepthInformation について実行しなければなりません。

textureType 属性は、texture が TEXTURE_2D 型であるか、TEXTURE_2D_ARRAY 型であるかを記述します。

imageIndex 属性は、texture array への offset を返します。textureType が TEXTURE_2D_ARRAY と等しい場合は定義されなければならず、TEXTURE_2D である場合は undefined でなければなりません。

partial interface XRWebGLBinding {
  XRWebGLDepthInformation? getDepthInformation(XRView view);
};

getDepthInformation(view) method は、XRWebGLBinding 上で呼び出されたとき、application が frame に関連する WebGL depth information を取得したいことを示します。

getDepthInformation(view) method が、XRWebGLBinding binding 上で、XRView view とともに呼び出されたとき、ユーザーエージェントは次の手順を実行して WebGL depth information を取得しなければなりません:

binding の session を session とします。
view の frame を frame とします。
session が frame の session と一致しない場合、InvalidStateError を投げ、これらの手順を中止します。
depth-sensing feature descriptor が、session の XR device の、session の mode に対する list of enabled features に contained されていない場合、NotSupportedError を投げ、これらの手順を中止します。
session の depthUsage が "gpu-optimized" でない場合、InvalidStateError を投げ、これらの手順を中止します。
frame の active boolean が false の場合、InvalidStateError を投げ、これらの手順を中止します。
frame の animationFrame boolean が false の場合、 InvalidStateError を投げ、これらの手順を中止します。
frame および view が与えられた WebGL depth information instance の作成の結果を depthInformation とします。
depthInformation を返します。

XRFrame frame および XRView view が与えられて WebGL depth information instance を作成するには、ユーザーエージェントは次の手順を実行しなければなりません:

XRWebGLDepthInformation の new instance を result とします。
time を次のように初期化します:

XRSession が matchDepthView を true に設定して作成された場合:
frame の time を time とします。
それ以外の場合
device が depth information を capture した time を time とします。
frame の session を session とします。
session の XR device を device とします。
depthActive が false である場合、null を返し、これらの手順を中止します。
session の depthType, depthUsage, および depthDataFormat を考慮し、指定された view について time 時点で有効な depth information を device の native depth sensing に query した結果を nativeDepthInformation とします。
nativeDepthInformation が null である場合、null を返し、これらの手順を中止します。
nativeDepthInformation 内に存在する depth buffer が、depth data への access を block するための user agent の criteria を満たす場合、null を返し、これらの手順を中止します。
nativeDepthInformation 内に存在する depth buffer が、depth buffer で利用可能な information の量を制限するための user agent の criteria を満たす場合、depth buffer をそれに応じて調整します。
result の width を、nativeDepthInformation で返された depth buffer の width に初期化します。
result の height を、nativeDepthInformation で返された depth buffer の height に初期化します。
result の normDepthBufferFromNormView を、nativeDepthInformation の depth coordinates transformation matrix に基づく new XRRigidTransform に初期化します。
result の texture を、nativeDepthInformation で返された depth buffer を含む opaque texture に初期化します。
result の view を view に初期化します。
result の transform を、view の reference space 内の time における sensor の pose に初期化します。
result の textureType を次のように初期化します:

result の texture が texture-array の textureType で作成された場合:
result の textureType を "texture-array" に初期化します。
それ以外の場合
result の textureType を "texture" に初期化します。
result の imageIndex を次のように初期化します:

textureType が texture である場合
result の imageIndex を null に初期化します。
それ以外の場合で、view の eye が "right" である場合
result の imageIndex を 1 に初期化します。
それ以外の場合
result の imageIndex を 0 に初期化します。
result を返します。

次の code は、XRFrameRequestCallback 内で depth data を取得する方法を示します。 depth sensing が有効で、usage が "gpu-optimized" に設定され、data format が "luminance-alpha" に設定された session であると仮定します:

const session = ...;          // Session created with depth sensing enabled.
const referenceSpace = ...;   // Reference space created from the session.
const glBinding = ...;        // XRWebGLBinding created from the session.

function requestAnimationFrameCallback(t, frame) {
  session.requestAnimationFrame(requestAnimationFrameCallback);

  const pose = frame.getViewerPose(referenceSpace);
  if (pose) {
    for (const view of pose.views) {
      const depthInformation = glBinding.getDepthInformation(view);
      if (depthInformation) {
        useGpuDepthInformation(view, depthInformation);
      }
    }
  }
}

XRWebGLDepthInformation が取得されると、それを使用して view plane から user’s environment までの距離を調べることができます（詳細は § 4 結果の解釈節を参照）。以下の code は、data を shader に転送する方法を示します:

const gl = ...;             // GL context to use.
const shaderProgram = ...;  // Linked WebGLProgram.
const programInfo = {
  uniformLocations: {
    depthTexture: gl.getUniformLocation(shaderProgram, 'uDepthTexture'),
    uvTransform: gl.getUniformLocation(shaderProgram, 'uUvTransform'),
    rawValueToMeters: gl.getUniformLocation(shaderProgram, 'uRawValueToMeters'),
  }
};

function useGpuDepthInformation(view, depthInformation) {
  // ...

  gl.bindTexture(gl.TEXTURE_2D, depthInformation.texture);
  gl.activeTexture(gl.TEXTURE0);
  gl.uniform1i(programInfo.uniformLocations.depthTexture, 0);

  gl.uniformMatrix4fv(
    programInfo.uniformLocations.uvTransform, false,
    depthData.normDepthBufferFromNormView.matrix);

  gl.uniform1f(
    programInfo.uniformLocations.rawValueToMeters,
    depthData.rawValueToMeters);

  // ...
}

depth buffer を利用する fragment shader は、たとえば次のようになります:

precision mediump float;

uniform sampler2D uDepthTexture;
uniform mat4 uUvTransform;
uniform float uRawValueToMeters;

varying vec2 vTexCoord;

float DepthGetMeters(in sampler2D depth_texture, in vec2 depth_uv) {
  // Depth is packed into the luminance and alpha components of its texture.
  // The texture is a normalized format, storing millimeters.
  vec2 packedDepth = texture2D(depth_texture, depth_uv).ra;
  return dot(packedDepth, vec2(255.0, 256.0 * 255.0)) * uRawValueToMeters;
}

void main(void) {
  vec2 texCoord = (uUvTransform * vec4(vTexCoord.xy, 0, 1)).xy;

  float depthInMeters = DepthGetMeters(uDepthTexture, texCoord);

  gl_FragColor = ...;
}

4. 結果の解釈

ある pixel が invalid depth data を持つと判断された場合、または depth data を他の理由で判定できない場合、ユーザーエージェントは depth value 0 を返さなければなりません。

data および texture に格納される値は、camera plane から real-world-geometry（XR system によって理解されるもの）までの距離を表します。以下の例では、point a = (x, y) における depth value は、point A から camera plane までの距離に対応します。具体的には、depth value は aA vector の長さを表すものではありません。

Depth API data explanation

上の画像は次の code に対応します:

// depthInfo is of type XRCPUDepthInformation:
const depthInMeters = depthInfo.getDepthInMeters(x, y);

5. Native device concepts

5.1. Native depth sensing

Depth sensing specification は、depth sensing API が実装される基盤となる native device が、device の native depth sensing capabilities を query する方法を提供することを前提としています。 device が depth buffer data を取得する方法を公開している場合、その device は device の native depth sensing capabilities の query をサポートしていると言われます。 depth buffer data は、buffer dimensions、buffer に格納された値で使用される units に関する情報、normalized view coordinates から normalized depth buffer coordinates への coordinate system change を行う depth coordinates transformation matrix を含まなければなりません。この transform は、transformed 3D vector の z coordinate を影響を受けないままにすべきです。 device はまた、projection matrix および sensor の transform を公開する何らかの mechanism も提供しなければなりません。

device は support depth sensing type を 2 通りの方法で行うことができます。 device が最小限の post-processing で estimated depth values を単に返す場合、"raw" depth type をサポートすると言われます。device または runtime が、この data から noise を "smooth" out するための追加処理（たとえば同じ depth value のより大きな領域へ）を適用できる場合、"smooth" depth type をサポートすると言われます。

注: "Raw" depth data は、confidence values を伴うことが多いです。 UA は、low confidence value を持つ depth data を、page にそのような data を返す際に invalid depth data として扱うことを選択できます。

device は support depth sensing usage を 2 通りの方法で行うことができます。 device が主に CPU-accessible memory を通じて depth data を返すことができる場合、"cpu-optimized" usage をサポートすると言われます。device が主に GPU-accessible memory を通じて depth data を返すことができる場合、 "gpu-optimized" usage をサポートすると言われます。

注: user agent は、両方の usage modes をサポートすることを選択できます（たとえば、device が CPU-accessible data と GPU-accessible data の両方を提供できる場合、または CPU-accessible data と GPU-accessible data 間の転送を手動で実行する場合）。

device は、depth sensing usage および type が与えられたとき、次の方法で support depth sensing data format を行うことができます。 depth sensing usage および type が与えられたとき、device が 16 bit unsigned integers を含む buffer として depth data を返せる場合、"luminance-alpha" および "unsigned-short" data formats をサポートすると言われます。depth sensing usage および type が与えられたとき、device が 32 bit floating point values を含む buffer として depth data を返せる場合、"float32" data format をサポートすると言われます。

depth sensing configuration は、1 つの XRDepthType、 1 つの XRDepthUsage、および 1 つの XRDepthDataFormat の組み合わせによって表されます。

device が指定された configuration について depth sensing type をサポートし、depth sensing usage をサポートし、かつ depth sensing data format をサポートする場合、その device は support the depth sensing configuration と言われます。

注: depth sensing API のサポートは、AR-capable と分類される hardware のみに限定されません。ただし、そのような devices ではこの feature がより一般的になることが期待されます。適切な sensors を含む、または depth buffer を提供するための他の techniques を使用する VR devices も、 depth sensing API を実装するために必要な data を提供できるべきです。

depthTypeRequest、 usagePreference、および dataFormatPreference のそれぞれについて、対応する array が空である場合に使用されなければならない preferred native depth sensing capability を device は持たなければなりません。type、usage、および format は、相互依存する可能性がありますが、 device の最も効率的なものを反映すべきです。

device は depth sensing active state を持つと言うことができ、これは depth sensing capabilities が active に running しているかを表す boolean です。この state は true として開始しなければなりません。この state が false の場合、ユーザーエージェントはこの feature が有効であることによる performance impact を軽減する手段を取るべきです。

6. プライバシーおよびセキュリティに関する考慮事項

depth sensing API は、depth buffer という format で、ユーザー環境に関する追加情報を websites に提供します。十分に高い resolution と十分に高い precision を持つ depth buffer が与えられると、websites はユーザーが快適と感じる範囲を超える、より詳細な情報を潜在的に知ることができます。使用される underlying technology によっては、 depth data は camera image および IMU sensors に基づいて作成されることがあります。

ユーザーに対する privacy risks を軽減するため、user agents は session で depth sensing API を有効にする前に user consent を求めるべきです。さらに、depth sensing technologies および hardware が向上するにつれて、 user agents は API を通じて公開される information の量を制限すること、またはそのような制限を導入することが feasible でない場合、API から返される data への access を block することを考慮すべきです。information の量を制限するために、 user agents はたとえば、結果の depth buffer の resolution を下げたり、depth buffer 内に存在する値の precision を下げたり（たとえば quantization によって）できます。そのような方法で data の量を制限することを決定した user agents は、それでもこの仕様を実装していると見なされます。

user agent が、device の cameras によって提供される情報と等価になるほど詳細な depth buffers を提供できる場合、まず camera access を取得するために必要な consent と等価な user consent を取得しなければなりません。

変更点

First Public Working Draft 31 August 2021 からの変更点

7. 謝辞

次の個人が WebXR Depth Sensing 仕様の設計に貢献しました:

WebXR 深度センシングモジュール

概要

この文書のステータス

1. 序論

1.1. 用語

2. 初期化

2.1. Feature descriptor

2.2. 意図される depth type、data usage、および data formats

2.3. Session configuration

3. Depth data の取得

3.1. XRDepthInformation

3.2. XRCPUDepthInformation

3.3. XRWebGLDepthInformation

4. 結果の解釈

5. Native device concepts

5.1. Native depth sensing

6. プライバシーおよびセキュリティに関する考慮事項

変更点

First Public Working Draft 31 August 2021 からの変更点

7. 謝辞

適合性

文書の慣例

適合アルゴリズム

索引

この仕様で定義される用語

参照により定義される用語

参考文献

規範的参考文献

参考情報の参考文献

IDL 索引

WebXR 深度センシングモジュール

概要

この文書のステータス

1. 序論

1.1. 用語

2. 初期化

2.1. Feature descriptor

2.2. 意図される depth type、data usage、および data formats

2.3. Session configuration

3. Depth data の取得

3.1. XRDepthInformation

3.2. XRCPUDepthInformation

3.3. XRWebGLDepthInformation

4. 結果の解釈

5. Native device concepts

5.1. Native depth sensing

6. プライバシーおよびセキュリティに関する考慮事項

変更点

First Public Working Draft 31 August 2021 からの変更点

7. 謝辞

適合性

文書の 慣例

適合 アルゴリズム

索引

この 仕様で定義される用語

参照により定義される 用語

参考文献

規範的参考文献

参考情報の参考文献

IDL 索引

文書の慣例

適合アルゴリズム

この仕様で定義される用語

参照により定義される用語