XR_ANDROID_composition_layer_passthrough_mesh پسوند OpenXR

رشته نام

XR_ANDROID_composition_layer_passthrough_mesh

نوع پسوند

پسوند نمونه

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

463

تجدید نظر

1

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

OpenXR 1.0

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

18-09-2024

وضعیت IP

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

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

گرنت یوشیدا، گوگل

کوین مول، گوگل

واسیلی بارانوف، گوگل

پیتر چن، گوگل

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

نمای کلی

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

این افزونه برنامه‌ها را قادر می‌سازد تا بافت‌های عبوری را از طریق یک لایه ترکیب اضافی XrCompositionLayerPassthroughANDROID روی هندسه دلخواه بفرستند.

ویژگی های لایه عبور با پارامترهای زیر مشخص می شود، که در آنها طرح ریزی با XrPassthroughLayerANDROID نشان داده می شود.

  XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;

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

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

هنگام فراخوانی xrGetSystemProperties، یک برنامه کاربردی می‌تواند بررسی کند که آیا سیستم قادر به ایجاد مش عبور لایه ترکیبی است یا خیر.

typedef struct XrSystemPassthroughLayerPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsPassthroughLayer;
    uint32_t           maxMeshIndexCount;
    uint32_t           maxMeshVertexCount;
} XrSystemPassthroughLayerPropertiesANDROID;

توضیحات اعضا

  • type XrStructureType این ساختار است.
  • next NULL یا اشاره گر به ساختار بعدی در زنجیره ساختار است. چنین ساختاری در هسته OpenXR یا این پسوند تعریف نشده است.
  • supportsPassthroughLayer یک XrBool32 است، که نشان می دهد آیا سیستم فعلی از شبکه عبور لایه ترکیب پشتیبانی می کند یا خیر.
  • maxMeshIndexCount یک uint32_t است که حداکثر تعداد شاخص هایی را که برای یک مش عبور پذیرفته می شود برمی گرداند.
  • maxMeshVertexCount یک uint32_t است که حداکثر تعداد رئوس را که برای یک مش عبور پذیرفته می شود، برمی گرداند.

اگر supportsPassthroughLayer XR_FALSE برگرداند، سیستم از شبکه عبور لایه ترکیب پشتیبانی نمی کند و بنابراین XR_ERROR_FEATURE_UNSUPPORTED از xrCreatePassthroughLayerANDROID دریافت می کند. هنگامی که supportsPassthroughLayer لایه XR_FALSE است، برنامه باید از استفاده از شبکه عبور لایه ترکیب اجتناب کند.

اگر supportsPassthroughLayer XR_TRUE برگرداند، سیستم از شبکه عبور لایه ترکیب پشتیبانی می کند. در این حالت، maxMeshIndexCount و maxMeshVertexCount یک عدد غیر صفر برمی‌گردانند. هنگام فراخوانی xrCreatePassthroughLayerANDROID و xrSetPassthroughLayerMeshANDROID ، یک برنامه باید از maxMeshIndexCount و maxMeshVertexCount به‌عنوان حداکثر مقادیر برای تنظیم مش‌های عبور استفاده کند، در غیر این صورت XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID بیشتر از داده‌های پشتیبانی شده است.

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

ترکیب لایه عبوری

XrCompositionLayerPassthroughANDROID حاوی اطلاعات مورد نیاز برای نمایش یک بافت عبوری بر روی یک شبکه مثلثی هنگام فراخوانی xrEndFrame است. XrCompositionLayerPassthroughANDROID یک نوع مستعار برای ساختار پایه XrCompositionLayerBaseHeader است که در XrFrameEndInfo استفاده می شود.

typedef struct XrCompositionLayerPassthroughANDROID {
    XrStructureType              type;
    const void*                  next;
    XrCompositionLayerFlags      layerFlags;
    XrSpace                      space;
    XrPosef                      pose;
    XrVector3f                   scale;
    float                        opacity;
    XrPassthroughLayerANDROID    layer;
} XrCompositionLayerPassthroughANDROID;

