XR_ANDROID_light_estimation_cubemap

Name String

XR_ANDROID_light_estimation_cubemap

Uzantı Türü

Örnek uzantısı

Kayıtlı Uzantı Numarası

722

Düzeltme

1

Onay Durumu

Onaylanmadı

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

XR_ANDROID_light_estimation

Son Değiştirilme Tarihi

2025-08-06

IP Durumu

Bilinen IP hak talebi yok.

Katkıda bulunanlar

Salar Khan, Google
Scott Chung, Google
Jared Finder, Google
Spencer Quin, Google
Levana Chen, Google
Nihav Jain, Google
Jürgen Sturm, Google

Genel Bakış

Bu uzantı, temel XR_ANDROID_light_estimation uzantısı üzerine kurulmuştur. Küresel harita ışık tahminleri alma desteği eklenir. Bu sayede, fiziksel ortamdaki ışıklandırma hakkında daha ayrıntılı tahminler sağlanır.

Not

Işık tahmini verilerini alma mekanizması, temel uzantıyla aynıdır. Ancak ışık tahmin edici tutamacı oluşturulurken XrCubemapLightEstimatorCreateInfoANDROID, XrLightEstimatorCreateInfoANDROID'e zincirlenmelidir.

Sistem kapasitesini inceleme

typedef struct XrSystemCubemapLightEstimationPropertiesANDROID {
    XrStructureType    type;
    void*              next;
    XrBool32           supportsCubemapLightEstimation;
} XrSystemCubemapLightEstimationPropertiesANDROID;

Ü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.
  • supportsCubemapLightEstimation , geçerli sistemin küp haritası ışık tahminini destekleyip desteklemediğini belirten bir XrBool32 değeridir.

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

Çalışma zamanı, XR_FALSE için supportsCubemapLightEstimation değerini döndürürse ve XrCubemapLightEstimatorCreateInfoANDROID, XrLightEstimatorCreateInfoANDROID ile zincirlenmişse çalışma zamanı, xrCreateLightEstimatorANDROID işlevinden XR_ERROR_FEATURE_UNSUPPORTED değerini döndürmelidir .

Geçerli Kullanım (Dolaylı)

Desteklenen küp haritası çözünürlüklerini alma

XrResult xrEnumerateCubemapLightingResolutionsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    resolutionCapacityInput,
    uint32_t*                                   resolutionCountOutput,
    uint32_t*                                   resolutions);

Parametre Açıklamaları

  • instance, daha önce oluşturulmuş bir XrInstance'tır.
  • systemId, desteklenen kübik harita çözünürlüklerinin alınacağı, xrGetSystem tarafından daha önce alınan XrSystemId değeridir.
  • resolutionCapacityInput, resolutions dizisinde depolanabilecek maksimum öğe sayısını gösteren bir uint32_t'dir.
  • resolutionCountOutput, çalışma zamanı tarafından resolutions dizisine yazılan öğelerin sayısını belirten, çalışma zamanı tarafından ayarlanan bir uint32_t işaretçisidir.
  • resolutions, desteklenen kübik harita çözünürlükleriyle çalışma zamanında doldurulan bir uint32_t dizisidir.

Bir küp haritası çözünürlüğü, küp haritasının her yüzünün piksel cinsinden genişliğini ve yüksekliğini gösterir. 2 çağrılı deyim Uygulama, ışık tahmin edici tutamacını oluştururken XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution içinde desteklenen çözünürlüklerden birini kullanmayı seçebilir. Uygulama, seçilen çözünürlüğe ve renk biçimine göre XrCubemapLightingDataANDROID öğesinin görüntü arabelleği üyeleri için uygun miktarda bellek ayırmalıdır.

Geçerli Kullanım (Dolaylı)

  • xrEnumerateCubemapLightingResolutionsANDROID çağrılmadan önce XR_ANDROID_light_estimation_cubemap uzantısı etkinleştirilmelidir.
  • instance geçerli bir XrInstance işleyeni olmalıdır.
  • resolutionCountOutput, uint32_t değerine yönelik bir işaretçi olmalıdır.
  • resolutionCapacityInput değeri 0 değilse resolutions , resolutionCapacityInput uint32_t değerlerinden oluşan bir dizinin işaretçisi olmalıdır.

Dönüş Kodları

Başarılı

  • XR_SUCCESS

Başarısız

  • 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

Desteklenen küp haritası renk biçimlerini alma

XrCubemapLightingColorFormatANDROID numaralandırması, küp haritası aydınlatmasının kullanılacak renk biçimini çalışma zamanına bildirir.

