XR_ANDROID_spatial_anchor_space

Name String

XR_ANDROID_spatial_anchor_space

Loại tiện ích

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

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

796

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_spatial_anchor

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

2025-09-15

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

YuSheng Chang, Google
Kyle Chen, Google
Levana Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Tổng quan

Hàm xrCreateSpatialAnchorEXT được xác định trong tiện ích XR_EXT_spatial_anchor cho phép các ứng dụng tạo neo không gian bằng một tay điều khiển XrSpatialEntityEXT để biểu thị neo đó. Ngược lại, tiện ích này tạo một neo không gian được biểu thị bằng một tay điều khiển XrSpace. Điều này hữu ích trong trường hợp ứng dụng muốn:

  • Sử dụng xrLocateSpaces để lấy vị trí của neo.
  • Xác định vị trí của các không gian khác so với điểm neo.
  • Xuất điểm neo bằng XR_ANDROID_anchor_sharing_export .
  • Ứng dụng đã đặt các neo và hiện chỉ quan tâm đến vị trí của các neo (để đính kèm nội dung ảo) và không quan tâm đến bất kỳ thành phần nào khác của bất kỳ thực thể nào khác được phát hiện thông qua XrSpatialContextEXT dùng để tạo neo, từ đó cho phép ứng dụng huỷ bối cảnh không gian.

Bạn không thể duy trì các neo được tạo bằng tiện ích này bằng tiện ích XR_ANDROID_device_anchor_persistence và ứng dụng phải sử dụng XR_EXT_spatial_persistence_operations . Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE từ xrPersistAnchorANDROID nếu XrPersistedAnchorSpaceInfoANDROID :: anchor được tạo bằng xrCreateSpatialAnchorSpaceANDROID hoặc xrCreateSpatialAnchorSpaceFromIdANDROID .

Tạo XrSpace cho một Điểm neo không gian

Tạo không gian và neo không gian

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

XrResult xrCreateSpatialAnchorSpaceANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorCreateInfoEXT*         createInfo,
    XrSpatialEntityIdEXT*                       anchorEntityId,
    XrSpace*                                    anchorSpace);

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

Hàm xrCreateSpatialAnchorSpaceANDROID tạo một neo xuất ra một XrSpatialEntityIdEXT và một tay điều khiển XrSpace. xrCreateSpatialAnchorSpaceANDROID có các yêu cầu xác thực giống như xrCreateSpatialAnchorEXT .

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE nếu XrSpatialContextEXT được truyền đến xrCreateSpatialAnchorSpaceANDROID không được định cấu hình bằng XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

Đối với khả năng được phát hiện của điểm neo đã tạo bằng xrCreateSpatialAnchorSpaceANDROID , đoạn cuối của thông số kỹ thuật xrCreateSpatialAnchorEXT sẽ được áp dụng.

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

  • Bạn phải bật tiện ích XR_ANDROID_spatial_anchor_space trước khi gọi xrCreateSpatialAnchorSpaceANDROID
  • session phải là một tên người dùng XrSession hợp lệ
  • spatialContext phải là một tay điều khiển XrSpatialContextEXT hợp lệ
  • createInfo phải là con trỏ đến cấu trúc XrSpatialAnchorCreateInfoEXT hợp lệ
  • anchorEntityId phải là một con trỏ đến giá trị XrSpatialEntityIdEXT
  • anchorSpace phải là con trỏ đến một tay điều khiển XrSpace
  • spatialContext phải được tạo, phân bổ hoặc truy xuất từ session

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

Tạo XrSpace từ một neo không gian hiện có

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

XrResult xrCreateSpatialAnchorSpaceFromIdANDROID(
    XrSession                                   session,
    XrSpatialContextEXT                         spatialContext,
    const XrSpatialAnchorSpaceFromIdCreateInfoANDROID* createInfo,
    XrSpace*                                    anchorSpace);

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

Trong trường hợp các thực thể neo không gian đã tồn tại từ trước (ví dụ: do tính bền vững), các ứng dụng có thể tạo một XrSpace từ các neo không gian này bằng cách cung cấp mã thực thể không gian của chúng.

Hàm xrCreateSpatialAnchorSpaceFromIdANDROID tạo một tay điều khiển XrSpace bằng cách cung cấp một XrSpatialEntityIdEXT trong trường XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId.

