مش‌بندی صحنه XR_ANDROID

رشته نام

XR_ANDROID_scene_meshing

نوع افزونه

افزونه نمونه

شماره داخلی ثبت شده

719

بازنگری

۳

وضعیت تصویب

تصویب نشده

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

اوپن‌ایکس‌آر ۱.۰

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

۲۰۲۵-۰۵-۱۵

وضعیت آی‌پی

هیچ ادعای مالکیت معنوی شناخته‌شده‌ای وجود ندارد.

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

اسپنسر کوئین، گوگل
جارد فایندر، گوگل
آنتونیو فونتان، گوگل
کایرن اوورترف، گوگل
نیهاو جین، گوگل
سالار خان، گوگل
سباستین کلوزه، گوگل
یورگن اشتورم، گوگل
وینی داسیلوا، گوگل
ریکاردو کمپبل، گوگل

نمای کلی

این افزونه برای ارائه شبکه‌هایی در نظر گرفته شده است که تقریباً نمایانگر اشیاء فیزیکی در محیط کاربر هستند.

برنامه‌ها می‌توانند از این افزونه برای تجسم صحنه و ایجاد تعامل اشیاء مجازی با اشیاء فیزیکی مانند برخوردها استفاده کنند.

داده‌های مش صحنه توسط زمان اجرا تولید شده و با استفاده از XrSceneMeshingTrackerANDROID و XrSceneMeshSnapshotANDROID با برنامه به اشتراک گذاشته می‌شود. برنامه‌ها می‌توانند از طریق XrSceneSubmeshStateANDROID که از xrGetAllSubmeshStatesANDROID برگردانده می‌شود، به مقادیر موجود در اطلاعات زیرمش صحنه دسترسی داشته باشند. برنامه‌ها می‌توانند از طریق XrSceneSubmeshDataANDROID که از xrGetSubmeshDataANDROID برگردانده می‌شود، به مقادیر موجود در داده‌های زیرمش صحنه دسترسی داشته باشند.

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

مجوزها

برنامه‌های اندروید باید مجوز android.permission.SCENE_UNDERSTANDING_FINE را در مانیفست خود داشته باشند. مجوز android.permission.SCENE_UNDERSTANDING_FINE یک مجوز حساس محسوب می‌شود زیرا به زمان اجرا اجازه می‌دهد تا محیط کاربر را مطالعه کند.

برنامه باید در زمان اجرا برای استفاده از این توابع درخواست مجوز کند:

(سطح حفاظت: خطرناک)

بررسی قابلیت سیستم

ساختار XrSystemSceneMeshingPropertiesANDROID به صورت زیر تعریف شده است:

typedef struct XrSystemSceneMeshingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsSceneMeshing;
} XrSystemSceneMeshingPropertiesANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • supportsSceneMeshing یک XrBool32 است که نشان می‌دهد آیا سیستم از مش‌بندی صحنه پشتیبانی می‌کند یا خیر.

یک برنامه می‌تواند با اتصال ساختار XrSystemSceneMeshingPropertiesANDROID به XrSystemProperties هنگام فراخوانی xrGetSystemProperties ، بررسی کند که آیا سیستم قادر به مش‌بندی صحنه است یا خیر.

اگر یک زمان اجرا برای supportsSceneMeshing XR_FALSE را برگرداند، سیستم از مش‌بندی صحنه پشتیبانی نمی‌کند و بنابراین باید XR_ERROR_FEATURE_UNSUPPORTED از xrCreateSceneMeshingTrackerANDROID برگرداند. برنامه باید از استفاده از قابلیت مش‌بندی صحنه هنگامی که supportsSceneMeshing XR_FALSE دارد، خودداری کند.

اگر یک زمان اجرا برای supportsSceneMeshing XR_TRUE را برگرداند، سیستم از مش‌بندی صحنه پشتیبانی می‌کند.

کاربرد معتبر (ضمنی)

شمارش XrSceneMeshSemanticLabelSetANDROID مجموعه‌های برچسب معنایی را برای مش‌بندی صحنه توصیف می‌کند. هر مقدار در این enum نشان‌دهنده enum دیگری است که شامل برچسب‌های معنایی است. برای مثال، مقدار XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID نشان‌دهنده مجموعه XrSceneMeshSemanticLabelANDROID است.

typedef enum XrSceneMeshSemanticLabelSetANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_SET_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelSetANDROID;

مقادیر شمارشی معانی زیر را دارند:

توضیحات شمارشی

XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID

این مجموعه برچسب معنایی نشان‌دهنده‌ی عدم وجود برچسب‌های معنایی است.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID

این مجموعه برچسب معنایی، XrSceneMeshSemanticLabelANDROID را نشان می‌دهد.

تابع xrEnumerateSupportedSemanticLabelSetsANDROID به صورت زیر تعریف شده است:

