XR_ANDROID_light_estimation

Name String

XR_ANDROID_light_estimation

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı Numarası

701

Düzeltme

1

Onay Durumu

Onaylanmadı

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

OpenXR 1.0

Son Değiştirilme Tarihi

2025-03-13

IP Durumu

Bilinen IP hak talebi yok.

Katkıda bulunanlar

Jared Finder, Google
Cairn Overturf, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Salar Khan, Google
Scott Chung, Google

Genel Bakış

Bu uzantı, uygulamanın başlığın etrafındaki gerçek dünya ortamının ışığını temsil eden verileri istemesine olanak tanır. Uygulama, bu bilgileri kullanarak sanal nesneleri yerleştirildikleri gerçek dünya sahnesiyle aynı koşullarda aydınlatabilir.

İzinler

Bu uzantı, ortamla ilgili aydınlatma bilgilerini sunduğundan Android uygulamalarının manifestlerinde android.permission.SCENE_UNDERSTANDING_COARSE izninin listelenmesi gerekir. android.permission.SCENE_UNDERSTANDING_COARSE izni tehlikeli bir izin olarak kabul edilir. Uygulama, bu işlevleri kullanmak için çalışma zamanında izni istemelidir:

(Koruma düzeyi: tehlikeli)

Sistem kapasitesini inceleme

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

typedef struct XrSystemLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsLightEstimation;
} XrSystemLightEstimationPropertiesANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de veya bu uzantıda bu tür yapılar tanımlanmamıştır.
  • supportsLightEstimation , geçerli sistemin ışık tahminini destekleyip desteklemediğini belirten bir XrBool32 değeridir.

Bir uygulama, xrGetSystemProperties çağrılırken XrSystemProperties'i XrSystemLightEstimationPropertiesANDROID yapısıyla genişleterek sistemin ışık tahmini özelliğini destekleyip desteklemediğini kontrol edebilir .

Yalnızca bir çalışma zamanı supportsLightEstimation için XR_FALSE döndürürse çalışma zamanı , xrCreateLightEstimatorANDROID işlevinden XR_ERROR_FEATURE_UNSUPPORTED döndürmelidir.

Geçerli Kullanım (Dolaylı)

Işık tahmin aracı oluşturma

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Işık tahmini verileri çalışma zamanı tarafından oluşturulur ve XrLightEstimatorANDROID tutma yeri kullanılarak uygulamayla paylaşılır.

Bu tutma yeri, bu uzantıdaki diğer işlevler kullanılarak ışık tahmini bilgilerine erişmek için kullanılabilir.

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

XrResult xrCreateLightEstimatorANDROID(
    XrSession                                   session,
    XrLightEstimatorCreateInfoANDROID*          createInfo,
    XrLightEstimatorANDROID*                    outHandle);

Parametre Açıklamaları

Uygulama, ışık tahmin aracı oluşturmak için xrCreateLightEstimatorANDROID işlevini kullanır.

  • Sistem ışık tahminini desteklemiyorsa çalışma zamanı mutlaka XR_ERROR_FEATURE_UNSUPPORTED değerini döndürmelidir.
  • Çalışma zamanı, gerekli izinler arayan uygulamaya verilmediyse mutlaka XR_ERROR_PERMISSION_INSUFFICIENT değerini döndürmelidir.

Bir uygulama, ışık tahmini verilerine erişimi tamamladığını çalışma zamanına bildirmek istiyorsa xrDestroyLightEstimatorANDROID aracılığıyla tutma yerini kaldırmalıdır .

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Başarısız

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST

XrLightEstimatorCreateInfoANDROID yapısı, XrLightEstimatorANDROID tutacını oluşturmak için gereken bilgileri açıklar.

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const void*        next;
} XrLightEstimatorCreateInfoANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Temel OpenXR'de veya bu uzantıda bu tür yapılar tanımlanmamıştır.

Geçerli Kullanım (Dolaylı)

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

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Parametre Açıklamaları

xrDestroyLightEstimatorANDROID işlevi, estimator ve temel kaynakları serbest bırakır.

Geçerli Kullanım (Dolaylı)

Thread Safety

  • estimator ve tüm alt tanıtıcılarına erişim, harici olarak senkronize edilmelidir.

Dönüş Kodları

Başarılı

  • XR_SUCCESS

Başarısız

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Işık tahmini verilerine erişme

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

XrResult xrGetLightEstimateANDROID(
    XrLightEstimatorANDROID                     estimator,
    const XrLightEstimateGetInfoANDROID*        input,
    XrLightEstimateANDROID*                     output);

Parametre Açıklamaları

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Başarısız

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

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

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const void*        next;
    XrSpace            space;
    XrTime             time;
} XrLightEstimateGetInfoANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • space, döndürülen ışık yönünün ve küresel harmoniklerin ifade edildiği referans alanını tanımlayan XrSpace'tir.
  • time, uygulamanın ışık tahmini sorgulamak istediği zamanı açıklayan XrTime değeridir.

Geçerli Kullanım (Dolaylı)

XrLightEstimateANDROID yapısı, ışık tahmini verilerini içerir:

typedef struct XrLightEstimateANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrTime                         lastUpdatedTime;
} XrLightEstimateANDROID;

Üye Açıklamaları

Her ışık tahmini yapısı için state alanı XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID ise yapıdaki diğer tüm alanlar rastgeledir. Yani değerleri tanımlanmamıştır.

