XR_ANDROID_geospatial

名称字符串

XR_ANDROID_geospatial

扩展程序类型

实例扩展程序

已注册的扩展程序编号

790

修订版本

1

批准状态

未批准

扩展程序和版本依赖项

XR_EXT_future

上次修改日期

2025-12-18

IP 状态

没有已知的 IP 权利主张。

创作贡献者

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

概览

此扩展程序为 Google 的 Geospatial API 提供地理空间跟踪功能，该 API 可提供精确的地理位置和方向，并允许应用根据地球放置内容。为此，它会结合使用动作追踪、GPS 和其他传感器，以及 Google 的视觉定位系统 (VPS)。VPS 会将设备摄像头拍摄的图像与街景图像进行比较，以确定精确位置和方向。Geospatial API 通常可提供亚米级的位置精确度（比 GPS 高出几个数量级）和亚度级的方向精确度。

如需成功使用此扩展程序中的 API（检查扩展程序支持情况除外），应用必须已通过某种机制（例如 XR_ANDROID_google_cloud_auth）成功设置身份验证凭证。如需详细了解设置和错误结果，请参阅身份验证扩展程序的文档。

权限

Android 应用必须在清单中列出 android.permission.ACCESS_FINE_LOCATION 权限，才能使用此扩展程序。android.permission.ACCESS_FINE_LOCATION 权限被视为危险权限。应用必须在运行时请求该权限才能使用以下函数：

（保护级别：危险）

检查系统功能

XrSystemGeospatialPropertiesANDROID 结构定义如下：

typedef struct XrSystemGeospatialPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGeospatial;
} XrSystemGeospatialPropertiesANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。核心 OpenXR 或此扩展程序中未定义任何此类结构。
  • supportsGeospatial 是一个 XrBool32，用于指示当前系统是否支持地理空间功能。

应用可以在调用 xrGetSystemProperties 时，将 XrSystemGeospatialPropertiesANDROID 结构链接到 XrSystemProperties，以检查系统是否支持地理空间功能。

如果运行时针对 supportsGeospatial 返回 XR_FALSE，则系统不支持地理空间功能，因此必须从 xrCreateGeospatialTrackerANDROID 返回 XR_ERROR_FEATURE_UNSUPPORTED。当 supportsGeospatial 为 XR_FALSE 时，应用应避免使用地理空间功能。

有效用法（隐式）

创建地理空间跟踪器句柄

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

xrCreateGeospatialTrackerANDROID 函数的定义如下：

XrResult xrCreateGeospatialTrackerANDROID(
    XrSession                                   session,
    const XrGeospatialTrackerCreateInfoANDROID* createInfo,
    XrGeospatialTrackerANDROID*                 geospatialTrackerOutput);

参数说明

应用可以通过调用 xrCreateGeospatialTrackerANDROID 来创建 XrGeospatialTrackerANDROID 句柄。返回的 XrGeospatialTrackerANDROID 句柄可以在后续 API 调用中使用。如果应用未获得所需权限，运行时必须返回 XR_ERROR_PERMISSION_INSUFFICIENT。对于特定的 XrSession，一次只能存在一个 XrGeospatialTrackerANDROID。应用必须确保在再次调用此函数之前，所有之前的 XrGeospatialTrackerANDROID 对象都已被销毁，否则运行时必须返回 XR_ERROR_LIMIT_REACHED。如果跟踪器创建成功，它最初会进入 XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID 状态，应用必须等到状态更改为 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 后才能使用跟踪器。请参阅 XrEventDataGeospatialTrackerStateChangedANDROID。如果应用将不处于 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 状态的 XrGeospatialTrackerANDROID 传递给需要它的函数，则运行时必须返回 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID。

XrGeospatialTrackerANDROID 句柄最终必须通过 xrDestroyGeospatialTrackerANDROID 函数释放。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

XrGeospatialTrackerCreateInfoANDROID 结构定义如下：

typedef struct XrGeospatialTrackerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrGeospatialTrackerCreateInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。

有效用法（隐式）

xrDestroyGeospatialTrackerANDROID 函数的定义如下：

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

参数说明

应用可以使用 xrDestroyGeospatialTrackerANDROID 函数来释放地理空间跟踪器和底层资源。

有效用法（隐式）

