XR_ANDROID_global_passthrough_dimming

Name String

XR_ANDROID_global_passthrough_dimming

Uzantı Türü

Örnek uzantısı

Kayıtlı Dahili Numara

797

Düzeltme

1

Onay Durumu

Onaylanmadı

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

OpenXR 1.0

Son Değiştirilme Tarihi

2026-03-10

IP Durumu

Bilinen bir fikri mülkiyet hak talebi yok.

Katkıda bulunanlar

Brian Chen, Google
Kyle Chen, Google
Nihav Jain, Google
Spencer Quin, Google

Genel Bakış

Optik şeffaf cihazlar kullanıma sunuldukça, uygulamaların geçişin karanlığını ayarlamasına izin vererek kullanıcıya uygulama bağlamıyla en iyi karışımı sunmak önemlidir. Ayrıca, güvenlik nedeniyle sistemin geçişi karartmasına izin vermek de önemlidir.

Bu uzantı, uygulamaların mevcut karartma seviyesini ayarlaması ve alması için iki işlevin yanı sıra karartma seviyesi değiştiğinde yayınlanacak bir etkinlik sağlar.

Sistem özelliğini inceleme

XrSystemGlobalDimmingPropertiesANDROID yapısı şu şekilde tanımlanır:

typedef struct XrSystemGlobalDimmingPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsGlobalDimming;
} XrSystemGlobalDimmingPropertiesANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • supportsGlobalDimming, mevcut sistemin genel karartmayı destekleyip desteklemediğini gösteren bir XrBool32 değeridir.

Bir uygulama, xrGetSystemProperties işlevini çağırırken XrSystemProperties'e bir XrSystemGlobalDimmingPropertiesANDROID yapısı zincirleyerek sistemin genel karartmayı destekleyip desteklemediğini inceleyebilir.

Çalışma zamanı, supportsGlobalDimming için XR_FALSE döndürürse xrGetGlobalDimmingLevelANDROID çağrıldığında XR_ERROR_FEATURE_UNSUPPORTED döndürmesi gerekir.

Geçerli Kullanım (Dolaylı)

Desteklenen genel karartma seviyelerini listeleme

xrEnumerateSupportedGlobalDimmingLevelsANDROID yapısı şu şekilde tanımlanır:

XrResult xrEnumerateSupportedGlobalDimmingLevelsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    supportedGlobalDimmingLevelCapacityInput,
    uint32_t*                                   supportedGlobalDimmingLevelCountOutput,
    float*                                      supportedGlobalDimmingLevels);

Üye Açıklamaları

  • instance, systemId öğesinin alındığı örnektir.
  • systemId, desteklenen düzeyleri numaralandırılacak XrSystemId değeridir.
  • supportedGlobalDimmingLevelCapacityInput, supportedGlobalDimmingLevels dizisinin kapasitesidir veya gerekli kapasiteyi alma isteğini belirtmek için 0'dır.
  • supportedGlobalDimmingLevelCountOutput, yazılan supportedGlobalDimmingLevels sayısına yönelik bir işaretçi veya supportedGlobalDimmingLevelCapacityInput değerinin yetersiz olması durumunda gerekli kapasiteye yönelik bir işaretçidir.
  • supportedGlobalDimmingLevels, desteklenen seviyeler dizisine işaret eder ancak supportedGlobalDimmingLevelCapacityInput 0 ise NULL olabilir.

Döndürülen supportedGlobalDimmingLevelCountOutput değeri 0 ise 0,0 ile 1,0 arasındaki tüm genel karartma seviyeleri desteklenir.

xrEnumerateSupportedGlobalDimmingLevelsANDROID, XrSystemId tarafından desteklenen genel karartma seviyelerini listeler. Desteklenen seviyeler, XrInstance'ın kullanım ömrü boyunca değişmemelidir. Döndürülen seviye listesi artan düzende sıralanmış olmalıdır.

Çalışma zamanları, belirli bir systemId için ve instance'nin kullanım ömrü boyunca bu numaralandırmadan her zaman aynı arabellek içeriklerini döndürmelidir.

