XR_ANDROID_spatial_annotation_tracking

Name String

XR_ANDROID_spatial_annotation_tracking

Loại tiện ích

Tiện ích phiên bản

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

795

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 vào phiên bản

XR_EXT_spatial_entity
và
XR_EXT_spatial_image_tracking

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

2026-01-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

Levana Chen, Google
Christopher Feil, Google
Martin Sundermeyer, Google
David Joseph Tan, Google
Jared Finder, Google
Nihav Jain, Google

Tổng quan

Tiện ích này cung cấp khả năng theo dõi chú thích cho tiện ích XR_EXT_spatial_entity để theo dõi nhiều chú thích trong cảnh. Thư viện này cho phép các ứng dụng đặt lớp phủ lên các đối tượng thực hoặc ảo do các tham chiếu thời gian chạy xác định.

Tiện ích này cung cấp một loại chú thích cơ bản là "Quad", tức là một đa giác có đúng 4 cạnh, tức là tứ giác lồi, đại diện cho một khung hình chữ nhật 2D tổng quát trong một tham chiếu thời gian chạy. Chú thích tứ giác được theo dõi được biểu thị dưới dạng một thực thể không gian có (hoặc "có") các thành phần sau:

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Các ứng dụng có thể thường sử dụng tiện ích theo dõi chú thích không gian theo các mẫu sau:

  • Trước tiên, ứng dụng sẽ tạo một đối tượng XrSpatialReferenceCacheANDROID để bắt đầu ghi các đối tượng tham chiếu thời gian chạy từ nguồn đã cho.
  • Sau đó, ứng dụng sẽ ghi lại một tham chiếu thời gian chạy của XrSpatialReferenceImageEXT và xác định chú thích mong muốn trong tham chiếu trong khoảng thời gian của bộ nhớ đệm tham chiếu.
  • Sau đó, ứng dụng sẽ tạo một giá trị nhận dạng XrSpatialContextEXT dựa trên XrSpatialReferenceImageEXT do XrSpatialCapabilityConfigurationAnnotationTrackingANDROID cung cấp .
  • Ứng dụng có thể huỷ bỏ tay cầm XrSpatialReferenceCacheANDROID để dừng ghi các tệp đối chiếu thời gian chạy nhằm giảm mức sử dụng bộ nhớ hoặc đợi sự kiện XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID để xác nhận kết quả khởi động.
  • Sau đó, ứng dụng sẽ kéo sự kiện XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID để xác nhận kết quả khởi tạo của chú thích.
  • Nếu quá trình khởi tạo thành công, ứng dụng có thể kéo sự kiện XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT để theo dõi chú thích.
  • Nếu quá trình khởi chạy không thành công, ứng dụng có thể sử dụng mã lỗi được trả về trong sự kiện để xác định lý do thất bại và hủy bỏ tay cầm XrSpatialContextEXT hiện có để bắt đầu chú giải mới.
  • Bất kể kết quả khởi chạy là gì, ứng dụng có thể giải phóng bộ đệm hình ảnh để giảm mức sử dụng bộ nhớ sau khi nhận được sự kiện.
  • Ứng dụng sẽ khám phá và truy vấn chú thích theo các mẫu truy cập thực thể không gian.
  • Ứng dụng có thể tạo thêm đối tượng XrSpatialContextEXT để theo dõi chú thích trong một đối tượng tham chiếu mới trong khoảng thời gian của XrSpatialReferenceCacheANDROID hợp lệ .
  • Ứng dụng có thể hủy bỏ các handle XrSpatialContextEXT để giảm tập hợp các chú giải có thể phát hiện và theo dõi một cách linh động trong thời gian chạy.

Hỗ trợ thời gian chạy

Một thời gian chạy phải quảng cáo khả năng hỗ trợ tính năng theo dõi chú thích bằng cách sử dụng xrEnumerateSpatialCapabilitiesEXT bằng cách liệt kê chức năng sau:

  • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

Khi thời gian chạy hỗ trợ khả năng theo dõi chú thích:

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

XrResult xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    XrSpatialCapabilityEXT                      capability,
    uint32_t                                    sourceCapacityInput,
    uint32_t*                                   sourceCountOutput,
    XrSpatialAnnotationReferenceSourceANDROID*  sources);

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

  • instance là một handle cho XrInstance .
  • systemId là XrSystemId mà nguồn tham chiếu sẽ được liệt kê.
  • capability là XrSpatialCapabilityEXT mà các nguồn tham chiếu sẽ được liệt kê.
  • sourceCapacityInput là dung lượng của mảng sources hoặc 0 để cho biết yêu cầu truy xuất dung lượng cần thiết.
  • sourceCountOutput là số lượng nguồn hoặc công suất cần thiết trong trường hợp sourceCapacityInput không đủ.
  • sources là một mảng XrSpatialAnnotationReferenceSourceANDROID . Giá trị này có thể là NULL nếu sourceCapacityInput là 0.
  • Hãy xem phần Tham số kích thước bộ nhớ đệm để biết nội dung mô tả chi tiết về cách truy xuất kích thước sources cần thiết.

