Tiện ích OpenXR XR_ANDROID_light_estimation

Name String

XR_ANDROID_light_estimation

Loại phần mở rộng

Tiện ích phiên bản

Số máy nhánh đã đăng ký

701

Bản sửa đổi

1

Phần mở rộng và các phần phụ thuộc vào phiên bản

OpenXR 1.0

Ngày sửa đổi gần đây nhất

2025-01-17

Trạng thái IP

Không có thông báo xác nhận quyền sở hữu nào đã biết về quyền sở hữu trí tuệ.

Cộng tác viên

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, Google

Salar Khan, Google

Scott Chung, Google

Tổng quan

Tiện ích này cho phép ứng dụng yêu cầu dữ liệu biểu thị ánh sáng của môi trường thực tế xung quanh tai nghe. Bạn có thể sử dụng thông tin này khi kết xuất các đối tượng ảo để chiếu sáng chúng trong cùng điều kiện với cảnh mà chúng được đặt vào.

Kiểm tra khả năng của hệ thống

Một ứng dụng có thể kiểm tra xem hệ thống có hỗ trợ tính năng ước tính ánh sáng hay không bằng cách liên kết một cấu trúc XrSystemLightEstimationPropertiesANDROID với XrSystemProperties khi gọi xrGetSystemProperties. 

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.
  • supportsLightEstimation là một XrBool32, cho biết liệu hệ thống hiện tại có hỗ trợ tính năng ước tính ánh sáng hay không.

Một ứng dụng có thể kiểm tra xem hệ thống có hỗ trợ tính năng ước tính ánh sáng hay không bằng cách mở rộng XrSystemProperties bằng cấu trúc XrSystemLightEstimationPropertiesANDROID khi gọi xrGetSystemProperties.

Nếu hệ thống không hỗ trợ tính năng ước tính ánh sáng, thì hệ thống sẽ trả về XR_FALSE cho supportsLightEstimation và XR_ERROR_FEATURE_UNSUPPORTED từ xrCreateLightEstimatorANDROID.

Sử dụng hợp lệ (Ngầm ẩn)

Tạo một đối tượng ước tính ánh sáng

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Xử lý XrLightEstimatorANDROID đại diện cho một công cụ ước tính ánh sáng. Bạn có thể dùng xử lý này để truy cập thông tin ước tính ánh sáng bằng các hàm khác trong tiện ích này.

Hàm xrCreateLightEstimatorANDROID được xác định như sau: 

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

Nội dung mô tả về tham số

  • session là XrSession tạo ra công cụ ước tính ánh sáng.
  • createInfo là con trỏ đến cấu trúc XrLightEstimatorCreateInfoANDROID chứa các tham số sẽ được dùng để tạo bộ ước tính ánh sáng.
  • outHandle là con trỏ đến một đối tượng mà XrLightEstimatorANDROID đã tạo sẽ được trả về.

Ứng dụng có thể dùng hàm xrCreateLightEstimatorANDROID để tạo một bộ ước tính ánh sáng.

  • xrCreateLightEstimatorANDROID sẽ trả về XR_ERROR_FEATURE_UNSUPPORTED nếu hệ thống không hỗ trợ tính năng ước tính ánh sáng.
  • xrCreateLightEstimatorANDROID sẽ trả về XR_ERROR_PERMISSION_INSUFFICIENT nếu ứng dụng gọi chưa được cấp các quyền cần thiết.

Sau đó, bạn có thể dùng tay cầm của bộ ước tính ánh sáng được trả về trong các lệnh gọi API. Nếu muốn cho thời gian chạy biết rằng ứng dụng đã truy cập xong dữ liệu ước tính ánh sáng, thì ứng dụng đó phải huỷ tay cầm bằng xrDestroyLightEstimatorANDROID.

Sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • 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

Cấu trúc XrLightEstimatorCreateInfoANDROID mô tả thông tin để tạo một đối tượng XrLightEstimatorANDROID. 

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Không có cấu trúc nào như vậy được xác định trong OpenXR cốt lõi hoặc tiện ích này.

Sử dụng hợp lệ (Ngầm ẩn)

Hàm xrDestroyLightEstimatorANDROID giải phóng estimator và mọi tài nguyên cơ bản. 

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Nội dung mô tả về tham số