Geçerli Kullanım (Dolaylı)

  • XR_ANDROID_global_passthrough_dimming uzantısı, xrEnumerateSupportedGlobalDimmingLevelsANDROID çağrılmadan önce etkinleştirilmelidir
  • instance geçerli bir XrInstance herkese açık kullanıcı adı olmalıdır
  • supportedGlobalDimmingLevelCountOutput, bir uint32_t değerine işaretçi olmalıdır
  • supportedGlobalDimmingLevelCapacityInput, 0 değilse supportedGlobalDimmingLevels, supportedGlobalDimmingLevelCapacityInput float değerlerinden oluşan bir dizinin işaretçisi olmalıdır.

Dönüş Kodları

Başarılı

  • XR_SUCCESS

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SIZE_INSUFFICIENT
  • XR_ERROR_SYSTEM_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Genel Karartma Seviyesini Yapılandır

XrGlobalDimmingFrameEndInfoANDROID yapısı şu şekilde tanımlanır:

typedef struct XrGlobalDimmingFrameEndInfoANDROID {
    XrStructureType    type;
    const void*        next;
    float              globalDimmingLevel;
} XrGlobalDimmingFrameEndInfoANDROID;

Parametre Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • globalDimmingLevel, 0,0 (şeffaf) ile 1,0 (opak) arasında bir değerdir. Çalışma zamanı, bu değeri desteklenen en yakın global karartma seviyesiyle eşleyebilir. Uygulama, mevcut karartma düzeyinin tercih edildiğini belirtmek için bu değeri -1,0 olarak ayarlayabilir.

globalDimmingLevel değeri, engellenen ışığın yüzdesini belirtir. 0,0 değeri% 0 ışık engellemeye, 1,0 ise% 100 ışık engellemeye karşılık gelir. Engellenen ışığın yüzdesi genel olarak şu şekilde gösterilebilir:

100% - Light Transmittance%

ISO 8980-3:2022 uyarınca ışık geçirgenliği yüzdesi, görünür ışık dalga boylarında (380 nm ila 780 nm) iletilen ışınım akısının gelen ışınım akısına oranı olarak ölçülebilir.

XrGlobalDimmingFrameEndInfoANDROID, bir uygulamanın tercih edilen genel karartma düzeyini istemek için XrFrameEndInfo'da zincirleyebileceği bir yapıdır.

İstenen karartma seviyesi mevcut karartma seviyesinden farklıysa çalışma zamanı, istenen karartma seviyesini uygulamalıdır.

Çalışma zamanı, genel karartma seviyesini kontrol eder ve güvenlik nedeniyle tercih edilen genel karartma seviyesini yok sayabilir.

Geçerli Kullanım (Dolaylı)

xrGetGlobalDimmingLevelANDROID işlevi şu şekilde tanımlanır:

XrResult xrGetGlobalDimmingLevelANDROID(
    XrSession                                   session,
    float*                                      dimmingLevel);

Parametre Açıklamaları

  • session, geçerli bir XrSession herkese açık adıdır.
  • dimmingLevel, mevcut karartma seviyesini gösteren bir işaretçidir.

Döndürülen dimmingLevel 0,0 ile 1,0 arasında olmalıdır. 0,0 tamamen şeffaf, 1,0 ise tamamen karartılmış anlamına gelir.

Karartma seviyesi ayarlanmadıysa çalışma zamanı, geçiş etkinleştirildiğinde karartma seviyesini 0,0, devre dışı bırakıldığında ise 1,0 olarak ayarlamalıdır.

Geçerli Kullanım (Dolaylı)

  • XR_ANDROID_global_passthrough_dimming uzantısı, xrGetGlobalDimmingLevelANDROID çağrılmadan önce etkinleştirilmelidir
  • session geçerli bir XrSession herkese açık kullanıcı adı olmalıdır
  • dimmingLevel, bir float değerine işaretçi olmalıdır

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_VALIDATION_FAILURE

Karartma Seviyesi Değiştirildi Etkinliği

