XR_EXT_interaction_profile_battery_state_display
名稱字串
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說明batteryLevel的有效性，並使用 XrBatteryStateDisplayStateFlagBitsEXT 中定義的位元遮罩batteryLevel是相關聯實體或動作所連線裝置的電池電量 (從 0.0f 到 1.0f)。
如要查詢電池電量，應用程式會將 XrBatteryStateDisplayEXT 結構體鏈結至呼叫 xrGetCurrentInteractionProfile 時的 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。
有效使用 (隱含)
- 使用 XrBatteryStateDisplayEXT 前，
XR_EXT_interaction_profile_battery_state_display擴充功能必須啟用 -
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 的有效性：batteryLevelXR_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)
- 初稿。