إضافة XR_ANDROID_hand_mesh OpenXR

سلسلة الاسم

XR_ANDROID_hand_mesh

نوع الإضافة

إضافة مثيل

رقم الإضافة المسجَّل

704

المراجعة

1

التبعيات المتعلّقة بالإصدارات والإضافات

OpenXR 1.0

تاريخ آخر تعديل

2024-09-10

حالة عنوان IP

ما مِن مطالبات معروفة بعناوين IP.

المساهمون

نيهاف جاين، Google

"كايرن أوفرتوف"، Google

سبنسر كوين، Google

ليفانا تشين، من Google

نظرة عامة

تتيح هذه الإضافة ميزة "تتبُّع اليد" التي يتم تمثيلها على شكل شبكة يد ديناميكية.

تهدف هذه الإضافة إلى توفير وحدات تخزين قمة وفهرسة لشبكة تمثيل مخصّص لأيادي المستخدم. يمكن استخدامها لتحديد المرئيات وتحديد العوائق.

يجب عدم استخدام هذه الإضافة لأغراض أخرى تتضمّن تتبُّع اليد.

يمكن أن تكون بيانات تتبُّع اليد معلومات شخصية حسّاسة وترتبط بشكل وثيق بالخصوصية الشخصية والنزاهة. ننصح بشدة بأن تطلب التطبيقات التي تخزِّن بيانات تتبُّع اليد أو تنقلها من المستخدم دائمًا الموافقة الواضحة والنشطة على ذلك.

فحص قدرة النظام

يمكن للتطبيق التحقّق مما إذا كان النظام قادرًا على تتبُّع تضاريس يد المستخدمين من خلال ربط بنية XrSystemHandMeshTrackingPropertiesANDROID بـ XrSystemProperties عند استدعاء xrGetSystemProperties.

typedef struct XrSystemHandMeshTrackingPropertiesANDROID {
  XrStructureType    type;
  void*              next;
  XrBool32           supportsHandMeshTracking;
  XrBool32           supportsTextureUV;
  XrBool32           supportsVertexNormal;
} XrSystemHandMeshTrackingPropertiesANDROID;

أوصاف الأعضاء

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.
  • supportsHandMeshTracking هو XrBool32، ويشير إلى ما إذا كان جهاز XrSystemId المحدّد يتيح تتبُّع شبكة اليد.
  • supportsTextureUV هو XrBool32، ويشير إلى ما إذا كان ملف XrSystemId المحدّد يتيح استخدام إحداثيات UV للنسيج في رؤوس الشبكة.
  • supportsVertexNormal هو XrBool32، ويشير إلى ما إذا كان ملف XrSystemId المحدّد يتيح استخدام اتجاهات رؤوس الشبكة لرؤوس الشبكة.

يجب أن يتجنب التطبيق استخدام إمكانات شبكة اليد عندما يكون supportsHandMeshTracking‏ = XR_FALSE، لأنّ هذا يعني أنّ النظام لا يسمح بتتبُّع شبكة اليد. في هذه الحالة، ستعرض xrCreateHandMeshTrackerANDROID القيمة XR_ERROR_FEATURE_UNSUPPORTED.

إذا كانت قيمة supportsHandMeshTracking هي XR_TRUE، يعني ذلك أنّ النظام يتوافق مع ميزة "تتبُّع شبكة اليد". يجب أن يستخدم التطبيق XrHandMeshANDROID::indexCount وXrHandMeshANDROID::vertexCount ل الوصول إلى مخازن توفُّر شبكة اليد وإعادة استخدامها في حلقة التقديم عند استدعاء xrGetHandMeshANDROID في كل إطار.

إذا كانت دالة supportsTextureUV تعرض القيمة XR_FALSE، يعني ذلك أنّ النظام لا يسمح باستخدام XrHandMeshANDROID::textureUVs NULL عند استدعاء دالة xrGetHandMeshANDROID.

إذا عرضت الدالة supportsVertexNormal القيمة XR_FALSE، يعني ذلك أنّ النظام لا يسمح باستخدام اتجاهات رؤوس الشبكة، وبالتالي سيتلقّى التطبيق XrHandMeshANDROID::normals NULL عند استدعاء xrGetHandMeshANDROID.

الاستخدام الصالح (ضمني)

إنشاء اسم معرِّف لجهاز التتبُّع اليدوي

XR_DEFINE_HANDLE(XrHandMeshTrackerANDROID)

