XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

Loại tiện ích

Tiện ích phiên bản

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

790

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa được phê chuẩn

Phần mở rộng và các phần phụ thuộc vào phiên bản

XR_EXT_future

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

2025-12-18

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 tính năng Theo dõi không gian địa lý cho API Không gian địa lý của Google. API này cung cấp thông tin chính xác về vị trí địa lý và hướng, đồng thời cho phép ứng dụng đặt nội dung liên quan đến Trái Đất. Hệ thống này thực hiện việc này bằng cách kết hợp tính năng theo dõi chuyển động, GPS và các cảm biến khác, cũng như Hệ thống định vị bằng hình ảnh (VPS) của Google. VPS so sánh hình ảnh từ camera của thiết bị với hình ảnh trong Chế độ xem đường phố để xác định vị trí chính xác và hướng. API Không gian địa lý thường cung cấp độ chính xác về vị trí dưới một mét (chính xác hơn GPS nhiều lần) và độ chính xác về hướng dưới một độ.

Để sử dụng thành công các API trong tiện ích này (ngoài việc kiểm tra khả năng hỗ trợ tiện ích), ứng dụng phải thiết lập thành công thông tin xác thực thông qua một số cơ chế, chẳng hạn như XR_ANDROID_google_cloud_auth . Hãy xem tài liệu về tiện ích xác thực để biết thêm thông tin chi tiết về chế độ thiết lập và kết quả lỗi.

Quyền

Các ứng dụng Android phải có quyền android.permission.ACCESS_FINE_LOCATION được liệt kê trong tệp kê khai để sử dụng tiện ích này. Quyền android.permission.ACCESS_FINE_LOCATION được coi là một quyền nguy hiểm. Ứng dụng phải yêu cầu cấp quyền trong thời gian chạy để sử dụng các chức năng này:

(cấp độ bảo vệ: nguy hiểm)

Kiểm tra khả năng của hệ thống

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

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • supportsGeospatial là một XrBool32 , cho biết liệu hệ thống hiện tại có hỗ trợ các tính năng không gian địa lý hay không.

Một ứng dụng có thể kiểm tra xem hệ thống có hỗ trợ các tính năng không gian địa lý hay không bằng cách liên kết cấu trúc XrSystemGeospatialPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties .

Nếu một thời gian chạy trả về XR_FALSE cho supportsGeospatial, thì hệ thống không hỗ trợ các tính năng không gian địa lý và do đó phải trả về XR_ERROR_FEATURE_UNSUPPORTED từ xrCreateGeospatialTrackerANDROID . Ứng dụng nên tránh sử dụng chức năng không gian địa lý khi supportsGeospatial là XR_FALSE .

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

Tạo một đối tượng xử lý Geospatial Tracker

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

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

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

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

  • session là một XrSession mà trong đó trình theo dõi không gian địa lý sẽ hoạt động.
  • createInfo là con trỏ đến một cấu trúc XrGeospatialTrackerCreateInfoANDROID chỉ định các tham số ban đầu của trình theo dõi không gian địa lý.
  • geospatialTrackerOutput là con trỏ đến một đối tượng mà XrGeospatialTrackerANDROID đã tạo sẽ được trả về.

Một ứng dụng có thể tạo một đối tượng XrGeospatialTrackerANDROID bằng cách gọi xrCreateGeospatialTrackerANDROID . Sau đó, bạn có thể sử dụng giá trị nhận dạng XrGeospatialTrackerANDROID được trả về trong các lệnh gọi API. Nếu ứng dụng chưa có các quyền cần thiết, thì thời gian chạy phải trả về XR_ERROR_PERMISSION_INSUFFICIENT . Chỉ có thể có một XrGeospatialTrackerANDROID có thể tồn tại tại một thời điểm cho một XrSession cụ thể . Ứng dụng phải đảm bảo rằng mọi đối tượng XrGeospatialTrackerANDROID trước đó đã bị huỷ trước khi gọi lại hàm này, nếu không, thời gian chạy phải trả về XR_ERROR_LIMIT_REACHED . Nếu được tạo thành công, trình theo dõi ban đầu sẽ chuyển sang trạng thái XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID và ứng dụng phải đợi cho đến khi trạng thái thay đổi thành XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID thì mới có thể sử dụng trình theo dõi. Xem XrEventDataGeospatialTrackerStateChangedANDROID . Nếu ứng dụng truyền một XrGeospatialTrackerANDROID không ở trạng thái XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID đến một hàm yêu cầu ứng dụng đó, thì thời gian chạy phải trả về XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID .

Cuối cùng, bạn phải giải phóng đối tượng XrGeospatialTrackerANDROID thông qua hàm xrDestroyGeospatialTrackerANDROID.

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

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

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.

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

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

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

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

Một ứng dụng có thể sử dụng hàm xrDestroyGeospatialTrackerANDROID để giải phóng trình theo dõi vị trí địa lý và các tài nguyên cơ bản.

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

Độ an toàn cho luồng

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

Mã trả về

Thành công

  • XR_SUCCESS

Thất bại

  • XR_ERROR_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Trạng thái của thiết bị theo dõi không gian địa lý

Liệt kê XrGeospatialTrackerStateANDROID được xác định như sau:

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;

Liệt kê XrGeospatialTrackerStateANDROID để xác định các trạng thái của trình theo dõi không gian địa lý.

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

Nội dung mô tả enum

XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID

Thiết bị theo dõi không gian địa lý không chạy.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Thiết bị theo dõi không gian địa lý đang chạy và có thể sử dụng.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Geospatial Tracker không khởi động được và sẽ không bao giờ sử dụng được.

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

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • geospatialTracker là XrGeospatialTrackerANDROID có trạng thái đã thay đổi.
  • state là XrGeospatialTrackerStateANDROID mới .
  • initializationResult là kết quả lỗi nếu state là XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID , nếu không thì kết quả sẽ là XR_SUCCESS .
  • time là XrTime mà tại đó trạng thái thay đổi.

Cấu trúc XrEventDataGeospatialTrackerStateChangedANDROID được gửi khi trạng thái của trình theo dõi vị trí địa lý thay đổi. Nếu ứng dụng có XrGeospatialTrackerANDROID hợp lệ , thì ứng dụng nên thăm dò sự kiện này. Sự kiện đầu tiên nhận được cho một trình theo dõi sẽ có state XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID . Sau một khoảng thời gian do thời gian chạy xác định, trạng thái phải thay đổi thành XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID hoặc XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID . Quá trình chuyển đổi này sẽ mất một khoảng thời gian tuỳ ý. Nếu state thay đổi thành XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID, thì đây phải là sự kiện cuối cùng nhận được cho trình theo dõi này và trường initializationResult sẽ chứa mã lỗi. Có thể mất vài giây thì lỗi mới xảy ra. Trong trường hợp này, ứng dụng phải huỷ thiết bị theo dõi. Nếu state thay đổi thành XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , tất cả neo không gian địa lý đã tạo trước đó phải ngừng theo dõi vĩnh viễn và nên bị ứng dụng huỷ. Trạng thái có thể thay đổi qua lại giữa XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID và XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID tuỳ ý nhiều lần.

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

Tư thế không gian địa lý

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

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

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

  • eastUpSouthOrientation là một XrQuaternionf xác định hướng theo hệ toạ độ trong đó +X=Đông, +Y=Lên và +Z=Nam.
  • latitude là vĩ độ tính bằng độ, trong khoảng từ -90 đến +90.
  • longitude là kinh độ tính bằng độ, trong khoảng từ -180 đến +180.
  • altitude là độ cao tính bằng mét so với hình elip WGS84.

Cấu trúc XrGeospatialPoseANDROID biểu thị vị trí và hướng tương ứng với Trái Đất bằng cách sử dụng hình elip WGS84.

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

  • Bạn phải bật tiện ích XR_ANDROID_geospatial trước khi sử dụng XrGeospatialPoseANDROID
  • latitude phải là một giá trị double hợp lệ
  • longitude phải là một giá trị double hợp lệ
  • altitude phải là một giá trị double hợp lệ

