XR_ANDROID_composition_layer_passthrough_mesh OpenXR uzantısı

Ad dizesi

XR_ANDROID_composition_layer_passthrough_mesh

Uzantı Türü

Örnek uzatma

Kayıtlı Uzatma Numarası

463

Düzeltme

1

Uzantı ve Sürüm Bağımlılıkları

OpenXR 1.0

Son Değiştirilme Tarihi

2024-09-18

IP Durumu

Bilinen IP hak talepleri yok.

Katkıda bulunanlar

Grant Yoshida, Google

Kevin Moule, Google

Vasiliy Baranov, Google

Peter Chen, Google

Levana Chen, Google

Genel Bakış

Birden fazla ortam karışımı modunu destekleyen cihazlarda sistem, kullanıcıya fiziksel ortamını etkileyici bir görünümden göstermek için geçiş yapılandırmaları sağlayabilir.

Bu uzantı, uygulamaların ek bir kompozisyon katmanı XrCompositionLayerPassthroughANDROID aracılığıyla geçişli dokuları rastgele geometriye yansıtmasına olanak tanır.

Geçiş katmanı özellikleri, projeksiyonun XrPassthroughLayerANDROID ile temsil edildiği aşağıdaki parametrelerle belirtilir.

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

Tam ekran geçişi için uygulamalar çevre karma modunu kullanabilir.

Sistem kapasitesini inceleme

Bir uygulama, xrGetSystemProperties çağrısı sırasında XrSystemPassthroughLayerPropertiesANDROID yapısını XrSystemProperties ile zincirleyerek sistemin kompozisyon katmanı geçiş örgüsü yapıp yapamayacağını inceleyebilir.

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • supportsPassthroughLayer, mevcut sistemin kompozisyon katmanı geçiş örgüsünü destekleyip desteklemediğini belirten bir XrBool32 bağımsız değişkenidir.
  • maxMeshIndexCount bir uint32_t, geçiş örgüsü için kabul edilecek maksimum dizin sayısını döndürür.
  • maxMeshVertexCount bir uint32_t olup, geçiş örgüsü için kabul edilecek maksimum köşe sayısını döndürür.

supportsPassthroughLayer XR_FALSE döndürürse sistem, kompozisyon katmanı geçiş örgüsünü desteklemez ve bu nedenle xrCreatePassthroughLayerANDROID işlevinden XR_ERROR_FEATURE_UNSUPPORTED alır. Uygulama, supportsPassthroughLayer XR_FALSE olduğunda kompozisyon katmanı geçiş örgüsünü kullanmaktan kaçınmalıdır.

supportsPassthroughLayer, XR_TRUE döndürürse sistem, kompozisyon katmanı geçiş örgüsünü destekler. Bu durumda maxMeshIndexCount ve maxMeshVertexCount sıfır olmayan bir sayı döndürür. Bir uygulama, xrCreatePassthroughLayerANDROID ve xrSetPassthroughLayerMeshANDROID çağrılarını yaparken geçiş örgüsünü ayarlamak için maksimum değerler olarak maxMeshIndexCount ve maxMeshVertexCount'ı kullanmalıdır. Aksi takdirde, ağ verilerinin desteklenen sınırı aştığını belirtmek için XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID döndürülebilir.

Geçerli Kullanım (Dolayı)

Geçiş Katmanı Bileşimi

XrCompositionLayerPassthroughANDROID, xrEndFrame çağrılırken bir geçiş dokusunu üçgen örgüsünde oluşturmak için gereken bilgileri içerir. XrCompositionLayerPassthroughANDROID, XrFrameEndInfo'da kullanılan temel yapı XrCompositionLayerBaseHeader için bir takma ad türüdür.

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'da veya bu uzantıda böyle bir yapı tanımlanmamıştır.
  • layerFlags, katmana uygulanacak işaretleri açıklayan XrCompositionLayerFlags bit maskesi.
  • space, katman örgüsünün pose değerinin zaman içinde değerlendirildiği XrSpace'tir.
  • pose, katman örgüsünün space referans çerçevesindeki konumunu ve yönünü tanımlayan bir XrPosef bağımsız değişkenidir.
  • scale, katman örgüsünün ölçeğini tanımlayan bir XrVector3f bağımsız değişkenidir.
  • opacity, [0, 1] aralığında geçiş dokusu opaklığını tanımlayan bir float bağımsız değişkenidir.
  • layer, daha önce xrCreatePassthroughLayerANDROID tarafından oluşturulan XrPassthroughLayerANDROID öğesidir.