XrResult xrEnumerateSupportedSemanticLabelSetsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedSemanticLabelSetsInputCapacity,
    uint32_t*                                   supportedSemanticLabelSetsOutputCount,
    XrSceneMeshSemanticLabelSetANDROID*         supportedSemanticLabelSets);

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

  • instance یک XrInstance است که توسط برنامه ایجاد شده است.
  • systemId یک XrSystemId است که از xrGetSystem دوباره امتحان شده است.
  • supportedSemanticLabelSetsInputCapacity ظرفیت supportedSemanticLabelSets است، یا 0 برای بازیابی ظرفیت مورد نیاز.
  • supportedSemanticLabelSetsOutputCount اشاره‌گری به تعداد supportedSemanticLabelSets نوشته شده است، یا اشاره‌گری به ظرفیت مورد نیاز در صورتی که supportedSemanticLabelSetsInputCapacity کافی نباشد.
  • supportedSemanticLabelSets یک اشاره‌گر به آرایه‌ای از XrSceneMeshSemanticLabelSetANDROID است. اگر supportedSemanticLabelSetsInputCapacity برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای شرح مفصلی از بازیابی اندازه مورد نیاز supportedSemanticLabelSets به فصل پارامترهای اندازه بافر مراجعه کنید.

این برنامه می‌تواند مجموعه‌های برچسب معنایی پشتیبانی‌شده توسط سیستم را با استفاده از تابع xrEnumerateSupportedSemanticLabelSetsANDROID فهرست کند.

هر سیستمی باید حداقل از XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID پشتیبانی کند زیرا این مقدار شمارشی هیچ مجموعه برچسب معنایی را نشان نمی‌دهد و می‌تواند در مواردی که برنامه به معنای رأس نیاز ندارد، مورد استفاده قرار گیرد.

کاربرد معتبر (ضمنی)

  • افزونه‌ی XR_ANDROID_scene_meshing باید قبل از فراخوانی xrEnumerateSupportedSemanticLabelSetsANDROID فعال شود.
  • instance باید یک شناسه معتبر XrInstance باشد.
  • supportedSemanticLabelSetsOutputCount باید یک اشاره‌گر به مقدار uint32_t باشد.
  • اگر supportedSemanticLabelSetsInputCapacity برابر با 0 نباشد، supportedSemanticLabelSets باید یک اشاره‌گر به آرایه‌ای از مقادیر supportedSemanticLabelSetsInputCapacity XrSceneMeshSemanticLabelSetANDROID باشد.

کدهای بازگشت

موفقیت

  • XR_SUCCESS

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

ایجاد یک دسته ردیاب مش‌بندی صحنه 

XR_DEFINE_HANDLE(XrSceneMeshingTrackerANDROID)

شناسه XrSceneMeshingTrackerANDROID یک ردیاب مش‌بندی صحنه برای مش‌بندی صحنه و مدیریت منابع مرتبط را نشان می‌دهد.

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

تابع xrCreateSceneMeshingTrackerANDROID به صورت زیر تعریف شده است:

XrResult xrCreateSceneMeshingTrackerANDROID(
    XrSession                                   session,
    const XrSceneMeshingTrackerCreateInfoANDROID* createInfo,
    XrSceneMeshingTrackerANDROID*               tracker);

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

  • session یک XrSession است که در آن ردیاب مش‌بندی صحنه فعال خواهد بود.
  • createInfo یک اشاره‌گر به ساختار XrSceneMeshingTrackerCreateInfoANDROID است که برای توصیف ردیاب مش‌بندی صحنه‌ای که قرار است ایجاد شود، استفاده می‌شود.
  • tracker هندل XrSceneMeshingTrackerANDROID برگردانده شده است.

یک برنامه می‌تواند با استفاده از تابع xrCreateSceneMeshingTrackerANDROID یک هندل XrSceneMeshingTrackerANDROID ایجاد کند.

اگر سیستم از شبکه‌بندی صحنه پشتیبانی نکند، زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED از xrCreateSceneMeshingTrackerANDROID برگرداند. در این حالت، زمان اجرا باید هنگام فراخوانی تابع xrGetSystemProperties XR_FALSE برای XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing برگرداند تا برنامه بتواند از ایجاد ردیاب شبکه‌بندی صحنه جلوگیری کند.

برنامه هنگام ایجاد ردیاب مش‌بندی صحنه، فقط باید از مجموعه برچسب‌های معنایی پشتیبانی‌شده توسط سیستم در XrSceneMeshingTrackerCreateInfoANDROID :: semanticLabelSet استفاده کند. اگر برنامه از یک مجموعه برچسب معنایی رأس مش‌بندی صحنه پشتیبانی‌نشده استفاده کند، زمان اجرا باید XR_ERROR_FEATURE_UNSUPPORTED از xrCreateSceneMeshingTrackerANDROID برگرداند.

برنامه می‌تواند فهرست مجموعه‌های برچسب معنایی پشتیبانی‌شده را با تابع xrEnumerateSupportedSemanticLabelSetsANDROID فهرست کند.

هندل xrCreateSceneMeshingTrackerANDROID تمام منابع لازم برای مش‌بندی صحنه را در اختیار دارد. پس از پایان تجربه مش‌بندی صحنه، برنامه باید هندل را از طریق تابع xrDestroySceneMeshingTrackerANDROID از بین ببرد.

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_FEATURE_UNSUPPORTED
  • 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_VALIDATION_FAILURE

