PFND3DDDI_CHECKCOUNTER回调函数 (d3dumddi.h)

  • 项目

PFND3DDDI_CHECKCOUNTER 由 Direct3D 运行时调用，以检索描述计数器的信息。 必须由 Windows 显示驱动程序模型 (WDDM) 1.3 及更高版本的用户模式显示驱动程序实现。

语法

PFND3DDDI_CHECKCOUNTER Pfnd3dddiCheckcounter;

HRESULT Pfnd3dddiCheckcounter(
  HANDLE hDevice,
  D3DDDIQUERYTYPE unnamedParam2,
  D3DDDI_COUNTER_TYPE *unnamedParam3,
  UINT *unnamedParam4,
  LPSTR unnamedParam5,
  UINT *pNameLength,
  LPSTR unnamedParam7,
  UINT *pUnitsLength,
  LPSTR unnamedParam9,
  UINT *pDescriptionLength
)
{...}

参数

hDevice

[in]显示设备的句柄 (图形上下文) 。

unnamedParam2

[in] 计数器 是 D3DDDIQUERYTYPE 类型的值，用于标识为其检索信息的计数器标识符。

unnamedParam3

[out] pType 是指向变量的指针，该变量接收标识计数器输出的数据类型 的D3DDDI_COUNTER_TYPE 枚举值。

unnamedParam4

pActiveCounters [out] pActiveCounters 是指向变量的指针，该变量接收为创建 Counter 参数标识的计数器标识符而分配的同时活动计数器数。

unnamedParam5

[out，可选] pszName 是驱动程序返回包含计数器标识符名称的以 NULL 结尾的字符串的可选指针。

可以为 NULL，在这种情况下，应用不需要名称。

pNameLength

[in，out， optional]指向变量的可选指针，该变量接收 pszName 参数指定的以 NULL 结尾的字符串的大小（以字节为单位）。

下面是 pNameLength 和 pszName 参数值的限制：

  • pNameLength 可以为 NULL，在这种情况下，应用不需要名称或名称长度。
  • 如果 pszName 为 NULL 且 pNameLength 不为 NULL，则忽略 pNameLength 的输入值，并且必须通过 pNameLength 参数返回字符串 (包括终止 NULL 字符) 的长度。
  • 如果 pszName 和 pNameLength 都不是 NULL，则驱动程序必须检查 pNameLength 的输入值，以确保在分配的缓冲区中有足够的空间，然后通过 pNameLength 参数传递 pszName 字符串 (包括终止 NULL 字符) 的长度。

unnamedParam7

[out，可选] pszUnits 是驱动程序返回一个以 NULL 结尾的字符串的可选指针，其中包含计数器标识符度量的单位的名称。

可以为 NULL，在这种情况下，应用不需要单位信息。 有关详细信息，请参阅 pUnitsLength 参数的说明。

pUnitsLength

[in，out， optional] pUnitsLength 是指向变量的可选指针，该变量接收 pszUnits 参数指定的以 NULL 结尾的字符串的大小（以字节为单位）。

下面是 pUnitsLength 和 pszUnits 参数值的限制：

  • pUnitsLength 可以为 NULL，在这种情况下，应用不需要单位名称或单位名称长度。
  • 如果 pszUnits 为 NULL 且 pUnitsLength 不为 NULL，则忽略 pUnitsLength 的输入值，并且必须通过 pUnitsLength 参数返回字符串 (包括终止 NULL 字符) 的长度。
  • 如果 pszUnits 和 pUnitsLength 都不为 NULL，则驱动程序必须检查 pUnitsLength 的输入值，以确保分配的缓冲区中有足够的空间，然后通过 pUnitsLength 参数传递 pszUnits 字符串 (包括终止 NULL 字符) 的长度。

unnamedParam9

[out，可选] pszDescription 是驱动程序返回的以 NULL 结尾的字符串的可选指针，其中包含计数器标识符度量值的说明。

可以为 NULL，在这种情况下，应用不需要说明信息。 有关详细信息，请参阅 pDescriptionLength 参数的说明。

pDescriptionLength

[in，out， optional] pDescriptionLength 是指向变量的可选指针，该变量接收 pszDescription 参数指定的 NULL 终止字符串的大小（以字节为单位）。

下面是 对 pDescriptionLength 和 pszDescription 参数的值的限制：

  • pDescriptionLength 可以为 NULL，在这种情况下，应用不需要单位名称或单位名称长度。
  • 如果 pszDescription 为 NULL 且 pDescriptionLength 不为 NULL，则忽略 pDescriptionLength 的输入值，并且必须通过 pDescriptionLength 参数返回字符串 (包括终止 NULL 字符) 的长度。
  • 如果 pszDescription 和 pDescriptionLength 都不是 NULL，则驱动程序必须检查 pDescriptionLength 的输入值，以确保分配的缓冲区中有足够的空间，然后 pszDescription 字符串的长度 (包括终止 NULL 字符) 通过 pDescriptionLength 参数传递。

返回值

如果此例程成功，则返回S_OK。 否则，它将返回 HRESULT 错误代码，包括以下内容：

返回代码 说明
E_INVALIDARG 请求范围外设备相关的计数器，或者字符串长度不够大，缓冲区无法包含整个字符串。 尽管此函数中使用的所有字符串都基于 Unicode，但它们始终位于英语区域设置中，并且不会本地化为其他区域设置。

注解

此函数的行为应类似于支持 Microsoft Direct3D 10 及更高版本的 CheckCounter 函数。

计数器通常由捕获帧并多次播放的工具使用。 记录准确计时信息的传递与其他传递是分开的。 在以后的传递中，每次都会使用一组不同的计数器。 优先级应该是获取计数器结果与绘制调用的准确关联，并且可以牺牲播放期间产生的开销。 驱动程序必须插入刷新调用或等待空闲调用，以确保准确关联。

通常，应用只能同时监视少量可能的本机计数器，这些计数器可能数百个。 此外，驱动程序必须指示从 D3DDDIQUERYTYPE 枚举 (已知计数器 ID 和设备特定的计数器 ID) 监视每个支持的计数器 ID 所使用的活动计数器数。 例如，驱动程序可以指示监视 FillRateUtilized 变量需要最多 4 个同时处于活动状态的计数器中的 3 个， (pActiveCounters 参数) 指示。 因此，只要该计数器 ID 需要一个或多个活动计数器，应用还可以监视另一个计数器 ID。

如果计数器 ID 始终可以 (监视，并且它不会干扰监视任何其他计数器 ID) ，则计数器 ID 所需的同时活动计数器数可以为零。

要求

要求 值
最低受支持的客户端 Windows 8.1
最低受支持的服务器 Windows Server 2012 R2
目标平台 桌面
标头 d3dumddi.h (包括 D3d10umddi.h)

另请参阅

CheckCounter

D3DDDIQUERYTYPE