XR_ANDROID_spatial_discovery_raycast

Name String

XR_ANDROID_spatial_discovery_raycast

拡張機能の種類

インスタンス拡張

登録済みの内線番号

787

リビジョン

1

承認ステータス

未批准

拡張機能とバージョンの依存関係

XR_EXT_spatial_entity

最終更新日

2025-08-12

IP ステータス

既知の IP 申し立てはありません。

寄与者

Brian Chen、Google
Levana Chen、Google
Kyle Chen、Google
Nihav Jain、Google
Spencer Quin、Google
Natalie Fleury、Meta
Yuichi Taguchi、Meta
Jimmy Alamparambil、ByteDance
Zhipeng Liu、ByteDance

概要

この拡張機能は XR_EXT_spatial_entity をベースに構築されており、XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT などの既存の空間機能にレイキャスト機能を提供して、空間エンティティを検出します。

この拡張機能では、深度バッファに対するレイキャスト用の新しい空間機能も導入されています。

権限

Android アプリケーションが使用する機能に応じて必要な権限。XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID を使用する場合、アプリには android.permission.SCENE_UNDERSTANDING_FINE 権限が必要です。XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT を使用する場合、アプリには android.permission.SCENE_UNDERSTANDING_COARSE 権限が必要です。android.permission.SCENE_UNDERSTANDING_FINE は、android.permission.SCENE_UNDERSTANDING_COARSE 権限も意味します。アプリが両方の機能を使用する場合、アプリは両方の権限を個別にリクエストする必要はありません。

android.permission.SCENE_UNDERSTANDING_COARSE と android.permission.SCENE_UNDERSTANDING_FINE はどちらも危険な権限と見なされます。

(保護レベル: dangerous)

ランタイム サポート

ランタイムがレイキャストによる空間エンティティの検出をサポートしている場合、レイキャストによる検出をサポートする機能について、xrEnumerateSpatialCapabilityComponentTypesEXT で XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID を列挙することで、これを示さなければなりません。

ランタイムが深度バッファに対するレイキャストをサポートしている場合、xrEnumerateSpatialCapabilitiesEXT で XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID を列挙しなければなりません。

レイキャストで空間エンティティを検出する

XrSpatialRaycastInfoANDROID 構造体は次のように定義されます。

typedef struct XrSpatialRaycastInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrVector3f         origin;
    XrVector3f         direction;
    float              maxDistance;
} XrSpatialRaycastInfoANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • space は、XrSpatialRaycastResultDataANDROID のポーズが配置される XrSpace です。
  • time は、XrSpatialRaycastResultDataANDROID のポーズが定義されている XrTime です。
  • origin は、レイの原点を記述する XrVector3f です。
  • direction は、レイの方向を記述する XrVector3f です。
  • maxDistance は、origin から direction に沿って指定された距離内にあるエンティティの検出を制限するために、アプリケーションがオプションで指定できる距離(メートル単位)です。

アプリは、XrSpatialDiscoverySnapshotCreateInfoEXT :: next チェーンに XrSpatialRaycastInfoANDROID を含めることで、この構造体で定義されたレイと交差する空間エンティティを検出できます。

アプリが、いずれの機能に対しても XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID を有効にせずに構成された XrSpatialContextEXT で XrSpatialRaycastInfoANDROID を使用する場合、ランタイムは xrCreateSpatialDiscoverySnapshotAsyncEXT または xrCreateSpatialRaycastSnapshotANDROID から XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT を返さなければなりません。

ランタイムは、XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID コンポーネントをサポートする機能から取得された XrSpatialSnapshotEXT 内の空間エンティティのコンポーネント データと ID のみを含める必要があります。

アプリケーションが maxDistance を正の値に設定した場合、ランタイムは、direction に沿って panme:origin から maxDistance を超えて離れているヒット空間エンティティをスナップショットに含めてはなりません。maxDistance が 0 または負の値に設定されている場合、ランタイムはレイを無制限とみなす必要があります。

有効な使用方法(暗黙的)

  • XrSpatialRaycastInfoANDROID を使用する前に、XR_ANDROID_spatial_discovery_raycast 拡張機能を有効にする必要があります。
  • type は XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • space は有効な XrSpace ハンドルでなければなりません

Raycast Result コンポーネント

XrSpatialRaycastResultDataANDROID 構造体は次のように定義されます。