يمثّل المعرّف XrHandMeshTrackerANDROID أداة تتبُّع شبكة اليد لتتبُّع شبكة اليد وإدارة الموارد ذات الصلة.

يمكن استخدام هذا المعرّف للوصول إلى مخازن مصفوفة اليد باستخدام دوال أخرى في هذه الإضافة.

يمكن للتطبيق إنشاء معرّف XrHandMeshTrackerANDROID باستخدام الدالة xrCreateHandMeshTrackerANDROID. 

XrResult xrCreateHandMeshTrackerANDROID(
    XrSession                                   session,
    const XrHandMeshTrackerCreateInfoANDROID*   createInfo,
    XrHandMeshTrackerANDROID*                   handMeshTracker);

أوصاف المَعلمات

إذا كان النظام لا يتيح تتبُّع شبكة اليد، ستُعرِض دالة xrCreateHandMeshTrackerANDROID القيمة XR_ERROR_FEATURE_UNSUPPORTED.

يملك الاسم المعرِّف XrHandMeshTrackerANDROID جميع الموارد اللازمة لتتبُّع شبكة اليدين. بعد الانتهاء من تجارب تتبُّع شبكة اليد، يجب أن يُبطل التطبيق العنصر باستخدام الدالة xrDestroyHandMeshTrackerANDROID.

الاستخدام الصالح (ضمني)

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر الإجراء

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_LIMIT_REACHED

تصف بنية XrHandMeshTrackerCreateInfoANDROID المعلومات اللازمة لإنشاء معرّف XrHandMeshTrackerANDROID. 

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

أوصاف الأعضاء

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.

الاستخدام الصالح (ضمني)

تُطلق الدالة xrDestroyHandMeshTrackerANDROID handMeshTracker والموارد الأساسية عند الانتهاء من تجارب تتبُّع شبكة اليد. 

XrResult xrDestroyHandMeshTrackerANDROID(
    XrHandMeshTrackerANDROID handMeshTracker);

أوصاف المَعلمات

الاستخدام الصالح (ضمني)

أمان سلسلة المحادثات

  • يجب أن تتم معالجة الوصول إلى handMeshTracker وأيّ أسماء معرِّفة فرعية بشكل خارجي.

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS

تعذُّر الإجراء

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

تحديد موقع شبكات الأيدي

يمكن للتطبيق استخدام الدالة xrGetHandMeshANDROID لاسترداد شبكة اليد في طابع زمني معيّن. يتم تمثيل موضع رؤوس شبكة اليد ومقدار الميل في المساحة المحدّدة من قِبل XrHandMeshGetInfoANDROID::baseSpace عند استدعاء xrGetHandMeshANDROID.

XrResult xrGetHandMeshANDROID(
    XrHandMeshTrackerANDROID                    handMeshTracker,
    const XrHandMeshGetInfoANDROID*             getInfo,
    XrHandTrackingMeshesANDROID*                handMeshes);

أوصاف المَعلمات

يمكن للتطبيق استخدام الدالة xrGetHandMeshANDROID للوصول إلى ملفّات 缓冲ه mesh يدوية التي أنشأها وقت التشغيل.

يجب أن يستدعي التطبيق xrBeginFrame مرة واحدة على الأقل أثناء الجلسة قبل أول استدعاء xrGetHandMeshANDROID.

يجب أن يستخدم التطبيق XrHandMeshANDROID::indexCount و XrHandMeshANDROID::vertexCount للوصول إلى مخازن توفُّر شبكة اليد وإعادة استخدامها في حلقة التقديم عند استدعاء xrGetHandMeshANDROID في كل إطار.

الاستخدام الصالح (ضمني)

رموز الإرجاع

تم بنجاح

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

تعذُّر الإجراء

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_TIME_INVALID

يصف XrHandMeshGetInfoANDROID المعلومات المطلوبة للحصول على بيانات الشبكات المتداخلة. 

typedef struct XrHandMeshGetInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
} XrHandMeshGetInfoANDROID;

أوصاف الأعضاء

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.
  • baseSpace هو XrSpace يحدِّد المساحة المرجعية التي يتم فيها تحديد موقع التحويل للرؤوس في time.
  • time هو XrTime الذي يصف الوقت الذي يريد فيه التطبيق طلب البحث عن شبكة اليد.

الاستخدام الصالح (ضمني)

تحتوي بنية XrHandTrackingMeshesANDROID على بيانات الشبكة لكلتا اليدين. 

