XR_ANDROID_light_estimation OpenXR uzantısı

Name String

XR_ANDROID_light_estimation

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı 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 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. Bu bilgiler, sanal nesneler oluşturulurken yerleştirildikleri sahneyle aynı koşullarda aydınlatmak için kullanılabilir.

Sistem kapasitesini inceleme

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

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 gösteren bir XrBool32'dir.

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

Sistem ışık tahminini desteklemiyorsa supportsLightEstimation için XR_FALSE, xrCreateLightEstimatorANDROID için XR_ERROR_FEATURE_UNSUPPORTED değerini döndürür.

Geçerli Kullanım (Dolaylı)

Işık tahmini herkese açık kullanıcı adı oluşturma

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

XrLightEstimatorANDROID tutacağı, ışık tahmincisini temsil eder. 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 kullanabilir.

Döndürülen ışık tahmin aracı tutacağı, daha sonra API çağrılarında kullanılabilir. Bir uygulama, çalışma zamanına ışık tahmini verilerine erişimi tamamladığını belirtmek istiyorsa xrDestroyLightEstimatorANDROID kullanarak 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_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 tutacını 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'ı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, estimator ve temel kaynakları serbest bırakır. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Parametre Açıklamaları

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_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'ı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, küresel harmoniklerin ve küp haritası dönüşünün 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ı

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

Geçerli Kullanım (Dolaylı)

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'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir. Geçerli yapılar XrSphericalHarmonicsANDROID, XrAmbientLightANDROID ve XrDirectionalLightANDROID'dir.
  • state, ışık tahmininin durumunu gösteren XrLightEstimateStateANDROID'dir.
  • cubemapRightImage, küp haritasının sağ tarafındaki R32G32B32_SFLOAT arabelleğini temsil eden bir float* değeridir. Bu değerin HDR olduğunu, dolayısıyla kayan değerlerin 1,0'dan büyük olabileceğini unutmayın.
  • cubemapLeftImage, küp haritasının sol tarafındaki R32G32B32_SFLOAT arabelleğini temsil eden bir float*'dir. Bu değerin HDR olduğunu, dolayısıyla kayan değerlerin 1,0'dan büyük olabileceğini unutmayın.
  • cubemapTopImage, küp haritasının üst tarafındaki R32G32B32_SFLOAT arabelleğini temsil eden bir float*'dir. Bu değerin HDR olduğunu, dolayısıyla kayan değerlerin 1,0'dan büyük olabileceğini unutmayın.
  • cubemapBottomImage, küp haritasının alt tarafındaki R32G32B32_SFLOAT arabelleğini temsil eden bir float*'dir. Bu değerin HDR olduğunu, dolayısıyla kayan değerlerin 1,0'dan büyük olabileceğini unutmayın.
  • cubemapFrontImage, küp haritasının ön tarafındaki R32G32B32_SFLOAT arabelleğini temsil eden bir float*'dir. Bu değerin HDR olduğunu, dolayısıyla kayan değerlerin 1,0'dan büyük olabileceğini unutmayın.
  • resolution, küp haritasının her bir tarafındaki görüntünün genişliğini ve yüksekliğini temsil eden bir uint32_t'dir.
  • rotation, küp haritasının döndürülmesini temsil eden bir XrQuaternionf'dir.
  • centerExposureTime, küp haritasının çekildiği zamanı temsil eden bir XrTime değeridir. Küpkartlar arasında enterpolasyon için kullanışlıdır.

Geçerli Kullanım (Dolaylı)

  • XR_ANDROID_light_estimation uzantısı, XrEnvironmentLightingCubemapANDROID kullanılmadan önce etkinleştirilmelidir.
  • type XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID olmalıdır
  • next, NULL veya bir yapı zincirindeki sonraki yapıya yönelik 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ğerine yönelik bir işaretçi olmalıdır.
  • cubemapLeftImage, geçerli bir kayan nokta değerine yönelik bir işaretçi olmalıdır.
  • cubemapTopImage, geçerli bir kayan nokta değerine yönelik bir işaretçi olmalıdır.
  • cubemapBottomImage, geçerli bir kayan nokta değerine yönelik bir işaretçi olmalıdır.
  • cubemapFrontImage, geçerli bir kayan nokta değerine yönelik bir işaretçi olmalıdır.
  • cubemapBackImage, geçerli bir kayan nokta değerine yönelik bir işaretçi 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ı

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ı

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 numaralandırması, çalışma zamanına uygulamanın ne tür küresel harmonikler istediğini bildirir. 

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

Numaralandırılmış değerler aşağıdaki anlamlara gelir:

Enum

Açıklama

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

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

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

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

XrLightEstimateStateANDROID numaralandırması, uygulamaların hangi tür küresel harmonikleri istediğini çalışma zamanına bildirir. 

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

Numaralandırılmış değerler aşağıdaki anlamlara gelir:

Enum

Açıklama

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

Işık tahmini geçerlidir.

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ından 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.

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 numaralandırması şu öğelerle genişletildi:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

XrStructureType numaralandırması şu değerlerle 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

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

OpenXR™ ve OpenXR logosu, The Khronos Group Inc. şirketinin ticari markalarıdır ve Çin, Avrupa Birliği, Japonya ve Birleşik Krallık'ta ticari marka olarak tescillidir.