Sử dụng hợp lệ (Ngầm ẩn)

Độ an toàn cho luồng

  • Quyền truy cập vào estimator và mọi đối tượng con phải được đồng bộ hoá bên ngoài

Mã trả về

Thành công

  • XR_SUCCESS

Thất bại

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID

Truy cập dữ liệu ước tính ánh sáng

Hàm xrGetLightEstimateANDROID được xác định như sau: 

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

Nội dung mô tả về tham số

Sử dụng hợp lệ (Ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • 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 mô tả thông tin cần thiết để nhận dữ liệu ước tính ánh sáng. 

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc.
  • space là XrSpace xác định không gian tham chiếu mà hướng ánh sáng, các hàm điều hoà cầu và hướng xoay cubemap được biểu thị.
  • time là XrTime mô tả thời điểm ứng dụng muốn truy vấn thông tin ước tính ánh sáng.

Sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc XrLightEstimateANDROID chứa dữ liệu ước tính ánh sáng. 

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

Nội dung mô tả thành viên

Để lấy thông tin ước tính ánh sáng cho cubemap ánh sáng môi trường, ánh sáng xung quanh, hài cầu và ánh sáng định hướng chính, các ứng dụng có thể xâu chuỗi các thực thể của các cấu trúc sau, XrEnvironmentLightingCubemapANDROID, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID và XrDirectionalLightANDROID tương ứng trên XrLightEstimateANDROID::next.

Sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc XrEnvironmentLightingCubemapANDROID chứa dữ liệu ước tính ánh sáng ở định dạng cubemap về ánh sáng môi trường của cảnh. 

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;

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Các cấu trúc hợp lệ là XrSphericalHarmonicsANDROID, XrAmbientLightANDROID và XrDirectionalLightANDROID.
  • state là XrLightEstimateStateANDROID đại diện cho trạng thái của thông tin ước tính về ánh sáng.
  • cubemapRightImage là một float* đại diện cho vùng đệm R32G32B32_SFLOAT ở phía bên phải của cubemap. Xin lưu ý rằng đây là HDR nên các giá trị dấu phẩy động có thể lớn hơn 1.0.
  • cubemapLeftImage là một float* đại diện cho vùng đệm R32G32B32_SFLOAT ở phía bên trái của cubemap. Xin lưu ý rằng đây là HDR nên các giá trị dấu phẩy động có thể lớn hơn 1.0.
  • cubemapTopImage là một float* đại diện cho vùng đệm R32G32B32_SFLOAT ở mặt trên của cubemap. Xin lưu ý rằng đây là HDR nên các giá trị dấu phẩy động có thể lớn hơn 1.0.
  • cubemapBottomImage là một float* đại diện cho vùng đệm R32G32B32_SFLOAT ở mặt dưới của cubemap. Xin lưu ý rằng đây là HDR nên các giá trị dấu phẩy động có thể lớn hơn 1.0.
  • cubemapFrontImage là một float* đại diện cho vùng đệm R32G32B32_SFLOAT ở mặt trước của cubemap. Xin lưu ý rằng đây là HDR nên các giá trị dấu phẩy động có thể lớn hơn 1.0.
  • resolution là một uint32_t biểu thị chiều rộng và chiều cao của hình ảnh ở mỗi mặt của cubemap.
  • rotation là một XrQuaternionf biểu thị hướng xoay của cubemap.
  • centerExposureTime là một XrTime biểu thị thời gian chụp cubemap. Hữu ích cho việc nội suy giữa các cubemap.

Sử dụng hợp lệ (Ngầm ẩn)

  • Bạn phải bật tiện ích XR_ANDROID_light_estimation trước khi sử dụng XrEnvironmentLightingCubemapANDROID
  • type phải là XR_TYPE_ENVIRONMENT_LIGHTING_CUBEMAP_ANDROID
  • next phải là NULL hoặc một con trỏ hợp lệ đến cấu trúc tiếp theo trong chuỗi cấu trúc
  • state phải là một giá trị XrLightEstimateStateANDROID hợp lệ
  • cubemapRightImage phải là con trỏ đến một giá trị số thực hợp lệ
  • cubemapLeftImage phải là con trỏ đến một giá trị số thực hợp lệ
  • cubemapTopImage phải là con trỏ đến một giá trị số thực hợp lệ
  • cubemapBottomImage phải là con trỏ đến một giá trị số thực hợp lệ
  • cubemapFrontImage phải là con trỏ đến một giá trị số thực hợp lệ
  • cubemapBackImage phải là con trỏ đến một giá trị số thực hợp lệ

Cấu trúc XrAmbientLightANDROID chứa dữ liệu ước tính ánh sáng về ánh sáng xung quanh trong cảnh. 

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Các cấu trúc hợp lệ là XrSphericalHarmonicsANDROID, XrEnvironmentLightingCubemapANDROID và XrDirectionalLightANDROID.
  • state là XrLightEstimateStateANDROID đại diện cho trạng thái của thông tin ước tính về ánh sáng.
  • intensity là một XrVector3 biểu thị cường độ của ánh sáng xung quanh. Mỗi thành phần của vectơ tương ứng với các kênh màu đỏ, xanh lục và xanh dương.
  • colorCorrection là một XrVector3 có các giá trị trong không gian gamma. Nhân theo thành phần màu của bản kết xuất đã hiệu chỉnh gamma với các giá trị này.

Sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc XrSphericalHarmonicsANDROID chứa các hàm điều hoà cầu đại diện cho ánh sáng của cảnh. 

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

Nội dung mô tả thành viên

Sử dụng hợp lệ (Ngầm ẩn)

Cấu trúc XrDirectionalLightANDROID chứa dữ liệu ước tính ánh sáng. 

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

Nội dung mô tả thành viên

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ đến cấu trúc tiếp theo trong chuỗi cấu trúc. Các cấu trúc hợp lệ là XrAmbientLightANDROID, XrSphericalHarmonicsANDROID và XrDirectionalLightANDROID.
  • state là XrLightEstimateStateANDROID đại diện cho trạng thái của thông tin ước tính về ánh sáng.
  • intensity là một XrVector3 biểu thị cường độ của ánh sáng định hướng. Mỗi thành phần của vectơ tương ứng với các kênh màu đỏ, xanh lục và xanh lam.
  • direction là một XrVector3 đại diện cho hướng ánh sáng.

Sử dụng hợp lệ (Ngầm ẩn)

Liệt kê XrSphericalHarmonicsKindANDROID để xác định cho thời gian chạy, loại hàm điều hoà cầu mà ứng dụng đang yêu cầu. 

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

Các enum có ý nghĩa như sau:

Enum

Nội dung mô tả

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Các hệ số điều hoà cầu biểu thị hàm độ chói của ánh sáng môi trường, không bao gồm phần đóng góp của ánh sáng chính.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

Các hệ số điều hoà cầu biểu thị hàm độ chói của ánh sáng môi trường, bao gồm cả đóng góp của ánh sáng chính.

Liệt kê XrLightEstimateStateANDROID để xác định thời gian chạy, loại hài cầu mà ứng dụng đang yêu cầu. 

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

Các enum có ý nghĩa như sau:

Enum

Nội dung mô tả

XR_LIGHT_ESTIMATE_STATE_VALID_ANDROID

Thông tin ước tính về ánh sáng là hợp lệ

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

Thông tin ước tính về ánh sáng không hợp lệ

Mã ví dụ để ước tính ánh sáng

Đoạn mã ví dụ sau đây minh hoạ cách lấy tất cả các số lượng ước tính ánh sáng có thể có từ thời gian chạy.

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

Các loại đối tượng mới

  • XrLightEstimator

Liệt kê XrObjectType bằng:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

Liệt kê XrStructureType được mở rộng bằng:

  • 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

Enum mới

Cấu trúc mới

Hàm mới

Vấn đề

Nhật ký phiên bản

  • Bản sửa đổi 2, ngày 17/1/2025 (Salar Khan)
    • Thêm chế độ hỗ trợ cubemap ánh sáng môi trường
  • Bản sửa đổi 1, ngày 16/9/2024 (Cairn Overturf)
    • Nội dung mô tả ban đầu của tiện ích

OpenXR™ và biểu trưng OpenXR là các nhãn hiệu thuộc sở hữu của The Khronos Group Inc. và được đăng ký làm nhãn hiệu ở Trung Quốc, Liên minh Châu Âu, Nhật Bản và Vương quốc Anh.