Uygulama, oluşturulan layer ve XrPassthroughLayerMeshANDROID tarafından sağlanan ilgili ağlarla bir XrCompositionLayerPassthroughANDROID yapısı oluşturabilir.

Çalışma zamanının, nihai kare çıkışına bir geçiş katmanı oluşturmasını istemek için XrCompositionLayerPassthroughANDROID'ın işaretçisi, xrEndFrame içinde seçilen katman sırasına göre temel yapı XrCompositionLayerBaseHeader'ın işaretçisi olarak gönderilebilir.

Geçerli Kullanım (Dolayı)

Geçiş katmanı kolu oluşturma

XrPassthroughLayerANDROID işleyicisi, XrCompositionLayerPassthroughANDROID'ın davranışını tanımlayan bir geçiş katmanını temsil eder.

XR_DEFINE_HANDLE(XrPassthroughLayerANDROID)

Uygulamalar, xrCreatePassthroughLayerANDROID işlevini çağırarak XrPassthroughLayerANDROID işleyicisi oluşturabilir. Döndürülen XrPassthroughLayerANDROID işleyicisi daha sonra API çağrılarında kullanıla bilir. 

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

Parametre Açıklamaları

Uygulama, XrPassthroughLayerCreateInfoANDROID::vertexCapacity ve XrPassthroughLayerCreateInfoANDROID::indexCapacity parametrelerinde, xrGetSystemProperties çağrısı sırasında XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount ve XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount tarafından döndürülen maksimum değerlerden küçük veya bu değerlere eşit olan geçişli ağ dizilerinin sayısını belirtmelidir. createInfo tarafından tanımlanan ağ dizini sayısı maksimum değerlerden büyükse xrCreatePassthroughLayerANDROID bir XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID hatası döndürür.

XrPassthroughLayerANDROID mülkünün xrDestroyPassthroughLayerANDROID işlevi kullanılarak serbest bırakılması gerekir.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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 yapısı şu şekilde tanımlanır: 

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya yapı zincirindeki bir sonraki yapının işaretçisidir. xrCreatePassthroughLayerANDROID çağrısı yapılırken geçiş katmanı için ilk bir ağ belirtmek üzere sonraki zincirde XrPassthroughLayerMeshANDROID sağlanabilir.
  • vertexCapacity, bu katmanın örgüsü için köşe ara belleğinin maksimum kapasitesini temsil eden bir uint32_t veya belirtilmemişse 0 değerini alır. Belirtilmişse bu katman için ayarlanan herhangi bir örgünün XrPassthroughLayerMeshANDROID::vertexCount değeri vertexCapacity değerinden az veya ona eşit olmalıdır.
  • indexCapacity, bu katmanın örgüsü için dizin arabelleğinin maksimum kapasitesini temsil eden bir uint32_t veya belirtilmemişse 0 değerini alır. Belirtilmişse bu katman için ayarlanan herhangi bir ağın XrPassthroughLayerMeshANDROID::indexCount değeri indexCapacity değerinden az veya ona eşit olmalıdır.

Geçerli Kullanım (Dolayı)

Uygulamalar, geçiş katmanını ve temel kaynakları serbest bırakmak için xrDestroyPassthroughLayerANDROID işlevini kullanabilir.

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

Parametre Açıklamaları

Geçerli Kullanım (Dolayı)

Thread Güvenliği

  • layer ve alt herkese açık kullanıcı adlarına erişim harici olarak senkronize edilmelidir.

İade Kodları

Başarılı

  • XR_SUCCESS

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_HANDLE_INVALID

Geçiş katmanı örgüsünü ayarlama

Uygulamalar, geçiş katmanının örgüsünü ayarlamak için xrSetPassthroughLayerMeshANDROID işlevini kullanabilir.

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

Parametre Açıklamaları