线程安全

  • 对 geospatialTracker 及其任何子句柄的访问都必须在外部进行同步

返回代码

成功

  • XR_SUCCESS

失败

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

地理空间跟踪器状态

XrGeospatialTrackerStateANDROID 枚举定义如下：

typedef enum XrGeospatialTrackerStateANDROID {
    XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID = 0,
    XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID = 1,
    XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID = 2,
    XR_GEOSPATIAL_TRACKER_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrGeospatialTrackerStateANDROID;

XrGeospatialTrackerStateANDROID 枚举用于标识地理空间跟踪器的不同状态。

枚举值具有以下值：

枚举说明

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

地理空间跟踪器未运行。

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Geospatial 跟踪器正在运行且可用。

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Geospatial Tracker 初始化失败，将无法使用。

XrEventDataGeospatialTrackerStateChangedANDROID 结构定义如下：

typedef struct XrEventDataGeospatialTrackerStateChangedANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrGeospatialTrackerANDROID         geospatialTracker;
    XrGeospatialTrackerStateANDROID    state;
    XrResult                           initializationResult;
    XrTime                             time;
} XrEventDataGeospatialTrackerStateChangedANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • geospatialTracker 是状态已发生变化的 XrGeospatialTrackerANDROID。
  • state 是新的 XrGeospatialTrackerStateANDROID。
  • 如果 state 为 XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID，则 initializationResult 为错误结果，否则为 XR_SUCCESS。
  • time 是发生状态更改的 XrTime。

当地理空间跟踪器状态发生变化时，系统会发送 XrEventDataGeospatialTrackerStateChangedANDROID 结构。如果应用具有有效的 XrGeospatialTrackerANDROID，则应轮询此事件。为跟踪器收到的第一个事件将具有 state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID。在运行时确定的时间段后，状态必须更改为 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 或 XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID。此转换将花费任意时间。如果 state 更改为 XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID，则它必须是此跟踪器收到的最后一个事件，并且 initializationResult 字段将包含错误代码。可能需要几秒钟的时间才会发生错误。在这种情况下，应用应销毁跟踪器。如果 state 更改为 XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID，则之前创建的所有地理空间锚点必须永久停止跟踪，并且应由应用销毁。状态可能会在 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID 和 XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID 之间来回切换任意多次。

有效用法（隐式）

地理空间姿态

XrGeospatialPoseANDROID 结构的定义如下：

typedef struct XrGeospatialPoseANDROID {
    XrQuaternionf    eastUpSouthOrientation;
    double           latitude;
    double           longitude;
    double           altitude;
} XrGeospatialPoseANDROID;

成员说明

  • eastUpSouthOrientation 是一个 XrQuaternionf，定义了相对于坐标系（其中 +X=东、+Y=上、+Z=南）的朝向。
  • latitude 是以度为单位的纬度，介于 -90 到 +90 之间。
  • longitude 是经度（以度为单位），介于 -180 到 +180 之间。
  • altitude 是 WGS84 椭球体上方的海拔高度（以米为单位）。

XrGeospatialPoseANDROID 结构表示使用 WGS84 椭球体相对于地球的位置和朝向。

有效用法（隐式）

  • 必须先启用 XR_ANDROID_geospatial 扩展程序，然后才能使用 XrGeospatialPoseANDROID
  • latitude 必须是有效的 double 值
  • longitude 必须是有效的 double 值
  • altitude 必须是有效的 double 值

XrGeospatialPoseFlagBitsANDROID 枚举定义如下：

// Flag bits for XrGeospatialPoseFlagsANDROID
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID = 0x00000001;
static const XrGeospatialPoseFlagsANDROID XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID = 0x00000002;

XrGeospatialPoseFlagBitsANDROID 枚举指定了地理空间姿态的标志。

标志位具有以下含义：

标志说明

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID - 表示方向成员包含有效数据
  • XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID - 表示位置成员包含有效数据

XrGeospatialPoseFlagsANDROID 类型是 XrGeospatialPoseFlagBitsANDROID 的位掩码。

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

将 XrPosef 转换为地理空间姿态

xrLocateGeospatialPoseFromPoseANDROID 函数的定义如下：

XrResult xrLocateGeospatialPoseFromPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseFromPoseLocateInfoANDROID* locateInfo,
    XrGeospatialPoseResultANDROID*              geospatialPoseResult);

参数说明

xrLocateGeospatialPoseFromPoseANDROID 函数会将 XrGeospatialPoseFromPoseLocateInfoANDROID :: space 中的姿态转换为地理空间姿态。如果 geospatialTracker 的状态不是 XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID，则运行时必须返回 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID。如果函数返回 XR_SUCCESS，则 geospatialPoseResult 的 XrGeospatialPoseResultANDROID :: poseFlags 字段会确定哪些输出字段有效。如果 XrGeospatialPoseResultANDROID :: poseFlags 中未设置 XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID，则应用不得读取 XrGeospatialPoseResultANDROID 中的 XrGeospatialPoseANDROID :: latitude、XrGeospatialPoseANDROID :: longitude、XrGeospatialPoseANDROID :: altitude、XrGeospatialPoseResultANDROID :: horizontalAccuracy 或 XrGeospatialPoseResultANDROID :: verticalAccuracy 字段。如果未在 XrGeospatialPoseResultANDROID :: poseFlags 中设置 XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID，则应用不得读取 XrGeospatialPoseANDROID :: eastUpSouthOrientation 或 XrGeospatialPoseResultANDROID :: orientationYawAccuracy。如果未设置 XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID，则必须同样不设置 XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID。

如果精确度低于预期，则可能表示设备未使用 VPS 定位。应用可以指示用户将设备对准标志和建筑物，以提高定位准确性。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrGeospatialPoseFromPoseLocateInfoANDROID 结构的定义如下：

typedef struct XrGeospatialPoseFromPoseLocateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
    XrPosef            pose;
} XrGeospatialPoseFromPoseLocateInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • space 是定义 pose 的 XrSpace。
  • time 是要评估 pose 的 XrTime。
  • pose 是 space 中要转换为地理空间姿态的 XrPosef。

有效用法（隐式）

XrGeospatialPoseResultANDROID 结构的定义如下：

typedef struct XrGeospatialPoseResultANDROID {
    XrStructureType                 type;
    void*                           next;
    XrGeospatialPoseFlagsANDROID    poseFlags;
    XrGeospatialPoseANDROID         geospatialPose;
    double                          horizontalAccuracy;
    double                          verticalAccuracy;
    double                          orientationYawAccuracy;
} XrGeospatialPoseResultANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • poseFlags 是 XrGeospatialPoseFlagsANDROID 的位掩码，用于指示姿态组件的有效性。
  • geospatialPose 是生成的 XrGeospatialPoseANDROID。
  • horizontalAccuracy 是地理空间姿态位置的预估水平精确度，定义为在给定纬度和经度周围 68% 置信度圆圈的半径（以米为单位）。
  • verticalAccuracy 是地理空间姿态位置的估计垂直精确度，定义为给定海拔周围 68% 置信度水平的距离（以米为单位）。换句话说，真实海拔高度有 68% 的概率在 [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ] 范围内。
  • orientationYawAccuracy 是地理空间姿态朝向的估算偏航角准确度，定义为给定朝向周围 68% 置信度水平的半径（以度为单位）。

有效用法（隐式）

将地理空间姿态转换为 XrPosef

xrLocateGeospatialPoseANDROID 函数的定义如下：

XrResult xrLocateGeospatialPoseANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker,
    const XrGeospatialPoseLocateInfoANDROID*    locateInfo,
    XrSpaceLocation*                            location);

参数说明

xrLocateGeospatialPoseANDROID 函数会将地理空间姿态转换为 XrSpaceLocation。如果 XrGeospatialTrackerANDROID 未运行，运行时必须返回 XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID。如果函数返回 XR_SUCCESS，则 location 的 XrSpaceLocation :: locationFlags 字段会确定哪些输出字段有效。

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • 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_POSE_INVALID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

XrGeospatialPoseLocateInfoANDROID 结构的定义如下：

typedef struct XrGeospatialPoseLocateInfoANDROID {
    XrStructureType            type;
    const void*                next;
    XrSpace                    space;
    XrTime                     time;
    XrGeospatialPoseANDROID    geospatialPose;
} XrGeospatialPoseLocateInfoANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • space 是将用于表示结果姿态的 XrSpace。
  • time 是姿势所在的 XrTime。
  • geospatialPose 是要转换的 XrGeospatialPoseANDROID。

