XR_ANDROID_spatial_discovery_raycast

Name String

XR_ANDROID_spatial_discovery_raycast

Loại tiện ích

Phần mở rộng thực thể

Số máy lẻ đã đăng ký

787

Bản sửa đổi

1

Trạng thái phê chuẩn

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

Phần phụ thuộc của tiện ích và 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ó tuyên bố nào về tài sản 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 tính năng không gian mới để truyền tia đối với vùng đệm độ sâu.

Quyền

Các quyền cần thiết tuỳ thuộc vào chức năng mà ứng dụng Android sử dụng. Nếu sử dụng XR_SPATIAL_CAPABILITY_DEPTH_RAYCAST_ANDROID, ứng dụng phải có quyền android.permission.SCENE_UNDERSTANDING_FINE. Nếu sử dụng XR_SPATIAL_CAPABILITY_PLANE_TRACKING_EXT, ứng dụng phải có quyền android.permission.SCENE_UNDERSTANDING_COARSE. Quyền android.permission.SCENE_UNDERSTANDING_FINE cũng bao hàm 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 riêng từng quyền.

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

(mức độ 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á 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 các 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ợ tính năng truyền tia đối với 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 kỹ thuật raycasting

Cấu trúc XrSpatialRaycastInfoANDROID được định nghĩa 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ả về thành viên

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
• space là XrSpace nơi đặt tư thế của XrSpatialRaycastResultDataANDROID.
• time là một XrTime mà tư thế của XrSpatialRaycastResultDataANDROID được xác định.
• origin là một XrVector3f mô tả 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 khám phá các thực thể nằm trong khoảng cách đã chỉ định từ origin , dọc theo direction .

Ứng dụng có thể thêm 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ỳ chức 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 đưa bất kỳ thực thể không gian nào vào ảnh chụp nhanh cách panme:origin hơn maxDistance dọc theo direction . Nếu maxDistance được đặt thành 0 hoặc giá trị âm, thì thời gian chạy phải coi tia là không giới hạn.

Cách sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_ANDROID_spatial_discovery_raycast trước khi sử dụng XrSpatialRaycastInfoANDROID
• type phải là XR_TYPE_SPATIAL_RAYCAST_INFO_ANDROID
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• space phải là một tên người dùng XrSpace hợp lệ

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

Cấu trúc XrSpatialRaycastResultDataANDROID được định nghĩa như sau:

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

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

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

Thành phần XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID sẽ chỉ có 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 bao gồm 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 chỉ được bao gồm các thực thể không gian do các 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 xếp 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 va chạm và trục Y âm gần như hướng về gốc tia.

Cách sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_ANDROID_spatial_discovery_raycast trước khi sử dụng XrSpatialRaycastResultDataANDROID

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

Cấu trúc XrSpatialComponentRaycastResultListANDROID được định nghĩa như sau:

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

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ 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ả truyền tia 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ự. Ứng dụng có thể sử dụng XrSpatialRaycastResultDataANDROID :: distanceSquared để sắp xếp kết quả theo khoảng cách.

Cách sử dụng hợp lệ (Ngầm ẩn)

• Phải bật tiện ích XR_ANDROID_spatial_discovery_raycast trước khi sử dụng XrSpatialComponentRaycastResultListANDROID
• type phải là XR_TYPE_SPATIAL_COMPONENT_RAYCAST_RESULT_LIST_ANDROID
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• raycastResults phải là một con trỏ đến một mảng gồm các cấu trúc raycastResultCount XrSpatialRaycastResultDataANDROID
• Tham số raycastResultCount phải lớn hơn 0

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID được liệt kê trong XrSpatialCapabilityComponentTypesEXT :: componentTypes cho một số chức 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 để đưa vào chuỗi XrSpatialCapabilityConfigurationBaseHeaderEXT tiếp theo.

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrCreateSpatialUpdateSnapshotEXT nếu ứng dụng bao gồm 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 khám phá.

Khả năng không gian của tia truyền sâu

Cấu hình

Cấu trúc XrSpatialCapabilityConfigurationDepthRaycastANDROID được định nghĩa như sau:

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

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ 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 .

Ứng dụng có thể bật chức 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 tay điều khiển XrSpatialEntityEXT cho các thực thể này, do đó, các thực thể này không thể được đưa vào XrSpatialUpdateSnapshotCreateInfoEXT :: entities để tạo ảnh chụp nhanh cập nhật

Cách sử dụng hợp lệ (Ngầm ẩn)

• Phải bật tiện ích XR_ANDROID_spatial_discovery_raycast trước khi sử dụng XrSpatialCapabilityConfigurationDepthRaycastANDROID
• type phải là XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_DEPTH_RAYCAST_ANDROID
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• capability phải là một giá trị XrSpatialCapabilityEXT hợp lệ
• enabledComponents phải là một con trỏ đến một mảng gồm enabledComponentCount giá trị XrSpatialComponentTypeEXT hợp lệ
• Tham số enabledComponentCount phải lớn hơn 0

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

Môi trường 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 thành phần được đảm bảo của các thực thể mà chức năng này phát hiện được và phải liệt kê các thành phần đó trong xrEnumerateSpatialCapabilityComponentTypesEXT –

• XR_SPATIAL_COMPONENT_TYPE_RAYCAST_RESULT_ANDROID

Raycast đồng bộ

Hàm xrCreateSpatialRaycastSnapshotANDROID được định nghĩa như sau:

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

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

• spatialContext là một XrSpatialContextEXT được tạo trước đó bằng cách sử dụng xrCreateSpatialContextAsyncEXT .
• createInfo là con trỏ đến XrSpatialRaycastSnapshotCreateInfoANDROID .
• snapshot là con trỏ đến XrSpatialSnapshotEXT .

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 các ứng dụng yêu cầu kết quả truyền tia tức thì. xrCreateSpatialRaycastSnapshotANDROID bắt đầu một quá trình truyền tia đồng bộ để tạo ả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 thành phần được liệt kê trong XrSpatialCapabilityConfigurationBaseHeaderEXT ::enabledComponents cho các chức năng được hỗ trợ 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 được bật của các chức năng được hỗ trợ raycast được định cấu hình cho spatialContext .

Cách sử dụng hợp lệ (Ngầm ẩn)

• Bạn phải bật tiện ích XR_ANDROID_spatial_discovery_raycast trước khi gọi xrCreateSpatialRaycastSnapshotANDROID
• spatialContext phải là một tay điều khiển XrSpatialContextEXT hợp lệ
• createInfo phải là một con trỏ đến cấu trúc XrSpatialRaycastSnapshotCreateInfoANDROID hợp lệ
• snapshot phải là một con trỏ đến một tay điều khiển XrSpatialSnapshotEXT

Mã trả về

Thành công

• XR_SUCCESS
• XR_SESSION_LOSS_PENDING

Không thành công

• 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 định nghĩa như sau:

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

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

• type là XrStructureType của cấu trúc này.
• next là NULL hoặc con trỏ 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 của một tia.

Cách sử dụng hợp lệ (Ngầm ẩn)

• Tiện ích XR_ANDROID_spatial_discovery_raycast phải được bật trước khi sử dụng XrSpatialRaycastSnapshotCreateInfoANDROID
• type phải là XR_TYPE_SPATIAL_RAYCAST_SNAPSHOT_CREATE_INFO_ANDROID
• next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
• Nếu componentTypeCount không phải là 0 , thì componentTypes phải là con trỏ đến một mảng gồm các giá trị componentTypeCount hợp lệ của XrSpatialComponentTypeEXT
• raycastInfo phải là một con trỏ đến cấu trúc XrSpatialRaycastInfoANDROID hợp lệ

Mã ví dụ

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

Mã ví dụ sau đây minh hoạ cách tạo bối cảnh không gian có các chức năng hỗ trợ chức 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á thực thể không gian và dữ liệu thành phần truy vấ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 bối cảnh đó.

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

Mã ví dụ sau đây minh hoạ cách tạo ảnh chụp nhanh raycast đồ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

• xrCreateSpatialRaycastSnapshotANDROID

Cấu trúc mới

• XrSpatialCapabilityConfigurationDepthRaycastANDROID
• XrSpatialRaycastResultDataANDROID
• XrSpatialRaycastSnapshotCreateInfoANDROID

• Mở rộng XrSpatialComponentDataQueryResultEXT :

  • XrSpatialComponentRaycastResultListANDROID

• Mở rộng XrSpatialDiscoverySnapshotCreateInfoEXT :

  • XrSpatialRaycastInfoANDROID

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 tháng 7 năm 2025 (Brian Chen)

  • Nội dung mô tả ban đầu về tiện ích.