Thời gian chạy phải trả về XR_ERROR_VALIDATION_FAILURE nếu XrSpatialContextEXT được truyền đến xrCreateSpatialAnchorSpaceFromIdANDROID không được định cấu hình bằng XR_SPATIAL_CAPABILITY_ANCHOR_EXT .

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

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

typedef struct XrSpatialAnchorSpaceFromIdCreateInfoANDROID {
    XrStructureType         type;
    const void*             next;
    XrSpatialEntityIdEXT    anchorEntityId;
} XrSpatialAnchorSpaceFromIdCreateInfoANDROID;

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.
  • anchorEntityId là XrSpatialEntityIdEXT của neo không gian hiện có để tạo XrSpace .

Thời gian chạy phải trả về XR_ERROR_SPATIAL_ENTITY_ID_INVALID_EXT nếu XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId không phải là mã nhận dạng hợp lệ cho spatialContext .

Thời gian chạy phải trả về XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID nếu XrSpatialAnchorSpaceFromIdCreateInfoANDROID ::entityId không phải là mã nhận dạng thực thể hợp lệ cho một neo.

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

Vòng đời của neo

Phần tử mẹ của một tay điều khiển XrSpace là một XrSession . Điều này có nghĩa là một tay điều khiển XrSpace đại diện cho neo vẫn hợp lệ ngay cả sau khi xrCreateSpatialAnchorSpaceFromIdANDROID :: spatialContext hoặc xrCreateSpatialAnchorSpaceANDROID :: spatialContext bị huỷ. Việc tạo một XrSpace để đại diện cho một neo thực thể không gian cho phép ứng dụng huỷ XrSpatialContextEXT đã được định cấu hình bằng XR_SPATIAL_CAPABILITY_ANCHOR_EXT trong khi vẫn tiếp tục nhận được tư thế mới nhất của neo bằng cách sử dụng XrSpace của neo đó với xrLocateSpaces, tức là thời gian chạy phải tiếp tục theo dõi neo cho đến khi tất cả các tay điều khiển XrSpace đại diện cho neo đó bị huỷ.

Mã ví dụ

Tạo neo không gian dưới dạng XrSpace

Mã ví dụ sau đây minh hoạ cách tạo một neo không gian và trả về neo đó dưới dạng XrSpace .

XrSpatialEntityIdEXT spatialAnchorEntityId;
XrSpace spatialAnchorSpace {XR_NULL_HANDLE}; // XrSpace handle of anchor

// Spatial anchor create info
XrSpatialAnchorCreateInfoEXT createInfo{
  .type = XR_TYPE_SPATIAL_ANCHOR_CREATE_INFO_EXT,
  .baseSpace = localSpace,
  .time = predictedDisplayTime,
  .pose = {{0, 0, 0, 1}, {1, 1, 1}},
};

// Create spatial anchor using the new API
CHK_XR(xrCreateSpatialAnchorSpaceANDROID(session, spatialContext, &createInfo, &spatialAnchorEntityId, &spatialAnchorSpace));

// ...

Tạo XrSpace từ mã nhận dạng thực thể neo

Mã ví dụ sau đây minh hoạ cách tạo XrSpace từ mã nhận dạng thực thể neo có sẵn.

XrSpace anchorSpace = XR_NULL_HANDLE;

// Spatial anchor from XrSpace create info
XrSpatialAnchorSpaceFromIdCreateInfoANDROID createInfoFromId{
  .type = XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID,
  .anchorEntityId = spatialAnchorEntityId,
};

// Create XrSpace handle from spatial anchor ID
CHK_XR(xrCreateSpatialAnchorSpaceFromIdANDROID(session, spatialContext, &createInfoFromId, &anchorSpace));

// ...

Lệnh mới

Cấu trúc mới

Hằng số enum mới

  • XR_ANDROID_SPATIAL_ANCHOR_SPACE_EXTENSION_NAME
  • XR_ANDROID_spatial_anchor_space_SPEC_VERSION

  • Mở rộng XrResult :

    • XR_ERROR_SPATIAL_ANCHOR_ENTITY_ID_INVALID_ANDROID

  • Mở rộng XrStructureType :

    • XR_TYPE_SPATIAL_ANCHOR_SPACE_FROM_ID_CREATE_INFO_ANDROID

Vấn đề

Danh sách phiên bản

  • Bản sửa đổi 1, ngày 15 tháng 9 năm 2025 (YuSheng Chang, Kyle Chen)

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