Ứng dụng có thể liệt kê danh sách các nguồn tham chiếu mà một XrSystemId nhất định hỗ trợ bằng cách sử dụng xrEnumerateSpatialAnnotationReferenceSourcesANDROID .

Thời gian chạy không được liệt kê các nguồn tham chiếu có tiện ích không được bật cho instance .

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

Mã trả về

Thành công

  • XR_SUCCESS

Thất bại

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

typedef enum XrSpatialAnnotationReferenceSourceANDROID {
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationReferenceSourceANDROID;

Liệt kê XrSpatialAnnotationReferenceSourceANDROID mô tả nguồn của thông tin tham chiếu cung cấp siêu dữ liệu cho chú thích.

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

Nội dung mô tả enum

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID

Hình ảnh tham khảo là hình ảnh đầu ra chưa được cắt của một API camera Android, chẳng hạn như Hình ảnh từ ImageReader được liên kết với CameraDevice Camera2 hoặc ImageProxy từ ImageAnalysis được liên kết với CameraX. Đây thường là một trong các camera RGB hướng về phía trước.

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID

Hình ảnh tham khảo là hình ảnh chưa được cắt do Android MediaProjection API xuất ra, ví dụ: Hình ảnh từ ImageReader được liên kết với màn hình ảo MediaProjection. Nội dung này có thể bao gồm nội dung ảo và nội dung thực.

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

typedef struct XrSystemSpatialAnnotationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           referenceCacheTimespan;
    uint32_t           maxReferencePixelWidth;
    uint32_t           maxReferencePixelHeight;
    uint32_t           maxReferenceCount;
    uint32_t           maxAnnotationCount;
} XrSystemSpatialAnnotationPropertiesANDROID;

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.
  • referenceCacheTimespan cho biết khoảng thời gian tính bằng giây của một đối tượng XrSpatialReferenceCacheANDROID hợp lệ.
  • maxReferencePixelWidth cho biết chiều rộng tối đa của cạnh hình ảnh tham chiếu tính bằng pixel.
  • maxReferencePixelHeight cho biết chiều cao tối đa của cạnh hình ảnh tham chiếu tính bằng pixel.
  • maxReferenceCount cho biết số lượng tối đa hình ảnh tham chiếu sẽ được phân bổ cùng một lúc.
  • maxAnnotationCount cho biết số lượng chú thích tối đa cần theo dõi cùng một lúc.

Khi thời gian chạy hỗ trợ khả năng theo dõi chú thích, một ứng dụng có thể kiểm tra các thuộc tính hệ thống có liên quan bằng cách liên kết cấu trúc XrSystemSpatialAnnotationPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties .

Nếu XrSpatialReferenceImageEXT :: width từ XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference vượt quá maxReferencePixelWidth , thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE khi gọi xrCreateSpatialContextAsyncEXT .

Nếu XrSpatialReferenceImageEXT :: height từ XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference vượt quá maxReferencePixelHeight , thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE khi gọi xrCreateSpatialContextAsyncEXT .

Nếu XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: time nằm ngoài khoảng thời gian của XrSpatialReferenceCacheANDROID :: cache , thì thời gian chạy phải trả về XR_ERROR_TIME_INVALID khi gọi xrCreateSpatialContextAsyncEXT . Ứng dụng có thể tạo lại đối tượng XrSpatialContextEXT bằng một thông tin tham chiếu mới trong khoảng thời gian của XrSpatialReferenceCacheANDROID .

Nếu số lượng hình ảnh tham chiếu được phân bổ vượt quá maxReferenceCount , thì thời gian chạy phải trả về XR_ERROR_LIMIT_REACHED và cho biết lỗi khởi tạo thông qua XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult . Ứng dụng có thể hủy bỏ tay cầm XrSpatialContextEXT và thử lại sau khi quá trình khởi tạo đang chờ xử lý hoàn tất.

Nếu số lượng chú thích đang hoạt động vượt quá maxAnnotationCount , thì thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE khi gọi xrCreateSpatialContextAsyncEXT .

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

Bộ nhớ đệm tham chiếu thời gian chạy

XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)

Xử lý XrSpatialReferenceCacheANDROID đại diện cho bộ nhớ đệm của các lượt tham chiếu thời gian chạy được ghi lại từ một nguồn nhất định.

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