Uygulama, xrGetSystemProperties çağrısı sırasında XrSystemPassthroughLayerPropertiesANDROID::maxMeshIndexCount ve XrSystemPassthroughLayerPropertiesANDROID::maxMeshVertexCount tarafından döndürülen maksimum değerlerden küçük veya bu değerlere eşit olacak şekilde XrPassthroughLayerMeshANDROID::vertexCount ve XrPassthroughLayerMeshANDROID::indexCount'ta geçiş ağı dizinlerinin sayısını belirtmelidir. xrSetPassthroughLayerMeshANDROID işlevindeki mesh tarafından verilen ağ dizini sayısı maksimum değerlerden büyükse XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID döndürülür.

xrCreatePassthroughLayerANDROID kullanılarak layer oluşturulurken ağ geçidi arabelleği kapasitesi XrPassthroughLayerCreateInfoANDROID::vertexCapacity ve XrPassthroughLayerCreateInfoANDROID::indexCapacity ile belirtilirse mesh tarafından tanımlanan ağ geçidi dizinlerinin sayısı kapasiteden fazlaysa xrSetPassthroughLayerMeshANDROID işlevinde XR_ERROR_SIZE_INSUFFICIENT hatası döndürülür.

Geçerli Kullanım (Dolayı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • 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 yapısı şu şekilde tanımlanır: 

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • windingOrder, ağ üçgenlerinin XrWindingOrderANDROID değeridir. Bu değer, ağ oluşturulurken arka yüz kırpma için kullanılır.
  • vertexCount, ağdaki köşe sayısını temsil eden bir uint32_t bağımsız değişkenidir. XrPassthroughLayerCreateInfoANDROID::vertexCapacity belirtildiğinde vertexCount vertexCapacity değerinden küçük veya bu değere eşit olmalıdır.
    • vertices, üçgen örgünün köşe konumlarını içeren bir XrVector3f dizisine işaretçidir.
  • indexCount, üçgen örgesindeki dizin sayısını temsil eden bir uint32_t bağımsız değişkenidir. Varsa son indexCount % 3 dizin çizilmez. XrPassthroughLayerCreateInfoANDROID::indexCapacity belirtildiğinde indexCount, indexCapacity değerinden küçük veya ona eşit olmalıdır.
  • indices, üçgen örgünün dizinlerini içeren bir uint16_t dizisinin işaretçisidir.

Geçerli Kullanım (Dolayı)

XrWindingOrderANDROID enumeration, bir örgünün üçgenlerinin sarma sırasını tanımlar. Bu sıra, geçiş katmanının örgüsünü oluştururken arka yüz kırpma için çalışma zamanında kullanılır. 

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

Listeleme Açıklamaları

  • XR_WINDING_ORDER_UNKNOWN_ANDROID  — Örgünün üçgenlerinin sarma sırası bilinmiyor.
  • XR_WINDING_ORDER_CW_ANDROID  — Örgünün üçgenlerinin sarma sırası saat yönündedir.
  • XR_WINDING_ORDER_CCW_ANDROID  — Örgünün üçgenlerinin sarma sırası saat yönünün tersinedir.

Geçiş katmanı oluşturma için örnek kod

Aşağıdaki örnek kodda, geçiş katmanının nasıl oluşturulacağı ve kompozisyonda nasıl kullanılacağı gösterilmektedir.

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

Yeni Nesne Türleri

Yeni Enum Constants

XrObjectType dizini aşağıdakilerle genişletildi:

  • XR_OBJECT_TYPE_PASSTHROUGH_LAYER_ANDROID

XrStructureType dizini aşağıdakilerle genişletildi:

  • 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 dizini şu şekilde genişletildi:

  • XR_ERROR_MESH_DATA_LIMIT_EXCEEDED_ANDROID

Yeni Sıralamalar

Yeni Yapılar

Yeni İşlevler

Sorunlar

Sürüm Geçmişi

  • Düzeltme 1, 11.09.2024 (Levana Chen)
    • İlk uzantı açıklaması

OpenXR™ ve OpenXR logosu, The Khronos Group Inc. şirketinin ticari markalarıdır ve Çin, Avrupa Birliği, Japonya ve Birleşik Krallık'ta ticari marka olarak tescil edilmiştir.