XR_ANDROID_light_estimation OpenXR uzantısı

Ad dizesi

XR_ANDROID_light_estimation

Uzantı Türü

Örnek uzatma

Kayıtlı Uzatma Numarası

701

Düzeltme

1

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

OpenXR 1.0

Son Değiştirilme Tarihi

2025-01-17

IP Durumu

Bilinen IP hak talepleri 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 kulaklığın etrafındaki gerçek dünya ortamının ışığını temsil eden veriler istemesine olanak tanır. Bu bilgiler, sanal nesneleri oluşturulurken yerleştirildikleri sahneyle aynı koşullarda aydınlatmak için kullanılabilir.

Sistem kapasitesini inceleme

Bir uygulama, xrGetSystemProperties çağrısında XrSystemLightEstimationPropertiesANDROID yapısını XrSystemProperties ile zincirleyerek sistemin ışık tahminini destekleyip desteklemediğini inceleyebilir. 

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

Ü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.
  • supportsLightEstimation, mevcut sistemin ışık tahminini destekleyip desteklemediğini belirten bir XrBool32 değeridir.

Bir uygulama, xrGetSystemProperties çağrısını yaparken XrSystemProperties'i XrSystemLightEstimationPropertiesANDROID yapısıyla genişleterek sistemin ışık tahminini destekleyip desteklemediğini inceleyebilir.

Sistem ışık tahminini destekleyemiyorsa supportsLightEstimation için XR_FALSE ve xrCreateLightEstimatorANDROID için XR_ERROR_FEATURE_UNSUPPORTED döndürür.

Geçerli Kullanım (Dolayı)

Hafif tahminci herkese açık kullanıcı adı oluşturma

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

XrLightEstimatorANDROID herkese açık kullanıcı adı, bir ışık tahmin aracını temsil eder. Bu uzantıdaki diğer işlevleri kullanarak hafif tahmin bilgilerine erişmek için bu herkese açık kimlik kullanılabilinir.

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

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

Parametre Açıklamaları

  • session, ışık tahmin cihazını oluşturan XrSession'dir.
  • createInfo, ışık tahmin cihazını oluşturmak için kullanılacak parametreleri içeren bir XrLightEstimatorCreateInfoANDROID yapısının işaretçisidir.
  • outHandle, oluşturulan XrLightEstimatorANDROID nesnesinin döndürüldüğü bir tutamacın işaretçisidir.

Uygulama, ışık tahmin edebilecek bir öğe oluşturmak için xrCreateLightEstimatorANDROID işlevini kullanabilir.

Döndürülen ışık tahmin aracısı herkese açık kullanıcı adı daha sonra API çağrılarında kullanılabilinir. Bir uygulama, ışık tahmini verilerine erişmeyi tamamladığını çalışma zamanında belirtmek istiyorsa xrDestroyLightEstimatorANDROID'ı kullanarak handle'i yok etmelidir.

Geçerli Kullanım (Dolaylı)

İade Kodları

Başarılı

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Hata

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

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

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

Ü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.

Geçerli Kullanım (Dolayı)

xrDestroyLightEstimatorANDROID işlevi, estimator ve temeldeki tüm kaynakları serbest bırakır. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Parametre Açıklamaları

Geçerli Kullanım (Dolayı)

Thread Güvenliği

  • estimator ve alt herkese açık kimliklere erişim, harici olarak senkronize edilmelidir.

İade Kodları

Başarılı

  • XR_SUCCESS