توضیحات اعضا

  • type XrStructureType این ساختار است.
  • next NULL یا اشاره گر به ساختار بعدی در زنجیره ساختار است. چنین ساختاری در هسته OpenXR یا این پسوند تعریف نشده است.
  • layerFlags یک بیت ماسک از XrCompositionLayerFlags است که پرچم هایی را برای اعمال بر روی لایه توصیف می کند.
  • space ، فضای XrSpace است که در آن pose لایه مش در طول زمان ارزیابی می شود.
  • pose یک XrPosef است که موقعیت و جهت لایه مش را در چارچوب مرجع space مشخص می کند.
  • scale یک XrVector3f است که مقیاس مش لایه را تعریف می کند.
  • opacity یک float است که کدورت بافت عبوری را در محدوده [0، 1] تعریف می کند.
  • layer XrPassthroughLayerANDROID است که قبلا توسط xrCreatePassthroughLayerANDROID ایجاد شده است.

برنامه می تواند یک ساختار XrCompositionLayerPassthroughANDROID با layer ایجاد شده و مش های مربوطه ارائه شده توسط XrPassthroughLayerMeshANDROID ایجاد کند.

یک اشاره گر به XrCompositionLayerPassthroughANDROID ممکن است در xrEndFrame به عنوان یک اشاره گر به ساختار پایه XrCompositionLayerBaseHeader ، به ترتیب لایه انتخاب شده، برای درخواست زمان اجرا برای ترکیب لایه عبور در خروجی فریم نهایی ارسال شود.

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

یک دسته لایه عبور ایجاد کنید

دسته XrPassthroughLayerANDROID یک لایه عبور را نشان می دهد که رفتار XrCompositionLayerPassthroughANDROID را تعریف می کند.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

یک برنامه کاربردی می تواند با فراخوانی xrCreatePassthroughLayerANDROID یک دسته XrPassthroughLayerANDROID ایجاد کند. دسته XrPassthroughLayerANDROID برگشتی را می توان متعاقباً در فراخوانی های API استفاده کرد.

XrResult xrCreatePassthroughLayerANDROID(
    XrSession                                   session,
    const XrPassthroughLayerCreateInfoANDROID*  createInfo,
    XrPassthroughLayerANDROID*                  layer);

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

  • session یک XrSession است که در آن لایه passthrough برای آن ایجاد می شود.
  • createInfo یک اشاره گر به ساختار XrPassthroughLayerCreateInfoANDROID است که پارامترهای لایه عبور اولیه را مشخص می کند. این فیلد همچنین می تواند به یک ساختار XrPassthroughLayerMeshANDROID متصل شود تا مش را همزمان تنظیم کند.
  • layer اشاره گر به دسته ای است که XrPassthroughLayerANDROID ایجاد شده در آن برگردانده می شود.

برنامه باید تعداد شاخص‌های مش عبوری را در XrPassthroughLayerCreateInfoANDROID::vertexCapacity و XrPassthroughLayerCreateInfoANDROID::indexCapacity کمتر یا مساوی با حداکثر مقادیر بازگردانده شده توسط XrSystemPassthroughROID:AndCondexmax مشخص کند. XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount هنگام فراخوانی xrGetSystemProperties . xrCreatePassthroughLayerANDROID یک خطای XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID برمی گرداند اگر تعداد شاخص های مش تعریف شده توسط createInfo از حداکثر مقادیر بیشتر باشد.

دسته XrPassthroughLayerANDROID باید در نهایت با استفاده از تابع xrDestroyPassthroughLayerANDROID آزاد شود.

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

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

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

typedef struct XrPassthroughLayerCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
    uint32_t           vertexCapacity;
    uint32_t           indexCapacity;
} XrPassthroughLayerCreateInfoANDROID;

توضیحات اعضا

  • type XrStructureType این ساختار است.
  • next NULL یا اشاره گر به ساختار بعدی در زنجیره ساختار است. XrPassthroughLayerMeshANDROID را می توان در زنجیره بعدی ارائه کرد تا یک مش اولیه برای لایه passthrough هنگام فراخوانی xrCreatePassthroughLayerANDROID مشخص شود.
  • vertexCapacity یک uint32_t است که حداکثر ظرفیت بافر رأس برای مش این لایه یا 0 در صورت نامشخص نشان می دهد. اگر مشخص شده باشد، XrPassthroughLayerMeshANDROID::vertexCount هر مجموعه مش برای این لایه باید کمتر یا برابر با vertexCapacity باشد.
  • indexCapacity یک uint32_t است که حداکثر ظرفیت بافر شاخص برای مش این لایه یا 0 را در صورت نامشخص نشان می دهد. اگر مشخص شده باشد، XrPassthroughLayerMeshANDROID::indexCount هر مجموعه مش برای این لایه باید کمتر یا برابر با indexCapacity باشد.

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