ساختار XrSceneMeshingTrackerCreateInfoANDROID به صورت زیر تعریف شده است:

typedef struct XrSceneMeshingTrackerCreateInfoANDROID {
    XrStructureType                       type;
    const void*                           next;
    XrSceneMeshSemanticLabelSetANDROID    semanticLabelSet;
    XrBool32                              enableNormals;
} XrSceneMeshingTrackerCreateInfoANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • semanticLabelSet یک XrSceneMeshSemanticLabelSetANDROID است که برای تعیین مجموعه برچسب معنایی مورد استفاده برای مش‌بندی صحنه استفاده می‌شود. اگر این مقدار روی XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID تنظیم شده باشد، زمان اجرا فیلد بافر XrSceneSubmeshDataANDROID :: vertexSemantics را نادیده می‌گیرد.
  • enableNormals یک XrBool32 است که برای تعیین اینکه آیا هنگام دریافت داده‌های مش صحنه، نرمال‌های رأس برای رئوس مش در بافر مش صحنه لحاظ شوند یا خیر، استفاده می‌شود.

ساختار XrSceneMeshingTrackerCreateInfoANDROID اطلاعات لازم برای ایجاد یک هندل XrSceneMeshingTrackerANDROID را توصیف می‌کند.

کاربرد معتبر (ضمنی)

تابع xrDestroySceneMeshingTrackerANDROID به صورت زیر تعریف شده است:

XrResult xrDestroySceneMeshingTrackerANDROID(
    XrSceneMeshingTrackerANDROID                tracker);

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

تابع xrDestroySceneMeshingTrackerANDROID پس از اتمام تجربیات مش‌بندی صحنه، tracker و منابع زیربنایی را آزاد می‌کند.

کاربرد معتبر (ضمنی)

ایمنی رزوه

  • دسترسی به tracker و هر گونه کنترل فرزند باید به صورت خارجی هماهنگ شود

کدهای بازگشت

موفقیت

  • XR_SUCCESS

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

ایجاد دسته عکس فوری مش صحنه 

XR_DEFINE_HANDLE(XrSceneMeshSnapshotANDROID)

شناسه XrSceneMeshSnapshotANDROID نشان‌دهنده یک تصویر لحظه‌ای از مش صحنه است. این تصویر لحظه‌ای با استفاده از xrCreateSceneMeshSnapshotANDROID ایجاد می‌شود که در زمان فراخوانی تابع، یک تصویر لحظه‌ای از داده‌های مش صحنه می‌گیرد.

این هندل می‌تواند برای بازیابی اطلاعات و داده‌های submesh با استفاده از xrGetAllSubmeshStatesANDROID و xrGetSubmeshDataANDROID استفاده شود.

تابع xrCreateSceneMeshSnapshotANDROID به صورت زیر تعریف شده است:

XrResult xrCreateSceneMeshSnapshotANDROID(
    XrSceneMeshingTrackerANDROID                tracker,
    const XrSceneMeshSnapshotCreateInfoANDROID* createInfo,
    XrSceneMeshSnapshotCreationResultANDROID*   outSnapshotCreationResult);

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

برنامه می‌تواند از تابع xrCreateSceneMeshSnapshotANDROID برای ایجاد یک تصویر لحظه‌ای از مش صحنه از ردیاب مش صحنه استفاده کند. این تابع یک هندل XrSceneMeshSnapshotANDROID به همراه XrSceneMeshTrackingStateANDROID که در ساختار XrSceneMeshSnapshotCreationResultANDROID قرار گرفته است، برمی‌گرداند. این هندل از نظر فنی یک تصویر لحظه‌ای از داده‌های مش صحنه در زمان ایجاد است. از این هندل می‌توان برای جستجوی اطلاعات و داده‌های مش صحنه به ترتیب با استفاده از xrGetAllSubmeshStatesANDROID و xrGetSubmeshDataANDROID استفاده کرد.

کاربرد معتبر (ضمنی)

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • 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_TIME_INVALID

ساختار XrSceneMeshSnapshotCreateInfoANDROID به صورت زیر تعریف شده است: 

typedef struct XrSceneMeshSnapshotCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            baseSpace;
    XrTime             time;
    XrBoxf             boundingBox;
} XrSceneMeshSnapshotCreateInfoANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • baseSpace یک XrSpace است که اطلاعات مربوط به حالت submesh صحنه در آن نمایش داده می‌شود.
  • time همان XrTime است که زمانی را که مش صحنه پردازش یا نمایش داده می‌شود، توصیف می‌کند و معمولاً XrFrameState :: predictedDisplayTime .
  • boundingBox یک XrBoxf است که کادر مرزی را که مش صحنه در آن قرار می‌گیرد، توصیف می‌کند.

ساختار XrSceneMeshSnapshotCreateInfoANDROID اطلاعات لازم برای ایجاد یک هندل XrSceneMeshSnapshotANDROID را توصیف می‌کند.

کاربرد معتبر (ضمنی)

