XR_ANDROID_geospatial

Name String

XR_ANDROID_geospatial

Loại tiện ích

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

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

790

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_future

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

2025-12-18

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 tính năng theo dõi không gian địa lý cho Geospatial API của Google, giúp 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 theo Trái Đất. Tính năng này hoạt động 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ị trực quan (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í và hướng chính xác. Geospatial API thường cung cấp độ chính xác về vị trí dưới một mét (mức độ chính xác cao hơn nhiều so với GPS) 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 đặt 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ề cách thiết lập và kết quả lỗi.

Quyền

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

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

Kiểm tra chức năng của hệ thống

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

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

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

Ứ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 sẽ không hỗ trợ các tính năng không gian địa lý, 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 ẩn)

Tạo một trình xử lý Trình theo dõi không gian địa lý

XR_DEFINE_HANDLE(XrGeospatialTrackerANDROID)

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

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

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

  • session là một XrSession, trong đó trình theo dõi không gian địa lý sẽ hoạt động.
  • createInfo là con trỏ đến 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 handle mà trong đó XrGeospatialTrackerANDROID được tạo sẽ được trả về.

Ứng dụng có thể tạo một tay điều khiển XrGeospatialTrackerANDROID bằng cách gọi xrCreateGeospatialTrackerANDROID . Sau đó, bạn có thể sử dụng tay điều khiển XrGeospatialTrackerANDROID được trả về trong các lệnh gọi API. Nếu ứng dụng chưa có đượ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 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 trình theo dõi được tạo thành công, thì ban đầu trình theo dõi 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 chuyển sang XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID trước khi 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 trạng thái đó, 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 tay điều khiển XrGeospatialTrackerANDROID thông qua hàm xrDestroyGeospatialTrackerANDROID.

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

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

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.

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

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

XrResult xrDestroyGeospatialTrackerANDROID(
    XrGeospatialTrackerANDROID                  geospatialTracker);

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

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

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

Độ an toàn cho chuỗi

  • Quyền truy cập vào geospatialTracker 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_CALL_ORDER_INVALID
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

Trạng thái của trình theo dõi không gian địa lý

Phép liệt kê XrGeospatialTrackerStateANDROID được định nghĩa 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;

Kiểu 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

Trình theo dõi không gian địa lý không chạy.

XR_GEOSPATIAL_TRACKER_STATE_RUNNING_ANDROID

Trình theo dõi không gian địa lý đang chạy và có thể sử dụng được.

XR_GEOSPATIAL_TRACKER_STATE_INITIALIZATION_FAILED_ANDROID

Không khởi động được Trình theo dõi không gian địa lý và sẽ không thể sử dụng được.

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

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

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ó 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ì 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 không gian địa lý thay đổi. Nếu ứng dụng có XrGeospatialTrackerANDROID hợp lệ, thì ứng dụng nên thăm dò ý kiến về 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 để lỗi xảy ra. Trong trường hợp này, ứng dụng nên huỷ trình theo dõi. Nếu state thay đổi thành XR_GEOSPATIAL_TRACKER_STATE_STOPPED_ANDROID , thì tất cả các neo không gian địa lý đã tạo trước đó phải ngừng theo dõi vĩnh viễn và phải 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 nhiều lần tuỳ ý.

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

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

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

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

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

  • eastUpSouthOrientation là một XrQuaternionf xác định hướng đối với 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 độ, 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 ẩn)

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

Phép liệt kê XrGeospatialPoseFlagBitsANDROID được định nghĩa 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;

Bảng liệt kê XrGeospatialPoseFlagBitsANDROID chỉ định 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 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 Tư thế không gian địa lý

Hàm xrLocateGeospatialPoseFromPoseANDROID được định nghĩa 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 tư thế trong XrGeospatialPoseFromPoseLocateInfoANDROID :: space thành 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 trường đầu ra nào hợp lệ. Nếu XR_GEOSPATIAL_POSE_POSITION_VALID_BIT_ANDROID không được đặt trong XrGeospatialPoseResultANDROID :: poseFlags , thì ứ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 cũng 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ì đây có thể 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ị của họ vào các biển báo và toà nhà để cải thiện khả năng bản địa hoá.

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

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

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.
  • space là XrSpace mà pose được xác định.
  • time là XrTime để đá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 ẩn)

Cấu trúc XrGeospatialPoseResultANDROID được định nghĩa 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ả 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.
  • 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 ước tính theo chiều ngang 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ó mức độ tin cậy 68% xung quanh vĩ độ và kinh độ đã cho.
  • verticalAccuracy là độ chính xác ước tính theo chiều dọc 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 của mức độ 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 góc lệch trong hướng tư thế Địa không gian, được xác định là bán kính tính bằng độ của mức độ tin cậy 68% xung quanh hướng đã cho.

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

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

Hàm xrLocateGeospatialPoseANDROID được định nghĩa 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 trường đầu ra nào là hợp lệ.

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

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

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

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.
  • space là XrSpace mà tư thế thu được sẽ được biểu thị.
  • time là XrTime để xác định tư thế.
  • geospatialPose là XrGeospatialPoseANDROID cần chuyển đổi.

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

Phạm vi cung cấp VPS

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

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

Bảng 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ó sẵn gần vị trí đã cho.

Hàm xrCheckVpsAvailabilityAsyncANDROID được định nghĩa 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 để 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ẽ lưu giữ kết quả của hoạt động không đồng bộ.

Phạm vi cung cấp 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 của dữ liệu không gian địa lý tại một vị trí nhất định hay không.

Hàm xrCheckVpsAvailabilityAsyncANDROID bắt đầu kiểm tra không đồng bộ về phạm vi cung cấp VPS tại một vị trí nhất định. Ứ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 xem có tạo một hàm hay không. Nếu ứng dụng chưa có đượ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 ẩn)

  • Tiện ích XR_ANDROID_geospatial phải được bật trước khi gọi xrCheckVpsAvailabilityAsyncANDROID
  • session phải là một tên người dù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à một con trỏ đến giá trị XrFutureEXT

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

Hàm xrCheckVpsAvailabilityCompleteANDROID được định nghĩa 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 ẩ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_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

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

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

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

Không thành công

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

Ví dụ

Thiết lập trình theo dõi không gian địa lý

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 API Tư thế không gian địa lý

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, 18/12/2025 (Ben King)

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