Hata

  • 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 (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_TIME_INVALID

XrLightEstimateGetInfoANDROID, ışık tahmini verilerini almak için gereken bilgileri açıklar. 

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

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • space, döndürülen ışık yönünün, küresel armonilerin ve küp haritası dönme işleminin ifade edildiği referans uzayı tanımlayan XrSpace bağımsız değişkenidir.
  • time, uygulamanın ışık tahminini sorgulamak istediği zamanı açıklayan XrTime bağımsız değişkenidir.

Geçerli Kullanım (Dolayı)

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

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

Üye Açıklamaları

Ortam ışığı küp haritası, ortam ışığı, küresel armonikler ve birincil yönlü ışık için ışık tahmini bilgisi elde etmek amacıyla uygulamalar, XrLightEstimateANDROID::next üzerine sırasıyla XrEnvironmentLightingCubemapANDROID, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID ve XrDirectionalLightANDROID yapılarının örneklerini zincirleyebilir.

Geçerli Kullanım (Dolayı)

XrEnvironmentLightingCubemapANDROID yapısı, sahnenin ortam ışığıyla ilgili küp haritası biçiminde ışık tahmini verilerini içerir. 

typedef struct XrEnvironmentLightingCubemapANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    const float*                   cubemapRightImage;
    const float*                   cubemapLeftImage;
    const float*                   cubemapTopImage;
    const float*                   cubemapBottomImage;
    const float*                   cubemapFrontImage;
    const float*                   cubemapBackImage;
    uint32_t                       resolution;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrEnvironmentLightingCubemapANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Geçerli yapılar XrSphericalHarmonicsANDROID, XrAmbientLightANDROID ve XrDirectionalLightANDROID'dır.
  • state, ışık tahmininin durumunu temsil eden XrLightEstimateStateANDROID değeridir.
  • cubemapRightImage, küp haritasının sağ tarafının R32G32B32_SFLOAT arabelleğini temsil eden bir float* bağımsız değişkenidir. Bu HDR olduğu için kayan nokta değerleri 1,0'dan yüksek olabilir.
  • cubemapLeftImage, küp haritanın sol tarafının R32G32B32_SFLOAT arabelleğini temsil eden bir float* bağımsız değişkenidir. Bu HDR olduğu için kayan nokta değerleri 1,0'dan yüksek olabilir.
  • cubemapTopImage, küp haritasının üst tarafının R32G32B32_SFLOAT arabelleğini temsil eden bir float* bağımsız değişkenidir. Bu HDR olduğu için kayan nokta değerleri 1,0'dan yüksek olabilir.
  • cubemapBottomImage, küp haritasının alt tarafının R32G32B32_SFLOAT arabelleğini temsil eden bir float* bağımsız değişkenidir. Bu HDR olduğu için kayan nokta değerleri 1,0'dan yüksek olabilir.
  • cubemapFrontImage, küp haritasının ön tarafının R32G32B32_SFLOAT arabelleğini temsil eden bir float* bağımsız değişkenidir. Bu HDR olduğu için kayan nokta değerleri 1,0'dan yüksek olabilir.
  • resolution, küp haritanın her tarafının resminin genişliğini ve yüksekliğini temsil eden bir uint32_t bağımsız değişkenidir. Bu HDR olduğu için kayan nokta değerleri 1,0'dan büyük olabilir.
  • rotation, küp haritasının döndürülmesini temsil eden bir XrQuaternionf bağımsız değişkenidir.
  • centerExposureTime, küp haritasının yakalandığı zamanı temsil eden bir XrTime bağımsız değişkenidir. Küp haritaları arasında interpolasyon için kullanışlıdır.

Geçerli Kullanım (Dolayı)

  • XrEnvironmentLightingCubemapANDROID kullanılmadan önce XR_ANDROID_light_estimation uzantısı etkinleştirilmelidir.
  • type XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID olmalıdır
  • next NULL veya yapı zincirindeki sonraki yapıya işaret eden geçerli bir işaretçi olmalıdır.
  • state geçerli bir XrLightEstimateStateANDROID değeri olmalıdır.
  • cubemapRightImage geçerli bir kayan nokta değerinin işaretçisi olmalıdır.
  • cubemapLeftImage geçerli bir kayan nokta değerinin işaretçisi olmalıdır.
  • cubemapTopImage geçerli bir kayan nokta değerinin işaretçisi olmalıdır.
  • cubemapBottomImage geçerli bir kayan nokta değerinin işaretçisi olmalıdır.
  • cubemapFrontImage geçerli bir kayan nokta değerinin işaretçisi olmalıdır.
  • cubemapBackImage geçerli bir kayan nokta değerinin işaretçisi olmalıdır.

XrAmbientLightANDROID yapısı, sahnedeki ortam ışığı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 değeridir.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Geçerli yapılar XrSphericalHarmonicsANDROID, XrEnvironmentLightingCubemapANDROID ve XrDirectionalLightANDROID'dır.
  • state, ışık tahmininin durumunu temsil eden XrLightEstimateStateANDROID değeridir.
  • intensity, ortam ışığının yoğunluğunu temsil eden bir XrVector3 bağımsız değişkenidir. Vektörün her bileşeni kırmızı, yeşil ve mavi kanallara karşılık gelir.
  • colorCorrection, gama alanında değerlere sahip bir XrVector3 bağımsız değişkenidir. Gama düzeltilmiş oluşturma işleminizin rengini bu değerlerle bileşen bazında çarpın.

Geçerli Kullanım (Dolayı)

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

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

Üye Açıklamaları

Geçerli Kullanım (Dolaylı)

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

XrSphericalHarmonicsKindANDROID enumeration, uygulamanın hangi tür küresel armonikleri istediğini çalışma zamanında tanımlar. 

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

Listeler aşağıdaki anlamlara sahiptir:

Enum

Açıklama

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Küresel harmonik katsayıları, ana ışıktan gelen katkı hariç olmak üzere ortam ışığı parlaklık işlevini temsil eder.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Küresel armonik katsayıları, ana ışıktan gelen katkı da dahil olmak üzere ortam ışığı parlaklık işlevini temsil eder.

XrLightEstimateStateANDROID enumeration, uygulamanın hangi tür küresel armonikleri istediğini çalışma zamanında tanımlar. 

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

Listeler aşağıdaki anlamlara sahiptir:

Enum

Açıklama

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 kodda, çalışma zamanından mümkün olan tüm ışık tahmini miktarlarının nasıl alınacağı gösterilmektedir.

XrSession session;  // Created at app startup
XrSpace appSpace;   // 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 totalSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
    .next = &directionalLight,
};

XrSphericalHarmonicsANDROID ambientSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID,
    .next = &totalSh,
};

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


XrEnvironmentLightingCubemapANDROID lightingCubemap {
    .type = XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID,
    .next = &ambientLight,
}

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

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

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

Yeni Nesne Türleri

  • XrLightEstimator

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

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

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

  • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
  • XR_TYPE_LIGHT_ESTIMATE_ANDROID
  • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
  • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
  • XR_TYPE_AMBIENT_LIGHT_ANDROID
  • XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID

Yeni Sıralamalar

Yeni Yapılar

Yeni İşlevler

Sorunlar

Sürüm Geçmişi

  • 2. Düzeltme, 17.01.2025 (Salar Khan)
    • Ortam ışığı küp haritası desteği eklendi
  • 1. Düzeltme, 16.09.2024 (Cairn Overturf)
    • İlk uzantı açıklaması