XR_ANDROID_spatial_discovery_raycast

Name String

XR_ANDROID_spatial_discovery_raycast

Loại phần mở rộng

Tiện ích Instance

Số máy nhánh đã đăng ký

787

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa được phê chuẩn

Phần mở rộng và các phần phụ thuộc của phiên bản

XR_EXT_spatial_entity

Ngày sửa đổi gần đây nhất

2025-08-12

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu nào đã biết về quyền sở hữu trí tuệ.

Cộng tác viên

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

Tổng quan

Tiện ích này được xây dựng dựa trên XR_EXT_spatial_entity và cung cấp chức năng truyền tia cho các chức năng không gian hiện có, chẳng hạn như XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT , để khám phá các thực thể không gian.

Tiện ích này cũng giới thiệu một chức năng không gian mới để truyền tia đối với vùng đệm độ sâu.

Quyền

Các quyền bắt buộc tuỳ thuộc vào những chức năng mà ứng dụng Android sử dụng. Nếu dùng XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID, ứng dụng phải có quyền android.permission.SCENE_UNDERSTANDING_FINE. Nếu dùng XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, ứng dụng phải có quyền android.permission.SCENE_UNDERSTANDING_COARSE. android.permission.SCENE_UNDERSTANDING_FINE cũng ngụ ý quyền android.permission.SCENE_UNDERSTANDING_COARSE. Nếu ứng dụng sử dụng cả hai chức năng, thì ứng dụng không cần yêu cầu cả hai quyền riêng biệt.

Cả android.permission.SCENE_UNDERSTANDING_COARSE và android.permission.SCENE_UNDERSTANDING_FINE đều được coi là các quyền nguy hiểm.

(cấp độ bảo vệ: nguy hiểm)

Hỗ trợ thời gian chạy

Nếu thời gian chạy hỗ trợ việc khám phá các thực thể không gian thông qua tính năng truyền tia, thì thời gian chạy phải cho biết điều này bằng cách liệt kê XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID trong xrEnumerateSpatialCapabilityComponentTypesEXT cho những chức năng hỗ trợ việc khám phá bằng tính năng truyền tia.

Nếu thời gian chạy hỗ trợ truyền tia dựa trên vùng đệm độ sâu, thì thời gian chạy đó phải liệt kê XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID trong xrEnumerateSpatialCapabilitiesEXT .

Khám phá các thực thể không gian bằng cách truyền tia

Cấu trúc XrSpatialRaycastInfoANDROID được xác định như sau:

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • space là XrSpace mà tư thế của XrSpatialRaycastResultDataANDROID sẽ nằm trong đó.
  • time là một XrTime mà tại đó tư thế của XrSpatialRaycastResultDataANDROID được xác định.
  • origin là một XrVector3f mô tả nguồn gốc của tia.
  • direction là một XrVector3f mô tả hướng của tia.
  • maxDistance là khoảng cách (tính bằng mét) mà ứng dụng có thể tuỳ ý chỉ định để giới hạn việc phát hiện các thực thể nằm trong khoảng cách đã chỉ định từ origin , dọc theo direction .

Một ứng dụng có thể đưa XrSpatialRaycastInfoANDROID vào chuỗi XrSpatialDiscoverySnapshotCreateInfoEXT :: next để khám phá các thực thể không gian giao nhau với tia được xác định trong cấu trúc này.

Nếu một ứng dụng sử dụng XrSpatialRaycastInfoANDROID với XrSpatialContextEXT được định cấu hình mà không bật XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID cho bất kỳ khả năng nào, thì thời gian chạy phải trả về XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT từ xrCreateSpatialDiscoverySnapshotAsyncEXT hoặc xrCreateSpatialRaycastSnapshotANDROID .

Thời gian chạy phải bao gồm dữ liệu thành phần và mã nhận dạng của chỉ những thực thể không gian trong XrSpatialSnapshotEXT đến từ các chức năng hỗ trợ thành phần XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID.

Nếu một ứng dụng đặt maxDistance thành một giá trị dương, thì thời gian chạy không được bao gồm bất kỳ thực thể không gian nào trong ảnh chụp nhanh có khoảng cách lớn hơn maxDistance so với panme:origin dọc theo direction . Nếu maxDistance được đặt thành 0 hoặc một giá trị âm, thì thời gian chạy phải coi tia là không giới hạn.

Sử dụng hợp lệ (Ngầm ẩn)

Thành phần kết quả Raycast