یک برنامه می تواند از تابع xrDestroyPassthroughLayerANDROID برای آزاد کردن لایه عبور و منابع زیرین استفاده کند.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

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

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

ایمنی نخ

  • دسترسی به layer ، و هر دسته فرزند، باید به صورت خارجی همگام شود

کدهای بازگشت

موفقیت

  • XR_SUCCESS

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID

شبکه لایه عبوری را تنظیم کنید

یک برنامه می تواند از تابع xrSetPassthroughLayerMeshANDROID برای تنظیم مش برای لایه عبور استفاده کند.

XrResult xrSetPassthroughLayerMeshANDROID(
    XrPassthroughLayerANDROID                   layer,
    const XrPassthroughLayerMeshANDROID*        mesh);

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

برنامه باید تعداد شاخص‌های مش عبوری را در XrPassthroughLayerMeshANDROID::vertexCount و XrPassthroughLayerMeshANDROID::indexCount کمتر یا مساوی با حداکثر مقادیر برگردانده شده توسط XrSystemPassthroughLayerPropertiesANDROID::maxCountshI مشخص کند. XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount هنگام فراخوانی xrGetSystemProperties . اگر تعداد شاخص های مش داده شده توسط mesh از xrSetPassthroughLayerMeshANDROID بیشتر از مقادیر حداکثر باشد، XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID برگردانده می شود.

اگر ظرفیت بافر مش توسط XrPassthroughLayerCreateInfoANDROID::vertexCapacity و XrPassthroughLayerCreateInfoANDROID::indexCapacity در هنگام ایجاد layer با استفاده از xrCreatePassthroughLayerANDROID مشخص شده باشد، آنگاه error XR_ERROR_SIZE_INSUFFICIENT برمی گردد. xrSetPassthroughLayerMeshANDROID اگر تعداد شاخص های مش تعریف شده توسط mesh بیشتر از ظرفیت باشد.

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

کدهای بازگشت

موفقیت

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

شکست

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_VALIDATION_FAILURE
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

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

typedef struct XrPassthroughLayerMeshANDROID {
    XrStructureType          type;
    const void*              next;
    XrWindingOrderANDROID    windingOrder;
    uint32_t                 vertexCount;
    const XrVector3f*        vertices;
    uint32_t                 indexCount;
    const uint16_t*          indices;
} XrPassthroughLayerMeshANDROID;

توضیحات اعضا

  • type XrStructureType این ساختار است.
  • next NULL یا اشاره گر به ساختار بعدی در زنجیره ساختار است.
  • windingOrder XrWindingOrderANDROID از مثلث های مش است که در هنگام رندر کردن مش از آن برای حذف پشتی استفاده می شود.
  • vertexCount یک uint32_t است که نشان دهنده تعداد رئوس در مش است. وقتی XrPassthroughLayerCreateInfoANDROID::vertexCapacity مشخص می شود، vertexCount باید کمتر یا مساوی vertexCapacity باشد.
    • vertices یک اشاره گر به آرایه ای از XrVector3f است که شامل موقعیت های رأس مش مثلث است.
  • indexCount یک uint32_t است که نشان دهنده تعداد اندیس ها در مش مثلث است. آخرین indexCount % 3 شاخص ها، در صورت وجود، ترسیم نمی شوند. وقتی XrPassthroughLayerCreateInfoANDROID::indexCapacity مشخص می شود، indexCount باید کمتر یا مساوی با indexCapacity باشد.
  • indices یک اشاره گر به آرایه uint16_t است که شامل شاخص های مش مثلث است.

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

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

typedef enum XrWindingOrderANDROID {
    XR_WINDING_ORDER_UNKNOWN_ANDROID = 0,
    XR_WINDING_ORDER_CW_ANDROID = 1,
    XR_WINDING_ORDER_CCW_ANDROID = 2
} XrWindingOrderANDROID;

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

  • XR_WINDING_ORDER_UNKNOWN_ANDROID — ترتیب سیم پیچی مثلث های مش مشخص نیست.
  • XR_WINDING_ORDER_CW_ANDROID - ترتیب سیم پیچی مثلث های مش در جهت عقربه های ساعت است.
  • XR_WINDING_ORDER_CCW_ANDROID — ترتیب سیم پیچی مثلث های مش در خلاف جهت عقربه های ساعت است.