XrResult xrCreateSpatialReferenceCacheAsyncANDROID(
    XrSession                                   session,
    const XrSpatialReferenceCacheCreateInfoANDROID* createInfo,
    XrFutureEXT*                                future);

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

  • session là một XrSession mà bộ nhớ đệm tham chiếu sẽ hoạt động.
  • createInfo là một con trỏ đến XrSpatialReferenceCacheCreateInfoANDROID dùng để chỉ định các tham số bộ nhớ đệm tham chiếu.
  • future là con trỏ đến giá trị nhận dạng đầu ra của XrFutureEXT .

Ứng dụng có thể tạo một đối tượng XrSpatialReferenceCacheANDROID bằng cách gọi xrCreateSpatialReferenceCacheAsyncANDROID . Thời gian chạy có thể mất một chút thời gian để khởi động các dịch vụ theo dõi. Sau đó, ứng dụng có thể gọi xrCreateSpatialReferenceCacheCompleteANDROID nhiều lần để kiểm tra xem thao tác không đồng bộ này đã hoàn tất hay chưa.

Thời gian chạy phải trả về XR_ERROR_SPATIAL_CAPABILITY_UNSUPPORTED_EXT nếu XrSpatialReferenceCacheCreateInfoANDROID :: capability không được xrEnumerateSpatialCapabilitiesEXT liệt kê .

Thời gian chạy phải trả về XR_ERROR_FEATURE_UNSUPPORTED nếu XrSpatialReferenceCacheCreateInfoANDROID :: source không được xrEnumerateSpatialAnnotationReferenceSourcesANDROID liệt kê cho khả năng đã cho.

Ứng dụng chỉ có thể tạo một giá trị nhận dạng cho mỗi nguồn đối với một chức năng nhất định. Nếu không, thời gian chạy phải trả về XR_ERROR_LIMIT_REACHED .

Sau đó, ứng dụng có thể ghi lại các tham chiếu thời gian chạy trong khoảng thời gian của đối tượng XrSpatialReferenceCacheANDROID để định cấu hình đối tượng XrSpatialContextEXT mới.

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

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • XR_ERROR_FEATURE_UNSUPPORTED
  • 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_CAPABILITY_UNSUPPORTED_EXT
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSpatialReferenceCacheCreateInfoANDROID {
    XrStructureType                              type;
    const void*                                  next;
    XrSpatialCapabilityEXT                       capability;
    XrSpatialAnnotationReferenceSourceANDROID    source;
} XrSpatialReferenceCacheCreateInfoANDROID;

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.
  • capability là một XrSpatialCapabilityEXT mô tả khả năng mà bộ nhớ đệm tham chiếu được tạo ra.
  • source là một XrSpatialAnnotationReferenceSourceANDROID mô tả nguồn của bộ nhớ đệm tham chiếu.

Cấu trúc XrSpatialReferenceCacheCreateInfoANDROID mô tả thông tin để tạo một đối tượng XrSpatialReferenceCacheANDROID.

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

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

XrResult xrCreateSpatialReferenceCacheCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrCreateSpatialReferenceCacheCompletionANDROID* completion);

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

Ứng dụng có thể gọi xrCreateSpatialReferenceCacheCompleteANDROID để chờ hoàn tất thao tác không đồng bộ do xrCreateSpatialReferenceCacheAsyncANDROID 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)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • XR_ERROR_FEATURE_UNSUPPORTED
  • 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 XrCreateSpatialReferenceCacheCompletionANDROID được xác định như sau:

typedef struct XrCreateSpatialReferenceCacheCompletionANDROID {
    XrStructureType                   type;
    void*                             next;
    XrResult                          futureResult;
    XrSpatialReferenceCacheANDROID    referenceCache;
} XrCreateSpatialReferenceCacheCompletionANDROID;

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.
  • futureResult là XrResult của thao tác tạo bộ nhớ đệm tham chiếu.
  • referenceCache là giá trị nhận dạng XrSpatialReferenceCacheANDROID nếu thao tác thành công.

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

Giá trị futureResult:

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED

Nếu futureResult là mã thành công, thì thời gian chạy phải trả về một giá trị nhận dạng referenceCache hợp lệ. Nếu referenceCache hợp lệ, thì nó chỉ hợp lệ trong vòng đời của xrCreateSpatialReferenceCacheAsyncANDROID :: session hoặc cho đến khi ứng dụng huỷ tay cầm bằng xrDestroySpatialReferenceCacheANDROID, tuỳ theo điều kiện nào đến trước.

Khi referenceCache hợp lệ, nó sẽ ghi lại các bộ nhớ đệm trong XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan .

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

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

