XR_EXT_spatial_persistence

Name String

XR_EXT_spatial_persistence

Loại tiện ích

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

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

764

Bản sửa đổi

1

Trạng thái phê chuẩn

Đã phê chuẩn

Phần phụ thuộc của tiện ích và phiên bản

XR_EXT_spatial_entity
và
XR_EXT_future

Cộng tác viên

Nihav Jain, Google
Jared Finder, Google
Natalie Fleury, Meta
Yuichi Taguchi, Meta
Ron Bessems, Meta
Yin Li, Microsoft
Jimmy Alamparambil, ByteDance
Zhipeng Liu, ByteDance
Jun Yan, ByteDance

Tổng quan

Tiện ích này cho phép các ứng dụng khám phá và liên kết các thực thể không gian trên các phiên ứng dụng, phiên OpenXR và nhiều bối cảnh không gian OpenXR trong một phiên. Tiện ích XR_EXT_spatial_entity xác định rằng một thực thể trong XrSpatialContextEXT được biểu thị bằng XrSpatialEntityIdEXT . Tiện ích này mở rộng khái niệm đó bằng cách thiết lập rằng một thực thể, nếu được duy trì, sẽ được biểu thị bằng XrUuid trên các phiên ứng dụng và OpenXR, tức là một ứng dụng có thể sử dụng XrUuid do tiện ích này cung cấp để xác định một thực thể trên các phiên. Tiện ích này cũng cung cấp các điểm trùng lặp hữu ích với tiện ích XR_EXT_spatial_entity để khám phá các thực thể được duy trì trong môi trường của người dùng và khả năng truy vấn dữ liệu thành phần của các thực thể đó.

Bối cảnh lưu trữ không gian

Tạo bối cảnh lưu trữ không gian

XR_DEFINE_HANDLE(XrSpatialPersistenceContextEXT)

Tay điều khiển XrSpatialPersistenceContextEXT đại diện cho kết nối với bộ nhớ thực thể không gian cố định.

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

XrResult xrCreateSpatialPersistenceContextAsyncEXT(
    XrSession                                   session,
    const XrSpatialPersistenceContextCreateInfoEXT* createInfo,
    XrFutureEXT*                                future);

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

  • session là một XrSession, trong đó bối cảnh lưu trữ không gian sẽ hoạt động.
  • createInfo là XrSpatialPersistenceContextCreateInfoEXT dùng để chỉ định các tham số bối cảnh lưu trữ không gian.
  • future là con trỏ đến XrFutureEXT .

Ứng dụng có thể tạo một tay điều khiển XrSpatialPersistenceContextEXT bằng hàm xrCreateSpatialPersistenceContextAsyncEXT và định cấu hình phạm vi của bối cảnh cố định trong createInfo .

Thời gian chạy phải trả về XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT nếu XrSpatialPersistenceContextCreateInfoEXT :: scope không được liệt kê bằng xrEnumerateSpatialPersistenceScopesEXT .

Nếu một thời gian chạy thực thi hệ thống quyền để kiểm soát quyền truy cập của ứng dụng vào bộ nhớ cố định do XrSpatialPersistenceContextEXT biểu thị, thì thời gian chạy phải trả về XR_ERROR_PERMISSION_INSUFFICIENT nếu các quyền đó chưa được cấp cho ứng dụng này.

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

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_PERSISTENCE_SCOPE_UNSUPPORTED_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialPersistenceContextCreateInfoEXT {
    XrStructureType                 type;
    const void*                     next;
    XrSpatialPersistenceScopeEXT    scope;
} XrSpatialPersistenceContextCreateInfoEXT;

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.
  • scope là một XrSpatialPersistenceScopeEXT xác định phạm vi lưu trữ của bối cảnh lưu trữ lâu dài.

Cấu trúc XrSpatialPersistenceContextCreateInfoEXT mô tả thông tin để tạo một tay điều khiển XrSpatialPersistenceContextEXT.

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

