XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

Loại tiện ích

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

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

798

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_ANDROID_geospatial
và
XR_EXT_future
và
XR_EXT_spatial_entity
và
XR_EXT_spatial_anchor

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

2025-10-30

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

John Ullman, Google
Ben King, Google
Nihav Jain, Google
Jared Finder, Google

Tổng quan

Tiện ích này cung cấp Điểm neo không gian địa lý và Điểm neo bề mặt dựa trên tiện ích Không gian địa lý cơ bản. Điểm neo không gian địa lý là các điểm neo được đặt trong không gian tương ứng với Trái Đất ở một vĩ độ, kinh độ và độ cao nhất định. Điểm neo bề mặt là điểm neo tương ứng với Trái Đất, được đặt ở một vĩ độ, kinh độ và cao độ nhất định so với một bề mặt mà Dịch vụ định vị trực quan biết. Khi độ chính xác của vị trí của thời gian chạy so với Trái đất được cải thiện, tư thế của Điểm neo sẽ điều chỉnh cho phù hợp.

Khả năng của hệ thống đối với neo không gian địa lý

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

typedef struct XrSystemGeospatialAnchorPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    uint32_t           maxSurfaceAnchorCount;
} XrSystemGeospatialAnchorPropertiesANDROID;

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.
  • maxSurfaceAnchorCount là một uint32_t cho biết số lượng neo bề mặt tối đa có thể tạo.

Ứng dụng có thể kiểm tra các chức năng neo không gian địa lý của hệ thống bằng cách liên kết cấu trúc XrSystemGeospatialAnchorPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties .

Nếu XrSystemGeospatialPropertiesANDROID :: supportsGeospatial là XR_TRUE , thì maxSurfaceAnchorCount cho biết số lượng neo bề mặt tối đa mà thời gian chạy hỗ trợ. Trong trường hợp này, giới hạn phải lớn hơn 0.

Nếu XrSystemGeospatialPropertiesANDROID :: supportsGeospatial không phải là XR_TRUE , thì maxSurfaceAnchorCount phải là 0.

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

Theo dõi mặt phẳng cho neo

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

typedef struct XrGeospatialTrackerAnchorTrackingInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrBool32           shouldTrackPlanes;
} XrGeospatialTrackerAnchorTrackingInfoANDROID;

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.
  • shouldTrackPlanes là một XrBool32 cho biết liệu trình theo dõi không gian địa lý có theo dõi các mặt phẳng để cải thiện vị trí của các neo bị khoá trên bề mặt hay không.

Bạn có thể bật tính năng theo dõi mặt phẳng để cải thiện vị trí của các neo được khoá trên bề mặt.

Nếu muốn bật tính năng theo dõi mặt phẳng để cải thiện tư thế neo bề mặt, ứng dụng có thể liên kết cấu trúc XrGeospatialTrackerAnchorTrackingInfoANDROID với XrGeospatialTrackerCreateInfoANDROID khi gọi xrCreateGeospatialTrackerANDROID .

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

Điểm neo không gian địa lý

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

XrResult xrCreateGeospatialAnchorANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrGeospatialAnchorCreateInfoANDROID*  createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId);

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

  • spatialContext là XrSpatialContextEXT để tạo neo. Bối cảnh phải được định cấu hình cho XR_SPATIAL_CAPABILITY_ANCHOR_EXT, nếu không, thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE .
  • createInfo là con trỏ đến XrGeospatialAnchorCreateInfoANDROID chứa các tham số tạo điểm neo.
  • anchorEntityId là con trỏ đến XrSpatialEntityIdEXT, trong đó mã nhận dạng thực thể neo được trả về.

Nếu XrGeospatialTrackerANDROID được chỉ định trong XrGeospatialAnchorCreateInfoANDROID :: geospatialTracker không ở trạng thái XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, thì thời gian chạy phải trả về XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

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_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrGeospatialAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrGeospatialPoseANDROID       geospatialPose;
} XrGeospatialAnchorCreateInfoANDROID;

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.
  • geospatialTracker là XrGeospatialTrackerANDROID dùng để tạo điểm neo.
  • geospatialPose là con trỏ đến XrGeospatialPoseANDROID xác định vị trí và hướng của neo.

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

