XR_EXT_interaction_profile_battery_state_display
Name String
XR_EXT_interaction_profile_battery_state_display
擴充功能類型
執行個體擴充功能
擴充功能註冊編號
837
修訂版本
1
批准狀態
已批准
擴充功能和版本依附元件
上次修改日期
2025-10-21
IP 狀態
沒有已知的智慧財產權聲明。
著作人
John Kearney，Meta
Daniel Willmott，Valve
Denny Rönngren，Varjo
Jakob Bornecrantz，NVIDIA
Nathan Nuber，Valve
Lachlan Ford，Google
Nihav Jain，Google
總覽
XR_EXT_interaction_profile_battery_state_display 提供一種機制，讓應用程式查詢執行階段，取得與互動設定檔搭配使用的裝置電池狀態資訊。這項電池狀態資訊應僅用於顯示，且執行階段應確保這項資訊與內建系統使用者介面中使用的資訊相符。
如果有多個實體裝置為與頂層路徑相關聯的動作提供輸入內容，例如執行階段為使用者自訂或無障礙功能執行重新對應，則這些執行階段應盡可能以單一值呈現實用的電池資訊。
具體來說，這項資訊不應在執行階段或裝置之間校準，也「不應」用於產生警告或修改應用程式行為。
查詢電池狀態
XrBatteryStateDisplayEXT 結構定義如下：
typedef struct XrBatteryStateDisplayEXT {
XrStructureType type;
void* next;
XrBatteryStateDisplayStateFlagsEXT stateFlags;
float batteryLevel;
} XrBatteryStateDisplayEXT;
成員說明
type是這個結構的 XrStructureType。next是NULL，或指向結構鏈中下一個結構的指標。stateFlags使用 XrBatteryStateDisplayStateFlagBitsEXT 中定義的位元遮罩，說明batteryLevel的有效性batteryLevel是由相關聯實體或動作連結的裝置電池電量 (從 0.0f 到 1.0f)。
如要查詢電池電量，應用程式會在呼叫 xrGetCurrentInteractionProfile 時，將 XrBatteryStateDisplayEXT 結構鏈結至 XrInteractionProfileState :: next 鏈結。
如果 xrGetCurrentInteractionProfile 將 XrInteractionProfileState :: interactionProfile 設為 XR_NULL_PATH，則執行階段不得在 stateFlags 中設定 XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT 位元。
XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT 指出 batteryLevel 是否包含有效資料。如果 stateFlags 中未設定 XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT 位元，應用程式「不得」讀取 batteryLevel。
有效用途 (隱含)
- 您必須先啟用
XR_EXT_interaction_profile_battery_state_display擴充功能，才能使用 XrBatteryStateDisplayEXT -
type「必須」為XR_TYPE_BATTERY_STATE_DISPLAY_EXT -
next「必須」為NULL，或指向結構鏈中下一個結構的有效指標 -
stateFlags「必須」是 XrBatteryStateDisplayStateFlagBitsEXT 值的有效組合 -
stateFlags「不得」為0
XrBatteryStateDisplayEXT :: stateFlags 成員屬於下列類型，且包含 XrBatteryStateDisplayStateFlagBitsEXT 中定義的零或多個位元的位元 OR。
typedef XrFlags64 XrBatteryStateDisplayStateFlagsEXT;
// Flag bits for XrBatteryStateDisplayStateFlagsEXT
static const XrBatteryStateDisplayStateFlagsEXT XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT = 0x00000001;
static const XrBatteryStateDisplayStateFlagsEXT XR_BATTERY_STATE_DISPLAY_STATE_CHARGING_BIT_EXT = 0x00000002;
static const XrBatteryStateDisplayStateFlagsEXT XR_BATTERY_STATE_DISPLAY_STATE_PLUGGED_IN_BIT_EXT = 0x00000004;
static const XrBatteryStateDisplayStateFlagsEXT XR_BATTERY_STATE_DISPLAY_STATE_NO_BATTERY_BIT_EXT = 0x00000008;
旗標位元的意義如下：
旗標說明
XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT：表示 XrBatteryStateDisplayEXT ::batteryLevel的有效性XR_BATTERY_STATE_DISPLAY_STATE_CHARGING_BIT_EXT：表示與互動設定檔相關聯的裝置正在充電。XR_BATTERY_STATE_DISPLAY_STATE_PLUGGED_IN_BIT_EXT：表示與互動設定檔相關聯的裝置已接上電源。XR_BATTERY_STATE_DISPLAY_STATE_NO_BATTERY_BIT_EXT：表示與互動設定檔相關聯的裝置沒有電池電源。
範例
// previously initialized
extern XrSession session;
extern XrPath topLevelUserPath;
XrBatteryStateDisplayEXT batteryStateDisplay{XR_TYPE_BATTERY_STATE_DISPLAY_EXT};
XrInteractionProfileState ipState{XR_TYPE_INTERACTION_PROFILE_STATE, &batteryStateDisplay};
CHK_XR(xrGetCurrentInteractionProfile(session, topLevelUserPath, &ipState));
if ((batteryStateDisplay.stateFlags & XR_BATTERY_STATE_DISPLAY_STATE_VALID_BIT_EXT) != 0) {
// use value of batteryStateDisplay.batteryLevel
}
新結構
新列舉
新位元遮罩
新列舉常數
XR_EXT_INTERACTION_PROFILE_BATTERY_STATE_DISPLAY_EXTENSION_NAMEXR_EXT_interaction_profile_battery_state_display_SPEC_VERSION擴充 XrStructureType：
XR_TYPE_BATTERY_STATE_DISPLAY_EXT
問題
應用程式能否透過這項擴充功能，查詢頭戴式裝置顯示的電池電量？
- 已解決。無法直接。這項擴充功能僅支援傳回頂層 /user 路徑顯示的電池電量，以及目前的互動設定檔。如果應用程式建議頭戴式裝置 ( /user/head) 互動設定檔的繫結，且執行階段啟用該互動設定檔，則執行階段可以傳回該頂層 /user 路徑的電池電量。
版本記錄
修訂版本 1，2025-10-21 (John Kearney)
- 初始草稿。