מחרוזת שם
XR_ANDROID_composition_layer_passthrough_mesh
סוג התוסף
תוסף למכונה
מספר תוסף רשום
463
גרסה
1
תלות בתוספים ובגרסאות
תאריך השינוי האחרון
2024-09-18
סטטוס כתובת ה-IP
לא ידוע על תלונות על הפרת זכויות יוצרים בנושא כתובת IP.
שותפים ביצירת התוכן
גרנט יושידה (Grant Yoshida), Google
Kevin Moule, Google
Vasiliy Baranov, Google
פיטר צ'ן (Peter Chen), Google
לבנה צ'ן, Google
סקירה כללית
במכשירים שתומכים במספר מצבי שילוב סביבה, המערכת עשויה לספק הגדרות של העברה ישירה (passthrough) כדי להציג למשתמש את הסביבה הפיזית שלו בתצוגה מוחלטת.
התוסף הזה מאפשר לאפליקציות להקרין טקסטורות של העברה (passthrough) על גיאומטריה שרירותית באמצעות שכבת קומפוזיציה נוספת XrCompositionLayerPassthroughANDROID.
המאפיינים של שכבת העברה מפורטים באמצעות הפרמטרים הבאים, שבהם ההקרנה מיוצגת על ידי XrPassthroughLayerANDROID.
XrPosef pose;
XrVector3f scale;
float opacity;
XrPassthroughLayerANDROID layer;
כדי להעביר את המסך במלואו, האפליקציות יכולות להשתמש במצב ערבוב סביבה.
בדיקת יכולות המערכת
אפליקציה יכולה לבדוק אם המערכת מסוגלת להעביר רשתות של שכבות קומפוזיציה באמצעות שרשור של המבנה XrSystemPassthroughLayerPropertiesANDROID למבנה XrSystemProperties בזמן הקריאה ל-xrGetSystemProperties.
typedef struct XrSystemPassthroughLayerPropertiesANDROID {
XrStructureType type;
void* next;
XrBool32 supportsPassthroughLayer;
uint32_t maxMeshIndexCount;
uint32_t maxMeshVertexCount;
} XrSystemPassthroughLayerPropertiesANDROID;
תיאורי חברים
type
הוא XrStructureType של המבנה הזה.next
הואNULL
או הפניה למבנה הבא בשרשרת המבנים. לא מוגדרים מבנים כאלה ב-OpenXR או בהרחבה הזו.supportsPassthroughLayer
הואXrBool32
, שמציין אם המערכת הנוכחית תומכת במעבר רשת (passthrough) של שכבת קומפוזיציה.maxMeshIndexCount
הואuint32_t
שמחזיר את המספר המקסימלי של אינדקסים שייכללו במערך של רשת העברה.maxMeshVertexCount
הואuint32_t
שמחזיר את המספר המקסימלי של קודקודים שייכללו ברשת העברה.
אם הפונקציה supportsPassthroughLayer
מחזירה את הערך XR_FALSE
, המערכת לא תומכת ברשת של העברה ישירה של שכבת קומפוזיציה, ולכן תקבל את הערך XR_ERROR_FEATURE_UNSUPPORTED
מהפונקציה xrCreatePassthroughLayerANDROID. צריך להימנע משימוש במערך של העברה ישירה בשכבת הקומפוזיציה כשהערך של supportsPassthroughLayer
הוא XR_FALSE
.
אם הפונקציה supportsPassthroughLayer
מחזירה את הערך XR_TRUE
, המערכת תומכת במעבר של רשתות (mesh) דרך שכבת קומפוזיציה. במקרה כזה, הפונקציות maxMeshIndexCount
ו-maxMeshVertexCount
יחזירו מספר שאינו אפס. באפליקציה צריך להשתמש ב-maxMeshIndexCount
וב-maxMeshVertexCount
כערכים המקסימליים להגדרת רשתות של העברה דרך כשקוראים ל-xrCreatePassthroughLayerANDROID ול-xrSetPassthroughLayerMeshANDROID. אחרת, יכול להיות שהערך XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID
יוחזר כדי לציין שנתוני הרשת חורגים מהמגבלה הנתמכת.
שימוש תקין (מרומז)
- צריך להפעיל את התוסף
XR_ANDROID_composition_layer_passthrough_mesh
לפני שמשתמשים ב-XrSystemPassthroughLayerPropertiesANDROID - הערך של
type
חייב להיותXR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID
next
חייב להיותNULL
או מצביע תקין למבנה הבא בשרשרת המבנים
הרכב השכבה השקופה
השכבה XrCompositionLayerPassthroughANDROID מכילה את המידע הדרוש לעיבוד (רנדר) של טקסטורה של העברה (passthrough) על רשת משולשים כשקוראים ל-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
הוא מרחב Xr שבוpose
של רשת השכבות נמדד לאורך זמן.pose
הואXrPosef
שמגדיר את המיקום והכיוון של רשת השכבה במסגרת העזר שלspace
.scale
הואXrVector3f
שמגדיר את קנה המידה של רשת השכבה.opacity
הואfloat
שמגדיר את האטימות של הטקסטורה של העברת ההמשך בטווח [0, 1].layer
הוא XrPassthroughLayerANDROID שנוצר קודם לכן על ידי xrCreatePassthroughLayerANDROID.
האפליקציה יכולה ליצור מבנה XrCompositionLayerPassthroughANDROID עם layer
שנוצר והמערכות הרלוונטיות שסופקו על ידי XrPassthroughLayerMeshANDROID.
אפשר לשלוח הפניה ל-XrCompositionLayerPassthroughANDROID ב-xrEndFrame כהפניה למבנה הבסיס XrCompositionLayerBaseHeader, בסדר השכבות שנבחר, כדי לבקש מסביבת זמן הריצה ליצור שכבת העברה (passthrough) בתוצר המסגרת הסופי.
שימוש תקין (מרומז)
- חובה להפעיל את התוסף
XR_ANDROID_composition_layer_passthrough_mesh
לפני שמשתמשים ב-XrCompositionLayerPassthroughANDROID - הערך של
type
חייב להיותXR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID
next
חייב להיותNULL
או מצביע תקין למבנה הבא בשרשרת המבניםlayerFlags
חייב להיות0
או שילוב תקין של ערכים של XrCompositionLayerFlagBitsspace
חייב להיות כינוי חוקי ב-XrSpacelayer
חייב להיות מזהה XrPassthroughLayerANDROID חוקי- חובה שהמזהים
layer
ו-space
נוצרו, הוקצו או אוחזר מאותו XrSession.
יצירת שם למעטפת של שכבת העברה
הידית XrPassthroughLayerANDROID מייצגת שכבת העברה שמגדירה את ההתנהגות של XrCompositionLayerPassthroughANDROID.
XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)
אפליקציה יכולה ליצור מנוף XrPassthroughLayerANDROID באמצעות קריאה ל-xrCreatePassthroughLayerANDROID. אפשר להשתמש במנהל XrPassthroughLayerANDROID שהוחזרה בקריאות API.
XrResult xrCreatePassthroughLayerANDROID(
XrSession session,
const XrPassthroughLayerCreateInfoANDROID* createInfo,
XrPassthroughLayerANDROID* layer);
תיאורי פרמטרים
session
הוא XrSession שבו שכבת העברה תיצור.createInfo
הוא הפניה למבנה XrPassthroughLayerCreateInfoANDROID שמציין את הפרמטרים הראשוניים של שכבת העברה. אפשר גם לשרשר את השדה הזה למבנה XrPassthroughLayerMeshANDROID כדי להגדיר את הרשת בו-זמנית.layer
הוא הפניה למזהה (handle) שבו מוחזר האובייקט שנוצר של XrPassthroughLayerANDROID.
האפליקציה צריכה לציין את מספר אינדקסי הרשת של העברה דרך XrPassthroughLayerCreateInfoANDROID::vertexCapacity ו-XrPassthroughLayerCreateInfoANDROID::indexCapacity, כך שהם יהיו קטנים או שווים לערכי המקסימום שמוחזרים על ידי XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount ו-XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount בקריאה ל-xrGetSystemProperties. xrCreatePassthroughLayerANDROID תחזיר שגיאת XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID
אם מספר אינדקסי הרשת שמוגדר על ידי createInfo
גדול מהערכים המקסימליים.
צריך לפנות את הטיפולן של XrPassthroughLayerANDROID בסופו של דבר באמצעות הפונקציה xrDestroyPassthroughLayerANDROID.
שימוש תקין (מרומז)
- חובה להפעיל את התוסף
XR_ANDROID_composition_layer_passthrough_mesh
לפני שמפעילים את xrCreatePassthroughLayerANDROID session
חייב להיות מזהה XrSession חוקיcreateInfo
חייב להיות הפניה למבנה תקין של XrPassthroughLayerCreateInfoANDROIDlayer
חייב להיות הפניה למזהה של XrPassthroughLayerANDROID
קודי החזרה
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 בשרשרת הבאה כדי לציין רשת ראשונית לשכבת העברה כשקוראים ל-xrCreatePassthroughLayerANDROID.vertexCapacity
הואuint32_t
שמייצג את הקיבולת המקסימלית של מאגר הנקודות (vertex buffer) של המארג של השכבה הזו, או0
אם לא צוין אחרת. אם יצוין, הערך של XrPassthroughLayerMeshANDROID::vertexCount של כל רשת שמוגדר לה שכבה הזו חייב להיות קטן מ-vertexCapacity
או שווה לו.indexCapacity
הואuint32_t
שמייצג את הקיבולת המקסימלית של מאגר האינדקס של הרשת של השכבה הזו, או0
אם לא צוין אחרת. אם יצוין, הערך של XrPassthroughLayerMeshANDROID::indexCount של כל רשת שמוגדר לה שכבה הזו חייב להיות קטן מ-indexCapacity
או שווה לו.
שימוש תקין (מרומז)
- חובה להפעיל את התוסף
XR_ANDROID_composition_layer_passthrough_mesh
לפני שמשתמשים ב-XrPassthroughLayerCreateInfoANDROID - הערך של
type
חייב להיותXR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID
next
חייב להיותNULL
או מצביע תקין להמבנה הבא בשרשרת המבנים. מידע נוסף זמין במאמר XrPassthroughLayerMeshANDROID
אפליקציה יכולה להשתמש בפונקציה xrDestroyPassthroughLayerANDROID כדי לשחרר את שכבת העברה ואת המשאבים הבסיסיים.
XrResult xrDestroyPassthroughLayerANDROID(
XrPassthroughLayerANDROID layer);
תיאורי פרמטרים
layer
הוא XrPassthroughLayerANDROID שצריך להשמיד.
שימוש תקין (מרומז)
- חובה להפעיל את התוסף
XR_ANDROID_composition_layer_passthrough_mesh
לפני שמפעילים את xrDestroyPassthroughLayerANDROID. layer
חייב להיות מזהה XrPassthroughLayerANDROID חוקי
בטיחות בשרשור
- חובה לסנכרן באופן חיצוני את הגישה ל-
layer
ואת כל כינויי הילדים
קודי החזרה
XR_SUCCESS
XR_ERROR_FUNCTION_UNSUPPORTED
XR_ERROR_RUNTIME_FAILURE
XR_ERROR_HANDLE_INVALID
הגדרת רשת של שכבת העברה
אפליקציה יכולה להשתמש בפונקציה xrSetPassthroughLayerMeshANDROID כדי להגדיר את הרשת של שכבת העברה.
XrResult xrSetPassthroughLayerMeshANDROID(
XrPassthroughLayerANDROID layer,
const XrPassthroughLayerMeshANDROID* mesh);
תיאורי פרמטרים
layer
הוא הכינוי של XrPassthroughLayerANDROID שבו מעדכנים אתmesh
.mesh
הוא הפניה למבנה XrPassthroughLayerMeshANDROID שמציין את המידע של הרשת.
האפליקציה צריכה לציין את מספר אינדקסי הרשת של העברה דרך XrPassthroughLayerMeshANDROID::vertexCount ו-XrPassthroughLayerMeshANDROID::indexCount, כך שהם יהיו קטנים או שווים לערכי המקסימום שמוחזרים על ידי XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount ו-XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount בקריאה ל-xrGetSystemProperties. אם מספר האינדקסים של הרשת שמוצגים ב-mesh
מ-xrSetPassthroughLayerMeshANDROID גדול מהערכים המקסימליים, יוחזר הערך XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID
.
אם קיבולת מאגר המשנה של המבנה רשומה ב-XrPassthroughLayerCreateInfoANDROID::vertexCapacity וב-XrPassthroughLayerCreateInfoANDROID::indexCapacity כשיוצרים את layer
באמצעות xrCreatePassthroughLayerANDROID, השגיאה XR_ERROR_SIZE_INSUFFICIENT
תוחזר ב-xrSetPassthroughLayerMeshANDROID אם מספר האינדקסים של המבנה שמוגדר על ידי mesh
גדול מהקיבולת.
שימוש תקין (מרומז)
- חובה להפעיל את התוסף
XR_ANDROID_composition_layer_passthrough_mesh
לפני שמפעילים את xrSetPassthroughLayerMeshANDROID. layer
חייב להיות מזהה XrPassthroughLayerANDROID חוקיmesh
חייב להיות הפניה למבנה XrPassthroughLayerMeshANDROID תקין
קודי החזרה
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 של משולשי המארג, שישמש לצורך סינון צד עורפי (backface culling) במהלך העיבוד הגרפי של המארג.vertexCount
הואuint32_t
שמייצג את מספר הקודקודים ברשת. כשמציינים את XrPassthroughLayerCreateInfoANDROID::vertexCapacity, הערך שלvertexCount
חייב להיות קטן מ-vertexCapacity
או שווה לו.vertices
הוא הפניה למערך שלXrVector3f
שמכיל את מיקומי הנקודות של רשת המשולשים.
indexCount
הואuint32_t
שמייצג את מספר האינדקסים ברשת המשולשים. האינדקסים האחרונים שלindexCount % 3
, אם יש כאלה, לא יתוארו. כשמציינים את XrPassthroughLayerCreateInfoANDROID::indexCapacity, הערך שלindexCount
חייב להיות קטן מ-indexCapacity
או שווה לו.indices
הוא הפניה למערך שלuint16_t
שמכיל את האינדקסים של רשת המשולשים.
שימוש תקין (מרומז)
- חובה להפעיל את התוסף
XR_ANDROID_composition_layer_passthrough_mesh
לפני שמשתמשים ב-XrPassthroughLayerMeshANDROID - הערך של
type
חייב להיותXR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
next
חייב להיותNULL
או מצביע תקין למבנה הבא בשרשרת המבניםwindingOrder
חייב להיות ערך חוקי של XrWindingOrderANDROID- אם
vertexCount
הוא לא0, vertices
, חייב להיות זהו הפניה למערך שלvertexCount
מבני XrVector3f - אם
indexCount
הוא לא0, indices
, חייב להיות הפניה למערך של ערכים שלindexCount 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
משתני Enum חדשים
מבנים חדשים
- XrPassthroughLayerCreateInfoANDROID
- XrPassthroughLayerMeshANDROID
- XrCompositionLayerPassthroughANDROID
- XrSystemPassthroughLayerPropertiesANDROID
פונקציות חדשות
בעיות
היסטוריית הגרסאות
- גרסה 1, 11 בספטמבר 2024 (Levana Chen)
- תיאור ראשוני של התוסף