typedef enum XrCubemapLightingColorFormatANDROID {
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID = 1,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID = 2,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID = 3,
    XR_CUBEMAP_LIGHTING_COLOR_FORMAT_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrCubemapLightingColorFormatANDROID;

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

Enum Açıklaması

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID

Her kanalın 32 bit kayan nokta değeri olduğu 3 kanallı bir renk biçimi.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID

Her kanalın 32 bit kayan nokta değeri olduğu 4 kanallı bir renk biçimi.

XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID

Her kanalın 16 bit kayan nokta değeri olduğu 4 kanallı bir renk biçimi.

XrResult xrEnumerateCubemapLightingColorFormatsANDROID(
    XrInstance                                  instance,
    XrSystemId                                  systemId,
    uint32_t                                    colorFormatCapacityInput,
    uint32_t*                                   colorFormatCountOutput,
    XrCubemapLightingColorFormatANDROID*        colorFormats);

Parametre Açıklamaları

  • instance, daha önce oluşturulmuş bir XrInstance'tır.
  • systemId, desteklenen kübik harita çözünürlüklerinin alınacağı, xrGetSystem tarafından daha önce alınan XrSystemId değeridir.
  • colorFormatCapacityInput, colorFormats dizisinde depolanabilecek maksimum öğe sayısını gösteren bir uint32_t'dir.
  • colorFormatCountOutput, çalışma zamanı tarafından colorFormats dizisine yazılan öğelerin sayısını belirten, çalışma zamanı tarafından ayarlanan bir uint32_t işaretçisidir.
  • colorFormats, desteklenen küp haritası renk biçimleriyle çalışma zamanında doldurulan bir XrCubemapLightingColorFormatANDROID dizisidir.

2 çağrılı deyim: Uygulama, ışık tahmin edici tutamacını oluştururken XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat içinde desteklenen renk biçimlerinden birini kullanmayı seçebilir. Uygulama, seçilen renk biçimine göre XrCubemapLightingDataANDROID'in görüntü arabelleği üyeleri için uygun miktarda bellek ayırmalıdır.

Geçerli Kullanım (Dolaylı)

Dönüş Kodları

Başarılı

  • XR_SUCCESS

Başarısız

  • 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

Küresel harita ışık tahmin aracı oluşturma

typedef struct XrCubemapLightEstimatorCreateInfoANDROID {
    XrStructureType                        type;
    const void*                            next;
    uint32_t                               cubemapResolution;
    XrCubemapLightingColorFormatANDROID    colorFormat;
    XrBool32                               reproject;
} XrCubemapLightEstimatorCreateInfoANDROID;

Üye Açıklamaları

  • type, bu yapının XrStructureType'ıdır.
  • next, NULL veya bir yapı zincirindeki sonraki yapının işaretçisidir.
  • cubemapResolution, kullanılacak kübik harita aydınlatmasının çözünürlüğünü gösteren bir uint32_t'dir.
  • colorFormat, kullanılacak küp haritası ışıklandırma verilerinin renk biçimini belirten bir XrCubemapLightingColorFormatANDROID değeridir.
  • reproject, küp haritası ışıklandırmasının uygulama taban alanına yeniden yansıtılıp yansıtılmayacağını gösteren bir XrBool32 değeridir.

XrCubemapLightEstimatorCreateInfoANDROID yapısı, küp haritası aydınlatma tahminleri sağlayabilecek bir XrLightEstimatorANDROID tutacı oluşturmak için gereken bilgileri açıklar. XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution üyesi, xrEnumerateCubemapLightingResolutionsANDROID tarafından döndürülen çözünürlüklerden birine ayarlanmalıdır . XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat üyesi, xrEnumerateCubemapLightingColorFormatsANDROID tarafından döndürülen renk biçimlerinden birine ayarlanmalıdır . Uygulama, çözünürlüğü desteklenen çözünürlüklerden birine veya renk biçimini desteklenen renk biçimlerinden birine ayarlamazsa çalışma zamanı, xrCreateLightEstimatorANDROID işlevinden XR_ERROR_FEATURE_UNSUPPORTED değerini döndürmelidir.

Geçerli Kullanım (Dolaylı)

Cubemap ışık tahminleri

typedef struct XrCubemapLightingDataANDROID {
    XrStructureType                type;
    void*                          next;
    XrLightEstimateStateANDROID    state;
    uint32_t                       imageBufferSize;
    uint8_t*                       imageBufferRight;
    uint8_t*                       imageBufferLeft;
    uint8_t*                       imageBufferTop;
    uint8_t*                       imageBufferBottom;
    uint8_t*                       imageBufferFront;
    uint8_t*                       imageBufferBack;
    XrQuaternionf                  rotation;
    XrTime                         centerExposureTime;
} XrCubemapLightingDataANDROID;

Ü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 XrAmbientLightANDROID, XrSphericalHarmonicsANDROID ve XrDirectionalLightANDROID'dir .
  • state, ışık tahmini durumunu temsil eden XrLightEstimateStateANDROID değeridir.
  • imageBufferSize, küp haritasındaki her yüz görüntüsü arabelleğinin bayt boyutunu gösteren bir uint32_t'dir.
  • imageBufferRight, küp haritasının sağ yüz görüntüsünü içeren bir uint8_t arabelleğidir.
  • imageBufferLeft, küp haritasının sol yüz görüntüsünü içeren bir uint8_t arabelleğidir.
  • imageBufferTop, küp haritasının üst yüz görüntüsünü içeren bir uint8_t arabelleğidir.
  • imageBufferBottom, küp haritasının alt yüz görüntüsünü içeren bir uint8_t arabelleğidir.
  • imageBufferFront, küp haritasının ön yüz görüntüsünü içeren bir uint8_t arabelleğidir.
  • imageBufferBack, küp haritasının arka yüz görüntüsünü içeren bir uint8_t arabelleğidir.
  • rotation, küp haritasının döndürülmesini gösteren bir XrQuaternionf değeridir.
  • centerExposureTime, küp haritasının çekildiği zamanı gösteren bir XrTime'dir.

Bu yapı, XrLightEstimateANDROID ile zincirlenebilir. Çalışma zamanı, bu yapıyı yalnızca ışık tahmin edici tutma yeri oluşturmak için XrCubemapLightEstimatorCreateInfoANDROID kullanıldıysa xrGetLightEstimateANDROID içinde doldurmalıdır. Uygulama, ışık tahmin edici tutacını oluştururken XrCubemapLightEstimatorCreateInfoANDROID :: cubemapResolution ve XrCubemapLightEstimatorCreateInfoANDROID :: colorFormat içinde ayarlanan değerlere bağlı olarak görüntü arabellekleri için uygun miktarda bellek ayırmalıdır. Uygulama, XrCubemapLightingDataANDROID :: imageBufferSize değerini her yüz resmi arabelleğinin kapasitesine (bayt cinsinden) ayarlamalıdır. Uygulama küp haritası ışık tahmini kullanmıyorsa veya XrCubemapLightingDataANDROID :: imageBufferSize, çalışma zamanının görüntü arabelleklerini doldurması için yeterince büyük değilse çalışma zamanı XrCubemapLightingDataANDROID :: state değerini XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID olarak ayarlamalıdır .

Uygulama, ışık tahmin edici tutamacını oluştururken XrCubemapLightEstimatorCreateInfoANDROID :: reproject değerini XR_TRUE olarak ayarlarsa çalışma zamanı XrCubemapLightingDataANDROID :: rotation değerini kimlik rotasyonu olarak ayarlamalı ve dahili olarak döndürülmüş küp haritanın, uygulama taban alanındaki bir kimlik küp haritasının yüzlerine yeniden yansıtılmasını sağlamalıdır.

Işıklandırma küp haritasının düzeni, aşağıdaki resimde gösterildiği gibi OpenGL küp haritası düzeniyle aynıdır.

XR ANDROID ışık tahmini kübik harita düzeni

Şekil 24. Cubemap düzeni.

Geçerli Kullanım (Dolaylı)

  • XrCubemapLightingDataANDROID kullanılmadan önce XR_ANDROID_light_estimation_cubemap uzantısı etkinleştirilmelidir.
  • type XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID olmalıdır.
  • next must be NULL or a valid pointer to the next structure in a structure chain
  • state geçerli bir XrLightEstimateStateANDROID değeri olmalıdır.
  • imageBufferRight must be a pointer to an array of imageBufferSize uint8_t values
  • imageBufferLeft must be a pointer to an array of imageBufferSize uint8_t values
  • imageBufferTop must be a pointer to an array of imageBufferSize uint8_t values
  • imageBufferBottom must be a pointer to an array of imageBufferSize uint8_t values
  • imageBufferFront must be a pointer to an array of imageBufferSize uint8_t values
  • imageBufferBack must be a pointer to an array of imageBufferSize uint8_t values
  • imageBufferSize parametresi 0 değerinden büyük olmalıdır.

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
XrInstance instance; // Created at app startup
XrSpace appSpace;   // Created previously.
XrSystemId systemId; // Retrieved previously by xrGetSystem
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingResolutionsANDROID xrEnumerateCubemapLightingResolutionsANDROID; // Created previously.
PFN_xrEnumerateCubemapLightingColorFormatsANDROID xrEnumerateCubemapLightingColorFormatsANDROID; // Created previously.

XrSystemCubemapLightEstimationPropertiesANDROID props = {
  .type = XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID};
XrSystemProperties base = {.type = XR_TYPE_SYSTEM_PROPERTIES,
                           .next = &props};
CHK_XR(xrGetSystemProperties(instance, systemId, &base));
if (!props.supportsCubemapLightEstimation) {
   // Cubemap light estimation is not supported
}

uint32_t cubemapResolution = 0;
std::vector<uint32_t> supportedCubemapResolutions;
uint32_t resolutionCount;
CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
  instance, systemId, 0, &resolutionCount, nullptr));