ساختار XrSceneMeshSnapshotCreationResultANDROID به صورت زیر تعریف شده است: 

typedef struct XrSceneMeshSnapshotCreationResultANDROID {
    XrStructureType                    type;
    const void*                        next;
    XrSceneMeshSnapshotANDROID         snapshot;
    XrSceneMeshTrackingStateANDROID    trackingState;
} XrSceneMeshSnapshotCreationResultANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • snapshot یک هندل XrSceneMeshSnapshotANDROID است که توسط زمان اجرا ایجاد شده است.
  • trackingState یک XrSceneMeshTrackingStateANDROID است که وضعیت ردیاب مش‌بندی صحنه را در زمان ایجاد اسنپ‌شات توصیف می‌کند.

ساختار XrSceneMeshSnapshotCreationResultANDROID نتیجه‌ی ایجاد اسنپ‌شات مش صحنه را که از xrCreateSceneMeshSnapshotANDROID برگردانده شده است، ذخیره می‌کند.

کاربرد معتبر (ضمنی)

شمارش XrSceneMeshTrackingStateANDROID وضعیت ردیابی را برای یک ردیاب مش‌بندی صحنه توصیف می‌کند. هر مقدار در این enum نشان دهنده یک وضعیت از ردیاب مش‌بندی صحنه است. 

typedef enum XrSceneMeshTrackingStateANDROID {
    XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID = 0,
    XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID = 1,
    XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID = 2,
    XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID = 3,
    XR_SCENE_MESH_TRACKING_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshTrackingStateANDROID;

مقادیر شمارشی معانی زیر را دارند:

توضیحات شمارشی

XR_SCENE_MESH_TRACKING_STATE_INITIALIZING_ANDROID

این ردیاب هنوز آماده ارائه داده‌های مش نیست.

XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID

ردیاب به طور فعال در حال ردیابی است.

XR_SCENE_MESH_TRACKING_STATE_WAITING_ANDROID

ردیاب منتظر اندازه‌گیری‌های معتبر برای ادغام از آخرین به‌روزرسانی مش است.

XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID

ردیاب برای چندین چرخه اندازه‌گیری‌های معتبری دریافت نکرده و در حالت خطا قرار دارد.

این وضعیت فقط به عنوان اطلاعات اضافی برای برنامه عمل می‌کند. در غیاب سایر منابع خطا، زمان اجرا باید به برنامه اجازه دهد تا صرف نظر از XrSceneMeshTrackingStateANDROID فعلی ردیاب، اسنپ‌شات ایجاد کرده و داده‌ها را از آنها بازیابی کند. اگر وضعیت XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID نباشد، ممکن است اسنپ‌شات‌ها به‌روز نباشند یا خالی باشند.

دریافت داده‌های مش صحنه از اسنپ‌شات مش صحنه

تابع xrGetAllSubmeshStatesANDROID به صورت زیر تعریف می‌شود: 

XrResult xrGetAllSubmeshStatesANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshStateCapacityInput,
    uint32_t*                                   submeshStateCountOutput,
    XrSceneSubmeshStateANDROID*                 submeshStates);

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

  • snapshot یک شناسه XrSceneMeshSnapshotANDROID است که قبلاً با xrCreateSceneMeshSnapshotANDROID ایجاد شده است.
  • submeshStateCapacityInput ظرفیت submeshStates است، یا برای بازیابی ظرفیت مورد نیاز، 0 است.
  • submeshStateCountOutput اشاره‌گری به تعداد submeshStates نوشته شده یا اشاره‌گری به ظرفیت مورد نیاز در صورتی که submeshStateCapacityInput کافی نباشد، می‌باشد.
  • submeshStates یک اشاره‌گر به آرایه‌ای از ساختارهای XrSceneSubmeshStateANDROID است که در زمان اجرا، وضعیت تمام زیرمش‌ها در مش صحنه را به آن نمایش می‌دهد. اگر submeshStateCapacityInput برابر با ۰ باشد، می‌تواند NULL باشد.
  • برای توضیحات مفصل در مورد بازیابی اندازه submeshStates مورد نیاز، به فصل پارامترهای اندازه بافر مراجعه کنید.

برنامه می‌تواند از تابع xrGetAllSubmeshStatesANDROID برای دریافت وضعیت تمام زیرشبکه‌ها در مش صحنه استفاده کند. این تابع حاوی اطلاعات اولیه‌ای است که به برنامه اجازه می‌دهد زیرشبکه‌هایی را که برای آنها داده می‌خواهد، انتخاب کند.

کاربرد معتبر (ضمنی)

  • افزونه‌ی XR_ANDROID_scene_meshing باید قبل از فراخوانی xrGetAllSubmeshStatesANDROID فعال شود.
  • snapshot باید یک شناسه معتبر XrSceneMeshSnapshotANDROID باشد.
  • submeshStateCountOutput باید یک اشاره‌گر به مقدار uint32_t باشد.
  • اگر submeshStateCapacityInput برابر با 0 نباشد، submeshStates باید اشاره‌گری به آرایه‌ای از ساختارهای submeshStateCapacityInput XrSceneSubmeshStateANDROID باشد.

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

