用於存取各種其它工具函式的介面。
成員函式
ISteamUtils
的成員函式可透過全域存取子函式
SteamUtils()
呼叫。
BOverlayNeedsPresent
bool BOverlayNeedsPresent();
檢查內嵌介面是否需要 Present。 僅在使用事件驅動彩現更新時需要。
如果您的遊戲與大多遊戲一樣,每幀都會持續執行會呼叫 D3D Present API 或 OGL SwapBuffer API 的幀循環,一般並不需要此呼叫。 不過,如果您的遊戲僅在事件發生時更新畫面,這可能會造成內嵌介面出錯,因為它是使用 Present/SwapBuffer 呼叫來驅動其內部幀循環,而且可能需要在出現通知或使用者在遊戲上方開啟內嵌介面時在畫面中使用 Present()。 You can use this API to ask the overlay if it currently need a present in that case, and then you can check for this periodically (roughly 33hz is desirable) and make sure you refresh the screen with Present or SwapBuffers to allow the overlay to do its work.
傳回: bool
true ,如果內嵌介面需要刷新畫面,否則傳回
false。
CheckFileSignature
SteamAPICall_t CheckFileSignature( const char *szFileName );
名稱 | 型別 | 說明 |
szFileName | const char * | . |
已棄用。
傳回: 用於
CheckFileSignature_t 呼叫結果的
SteamAPICall_t。
GetAPICallFailureReason
ESteamAPICallFailure GetAPICallFailureReason( SteamAPICall_t hSteamAPICall );
用於取得呼叫結果的失敗原因。
此函式的主要用途是偵錯。 失敗的原因一般不是您所能控制的,而且往往並不重要。 請繼續嘗試 API 呼叫,直到成功為止。
傳回: ESteamAPICallFailure[type]ESteamAPICallFailure[/type]
另外請見: IsAPICallCompleted、
GetAPICallResult範例:void CHTMLSurface::OnBrowserReady( HTML_BrowserReady_t *pBrowserReady, bool bIOFailure )
{
if ( bIOFailure ) {
SteamUtils()->GetAPICallFailureReason( handle ); // 控制代碼必須分開存放。
return;
}
}
GetAPICallResult
bool GetAPICallResult( SteamAPICall_t hSteamAPICall, void *pCallback, int cubCallback, int iCallbackExpected, bool *pbFailed );
名稱 | 型別 | 說明 |
hSteamAPICall | SteamAPICall_t | API 呼叫的控制代碼。 |
pCallback | void * | 將回呼傳回預留的記憶體中。 |
cubCallback | int | 傳入的 pCallback 大小。 |
iCallbackExpected | int | 與回呼相關的 k_iCallback 數量。 |
pbFailed | bool * | API 呼叫遭遇失敗時傳回。 |
取得完成的 API 呼叫內容。 為 CallResult 包裝函式的後端提供。
一般不建議手動使用此功能。
傳回: bool
true 於成功時傳回,如果 API 呼叫有效且已完成,否則傳回
false。
如果呼叫成功,它將把回呼複製至
pCallback
並將失敗傳回至
pbFailed
。
另外請見: IsAPICallCompleted、
GetAPICallFailureReasonGetAppID
uint32 GetAppID();
在目前的程序中取得 App ID。
傳回: uint32傳回 AppID。
GetConnectedUniverse
EUniverse GetConnectedUniverse();
取得用戶端目前連結至的宇宙 (僅限 Valve 使用)。
傳回: EUniverse[type]EUniverse[/type]
GetCSERIPPort
bool GetCSERIPPort( uint32 *unIP, uint16 *usPort );
名稱 | 型別 | 說明 |
unIP | uint32 * | 傳回用戶端連結至的 IP。 |
usPort | uint16 * | 傳回用戶端連結至的連接埠。 |
Gets the IP of the reporting server for Valve - currently only used in Source engine games
傳回: bool
如果使用者目前已連線,便傳回
true,否則傳回
false。
GetCurrentBatteryPower
uint8 GetCurrentBatteryPower();
取得電腦目前的電池電量。
傳回: uint8電池目前的電量範圍於 [0..100]% 間。 使用者使用連接電源時傳回 255。
GetEnteredGamepadTextInput
bool GetEnteredGamepadTextInput( char *pchText, uint32 cchText );
名稱 | 型別 | 說明 |
pchText | char * | 預留的緩衝區,可將文字輸入字串複製於此。 |
cchText | uint32 | pchText 緩衝區的大小。 |
從 Big Picture 內嵌介面取得遊戲手把文字輸入。
這必須在
GamepadTextInputDismissed_t 回呼內進行呼叫,且僅在
GamepadTextInputDismissed_t.m_bSubmitted
為 true 時適用。
Provides the text input as UTF-8.
傳回: bool
true 如果有可接收文字且
cchText
大小與 GamepadTextInputDismissed_t.m_unSubmittedText,否則傳回
false。
另外請見: ShowGamepadTextInput、
GetEnteredGamepadTextLength範例:void OnGamepadTextInputDismissed_t( GamepadTextInputDismissed_t* pCallback )
{
// 使用者取消了,
if ( !pCallback.m_bSubmitted )
return;
// 使用一些傳入 ShowGamepadTextInput 的最大輸入長度,Null 結束字元 +1。
const uint32 MAX_INPUT_LENGTH = 64 + 1;
uint32 length = SteamUtils()->GetEnteredGamepadTextLength();
char* szTextInput[MAX_INPUT_LENGTH];
bool success = SteamUtils()->GetEnteredGamepadTextInput( szTextInput, length );
if ( !success )
{
// 記錄一個錯誤。 這應該只會在長度為 > MaxInputLength 時發生
return;
}
// 顯示更新字串
}
GetEnteredGamepadTextLength
uint32 GetEnteredGamepadTextLength();
從 Big Picture 內嵌介面取得遊戲手把文字輸入的長度。
這必須在
GamepadTextInputDismissed_t 回呼內進行呼叫,且僅在
GamepadTextInputDismissed_t.m_bSubmitted
為 true 時適用。
傳回: uint32另外請見: ShowGamepadTextInput、
GetEnteredGamepadTextInput範例:void OnGamepadTextInputDismissed_t( GamepadTextInputDismissed_t* pCallback )
{
// 使用者取消了,
if ( !pCallback.m_bSubmitted )
return;
// 使用一些傳入 ShowGamepadTextInput 的最大輸入長度,Null 結束字元 +1。
const uint32 MAX_INPUT_LENGTH = 64 + 1;
uint32 length = SteamUtils()->GetEnteredGamepadTextLength();
const char* szTextInput[MAX_INPUT_LENGTH];
bool success = SteamUtils()->GetEnteredGamepadTextInput( szTextInput, length );
if ( !success )
{
// 記錄一個錯誤。 這應該只會在長度為 > MaxInputLength 時發生
return;
}
// 顯示更新字串
}
GetImageRGBA
bool GetImageRGBA( int iImage, uint8 *pubDest, int nDestBufferSize );
名稱 | 型別 | 說明 |
iImage | int | 將取得的圖像控制代碼。 |
pubDest | uint8 * | 將被填入的緩衝區。 |
nDestBufferSize | int | pchDest 緩衝區的總大小。 |
從圖像控制代碼取得圖像位元組。
在呼叫之前,必須先透過呼叫
GetImageSize 取得圖像的大小來建立大小適當的緩衝區。 接著,您可以如此分配緩衝區的寬與高:寬 * 高 * 4。 圖像將以 RGBA 格式提供。 此呼叫可能會消耗較多資源,因為轉換的是壓縮類型(JPG、PNG、TGA)且不為傳回的緩衝區提供內部快取,因此建議僅呼叫每個圖像控制代碼一次並快取此結果。 此功能僅用於 Steam 個人圖示與成就圖像,且這些一般不會在遊戲進行期間改變。
傳回: bool
true 於成功時傳回,如果圖像控制代碼有效且緩衝區已填入,否則傳回
false。
另外請見: ISteamFriends::GetSmallFriendAvatar、
ISteamFriends::GetMediumFriendAvatar、
ISteamFriends::GetLargeFriendAvatar、
ISteamUserStats::GetAchievementIcon範例:HGAMETEXTURE GetSteamImageAsTexture( int iImage )
{
HGAMETEXTURE hTexture = 0;
// You should first check if you have already cached this image using something like a dictionary/map
// with iImage as the key and then return the texture handle associated with it if it exists.
// If it doesn't exist, continue on, and add the texture to the map before returning at the end of the function.
// If we have to check the size of the image.
uint32 uAvatarWidth, uAvatarHeight;
bool success = SteamUtils()->GetImageSize( iImage, &uAvatarWidth, &uAvatarHeight );
if ( !success ) {
// Log a warning message.
return hTexture;
}
// Get the actual raw RGBA data from Steam and turn it into a texture in our game engine
const int uImageSizeInBytes = uAvatarWidth * uAvatarHeight * 4;
uint8 *pAvatarRGBA = new uint8[uImageSizeInBytes];
success = SteamUtils()->GetImageRGBA( iImage, pAvatarRGBA, uImageSizeInBytes );
if( !success )
{
// Do something to convert the RGBA texture into your internal texture format for displaying.
// hTexture = m_pGameEngine->HCreateTexture( pAvatarRGBA, uAvatarWidth, uAvatarHeight );
// And add the texture to the cache
}
// Don't forget to free the memory!
delete[] pAvatarRGBA;
return hTexture;
}
GetImageSize
bool GetImageSize( int iImage, uint32 *pnWidth, uint32 *pnHeight );
名稱 | 型別 | 說明 |
iImage | int | 要取得大小的圖像控制代碼。 |
pnWidth | uint32 * | 傳回圖像的寬度。 |
pnHeight | uint32 * | 傳回圖像的高度。 |
取得 Steam 圖像控制代碼的大小。
呼叫
GetImageRGBA 之前必須先呼叫此函式,以建立大小適當的緩衝區以供原始圖像資料填入。
傳回: bool
true 於成功時傳回,如果圖像控制代碼有效且大小已填入,否則傳回
false。
另外請見: ISteamFriends::GetSmallFriendAvatar、
ISteamFriends::GetMediumFriendAvatar、
ISteamFriends::GetLargeFriendAvatar、
ISteamUserStats::GetAchievementIconGetIPCCallCount
uint32 GetIPCCallCount();
傳回自上次呼叫此函式以來進行過的 IPC 呼叫數量。
用於效能偵錯來判斷您的遊戲每幀會有多少 IPC (處理程序內溝通)呼叫
每次 IPC 呼叫若不是處理程序,至少會是一次字串內容切換,因此您應該控制執行它們的頻率。
傳回: uint32GetIPCountry
const char * GetIPCountry();
傳回用戶端目前執行位置的 2 位數 ISO 3166-1-alpha-2 格式國家 / 地區碼。
例如:「US」或「UK」。
透過 IP 對應位置資料庫搜尋。
傳回: const char *
GetSecondsSinceAppActive
uint32 GetSecondsSinceAppActive();
傳回應用程式開始使用起計的秒數。
傳回: uint32GetSecondsSinceComputerActive
uint32 GetSecondsSinceComputerActive();
傳回使用者最後移動滑鼠起計的秒數。
傳回: uint32GetServerRealTime
uint32 GetServerRealTime();
傳回 Steam 伺服器時間,以 Unix 紀元格式表示 (自 UTC 時間 1970 年 1 月 1 日以來的秒數)。
傳回: uint32GetSteamUILanguage
const char * GetSteamUILanguage();
傳回 Steam 用戶端正在執行的語言。
建議一般使用
ISteamApps::GetCurrentGameLanguage,應只在特殊情況下使用此函式。
欲查看完整的語言清單,請見
支援的語言。
傳回: const char *
另外請見: ISteamApps::GetCurrentGameLanguage、
ISteamApps::GetAvailableGameLanguagesIsAPICallCompleted
bool IsAPICallCompleted( SteamAPICall_t hSteamAPICall, bool *pbFailed );
名稱 | 型別 | 說明 |
hSteamAPICall | SteamAPICall_t | 要檢查的 API 呼叫控制代碼。 |
pbFailed | bool * | 傳回 API 呼叫是(true)、否(false)遭遇失敗。 |
檢查 API 呼叫是否已完成。 提供 CallResult 包裝函式的後端。
一般不建議您自行使用此功能。
傳回: bool
true ,如果 API 呼叫有效且已完成,否則傳回
false。
另外請見: GetAPICallResult、
GetAPICallFailureReasonIsOverlayEnabled
bool IsOverlayEnabled();
檢查
Steam 內嵌介面是否正在執行中並可供使用者存取。
內嵌介面可能需要幾秒鐘的時間來啟動並與遊戲掛鉤,所以當內嵌介面在載入時,函式一開始將傳回 False。
傳回: bool
IsSteamChinaLauncher
bool IsSteamChinaLauncher();
傳回目前的啟動器是否為蒸汽平台啟動器。 您可以在執行 Steam 時添加 -dev -steamchina 至命令列,讓用戶端模擬蒸汽平台啟動器的運作。
InitFilterText
bool InitFilterText();
初始化文字過濾功能,並載入遊戲執行語言的字典。
使用者可在
Steam 帳戶偏好設定中設定文字過濾行為。
傳回: bool
true ,若初始化成功;若遊戲語言無法使用過濾功能,則
false,在此情況下,會使用
FilterText() 進行傳遞。
另外請見: FilterTextFilterText
int FilterText( ETextFilteringContext eContext, CSteamID sourceSteamID, const char *pchInputMessage, char *pchOutFilteredText, uint32 nByteSizeOutFilteredText );
名稱 | 型別 | 說明 |
eContext | ETextFilteringContext | 輸入字串中的內容類型。 |
sourceSteamID | CSteamID | 作為輸入字串來源的 Steam ID(例如使用該名稱的玩家,或傳送該聊天文字的人)。 |
pchInputText | const char* | 該受到過濾的輸入字串,可以是 ASCII 或 UTF-8 格式。 |
pchOutFilteredText | char* | 輸出的位置(不論有否受到過濾)。 |
nByteSizeOutFilteredText | uint32 | pchOutFilteredText 的大小(位元組),應至少為 strlen(pchInputText)+1。 |
過濾提供的輸入訊息並將過濾後的結果放至 pchOutFilteredText。 法律要求的過濾條件將一律套用。 可根據內容和使用者設定進行額外過濾。
傳回: int
傳回受到過濾的字元數(非位元組)。
另外請見: InitFilterTextIsSteamInBigPictureMode
bool IsSteamInBigPictureMode();
檢查 Steam 和 Steam 內嵌介面是否在 Big Picture 模式下執行。
Games must be launched through the Steam client to enable the Big Picture overlay.
During development, a game can be added as a non-steam game to the developer's library to test this feature.
傳回: bool
true ,如果可使用 Big Picture 內嵌介面,否則傳回
false。
如果
應用程式類型非「遊戲」,將永遠傳回
false。
IsSteamRunningInVR
bool IsSteamRunningInVR();
檢查 Steam 是否在 VR 模式下執行。
傳回: bool
true ,如果 Steam 本身以 VR 模式執行,否則傳回
false。
IsVRHeadsetStreamingEnabled
bool IsVRHeadsetStreamingEnabled();
Checks if the HMD view is being streamed via Steam Remote Play.
傳回: bool
true ,如果 VR 已啟用且正在串流頭戴顯示器的畫面,否則傳回
false。
另外請見: SetVRHeadsetStreamingEnabledIsSteamRunningOnSteamDeck
bool IsSteamRunningOnSteamDeck();
檢查 Steam 是否在 Steam Deck 裝置上執行。
傳回: bool
true ,如果 Steam 本身在 Steam Deck 裝置上執行,否則傳回
false。
SetOverlayNotificationInset
void SetOverlayNotificationInset( int nHorizontalInset, int nVerticalInset );
名稱 | 型別 | 說明 |
nHorizontalInset | int | 與邊角的水平像素距離(左右)。 |
nVerticalInset | int | 與邊角的垂直像素距離(上下)。 |
根據與在
SetOverlayNotificationPosition 中指定的邊角的距離,來設定內嵌介面通知的嵌入位置。
當值為 (0, 0) 時,位置將重置於邊角。
此位置設定只會套用於該款遊戲,每次啟動都會重設。
SetOverlayNotificationPosition
void SetOverlayNotificationPosition( ENotificationPosition eNotificationPosition );
設定 Steam 內嵌介面通知該從哪個邊角彈出顯示。
您亦可使用
SetOverlayNotificationInset 設定與特定邊角的距離。
此位置設定只會套用於該次遊戲,每次啟動都會重設。
SetVRHeadsetStreamingEnabled
void SetVRHeadsetStreamingEnabled( bool bEnabled );
名稱 | 型別 | 說明 |
bEnabled | bool | 開啟(true)或關閉(false)VR 頭戴顯示器。 |
設定頭戴顯示器的內容是否會透過 Steam 遠端暢玩串流。
若啟用,則會串流頭戴顯示器的畫面,且不允許遠端輸入。 若停用,則會改串流應用程式視窗,並允許遠端輸入。 VR 遊戲預設為啟用,除非遊戲延伸應用程式資訊中有 "VRHeadsetStreaming" "0"。
此函式適合在遊戲擁有非同步多人遊戲玩法時使用。
另外請見: IsVRHeadsetStreamingEnabledSetWarningMessageHook
void SetWarningMessageHook( SteamAPIWarningMessageHook_t pFunction );
名稱 | 型別 | 說明 |
pFunction | SteamAPIWarningMessageHook_t | 指向回呼函式的函式指標。 |
設置警告訊息掛鉤,以接收回呼函式中的 SteamAPI 警告與資訊訊息。
函式原型須與 SteamAPIWarningMessageHook_t 中的定義相符, 其中包括外部 「C」 鏈結及 __cdecl 呼叫慣例。
「int nSeverity」為嚴重等級,0 為訊息,1 為警告。 如您在偵錯工具中運行,則只發送警告。 如在命令列添加 -debug_steamapi,則也會發送資訊訊息。
「const char * pchDebugText」為訊息文字。
如果呼叫的 API 函式產生了警告或訊息,便會直接產生回呼。
傳入 NULL 可解除掛鉤。
範例:extern "C" void __cdecl SteamAPIDebugTextHook( int nSeverity, const char *pchDebugText )
{
::OutputDebugString( pchDebugText );
if ( nSeverity >= 1 )
{
// 在此處設置攔截 API 錯誤的中斷點
int x = 3;
x = x;
}
}
void EnableWarningMessageHook()
{
SteamUtils()->SetWarningMessageHook( &SteamAPIDebugTextHook );
}
ShowGamepadTextInput
bool ShowGamepadTextInput( EGamepadTextInputMode eInputMode, EGamepadTextInputLineMode eLineInputMode, const char *pchDescription, uint32 unCharMax, const char *pchExistingText );
啟用 Big Picture 文字輸入對話視窗,僅支援遊戲手把輸入。
傳回: bool
true ,如果正在執行 Big Picture 內嵌頁面,否則傳回
false。
另外請見: GetEnteredGamepadTextLength、
GetEnteredGamepadTextInputShowFloatingGamepadTextInput
bool ShowFloatingGamepadTextInput( EFloatingGamepadTextInputMode eKeyboardMode, int nTextFieldXPosition, int nTextFieldYPosition, int nTextFieldWidth, int nTextFieldHeight );
名稱 | 型別 | 說明 |
eKeyboardMode | EFloatingGamepadTextInputMode | 選擇要使用的鍵盤類型。 |
nTextFieldXPosition | int | X coordinate of text field which shouldn't be obscured by the floating keyboard |
nTextFieldYPosition | int | Y coordinate of text field which shouldn't be obscured by the floating keyboard |
nTextFieldWidth | int | width of text field which shouldn't be obscured by the floating keyboard |
nTextFieldHeight | int | height of text field which shouldn't be obscured by the floating keyboard |
在遊戲內容上方開啟懸浮鍵盤,並直接傳送作業系統鍵盤按鍵至遊戲。
文字欄位位置以相對於遊戲視窗原點的像素標示,並用於以不會蓋住文字欄位的方式放置懸浮鍵盤。
傳回: bool
true ,如果顯示懸浮鍵盤;若否,傳回
false。
另外請見: FloatingGamepadTextInputDismissed_tStartVRDashboard
void StartVRDashboard();
要求 Steam 建立並彩現 OpenVR 主控台。
SetGameLauncherMode
void SetGameLauncherMode( bool bLauncherMode);
名稱 | 型別 | 說明 |
bLauncherMode | bool | 啟動器是否為使用中。 |
在不提供控制器支援的遊戲啟動器中,可呼叫此功能讓 Steam 輸入將控制器輸入轉譯為滑鼠或鍵盤輸入,以此操控啟動器。
回呼
These are callbacks which can be fired by calling
SteamAPI_RunCallbacks. Many of these will be fired directly in response to the member functions of
ISteamUtils
.
CheckFileSignature_t
CallResult for
CheckFileSignature.
關聯函式: CheckFileSignatureGamepadTextInputDismissed_t
Called when the big picture gamepad text input has been closed.
FloatingGamepadTextInputDismissed_t
Called when the floating keyboard invoked from
ShowFloatingGamepadTextInput has been closed.
IPCountry_t
Called when the country of the user changed. The country should be updated with
GetIPCountry.
This callback has no fields.
LowBatteryPower_t
Called when running on a laptop and less than 10 minutes of battery is left, and then fires then every minute afterwards.
名稱 | 型別 | 說明 |
m_nMinutesBatteryLeft | uint8 | 預計剩餘的電池電量(以分鐘計)。 |
SteamAPICallCompleted_t
Called when a SteamAPICall_t has completed (or failed)
名稱 | 型別 | 說明 |
m_hAsyncCall | SteamAPICall_t | 已完成的 Steam API 呼叫的控制代碼。 |
m_iCallback | int | 用來唯一識別已完成回呼的 k_iCallback 常數。 |
m_cubParam | uint32 | 已完成回呼的位元組大小。 |
AppResumingFromSuspend_t
Sent after the device returns from sleep/suspend mode.
This callback has no fields.
SteamShutdown_t
Called when Steam wants to shutdown.
此回呼沒有欄位。
列舉
These are enums which are defined for use with ISteamUtils.
ECheckFileSignature
The result of a call to
CheckFileSignature 名稱 | 值 | 說明 |
k_ECheckFileSignatureInvalidSignature | 0 | |
k_ECheckFileSignatureValidSignature | 1 | |
k_ECheckFileSignatureFileNotFound | 2 | |
k_ECheckFileSignatureNoSignaturesFoundForThisApp | 3 | |
k_ECheckFileSignatureNoSignaturesFoundForThisFile | 4 | |
EGamepadTextInputLineMode
Controls number of allowed lines for the Big Picture gamepad text entry
名稱 | 值 | 說明 |
k_EGamepadTextInputLineModeSingleLine | 0 | |
k_EGamepadTextInputLineModeMultipleLines | 1 | |
EGamepadTextInputMode
Input modes for the Big Picture gamepad text entry
名稱 | 值 | 說明 |
k_EGamepadTextInputModeNormal | 0 | |
k_EGamepadTextInputModePassword | 1 | |
EFloatingGamepadTextInputMode
Controls the mode for the floating keyboard
名稱 | 值 | 說明 |
k_EFloatingGamepadTextInputModeModeSingleLine | 0 | 按 Enter 鍵關閉鍵盤。 |
k_EFloatingGamepadTextInputModeModeMultipleLines | 1 | 使用者需要明確關閉鍵盤。 |
k_EFloatingGamepadTextInputModeModeEmail | 2 | 以更容易輸入電子郵件的特殊模式顯示鍵盤。 |
k_EFloatingGamepadTextInputModeModeNumeric | 3 | 顯示數字鍵盤。 |
ESteamAPICallFailure
Steam API call failure results returned by
GetAPICallFailureReason.
名稱 | 值 | 說明 |
k_ESteamAPICallFailureNone | -1 | 無失敗。 |
k_ESteamAPICallFailureSteamGone | 0 | 本機的 Steam 處理序停止回應,可能被強行關閉或處於凍結狀態。 |
k_ESteamAPICallFailureNetworkFailure | 1 | 與 Steam 伺服器的網路連線中斷,或已損壞。 SteamServersDisconnected_t 回呼將大致在同一時間發出,而 SteamServersConnected_t 回呼將在用戶端與 Steam 伺服器恢復通訊後發出。 |
k_ESteamAPICallFailureInvalidHandle | 2 | 傳入的 SteamAPICall_t 控制代碼已不存在。 |
k_ESteamAPICallFailureMismatchedCallback | 3 | 在呼叫 GetAPICallResult 時使用了不符合該 API 呼叫的錯誤回呼型別。 |
常數
These are constants which are defined for use with ISteamUtils.
名稱 | 型別 | 值 | 說明 |
STEAMUTILS_INTERFACE_VERSION | const char * | "SteamUtils009" | |