XrEventDataGlobalDimmingLevelChangedANDROID yapısı şu şekilde tanımlanır:

typedef struct XrEventDataGlobalDimmingLevelChangedANDROID {
    XrStructureType    type;
    const void*        next;
    XrSession          session;
} XrEventDataGlobalDimmingLevelChangedANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapıya işaret eden bir göstergedir. Temel OpenXR'da veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • session, geçerli bir XrSession herkese açık adıdır.

Uygulama, xrPollEvent kullanarak bu etkinliği alabilir. Bu etkinlik, karartma seviyesi uygulamalar veya cihazlardaki fiziksel düğmeler tarafından değiştirildiğinde gönderilir.

Odaklanılan uygulama başka bir uygulamaya geçtiğinde bu etkinlik gönderilmez.

Uygulama, yeni karartma seviyesini almak için xrGetGlobalDimmingLevelANDROID'i çağırarak etkinliğe yanıt vermelidir ve XrGlobalDimmingFrameEndInfoANDROID :: globalDimmingLevel değerini buna göre güncellemelidir. Etkinliğe yanıt vermek, uygulama tercih edilen karartma düzeyini değiştirdiğinde çalışma zamanına sinyal gönderilmesini sağlar.

Geçerli Kullanım (Dolaylı)

Örnek kod

Sistem kapasitesini kontrol etme ve desteklenen global karartma seviyelerini listeleme

Aşağıdaki örnek kodda, genel karartmanın desteklenip desteklenmediğinin nasıl kontrol edileceği gösterilmektedir.

XrInstance instance; // previously initialized
XrSystemId systemId; // previously initialized

// The function pointers are previously initialized using xrGetInstanceProcAddr.
PFN_xrEnumerateSupportedGlobalDimmingLevelsANDROID xrEnumerateSupportedGlobalDimmingLevelsANDROID;

XrSystemGlobalDimmingPropertiesANDROID dimmingControlSystemProperties { XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID };

XrSystemProperties systemProperties; // Chain dimmingControlSystemProperties

// ...
// Run xrGetSystemProperties()
// ...

if (!dimmingControlSystemProperties.supportsGlobalDimming) {
  // The system does not support global dimming
  return;
}

// Enumerate supported levels
uint32_t count = 0;
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, nullptr));

std::vector<float> supportedLevels(count);
CHK_XR(xrEnumerateSupportedGlobalDimmingLevelsANDROID(instance, systemId, count, &count, supportedLevels.data()));

Anket Karartma Seviyesi Değiştirildi Etkinliği

Aşağıdaki örnek kod, karartma seviyesi değiştirildi etkinliğinin nasıl sorgulanacağını gösterir.

XrEventDataBuffer event{ XR_TYPE_EVENT_DATA_BUFFER };

// ...
// Run xrPollEvent()
// ...

switch (event.type) {
  // This event will not be sent when focused app switches
  case XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID:
  {
    const XrEventDataGlobalDimmingLevelChangedANDROID &dimmingLevelChangedEvent =
            *reinterpret_cast<XrEventDataGlobalDimmingLevelChangedANDROID *>(&event);

    // Query new dimming level using xrGetGlobalDimmingLevelANDROID()
  }
}

Yeni Komutlar

Yeni Yapılar

Yeni Enum Sabitleri

  • XR_ANDROID_GLOBAL_PASSTHROUGH_DIMMING_EXTENSION_NAME
  • XR_ANDROID_global_passthrough_dimming_SPEC_VERSION

  • XrStructureType'ı genişletme:

    • XR_TYPE_EVENT_DATA_GLOBAL_DIMMING_LEVEL_CHANGED_ANDROID
    • XR_TYPE_GLOBAL_DIMMING_FRAME_END_INFO_ANDROID
    • XR_TYPE_SYSTEM_GLOBAL_DIMMING_PROPERTIES_ANDROID

Sayılar

Sürüm Geçmişi

  • Düzeltme 1, 07.10.2025 (Brian Chen)

    • İlk uzantı açıklaması.