ساختار XrSceneSubmeshStateANDROID به صورت زیر تعریف می‌شود: 

typedef struct XrSceneSubmeshStateANDROID {
    XrStructureType    type;
    void*              next;
    XrUuid             submeshId;
    XrTime             lastUpdatedTime;
    XrPosef            submeshPoseInBaseSpace;
    XrExtent3Df        bounds;
} XrSceneSubmeshStateANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • submeshId یک XrUuid است که زیرمش را مشخص می‌کند.
  • lastUpdatedTime یک XrTime است که نشان دهنده آخرین زمان به‌روزرسانی زیرشبکه است.
  • submeshPoseInBaseSpace یک XrPosef است که نشان دهنده موقعیت زیرمش در فضای پایه مورد استفاده برای ایجاد تصویر لحظه‌ای مش صحنه است. این موقعیت همچنین مرکز کادر محدود کننده زیرمش است.
  • bounds یک XrExtent3Df است که ابعاد کادر مرزی که submesh را در بر می‌گیرد، توصیف می‌کند. این bounds در فضای پایه‌ای که برای ایجاد دسته مش صحنه استفاده شده است، تعریف می‌شود.

زمان اجرا تمام تلاش خود را می‌کند تا submeshId با ناحیه فضای فیزیکی اشغال شده توسط submesh نگاشت کند. زمان‌های اجرا ممکن است در هر زمانی این نگاشت را از دست بدهند و یک UUID جدید به هر زیرمجموعه از زیرمش‌های شناسایی شده اختصاص دهند. به طور خاص، زمان‌های اجرا ملزم به استفاده مجدد از UUIDهای مشابه برای مش‌های مشابه در نمونه‌های بعدی برنامه نیستند.

کاربرد معتبر (ضمنی)

تابع xrGetSubmeshDataANDROID به صورت زیر تعریف می‌شود: 

XrResult xrGetSubmeshDataANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot,
    uint32_t                                    submeshDataCount,
    XrSceneSubmeshDataANDROID*                  inoutSubmeshData);

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

برنامه می‌تواند از تابع xrGetSubmeshDataANDROID برای دریافت دسته‌هایی از زیرمش‌ها یا همه زیرمش‌ها به طور همزمان استفاده کند، این کار با ارسال لیستی از XrSceneSubmeshDataANDROID انجام می‌شود که در آن هر XrSceneSubmeshDataANDROID :: submeshId روی شناسه مربوطه زیرمشی که قرار است بازیابی شود، تنظیم شده است.

شناسه‌ی XrSceneSubmeshDataANDROID :: submeshId باید برای هر عنصر در inoutSubmeshData منحصر به فرد باشد و توسط xrGetAllSubmeshStatesANDROID برای همان snapshot قابل بازیابی باشد. اگر شناسه‌ی submesh نامعتبر باشد یا بیش از یک عنصر در inoutSubmeshData شناسه‌ی submesh یکسانی داشته باشند، آنگاه زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

submeshDataCount باید مساوی یا کمتر از مقداری باشد که توسط xrGetAllSubmeshStatesANDROID :: submeshStateCountOutput برگردانده می‌شود، در غیر این صورت زمان اجرا باید XR_ERROR_VALIDATION_FAILURE برگرداند.

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

کاربرد معتبر (ضمنی)

  • افزونه‌ی XR_ANDROID_scene_meshing باید قبل از فراخوانی xrGetSubmeshDataANDROID فعال شود.
  • snapshot باید یک شناسه معتبر XrSceneMeshSnapshotANDROID باشد.
  • inoutSubmeshData باید یک اشاره‌گر به آرایه‌ای از ساختارهای submeshDataCount XrSceneSubmeshDataANDROID باشد.
  • پارامتر submeshDataCount باید بزرگتر از 0 باشد.

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_VALIDATION_FAILURE

ساختار XrSceneSubmeshDataANDROID به صورت زیر تعریف می‌شود: 

typedef struct XrSceneSubmeshDataANDROID {
    XrStructureType    type;
    const void*        next;
    XrUuid             submeshId;
    uint32_t           vertexCapacityInput;
    uint32_t           vertexCountOutput;
    XrVector3f*        vertexPositions;
    XrVector3f*        vertexNormals;
    uint8_t*           vertexSemantics;
    uint32_t           indexCapacityInput;
    uint32_t           indexCountOutput;
    uint32_t*          indices;
} XrSceneSubmeshDataANDROID;