Cấu trúc XrSpatialRaycastResultDataANDROID được xác định như sau:

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

Nội dung mô tả thành viên

  • hitPose là một XrPosef xác định điểm mà tia giao với thực thể không gian.
  • distanceSquared là bình phương của khoảng cách từ điểm gốc của tia đến điểm giao nhau.

Thành phần XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID sẽ chỉ xuất hiện trong XrSpatialSnapshotEXT được tạo từ xrCreateSpatialDiscoverySnapshotAsyncEXT, trong đó XrSpatialRaycastInfoANDROID được đưa vào chuỗi XrSpatialDiscoverySnapshotCreateInfoEXT :: next hoặc trong XrSpatialSnapshotEXT được tạo từ xrCreateSpatialRaycastSnapshotANDROID .

Thời gian chạy không được đưa thành phần này vào bất kỳ XrSpatialSnapshotEXT nào được tạo bằng xrCreateSpatialUpdateSnapshotEXT .

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrCreateSpatialUpdateSnapshotEXT nếu ứng dụng có XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID trong XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes .

Nếu XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID chỉ được bật cho một số chức năng nhất định, thì thời gian chạy phải chỉ bao gồm các thực thể không gian do những chức năng đó cung cấp trong ảnh chụp nhanh. Ví dụ: nếu một đối tượng và một mặt phẳng thẳng hàng theo cùng một hướng và XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID chỉ được bật cho XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, thì chỉ mặt phẳng mới được phát hiện.

hitPose của XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID sẽ nằm trong XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: baseSpace tại XrCreateSpatialDiscoverySnapshotCompletionInfoEXT :: time . Trục Z dương là pháp tuyến của bề mặt trúng đích và trục Y âm gần như hướng về phía gốc của tia.

Sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc danh sách thành phần để truy vấn dữ liệu

Cấu trúc XrSpatialComponentRaycastResultListANDROID được xác định như sau:

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • raycastResultCount là một uint32_t mô tả số lượng phần tử trong mảng raycastResults.
  • raycastResults là một mảng XrSpatialRaycastResultDataANDROID .

Để truy vấn thành phần kết quả raycast của các thực thể không gian trong XrSpatialSnapshotEXT , hãy thêm XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID vào XrSpatialComponentDataQueryConditionEXT :: componentTypes và thêm XrSpatialComponentRaycastResultListANDROID vào chuỗi XrSpatialComponentDataQueryResultEXT :: next.

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrQuerySpatialComponentDataEXT nếu XrSpatialComponentRaycastResultListANDROID nằm trong chuỗi XrSpatialComponentDataQueryResultEXT :: next nhưng XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID không có trong XrSpatialComponentDataQueryConditionEXT :: componentTypes .

Thời gian chạy phải trả về XR_ERROR_SIZE_INSUFFICIENT từ xrQuerySpatialComponentDataEXT nếu raycastResultCount nhỏ hơn XrSpatialComponentDataQueryResultEXT :: entityIdCountOutput .

raycastResults được trả về không theo thứ tự. Một ứng dụng có thể sử dụng XrSpatialRaycastResultDataANDROID :: distanceSquared để sắp xếp kết quả theo khoảng cách.

Sử dụng hợp lệ (Ngầm ẩn)

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho một số khả năng, thì ứng dụng có thể bật chức năng đó bằng cách đưa giá trị enum vào danh sách XrSpatialCapabilityConfigurationBaseHeaderEXT :: enabledComponents. Thành phần này không yêu cầu bất kỳ cấu hình đặc biệt nào để được đưa vào chuỗi tiếp theo của XrSpatialCapabilityConfigurationBaseHeaderEXT .

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrCreateSpatialUpdateSnapshotEXT nếu ứng dụng có XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID trong XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes . Thành phần này dành riêng cho ảnh chụp nhanh về hoạt động khám phá.

Khả năng không gian truyền tia theo chiều sâu

Cấu hình

Cấu trúc XrSpatialCapabilityConfigurationDepthRaycastANDROID được xác định như sau:

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • capability là một XrSpatialCapabilityEXT và phải là XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID .
  • enabledComponentCount là một uint32_t mô tả số lượng phần tử trong mảng enabledComponents. Giá trị này phải lớn hơn 0.
  • enabledComponents là con trỏ đến một mảng XrSpatialComponentTypeEXT .

