XR_ANDROID_trackables_marker

สตริงชื่อ

XR_ANDROID_trackables_marker

ประเภทส่วนขยาย

ส่วนขยายอินสแตนซ์

หมายเลขส่วนขยายที่จดทะเบียน

708

การแก้ไข

1

สถานะการให้สัตยาบัน

ยังไม่ให้สัตยาบัน

การขึ้นต่อกันของส่วนขยายและเวอร์ชัน

XR_ANDROID_trackables

สถานะการเลิกใช้งาน

  • เลิกใช้งานโดยส่วนขยาย XR_EXT_spatial_marker_tracking

วันที่แก้ไขล่าสุด

2025-07-23

สถานะ IP

ไม่มีการอ้างสิทธิ์ IP ที่ทราบ

ผู้เขียน

Christopher Doer, Google
Diego Tipaldi, Google
Levana Chen, Google
Jared Finder, Google
Spencer Quin, Google
Nihav Jain, Google
Ken Mackay, Google
Daniel Guttenberg, Qualcomm

ภาพรวม

ส่วนขยายนี้ช่วยให้สามารถติดตามเครื่องหมายจริงและช่วยให้แอปพลิเคชันแนบเนื้อหา XR กับเครื่องหมายจริงได้อย่างมีประสิทธิภาพ

ส่วนขยายนี้รองรับเครื่องหมายประเภทที่รู้จักกันดี ได้แก่ ArUco และ April Tags และช่วยให้รันไทม์รองรับการประมาณขนาดเครื่องหมายได้ (ไม่บังคับ)

สิทธิ์

แอปพลิเคชัน Android ต้อง มีสิทธิ์ android.permission.SCENE_UNDERSTANDING_COARSE ที่ระบุไว้ในไฟล์ Manifest เนื่องจากส่วนขยายนี้ขึ้นอยู่กับ XR_ANDROID_trackables และแสดงเรขาคณิตของสภาพแวดล้อม สิทธิ์ android.permission.SCENE_UNDERSTANDING_COARSE ถือเป็นสิทธิ์ที่เป็นอันตราย ซึ่งหมายความว่าแอปพลิเคชันต้อง ขอสิทธิ์อย่างชัดเจน

(ระดับการปกป้อง: อันตราย)

ตรวจสอบความสามารถของระบบ

โครงสร้าง XrSystemMarkerTrackingPropertiesANDROID กำหนดไว้ดังนี้

typedef struct XrSystemMarkerTrackingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsMarkerTracking;
    XrBool32           supportsMarkerSizeEstimation;
    uint16_t           maxMarkerCount;
} XrSystemMarkerTrackingPropertiesANDROID;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้ ดูรายละเอียดเพิ่มเติมเกี่ยวกับเชนโครงสร้างได้ในโครงสร้างที่ขยาย ( XrSystemProperties )
  • supportsMarkerTracking คือ XrBool32 ที่ระบุว่าระบบปัจจุบันมีความสามารถในการติดตามเครื่องหมายหรือไม่
  • supportsMarkerSizeEstimation คือ XrBool32 ที่ระบุว่าระบบปัจจุบันมีความสามารถในการประมาณขนาดเครื่องหมายหรือไม่
  • maxMarkerCount คือจำนวนเครื่องหมายสูงสุดที่รันไทม์ติดตามได้พร้อมกัน

แอปพลิเคชันสามารถ ตรวจสอบว่าระบบมีความสามารถในการติดตามเครื่องหมายหรือไม่โดยขยาย XrSystemProperties ด้วยโครงสร้าง XrSystemMarkerTrackingPropertiesANDROID เมื่อเรียกใช้ xrGetSystemProperties รันไทม์ต้อง แสดงผล XR_ERROR_FEATURE_UNSUPPORTED สำหรับการสร้างเครื่องมือติดตามเครื่องหมายก็ต่อเมื่อ supportsMarkerTracking เป็น XR_FALSE เท่านั้น

หากรันไทม์รองรับการติดตามเครื่องหมาย maxMarkerCount ต้อง มีค่าอย่างน้อย 1

การใช้งานที่ถูกต้อง (โดยนัย)

การติดตามเครื่องหมาย