XrResult xrDestroySpatialReferenceCacheANDROID(
    XrSpatialReferenceCacheANDROID              cacheHandle);

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

Ứng dụng có thể gọi hàm xrDestroySpatialReferenceCacheANDROID để giải phóng đối tượng cacheHandle và các tài nguyên cơ bản khi hoàn tất quá trình tạo ngữ cảnh không gian.

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

Độ an toàn cho luồng

  • Quyền truy cập vào cacheHandle và mọi đối tượng con phải được đồng bộ hoá bên ngoài

Mã trả về

Thành công

  • XR_SUCCESS

Thất bại

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Cấu hình

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

typedef struct XrSpatialCapabilityConfigurationAnnotationTrackingANDROID {
    XrStructureType                     type;
    const void*                         next;
    XrSpatialCapabilityEXT              capability;
    uint32_t                            enabledComponentCount;
    const XrSpatialComponentTypeEXT*    enabledComponents;
    XrSpatialReferenceCacheANDROID      cache;
    XrTime                              time;
    XrSpatialReferenceImageEXT          reference;
} XrSpatialCapabilityConfigurationAnnotationTrackingANDROID;

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_ANNOTATION_TRACKING_ANDROID .
  • enabledComponentCount là một uint32_t mô tả số lượng phần tử trong mảng enabledComponents.
  • enabledComponents là con trỏ đến một mảng XrSpatialComponentTypeEXT .
  • cache là một XrSpatialReferenceCacheANDROID được tạo trước đó để ghi lại các thông tin tham chiếu trong thời gian chạy cho cấu hình reference.
  • time là XrTime mà reference được thu thập.
  • reference là một XrSpatialReferenceImageEXT có các chú thích được xâu chuỗi vào con trỏ tiếp theo của nó.

Các ứng dụng có thể bật chức năng XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID không gian bằng cách thêm một con trỏ vào cấu trúc XrSpatialCapabilityConfigurationAnnotationTrackingANDROID 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_ANNOTATION_TRACKING_ANDROID .

Thời gian chạy phải trả về XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT nếu reference không chứa chú giải nào.

Thời gian chạy phải trả về XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT nếu thành phần chú giải được liệt kê trong enabledComponents nhưng không có chú giải tương ứng nào được liên kết với reference .

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE nếu cache không thuộc sở hữu của cùng một XrSession truyền đến xrCreateSpatialContextAsyncEXT .

Thời gian chạy phải trả về XR_ERROR_TIME_INVALID nếu time nằm ngoài khoảng thời gian của cache .

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

Sự kiện theo dõi chú thích

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

typedef struct XrEventDataSpatialAnnotationTrackingANDROID {
    XrStructureType        type;
    const void*            next;
    XrSpatialContextEXT    spatialContext;
    uint32_t               annotationIndex;
    XrResult               initializationResult;
} XrEventDataSpatialAnnotationTrackingANDROID;

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.
  • spatialContext là XrSpatialContextEXT đã kích hoạt tính năng theo dõi chú thích.
  • annotationIndex ánh xạ đến chỉ mục từ mảng chú thích được liên kết với XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference .
  • initializationResult cho biết kết quả khởi tạo của chú thích. Nếu không phải là XR_SUCCESS , ứng dụng có thể hủy bỏ và tạo lại handle XrSpatialContextEXT để khởi động lại chú giải, hoặc tiếp tục dùng spatialContext để theo dõi các chú giải khác.

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

Thời gian chạy phải điền sẵn XrEventDataSpatialAnnotationTrackingANDROID cho từng chú thích để cho biết quá trình khởi tạo đã hoàn tất. Bất kể kết quả khởi chạy là gì, ứng dụng có thể giải phóng bộ đệm hình ảnh để giảm mức sử dụng bộ nhớ sau khi nhận được sự kiện.

Thời gian chạy phải điền sẵn initializationResult bằng XR_SUCCESS nếu chú thích được khởi chạy thành công. Sau đó, ứng dụng có thể kéo sự kiện XR_TYPE_EVENT_DATA_SPATIAL_DISCOVERY_RECOMMENDED_EXT để theo dõi chú thích.

Nếu không, thời gian chạy phải điền sẵn initializationResult bằng một mã lỗi thích hợp để cho biết lý do thất bại. Ứng dụng có thể hủy bỏ handle XrSpatialContextEXT để bắt đầu chú giải mới hoặc tiếp tục dùng spatialContext để theo dõi các chú giải khác.

Chú thích bốn phần

Thời gian chạy phải quảng cáo khả năng hỗ trợ chú giải tứ giác bằng cách sử dụng xrEnumerateSpatialCapabilityComponentTypesEXT bằng cách liệt kê loại thành phần sau:

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Quad Reference

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