توضیحات اعضا

  • type نوع XrStructureType این ساختار است.
  • next با NULL یا اشاره‌گری به ساختار بعدی در یک زنجیره ساختار است. چنین ساختارهایی در هسته OpenXR یا این افزونه تعریف نشده‌اند.
  • submeshId یک XrUuid است که زیرمش را مشخص می‌کند.
  • vertexCapacityInput ظرفیت vertexPositions ، vertexNormals و vertexSemantics است، یا برای بازیابی ظرفیت مورد نیاز، مقدار 0 را وارد می‌کنیم.
  • vertexCountOutput اشاره‌گری به تعداد vertexPositions ، vertexNormals و vertexSemantics نوشته شده است، یا اشاره‌گری به ظرفیت مورد نیاز در صورتی که vertexCapacityInput کافی نباشد.
  • vertexPositions آرایه‌ای از XrVector3f است که در زمان اجرا، موقعیت‌های رأس زیرمش را به آن خروجی می‌دهد.
  • vertexNormals آرایه‌ای از XrVector3f است که در زمان اجرا، نرمال‌های راس زیرمش به آن خروجی داده می‌شود. اگر برنامه یک ردیاب با نرمال‌های غیرفعال ایجاد کرده باشد، می‌توان این فیلد را NULL گذاشت.
  • vertexSemantics آرایه‌ای از uint8_t است که زمان اجرا، معنای رأس زیرمش را به آن خروجی می‌دهد. اگر برنامه یک ردیاب با مجموعه برچسب معنایی XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID ایجاد کرده باشد، می‌توان این فیلد را NULL گذاشت.
  • indexCapacityInput ظرفیت indices است، یا برای بازیابی ظرفیت مورد نیاز، 0 است.
  • indexCountOutput اشاره‌گری به تعداد indices نوشته شده یا اشاره‌گری به ظرفیت مورد نیاز در صورتی که vertexCapacityInput کافی نباشد، می‌باشد.
  • indices ‎ آرایه‌ای از uint32_t است که زمان اجرا، شاخص‌های زیرمش را به آن خروجی می‌دهد.
  • برای شرح مفصلی از بازیابی vertexPositions ، vertexNormals ، vertexSemantics و اندازه indices مورد نیاز، به فصل «پارامترهای اندازه بافر» مراجعه کنید.

کاربرد معتبر (ضمنی)

  • افزونه‌ی XR_ANDROID_scene_meshing باید قبل از استفاده از XrSceneSubmeshDataANDROID فعال شود.
  • type باید XR_TYPE_SCENE_SUBMESH_DATA_ANDROID باشد.
  • next باید NULL یا یک اشاره‌گر معتبر به ساختار بعدی در یک زنجیره ساختار باشد.
  • اگر vertexCapacityInput برابر با 0 نباشد، vertexPositions باید اشاره‌گری به آرایه‌ای از ساختارهای vertexCapacityInput XrVector3f باشد.
  • اگر vertexCapacityInput برابر با 0 نباشد، vertexNormals باید اشاره‌گری به آرایه‌ای از ساختارهای vertexCapacityInput XrVector3f باشد.
  • اگر vertexCapacityInput برابر با 0 نباشد، vertexSemantics باید یک اشاره‌گر به آرایه‌ای از مقادیر vertexCapacityInput uint8_t باشد.
  • اگر indexCapacityInput برابر با 0 نباشد، indices باید اشاره‌گری به آرایه‌ای از مقادیر uint32_t indexCapacityInput باشند.

شمارش XrSceneMeshSemanticLabelANDROID مجموعه پیش‌فرض برچسب‌های معنایی است که می‌تواند برای برچسب‌گذاری رئوس مش استفاده شود تا سطح محیط فیزیکی که رأس مش روی آن قرار دارد را توصیف کند. این مجموعه شمارشی با مقدار XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID در XrSceneMeshSemanticLabelSetANDROID نمایش داده می‌شود. 