Điểm neo trên bề mặt

Điểm neo bề mặt là điểm neo được đặt tương ứng với một bề mặt, chẳng hạn như địa hình hoặc mái nhà.

Kiểu liệt kê XrSurfaceAnchorTypeANDROID được định nghĩa như sau:

typedef enum XrSurfaceAnchorTypeANDROID {
    XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID = 1,
    XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID = 2,
    XR_SURFACE_ANCHOR_TYPE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSurfaceAnchorTypeANDROID;

Kiểu liệt kê XrSurfaceAnchorTypeANDROID chỉ định loại bề mặt mà một neo liên quan đến.

Các giá trị liệt kê có các giá trị sau:

Nội dung mô tả enum

XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID

Loại neo được đặt tương ứng với mặt đất.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Loại điểm neo được đặt tương ứng với tầng thượng hoặc mặt đất nơi không có toà nhà.

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

XrResult xrCreateSurfaceAnchorAsyncANDROID(
    XrSpatialContextEXT                         spatialContext,
    const XrSurfaceAnchorCreateInfoANDROID*     createInfo,
    XrFutureEXT*                                future);

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

  • spatialContext là XrSpatialContextEXT để tạo neo.
  • createInfo là con trỏ đến XrSurfaceAnchorCreateInfoANDROID chứa các tham số tạo điểm neo.
  • future là một con trỏ trỏ đến XrFutureEXT sẽ lưu giữ kết quả của hoạt động không đồng bộ.

Hàm xrCreateSurfaceAnchorAsyncANDROID bắt đầu một thao tác không đồng bộ để tạo neo bề mặt. Không giống như các neo không gian địa lý tiêu chuẩn, thời gian chạy có thể tìm nạp dữ liệu địa hình để xác định độ cao chính xác. Thời gian chạy phải trả về XR_ERROR_LIMIT_REACHED nếu ứng dụng cố gắng tạo nhiều hơn XrSystemGeospatialAnchorPropertiesANDROID :: maxSurfaceAnchorCount neo bề mặt cùng một lúc. Nếu XrGeospatialTrackerANDROID được chỉ định trong XrSurfaceAnchorCreateInfoANDROID :: geospatialTracker không ở trạng thái XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID, thì thời gian chạy phải trả về XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Thao tác này có thể không đồng bộ với kết quả XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID nếu không có dữ liệu bề mặt cho vị trí đã cho. Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE nếu XR_SPATIAL_CAPABILITY_ANCHOR_EXT chưa được định cấu hình cho spatialContext .

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_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrSurfaceAnchorCreateInfoANDROID {
    XrStructureType               type;
    const void*                   next;
    XrGeospatialTrackerANDROID    geospatialTracker;
    XrSurfaceAnchorTypeANDROID    surfaceAnchorType;
    XrQuaternionf                 eastUpSouthOrientation;
    double                        latitude;
    double                        longitude;
    double                        altitudeRelativeToSurface;
} XrSurfaceAnchorCreateInfoANDROID;

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.
  • geospatialTracker là XrGeospatialTrackerANDROID cần sử dụng.
  • surfaceAnchorType là XrSurfaceAnchorTypeANDROID cho điểm neo.
  • eastUpSouthOrientation là hướng liên quan đến hệ toạ độ trong đó +X=Đông, +Y=Lên và +Z=Nam.
  • latitude là vĩ độ tính bằng độ, trong khoảng từ -89,9 đến +89,9.
  • longitude là kinh độ tính bằng độ, từ -180 đến +180.
  • altitudeRelativeToSurface là cao độ tính bằng mét so với bề mặt được chỉ định bởi surfaceAnchorType .

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

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

XrResult xrCreateSurfaceAnchorCompleteANDROID(
    XrSpatialContextEXT                         spatialContext,
    XrFutureEXT                                 future,
    XrSurfaceAnchorCreateCompletionANDROID*     completion);

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

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 XrSurfaceAnchorCreateCompletionANDROID lưu giữ kết quả của quá trình tạo neo bề mặt không đồng bộ.

typedef struct XrSurfaceAnchorCreateCompletionANDROID {
    XrStructureType         type;
    void*                   next;
    XrResult                futureResult;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSurfaceAnchorCreateCompletionANDROID;

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.
  • futureResult là XrResult của thao tác tạo. Nếu futureResult là XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID , thì một cấu trúc trong chuỗi next có thể cung cấp thêm thông tin về lỗi.
  • anchorEntityId là XrSpatialEntityIdEXT của neo đã tạo hoặc XR_NULL_SPATIAL_ENTITY_ID_EXT nếu futureResult không phải là XR_SUCCESS .

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_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

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

Ví dụ

Tạo neo địa hình

PFN_xrCreateSpatialContextAsyncEXT xrCreateSpatialContextAsyncEXT;
PFN_xrCreateSpatialContextCompleteEXT xrCreateSpatialContextCompleteEXT;
PFN_xrCreateSurfaceAnchorAsyncANDROID xrCreateSurfaceAnchorAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCreateSurfaceAnchorCompleteANDROID xrCreateSurfaceAnchorCompleteANDROID;
XrInstance instance;
XrSession session;
XrGeospatialTrackerANDROID geospatialTracker;

// Create a spatial context
XrSpatialContextEXT spatialContext{};
{
  std::vector<XrSpatialComponentTypeEXT> enabledComponents = {
    XR_SPATIAL_COMPONENT_TYPE_ANCHOR_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();
  XrFutureEXT createContextFuture;
  CHK_XR(xrCreateSpatialContextAsyncEXT(session, &spatialContextCreateInfo, &createContextFuture));

  // ... wait until future is ready ...

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

  spatialContext = contextCompletion.spatialContext;
}

XrSurfaceAnchorCreateInfoANDROID anchorCreateInfo{
    XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID};
anchorCreateInfo.surfaceAnchorType = XR_SURFACE_ANCHOR_TYPE_TERRAIN_ANDROID;
anchorCreateInfo.eastUpSouthOrientation = {0, 0, 0, 1};
anchorCreateInfo.latitude = 37.7749;
anchorCreateInfo.longitude = -122.4194;
anchorCreateInfo.altitudeRelativeToSurface = 0;
anchorCreateInfo.geospatialTracker = geospatialTracker;
XrFutureEXT anchorFuture = XR_NULL_FUTURE_EXT;
CHK_XR(xrCreateSurfaceAnchorAsyncANDROID(spatialContext, &anchorCreateInfo, &anchorFuture));

XrFuturePollInfoEXT anchorPollInfo{XR_TYPE_FUTURE_POLL_INFO_EXT};
XrFuturePollResultEXT anchorPollResult{XR_TYPE_FUTURE_POLL_RESULT_EXT};
anchorPollInfo.future = anchorFuture;
anchorPollResult.state = XR_FUTURE_STATE_PENDING_EXT;
while (anchorPollResult.state == XR_FUTURE_STATE_PENDING_EXT) {
  // Do in render loop/state loop.
  CHK_XR(xrPollFutureEXT(instance, &anchorPollInfo, &anchorPollResult));
}

XrSurfaceAnchorCreateCompletionANDROID anchorCompletion{
    XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID};
CHK_XR(xrCreateSurfaceAnchorCompleteANDROID(spatialContext, anchorFuture, &anchorCompletion));
if (anchorCompletion.futureResult == XR_SUCCESS) {
  // Use completion.anchorEntityId.
  XrSpatialEntityIdEXT anchorId = anchorCompletion.anchorEntityId;

  // Query in UpdateSnapshot.
}

Lệnh mới

Cấu trúc mới

Enum mới

Hằng số enum mới

  • XR_ANDROID_GEOSPATIAL_ANCHOR_EXTENSION_NAME
  • XR_ANDROID_geospatial_anchor_SPEC_VERSION
  • Mở rộng XrResult :

    • XR_ERROR_SURFACE_ANCHOR_LOCATION_UNSUPPORTED_ANDROID
  • Mở rộng XrStructureType :

    • XR_TYPE_GEOSPATIAL_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_ANCHOR_TRACKING_INFO_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_COMPLETION_ANDROID
    • XR_TYPE_SURFACE_ANCHOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_ANCHOR_PROPERTIES_ANDROID

Vấn đề

Nhật ký phiên bản

  • Bản sửa đổi 1, 30/10/2025 (Ben King)

    • Bản nháp ban đầu.