XR_ANDROID_geospatial_anchor

Name String

XR_ANDROID_geospatial_anchor

Loại tiện ích

Tiện ích phiên bản

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

798

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_ANDROID_geospatial

XR_EXT_future

XR_EXT_spatial_entity

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ó 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

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

Tổng quan

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

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

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

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

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

  • typeXrStructureType của cấu trúc này.
  • nextNULL 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.
  • maxSurfaceAnchorCount là một uint32_t cho biết số lượng tối đa các neo trên bề mặt mà có thể được tạo.

Một ứng dụng có thể kiểm tra các chức năng của 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 :: supportsGeospatialXR_TRUE , thì maxSurfaceAnchorCount cho biết số lượng tối đa các neo trên bề mặt 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 bằng 0.

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

Theo dõi mặt phẳng cho các điểm neo

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

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

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

  • typeXrStructureType của cấu trúc này.
  • nextNULL hoặc con 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 cố định 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 điểm neo cố định 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ế của điểm neo trên 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)

Neo không gian địa lý

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

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

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

  • spatialContextXrSpatialContextEXT để tạo điểm neo. Bạn phải định cấu hình ngữ cả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à một con trỏ đến XrGeospatialAnchorCreateInfoANDROID chứa các tham số tạo neo.
  • anchorEntityId là một con trỏ đến XrSpatialEntityIdEXT, trong đó mã nhận dạng thực thể của điểm 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)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • 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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

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

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

  • typeXrStructureType của cấu trúc này.
  • nextNULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • geospatialTrackerXrGeospatialTrackerANDROID dùng để tạo neo.
  • geospatialPose là một 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)

Neo trên bề mặt

Neo bề mặt là các 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à.

Liệt kê XrSurfaceAnchorTypeANDROID được xác định là:

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;

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

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 điểm neo được đặt tương đối so với mặt đất.

XR_SURFACE_ANCHOR_TYPE_ROOFTOP_ANDROID

Loại điểm neo được đặt tương đối so với mái nhà hoặc mặt đất (nếu không có toà nhà).

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

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

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

  • spatialContextXrSpatialContextEXT để tạo điểm neo.
  • createInfo là một con trỏ đến XrSurfaceAnchorCreateInfoANDROID chứa các tham số tạo neo.
  • future là một con trỏ trỏ đến XrFutureEXT sẽ 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 một 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 thành công 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)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • 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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Cấu trúc XrSurfaceAnchorCreateInfoANDROID được xác định 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ả thành viên

  • typeXrStructureType của cấu trúc này.
  • nextNULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • geospatialTrackerXrGeospatialTrackerANDROID cần sử dụng.
  • surfaceAnchorTypeXrSurfaceAnchorTypeANDROID cho neo.
  • eastUpSouthOrientation là hướng so với một 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 độ, trong khoảng từ -180 đến +180.
  • altitudeRelativeToSurface là độ cao tính bằng mét so với bề mặt do surfaceAnchorType chỉ định .

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

Hàm xrCreateSurfaceAnchorCompleteANDROID được xác định 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)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • 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ả thành viên

  • typeXrStructureType của cấu trúc này.
  • nextNULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • futureResultXrResult của thao tác tạo. Nếu futureResultXR_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.
  • anchorEntityIdXrSpatialEntityIdEXT của điểm 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

Thất bại

  • 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)

Ví dụ

Tạo điểm 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, ngày 30/10/2025 (Ben King)

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