XR_ANDROID_trackables_marker

Name String

XR_ANDROID_trackables_marker

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

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

หมายเลขต่อที่ลงทะเบียนไว้

708

การแก้ไข

1

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

ไม่ได้รับการให้สัตยาบัน

ทรัพยากร Dependency ของส่วนขยายและเวอร์ชัน

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 และ AprilTag ซึ่งช่วยให้รันไทม์รองรับการประมาณขนาดเครื่องหมาย (ไม่บังคับ)

สิทธิ์

แอปพลิเคชัน 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 หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน 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 หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง
  • trackingMode คือ XrTrackableMarkerTrackingModeANDROID ที่ระบุโหมดที่ต้องการสำหรับการติดตาม
  • databaseCount คือ uint32_t ที่อธิบายจำนวนองค์ประกอบในอาร์เรย์ databases
  • databases เป็นตัวชี้ไปยังอาร์เรย์ของ 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

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

XrTrackableMarkerTrackingModeANDROID enum อธิบายโหมดการติดตามที่รองรับของมาร์กเกอร์

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 หรือตัวชี้ไปยังโครงสร้างถัดไปในเชนโครงสร้าง ไม่มีการกำหนดโครงสร้างดังกล่าวใน 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

ปัญหา

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

  • Revision 1, 2025-07-23 (Levana Chen)

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