Liệt kê XrGeospatialPoseFlagBitsANDROID được xác định như sau:

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

Liệt kê XrGeospatialPoseFlagBitsANDROID chỉ định các cờ cho tư thế không gian địa lý.

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

Nội dung mô tả cờ

  • XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID – Cho biết thành phần hướng chứa dữ liệu hợp lệ
  • XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID – Cho biết rằng thành phần vị trí chứa dữ liệu hợp lệ

Loại XrGeospatialPoseFlagsANDROID là một mặt nạ bit của XrGeospatialPoseFlagBitsANDROID .

typedef XrFlags64 XrGeospatialPoseFlagsANDROID;

Chuyển đổi XrPosef thành Geospatial Pose

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

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

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

Hàm xrLocateGeospatialPoseFromPoseANDROID chuyển đổi một tư thế trong XrGeospatialPoseFromPoseLocateInfoANDROID :: space thành một tư thế không gian địa lý. Nếu trạng thái của geospatialTracker không phải là XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID , thì thời gian chạy phải trả về XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Nếu hàm trả về XR_SUCCESS , thì trường XrGeospatialPoseResultANDROID :: poseFlags của geospatialPoseResult sẽ xác định những trường đầu ra hợp lệ. Nếu XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID không được đặt trong XrGeospatialPoseResultANDROID :: poseFlags , ứng dụng không được đọc các trường XrGeospatialPoseANDROID :: latitude , XrGeospatialPoseANDROID :: longitude , XrGeospatialPoseANDROID :: altitude , XrGeospatialPoseResultANDROID :: horizontalAccuracy hoặc XrGeospatialPoseResultANDROID :: verticalAccuracy trong XrGeospatialPoseResultANDROID . Nếu XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID không được đặt trong XrGeospatialPoseResultANDROID :: poseFlags , thì ứng dụng không được đọc XrGeospatialPoseANDROID :: eastUpSouthOrientation hoặc XrGeospatialPoseResultANDROID :: orientationYawAccuracy . Nếu bạn không đặt XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID, thì bạn không được đặt XR_GEOSPATIAL_POSE_ORIENTATION_VALID_BIT_ANDROID.

Nếu độ chính xác thấp hơn dự kiến, thì có thể đây là dấu hiệu cho thấy thiết bị không sử dụng tính năng bản địa hoá VPS. Ứng dụng có thể hướng dẫn người dùng hướng thiết bị vào biển hiệu và toà nhà để cải thiện khả năng bản địa hoá.

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

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

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • space là XrSpace mà pose được xác định.
  • time là XrTime mà tại đó bạn sẽ đánh giá pose .
  • pose là XrPosef trong space để chuyển đổi thành tư thế không gian địa lý.

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

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

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • poseFlags là một mặt nạ bit của XrGeospatialPoseFlagsANDROID cho biết tính hợp lệ của các thành phần tư thế.
  • geospatialPose là XrGeospatialPoseANDROID thu được .
  • horizontalAccuracy là độ chính xác theo phương ngang ước tính của vị trí tư thế không gian địa lý, được xác định là bán kính tính bằng mét của vòng tròn có độ tin cậy 68% xung quanh vĩ độ và kinh độ đã cho.
  • verticalAccuracy là độ chính xác theo phương thẳng đứng ước tính của vị trí Tư thế không gian địa lý, được xác định là khoảng cách tính bằng mét với độ tin cậy 68% xung quanh độ cao đã cho. Nói cách khác, có 68% khả năng độ cao thực nằm trong khoảng [ XrGeospatialPoseANDROID :: altitude - verticalAccuracy , XrGeospatialPoseANDROID :: altitude \+ verticalAccuracy ].
  • orientationYawAccuracy là độ chính xác ước tính của hướng xoay ngang của Tư thế không gian địa lý, được xác định là bán kính theo độ của độ tin cậy 68% xung quanh hướng đã cho.

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

Chuyển đổi Tư thế không gian địa lý thành XrPosef

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

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

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

