XR_ANDROID_light_estimation

Name String

XR_ANDROID_light_estimation

Loại tiện ích

Tiện ích phiên bản

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

701

Bản sửa đổi

1

Trạng thái phê chuẩn

Chưa được phê chuẩn

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-03-13

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 thể hiện ánh sáng của môi trường thực tế xung quanh tai nghe. Ứng dụng có thể sử dụng thông tin này để chiếu sáng các đối tượng ảo trong cùng điều kiện với cảnh thực tế mà các đối tượng đó được đặt vào.

Quyền

Các ứng dụng Android phải có quyền android.permission.SCENE_UNDERSTANDING_COARSE trong tệp kê khai vì tiện ích này cho biết thông tin về ánh sáng của môi trường. Quyền android.permission.SCENE_UNDERSTANDING_COARSE được coi là một quyền nguy hiểm. Ứng dụng phải yêu cầu cấp quyền trong thời gian chạy để sử dụng các chức năng này:

(cấp độ bảo vệ: nguy hiểm)

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

Cấu trúc XrSystemLightEstimationPropertiesANDROID được xác định như sau:

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 và chỉ nếu một thời gian chạy trả về XR_FALSE cho supportsLightEstimation , thì thời gian chạy phải trả về XR_ERROR_FEATURE_UNSUPPORTED từ xrCreateLightEstimatorANDROID .

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

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

XR_DEFINE_HANDLE(XrLightEstimatorANDROID)

Dữ liệu ước tính ánh sáng được tạo bởi thời gian chạy và chia sẻ với ứng dụng bằng cách sử dụng giá trị nhận dạng XrLightEstimatorANDROID.

Bạn có thể dùng đối tượng 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 bộ ước tính ánh sáng.
  • createInfo là con trỏ đến một 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 này dùng hàm xrCreateLightEstimatorANDROID để tạo một bộ ước tính ánh sáng.

  • Thời gian chạy phải 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.
  • Thời gian chạy phải trả về XR_ERROR_PERMISSION_INSUFFICIENT nếu ứng dụng gọi điện chưa được cấp các quyền cần thiết.

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 hủy bỏ ô điều khiển thông qua xrDestroyLightEstimatorANDROID .

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

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • XR_ERROR_FEATURE_UNSUPPORTED
  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_LIMIT_REACHED
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_PERMISSION_INSUFFICIENT
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST

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

