افزونه XR_ANDROID_hand_mesh OpenXR

رشته نام

XR_ANDROID_hand_mesh

نوع پسوند

پسوند نمونه

شماره برنامه افزودنی ثبت شده

704

تجدید نظر

1

وابستگی های افزونه و نسخه

OpenXR 1.0

آخرین تاریخ اصلاح

10-09-2024

وضعیت IP

هیچ ادعای IP شناخته شده ای وجود ندارد.

مشارکت کنندگان

نیهاو جین، گوگل

Cairn Overturf، گوگل

اسپنسر کوین، گوگل

لوانا چن، گوگل

نمای کلی

این برنامه افزودنی ردیابی دست را که به صورت یک توری دستی پویا نمایش داده می‌شود، فعال می‌کند.

این برنامه افزودنی برای ارائه بافرهای راس و شاخص برای مش نمایش شخصی دست کاربر در نظر گرفته شده است. می توان از آن برای انسداد و تجسم استفاده کرد.

این برنامه افزودنی نباید برای اهداف دیگر ردیابی دست استفاده شود.

داده‌های ردیابی دستی می‌توانند اطلاعات شخصی حساس باشند و ارتباط نزدیکی با حریم خصوصی و یکپارچگی شخصی دارند. اکیداً توصیه می‌شود که برنامه‌هایی که داده‌های ردیابی دستی را ذخیره یا انتقال می‌دهند همیشه از کاربر درخواست پذیرش فعال و خاص برای انجام این کار را داشته باشند.

قابلیت سیستم را بررسی کنید

هنگام فراخوانی 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 برای دسترسی به بافرهای hand mesh و استفاده مجدد از آنها در حلقه رندر خود هنگام فراخوانی xrGetHandMeshANDROID در هر فریم استفاده کند.

اگر supportsTextureUV XR_FALSE را برمی گرداند، سیستم از بافت UV برای رئوس مش پشتیبانی نمی کند و بنابراین یک برنامه 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 برای بازیابی مش دست در یک زمان مشخص استفاده کند. هنگام فراخوانی xrGetHandMeshANDROID، موقعیت رئوس مش دست و حالت عادی در فضای مشخص شده توسط XrHandMeshGetInfoANDROID::baseSpace نشان داده می شود.

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

توضیحات پارامترها

این برنامه می تواند از تابع xrGetHandMeshANDROID برای دسترسی به بافرهای مش دست تولید شده توسط زمان اجرا استفاده کند.

برنامه باید xrBeginFrame را حداقل یک بار در طول جلسه قبل از اولین تماس با xrGetHandMeshANDROID فراخوانی کند.

یک برنامه باید از XrHandMeshANDROID::indexCount و XrHandMeshANDROID::vertexCount برای دسترسی به بافرهای hand mesh و استفاده مجدد از آنها در حلقه رندر خود هنگام فراخوانی 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 نشان می دهد. تعداد مقادیر اشاره شده vertexCount است.
  • baseSpaceFromVertexSpace راس XrSpace است که در XrHandMeshGetInfoANDROID::baseSpace هنگام فراخوانی xrGetHandMeshANDROID قرار دارد. برنامه ها می توانند از این برای تبدیل فضای مختصات رئوس مش و نرمال ها در طول رندر استفاده کنند.

مش عقربه در لیست های مثلثی نشان داده می شود و رئوس هر مثلث هنگام نگاه کردن از بیرون عقربه به ترتیب خلاف جهت عقربه های ساعت است.

وقتی مقدار isActive برگشتی XR_FALSE باشد، این نشان می‌دهد که عقربه به طور فعال ردیابی نمی‌شود. برای مثال، عقربه خارج از محدوده سنسور است، فوکوس ورودی از برنامه حذف شده است، یا برنامه مجوز دسترسی به داده های ردیابی دست را ندارد.

وقتی مقدار isActive برگشتی XR_TRUE باشد، مش ردیابی دست که در indices و positions نشان داده می‌شود، از جمله textureUVs و normals در صورتی که توسط سیستم پشتیبانی شوند، به آخرین داده‌های XrHandMeshGetInfoANDROID::زمان داده‌شده به تابع xrGetHandMeshANDROID به‌روزرسانی می‌شوند.

حافظه ای که توسط بافرهای مش دستی که در XrHandMeshANDROID به آن اشاره می شود، متعلق به زمان اجرا است و با برنامه به اشتراک گذاشته می شود. تا زمانی که دسته XrHandMeshTrackerANDROID معتبر است، حافظه از هر رشته ای تا تماس بعدی با xrBeginFrame ایمن است.

  • مقادیر اشاره شده توسط 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));

انواع اشیاء جدید

ثابت های جدید Enum

شمارش 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 (لوانا چن)
    • توضیحات پسوند اولیه