XR_ANDROID_spatial_annotation_tracking

Name String

XR_ANDROID_spatial_annotation_tracking

Loại tiện ích

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

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

795

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
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ó tuyên bố nào về tài sản 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 chức 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. Tính năng 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 được xác định bằng các tệp đối chiếu trong thời gian chạy.

Phần mở rộng này cung cấp một loại chú thích cơ bản là "Quad" (Tứ giác), 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 hộp giới hạn 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ó các thành phần sau:

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Các ứng dụng thường có thể 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 handle của XrSpatialReferenceCacheANDROID để bắt đầu ghi lại các tệp đối chiếu trong thời gian chạy từ nguồn đã cho.
  • Sau đó, ứng dụng sẽ thu thập thông tin tham chiếu thời gian chạy của XrSpatialReferenceImageEXT và xác định chú thích mong muốn trong thông tin 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 tay điều khiển XrSpatialContextEXT dựa trên XrSpatialReferenceImageEXT do XrSpatialCapabilityConfigurationAnnotationTrackingANDROID cung cấp.
  • Ứng dụng có thể huỷ tay điều khiển XrSpatialReferenceCacheANDROID để dừng ghi lại 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 chạy.
  • Sau đó, ứng dụng sẽ lấy sự kiện XR_TYPE_EVENT_DATA_SPATIAL_ANNOTATION_TRACKING_ANDROID để xác nhận kết quả khởi chạy của chú thích.
  • Nếu quá trình khởi động thành công, thì ứng dụng có thể lấy 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 không thành công và huỷ tay điều khiển XrSpatialContextEXT hiện có để bắt đầu một chú thích mới.
  • Bất kể kết quả khởi chạy là gì, ứng dụng có thể giải phóng vùng đệm hình ảnh để giảm mức sử dụng bộ nhớ sau khi nhận được sự kiện.
  • Ứng dụng 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 tay điều khiển XrSpatialContextEXT để theo dõi chú thích trong một tệp đối chiếu mới trong khoảng thời gian của XrSpatialReferenceCacheANDROID hợp lệ.
  • Ứng dụng có thể huỷ các tay điều khiển XrSpatialContextEXT để giảm tập hợp chú thích 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

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 xrEnumerateSpatialCapabilitiesEXT bằng cách liệt kê tính năng sau:

  • XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID

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

Hàm xrEnumerateSpatialAnnotationReferenceSourcesANDROID được định nghĩa 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 tay điều khiển cho XrInstance .
  • systemId là XrSystemId có các 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 dung lượng 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ố 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 sources cần thiết.

Ứng dụng có thể liệt kê danh sách các nguồn tham chiếu được 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 ẩn)

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_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;

Bảng liệt kê XrSpatialAnnotationReferenceSourceANDROID mô tả nguồn của tệp đối chiếu cung cấp siêu dữ liệu cho một 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à kết quả hình ảnh chưa được cắt từ API camera Android, ví dụ: 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 những camera RGB hướng về phía trước.

XR_SPATIAL_ANNOTATION_REFERENCE_SOURCE_MEDIA_PROJECTION_ANDROID

Hình ảnh tham khảo là kết quả hình ảnh chưa được cắt từ API MediaProjection của Android, 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 cả nội dung ảo và nội dung thực.

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

Khi thời gian chạy hỗ trợ chức năng theo dõi chú thích, ứ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 tay điều khiển XrSpatialContextEXT bằng một tệp đối chiếu mới trong khoảng thời gian của XrSpatialReferenceCacheANDROID .

Nếu số lượng hình ảnh tham khảo đượ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 động thông qua XrEventDataSpatialAnnotationTrackingANDROID :: initializationResult . Ứng dụng có thể huỷ tay điều khiển XrSpatialContextEXT rồi thử lại sau khi quá trình khởi chạy đ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 ẩn)

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

XR_DEFINE_HANDLE(XrSpatialReferenceCacheANDROID)

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

Hàm xrCreateSpatialReferenceCacheAsyncANDROID được định nghĩa 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à trong đó bộ nhớ đệm tham chiếu sẽ hoạt động.
  • createInfo là con trỏ đến XrSpatialReferenceCacheCreateInfoANDROID dùng để chỉ định các tham số bộ nhớ đệm tham chiếu.
  • future là con trỏ đến tay điều khiển đầu ra của XrFutureEXT .

Ứng dụng có thể tạo một tay điều khiển 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 chức năng đã cho.

Ứng dụng chỉ có thể tạo một tay điều khiển cho mỗi nguồn cho 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ể thu thập các tệp đối chiếu trong thời gian chạy trong khoảng thời gian của tay điều khiển XrSpatialReferenceCacheANDROID để định cấu hình tay điều khiển XrSpatialContextEXT mới.

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

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

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.
  • capability là một XrSpatialCapabilityEXT mô tả chức năng mà bộ nhớ đệm tham chiếu được tạo.
  • 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 tay điều khiển XrSpatialReferenceCacheANDROID.

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