Các ứng dụng có thể bật khả năng không gian XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID bằng cách thêm một con trỏ vào cấu trúc XrSpatialCapabilityConfigurationDepthRaycastANDROID trong XrSpatialContextCreateInfoEXT :: capabilityConfigs .

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE nếu capability không phải là XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID .

Mã nhận dạng của các thực thể được phát hiện thông qua chức năng này luôn là XR_NULL_SPATIAL_ENTITY_ID_EXT . Điều này cũng có nghĩa là ứng dụng không thể tạo một đối tượng XrSpatialEntityEXT cho các thực thể này, và do đó, chúng không thể được đưa vào XrSpatialUpdateSnapshotCreateInfoEXT :: entities để tạo một ảnh chụp nhanh về bản cập nhật

Sử dụng hợp lệ (Ngầm ẩn)

Thành phần được đảm bảo

Thời gian chạy hỗ trợ XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID , phải hỗ trợ các thành phần không gian sau đây dưới dạng các thành phần được đảm bảo của các thực thể được phát hiện bởi khả năng này và phải liệt kê chúng trong xrEnumerateSpatialCapabilityComponentTypesEXT –

  • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Raycast đồng bộ

Hàm xrCreateSpatialRaycastSnapshotANDROID được xác định như sau:

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

Nội dung mô tả về tham số

Mặc dù xrCreateSpatialDiscoverySnapshotAsyncEXT là đủ cho hầu hết các trường hợp sử dụng, nhưng hàm này được coi là chậm đối với những ứng dụng yêu cầu kết quả truyền tia tức thì. xrCreateSpatialRaycastSnapshotANDROID bắt đầu truyền tia đồng bộ để tạo một ảnh chụp nhanh, cho phép các ứng dụng bắt đầu truy vấn kết quả truyền tia ngay lập tức.

Thời gian chạy phải trả về XR_ERROR_SPATIAL_COMPONENT_NOT_ENABLED_EXT nếu bất kỳ XrSpatialComponentTypeEXT nào trong XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes không được bật cho các chức năng không gian được truyền đến XrSpatialContextCreateInfoEXT :: capabilityConfigs khi tạo spatialContext .

Nếu ứng dụng không cung cấp danh sách các loại thành phần không gian trong XrSpatialRaycastSnapshotCreateInfoANDROID :: componentTypes , thì thời gian chạy phải bao gồm tất cả các thực thể không gian trong ảnh chụp nhanh có tập hợp các thành phần được liệt kê trong XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents cho các chức năng được hỗ trợ của raycast được định cấu hình cho spatialContext . Thời gian chạy phải bao gồm dữ liệu cho tất cả các thành phần đã bật của những chức năng được hỗ trợ của raycast được định cấu hình cho spatialContext .

Sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • 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

Cấu trúc XrSpatialRaycastSnapshotCreateInfoANDROID được xác định là:

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • componentTypeCount là một uint32_t mô tả số lượng phần tử trong mảng componentTypes.
  • componentTypes là một mảng XrSpatialComponentTypeEXT .
  • raycastInfo là cấu trúc XrSpatialRaycastInfoANDROID mô tả thông tin về một tia.

Sử dụng hợp lệ (Ngầm ẩn)

Mã ví dụ

Định cấu hình tính năng theo dõi mặt phẳng và truyền tia theo độ sâu

Đoạn mã ví dụ sau đây minh hoạ cách tạo một bối cảnh không gian có các chức năng hỗ trợ tính năng truyền tia. Trong ví dụ này, XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID và XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT được sử dụng.

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

Khám phá các thực thể không gian và dữ liệu thành phần truy vấn

Đoạn mã ví dụ sau đây minh hoạ cách khám phá các thực thể không gian cho một bối cảnh được định cấu hình bằng XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID và XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, đồng thời truy vấn dữ liệu thành phần của thực thể đó.

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

Tạo ảnh chụp nhanh bằng Raycast

Đoạn mã ví dụ sau đây minh hoạ cách tạo ảnh chụp nhanh tia truyền đồng bộ.

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

Lệnh mới

Cấu trúc mới

Hằng số Enum mới

  • XR_ANDROID_SPATIAL_DISCOVERY_RAYCAST_EXTENSION_NAME
  • XR_ANDROID_spatial_discovery_raycast_SPEC_VERSION

  • Mở rộng XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID

  • Mở rộng XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

  • Mở rộng 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

Vấn đề

Danh sách phiên bản

  • Bản sửa đổi 1, ngày 15/7/2025 (Brian Chen)

    • Nội dung mô tả ban đầu của tiện ích.