Hàm xrLocateGeospatialPoseANDROID chuyển đổi tư thế không gian địa lý thành XrSpaceLocation . Nếu XrGeospatialTrackerANDROID không chạy, thì thời gian chạy phải trả về XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID . Nếu hàm trả về XR_SUCCESS , thì trường XrSpaceLocation :: locationFlags của location sẽ xác định những trường đầu ra nào hợp lệ.

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

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

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • space là XrSpace mà tư thế thu được sẽ được biểu thị.
  • time là XrTime để xác định vị trí tư thế.
  • geospatialPose là XrGeospatialPoseANDROID cần chuyển đổi.

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

Phạm vi cung cấp VPS

Liệt kê XrVPSAvailabilityANDROID như sau:

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

Liệt kê XrVPSAvailabilityANDROID cho biết tình trạng còn hàng của VPS.

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

Nội dung mô tả enum

XR_VPS_AVAILABILITY_UNAVAILABLE_ANDROID

VPS không hoạt động ở gần vị trí đã cho.

XR_VPS_AVAILABILITY_AVAILABLE_ANDROID

VPS có ở gần vị trí đã cho.

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

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

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

  • session là XrSession cần dùng cho quy trình kiểm tra.
  • latitude là vĩ độ tính bằng độ.
  • longitude là kinh độ tính bằng độ.
  • future là một con trỏ trỏ đến XrFutureEXT sẽ giữ kết quả của hoạt động không đồng bộ.

Trạng thái sẵn có của Dịch vụ định vị bằng hình ảnh (VPS) cho biết liệu VPS có thể được dùng để cải thiện độ chính xác về không gian địa lý tại một vị trí nhất định hay không.

Hàm xrCheckVpsAvailabilityAsyncANDROID bắt đầu quy trình kiểm tra không đồng bộ để xác định xem VPS có hoạt động tại một vị trí nhất định hay không. Ứng dụng không cần XrGeospatialTrackerANDROID để gọi hàm này và có thể sử dụng kết quả của thao tác này để quyết định có tạo một hàm hay không. Nếu ứng dụng chưa có các quyền cần thiết, thì thời gian chạy phải trả về XR_ERROR_PERMISSION_INSUFFICIENT .

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

  • Bạn phải bật tiện ích XR_ANDROID_geospatial trước khi gọi xrCheckVpsAvailabilityAsyncANDROID
  • session phải là một đối tượng XrSession hợp lệ
  • latitude phải là một giá trị double hợp lệ
  • longitude phải là một giá trị double hợp lệ
  • future phải là con trỏ đến giá trị XrFutureEXT

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_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

XrResult xrCheckVpsAvailabilityCompleteANDROID(
    XrSession                                   session,
    XrFutureEXT                                 future,
    XrVPSAvailabilityCheckCompletionANDROID*    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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

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

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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • futureResult là XrResult của thao tác kiểm tra. 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.
  • availability là XrVPSAvailabilityANDROID thu được . Ứng dụng không được đọc trường này trừ phi futureResult 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_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID

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

Ví dụ

Thiết lập Geospatial Tracker

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

Gọi 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.
}

Các loại đối tượng mới

Lệnh mới

Cấu trúc mới

Enum mới

Mặt nạ bit mới

Hằng số Enum mới

  • XR_ANDROID_GEOSPATIAL_EXTENSION_NAME
  • XR_ANDROID_geospatial_SPEC_VERSION

  • Mở rộng XrObjectType :

    • XR_OBJECT_TYPE_GEOSPATIAL_TRACKER_ANDROID

  • Mở rộng XrResult :

    • XR_ERROR_GEOSPATIAL_CLOUD_AUTH_FAILED_ANDROID
    • XR_ERROR_GEOSPATIAL_COORDINATES_INVALID_ANDROID
    • XR_ERROR_GEOSPATIAL_TRACKER_NOT_RUNNING_ANDROID

  • Mở rộng 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

Vấn đề

Nhật ký phiên bản

  • Bản sửa đổi 1, ngày 18/12/2025 (Ben King)

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