XR_ANDROID_spatial_discovery_raycast

String Nama

XR_ANDROID_spatial_discovery_raycast

Jenis Ekstensi

Ekstensi instance

Nomor Ekstensi Terdaftar

787

Revisi

1

Status Ratifikasi

Tidak diratifikasi

Dependensi Ekstensi dan Versi

XR_EXT_spatial_entity

Tanggal Terakhir Diubah

2025-08-12

Status IP

Tidak ada klaim IP yang diketahui.

Kontributor

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

Ringkasan

Ekstensi ini dibuat berdasarkan XR_EXT_spatial_entity dan menyediakan fungsi raycast untuk kemampuan spasial yang ada, seperti XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , untuk menemukan entitas spasial.

Ekstensi ini juga memperkenalkan kemampuan spasial baru untuk raycasting terhadap buffer kedalaman.

Izin

Izin yang diperlukan bergantung pada kemampuan yang digunakan aplikasi Android. Jika XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID digunakan, aplikasi harus memiliki izin android.permission.SCENE_UNDERSTANDING_FINE. Jika XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT digunakan, aplikasi harus memiliki izin android.permission.SCENE_UNDERSTANDING_COARSE. android.permission.SCENE_UNDERSTANDING_FINE juga menyiratkan izin android.permission.SCENE_UNDERSTANDING_COARSE. Jika aplikasi menggunakan kedua kemampuan tersebut, aplikasi tidak perlu meminta kedua izin secara terpisah.

android.permission.SCENE_UNDERSTANDING_COARSE dan android.permission.SCENE_UNDERSTANDING_FINE dianggap sebagai izin berbahaya.

(tingkat perlindungan: berbahaya)

Dukungan Runtime

Jika runtime mendukung penemuan entitas spasial melalui raycasting, runtime harus menunjukkannya dengan mencantumkan XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID di xrEnumerateSpatialCapabilityComponentTypesEXT untuk kemampuan yang mendukung penemuan dengan raycast.

Jika runtime mendukung raycasting terhadap buffer kedalaman, runtime harus menghitung XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID dalam xrEnumerateSpatialCapabilitiesEXT .

Menemukan entitas spasial dengan raycasting

Struktur XrSpatialRaycastInfoANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • space adalah XrSpace tempat pose XrSpatialRaycastResultDataANDROID akan berada.
  • time adalah XrTime tempat pose XrSpatialRaycastResultDataANDROID ditentukan.
  • origin adalah XrVector3f yang menjelaskan asal sinar.
  • direction adalah XrVector3f yang menjelaskan arah sinar.
  • maxDistance adalah jarak dalam meter yang dapat ditentukan secara opsional oleh aplikasi untuk membatasi penemuan entitas yang berada dalam jarak yang ditentukan dari origin , di sepanjang direction .

Aplikasi dapat menyertakan XrSpatialRaycastInfoANDROID dalam rantai XrSpatialDiscoverySnapshotCreateInfoEXT :: next untuk menemukan entitas spasial yang berpotongan dengan sinar yang ditentukan dalam struktur ini.

Jika aplikasi menggunakan XrSpatialRaycastInfoANDROID dengan XrSpatialContextEXT yang dikonfigurasi tanpa mengaktifkan XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID untuk kemampuan apa pun, runtime harus menampilkan XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT dari xrCreateSpatialDiscoverySnapshotAsyncEXT atau xrCreateSpatialRaycastSnapshotANDROID .

Runtime harus menyertakan data dan ID komponen hanya dari entitas spasial tersebut di XrSpatialSnapshotEXT yang berasal dari kemampuan yang mendukung komponen XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID.

Jika aplikasi menyetel maxDistance ke nilai positif, runtime tidak boleh menyertakan entity spasial hit apa pun dalam snapshot yang berjarak lebih dari maxDistance dari panme:origin di sepanjang direction . Jika maxDistance disetel ke 0 atau nilai negatif, runtime harus menganggap sinar tidak terbatas.

Penggunaan yang Valid (Implisit)

Komponen Hasil Raycast

Struktur XrSpatialRaycastResultDataANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • hitPose adalah XrPosef yang menentukan titik tempat sinar berpotongan dengan entitas spasial.
  • distanceSquared adalah kuadrat jarak dari asal sinar ke titik persimpangan.

Komponen XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID hanya akan ada di XrSpatialSnapshotEXT yang dibuat dari xrCreateSpatialDiscoverySnapshotAsyncEXT dengan XrSpatialRaycastInfoANDROID disertakan dalam rantai XrSpatialDiscoverySnapshotCreateInfoEXT :: next atau di XrSpatialSnapshotEXT yang dibuat dari xrCreateSpatialRaycastSnapshotANDROID .

Runtime tidak boleh menyertakan komponen ini dalam XrSpatialSnapshotEXT apa pun yang dibuat menggunakan xrCreateSpatialUpdateSnapshotEXT .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrCreateSpatialUpdateSnapshotEXT jika aplikasi menyertakan XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID di XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes .

Jika XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID hanya diaktifkan untuk kemampuan tertentu, harus menyertakan hanya entitas spasial yang disediakan oleh kemampuan tersebut dalam snapshot. Misalnya, jika objek dan bidang sejajar ke arah yang sama dan XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID hanya diaktifkan untuk XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , hanya bidang yang akan ditemukan.

hitPose dari XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID akan berada di XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace di XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time . Sumbu Z positif adalah normal permukaan yang terkena, dan sumbu Y negatif kira-kira mengarah ke asal sinar.

Penggunaan yang Valid (Implisit)

Struktur daftar komponen untuk mengkueri data

Struktur XrSpatialComponentRaycastResultListANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • raycastResultCount adalah uint32_t yang menjelaskan jumlah elemen dalam array raycastResults.
  • raycastResults adalah array XrSpatialRaycastResultDataANDROID .

Untuk membuat kueri komponen hasil raycast entitas spasial dalam XrSpatialSnapshotEXT , sertakan XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes dan tambahkan XrSpatialComponentRaycastResultListANDROID ke rantai XrSpatialComponentDataQueryResultEXT :: next.

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrQuerySpatialComponentDataEXT jika XrSpatialComponentRaycastResultListANDROID ada dalam rantai XrSpatialComponentDataQueryResultEXT :: next, tetapi XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID tidak disertakan dalam XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Runtime harus menampilkan XR_ERROR_SIZE_INSUFFICIENT dari xrQuerySpatialComponentDataEXT jika raycastResultCount kurang dari XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

raycastResults yang ditampilkan tidak berurutan. Aplikasi dapat menggunakan XrSpatialRaycastResultDataANDROID :: distanceSquared untuk mengurutkan hasil menurut jarak.

Penggunaan yang Valid (Implisit)

Konfigurasi

Jika XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID tercantum dalam XrSpatialCapabilityComponentTypesEXT :: componentTypes untuk beberapa kemampuan, aplikasi dapat mengaktifkannya dengan menyertakan nilai enum dalam daftar XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Komponen ini tidak memerlukan konfigurasi khusus untuk disertakan dalam rantai XrSpatialCapabilityConfigurationBaseHeaderEXT berikutnya .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE dari xrCreateSpatialUpdateSnapshotEXT jika aplikasi menyertakan XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID di XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Komponen ini khusus untuk snapshot penemuan.

Kemampuan Spasial Depth Raycast

Konfigurasi

Struktur XrSpatialCapabilityConfigurationDepthRaycastANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur.
  • capability adalah XrSpatialCapabilityEXT dan harus berupa XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID .
  • enabledComponentCount adalah uint32_t yang menjelaskan jumlah elemen dalam array enabledComponents. Nilainya harus lebih besar dari 0.
  • enabledComponents adalah pointer ke array XrSpatialComponentTypeEXT .

Aplikasi dapat mengaktifkan kemampuan spasial XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID dengan menyertakan pointer ke struktur XrSpatialCapabilityConfigurationDepthRaycastANDROID di XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Runtime harus menampilkan XR_ERROR_VALIDATION_FAILURE jika capability bukan XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID .

ID entitas yang ditemukan melalui kemampuan ini selalu XR_NULL_SPATIAL_ENTITY_ID_EXT . Ini juga berarti aplikasi tidak dapat membuat handle XrSpatialEntityEXT untuk entitas ini, sehingga entitas tersebut tidak dapat disertakan dalam XrSpatialUpdateSnapshotCreateInfoEXT :: entities untuk membuat snapshot update

Penggunaan yang Valid (Implisit)

Komponen yang Dijamin

Runtime yang mendukung XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID , harus mendukung komponen spasial berikut sebagai komponen terjamin dari entitas yang ditemukan oleh kemampuan ini dan harus mencantumkannya di xrEnumerateSpatialCapabilityComponentTypesEXT -

  • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Raycast Sinkron

Fungsi xrCreateSpatialRaycastSnapshotANDROID ditentukan sebagai:

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

Deskripsi Parameter

Meskipun xrCreateSpatialDiscoverySnapshotAsyncEXT sudah cukup untuk sebagian besar kasus penggunaan, fungsi ini dianggap lambat untuk aplikasi yang memerlukan hasil raycast instan. xrCreateSpatialRaycastSnapshotANDROID memulai raycasting sinkron untuk membuat snapshot, yang memungkinkan aplikasi mulai mengkueri hasil raycast dengan segera.

Runtime harus menampilkan XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT jika ada XrSpatialComponentTypeEXT di XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes yang tidak diaktifkan untuk kemampuan spasial yang diteruskan ke XrSpatialContextCreateInfoEXT :: capabilityConfigs saat membuat spatialContext .

Jika aplikasi tidak menyediakan daftar jenis komponen spasial di XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes , runtime harus menyertakan semua entity spasial dalam snapshot yang memiliki kumpulan komponen yang tercantum di XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents untuk kemampuan yang didukung raycast yang dikonfigurasi untuk spatialContext . Runtime harus menyertakan data untuk semua komponen yang diaktifkan dari kemampuan yang didukung raycast yang dikonfigurasi untuk spatialContext .

Penggunaan yang Valid (Implisit)

Kode Status

Berhasil

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Kegagalan

  • 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

Struktur XrSpatialRaycastSnapshotCreateInfoANDROID ditentukan sebagai:

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

Deskripsi Anggota

  • type adalah XrStructureType dari struktur ini.
  • next adalah NULL atau pointer ke struktur berikutnya dalam rantai struktur. Tidak ada struktur seperti itu yang ditentukan dalam OpenXR inti atau ekstensi ini.
  • componentTypeCount adalah uint32_t yang menjelaskan jumlah elemen dalam array componentTypes.
  • componentTypes adalah array XrSpatialComponentTypeEXT .
  • raycastInfo adalah struktur XrSpatialRaycastInfoANDROID yang menjelaskan informasi sinar.

Penggunaan yang Valid (Implisit)

Kode contoh

Mengonfigurasi Kemampuan Depth Raycast dan Plane Tracking

Contoh kode berikut menunjukkan cara membuat konteks spasial dengan kemampuan yang mendukung fungsi raycast. Untuk contoh ini, XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID dan XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT digunakan.

// 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))

Menemukan Entitas Spasial & Data Komponen Kueri

Contoh kode berikut menunjukkan cara menemukan entitas spasial untuk konteks yang dikonfigurasi dengan XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID & XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT dan mengkueri data komponennya.

// 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);

Membuat Snapshot Raycast

Contoh kode berikut menunjukkan cara membuat snapshot raycast sinkron.

// 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);

Perintah Baru

Struktur Baru

Konstanta Enum Baru

  • XR_ANDROID_SPATIAL_DISCOVERY_RAYCAST_EXTENSION_NAME
  • XR_ANDROID_spatial_discovery_raycast_SPEC_VERSION

  • Memperluas XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

  • Memperluas XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

  • Memperluas 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

Masalah

Riwayat Versi

  • Revisi 1, 15-07-2025 (Brian Chen)

    • Deskripsi ekstensi awal.