typedef struct XrSpatialAnnotationQuadReferenceANDROID {
    XrStructureType                          type;
    const void*                              next;
    uint32_t                                 quadCount;
    const XrSpatialAnnotationQuadANDROID*    quads;
} XrSpatialAnnotationQuadReferenceANDROID;

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.
  • quadCount là một uint32_t mô tả số lượng phần tử trong mảng quads.
  • quads là con trỏ đến một mảng XrSpatialAnnotationQuadANDROID .

Khi thời gian chạy hỗ trợ chú thích tứ giác, ứng dụng có thể định cấu hình chú thích bằng cách liên kết cấu trúc XrSpatialAnnotationQuadReferenceANDROID với XrSpatialReferenceImageEXT :: next và đặt tham chiếu trong XrSpatialCapabilityConfigurationAnnotationTrackingANDROID :: reference khi tạo đối tượng XrSpatialContextEXT.

Thời gian chạy phải trả về XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT từ xrCreateSpatialContextAsyncEXT nếu quadCount là 0.

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

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

typedef struct XrSpatialAnnotationQuadANDROID {
    XrSpatialAnnotationQuadAlignmentANDROID    alignment;
    XrVector2f                                 upperLeft;
    XrVector2f                                 upperRight;
    XrVector2f                                 lowerRight;
    XrVector2f                                 lowerLeft;
} XrSpatialAnnotationQuadANDROID;

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

  • alignment là XrSpatialAnnotationQuadAlignmentANDROID của tứ giác.
  • upperLeft là một XrVector2f mô tả toạ độ của góc trên cùng bên trái của tứ giác liên quan đến điểm gốc.
  • upperRight là một XrVector2f mô tả toạ độ của góc trên bên phải của tứ giác liên quan đến nguồn gốc.
  • lowerRight là một XrVector2f mô tả toạ độ của góc dưới cùng bên phải của tứ giác liên quan đến gốc.
  • lowerLeft là một XrVector2f mô tả toạ độ của góc dưới cùng bên trái của tứ giác liên quan đến nguồn gốc.

Hình tứ giác trong không gian 2D là một tứ giác lồi có thứ tự theo chiều kim đồng hồ. Giá trị của 4 góc có liên quan đến gốc (0, 0) mà tứ giác được liên kết.

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

typedef enum XrSpatialAnnotationQuadAlignmentANDROID {
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID = 0,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID = 1,
    XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSpatialAnnotationQuadAlignmentANDROID;

Liệt kê XrSpatialAnnotationQuadAlignmentANDROID mô tả sự liên kết của chú thích tứ giác.

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

Nội dung mô tả enum

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SCREEN_ANDROID

Tứ giác chú thích song song với mặt phẳng màn hình, trong khi chế độ xoay trên mặt phẳng vẫn bị khoá theo trọng lực của thế giới. Đầu ra xuất hiện dưới dạng một khung hình chữ nhật thẳng đứng thông thường.

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID

Tứ giác chú thích được neo trực tiếp vào đối tượng, khớp với hướng căn chỉnh được xác định trong hình ảnh tham khảo. Đầu ra là một tứ giác lồi, điều chỉnh hình dạng để phù hợp với góc nhìn của đối tượng.

Thành phần Quad

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

typedef struct XrSpatialAnnotationQuadDataANDROID {
    uint32_t                          annotationIndex;
    XrSpaceLocationData               origin;
    XrSpatialAnnotationQuadANDROID    quad;
} XrSpatialAnnotationQuadDataANDROID;

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

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

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

typedef struct XrSpatialComponentAnnotationQuadListANDROID {
    XrStructureType                        type;
    void*                                  next;
    uint32_t                               quadCount;
    XrSpatialAnnotationQuadDataANDROID*    quads;
} XrSpatialComponentAnnotationQuadListANDROID;

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

Ứng dụng có thể truy vấn thành phần chú thích tứ giác của các thực thể không gian trong XrSpatialSnapshotEXT bằng cách thêm XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID vào XrSpatialComponentDataQueryConditionEXT :: componentTypes và thêm XrSpatialComponentAnnotationQuadListANDROID vào chuỗi con trỏ tiếp theo của XrSpatialComponentDataQueryResultEXT .

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

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

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

Mã ví dụ

Kiểm tra khả năng hỗ trợ thời gian chạy

Đoạn mã ví dụ sau đây minh hoạ cách kiểm tra xem thời gian chạy có hỗ trợ tính năng theo dõi chú thích hay không.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrEnumerateSpatialCapabilitiesEXT xrEnumerateSpatialCapabilitiesEXT;
PFN_xrEnumerateSpatialAnnotationReferenceSourcesANDROID xrEnumerateSpatialAnnotationReferenceSourcesANDROID;
PFN_xrEnumerateSpatialReferenceImageFormatsEXT xrEnumerateSpatialReferenceImageFormatsEXT;
PFN_xrEnumerateSpatialCapabilityComponentTypesEXT xrEnumerateSpatialCapabilityComponentTypesEXT;

// Check spatial annotation tracking capability
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_ANNOTATION_TRACKING_ANDROID) ==
    capabilities.end()) {
  // System does not support spatial annotation tracking.
  return;
}