ส่วนขยายนี้จะเพิ่ม XR_TRACKABLE_TYPE_MARKER_ANDROID ลงใน XrTrackableTypeANDROID

แอปพลิเคชันสร้าง XrTrackableTrackerANDROID โดยเรียกใช้ xrCreateTrackableTrackerANDROID และระบุ XR_TRACKABLE_TYPE_MARKER_ANDROID เป็นประเภทที่ติดตามได้ใน XrTrackableTrackerCreateInfoANDROID :: trackableType รวมถึงตั้งค่าการกำหนดค่าที่ถูกต้องโดยเพิ่ม XrTrackableMarkerConfigurationANDROID ลงในเชนถัดไปของ XrTrackableTrackerCreateInfoANDROID

รันไทม์ต้อง แสดงผล XR_ERROR_FEATURE_UNSUPPORTED หาก XrTrackableTrackerCreateInfoANDROID :: trackableType เป็น XR_TRACKABLE_TYPE_MARKER_ANDROID และ XrSystemMarkerTrackingPropertiesANDROID :: supportsMarkerTracking แสดงผล XR_FALSE ผ่าน xrGetSystemProperties

โครงสร้าง XrTrackableMarkerConfigurationANDROID กำหนดไว้ดังนี้

typedef struct XrTrackableMarkerConfigurationANDROID {
    XrStructureType                            type;
    void*                                      next;
    XrTrackableMarkerTrackingModeANDROID       trackingMode;
    uint32_t                                   databaseCount;
    const XrTrackableMarkerDatabaseANDROID*    databases;
} XrTrackableMarkerConfigurationANDROID;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • trackingMode คือ XrTrackableMarkerTrackingModeANDROID ที่ระบุโหมดที่ต้องการสำหรับการติดตาม
  • databaseCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ databases
  • databases คือ Pointer ไปยังอาร์เรย์ของ XrTrackableMarkerDatabaseANDROID ซึ่งแต่ละรายการมีตัวทำเครื่องหมายที่ต้องการจากพจนานุกรมที่กำหนดเพื่อติดตาม

แอปพลิเคชันต้อง ตั้งค่าการกำหนดค่าที่ถูกต้องโดยเพิ่ม XrTrackableMarkerConfigurationANDROID ลงในเชน XrTrackableTrackerCreateInfoANDROID :: next เมื่อเรียกใช้ xrCreateTrackableTrackerANDROID โดยตั้งค่า XrTrackableTrackerCreateInfoANDROID :: trackableType เป็น XR_TRACKABLE_TYPE_MARKER_ANDROID หากตั้งค่าประเภทเครื่องมือติดตามตามที่ระบุไว้ข้างต้น แต่ไม่มีโครงสร้างการกำหนดค่าหรือโครงสร้างการกำหนดค่าไม่ถูกต้อง รันไทม์ต้อง แสดงผล XR_ERROR_VALIDATION_FAILURE

หากรันไทม์รองรับการประมาณขนาดเครื่องหมาย แอปพลิเคชันสามารถ ตั้งค่า XrTrackableMarkerDatabaseEntryANDROID :: edgeSize เป็น 0 ใน XrTrackableMarkerDatabaseANDROID :: entries เพื่อระบุการใช้การประมาณขนาด มิฉะนั้น แอปพลิเคชันต้อง ตั้งค่า XrTrackableMarkerDatabaseEntryANDROID :: edgeSize เป็นค่าบวก หรือรันไทม์ต้อง แสดงผล XR_ERROR_VALIDATION_FAILURE

รันไทม์ต้อง กรองเอาต์พุตจาก xrGetAllTrackablesANDROID ให้ตรงกับ trackingMode และ XrTrackableMarkerDatabaseEntryANDROID :: edgeSize

การใช้งานที่ถูกต้อง (โดยนัย)

Enum XrTrackableMarkerTrackingModeANDROID อธิบายโหมดการติดตามเครื่องหมายที่รองรับ

