XR_ANDROID_scene_meshing

رشته نام

XR_ANDROID_scene_meshing

نوع افزونه

افزونه نمونه

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

719

بازبینی

3

وضعیت تصویب

تصویب‌نشده

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

OpenXR 1.0

تاریخ آخرین تغییر

2025-05-15

وضعیت IP

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

همیاران

Spencer Quin،‏ Google
Jared Finder،‏ Google
Antonio Fontan،‏ Google
Cairn Overturf،‏ Google
Nihav Jain،‏ Google
Salar Khan،‏ Google
Sebastian Klose،‏ Google
Jürgen Sturm،‏ Google
Vinny DaSilva،‏ Google
Ricardo Campbell،‏ Google

نمای کلی

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

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

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

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

اجازه‌ها

برنامه‌های Android باید اجازه 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، بررسی کند که آیا سیستم قادر به مش‌بندی صحنه است یا نه.

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

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

استفاده معتبر (ضمنی)

شمارش 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_DEFAULT2_ANDROID = 1000801000,
    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 است.

XR_SCENE_MESH_SEMANTIC_LABEL_SET_DEFAULT2_ANDROID

این مجموعه برچسب معنایی نشان‌دهنده XrSceneMeshSemanticLabel2ANDROID است. (افزوده‌شده توسط افزونه XR_ANDROID_scene_meshing_semantic_label2)

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

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

شرح پارامترها

  • ‫instance یک XrInstance است که توسط برنامه ایجاد شده است.
  • systemId یک XrSystemId است که از xrGetSystem دوباره امتحان شده است.
  • ‫supportedSemanticLabelSetsInputCapacity ظرفیت supportedSemanticLabelSets است، یا ۰ برای بازیابی ظرفیت موردنیاز.
  • ‫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 برگرداند. در این حالت، زمان اجرا باید XR_FALSE را برای XrSystemSceneMeshingPropertiesANDROID :: supportsSceneMeshing هنگام فراخوانی تابع xrGetSystemProperties برگرداند تا برنامه بتواند از ایجاد ردیاب مش‌بندی صحنه اجتناب کند.

برنامه باید فقط از مجموعه‌های برچسب معنایی استفاده کند که توسط سیستم در 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 ایجاد می‌شود که عکس آنی از داده‌های مش صحنه را در زمان فراخوانی تابع می‌گیرد.

از این دسته می‌توان برای بازیابی اطلاعات و داده‌های زیرشبکه بااستفاده از 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 است که اطلاعات وضعیت زیرشبکه صحنه در آن نمایش داده می‌شود.
  • 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 است، یا ۰ برای بازیابی ظرفیت موردنیاز.
  • ‫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 است که ابعاد چارگوش مرزی را که زیرشبکه را دربرمی‌گیرد توصیف می‌کند. این مرزها در فضای پایه‌ای تعریف شده است که برای ایجاد دسته مش صحنه استفاده شده است.

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

استفاده معتبر (ضمنی)

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

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

شرح پارامترها

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

XrSceneSubmeshDataANDROID :: submeshId باید برای هر عنصر در inoutSubmeshData منحصربه‌فرد باشد و توسط xrGetAllSubmeshStatesANDROID برای همان snapshot قابل‌بازیابی باشد. اگر شناسه زیرشبکه نامعتبر باشد یا بیش‌از یک عنصر در inoutSubmeshData شناسه زیرشبکه یکسانی داشته باشند، زمان اجرا باید 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 است، یا ۰ برای بازیابی ظرفیت موردنیاز.
  • vertexCountOutput اشاره‌گری به تعداد vertexPositions، vertexNormals، و vertexSemantics نوشته‌شده است، یا اشاره‌گری به ظرفیت موردنیاز درصورتی‌که vertexCapacityInput کافی نباشد.
  • vertexPositions آرایه‌ای از XrVector3f است که زمان اجرا موقعیت‌های رأس زیرشبکه را به آن خروجی می‌دهد.
  • ‫vertexNormals آرایه‌ای از XrVector3f است که زمان اجرا، بردار نرمال رأس‌های زیرشبکه را در آن خروجی می‌دهد. اگر برنامه ردیابی را با غیرفعال کردن حالت عادی ایجاد کرده باشد، این فیلد می‌تواند NULL باقی بماند.
  • ‫vertexSemantics آرایه‌ای از uint8_t است که زمان اجرا معناشناسی رأس زیرشبکه را به آن خروجی می‌دهد. اگر برنامه ردیابی با مجموعه برچسب معنایی XR_SCENE_MESH_SEMANTIC_LABEL_SET_NONE_ANDROID ایجاد کرده باشد، این فیلد می‌تواند NULL باقی بماند.
  • ‫indexCapacityInput ظرفیت indices است، یا ۰ برای بازیابی ظرفیت موردنیاز.
  • ‫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 باید اشاره‌گری به آرایه‌ای از مقادیر indexCapacityInput uint32_t باشد

شمارش 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;

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

شرح شمارشی

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 و هرگونه دسته فرزند باید به‌صورت خارجی همگام‌سازی شود

کدهای برگشتی

موفقیت‌آمیز بود

  • 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));

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

فرمان‌های جدید

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

Enums جدید

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

  • 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

مشکلات

سابقه نسخه

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

    • شرح اولیه افزونه