typedef enum XrSceneMeshSemanticLabelANDROID {
    XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID = 0,
    XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID = 1,
    XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID = 2,
    XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID = 3,
    XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID = 4,
    XR_SCENE_MESH_SEMANTIC_LABEL_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSceneMeshSemanticLabelANDROID;

enum ها معانی زیر را دارند:

توضیحات شمارشی

XR_SCENE_MESH_SEMANTIC_LABEL_OTHER_ANDROID

این برچسب معنایی نشان می‌دهد که عنصر مش مربوطه، یک شیء ناشناخته را نشان می‌دهد.

XR_SCENE_MESH_SEMANTIC_LABEL_FLOOR_ANDROID

این برچسب معنایی نشان می‌دهد که عنصر مش مربوطه، یک طبقه را نشان می‌دهد.

XR_SCENE_MESH_SEMANTIC_LABEL_CEILING_ANDROID

این برچسب معنایی نشان می‌دهد که عنصر مش مربوطه، یک سقف را نشان می‌دهد.

XR_SCENE_MESH_SEMANTIC_LABEL_WALL_ANDROID

این برچسب معنایی نشان می‌دهد که عنصر مش مربوطه، یک دیوار را نشان می‌دهد.

XR_SCENE_MESH_SEMANTIC_LABEL_TABLE_ANDROID

این برچسب معنایی نشان می‌دهد که عنصر مش مربوطه، یک جدول را نشان می‌دهد.

یک عکس فوری از مش صحنه را از بین ببرید

تابع xrDestroySceneMeshSnapshotANDROID به صورت زیر تعریف شده است: 

XrResult xrDestroySceneMeshSnapshotANDROID(
    XrSceneMeshSnapshotANDROID                  snapshot);

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

برنامه می‌تواند از تابع xrDestroySceneMeshSnapshotANDROID برای از بین بردن یک snapshot مش صحنه استفاده کند. پس از از بین رفتن handle، برنامه دیگر نمی‌تواند از آن برای دریافت اطلاعات یا داده‌های submesh استفاده کند. handle به طور خودکار با از بین رفتن tracker از بین می‌رود زیرا handle ردیاب، والد handle snapshot مش صحنه است.

کاربرد معتبر (ضمنی)

ایمنی رزوه

  • دسترسی به snapshot و هر دسته فرزندی باید به صورت خارجی هماهنگ‌سازی شود.

کدهای بازگشت

موفقیت

  • XR_SUCCESS

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_RUNTIME_FAILURE

کد نمونه برای مش‌بندی صحنه

کد نمونه زیر نحوه دسترسی به داده‌های مش صحنه برای رندرینگ را نشان می‌دهد. 

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_xrCreateSceneMeshingTrackerANDROID xrCreateSceneMeshingTrackerANDROID;
PFN_xrDestroySceneMeshingTrackerANDROID xrDestroySceneMeshingTrackerANDROID;
PFN_xrEnumerateSupportedSemanticLabelSetsANDROID xrEnumerateSupportedSemanticLabelSetsANDROID;
PFN_xrCreateSceneMeshSnapshotANDROID xrCreateSceneMeshSnapshotANDROID;
PFN_xrDestroySceneMeshSnapshotANDROID xrDestroySceneMeshSnapshotANDROID;
PFN_xrGetAllSubmeshStatesANDROID xrGetAllSubmeshStatesANDROID;
PFN_xrGetSubmeshDataANDROID xrGetSubmeshDataANDROID;

// Inspect system capability
XrSystemSceneMeshingPropertiesANDROID sceneMeshingProps = {
  .type = XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID,
};
XrSystemProperties sysProps = {
  .type = XR_TYPE_SYSTEM_PROPERTIES,
  .next = &sceneMeshingProps
};
CHK_XR(xrGetSystemProperties(instance, systemId, &sysProps));
if (!sceneMeshingProps.supportsSceneMeshing) {
    // scene meshing is not supported.
    return;
}

uint32_t supportedsemanticLabelSetsCount = 0;
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, 0, &supportedsemanticLabelSetsCount, nullptr);
std::vector<XrSceneMeshSemanticLabelSetANDROID> supportedSemanticLabelSets(
  supportedsemanticLabelSetsCount);
xrEnumerateSupportedSemanticLabelSetsANDROID(
  instance, systemId, supportedsemanticLabelSetsCount,
  &supportedsemanticLabelSetsCount, supportedSemanticLabelSets.data());

XrSceneMeshSemanticLabelSetANDROID semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID;
// Check if system supports XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID
if (std::find(supportedSemanticLabelSets.begin(), supportedSemanticLabelSets.end(),
              XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID) !=
    supportedSemanticLabelSets.end()) {
  semanticLabelSet = XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT_ANDROID;
}

XrSceneMeshingTrackerCreateInfoANDROID trackerCreateInfo = {
  .type = XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID,
  .semanticLabelSet = semanticLabelSet,
  .enableNormals = XR_TRUE
};

XrSceneMeshingTrackerANDROID tracker = XR_NULL_HANDLE;
CHK_XR(xrCreateSceneMeshingTrackerANDROID(session, &trackerCreateInfo, &tracker));

XrSceneMeshSnapshotCreationResultANDROID snapshotResult {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID,
  .snapshot = XR_NULL_HANDLE
};
XrSceneMeshSnapshotANDROID& snapshot = snapshotResult.snapshot;
XrSceneMeshSnapshotCreateInfoANDROID createInfo {
  .type = XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
};

