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ı
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 birXrBool32
bağımsız değişkenidir.maxMeshIndexCount
biruint32_t
olup, geçiş örgüsü için kabul edilecek maksimum dizin sayısını döndürür.maxMeshVertexCount
biruint32_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ırnext
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ünpose
değerinin zaman içinde değerlendirildiği XrSpace'tir.pose
, katman örgüsününspace
referans çerçevesindeki konumunu ve yönünü tanımlayan birXrPosef
bağımsız değişkenidir.scale
, katman örgüsünün ölçeğini tanımlayan birXrVector3f
bağımsız değişkenidir.opacity
, [0, 1] aralığında geçiş dokusu opaklığını tanımlayan birfloat
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ırnext
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ırspace
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 despace
, aynı XrSession'den 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ılırken 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ı
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 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 XrPassthroughLayerMeshANDROID sonraki zincirde sağlanabilir.vertexCapacity
, bu katmanın örgüsü için köşe ara belleğinin maksimum kapasitesini temsil eden biruint32_t
veya belirtilmemişse0
değerini alır. Belirtilmişse bu katman için ayarlanan herhangi bir ağın XrPassthroughLayerMeshANDROID::vertexCount değerivertexCapacity
'den küçük veya bu değere eşit olmalıdır.indexCapacity
, bu katmanın örgüsü için dizin arabelleğinin maksimum kapasitesini temsil eden biruint32_t
veya belirtilmemişse0
değerini alır. Belirtilmişse bu katman için ayarlanan herhangi bir ağın XrPassthroughLayerMeshANDROID::indexCount değeriindexCapacity
değerinden az veya ona 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ırnext
NULL
veya yapı zincirindeki sonraki yapıya işaret eden geçerli bir işaretçi olmalıdır. Ayrıca bkz. XrPassthroughLayerMeshANDROID
Uygulamalar, geçiş 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 çağrılmadan ö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ı
XR_SUCCESS
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
, belirtilenmesh
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ı
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 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 biruint32_t
bağımsız değişkenidir. XrPassthroughLayerCreateInfoANDROID::vertexCapacity belirtildiğindevertexCount
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 birXrVector3f
dizisinin işaretçisidir.
indexCount
, üçgen örgesindeki dizin sayısını temsil eden biruint32_t
bağımsız değişkenidir. Varsa sonindexCount % 3
dizin çizilmez. XrPassthroughLayerCreateInfoANDROID::indexCapacity belirtildiğindeindexCount
,indexCapacity
değerinden küçük veya ona eşit olmalıdır.indices
, üçgen örgünün dizinlerini içeren biruint16_t
dizisinin işaretçisidir.
Geçerli Kullanım (Dolayı)
- XrPassthroughLayerMeshANDROID kullanılacaksa
XR_ANDROID_composition_layer_passthrough_mesh
uzantısı etkinleştirilmelidir. type
XR_TYPE_PASSTHROUGH_LAYER_MESH_ANDROID
olmalıdırnext
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ğilsevertexCount
XrVector3f yapılarının dizisine işaret eden bir işaretçi olmalıdır.indexCount
,0, indices
değilseindexCount 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));
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
- XrPassthroughLayerCreateInfoANDROID
- XrPassthroughLayerMeshANDROID
- XrCompositionLayerPassthroughANDROID
- XrSystemPassthroughLayerPropertiesANDROID
Yeni İşlevler
Sorunlar
Sürüm Geçmişi
- Düzeltme 1, 11.09.2024 (Levana Chen)
- İlk uzantı açıklaması