typedef struct XrLightEstimatorCreateInfoANDROID {
    XrStructureType    type;
    const 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.

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

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

XrResult xrDestroyLightEstimatorANDROID(
    XrLightEstimatorANDROID                     estimator);

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

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

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

Độ 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ố

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

Mã trả về

Thành công

  • XR_SUCCESS
  • XR_SESSION_LOSS_PENDING

Thất bại

  • XR_ERROR_FUNCTION_UNSUPPORTED
  • XR_ERROR_HANDLE_INVALID
  • XR_ERROR_INSTANCE_LOST
  • XR_ERROR_OUT_OF_MEMORY
  • XR_ERROR_RUNTIME_FAILURE
  • XR_ERROR_SESSION_LOST
  • XR_ERROR_TIME_INVALID
  • XR_ERROR_VALIDATION_FAILURE

Cấu trúc XrLightEstimateGetInfoANDROID được xác định như sau:

typedef struct XrLightEstimateGetInfoANDROID {
    XrStructureType    type;
    const 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 và các hàm điều hoà cầu được biểu thị trong đó.
  • time là XrTime mô tả thời điểm ứng dụng muốn truy vấn thông tin ước tính về ánh sáng.

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

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

Đối với mọi cấu trúc ước tính ánh sáng, nếu state là XR_LIGHT_ESTIMATE_STATE_INVALID_ANDROID, thì tất cả các trường khác trong cấu trúc đều là tuỳ ý, tức là các giá trị của chúng không xác định.

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

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

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ệ bao gồm 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 XrVector3f đại diện cho 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 XrVector3f có các giá trị trong không gian gamma. Nếu kết xuất trong không gian màu gamma, hãy nhân các thành phần đó theo từng thành phần với màu đã tính toán cuối cùng sau khi kết xuất. Nếu kết xuất trong không gian tuyến tính, trước tiên hãy chuyển đổi các giá trị thành không gian tuyến tính bằng cách tăng lên lũy thừa 2,2, sau đó nhân theo thành phần với màu đã tính toán cuối cùng sau khi kết xuất.

    The purpose of pname:colorCorrection is to make a scene appear natural and
blend with the real world.

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

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

  • 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ệ bao gồm 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.
  • kind là XrSphericalHarmonicsKindANDROID mà ứ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ố điều hoà cầu.

coefficients sẽ được dùng trong một hàm đặc biệt nhận hướng làm dữ liệu đầu vào và xuất màu ánh sáng đến từ hướng đó. Bạn có thể xem thêm thông tin chi tiết trong bài viết này .

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

Liệt kê XrSphericalHarmonicsKindANDROID để xác định 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,
    XR_SPHERICAL_HARMONICS_KIND_MAX_ENUM_ANDROID = 0x7FFFFFFF
} XrSphericalHarmonicsKindANDROID;

Các giá trị liệt kê có ý nghĩa như sau:

Nội dung mô tả enum

XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID

Các hệ số điều hoà cầu thể hiện hàm độ chói á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 thể hiện hàm độ chói ánh sáng môi trường, bao gồm cả đóng góp từ ánh sáng chính.

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

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

Liệt kê XrLightEstimateStateANDROID cho biết trạng thái của thông tin ước tính về ánh sáng do thời gian chạy trả về.

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

Các giá trị liệt kê có ý nghĩa như sau:

Nội dung mô tả enum

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.
PFN_xrCreateLightEstimatorANDROID xrCreateLightEstimatorANDROID; // Created previously.
PFN_xrDestroyLightEstimatorANDROID xrDestroyLightEstimatorANDROID; // Created previously.
PFN_xrGetLightEstimateANDROID xrGetLightEstimateANDROID; // 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 sphericalHarmonics = {
    .type = XR_TYPE_SPHERICAL_HARMONICS_ANDROID,
    .next = &directionalLight,
};

// Querying both TOTAL or AMBIENT spherical harmonics in one call will result in an error because chaining two structs with the same type is not allowed
bool useTotalSH;
if (useTotalSH) {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_TOTAL_ANDROID;
} else {
  sphericalHarmonics.kind = XR_SPHERICAL_HARMONICS_KIND_AMBIENT_ANDROID;
}

XrAmbientLightANDROID ambientLight = {
    .type = XR_TYPE_AMBIENT_LIGHT_ANDROID,
    .next = &sphericalHarmonics,
};

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

Lệnh mới

Cấu trúc mới

Enum mới

Hằng số Enum mới

  • XR_ANDROID_LIGHT_ESTIMATION_EXTENSION_NAME
  • XR_ANDROID_light_estimation_SPEC_VERSION

  • Mở rộng XrObjectType :

    • XR_OBJECT_TYPE_LIGHT_ESTIMATOR_ANDROID

  • Mở rộng XrStructureType :

    • XR_TYPE_AMBIENT_LIGHT_ANDROID
    • XR_TYPE_DIRECTIONAL_LIGHT_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_ANDROID
    • XR_TYPE_LIGHT_ESTIMATE_GET_INFO_ANDROID
    • XR_TYPE_LIGHT_ESTIMATOR_CREATE_INFO_ANDROID
    • XR_TYPE_SPHERICAL_HARMONICS_ANDROID
    • XR_TYPE_SYSTEM_LIGHT_ESTIMATION_PROPERTIES_ANDROID

Vấn đề

Nhật ký phiên bản

  • 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