访问一系列杂项工具函数的接口。
成员函数
ISteamUtils
的成员函数通过全局访问器函数
SteamUtils()
调用。
BOverlayNeedsPresent
bool BOverlayNeedsPresent();
检查界面是否需要显示。 仅在使用由事件驱动的渲染更新时需要。
通常,如果您的游戏有一个持续运行的帧循环来调用 D3D Presnet API,或者如多数游戏一样,每帧调用 OGL swapbuffer API,那么您不需要此调用。 然而,如果您的游戏仅仅在事件驱动下刷新屏幕,那么可能会破坏界面,因为它使用了 Present/SwapBuffers 调用来驱动其内部帧循环,而且只要出现通知,或用户在游戏中调出界面,它可能就会对屏幕使用 Present()。 可使用此 API 来询问界面当前是否需要显示,然后可周期性地检查(最好是大约 33hz),并确保您使用 Present 或 SwapBuffers 刷新屏幕,以使界面正常工作。
返回: bool
true, 表示界面需要您刷新屏幕,否则返回
false。
CheckFileSignature
SteamAPICall_t CheckFileSignature( const char *szFileName );
名称 | 类型 | 描述 |
szFileName | const char * | . |
已弃用。
返回: SteamAPICall_t,与
CheckFileSignature_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 ); // handle must be stored separately.
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();
获取当前客户端连接至的 Steam 系统。 (仅限 Valve 使用。)
返回: EUniverse[type]EUniverse[/type]
GetCSERIPPort
bool GetCSERIPPort( uint32 *unIP, uint16 *usPort );
为 Valve 获取报告服务器的 IP,目前只在 Source 引擎游戏中使用。
返回: bool
如果用户当前已连接,返回
true,否则返回
false。
GetCurrentBatteryPower
uint8 GetCurrentBatteryPower();
获取电脑上的当前电池电量。
返回: uint8当前电池电量范围 [0..100]%。 用户使用 AC 电源时,返回 255。
GetEnteredGamepadTextInput
bool GetEnteredGamepadTextInput( char *pchText, uint32 cchText );
名称 | 类型 | 描述 |
pchText | char * | 文本输入字符串要复制入的预分配缓冲区。 |
cchText | uint32 | pchText 缓冲区大小。 |
从大屏幕界面获取游戏手柄文本输入。
此函数必须在
GamepadTextInputDismissed_t 回调中调用,且仅在
GamepadTextInputDismissed_t.m_bSubmitted 为 true 时调用。
以 UTF-8 格式提供文本输入。
[b]返回:[/b] bool
true, 表示有要接收的文本,且 cchText
与 GamepadTextInputDismissed_t.m_unSubmittedText; 的大小相同;否则,返回 false。
另见: ShowGamepadTextInput、GetEnteredGamepadTextLength
示例:
void OnGamepadTextInputDismissed_t( GamepadTextInputDismissed_t* pCallback )
{
// 用户已取消,
if ( !pCallback.m_bSubmitted )
return;
// 使用我们传入 ShowGamepadTextInput 的最大输入长度,并为空字符多留一个位置用作终止符。
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();
从大屏幕界面获取游戏手柄文本输入长度。
此函数必须在 GamepadTextInputDismissed_t 回调中调用,且仅在 GamepadTextInputDismissed_t.m_bSubmitted
为 true 时调用。
返回: uint32
另见: ShowGamepadTextInput、GetEnteredGamepadTextInput
示例:
void OnGamepadTextInputDismissed_t( GamepadTextInputDismissed_t* pCallback )
{
// 用户已取消,
if ( !pCallback.m_bSubmitted )
return;
// 使用我们传入 ShowGamepadTextInput 的最大输入长度,并为空字符多留一个位置用作终止符。
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 | pubDest 缓冲区的总大小。 |
从图像句柄中获取图像字节。
调用此函数前必须通过调用 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;
// 您应首先检查是否已经使用字典/地图之类的东西缓存了这张图片
// 以 iImage 为键,返回与之关联的纹理句柄(如果存在)
// 如果不存在,则继续,并在函数结束时返回地图前,对地图添加纹理
// 如果我们需要查看图像的大小
uint32 uAvatarWidth, uAvatarHeight;
bool success = SteamUtils()->GetImageSize( iImage, &uAvatarWidth, &uAvatarHeight );
if ( !success ) {
// 记录一条警告消息
return hTexture;
}
// 从 Steam 获取实际的原始 RGBA 数据并在我们的游戏引擎中将其转化为纹理
const int uImageSizeInBytes = uAvatarWidth * uAvatarHeight * 4;
uint8 *pAvatarRGBA = new uint8[uImageSizeInBytes];
success = SteamUtils()->GetImageRGBA( iImage, pAvatarRGBA, uImageSizeInBytes );
if( !success )
{
// 将 RGBA 纹理转换为您的内部纹理格式以供显示
// hTexture = m_pGameEngine->HCreateTexture( pAvatarRGBA, uAvatarWidth, uAvatarHeight );
// 并将纹理添加到缓存
}
// 不要忘记释放内存!
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();
以 Unix 时间戳格式返回 Steam 服务器时间。 (自 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。
返回: boolIsSteamChinaLauncher
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 界面是否在大屏幕模式下运行。
游戏必须通过 Steam 客户端启动,以启用大屏幕界面。
在开发过程中,可以将一款游戏作为非 Steam 游戏添加到开发者库中以测试此功能。
返回: bool
true, 表示大屏幕界面可用;否则返回 false。
如果您的应用不是“游戏”应用程序类型,将总是返回 false。IsSteamRunningInVR
bool IsSteamRunningInVR();
检查 Steam 是否在 VR 模式下运行。
返回: bool
true, 表示 Steam 自身在 VR 模式下运行,否则返回 false。IsVRHeadsetStreamingEnabled
bool IsVRHeadsetStreamingEnabled();
检查 HMD 视图是否通过 Steam 远程畅玩流式传输。
返回: 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 远程畅玩进行流式传输。
如果启用这一功能,那么 HMD 头戴设备内的场景将被流式传输,且不允许远程输入。 反之,若禁用此功能,那么应用程序窗口将被流式传输,且允许远程输入。 VR 游戏默认为启用,除非“VRHeadsetStreaming”“0”包括在游戏的扩展 appinfo 中。
这对于有非对称多人玩法的游戏非常有用。
另见: 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 );
激活仅支持游戏手柄输入的大屏幕文本输入对话框。
返回: bool
true, 表示大屏幕界面正在运行;否则返回 false。
另见: GetEnteredGamepadTextLength、GetEnteredGamepadTextInputShowFloatingGamepadTextInput
bool ShowFloatingGamepadTextInput( EFloatingGamepadTextInputMode eKeyboardMode, int nTextFieldXPosition, int nTextFieldYPosition, int nTextFieldWidth, int nTextFieldHeight );
名称 | 类型 | 描述 |
eKeyboardMode | EFloatingGamepadTextInputMode | 选择要使用的键盘类型。 |
nTextFieldXPosition | int | 不应被浮动键盘遮挡的文本字段的 X 坐标。 |
nTextFieldYPosition | int | 不应被浮动键盘遮挡的文本字段的 Y 坐标。 |
nTextFieldWidth | int | 不应被浮动键盘遮挡的文本字段的宽度。 |
nTextFieldHeight | int | 不应被浮动键盘遮挡的文本字段的高度。 |
在游戏内容上打开一个浮动键盘并将操作系统键盘键直接发送到游戏。
文本字段位置以相对于游戏窗口原点的像素距离为单位指定,用于以不覆盖文本字段的方式定位浮动键盘。
返回: bool
true, 表示已显示浮动键盘,否则返回 false。
另见: FloatingGamepadTextInputDismissed_tStartVRDashboard
void StartVRDashboard();
要求 Steam 创建并渲染 OpenVR 主面板。SetGameLauncherMode
void SetGameLauncherMode( bool bLauncherMode);
名称 | 类型 | 描述 |
bLauncherMode | bool | 启动器是否在使用中。 |
您可以在没有控制器支持的游戏启动器中调用此函数,让 Steam 输入将控制器输入转换为鼠标/键盘,以操控启动器。Callbacks
以下是可以通过调用 SteamAPI_RunCallbacks 触发的回调。 其中许多将响应 ISteamUtils
的成员函数直接触发。CheckFileSignature_t
CheckFileSignature 的调用结果。
关联函数: CheckFileSignatureGamepadTextInputDismissed_t
在大屏幕游戏手柄文本输入关闭的情况下调用。
FloatingGamepadTextInputDismissed_t
当从 ShowFloatingGamepadTextInput 调用的浮动键盘关闭时调用。IPCountry_t
当用户的国家改变时调用。 应调用 GetIPCountry 更新国家。
此回调无字段。LowBatteryPower_t
在笔记本电脑上运行且电池电量不足 10 分钟时调用,之后每分钟内都会触发。
名称 | 类型 | 描述 |
m_nMinutesBatteryLeft | uint8 | 预计的剩余电量可用的分钟数。 |
SteamAPICallCompleted_t
当 SteamAPICall_t 完成(或失败)时调用。
名称 | 类型 | 描述 |
m_hAsyncCall | SteamAPICall_t | 已完成的 Steam API 调用的句柄。 |
m_iCallback | int | 这是 k_iCallback 常量,它可以对已完成的回调进行唯一标识。 |
m_cubParam | uint32 | 已完成回调的字节大小。 |
AppResumingFromSuspend_t
在设备从休眠/暂挂模式中恢复时发送。
此回调无字段。SteamShutdown_t
当 Steam 想要关闭时调用。
此回调无字段。枚举
以下是定义来与 ISteamUtils 一起使用的枚举。ECheckFileSignature
调用 CheckFileSignature 的结果。
名称 | 值 | 描述 |
k_ECheckFileSignatureInvalidSignature | 0 | |
k_ECheckFileSignatureValidSignature | 1 | |
k_ECheckFileSignatureFileNotFound | 2 | |
k_ECheckFileSignatureNoSignaturesFoundForThisApp | 3 | |
k_ECheckFileSignatureNoSignaturesFoundForThisFile | 4 | |
EGamepadTextInputLineMode
控制大屏幕游戏手柄文本输入允许的行数。
名称 | 值 | 描述 |
k_EGamepadTextInputLineModeSingleLine | 0 | |
k_EGamepadTextInputLineModeMultipleLines | 1 | |
EGamepadTextInputMode
大屏幕游戏手柄文本条目的输入模式。
名称 | 值 | 描述 |
k_EGamepadTextInputModeNormal | 0 | |
k_EGamepadTextInputModePassword | 1 | |
EFloatingGamepadTextInputMode
控制悬浮键盘的模式。
名称 | 值 | 描述 |
k_EFloatingGamepadTextInputModeModeSingleLine | 0 | 按下 Enter 键即关闭键盘。 |
k_EFloatingGamepadTextInputModeModeMultipleLines | 1 | 用户需要明确关闭键盘。 |
k_EFloatingGamepadTextInputModeModeEmail | 2 | 以特殊模式显示键盘,输入电子邮件更为容易。 |
k_EFloatingGamepadTextInputModeModeNumeric | 3 | 已显示数字键盘。 |
ESteamAPICallFailure
GetAPICallFailureReason 返回的 Steam API 调用失败结果。
名称 | 值 | 描述 |
k_ESteamAPICallFailureNone | -1 | 无失败。 |
k_ESteamAPICallFailureSteamGone | 0 | 本地 Steam 进程已停止响应,有可能已被强行关闭或冻结。 |
k_ESteamAPICallFailureNetworkFailure | 1 | Steam 服务器的网络连接已丢失,或已被破坏。 SteamServersDisconnected_t 回调将在同一时间发出,当客户端能够再次与 Steam 服务器通信时,将发送 SteamServersConnected_t 回调。 |
k_ESteamAPICallFailureInvalidHandle | 2 | 传入的 SteamAPICall_t 句柄不再存在。 |
k_ESteamAPICallFailureMismatchedCallback | 3 | 调用 GetAPICallResult 时使用了此 API 调用的错误回调类型。 |
常量
以下是定义来与 ISteamUtils 一起使用的常量。
名称 | 类型 | 值 | 描述 |
STEAMUTILS_INTERFACE_VERSION | const char * | "SteamUtils009" | |