The Android XR SDK is now available in Developer Preview. We want your feedback! Visit our support page to reach out.

Bu sayfa, Cloud Translation API ile çevrilmiştir.

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

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 ise, 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ş ağı özelliğini 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ı)

XrSystemPassthroughLayerPropertiesANDROID kullanılmadan önce XR_ANDROID_composition_layer_passthrough_mesh uzantısı etkinleştirilmelidir.
type XR_TYPE_SYSTEM_PASSTHROUGH_LAYER_PROPERTIES_ANDROID olmalıdır
next NULL veya yapı zincirindeki sonraki yapıya işaret eden geçerli bir işaretçi olmalıdır.

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 çerçeve çı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ı)

XrCompositionLayerPassthroughANDROID kullanılmadan önce XR_ANDROID_composition_layer_passthrough_mesh uzantısı etkinleştirilmelidir.
type XR_TYPE_COMPOSITION_LAYER_PASSTHROUGH_ANDROID olmalıdır
next NULL veya yapı zincirindeki sonraki yapıya işaret eden geçerli bir işaretçi olmalıdır.
layerFlags 0 veya XrCompositionLayerFlagBits değerlerinin geçerli bir kombinasyonu olmalıdır
space geçerli bir XrSpace herkese açık kullanıcı adı olmalıdır.
layer geçerli bir XrPassthroughLayerANDROID tutma yeri olmalıdır.
Hem layer hem de space, aynı XrSession'de oluşturulmuş, ayrılmış veya alınmış olmalıdır.

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ı

session, geçiş katmanının oluşturulacağı bir XrSession'dir.
createInfo, ilk geçiş katmanı parametrelerini belirten bir XrPassthroughLayerCreateInfoANDROID yapısının işaretçisidir. Bu alan, aynı anda örgüyü ayarlamak için bir XrPassthroughLayerMeshANDROID yapısına da zincirlenebilir.
layer, oluşturulan XrPassthroughLayerANDROID nesnesinin döndürüldüğü bir tutamacın işaretçisidir.

Uygulama, XrPassthroughLayerCreateInfoANDROID::vertexCapacity ve XrPassthroughLayerCreateInfoANDROID::indexCapacity içinde, 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ı)

xrCreatePassthroughLayerANDROID çağrılmadan önce XR_ANDROID_composition_layer_passthrough_mesh uzantısı etkinleştirilmelidir.
session geçerli bir XrSession herkese açık kullanıcı adı olmalıdır.
createInfo, geçerli bir XrPassthroughLayerCreateInfoANDROID yapısının işaretçisi olmalıdır.
layer, XrPassthroughLayerANDROID kolunun işaretçisi olmalıdır.

İ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 bir yapı zincirindeki sonraki yapının işaretçisidir. xrCreatePassthroughLayerANDROID çağrısı yapılırken geçiş katmanı için ilk bir örgüyü 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 ifade eder. Belirtilmişse bu katman için ayarlanan herhangi bir örgünün XrPassthroughLayerMeshANDROID::vertexCount değeri vertexCapacity'ten 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 ifade eder. Belirtilmişse bu katman için ayarlanan herhangi bir ağın XrPassthroughLayerMeshANDROID::indexCount değeri indexCapacity değerinden az veya eşit olmalıdır.

Geçerli Kullanım (Dolayı)

XrPassthroughLayerCreateInfoANDROID kullanılmadan önce XR_ANDROID_composition_layer_passthrough_mesh uzantısı etkinleştirilmelidir.
type XR_TYPE_PASSTHROUGH_LAYER_CREATE_INFO_ANDROID olmalıdır
next NULL veya yapı zincirindeki sonraki yapıya işaret eden geçerli bir işaretçi olmalıdır. Ayrıca bkz. XrPassthroughLayerMeshANDROID

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

XrResult xrDestroyPassthroughLayerANDROID(
    XrPassthroughLayerANDROID                   layer);

Parametre Açıklamaları

layer, kaldırılacak XrPassthroughLayerANDROID öğesidir.

Geçerli Kullanım (Dolayı)

xrDestroyPassthroughLayerANDROID numarası aranmadan önce XR_ANDROID_composition_layer_passthrough_mesh uzantısı etkinleştirilmelidir.
layer geçerli bir XrPassthroughLayerANDROID tutma yeri olmalıdır.

Thread Güvenliği

layer ve alt kimliklerine 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ı

layer, belirtilen mesh ile güncellenecek bir XrPassthroughLayerANDROID herkese açık kullanıcı adıdır.
- mesh, ağın bilgilerini belirten bir XrPassthroughLayerMeshANDROID yapısının işaretçisidir.

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

xrSetPassthroughLayerMeshANDROID çağrılmadan önce XR_ANDROID_composition_layer_passthrough_mesh uzantısı etkinleştirilmelidir.
layer geçerli bir XrPassthroughLayerANDROID tutma yeri olmalıdır.
mesh, geçerli bir XrPassthroughLayerMeshANDROID yapısına işaretçi olmalıdır

İ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 dizisinin işaretçisidir.
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ı)

XrPassthroughLayerMeshANDROID kullanılmadan önce XR_ANDROID_composition_layer_passthrough_mesh uzantısı etkinleştirilmelidir.
type XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID olmalıdır
next NULL veya yapı zincirindeki sonraki yapıya işaret eden geçerli bir işaretçi olmalıdır.
windingOrder geçerli bir XrWindingOrderANDROID değeri olmalıdır.
vertexCount 0, vertices değilse vertexCount XrVector3f yapılarının dizisine işaret eden bir işaretçi olmalıdır.
indexCount, 0, indices değilse indexCount uint16_t değerleri dizisinin bir işaretçisi olmalıdır.

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