Hàm xrCreateSpatialReferenceCacheCompleteANDROID được định nghĩa 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 ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

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

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

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.
  • futureResult là XrResult của thao tác tạo bộ nhớ đệm tham chiếu.
  • referenceCache là tên người 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

Không thành công

  • 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 tay điều khiển referenceCache hợp lệ. Nếu referenceCache hợp lệ, thì giá trị này chỉ duy trì trong thời gian hoạt động của xrCreateSpatialReferenceCacheAsyncANDROID :: session hoặc cho đến khi ứng dụng huỷ tay điều khiển bằng xrDestroySpatialReferenceCacheANDROID, tuỳ theo điều kiện nào xảy ra trước.

Khi referenceCache hợp lệ, thuộc tính này sẽ ghi lại bộ nhớ đệm trong XrSystemSpatialAnnotationPropertiesANDROID :: referenceCacheTimespan .

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

Hàm xrDestroySpatialReferenceCacheANDROID được định nghĩa 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 tay điều khiển cacheHandle và các tài nguyên cơ bản khi hoàn tất việc tạo bối cảnh không gian.

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

Độ an toàn cho chuỗi

  • Quyền truy cập vào cacheHandle 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

Cấu hình

Cấu trúc XrSpatialCapabilityConfigurationAnnotationTrackingANDROID được định nghĩa 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ả 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_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 tệp đối chiếu thời gian chạy cho cấu hình reference.
  • time là XrTime mà reference được ghi lại.
  • reference là một XrSpatialReferenceImageEXT có chú thích được liên kết với con trỏ tiếp theo.

Ứng dụng có thể bật chức năng không gian XR_SPATIAL_CAPABILITY_ANNOTATION_TRACKING_ANDROID 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ú thích.

Thời gian chạy phải trả về XR_ERROR_SPATIAL_CAPABILITY_CONFIGURATION_INVALID_EXT nếu thành phần chú thích được liệt kê trong enabledComponents nhưng không có chú thích 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 ẩn)

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

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

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

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

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

Thời gian chạy phải điền XrEventDataSpatialAnnotationTrackingANDROID cho mỗi chú thích để cho biết quá trình khởi chạy đã 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 vùng đệ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 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ể lấy 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 mã lỗi thích hợp vào initializationResult để cho biết lý do không thành công. Ứng dụng có thể huỷ tay điều khiển XrSpatialContextEXT để bắt đầu một chú thích mới hoặc tiếp tục sử dụng spatialContext để theo dõi các chú thích khác.

Chú thích bốn chiều

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

  • XR_SPATIAL_COMPONENT_TYPE_ANNOTATION_QUAD_ANDROID

Tệp đối chiếu bốn hướng

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

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

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.
  • 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 tay điều khiển 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 ẩn)

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

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

Nội dung mô tả về 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 bên trái của hình tứ giác liên quan đến gốc toạ độ.
  • upperRight là một XrVector2f mô tả toạ độ của góc trên bên phải của hình tứ giác liên quan đến gốc toạ độ.
  • lowerRight là một XrVector2f mô tả toạ độ của góc dưới bên phải của tứ giác liên quan đến gốc toạ độ.
  • lowerLeft là một XrVector2f mô tả toạ độ của góc dưới bên trái của hình tứ giác liên quan đến gốc toạ độ.

Tứ giác trong không gian 2D là tứ giác lồi theo thứ tự 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 ẩn)

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

Phép liệt kê XrSpatialAnnotationQuadAlignmentANDROID mô tả cách căn chỉnh 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 trong mặt phẳng vẫn bị khoá theo trọng lực của thế giới. Kết quả đầu ra xuất hiện dưới dạng một hộp giới hạn thẳng đứng thông thường.

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_OBJECT_ANDROID

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

XR_SPATIAL_ANNOTATION_QUAD_ALIGNMENT_SURFACE_ANDROID

Chú thích hình tứ giác nằm trên cùng một mặt phẳng với bề mặt của đối tượng bên dưới, giả sử mục tiêu được theo dõi là một đối tượng hoặc bề mặt phẳng. Kết quả sẽ khớp hoàn toàn với hình dạng vật lý của vật thể, điều chỉnh góc nhìn để nằm phẳng trên bề mặt cụ thể đó.

Thành phần Quad

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

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

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

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

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

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

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.
  • 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 ẩn)

Mã ví dụ

Kiểm tra khả năng hỗ trợ trong 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

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 đề

Danh sách 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.