typedef enum XrTrackableMarkerTrackingModeANDROID {
    XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID = 0,
    XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID = 1,
    XR_TRACKABLE_MARKER_TRACKING_MODE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerTrackingModeANDROID;

คำอธิบาย Enumerant

  • XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID \- การติดตามเครื่องหมายแบบไดนามิก โหมดนี้มีความแม่นยำสูงสุดและใช้ได้กับเครื่องหมายที่เคลื่อนไหวและคงที่ แต่ก็ใช้พลังงานสูงสุดด้วย
  • XR_TRACKABLE_MARKER_TRACKING_MODE_STATIC_ANDROID \- การติดตามเครื่องหมายคงที่ โหมดนี้มีประโยชน์หลักๆ สำหรับเครื่องหมายที่ทราบว่าคงที่ ซึ่งจะใช้พลังงานน้อยกว่าเมื่อเทียบกับโหมดไดนามิก

โครงสร้าง XrTrackableMarkerDatabaseANDROID กำหนดพจนานุกรมและรหัสเครื่องหมายที่เกี่ยวข้องเพื่อติดตาม

typedef struct XrTrackableMarkerDatabaseANDROID {
    XrTrackableMarkerDictionaryANDROID              dictionary;
    uint32_t                                        entryCount;
    const XrTrackableMarkerDatabaseEntryANDROID*    entries;
} XrTrackableMarkerDatabaseANDROID;

คำอธิบายสมาชิก

  • dictionary คือ XrTrackableMarkerDictionaryANDROID ที่ entries ทั้งหมดเป็นของ
  • entryCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ entries แอปพลิเคชันสามารถ ตั้งค่า entryCount เป็น 0 เพื่อติดตามเครื่องหมายทั้งหมดใน dictionary
  • entries คือตัวชี้ไปยังอาร์เรย์ของ XrTrackableMarkerDatabaseEntryANDROID ซึ่งแต่ละรายการมีการกำหนดค่าของเครื่องหมายที่จะติดตาม

การใช้งานที่ถูกต้อง (โดยนัย)

Enum XrTrackableMarkerDictionaryANDROID อธิบายพจนานุกรมตัวทำเครื่องหมายที่รองรับ

typedef enum XrTrackableMarkerDictionaryANDROID {
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID = 0,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_100_ANDROID = 1,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_250_ANDROID = 2,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_1000_ANDROID = 3,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_50_ANDROID = 4,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_100_ANDROID = 5,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_250_ANDROID = 6,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_5X5_1000_ANDROID = 7,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_50_ANDROID = 8,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_100_ANDROID = 9,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_250_ANDROID = 10,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_6X6_1000_ANDROID = 11,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_50_ANDROID = 12,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_100_ANDROID = 13,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_250_ANDROID = 14,
    XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_7X7_1000_ANDROID = 15,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_16H5_ANDROID = 16,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_25H9_ANDROID = 17,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H10_ANDROID = 18,
    XR_TRACKABLE_MARKER_DICTIONARY_APRILTAG_36H11_ANDROID = 19,
    XR_TRACKABLE_MARKER_DICTIONARY_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrTrackableMarkerDictionaryANDROID;

โครงสร้าง XrTrackableMarkerDatabaseEntryANDROID กำหนดค่ารหัสเครื่องหมายเดียวของพจนานุกรม

typedef struct XrTrackableMarkerDatabaseEntryANDROID {
    int32_t    id;
    float      edgeSize;
} XrTrackableMarkerDatabaseEntryANDROID;

คำอธิบายสมาชิก

  • id คือรหัสเครื่องหมายตามที่ระบุไว้ในพจนานุกรม
  • edgeSize แสดงขนาดของขอบเครื่องหมายเป็นเมตร หากรันไทม์รองรับการประมาณขนาดเครื่องหมาย แอปพลิเคชันสามารถ ตั้งค่านี้เป็น 0 และระบบจะประมาณขนาดเครื่องหมายแบบออนไลน์ หากตั้งค่านี้เป็น 0 แต่รันไทม์ไม่รองรับการประมาณขนาดตัวทำเครื่องหมาย รันไทม์ต้อง แสดงผล XR_ERROR_VALIDATION_FAILURE

การใช้งานที่ถูกต้อง (โดยนัย)

รับเครื่องหมาย

ฟังก์ชัน xrGetTrackableMarkerANDROID กำหนดไว้ดังนี้

XrResult xrGetTrackableMarkerANDROID(
    XrTrackableTrackerANDROID                   tracker,
    const XrTrackableGetInfoANDROID*            getInfo,
    XrTrackableMarkerANDROID*                   markerOutput);

คำอธิบายพารามิเตอร์

  • tracker คือ XrTrackableTrackerANDROID ที่จะค้นหา
  • getInfo คือ XrTrackableGetInfoANDROID ที่มีข้อมูลที่ใช้ในการรับเครื่องหมายที่ติดตามได้
  • markerOutput คือตัวชี้ไปยังโครงสร้าง XrTrackableMarkerANDROID ที่จะแสดงผลเครื่องหมายที่ติดตามได้

รันไทม์ต้อง แสดงผล XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID หากประเภทที่ติดตามได้ของ XrTrackableANDROID ไม่ใช่ XR_TRACKABLE_TYPE_MARKER_ANDROID หรือหากประเภทที่ติดตามได้ของ XrTrackableTrackerANDROID ไม่ใช่ XR_TRACKABLE_TYPE_MARKER_ANDROID

การใช้งานที่ถูกต้อง (โดยนัย)

  • ต้องเปิดใช้ส่วนขยาย XR_ANDROID_trackables_marker ก่อน จึงจะเรียกใช้ xrGetTrackableMarkerANDROID ได้
  • tracker ต้อง เป็นแฮนเดิล XrTrackableTrackerANDROID ที่ถูกต้อง
  • getInfo ต้อง เป็นตัวชี้ไปยังโครงสร้าง XrTrackableGetInfoANDROID ที่ถูกต้อง
  • markerOutput ต้อง เป็นตัวชี้ไปยังโครงสร้าง XrTrackableMarkerANDROID

รหัสแสดงผล

สำเร็จ

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

ความล้มเหลว

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_MISMATCHING_TRACKABLE_TYPE_ANDROID
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

โครงสร้าง XrTrackableMarkerANDROID กำหนดไว้ดังนี้

typedef struct XrTrackableMarkerANDROID {
    XrStructureType                       type;
    void*                                 next;
    XrTrackingStateANDROID                trackingState;
    XrTime                                lastUpdatedTime;
    XrTrackableMarkerDictionaryANDROID    dictionary;
    int32_t                               markerId;
    XrPosef                               centerPose;
    XrExtent2Df                           extents;
} XrTrackableMarkerANDROID;

คำอธิบายสมาชิก

  • type คือ XrStructureType ของโครงสร้างนี้
  • next คือ NULL หรือ Pointer ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีโครงสร้างดังกล่าวที่กำหนดไว้ใน OpenXR หลักหรือส่วนขยายนี้
  • trackingState คือ XrTrackingStateANDROID ของตัวทำเครื่องหมาย
  • lastUpdatedTime คือ XrTime ของการอัปเดตเครื่องหมายครั้งล่าสุด
  • dictionary คือ XrTrackableMarkerDictionaryANDROID ของตัวทำเครื่องหมาย
  • markerId คือรหัสเครื่องหมายตามที่ระบุไว้ในพจนานุกรม
  • centerPose คือ XrPosef ของเครื่องหมายที่อยู่ใน XrTrackableGetInfoANDROID :: baseSpace ตัวทำเครื่องหมายจะอยู่ในระนาบ XZ โดย X ชี้ไปทางขวาของตัวทำเครื่องหมายและ Z ชี้ไปทางด้านล่างของตัวทำเครื่องหมาย ส่วน Y จะออกมาจากตัวทำเครื่องหมายเป็นปกติ
  • extents คือขนาด XrExtent2Df ของเครื่องหมาย ขอบเขตของกรอบล้อมรอบอยู่ที่จุด centerPose +/- ( extents / 2)

การใช้งานที่ถูกต้อง (โดยนัย)

โค้ดตัวอย่างสำหรับการรับเครื่องหมายที่ติดตามได้

โค้ดตัวอย่างต่อไปนี้แสดงวิธีรับเครื่องหมายที่ติดตามได้

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session;   // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrGetSystemProperties xrGetSystemProperties;                       // previously initialized
PFN_xrCreateTrackableTrackerANDROID xrCreateTrackableTrackerANDROID;   // previously initialized
PFN_xrGetAllTrackablesANDROID xrGetAllTrackablesANDROID;               // previously initialized
PFN_xrGetTrackableMarkerANDROID xrGetTrackableMarkerANDROID;           // previously initialized
PFN_xrDestroyTrackableTrackerANDROID xrDestroyTrackableTrackerANDROID; // previously initialized

XrTime updateTime; // Time used for the current frame's simulation update.
XrSpace appSpace;  // Space created for XR_REFERENCE_SPACE_TYPE_LOCAL.

// Inspect system capability
XrSystemMarkerTrackingPropertiesANDROID markerProperty {
  .type = XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID,
  .next = nullptr,
};
XrSystemProperties systemProperties {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &markerProperty,
};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!markerProperty.supportsMarkerTracking) {
    // Marker tracking is not supported.
    return;
}

// Create a trackable tracker for marker tracking.
// If the runtime does not support size estimation, configures marker edge size of 0.1m.
XrTrackableMarkerDatabaseEntryANDROID markerEntries {
  .id = 0,
  .edgeSize = markerProperty.supportsMarkerSizeEstimation ? 0.0f : 0.1f,
};
XrTrackableMarkerDatabaseANDROID markerDatabases {
  .dictionary = XR_TRACKABLE_MARKER_DICTIONARY_ARUCO_4X4_50_ANDROID,
  .entryCount = 1,
  .entries = &markerEntries,
};
XrTrackableMarkerConfigurationANDROID configuration {
  .type = XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID,
  .next = nullptr,
  .trackingMode = XR_TRACKABLE_MARKER_TRACKING_MODE_DYNAMIC_ANDROID,
  .databaseCount = 1,
  .databases = &markerDatabases,
};
XrTrackableTrackerCreateInfoANDROID createInfo {
  .type = XR_TYPE_TRACKABLE_TRACKER_CREATE_INFO_ANDROID,
  .next = &configuration,
  .trackableType = XR_TRACKABLE_TYPE_MARKER_ANDROID,
};
XrTrackableTrackerANDROID markerTracker;
auto res = xrCreateTrackableTrackerANDROID(session, &createInfo, &markerTracker);
if (res == XR_ERROR_PERMISSION_INSUFFICIENT) {
    // Handle permission requests.
}
CHK_XR(res);

// Get markers.
std::vector<XrTrackableANDROID> trackables(markerProperty.maxMarkerCount);
std::vector<XrTrackableMarkerANDROID> markers(markerProperty.maxMarkerCount, {
  .type = XR_TYPE_TRACKABLE_MARKER_ANDROID,
  .next = nullptr,
});
uint32_t markerSize = 0;
CHK_XR(xrGetAllTrackablesANDROID(markerTracker, markerProperty.maxMarkerCount, &markerSize,
                                 trackables.data()));
for (int i = 0; i < markerSize; i++) {
    XrTrackableGetInfoANDROID getInfo {
      .type = XR_TYPE_TRACKABLE_GET_INFO_ANDROID,
      .next = nullptr,
      .trackable = trackables[i],
      .baseSpace = appSpace,
      .time = updateTime,
    };
    CHK_XR(xrGetTrackableMarkerANDROID(markerTracker, &getInfo, &markers[i]));
    // Handle markers.
}

// Release trackable tracker.
CHK_XR(xrDestroyTrackableTrackerANDROID(markerTracker));

คำสั่งใหม่

โครงสร้างใหม่

Enum ใหม่

ค่าคงที่ Enum ใหม่

  • XR_ANDROID_TRACKABLES_MARKER_EXTENSION_NAME
  • XR_ANDROID_trackables_marker_SPEC_VERSION

  • การขยาย XrStructureType :

    • XR_TYPE_SYSTEM_MARKER_TRACKING_PROPERTIES_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_ANDROID
    • XR_TYPE_TRACKABLE_MARKER_CONFIGURATION_ANDROID

  • การขยาย XrTrackableTypeANDROID :

    • XR_TRACKABLE_TYPE_MARKER_ANDROID

ปัญหา

ประวัติเวอร์ชัน

  • การแก้ไข 1, 2025-07-23 (Levana Chen)

    • คำอธิบายส่วนขยายเริ่มต้น