typedef struct XrHandTrackingMeshesANDROID {
    XrStructureType      type;
    void*                next;
    XrHandMeshANDROID    leftHandMesh;
    XrHandMeshANDROID    rightHandMesh;
} XrHandTrackingMeshesANDROID;

أوصاف الأعضاء

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.
  • leftHandMesh هو XrHandMeshANDROID لليد اليسرى.
  • rightHandMesh هو XrHandMeshANDROID لليد اليمنى.

الاستخدام الصالح (ضمني)

تحتوي بنية XrHandMeshANDROID على بيانات ومساحات تخزين مؤقتة لتلقّي بيانات تتبُّع شبكة اليد من الدالة xrGetHandMeshANDROID لأحد اليدين.

typedef struct XrHandMeshANDROID {
    XrBool32             isActive;
    XrTime               dynamicLastUpdateTime;
    uint32_t             indexCount;
    uint32_t             vertexCount;
    const uint32_t*      indices;
    const XrVector2f*    textureUVs;
    const XrVector3f*    positions;
    const XrVector3f*    normals;
    XrPosef              baseSpaceFromVertexSpace;
} XrHandMeshANDROID;

أوصاف الأعضاء

  • type هو XrStructureType لهذه البنية.
  • next هو NULL أو مؤشر إلى البنية التالية في سلسلة البنية. لا يتم تعريف مثل هذه الهياكل في OpenXR الأساسية أو هذه الإضافة.
  • isActive هو XrBool32 يشير إلى ما إذا كان جهاز التتبُّع الحالي لشبكة اليد نشطًا وبيانات الشبكة صالحة.
  • dynamicLastUpdateTime هو XrTime الذي يحدّد الوقت الذي تم فيه تعديل ملفّات التخزين المؤقتالديناميكية آخر مرة.
  • indexCount هو uint32_t يمثّل عدد indices لشبكة اليد.
  • ‫vertexCount هو uint32_t يمثّل عدد positions لشبكة اليد. يمكن أيضًا استخدامها مع textureUVs أو normals عندما يكونان متوافقَين مع النظام.
  • indices هي صفيف من uint32_t يمثّل فهارس الشبكة للمثلثات في ترتيب لفات عكس عقارب الساعة. عدد القيم المشار إليها هو indexCount.
  • textureUVs هو NULL أو صفيف من XrVector2f يمثّل إحداثيات الملمس للرأس. عدد القيم التي يتمّ الإشارة إليها هو vertexCount.
  • positions هي صفيف من XrVector3f يمثّل مواضع الرؤوس في baseSpaceFromVertexSpace. عدد القيم التي يتمّ الإشارة إليها هو vertexCount.
  • normals هو NULL أو صفيف من XrVector3f يمثّل اتجاهات baseSpaceFromVertexSpace في baseSpaceFromVertexSpace. عدد القيم التي يتم الإشارة إليها هو vertexCount.
  • baseSpaceFromVertexSpace هو رأس XrSpace في XrHandMeshGetInfoANDROID::baseSpace عند استدعاء xrGetHandMeshANDROID. يمكن للتطبيقات استخدام هذا الإجراء لتحويل مساحة التنسيقات لرؤوس الشبكة والعناصر العادية أثناء العرض.

يتم تمثيل شبكة اليد في قوائم المثلثات، وتكون رؤوس كل مثلث بترتيب عكس عقارب الساعة عند النظر من خارج اليد.

عندما تكون قيمة isActive المعروضة هي XR_FALSE، يعني ذلك أنّه تتم متابعة اليد بشكل غير نشط، على سبيل المثال، تكون اليد خارج نطاق أداة الاستشعار، أو تتم إزالة تركيز الإدخال من التطبيق، أو لا يملك التطبيق الأذونات اللازمة للوصول إلى بيانات تتبُّع اليد.

عندما تكون قيمة isActive المعروضة هي XR_TRUE، يتم تعديل شبكة تتبُّع اليد الممثّلة في indices وpositions، بما في ذلك textureUVs وnormals إذا كانا متوافقَين مع النظام، لتتضمّن أحدث البيانات الخاصة بالملف الشخصي XrHandMeshGetInfoANDROID::time الذي تم تقديمه إلى الدالة xrGetHandMeshANDROID.