supportedCubemapResolutions.resize(resolutionCount);
if (resolutionCount == 0) {
  // No cubemap lighting supported
} else {
  CHK_XR(xrEnumerateCubemapLightingResolutionsANDROID(
    instance, systemId, 0, &resolutionCount, supportedCubemapResolutions.data()));
  cubemapResolution = supportedCubemapResolutions[0];
}

uint32_t pixelCount = cubemapResolution * cubemapResolution;

XrCubemapLightingColorFormatANDROID colorFormat;
std::vector<XrCubemapLightingColorFormatANDROID> supportedColorFormats;
uint32_t colorFormatCount;
CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
  instance, systemId, 0, &colorFormatCount, nullptr));
supportedColorFormats.resize(colorFormatCount);
if (colorFormatCount == 0) {
  // No supported color formats for cubemap lighting. Cannot use cubemap
  // light estimation.
} else {
  CHK_XR(xrEnumerateCubemapLightingColorFormatsANDROID(
    instance, systemId, 0, &colorFormatCount, supportedColorFormats.data()));
  colorFormat = supportedColorFormats[0];
}

uint32_t pixelSize = 0;
switch (colorFormat) {
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32_SFLOAT_ANDROID:
    pixelSize = 3 * sizeof(float);
    break;
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R32G32B32A32_SFLOAT_ANDROID:
    pixelSize = 4 * sizeof(float);
    break;
  case XR_CUBEMAP_LIGHTING_COLOR_FORMAT_R16G16B16A16_SFLOAT_ANDROID:
    pixelSize = 4 * sizeof(uint16_t);
    break;
  default:
    // Should not happen since the color format was validated previously.
    break;
}