有效用法（隐式）

VPS 可用性

XrVPSAvailabilityANDROID 枚举定义如下：

typedef enum XrVPSAvailabilityANDROID {
    XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID = 1,
    XR_VPS_AVAILABILITY_AVAILABLE_ANDROID = 2,
    XR_VPSAVAILABILITY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrVPSAvailabilityANDROID;

XrVPSAvailabilityANDROID 枚举表示 VPS 可用性。

枚举值具有以下值：

枚举说明

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

指定位置附近没有可用的 VPS。

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

VPS 在指定位置附近可用。

xrCheckVpsAvailabilityAsyncANDROID 函数定义如下：

XrResult xrCheckVpsAvailabilityAsyncANDROID(
    XrSession                                   session,
    double                                      latitude,
    double                                      longitude,
    XrFutureEXT*                                future);

参数说明

  • session 是用于检查的 XrSession。
  • latitude 是指纬度（以度为单位）。
  • longitude 是指经度（以度为单位）。
  • future 是指向 XrFutureEXT 的指针，用于保存异步操作的结果。

视觉定位服务 (VPS) 可用性表示是否可以使用 VPS 来提高给定位置的地理空间准确性。

xrCheckVpsAvailabilityAsyncANDROID 函数会开始异步检查指定位置的 VPS 可用性。应用无需 XrGeospatialTrackerANDROID 即可调用此函数，并且可以使用此操作的结果来决定是否创建一个。如果应用未获得所需权限，运行时必须返回 XR_ERROR_PERMISSION_INSUFFICIENT。

有效用法（隐式）

  • 必须先启用 XR_ANDROID_geospatial 扩展程序，然后才能调用 xrCheckVpsAvailabilityAsyncANDROID
  • session 必须是有效的 XrSession 句柄
  • latitude 必须是有效的 double 值
  • longitude 必须是有效的 double 值
  • future 必须是指向 XrFutureEXT 值的指针

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

xrCheckVpsAvailabilityCompleteANDROID 函数定义如下：

XrResult xrCheckVpsAvailabilityCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrVPSAvailabilityCheckCompletionANDROID*    completion);

参数说明

有效用法（隐式）

返回代码

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_FUTURE_INVALID_EXT
  • XR_ERROR_FUTURE_PENDING_EXT
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

XrVPSAvailabilityCheckCompletionANDROID 结构定义如下：

typedef struct XrVPSAvailabilityCheckCompletionANDROID {
    XrStructureType             type;
    void*                       next;
    XrResult                    futureResult;
    XrVPSAvailabilityANDROID    availability;
} XrVPSAvailabilityCheckCompletionANDROID;

成员说明

  • type 是此结构的 XrStructureType。
  • next 是 NULL 或指向结构链中下一个结构的指针。
  • futureResult 是检查操作的 XrResult。如果 futureResult 为 XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID，则 next 链中的结构可能会提供有关失败的更多信息。
  • availability 是生成的 XrVPSAvailabilityANDROID。除非 futureResult 为 XR_SUCCESS，否则应用不得读取此字段。

未来返回代码

futureResult 个值：

成功

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

失败

  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

有效用法（隐式）

示例

设置地理空间跟踪器

PFN_xrCheckVpsAvailabilityAsyncANDROID xrCheckVpsAvailabilityAsyncANDROID;
PFN_xrPollFutureEXT xrPollFutureEXT;
PFN_xrCheckVpsAvailabilityCompleteANDROID xrCheckVpsAvailabilityCompleteANDROID;
PFN_xrCreateGeospatialTrackerANDROID xrCreateGeospatialTrackerANDROID;
XrInstance instance = XR_NULL_HANDLE;
XrSystemId systemId = XR_NULL_SYSTEM_ID;
XrSession session = XR_NULL_HANDLE;
double lat = 37.422, lng = -122.084;