إنّ الذاكرة التي تشير إليها ذاكرات التخزين المؤقت للشبكات اليدوية التي يتم عرضها في XrHandMeshANDROID هي ملكية وقت التشغيل ومشترَكة مع التطبيق. يمكن الوصول إلى الذاكرة بأمان من أي سلسلة محادثات إلى أن يتم إجراء الطلب التالي إلى xrBeginFrame عندما يكون معرّف XrHandMeshTrackerANDROID صالحًا.

  • القيم التي تشير إليها indices وtextureUVs ليست ديناميكية
  • المؤشر والقيم التي يشير إليها positions وnormals ديناميكية قد تتغيّر بين طلبات xrBeginFrame. يمكن للتطبيق استخدام dynamicLastUpdateTime للتحقّق مما إذا كانت القيم قد تغيّرت منذ اللقطة الأخيرة وتجنُّب معالجة البيانات غير الضرورية في حال عدم حدوث أي تغييرات.

الاستخدام الصالح (ضمني)

  • يجب تفعيل إضافة XR_ANDROID_hand_mesh قبل استخدام XrHandMeshANDROID.
  • indices يجب أن يكون مؤشرًا إلى قيمة uint32_t صالحة.
  • textureUVs يجب أن يكون مؤشرًا إلى بنية XrVector2f صالحة.
  • positions يجب أن يكون مؤشرًا إلى بنية XrVector3f صالحة
  • normals يجب أن يكون مؤشرًا إلى بنية XrVector3f صالحة

مثال على رمز تتبُّع شبكة اليد

يوضّح المثال التالي للرمز البرمجي كيفية الوصول إلى مخازن توفُّر شبكة اليد لعمليات المعالجة.

XrInstance instance;  // Created at app startup
XrSystemId systemId;  // Received from xrGetSystem() at app startup
XrSession session;    // Created at app startup.
XrSpace appPlaySpace; // Created at app startup.

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreateHandMeshTrackerANDROID xrCreateHandMeshTrackerANDROID; // previously initialized
PFN_xrDestroyHandMeshTrackerANDROID xrDestroyHandMeshTrackerANDROID; // previously initialized
PFN_xrGetHandMeshANDROID xrGetHandMeshANDROID; // previously initialized

// Inspect system capability
XrSystemHandMeshTrackingPropertiesANDROID handMeshTrackingProps = {
  .type = XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &handMeshTrackingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!handMeshTrackingProps.supportsHandMeshTracking) {
  // hand mesh tracking is not supported.
  return;
}

XrHandMeshTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
};
XrHandMeshTrackerANDROID handMeshTracker = XR_NULL_HANDLE;
CHK_XR(xrCreateHandMeshTrackerANDROID(
    session, &trackerCreateInfo, &handMeshTracker));
// app update loop
while (true) {
    // ...
    // For every frame in frame loop
    // ...

    XrFrameState frameState;  // previously returned from xrWaitFrame
    const XrTime time = frameState.predictedDisplayTime;

    // ...
    XrHandMeshGetInfoANDROID getInfo = {
        .type = XR_TYPE_HAND_MESH_GET_INFO_ANDROID,
        .baseSpace = appPlaySpace,
        .time = time,
    };
    XrHandTrackingMeshesANDROID handMeshes = {
        .type = XR_TYPE_HAND_TRACKING_MESHES_ANDROID
    };
    CHK_XR(xrGetHandMeshANDROID(handMeshTracker, &getInfo, &handMeshes));

    if (handMeshes.leftHandMesh.isActive) {
        // access vertex/index buffers for rendering.
    }

    // ...
    // Finish frame loop
    // ...
}

CHECK_XR(xrDestroyHandMeshTracker(handMeshTracker));

أنواع العناصر الجديدة

ثوابت قائمة التعداد الجديدة

تم توسيع قائمة XrObjectType بإضافة ما يلي:

  • XR_OBJECT_TYPE_HAND_MESH_TRACKER_ANDROID

تمّت إضافة ما يلي إلى التعداد XrStructureType:

  • XR_TYPE_SYSTEM_HAND_MESH_TRACKING_PROPERTIES_ANDROID
  • XR_TYPE_HAND_MESH_TRACKER_CREATE_INFO_ANDROID
  • XR_TYPE_HAND_MESH_GET_INFO_ANDROID
  • XR_TYPE_HAND_TRACKING_MESHES_ANDROID

عمليات التعداد الجديدة

التصاميم الجديدة

الدوالّ الجديدة

المشاكل

سجلّ الإصدارات

  • المراجعة 1، ‎10-09-2024 (ليفانا تشين)
    • الوصف الأولي للإضافة