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

2024-09-18

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

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ı sırasında XrSystemProperties öğesini 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 tahmin aracı herkese açık kullanıcı adı oluşturma

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

XrLightEstimatorANDROID herkese açık kullanıcı adı, ışık tahmin cihazını temsil eder. Bu uzantıdaki diğer işlevleri kullanarak ışık tahmini 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ılabilir. Bir uygulama, çalışma zamanında ışık tahmini verilerine erişmeyi tamamladığını belirtmek istiyorsa xrDestroyLightEstimatorANDROID'ı kullanarak handle'i yok etmelidir.

Geçerli Kullanım (Dolayı)

İ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 ve küresel armonilerin ifade edildiği referans alanını 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üresel armonikler ve birincil yönlü ışık için ışık tahmini bilgisi elde etmek amacıyla uygulamalar, XrLightEstimateANDROID::next üzerine sırasıyla XrAmbientLightANDROID, XrSphericalHarmonicsANDROID ve XrDirectionalLightANDROID yapılarının örneklerini zincirleyebilir.

Geçerli Kullanım (Dolayı)

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

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

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 harmonik 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,
};

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

  • 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

Yeni Sıralamalar

Yeni Yapılar

Yeni İşlevler

Sorunlar

Sürüm Geçmişi

  • 1. Düzeltme, 16.09.2024 (Cairn Overturf)
    • İlk uzantı açıklaması