// Check for support.
XrSystemGeospatialPropertiesANDROID geospatialSystemProperties{
    XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{XR_TYPE_SYSTEM_PROPERTIES,
                                    &geospatialSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!geospatialSystemProperties.supportsGeospatial) {
  return;
}

// Check VPS Availability.
XrFutureEXT future = XR_NULL_FUTURE_EXT;
CHK_XR(xrCheckVpsAvailabilityAsyncANDROID(session, lat, lng, &future));

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

XrVPSAvailabilityCheckCompletionANDROID vpsCompletion{
    XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID};
CHK_XR(xrCheckVpsAvailabilityCompleteANDROID(session, future, &vpsCompletion));
if (vpsCompletion.futureResult == XR_SUCCESS) {
  if (vpsCompletion.availability == XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID) {
    // Visual Positioning Service is not available. Accuracy of positions and
    // orientations from Geospatial APIs are expected to be lower at this location.
  } else {
    // Visual Positioning Service is available. Higher accuracy of position and
    // orientation is achievable at this location.
  }
}

// Create Geospatial Tracker.
XrGeospatialTrackerCreateInfoANDROID createInfo{
    XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID};
XrGeospatialTrackerANDROID geospatialTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateGeospatialTrackerANDROID(session, &createInfo, &geospatialTracker));

// In application main event loop:
while (true) {
  XrEventDataBuffer event = {XR_TYPE_EVENT_DATA_BUFFER};
  if (xrPollEvent(instance, &event) != XR_SUCCESS) {
    continue;
  }
  switch (event.type) {
    case XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID:
      const XrEventDataGeospatialTrackerStateChangedANDROID& eventData =
          *reinterpret_cast<XrEventDataGeospatialTrackerStateChangedANDROID*>(&event);
      switch (eventData.state) {
        case XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID:
          // Destroy existing anchors, if any.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID:
          // Start adding content.
          break;
        case XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID:
          // Handle eventData.initializationResult error result.
          break;
      }
  }
}

调用 Geospatial Pose API

PFN_xrLocateGeospatialPoseFromPoseANDROID xrLocateGeospatialPoseFromPoseANDROID;
PFN_xrLocateGeospatialPoseANDROID xrLocateGeospatialPoseANDROID;

XrGeospatialTrackerANDROID geospatialTracker;

// Get pose from view space.
XrSpace viewSpace;
XrPosef identityPose = {{0,0,0,1},{0,0,0}};
XrGeospatialPoseFromPoseLocateInfoANDROID poseGetInfo{
    XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID};
XrGeospatialPoseResultANDROID poseResult{
    XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID};
poseGetInfo.space = viewSpace;
poseGetInfo.pose = identityPose;
poseGetInfo.time = 0;  // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseFromPoseANDROID(geospatialTracker, &poseGetInfo, &poseResult));
if ((poseResult.poseFlags & XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID) &&
    (poseResult.poseFlags & XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID)) {
  // poseResult.geospatialPose is valid.
}

// Convert Geospatial pose to an XrSpaceLocation.
XrGeospatialPoseLocateInfoANDROID poseLocateInfo{
    XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID};
XrSpaceLocation location{XR_TYPE_SPACE_LOCATION};
poseLocateInfo.space = viewSpace;
poseLocateInfo.geospatialPose = poseResult.geospatialPose;
poseLocateInfo.time = 0; // Next frame timestamp.
CHK_XR(xrLocateGeospatialPoseANDROID(geospatialTracker, &poseLocateInfo, &location));
if ((location.locationFlags & XR_SPACE_LOCATION_ORIENTATION_VALID_BIT) &&
    (location.locationFlags & XR_SPACE_LOCATION_POSITION_VALID_BIT)) {
  // location.pose is valid.
}

新对象类型

新增命令

新结构

新枚举

新位掩码

新枚举常量

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • 扩展 XrObjectType：

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • 扩展 XrResult：

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • 扩展 XrStructureType：

    • XR_TYPE_EVENT_DATA_GEOSPATIAL_TRACKER_STATE_CHANGED_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_FROM_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_LOCATE_INFO_ANDROID
    • XR_TYPE_GEOSPATIAL_POSE_RESULT_ANDROID
    • XR_TYPE_GEOSPATIAL_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_GEOSPATIAL_PROPERTIES_ANDROID
    • XR_TYPE_VPS_AVAILABILITY_CHECK_COMPLETION_ANDROID

问题

版本记录

  • 修订版 1，2025 年 12 月 18 日（Ben King）

    • 初始扩展程序说明。