typedef struct XrSpatialRaycastResultDataANDROID {
    XrPosef    hitPose;
    float      distanceSquared;
} XrSpatialRaycastResultDataANDROID;

メンバーの説明

  • hitPose は、レイが空間エンティティと交差するポイントを定義する XrPosef です。
  • distanceSquared は、レイの原点から交点までの距離の 2 乗です。

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID コンポーネントは、xrCreateSpatialDiscoverySnapshotAsyncEXT から作成された XrSpatialSnapshotEXT(XrSpatialRaycastInfoANDROID が XrSpatialDiscoverySnapshotCreateInfoEXT :: next チェーンに含まれている場合)または xrCreateSpatialRaycastSnapshotANDROID から作成された XrSpatialSnapshotEXT にのみ存在します。

ランタイムは、xrCreateSpatialUpdateSnapshotEXT を使用して作成された XrSpatialSnapshotEXT にこのコンポーネントを含めてはなりません。

アプリケーションが XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes に XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID を含んでいる場合、ランタイムは xrCreateSpatialUpdateSnapshotEXT から XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID が特定の機能に対してのみ有効になっている場合、ランタイムは、それらの機能によって提供される空間エンティティのみをスナップショットに含める必要があります。たとえば、オブジェクトと平面が同じ方向に並んでいて、XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID が XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT に対してのみ有効になっている場合、平面のみが検出されます。

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID の hitPose は、XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time の XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace に配置されます。正の Z 軸はヒットしたサーフェスの法線であり、負の Y 軸はほぼレイの原点を指します。

有効な使用方法(暗黙的)

データをクエリするコンポーネント リスト構造体

XrSpatialComponentRaycastResultListANDROID 構造体は次のように定義されます。

typedef struct XrSpatialComponentRaycastResultListANDROID {
    XrStructureType                       type;
    void*                                 next;
    uint32_t                              raycastResultCount;
    XrSpatialRaycastResultDataANDROID*    raycastResults;
} XrSpatialComponentRaycastResultListANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • raycastResultCount は、raycastResults 配列内の要素の数を表す uint32_t です。
  • raycastResults は XrSpatialRaycastResultDataANDROID の配列です。

XrSpatialSnapshotEXT 内の空間エンティティのレイキャスト結果コンポーネントをクエリするには、XrSpatialComponentDataQueryConditionEXT :: componentTypes に XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID を含め、XrSpatialComponentDataQueryResultEXT :: next チェーンに XrSpatialComponentRaycastResultListANDROID を追加します。

XrSpatialComponentRaycastResultListANDROID が XrSpatialComponentDataQueryResultEXT :: next チェーンに含まれているが、XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID が XrSpatialComponentDataQueryConditionEXT :: componentTypes に含まれていない場合、ランタイムは xrQuerySpatialComponentDataEXT から XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

raycastResultCount が XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput より小さい場合、ランタイムは xrQuerySpatialComponentDataEXT から XR_ERROR_SIZE_INSUFFICIENT を返さなければなりません。

返される raycastResults は順序付けされていません。アプリケーションは、XrSpatialRaycastResultDataANDROID :: distanceSquared を使用して、結果を距離順に並べ替えることができます。

有効な使用方法(暗黙的)

  • XrSpatialComponentRaycastResultListANDROID を使用する前に、XR_ANDROID_spatial_discovery_raycast 拡張機能を有効にする必要があります。
  • type は XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • raycastResults は、raycastResultCount XrSpatialRaycastResultDataANDROID 構造体の配列へのポインタでなければなりません。
  • raycastResultCount パラメータは 0 より大きい値にする必要があります。

構成

XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID が、ある機能の XrSpatialCapabilityComponentTypesEXT :: componentTypes で列挙されている場合、アプリは、XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents リストに列挙値を含めることで、その機能を有効にできます。このコンポーネントでは、XrSpatialCapabilityConfigurationBaseHeaderEXT の次のチェーンに含めるための特別な構成は必要ありません。

アプリケーションが XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes に XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID を含んでいる場合、ランタイムは xrCreateSpatialUpdateSnapshotEXT から XR_ERROR_VALIDATION_FAILURE を返さなければなりません。このコンポーネントは、検出スナップショットに固有のものです。

Depth Raycast の空間機能

構成

XrSpatialCapabilityConfigurationDepthRaycastANDROID 構造体は次のように定義されます。