uint32_t perFaceImageBufferSize = pixelCount * pixelSize;

XrLightEstimatorANDROID estimator;
XrCubemapLightEstimatorCreateInfoANDROID cubemapCreateInfo = {
    .type = XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
    .cubemapResolution = cubemapResolution,
    .colorFormat = colorFormat,
    .reproject = XR_TRUE
};
XrLightEstimatorCreateInfoANDROID basicCreateInfo = {
    .type = XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID,
    .next = &cubemapCreateInfo};
CHK_XR(xrCreateLightEstimatorANDROID(session, &basicCreateInfo, &estimator));

std::vector<uint8_t> cubemapBuffer(perFaceImageBufferSize * 6); // 6 faces * perFaceImageBufferSize

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

XrCubemapLightingDataANDROID cubemap = {
    .type = XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID,
    .next = nullptr,
    .imageBufferSize = perFaceImageBufferSize,
    .imageBufferRight = cubemapBuffer.data() + 0 * perFaceImageBufferSize,
    .imageBufferLeft = cubemapBuffer.data() + 1 * perFaceImageBufferSize,
    .imageBufferTop = cubemapBuffer.data() + 2 * perFaceImageBufferSize,
    .imageBufferBottom = cubemapBuffer.data() + 3 * perFaceImageBufferSize,
    .imageBufferFront = cubemapBuffer.data() + 4 * perFaceImageBufferSize,
    .imageBufferBack = cubemapBuffer.data() + 5 * perFaceImageBufferSize,
};

XrDirectionalLightANDROID directionalLight = {
    .type = XR_TYPE_DIRECTIONAL_LIGHT_ANDROID,
    .next = &cubemap,
};

XrSphericalHarmonicsANDROID totalSh = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
    .kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID,
};

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

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 cubemap, directionalLight, totalSh, ambientSh, and
  // ambientLight if each struct has a valid state field

  if (cubemap.state == XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID) {
    // use cubemap
    if (cubemapCreateInfo.reproject == XR_TRUE) {
      XrQuaternionf identityQuaternion = {0.0f, 0.0f, 0.0f, 1.0f};
      assert(memcmp(&cubemap.rotation, &identityQuaternion, sizeof(XrQuaternionf)) == 0);
    }
  }
}

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

Yeni Komutlar

Yeni Yapılar

Yeni Sıralamalar

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

  • XR_ANDROID_LIGHT_ESTIMATION_CUBEMAP_EXTENSION_NAME
  • XR_ANDROID_light_estimation_cubemap_SPEC_VERSION
  • XrStructureType'ı genişletme :

    • XR_TYPE_CUBEMAP_LIGHTING_DATA_ANDROID
    • XR_TYPE_CUBEMAP_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SYSTEM_CUBEMAP_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Sorunlar

Sürüm Geçmişi

  • Düzeltme 1, 2025-12-05 (Salar Khan)

    • İlk uzantı açıklaması