Ortam ışığı, küresel harmonikler ve birincil yönlü ışık için ışık tahmini bilgilerini almak üzere uygulamalar, sırasıyla XrAmbientLightANDROID, XrSphericalHarmonicsANDROID ve XrDirectionalLightANDROID yapılarını XrLightEstimateANDROID :: next ile zincirleyebilir.

Geçerli Kullanım (Dolaylı)

XrAmbientLightANDROID yapısı, sahnedeki ambiyans ışığıyla ilgili ışık tahmini verilerini içerir.

typedef struct XrAmbientLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     colorCorrection;
} XrAmbientLightANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Geçerli yapılar arasında XrSphericalHarmonicsANDROID ve XrDirectionalLightANDROID yer alır .
  • state, ışık tahmini durumunu temsil eden XrLightEstimateStateANDROID değeridir.
  • intensity, ambiyans ışığının yoğunluğunu temsil eden bir XrVector3f'dir. Vektörün her bileşeni sırasıyla kırmızı, yeşil ve mavi kanallara karşılık gelir.

  • colorCorrection, gama alanındaki değerlere sahip bir XrVector3f'dir. Gama renk alanında oluşturuluyorsa oluşturma işleminden sonra nihai hesaplanan renge karşı bileşen bazında çarpın. Doğrusal alanda oluşturuluyorsa önce değerleri 2, 2 kuvvetini alarak doğrusal alana dönüştürün, ardından oluşturma işleminden sonra bileşen bazında nihai hesaplanmış renkle çarpın.

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

Geçerli Kullanım (Dolaylı)

XrSphericalHarmonicsANDROID yapısı, sahnenin aydınlatmasını temsil eden küresel harmonikleri içerir.

typedef struct XrSphericalHarmonicsANDROID {
    XrStructureType                    type;
    void*                              next;
    XrLightEstimateStateANDROID        state;
    XrSphericalHarmonicsKindANDROID    kind;
    float                              coefficients[9][3];
} XrSphericalHarmonicsANDROID;

Üye Açıklamaları

coefficients, giriş olarak yön alan ve o yönden gelen ışığın rengini çıkış olarak veren özel bir işlevde kullanılmalıdır. Daha fazla ayrıntıyı bu makalede bulabilirsiniz .

Geçerli Kullanım (Dolaylı)

XrSphericalHarmonicsKindANDROID numaralandırması, uygulamanın hangi tür küresel harmonikler istediğini çalışma zamanına bildirir.

typedef enum XrSphericalHarmonicsKindANDROID {
    XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID = 0,
    XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID = 1,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

Numaralandırma değerleri aşağıdaki anlamlara sahiptir:

Enum Açıklaması

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Küresel harmonik katsayılar, ana ışığın katkısı hariç olmak üzere ortam ışığı ışıma işlevini temsil eder.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Küresel harmonik katsayılar, ana ışığın katkısı da dahil olmak üzere ortam ışığı ışıma işlevini temsil eder.

XrDirectionalLightANDROID yapısı, ışık tahmini verilerini içerir.

typedef struct XrDirectionalLightANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    XrVector3f                     intensity;
    XrVector3f                     direction;
} XrDirectionalLightANDROID;

Üye Açıklamaları

Geçerli Kullanım (Dolaylı)

XrLightEstimateStateANDROID numaralandırması, çalışma zamanı tarafından döndürülen ışık tahmininin durumunu gösterir.

typedef enum XrLightEstimateStateANDROID {
    XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID = 0,
    XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID = 1,
    XR_LIGHT_ESTIMATE_STATE_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrLightEstimateStateANDROID;

Numaralandırma değerleri aşağıdaki anlamlara sahiptir:

Enum Açıklaması

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

Işık tahmini geçerli

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

Işık tahmini geçersiz

Işık tahmini için örnek kod

Aşağıdaki örnek kod, çalışma zamanında olası tüm ışık tahmini miktarlarının nasıl alınacağını gösterir.

XrSession session;  // Created at app startup
XrSpace appSpace;   // Created previously.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // Created previously.

XrLightEstimatorANDROID estimator;
XrLightEstimatorCreateInfoANDROID createInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID};
CHK_XR(xrCreateLightEstimatorANDROID(session, &createInfo, &estimator));

// Every frame
XrTime updateTime;  // Time used for the current frame's simulation update.

XrLightEstimateGetInfoANDROID info = {
    .type = XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID,
    .space = appSpace,
    .time = updateTime,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
};

XrSphericalHarmonicsANDROID sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &sphericalHarmonics,
};

XrLightEstimateANDROID estimate = {
    .type = XR_TYPE_LIGHT_ESTIMATE_ANDROID,
    .next = &ambientLight,
};

XrResult result = xrGetLightEstimateANDROID(estimator, &info, &estimate);
if (result == XR_SUCCESS &&
    estimate.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
  // use directionalLight, totalSh, ambientSh, ambientLight if each
  // struct has a valid state field
}

// When you want to disable light estimation
CHK_XR(xrDestroyLightEstimatorANDROID(estimator));

Yeni Nesne Türleri

Yeni Komutlar

Yeni Yapılar

Yeni Sıralamalar

Yeni Numaralandırılmış Değer Sabitleri

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • XrObjectType'i genişletme :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • XrStructureType'ı genişletme :

    • XR_TYPE_AMBIENT_LIGHT_ANDROID
    • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
    • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
    • XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Sayılar

Sürüm Geçmişi

  • 1. düzeltme, 16.09.2024 (Cairn Overturf)

    • İlk uzantı açıklaması