Tiện ích OpenXR XR_ANDROID_light_estimation

Chuỗi tên

XR_ANDROID_light_estimation

Loại phần mở rộng

Tiện ích thực thể

Số điện thoại mở rộng đã đăng ký

701

Bản sửa đổi

1

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

OpenXR 1.0

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

2024-09-18

Trạng thái IP

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

Cộng tác viên

Jared Finder, Google

Cairn Overturf, Google

Spencer Quin, Google

Levana Chen, Google

Nihav Jain, Google

Tổng quan

Tiện ích này cho phép ứng dụng yêu cầu dữ liệu thể hiện á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 các đối tượng đó trong cùng điều kiện với cảnh mà các đối tượng đó được đặt trong đó.

Kiểm tra chức năng của hệ thống

Ứ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 tạo chuỗi 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ỏ 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à 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.

Ứ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 không thể hỗ trợ tính năng ước tính ánh sáng, hệ thống sẽ trả về XR_FALSE cho supportsLightEstimation và XR_ERROR_FEATURE_UNSUPPORTED từ xrCreateLightEstimatorANDROID.

Cách sử dụng hợp lệ (ngầm ẩn)

Tạo một tên người dùng của trình ước tính ánh sáng

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Tay cầm XrLightEstimatorANDROID đại diện cho một công cụ ước tính ánh sáng. Bạn có thể sử dụng tay điều khiển 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 là: 

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

Nội dung mô tả tham số

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

Ứng dụng có thể sử dụng hàm xrCreateLightEstimatorANDROID để tạo một trình ướ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 các quyền cần thiết chưa được cấp cho ứng dụng gọi.

Sau đó, bạn có thể sử dụng tay cầm trình ướ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 vào dữ liệu ước tính ánh sáng, thì ứng dụng phải huỷ tay cầm bằng cách sử dụng xrDestroyLightEstimatorANDROID.

Cách sử dụng hợp lệ (ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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 tay điều khiển 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ỏ 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.

Cách sử dụng hợp lệ (ngầm ẩn)

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

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

Nội dung mô tả tham số

Cách 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 tay điều khiển con phải được đồng bộ hoá bên ngoài

Mã trả về

Thành công

  • XR_SUCCESS

Không thành công

  • 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 là: 

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

Nội dung mô tả tham số

Cách sử dụng hợp lệ (ngầm ẩn)

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Không thành công

  • 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 để lấy 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ỏ 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 trong đó hướng ánh sáng trả về và hàm điều hoà hình cầu được thể hiện.
  • 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.

Cách 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 ánh sáng môi trường xung quanh, hàm điều hoà hình cầu và ánh sáng định hướng chính, các ứng dụng có thể tạo chuỗi các thực thể của các cấu trúc sau, XrAmbientLightANDROID, XrSphericalHarmonicsANDROID và XrDirectionalLightANDROID tương ứng trên XrLightEstimateANDROID::next.

Cách sử dụng hợp lệ (ngầm ẩn)

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ỏ 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 và XrDirectionalLightANDROID.
  • state là XrLightEstimateStateANDROID đại diện cho trạng thái của giá trị ước tính ánh sáng.
  • intensity là một XrVector3 thể hiện cường độ của ánh sáng môi trường xung quanh. Mỗi thành phần của vectơ tương ứng với kênh màu đỏ, xanh lục và xanh lam.
  • colorCorrection là XrVector3 có các giá trị trong không gian gamma. Nhân màu của kết xuất gamma đã sửa bằng các giá trị này theo từng thành phần.

Cách sử dụng hợp lệ (ngầm ẩn)

Cấu trúc XrSphericalHarmonicsANDROID chứa các hàm điều hoà hình 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

  • type là XrStructureType của cấu trúc này.
  • next là NULL hoặc con trỏ 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 và XrDirectionalLightANDROID.
  • state là XrLightEstimateStateANDROID đại diện cho trạng thái của giá trị ước tính ánh sáng.
  • kind là XrSphericalHarmonicsKindANDROID do ứng dụng yêu cầu.
  • coefficients là một mảng float hai chiều có kích thước 9 hàng và 3 cột. 3 cột tương ứng với các kênh màu đỏ, xanh lục và xanh dương. Mỗi kênh có 9 hệ số hài hình cầu.

Cách 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ỏ 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 giá trị ước tính ánh sáng.
  • intensity là một XrVector3 đại diện cho cường độ của ánh sáng định hướng. Mỗi thành phần của vectơ tương ứng với kênh màu đỏ, xanh lục và xanh lam.
  • direction là một XrVector3 đại diện cho hướng ánh sáng.

Cách sử dụng hợp lệ (ngầm ẩn)

Biến liệt kê XrSphericalHarmonicsKindANDROID xác định cho thời gian chạy, loại hàm điều hoà hình 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

Hệ số hài hình cầu biểu thị hàm độ sáng của ánh sáng môi trường, ngoại trừ phần đóng góp của ánh sáng chính.

XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID

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

Biến liệt kê XrLightEstimateStateANDROID xác định cho thời gian chạy, loại hàm điều hoà hình 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

Đèn ước tính là hợp lệ

XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID

Đơn giá ước tính của ánh sáng không hợp lệ

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

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

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

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

  • XrLightEstimator

Bổ sung enum XrObjectType bằng:

  • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

Bổ sung enum XrStructureType:

  • 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

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 1, ngày 16 tháng 9 năm 2024 (Cairn Overturf)
    • Nội dung mô tả ban đầu của tiện ích