typedef struct XrSpatialCapabilityConfigurationDepthRaycastANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
} XrSpatialCapabilityConfigurationDepthRaycastANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。
  • capability は XrSpatialCapabilityEXT であり、XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID でなければなりません。
  • enabledComponentCount は、enabledComponents 配列内の要素の数を表す uint32_t です。0 より大きい値にする必要があります。
  • enabledComponents は XrSpatialComponentTypeEXT の配列へのポインタです。

アプリは、XrSpatialContextCreateInfoEXT :: capabilityConfigs に XrSpatialCapabilityConfigurationDepthRaycastANDROID 構造体へのポインタを含めることで、XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID 空間機能を有効にできます。

capability が XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID でない場合、ランタイムは XR_ERROR_VALIDATION_FAILURE を返さなければなりません。

この機能で検出されたエンティティの ID は、常に XR_NULL_SPATIAL_ENTITY_ID_EXT です。これは、アプリケーションがこれらのエンティティの XrSpatialEntityEXT ハンドルを作成できないことも意味します。そのため、これらのエンティティを XrSpatialUpdateSnapshotCreateInfoEXT :: entities に含めて更新スナップショットを作成することはできません。

有効な使用方法(暗黙的)

  • XR_ANDROID_spatial_discovery_raycast 拡張機能は、XrSpatialCapabilityConfigurationDepthRaycastANDROID を使用する前に有効にする必要があります。
  • type は XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • capability は、有効な XrSpatialCapabilityEXT 値でなければなりません
  • enabledComponents は、enabledComponentCount 個の有効な XrSpatialComponentTypeEXT 値の配列へのポインタでなければなりません。
  • enabledComponentCount パラメータは 0 より大きい値にする必要があります。

保証対象の部品

XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID をサポートするランタイムは、この機能によって検出されたエンティティの保証されたコンポーネントとして、次の空間コンポーネントをサポートしなければならず、xrEnumerateSpatialCapabilityComponentTypesEXT でそれらを列挙しなければなりません。

  • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

同期レイキャスト

xrCreateSpatialRaycastSnapshotANDROID 関数は次のように定義されます。

XrResult xrCreateSpatialRaycastSnapshotANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialRaycastSnapshotCreateInfoANDROID* createInfo,
    XrSpatialSnapshotEXT*                       snapshot);

パラメータの説明

ほとんどのユースケースでは xrCreateSpatialDiscoverySnapshotAsyncEXT で十分ですが、レイキャストの結果をすぐに必要とするアプリケーションでは、この関数は遅いと見なされます。xrCreateSpatialRaycastSnapshotANDROID は、同期レイキャストを開始してスナップショットを作成します。これにより、アプリケーションはレイキャストの結果のクエリをすぐに開始できます。

XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes の XrSpatialComponentTypeEXT のいずれかが、spatialContext の作成時に XrSpatialContextCreateInfoEXT :: capabilityConfigs に渡された空間機能に対して有効になっていない場合、ランタイムは XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT を返さなければなりません。

アプリが XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes で空間コンポーネント タイプのリストを提供しない場合、ランタイムは、spatialContext 用に構成されたレイキャスト対応機能の XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents で列挙されたコンポーネントのセットを持つスナップショット内のすべての空間エンティティを含めなければなりません。ランタイムには、spatialContext 用に構成されたレイキャスト対応機能の有効なすべてのコンポーネントのデータを含める必要があります。

有効な使用方法(暗黙的)

戻りコード

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失敗

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrSpatialRaycastSnapshotCreateInfoANDROID 構造体は次のように定義されます。

typedef struct XrSpatialRaycastSnapshotCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    uint32_t                              componentTypeCount;
    const XrSpatialComponentTypeEXT*      componentTypes;
    const XrSpatialRaycastInfoANDROID*    raycastInfo;
} XrSpatialRaycastSnapshotCreateInfoANDROID;

メンバーの説明

  • type は、この構造の XrStructureType です。
  • next は、NULL または構造体チェーン内の次の構造体へのポインタです。このような構造体は、コア OpenXR またはこの拡張機能では定義されていません。
  • componentTypeCount は、componentTypes 配列内の要素の数を表す uint32_t です。
  • componentTypes は XrSpatialComponentTypeEXT の配列です。
  • raycastInfo は、レイの情報を記述する XrSpatialRaycastInfoANDROID 構造体です。