typedef enum XrSpatialPersistenceScopeEXT {
    XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT = 1,
    XR_SPATIAL_PERSISTENCE_SCOPE_LOCAL_ANCHORS_EXT = 1000781000,
    XR_SPATIAL_PERSISTENCE_SCOPE_ANCHORS_FOR_CLOUD_SHARING_ANDROIDX1 = 1000808000,
    XR_SPATIAL_PERSISTENCE_SCOPE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceScopeEXT;

Bảng liệt kê XrSpatialPersistenceScopeEXT xác định các loại phạm vi bối cảnh cố định khác nhau.

Các enum có ý nghĩa như sau:

Nội dung mô tả enum

XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT

Cung cấp cho ứng dụng quyền chỉ đọc (tức là ứng dụng không thể sửa đổi kho lưu trữ liên kết với phạm vi này) đối với các thực thể không gian được hệ thống lưu trữ và quản lý. Ứng dụng có thể sử dụng UUID trong thành phần cố định cho phạm vi này để liên kết các thực thể trên các bối cảnh không gian và các lần khởi động lại thiết bị.

XR_SPATIAL_PERSISTENCE_SCOPE_LOCAL_ANCHORS_EXT

Các thao tác lưu trữ và truy cập dữ liệu chỉ áp dụng cho neo không gian, trên cùng một thiết bị, cho cùng một người dùng và cùng một ứng dụng (Do tiện ích XR_EXT_spatial_persistence_operations thêm vào)

XR_SPATIAL_PERSISTENCE_SCOPE_ANCHORS_FOR_CLOUD_SHARING_ANDROIDX1

Các thao tác lưu trữ và truy cập dữ liệu chỉ áp dụng cho các neo không gian, do cùng một dự án trên đám mây sở hữu và quản lý. (Do tiện ích XR_ANDROIDX1_spatial_anchor_cloud_sharing thêm)

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

XrResult xrEnumerateSpatialPersistenceScopesEXT(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    persistenceScopeCapacityInput,
    uint32_t*                                   persistenceScopeCountOutput,
    XrSpatialPersistenceScopeEXT*               persistenceScopes);

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

  • instance là một tay điều khiển cho XrInstance .
  • systemId là XrSystemId có phạm vi lưu trữ không gian sẽ được liệt kê.
  • persistenceScopeCapacityInput là dung lượng của mảng persistenceScopes hoặc 0 để cho biết yêu cầu truy xuất dung lượng cần thiết.
  • persistenceScopeCountOutput là số lượng phạm vi lưu trữ cố định hoặc dung lượng cần thiết trong trường hợp persistenceScopeCapacityInput không đủ.
  • persistenceScopes là một mảng XrSpatialPersistenceScopeEXT . Giá trị này có thể là NULL nếu persistenceScopeCapacityInput là 0.
  • Xem chương Tham số dung lượng bộ nhớ đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước persistenceScopes cần thiết.

Ứng dụng có thể liệt kê danh sách các phạm vi lưu trữ không gian được một XrSystemId nhất định hỗ trợ bằng cách sử dụng xrEnumerateSpatialPersistenceScopesEXT .

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

  • Tiện ích XR_EXT_spatial_persistence phải được bật trước khi gọi xrEnumerateSpatialPersistenceScopesEXT
  • instance phải là một tên người dùng XrInstance hợp lệ
  • persistenceScopeCountOutput phải là con trỏ đến giá trị uint32_t
  • Nếu persistenceScopeCapacityInput không phải là 0 , thì persistenceScopes phải là con trỏ đến một mảng các giá trị persistenceScopeCapacityInput XrSpatialPersistenceScopeEXT

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCreateSpatialPersistenceContextCompleteEXT(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialPersistenceContextCompletionEXT* completion);

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

xrCreateSpatialPersistenceContextCompleteEXT hoàn tất thao tác không đồng bộ do xrCreateSpatialPersistenceContextAsyncEXT bắt đầu. Thời gian chạy phải trả về XR_ERROR_FUTURE_PENDING_EXT nếu future không ở trạng thái sẵn sàng. Thời gian chạy phải trả về XR_ERROR_FUTURE_INVALID_EXT nếu future đã hoàn tất hoặc bị huỷ.

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

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_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • 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_VALIDATION_FAILURE

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

typedef struct XrCreateSpatialPersistenceContextCompletionEXT {
    XrStructureType                         type;
    void*                                   next;
    XrResult                                futureResult;
    XrSpatialPersistenceContextResultEXT    createResult;
    XrSpatialPersistenceContextEXT          persistenceContext;
} XrCreateSpatialPersistenceContextCompletionEXT;

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

Mã trả về trong tương lai

Giá trị futureResult:

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_PERMISSION_INSUFFICIENT

Nếu futureResult và createResult đều là mã thành công, thì persistenceContext phải hợp lệ. Nếu persistenceContext hợp lệ, thì giá trị này phải được giữ nguyên trong vòng đời của xrCreateSpatialPersistenceContextAsyncEXT :: session hoặc cho đến khi ứng dụng sử dụng xrDestroySpatialPersistenceContextEXT với persistenceContext , tuỳ theo điều kiện nào xảy ra trước.

Môi trường thời gian chạy phải đặt createResult chỉ khi futureResult là mã thành công.

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

typedef enum XrSpatialPersistenceContextResultEXT {
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT = 0,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT = -1000781001,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_PERSIST_UUID_NOT_FOUND_EXT = -1000781002,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_LOCALIZATION_FAILURE_ANDROIDX1 = -1000808000,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAP_FEATURE_INSUFFICIENT_ANDROIDX1 = -1000808001,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_FAILURE_ANDROIDX1 = -1000808002,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_TIMEOUT_ANDROIDX1 = -1000808003,
    XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceContextResultEXT;

Bảng liệt kê XrSpatialPersistenceContextResultEXT xác định các loại mã kết quả khác nhau cho một thao tác lưu trữ cố định. Lỗi trong quá trình duy trì không phải lúc nào cũng nằm trong tầm kiểm soát của ứng dụng và việc liệt kê này được dùng để truyền tải các trường hợp như vậy. Tương tự như XrResult, mã thành công trong enum XrSpatialPersistenceContextResultEXT là các giá trị không âm và mã không thành công là các giá trị âm.

Các enum có ý nghĩa như sau:

Nội dung mô tả enum

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT

Thao tác bối cảnh duy trì đã thành công.

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_ENTITY_NOT_TRACKING_EXT

Thao tác duy trì không thành công vì thời gian chạy không theo dõi được thực thể. (Do tiện ích XR_EXT_spatial_persistence_operations thêm)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_PERSIST_UUID_NOT_FOUND_EXT

Không tìm thấy UUID cố định được cung cấp trong bộ nhớ. (Do tiện ích XR_EXT_spatial_persistence_operations thêm)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_LOCALIZATION_FAILURE_ANDROIDX1

Thao tác duy trì không thành công vì không thể bản địa hoá. (Do tiện ích XR_ANDROIDX1_spatial_anchor_cloud_sharing thêm)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_MAP_FEATURE_INSUFFICIENT_ANDROIDX1

Thao tác lưu trữ không thành công vì tính năng bản đồ bản địa hoá không đủ. (Do tiện ích XR_ANDROIDX1_spatial_anchor_cloud_sharing thêm)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_FAILURE_ANDROIDX1

Thao tác duy trì không thành công do kết nối mạng không thành công. (Do tiện ích XR_ANDROIDX1_spatial_anchor_cloud_sharing thêm)

XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_NETWORK_TIMEOUT_ANDROIDX1

Thao tác lưu trữ không thành công do hết thời gian chờ mạng. (Do tiện ích XR_ANDROIDX1_spatial_anchor_cloud_sharing thêm)

Huỷ bỏ bối cảnh lưu trữ không gian

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

XrResult xrDestroySpatialPersistenceContextEXT(
    XrSpatialPersistenceContextEXT              persistenceContext);

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

Ứng dụng có thể sử dụng xrDestroySpatialPersistenceContextEXT để giải phóng tay điều khiển persistenceContext khi hoàn tất các tác vụ lưu trữ không gian.

Thời gian chạy không được huỷ các tài nguyên cơ bản cho persistenceContext khi xrDestroySpatialPersistenceContextEXT được gọi nếu có bất kỳ tay điều khiển XrSpatialContextEXT hợp lệ nào mà persistenceContext được liên kết thông qua XrSpatialContextPersistenceConfigEXT . Điều này là do tài nguyên của bối cảnh cố định vẫn được bối cảnh không gian sử dụng để khám phá các thực thể cố định. Trong trường hợp này, việc huỷ bỏ tay điều khiển bối cảnh cố định chỉ xoá quyền truy cập của ứng dụng vào các tài nguyên này.

Tài nguyên cho XrSpatialPersistenceContextEXT bị huỷ phải được giải phóng khi tất cả các tay điều khiển XrSpatialContextEXT mà bối cảnh cố định được liên kết đều bị huỷ.

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

Độ an toàn cho chuỗi

  • Quyền truy cập vào persistenceContext và mọi tay điều khiển con phải được đồng bộ hoá bên ngoài

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Khám phá các thực thể được lưu trữ lâu dài

Thành phần lưu trữ lâu dài

Thực thể không gian cố định có thành phần cố định mà thời gian chạy phải đưa vào ảnh chụp nhanh khám phá và cập nhật nếu XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT được bật trong quá trình tạo XrSpatialContextEXT và được đưa vào XrSpatialDiscoverySnapshotCreateInfoEXT :: componentTypes hoặc XrSpatialUpdateSnapshotCreateInfoEXT :: componentTypes .

Dữ liệu thành phần

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

typedef struct XrSpatialPersistenceDataEXT {
    XrUuid                          persistUuid;
    XrSpatialPersistenceStateEXT    persistState;
} XrSpatialPersistenceDataEXT;

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

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

typedef enum XrSpatialPersistenceStateEXT {
    XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT = 1,
    XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT = 2,
    XR_SPATIAL_PERSISTENCE_STATE_MAX_ENUM_EXT = 0x7FFFFFFF
} XrSpatialPersistenceStateEXT;

Bảng liệt kê XrSpatialPersistenceStateEXT xác định các trạng thái khác nhau của uuid được duy trì.

Các enum có ý nghĩa như sau:

Nội dung mô tả enum

XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT

Đã tải thành công UUID cố định từ bộ nhớ.

XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT

Không tìm thấy UUID cố định trong bộ nhớ và UUID này đã bị xoá khỏi bộ nhớ hoặc chưa từng có trong bộ nhớ.

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

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

typedef struct XrSpatialComponentPersistenceListEXT {
    XrStructureType                 type;
    void*                           next;
    uint32_t                        persistDataCount;
    XrSpatialPersistenceDataEXT*    persistData;
} XrSpatialComponentPersistenceListEXT;

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.
  • persistDataCount là một uint32_t mô tả số lượng phần tử trong mảng persistData.
  • persistData là một mảng XrSpatialPersistenceDataEXT .

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

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

Không giống như các thành phần khác, thời gian chạy phải đặt dữ liệu cho XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT bất kể XrSpatialEntityTrackingStateEXT .

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

Cấu hình

Nếu XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT đượ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 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. Nếu ứng dụng bao gồm XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT trong danh sách thành phần được bật, thì ứng dụng đó cũng phải bao gồm XrSpatialContextPersistenceConfigEXT trong chuỗi tiếp theo của XrSpatialContextCreateInfoEXT, nếu không, thời gian chạy phải trả về XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT từ xrCreateSpatialContextAsyncEXT .

Định cấu hình bối cảnh không gian bằng bối cảnh cố định

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

typedef struct XrSpatialContextPersistenceConfigEXT {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 persistenceContextCount;
    const XrSpatialPersistenceContextEXT*    persistenceContexts;
} XrSpatialContextPersistenceConfigEXT;

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.
  • persistenceContextCount là một uint32_t mô tả số lượng phần tử trong mảng persistenceContexts.
  • persistenceContexts là một mảng XrSpatialPersistenceContextEXT .

Ứng dụng có thể thêm XrSpatialContextPersistenceConfigEXT vào chuỗi tiếp theo của XrSpatialContextCreateInfoEXT . Thao tác này sẽ định cấu hình XrSpatialContextEXT đã tạo bằng persistenceContexts và cho phép ứng dụng khám phá các thực thể không gian được lưu trữ trong bộ nhớ do các tay điều khiển XrSpatialPersistenceContextEXT trong persistenceContexts đại diện.

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

Tạo ảnh chụp nhanh về hoạt động khám phá

Khám phá các thực thể có UUID cụ thể

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

typedef struct XrSpatialDiscoveryPersistenceUuidFilterEXT {
    XrStructureType    type;
    const void*        next;
    uint32_t           persistedUuidCount;
    const XrUuid*      persistedUuids;
} XrSpatialDiscoveryPersistenceUuidFilterEXT;

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.
  • persistedUuidCount là một uint32_t mô tả số lượng phần tử trong mảng persistedUuids
  • persistedUuids là một mảng XrUuid .

Ứng dụng có thể sử dụng XrSpatialDiscoveryPersistenceUuidFilterEXT trong chuỗi tiếp theo của XrSpatialDiscoverySnapshotCreateInfoEXT để giới hạn phạm vi hoạt động khám phá chỉ cho những thực thể có UUID cố định nằm trong tập hợp UUID được cung cấp trong persistedUuids .

Nếu ứng dụng thêm XrSpatialDiscoveryPersistenceUuidFilterEXT vào chuỗi tiếp theo của XrSpatialDiscoverySnapshotCreateInfoEXT nhưng xrCreateSpatialDiscoverySnapshotAsyncEXT :: spatialContext không được định cấu hình bằng bất kỳ XrSpatialPersistenceContextEXT nào sử dụng XrSpatialContextPersistenceConfigEXT , thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrCreateSpatialDiscoverySnapshotAsyncEXT .

Thời gian chạy phải coi bộ lọc XrSpatialDiscoveryPersistenceUuidFilterEXT là điều kiện "AND" (VÀ) với mọi bộ lọc khác được cung cấp trong XrSpatialDiscoverySnapshotCreateInfoEXT hoặc chuỗi tiếp theo. Thời gian chạy phải coi mảng persistedUuids là điều kiện "HOẶC", tức là lọc các thực thể có bất kỳ UUID nào được cung cấp trong mảng đó.

Thời gian chạy phải bao gồm một mục trong ảnh chụp nhanh đã tạo cho mỗi UUID trong persistedUuids mà thời gian chạy có thể xác định trạng thái XrSpatialPersistenceStateEXT tại thời điểm này.

  • Nếu thời gian chạy đã tìm thấy thành công UUID trong bộ nhớ, thì –

    • Thời gian chạy phải đặt XrSpatialPersistenceStateEXT trong XrSpatialPersistenceDataEXT của thực thể này thành XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT .
    • Thời gian chạy phải bao gồm một XrSpatialEntityIdEXT hợp lệ cho thực thể này trong ảnh chụp nhanh đã tạo.
    • Thời gian chạy phải đặt XrSpatialEntityTrackingStateEXT của thực thể đó thành XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT nếu thực thể đó đang được theo dõi và có dữ liệu hợp lệ cho các thành phần của thực thể đó. Nếu không, thời gian chạy phải đặt XrSpatialEntityTrackingStateEXT thành XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT .

  • Nếu thời gian chạy xác định rằng UUID không có trong bộ nhớ (bất kể UUID đó chưa từng có trong bộ nhớ hay đã từng có nhưng sau đó không còn tồn tại), thì –

    • Thời gian chạy phải đặt XrSpatialPersistenceStateEXT trong XrSpatialPersistenceDataEXT của thực thể này thành XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT để cho ứng dụng biết rằng UUID này không còn trong bộ nhớ.
    • Thời gian chạy phải đặt XrSpatialEntityIdEXT cho thực thể này trong ảnh chụp nhanh đã tạo thành XR_NULL_SPATIAL_ENTITY_ID_EXT .
    • Thời gian chạy phải đặt XrSpatialEntityTrackingStateEXT của thực thể đó thành XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT để cho ứng dụng biết rằng thực thể này sẽ không bao giờ được theo dõi.

  • Nếu thời gian chạy không thể xác định xem UUID có trong bộ nhớ hay không, thì thời gian chạy không được đưa UUID vào ảnh chụp nhanh.

Ứng dụng cũng có thể sử dụng XrSpatialDiscoveryPersistenceUuidFilterEXT trong chuỗi tiếp theo của XrSpatialComponentDataQueryConditionEXT để truy vấn các thực thể của UUID cụ thể trong ảnh chụp nhanh hiện có. Khi được dùng với XrSpatialComponentDataQueryConditionEXT , nếu XrSpatialDiscoveryPersistenceUuidFilterEXT :: persistedUuids chứa bất kỳ XrUuid nào không có trong XrSpatialSnapshotEXT , thì thời gian chạy không được đưa mục nhập cho XrUuid đó vào kết quả truy vấn. Ngoài ra, thứ tự (trình tự) của các thực thể trong kết quả truy vấn có thể không khớp với thứ tự của UUID được cung cấp trong XrSpatialDiscoveryPersistenceUuidFilterEXT :: persistedUuids . Ứng dụng nên đưa XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT vào XrSpatialComponentDataQueryConditionEXT :: componentTypes và XrSpatialComponentPersistenceListEXT trong chuỗi tiếp theo của XrSpatialComponentDataQueryResultEXT, sau đó kiểm tra XrSpatialPersistenceDataEXT :: persistUuid của từng chỉ mục kết quả truy vấn để biết chỉ mục kết quả hiện tại tương ứng với UUID nào.

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

Khám phá tất cả thực thể được duy trì

Nếu ứng dụng sử dụng xrCreateSpatialDiscoverySnapshotAsyncEXT mà không có XrSpatialDiscoveryPersistenceUuidFilterEXT và có XrSpatialContextEXT đã được định cấu hình bằng XrSpatialPersistenceContextEXT , thì thời gian chạy phải bao gồm các thực thể đó trong ảnh chụp nhanh đã tạo được lưu trữ trong bộ nhớ do XrSpatialPersistenceContextEXT biểu thị và đáp ứng các bộ lọc được cung cấp trong XrSpatialDiscoverySnapshotCreateInfoEXT . Đối với những pháp nhân đó –

  • Thời gian chạy phải đặt XrSpatialPersistenceStateEXT trong XrSpatialPersistenceDataEXT của thực thể này thành XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT .
  • Thời gian chạy phải bao gồm một XrSpatialEntityIdEXT hợp lệ cho thực thể này trong ảnh chụp nhanh đã tạo.
  • Thời gian chạy phải đặt XrSpatialEntityTrackingStateEXT của thực thể đó thành XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT nếu thực thể đó đang được theo dõi và có dữ liệu hợp lệ cho các thành phần của thực thể đó. Nếu không, thời gian chạy phải đặt XrSpatialEntityTrackingStateEXT thành XR_SPATIAL_ENTITY_TRACKING_STATE_PAUSED_EXT .

Các loại đối tượng mới

Lệnh mới

Cấu trúc mới

Enum mới

Hằng số enum mới

  • XR_EXT_SPATIAL_PERSISTENCE_EXTENSION_NAME
  • XR_EXT_spatial_persistence_SPEC_VERSION

  • Mở rộng XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_PERSISTENCE_CONTEXT_EXT

  • Mở rộng XrResult :

    • XR_ERROR_SPATIAL_PERSISTENCE_SCOPE_UNSUPPORTED_EXT

  • Mở rộng XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT

  • Mở rộng XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_PERSISTENCE_CONTEXT_COMPLETION_EXT
    • XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT
    • XR_TYPE_SPATIAL_CONTEXT_PERSISTENCE_CONFIG_EXT
    • XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT
    • XR_TYPE_SPATIAL_PERSISTENCE_CONTEXT_CREATE_INFO_EXT

Mã ví dụ

Tạo bối cảnh lưu trữ lâu dài

// Check if the required persistence scope supported
uint32_t scopeCount;
CHK_XR(xrEnumerateSpatialPersistenceScopesEXT(instance, systemId, 0, &scopeCount, nullptr));
std::vector<XrSpatialPersistenceScopeEXT> persistenceScopes(scopeCount);
CHK_XR(xrEnumerateSpatialPersistenceScopesEXT(instance, systemId, scopeCount, &scopeCount, persistenceScopes.data()));

if (std::find(persistenceScopes.begin(), persistenceScopes.end(), XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT) == persistenceScopes.end()) {
  return;
}

XrSpatialPersistenceContextEXT persistenceContext{};

XrSpatialPersistenceContextCreateInfoEXT persistenceContextCreateInfo{XR_TYPE_SPATIAL_PERSISTENCE_CONTEXT_CREATE_INFO_EXT};
persistenceContextCreateInfo.scope = XR_SPATIAL_PERSISTENCE_SCOPE_SYSTEM_MANAGED_EXT;
XrFutureEXT createContextFuture;
CHK_XR(xrCreateSpatialPersistenceContextAsyncEXT(session, &persistenceContextCreateInfo, &createContextFuture));

waitUntilReady(createContextFuture);

XrCreateSpatialPersistenceContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_PERSISTENCE_CONTEXT_COMPLETION_EXT};
CHK_XR(xrCreateSpatialPersistenceContextCompleteEXT(session, createContextFuture, &completion));
if (completion.futureResult != XR_SUCCESS || completion.createResult != XR_SPATIAL_PERSISTENCE_CONTEXT_RESULT_SUCCESS_EXT) {
  return;
}

persistenceContext = completion.persistenceContext;

// ...
// Connect persistence context to a spatial context and discover persisted entities.
// ...

CHK_XR(xrDestroySpatialPersistenceContextEXT(persistenceContext));

Kết nối bối cảnh cố định với bối cảnh không gian

// Note: Anchor capability is just used as an example here. Persistence can be
// supported by other capabilities too. xrEnumerateSpatialCapabilityComponentTypesEXT() can
// be used to check if a certain capability supports persistence.
if (!isSpatialCapabilitySupported(instance, systemId, XR_SPATIAL_CAPABILITY_ANCHOR_EXT)) {
  return;
}

const bool supportsPersistenceComponent = isSpatialComponentSupported(instance, systemId, XR_SPATIAL_CAPABILITY_ANCHOR_EXT, XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT);

// Create a spatial spatial context
XrSpatialContextEXT spatialContext{};
{

  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_EXT,
  };

  if (supportsPersistenceComponent) {
    enabledComponents.push_back(XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT);
  }

  XrSpatialCapabilityConfigurationAnchorEXT anchorConfig{XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANCHOR_EXT};
  anchorConfig.capability = XR_SPATIAL_CAPABILITY_ANCHOR_EXT;
  anchorConfig.enabledComponentCount = enabledComponents.size();
  anchorConfig.enabledComponents = enabledComponents.data();

  std::array<XrSpatialCapabilityConfigurationBaseHeaderEXT*, 1> capabilityConfigs = {
    reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT*>(&anchorConfig),
  };

  XrSpatialContextCreateInfoEXT spatialContextCreateInfo{XR_TYPE_SPATIAL_CONTEXT_CREATE_INFO_EXT};
  spatialContextCreateInfo.capabilityConfigCount = capabilityConfigs.size();
  spatialContextCreateInfo.capabilityConfigs = capabilityConfigs.data();

  XrSpatialContextPersistenceConfigEXT persistenceConfig{XR_TYPE_SPATIAL_CONTEXT_PERSISTENCE_CONFIG_EXT};
  persistenceConfig.persistenceContextCount = 1;
  persistenceConfig.persistenceContexts = &persistenceContext;

  if (supportsPersistenceComponent) {
    spatialContextCreateInfo.next = &persistenceConfig;
  }

  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  waitUntilReady(createContextFuture);

  XrCreateSpatialContextCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_CONTEXT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialContextCompleteEXT(session, createContextFuture, &completion));
  if (completion.futureResult != XR_SUCCESS) {
    return;
  }

  spatialContext = completion.spatialContext;
}