// Inspect system properties for annotation tracking variables
XrSystemSpatialAnnotationPropertiesANDROID annotationSystemProperties{
    XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{.type = XR_TYPE_SYSTEM_PROPERTIES,
                                    .next = &annotationSystemProperties,
                                    .systemId = systemId};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (annotationSystemProperties.maxAnnotationCount == 0) {
  // System does not support any active annotations.
  return;
}

// Enumerate supported reference sources
uint32_t sourceCountOutput = 0;
XrSpatialAnnotationReferenceSourceANDROID desiredSource =
    XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_CAMERA_ANDROID;
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    0, &sourceCountOutput, nullptr));
std::vector<XrSpatialAnnotationReferenceSourceANDROID> sources(sourceCountOutput);
CHK_XR(xrEnumerateSpatialAnnotationReferenceSourcesANDROID(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    sourceCountOutput, &sourceCountOutput, sources.data()));
if (std::find(sources.begin(), sources.end(), desiredSource) == sources.end()) {
  // The desired source is not supported.
  return;
}

// Enumerate supported reference image formats, provided by XR_EXT_spatial_image_tracking.
uint32_t formatCountOutput = 0;
XrSpatialReferenceImageFormatEXT desiredFormat =
    XR_SPATIAL_REFERENCE_IMAGE_FORMAT_YUV_420_888_EXT; // Or XR_SPATIAL_REFERENCE_IMAGE_FORMAT_RGBA_8888_EXT for screenshot.
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID, 0,
    &formatCountOutput, nullptr));
std::vector<XrSpatialReferenceImageFormatEXT> formats(formatCountOutput);
CHK_XR(xrEnumerateSpatialReferenceImageFormatsEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    formats.size(), &formatCountOutput, formats.data()));
if (std::find(formats.begin(), formats.end(), desiredFormat) == formats.end()) {
  // The desired format is not supported
  return;
}

// Enumerate supported components for annotation tracking capability.
XrSpatialCapabilityComponentTypesEXT capabilityComponentTypes{
    XR_TYPE_SPATIAL_CAPABILITY_COMPONENT_TYPES_EXT};
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));
std::vector<XrSpatialComponentTypeEXT>
    annotationTypes(capabilityComponentTypes.componentTypeCountOutput);
capabilityComponentTypes.componentTypeCapacityInput = annotationTypes.size();
capabilityComponentTypes.componentTypes = annotationTypes.data();
CHK_XR(xrEnumerateSpatialCapabilityComponentTypesEXT(
    instance, systemId, XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
    &capabilityComponentTypes));

// Check supported annotation components.
XrSpatialComponentTypeEXT desiredComponent =
    XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID;
const auto supportedComponent = [&annotationTypes](
                                    XrSpatialComponentTypeEXT component) {
  return std::find(annotationTypes.begin(), annotationTypes.end(), component) !=
         annotationTypes.end();
};
if (!supportedComponent(desiredComponent)) {
  // The desired annotation is not supported.
  return;
}

Định cấu hình chú thích tứ giác

Đoạn mã ví dụ sau đây minh hoạ cách định cấu hình chú thích tứ giác.

XrInstance instance;  // previously initialized
XrSystemId systemId;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL

PFN_xrCreateSpatialReferenceCacheAsyncANDROID xrCreateSpatialReferenceCacheAsyncANDROID;
PFN_xrCreateSpatialReferenceCacheCompleteANDROID xrCreateSpatialReferenceCacheCompleteANDROID;
PFN_xrDestroySpatialReferenceCacheANDROID xrDestroySpatialReferenceCacheANDROID;
PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialReferenceImageFormatEXT desiredFormat;
XrSpatialAnnotationReferenceSourceANDROID desiredSource;
XrSpatialComponentTypeEXT desiredComponent;

// Create and start reference cache to prepare for capturing reference images.
XrSpatialReferenceCacheANDROID referenceCache;
XrSpatialReferenceCacheCreateInfoANDROID cacheCreateInfo{
  .type = XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID,
  .next = nullptr,
  .capability = XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID,
  .source = desiredSource,
};
XrFutureEXT cacheFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSpatialReferenceCacheAsyncANDROID(session, &cacheCreateInfo, &cacheFuture));