有効な使用方法(暗黙的)

  • XrSpatialRaycastSnapshotCreateInfoANDROID を使用する前に、XR_ANDROID_spatial_discovery_raycast 拡張機能を有効にする必要があります。
  • type は XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID にする必要があります。
  • next は、NULL または構造体チェーン内の次の構造体への有効なポインタでなければなりません。
  • componentTypeCount が 0 でない場合、componentTypes は componentTypeCount の有効な XrSpatialComponentTypeEXT 値の配列へのポインタでなければなりません。
  • raycastInfo は、有効な XrSpatialRaycastInfoANDROID 構造体へのポインタでなければなりません。

コード例

深度レイキャストと平面トラッキング機能を設定する

次のサンプルコードは、レイキャスト機能をサポートする機能を備えた空間コンテキストを作成する方法を示しています。この例では、XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID と XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT を使用します。

// Check runtime supported capabilities
uint32_t capabilityCount;
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, 0, &capabilityCount, nullptr));
std::vector<XrSpatialCapabilityEXT> capabilities(capabilityCount);
CHK_XR(xrEnumerateSpatialCapabilitiesEXT(instance, systemId, capabilityCount, &capabilityCount, capabilities.data()));

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID) == capabilities.end()) {
  return;
}

if (std::find(capabilities.begin(), capabilities.end(), XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT) == capabilities.end()) {
  return;
}

// Create capability config for depth raycasting
std::vector<XrSpatialComponentTypeEXT> depthRaycastComponents {
  XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID
};

// Create capability config for depth raycasting
XrSpatialCapabilityConfigurationDepthRaycastANDROID depthRaycastConfig {
  .type = XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID,
  .enabledComponentCount = (uint32_t)depthRaycastComponents.size(),
  .enabledComponents = depthRaycastComponents.data(),
};

// Enumerate runtime supported components for plane tracking capability
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes {
  XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT
};

bool isRaycastSupportedViaPlaneTracking;
std::vector<XrSpatialComponentTypeEXT> planeTrackingComponents {
  XR_SPATIAL_COMPONENT_TYPE_BOUNDED_2D_EXT,
  XR_SPATIAL_COMPONENT_TYPE_PLANE_ALIGNMENT_EXT,
};

CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId,
       XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &capabilityComponentTypes));

planeTrackingComponents.resize(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = (uint32_t)planeTrackingComponents.size();
capabilityComponentTypes.componentTypes = planeTrackingComponents.data();

CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(instance, systemId,
       XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, &capabilityComponentTypes));

// Check if raycast is supported by plane tracking
isRaycastSupportedViaPlaneTracking = std::find(planeTrackingComponents.begin(),
planeTrackingComponents.end(), XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID)
!= planeTrackingComponents.end();

// Create capability config for plane tracking
XrSpatialCapabilityConfigurationPlaneTrackingEXT planeTrackingConfig {
  .type = XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_PLANE_TRACKING_EXT,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT,
  .enabledComponentCount = (uint32_t)planeTrackingComponents.size(),
  .enabledComponents = planeTrackingComponents.data(),
};

// Create spatial context
// Types of raycast is determined by configs included in XrSpatialContextCreateInfoEXT
// For this example, both plane raycast & depth raycast are performed
std::vector<const XrSpatialCapabilityConfigurationBaseHeaderEXT*> capabilityConfigs;
capabilityConfigs.push_back(reinterpret_cast<const XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&depthRaycastConfig));
if(isRaycastSupportedViaPlaneTracking) capabilityConfigs.push_back(reinterpret_cast<const XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&planeTrackingConfig));

XrSpatialContextCreateInfoEXT contextCreateInfo {
  .type = XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT,
  .next = nullptr,
  .capabilityConfigCount = (uint32_t)capabilityConfigs.size(),
  .capabilityConfigs = capabilityConfigs.data(),
};

CHK_XR(xrCreateSpatialContextAsyncEXT(session, &contextCreateInfo, &future))

// Completes creating spatial context
XrCreateSpatialContextCompletionEXT contextCompletion{
XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};

CHK_XR(xrCreateSpatialContextCompleteEXT(session, future, &contextCompletion))

空間エンティティを検出してコンポーネント データをクエリする

次のサンプルコードは、XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID と XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT で構成されたコンテキストの空間エンティティを検出し、そのコンポーネント データをクエリする方法を示しています。