کد مثال برای ترکیب لایه عبوری

کد مثال زیر نحوه ایجاد یک لایه عبور و استفاده از آن در ترکیب بندی را نشان می دهد. 

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized
XrSession session; // previously initialized
XrSpace space; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrCreatePassthroughLayerANDROID xrCreatePassthroughLayerANDROID; // previously initialized
PFN_xrDestroyPassthroughLayerANDROID xrDestroyPassthroughLayerANDROID; // previously initialized
PFN_xrSetPassthroughLayerMeshANDROID xrSetPassthroughLayerMeshANDROID; // previously initialized

// Inspect passthrough mesh system properties
XrSystemPassthroughLayerPropertiesANDROID passthroughLayerSystemProperties{
  XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID};
XrSystemProperties systemProperties{
  XR_TYPE_SYSTEM_PROPERTIES, &passthroughLayerSystemProperties};
CHK_XR(xrGetSystemProperties(instance, systemId, &systemProperties));
if (!passthroughLayerSystemProperties.supportsPassthroughLayer) {
    // the system does not support composite layer passthrough mesh.
    return;
}

// The initial mesh for the layer.
XrPassthroughLayerMeshANDROID mesh = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID,
  .windingOrder = XR_WINDING_ORDER_CW_ANDROID,
  .vertexCount = 4,
  .vertices = {
    { 0, 0, 0 }, { 0, 1, 0 }, { 1, 1, 0 }, { 1, 0, 0 }
  },
  .indexCount = 6,
  .indices = {
    0, 1, 2,
    0, 2, 3
  },
};

// Create the layer. Layers are expected to persist across frames.
XrPassthroughLayerCreateInfoANDROID create_info = {
  .type = XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID,
  .next = &mesh,
  .vertexCapacity = 0,
  .indexCapacity = 0,
};
XrPassthroughLayerANDROID layer;
CHK_XR(xrCreatePassthroughLayerANDROID(session, &create_info, &layer));

// Create a composition layer. Composition layers are submitted per frame.
XrCompositionLayerPassthroughANDROID passthrough_layer = {
  .type = XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID,
  .next = nullptr,
  .layerFlags = 0,
  .space = space,
  .pose = {
    .orientation = { 0.0f, 0.0f, 0.0f, 1.0f }
    .position = { 0.0f, 0.0f, 0.0f }
  },
  .scale = { 1.0f, 1.0f, 1.0f },
  .opacity = 1.0f,
  .layer = layer
};

while (1) {
    // ...
    // For every frame in frame loop
    // ...

    // Submit composition layer in xrEndFrame.
    std::vector<XrCompositionLayerBaseHeader*> layers = {
        ...,
        &passthrough_layer,
        ...,
    };
    XrFrameEndInfo end_frame_info = { XR_TYPE_FRAME_END_INFO, nullptr };
    end_frame_info.layerCount = (uint32_t)layers.size();
    end_frame_info.layers = layers.data();
    CHK_XR(xrEndFrame(session, &end_frame_info));

    // Update the layer. Results can be seen the next time a passthrough composition
    // layer is submitted.
    mesh.indexCount = 9;
    const uint16_t new_index_buffer[] = {
        0, 1, 2,
        0, 2, 3,
        0, 1, 2
    };
    mesh.indexBuffer = &new_index_buffer[0];
    CHK_XR(xrSetPassthroughLayerMeshANDROID(&layer, &mesh));

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

// Clean up.
CHK_XR(xrDestroyPassthroughLayerANDROID(layer));

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

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

شمارش XrObjectType با:

  • XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

شمارش XrStructureType با:

  • XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
  • XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
  • XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
  • XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID

شمارش XrResult با:

  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

فهرست های جدید

ساختارهای جدید

توابع جدید

مسائل

تاریخچه نسخه

  • بازبینی 1، 11/09/2024 (لوانا چن)
    • توضیحات پسوند اولیه

OpenXR™ و لوگوی OpenXR علائم تجاری متعلق به The Khronos Group Inc. هستند و به عنوان یک علامت تجاری در چین، اتحادیه اروپا، ژاپن و بریتانیا ثبت شده اند.