// app update loop
while (true) {
  // ...
  // For every frame in frame loop
  // ...

  XrFrameState frameState; // previously returned from xrWaitFrame
  const XrTime time = frameState.predictedDisplayTime;
  XrBoxf box; // populated with the bounding box of the camera frustum

  // ...

  createInfo.baseSpace = appPlaySpace;
  createInfo.time = time;
  createInfo.boundingBox = box;

  // Grab the scene mesh snapshot. This way the app can: know all of the submesh infos,
  // choose the appropriate submeshes for which to get data, allocate the necessary
  // buffer for those submeshes, and then get the data.
  CHK_XR(xrCreateSceneMeshSnapshotANDROID(tracker, &createInfo, &snapshotResult));

  // check the tracking state
  if (snapshotResult.trackingState == XR_SCENE_MESH_TRACKING_STATE_ERROR_ANDROID) {
    // unrecoverable error. Exit the app.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    break;
  } else if (snapshotResult.trackingState != XR_SCENE_MESH_TRACKING_STATE_TRACKING_ANDROID) {
    // The tracker is not tracking. Try again later.
    if (snapshot != XR_NULL_HANDLE) {
      CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
      snapshot = XR_NULL_HANDLE;
    }
    continue;
  }

  // 2-call idiom for getting submesh states
  uint32_t submeshCount = 0;
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, 0, &submeshCount, nullptr));
  std::vector<XrSceneSubmeshStateANDROID> states(submeshCount, {
    .type = XR_TYPE_SCENE_SUBMESH_STATE_ANDROID,
  });
  CHK_XR(xrGetAllSubmeshStatesANDROID(snapshot, submeshCount, &submeshCount, states.data()));

  // To store the poses for the selected submeshes
  std::vector<XrPosef> submeshesPoses;
  submeshesPoses.reserve(submeshCount);

  std::vector<XrSceneSubmeshDataANDROID> submeshes;
  submeshes.reserve(submeshCount);
  // Iterate the states and determine which submeshes the app wants data for
  for (XrSceneSubmeshStateANDROID& state : states) {
    // Modify this bool as necessary by looking at states. Maybe state.lastUpdatedTime
    // is below a threshold or maybe the bounding box does not intersect with camera view
    // frustum (The submesh will be culled).
    bool needed;
    if (needed) {
      // Add the selected submesh to the submeshes list. Set the capacity
      // zero for now since the size of the buffer will be determined later.
      XrSceneSubmeshDataANDROID submesh {
        .type = XR_TYPE_SCENE_SUBMESH_DATA_ANDROID,
        .submeshId = state.submeshId,
        .vertexCapacityInput = 0,
        .vertexCountOutput = 0,
        .vertexPositions = nullptr,
        .vertexNormals = nullptr,
        .vertexSemantics = nullptr,
        .indexCapacityInput = 0,
        .indexCountOutput = 0,
        .indices = nullptr,
      };
      submeshes.push_back(submesh);
      submeshesPoses.push_back(state.submeshPoseInBaseSpace);
    }
  }

  // Grab the data for the selected submeshes using the 2-call idiom.
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));
  for (XrSceneSubmeshDataANDROID& submesh : submeshes) {
    submesh.vertexCapacityInput = submesh.vertexCountOutput;
    submesh.vertexCountOutput = 0;
    submesh.vertexPositions = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexNormals = new XrVector3f[submesh.vertexCapacityInput];
    submesh.vertexSemantics = new uint8_t[submesh.vertexCapacityInput];
    submesh.indexCapacityInput = submesh.indexCountOutput;
    submesh.indexCountOutput = 0;
    submesh.indices = new uint32_t[submesh.indexCapacityInput];
  }
  CHK_XR(xrGetSubmeshDataANDROID(snapshot, submeshes.size(), submeshes.data()));

  // Destroy the scene mesh snapshot since we have finally grabbed the submeshes data. In
  // next iteration app can: create a new one to get latest mesh data
  CHK_XR(xrDestroySceneMeshSnapshotANDROID(snapshot));
  snapshot = XR_NULL_HANDLE;

  // Iterate the submeshes and get the vertex positions, vertex normals and
  // vertex semantics data for the selected submeshes
  for (uint32_t i = 0; i < submeshes.size(); i++) {
    XrSceneSubmeshDataANDROID& data = submeshes[i];
    XrVector3f* vertexPositions = data.vertexPositions;
    XrVector3f* vertexNormals = data.vertexNormals;
    XrSceneMeshSemanticLabelANDROID* vertexSemantics =
      new XrSceneMeshSemanticLabelANDROID[data.vertexCountOutput];
    for (uint32_t j = 0; j < data.vertexCountOutput; j++) {
      vertexSemantics[j] =
        static_cast<XrSceneMeshSemanticLabelANDROID>(data.vertexSemantics[j]);
    }
    XrPosef pose = submeshesPoses[i];

    // *** Use the data as per needs ***

    // Release the allocated memory for the data buffers when done using
    delete [] vertexSemantics;
    delete [] data.vertexPositions;
    delete [] data.vertexNormals;
    delete [] data.vertexSemantics;
    delete [] data.indices;
  }

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

CHK_XR(xrDestroySceneMeshingTrackerANDROID(tracker));

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

دستورات جدید

سازه‌های جدید

Enum های جدید

ثابت‌های شمارشی جدید

  • XR_ANDROID_SCENE_MESHING_EXTENSION_NAME
  • XR_ANDROID_scene_meshing_SPEC_VERSION

  • بسط XrObjectType :

    • XR_OBJECT_TYPE_SCENE_MESHING_TRACKER_ANDROID
    • XR_OBJECT_TYPE_SCENE_MESH_SNAPSHOT_ANDROID

  • گسترش XrStructureType :

    • XR_TYPE_SCENE_MESHING_TRACKER_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATE_INFO_ANDROID
    • XR_TYPE_SCENE_MESH_SNAPSHOT_CREATION_RESULT_ANDROID
    • XR_TYPE_SCENE_SUBMESH_DATA_ANDROID
    • XR_TYPE_SCENE_SUBMESH_STATE_ANDROID
    • XR_TYPE_SYSTEM_SCENE_MESHING_PROPERTIES_ANDROID

مسائل

تاریخچه نسخه

  • نسخه ۳، ۲۰۲۵-۰۵-۱۵ (سالار خان)

    • توضیحات اولیه افزونه