// ...
// Discover persisted anchors.
// ...

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

Khám phá tất cả thực thể được duy trì

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialPersistenceDataEXT> persistenceData(queryResult.entityIdCountOutput);
    XrSpatialComponentPersistenceListEXT persistenceDataList{XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT};
    persistenceDataList.persistDataCount = persistenceData.size();
    persistenceDataList.persistData = persistenceData.data();
    queryResult.next = &persistenceDataList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      // persistenceData[i].persistUuid is the UUID of the persisted entity whose entity ID is entityIds[i].
      // The persistenceData array is essentially the uuids persisted in the scope that the current
      // XrSpatialPersistenceContextEXT is configured with.
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

Khám phá các thực thể có UUID cụ thể

XrFutureEXT future = XR_NULL_FUTURE_EXT;

// Load up the uuids that the app has stored on its own i.e. the uuids it is interested in.
std::vector<XrUuid> uuidsStoredByApp = loadPersistedUuids();

// We want to look for entities that have the following components.
std::vector<XrSpatialComponentTypeEXT> snapshotComponents = {
  XR_SPATIAL_COMPONENT_TYPE_PERSISTENCE_EXT,
};

auto discoverSpatialEntities = [&](XrSpatialContextEXT spatialContext, XrTime time) {
  XrSpatialDiscoveryPersistenceUuidFilterEXT persistenceFilter{XR_TYPE_SPATIAL_DISCOVERY_PERSISTENCE_UUID_FILTER_EXT};
  persistenceFilter.persistedUuidCount = uuidsStoredByApp.size();
  persistenceFilter.persistedUuids = uuidsStoredByApp.data();

  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  snapshotCreateInfo.next = &persistenceFilter;

  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(spatialContext, &snapshotCreateInfo, &future));

  waitUntilReady(future);

  XrCreateSpatialDiscoverySnapshotCompletionInfoEXT completionInfo{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_INFO_EXT};
  completionInfo.baseSpace = localSpace;
  completionInfo.time = time;
  completionInfo.future = future;

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {

    // Query for the semantic label component data
    XrSpatialComponentDataQueryConditionEXT queryCond{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = snapshotComponents.size();
    queryCond.componentTypes = snapshotComponents.data();

    XrSpatialComponentDataQueryResultEXT queryResult{XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_RESULT_EXT};
    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    std::vector<XrSpatialEntityIdEXT> entityIds(queryResult.entityIdCountOutput);
    std::vector<XrSpatialEntityTrackingStateEXT> entityStates(queryResult.entityIdCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialPersistenceDataEXT> persistenceData(queryResult.entityIdCountOutput);
    XrSpatialComponentPersistenceListEXT persistenceDataList{XR_TYPE_SPATIAL_COMPONENT_PERSISTENCE_LIST_EXT};
    persistenceDataList.persistDataCount = persistenceData.size();
    persistenceDataList.persistData = persistenceData.data();
    queryResult.next = &persistenceDataList;

    CHK_XR(xrQuerySpatialComponentDataEXT(completion.snapshot, &queryCond, &queryResult));

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (persistenceData[i].persistState == XR_SPATIAL_PERSISTENCE_STATE_LOADED_EXT) {
        // persistenceData[i].persistUuid, requested by the app, is present in the persistence scope
        // and its corresponding entity ID and state are entityIds[i] & entityStates[i] respectively.
      } else if (persistenceData[i].persistState == XR_SPATIAL_PERSISTENCE_STATE_NOT_FOUND_EXT) {
        // persistenceData[i].persistUuid, requested by the app, is NOT present in the persistence scope
        // and its corresponding entity ID (entityIds[i]) would be XR_NULL_SPATIAL_ENTITY_ID_EXT
        // and tracking state (entityStates[i]) would be XR_SPATIAL_ENTITY_TRACKING_STATE_STOPPED_EXT.
      }
    }

    CHK_XR(xrDestroySpatialSnapshotEXT(completion.snapshot));
  }
};

while (1) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState;  // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;

  // Poll for the XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT event
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  XrResult result = xrPollEvent(instance, &event);
  if (result == XR_SUCCESS) {
      switch (event.type) {
          case XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT: {
              const XrEventDataSpatialDiscoveryRecommendedEXT& eventdata =
                  *reinterpret_cast<XrEventDataSpatialDiscoveryRecommendedEXT*>(&event);
              // Discover spatial entities for the context that we received the "discovery
              // recommended" event for.
              discoverSpatialEntities(eventdata.spatialContext, time);
              break;
          }
      }
  }

  // ...
  // Finish frame loop
  // ...
}

Vấn đề

Danh sách phiên bản

  • Bản sửa đổi 1, 29/8/2024 (Nihav Jain, Google)

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