waitUntilReady(cacheFuture);

XrCreateSpatialReferenceCacheCompletionANDROID cacheCompletion{
    XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID};
CHK_XR(xrCreateSpatialReferenceCacheCompleteANDROID(session, cacheFuture,
                                                     &cacheCompletion));
if (cacheCompletion.futureResult != XR_SUCCESS) {
  // Error, reference cache creation failed
  return;
}

referenceCache = cacheCompletion.referenceCache;

// Create the reference image with quad annotations

//  YUV 4:2:0 Planar:
// ----------------------
// |     Y      |Cb |Cr |
// ----------------------
XrSpatialReferenceImagePlaneEXT cameraImagePlanes[3];
// for each plane (0=Y, 1=U(cb), 2=V(Cr)) return by Image#getPlanes().
for (int i = 0; i < 3; ++i) {
  cameraImagePlanes[i].buffer; // read from Plane#getBuffer().
  cameraImagePlanes[i].bufferSize; // set each buffer size. Y = width * height (bytes); U = Y / 4 (bytes); V = Y / 4 (bytes).
  cameraImagePlanes[i].rowStride; // read from Plane#getRowStride().
  cameraImagePlanes[i].pixelStride; // read from Plane#getPixelStride().
}
XrSpatialReferenceImageEXT referenceImage{
      XR_TYPE_SPATIAL_REFERENCE_IMAGE_EXT};
referenceImage.width = 640;
referenceImage.height = 480;
referenceImage.format = desiredFormat;
referenceImage.planeCount = 3;
referenceImage.planes = cameraImagePlanes;

XrSpatialAnnotationQuadANDROID
    quad; // quad coordinates within the reference image.
quad.alignment = XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID;
// Set unnormalized pixel coordinates of 4 corners.
quad.upperLeft = {0.0, 0.0};
quad.upperRight = {0.0, 100.0};
quad.lowerRight = {100.0, 100.0};
quad.lowerLeft = {0.0, 100.0};

XrSpatialAnnotationQuadReferenceANDROID quadReference{
    XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID};
quadReference.quads = &quad;
quadReference.quadCount = 1;
referenceImage.next = &quadReference;

// Create the spatial context with annotation configuration.
XrSpatialContextEXT spatialContext{};
{
  const std::array<XrSpatialComponentTypeEXT, 1> enabledComponents = {
      desiredComponent,
  };

  // Configure annotation tracking
  XrSpatialCapabilityConfigurationAnnotationTrackingANDROID annotationConfig{
      XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID};
  annotationConfig.capability =
      XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID;
  annotationConfig.enabledComponentCount = enabledComponents.size();
  annotationConfig.enabledComponents = enabledComponents.data();
  annotationConfig.cache = referenceCache;
  annotationConfig.time; // The time when this reference image is captured.
  annotationConfig.reference = referenceImage;

  std::vector<XrSpatialCapabilityConfigurationBaseHeaderEXT *>
      capabilityConfigs;
  capabilityConfigs.push_back(
      reinterpret_cast<XrSpatialCapabilityConfigurationBaseHeaderEXT *>(
          &annotationConfig));

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

  XrFutureEXT createContextFuture = XR_NULL_FUTURE_EXT;
  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) {
    // Error, spatial context creation failed
    return;
  }

  spatialContext = completion.spatialContext;
  CHK_XR(xrDestroySpatialReferenceCacheANDROID(referenceCache));
}

Khám phá chú thích đang hoạt động

Đoạn mã ví dụ sau đây minh hoạ cách khám phá và truy vấn chú thích.

XrInstance instance;  // previously initialized
XrSession session;    // previously initialized
XrSpace localSpace;   // previously initialized, e.g. from
                      // XR_REFERENCE_SPACE_TYPE_LOCAL
XrSpatialContextEXT spatialContext; // previously created

PFN_xrCreateSpatialDiscoverySnapshotAsyncEXT xrCreateSpatialDiscoverySnapshotAsyncEXT;
PFN_xrCreateSpatialDiscoverySnapshotCompleteEXT xrCreateSpatialDiscoverySnapshotCompleteEXT;
PFN_xrQuerySpatialComponentDataEXT xrQuerySpatialComponentDataEXT;
PFN_xrDestroySpatialSnapshotEXT xrDestroySpatialSnapshotEXT;
PFN_xrPollEvent xrPollEvent;
PFN_xrDestroySpatialContextEXT xrDestroySpatialContextEXT;
void (*waitUntilReady)(XrFutureEXT);