// Fill in the raycast info.
XrSpatialRaycastInfoANDROID raycastInfo {
  .type        = XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID,
  .next        = nullptr,
  .space       = viewSpace,
  .time        = updateTime,
  .origin      = {0.0f, 0.0f, 0.0f},
  .direction   = {0.0f, 0.0f,-1.0f},
  .maxDistance = 0.0f  // ray is unbounded
};

// Next pointing to the raycast info.
XrSpatialDiscoverySnapshotCreateInfoEXT discoverySnapshotCreateInfo {
  .type = XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT,
  .next = &raycastInfo
};

// Create snapshot
CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT (
spatialContext, &discoverySnapshotCreateInfo, &future));

waitUntilReady(future);

// Complete async operation.
XrCreateSpatialDiscoverySnapshotCompletionInfoEXT
  createSnapshotCompletionInfo {
    .type      = XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT,
    .baseSpace = viewSpace,
    .time      = updateTime,
    .future    = future,
  };

XrCreateSpatialDiscoverySnapshotCompletionEXT completion {
  XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};

CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
           spatialContext, &createSnapshotCompletionInfo,
           &completion));

if(completion.futureResult != XR_SUCCESS) return;

// Query hit result components
std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
  XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID
};

XrSpatialComponentDataQueryConditionEXT queryCond {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT,
  .componentTypeCount = 1,
  .componentTypes     = enabledComponents.data(),
};

XrSpatialComponentDataQueryResultEXT queryResult {
  .type = XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT,
};

XrResult result = xrQuerySpatialComponentDataEXT(
           completion.snapshot, &queryCond, &queryResult);

// Check query result.
if(result != XR_SUCCESS) return;

// Query again for the hit result list.
std::vector<XrSpatialRaycastResultDataANDROID> raycastResults;
raycastResults.resize(queryResult.entityIdCountOutput);
XrSpatialComponentRaycastResultListANDROID raycastResultList {
  .type               = XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID,
  .raycastResultCount = (uint32_t)raycastResults.size(),
  .raycastResults     = raycastResults.data(),
};

queryResult.next = &raycastResultList;
result = xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult);

// Check query result again.
if(result != XR_SUCCESS) return;

std::vector<XrSpatialEntityEXT> hitEntities;
std::vector<XrPosef> depthHitPoses;
for(uint32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
    // access raycastResults[i] for id & pose
    XrSpatialEntityIdEXT   id   = queryResult.entityIds[i];
    XrPosef                pose = raycastResults[i].hitPose;

    if (id != XR_NULL_SPATIAL_ENTITY_ID_EXT) {
        // hit entities (e.g. planes)
    // get entity handle via entity id
    XrSpatialEntityFromIdCreateInfoEXT entityCreateInfo {
      .type = XR_TYPE_SPATIAL_ENTITY_FROM_ID_CREATE_INFO_EXT,
      .entityId = id,
    };

    XrSpatialEntityEXT entity = XR_NULL_HANDLE;
    xrCreateSpatialEntityFromIdEXT(spatialContext, &entityCreateInfo, &entity);

    hitEntities.push_back(entity);
  } else {
    // hit depth
    depthHitPoses.push_back(pose);
  }
}

// Cleanup
xrDestroySpatialSnapshotEXT(completion.snapshot);

レイキャスト スナップショットを作成する

次のサンプルコードは、同期レイキャスト スナップショットを作成する方法を示しています。

// fill in create info
XrSpatialRaycastSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID,
  .componentTypeCount = 0,   // include all hit spatial entities
  .componentTypes = nullptr,
  .raycastInfo = &raycastInfo
};

// create raycast snapshot
XrSpatialSnapshotEXT raycastSnapshot = XR_NULL_HANDLE;
CHK_XR(xrCreateSpatialRaycastSnapshotANDROID(
  spatialContext, &createInfo, &raycastSnapshot));

// ...
// query component data as previous example
// ...

// Cleanup
xrDestroySpatialSnapshotEXT(raycastSnapshot);

新しいコマンド

新しい構造

新しい列挙型定数

  • XR_ANDROID_SPATIAL_DISCOVERY_RAYCAST_EXTENSION_NAME
  • XR_ANDROID_spatial_discovery_raycast_SPEC_VERSION
  • XrSpatialCapabilityEXT の拡張:

    • XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID
  • XrSpatialComponentTypeEXT の拡張:

    • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID
  • XrStructureType の拡張:

    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID
    • XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID
    • XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID
    • XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID

問題

変更履歴

  • リビジョン 1、2025-07-15(Brian Chen)

    • 拡張機能の初期説明。