XrSpatialComponentTypeEXT desiredComponent; // e.g. XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

auto discoverAnnotations = [&](XrSpatialContextEXT spatialContext, XrTime time,
                               XrSpace baseSpace) {
  std::array<XrSpatialComponentTypeEXT, 1> snapshotComponents{desiredComponent};
  XrSpatialDiscoverySnapshotCreateInfoEXT snapshotCreateInfo{
      XR_TYPE_SPATIAL_DISCOVERY_SNAPSHOT_CREATE_INFO_EXT};
  snapshotCreateInfo.componentTypeCount = snapshotComponents.size();
  snapshotCreateInfo.componentTypes = snapshotComponents.data();
  XrFutureEXT discoveryFuture = XR_NULL_FUTURE_EXT;
  CHK_XR(xrCreateSpatialDiscoverySnapshotAsyncEXT(
      spatialContext, &snapshotCreateInfo, &discoveryFuture));

  waitUntilReady(discoveryFuture);

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

  XrCreateSpatialDiscoverySnapshotCompletionEXT completion{
      XR_TYPE_CREATE_SPATIAL_DISCOVERY_SNAPSHOT_COMPLETION_EXT};
  CHK_XR(xrCreateSpatialDiscoverySnapshotCompleteEXT(
      spatialContext, &completionInfo, &completion));
  if (completion.futureResult == XR_SUCCESS) {
    // Query for desired annotation data, e.g. quad.
    XrSpatialComponentTypeEXT componentsToQuery[] = {
        XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID};
    XrSpatialComponentDataQueryConditionEXT queryCond{
        XR_TYPE_SPATIAL_COMPONENT_DATA_QUERY_CONDITION_EXT};
    queryCond.componentTypeCount = 1;
    queryCond.componentTypes = componentsToQuery;
    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.entityStateCountOutput);
    queryResult.entityIdCapacityInput = entityIds.size();
    queryResult.entityIds = entityIds.data();
    queryResult.entityStateCapacityInput = entityStates.size();
    queryResult.entityStates = entityStates.data();

    std::vector<XrSpatialAnnotationQuadDataANDROID> quads(
        queryResult.entityIdCountOutput);
    XrSpatialComponentAnnotationQuadListANDROID quadList{
        XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID};
    quadList.quadCount = quads.size();
    quadList.quads = quads.data();
    queryResult.next = &quadList;

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

    for (int32_t i = 0; i < queryResult.entityIdCountOutput; ++i) {
      if (entityStates[i] == XR_SPATIAL_ENTITY_TRACKING_STATE_TRACKING_EXT) {
        const XrSpatialAnnotationQuadDataANDROID &currentQuad = quads[i];
        // Rendering quad in the view.
      }
    }

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

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

  XrSpace space;           // Application's play space.
  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_ANNOTATION_TRACKING_ANDROID: {
      const XrEventDataSpatialAnnotationTrackingANDROID &eventdata =
          *reinterpret_cast<XrEventDataSpatialAnnotationTrackingANDROID *>(
              &event);
      if (eventdata.initializationResult != XR_SUCCESS) {
        // handle initialization failure.
        // e.g. CHK_XR(xrDestroySpatialContextEXT(spatialContext));
      }
      break;
    }
    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, space);
      break;
    }
    }
  }

  // Finish frame loop
}

CHK_XR(xrDestroySpatialContextEXT(spatialContext));

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_ANDROID_SPATIAL_ANNOTATION_TRACKING_EXTENSION_NAME
  • XR_ANDROID_spatial_annotation_tracking_SPEC_VERSION

  • Mở rộng XrObjectType :

    • XR_OBJECT_TYPE_SPATIAL_REFERENCE_CACHE_ANDROID

  • Mở rộng XrSpatialCapabilityEXT :

    • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

  • Mở rộng XrSpatialComponentTypeEXT :

    • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

  • Mở rộng XrStructureType :

    • XR_TYPE_CREATE_SPATIAL_REFERENCE_CACHE_COMPLETION_ANDROID
    • XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID
    • XR_TYPE_SPATIAL_ANNOTATION_QUAD_REFERENCE_ANDROID
    • XR_TYPE_SPATIAL_CAPABILITY_CONFIGURATION_ANNOTATION_TRACKING_ANDROID
    • XR_TYPE_SPATIAL_COMPONENT_ANNOTATION_QUAD_LIST_ANDROID
    • XR_TYPE_SPATIAL_REFERENCE_CACHE_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_SPATIAL_ANNOTATION_PROPERTIES_ANDROID

Vấn đề

Nhật ký phiên bản

  • Bản sửa đổi 1, ngày 17 tháng 9 năm 2025 (Levana Chen)

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