PFND3DDDI_CHECKCOUNTER callback function

Called by the Microsoft Direct3D runtime to retrieve info that describes a counter. Must be implemented by Windows Display Driver Model (WDDM) 1.3 and later user-mode display drivers.

Syntax


PFND3DDDI_CHECKCOUNTER pfnCheckCounter;

_Check_return_ HRESULT APIENTRY* pfnCheckCounter(
  _In_        HANDLE              hDevice,
  _In_        D3DDDIQUERYTYPE     Counter,
  _Out_       D3DDDI_COUNTER_TYPE *pType,
  _Out_       UINT                *pActiveCounters,
  _Out_opt_   LPSTR               pszName,
  _Inout_opt_ UINT                *pNameLength,
  _Out_opt_   LPSTR               pszUnits,
  _Inout_opt_ UINT                *pUnitsLength,
  _Out_opt_   LPSTR               pszDescription,
  _Inout_opt_ UINT                *pDescriptionLength
)
{ ... }

Parameters

hDevice [in]

A handle to the display device (graphics context).

Counter [in]

A value of type D3DDDIQUERYTYPE that identifies the counter identifier that info is retrieved for.

pType [out]

A pointer to a variable that receives one of the following values from the D3DDDI_COUNTER_TYPE enumeration that identifies the data type that the counter outputs.

ValueMeaning

D3DDDI_COUNTER_TYPE_FLOAT32

Single-precision float

D3DDDI_COUNTER_TYPE_UINT16

16-bit value

D3DDDI_COUNTER_TYPE_UINT32

32-bit value

D3DDDI_COUNTER_TYPE_UINT64

64-bit value

 

pActiveCounters [out]

A pointer to a variable that receives the number of simultaneously active counters that are allocated for the creation of the counter identifier that the Counter parameter identifies.

pszName [out, optional]

An optional pointer that the driver returns a NULL-terminated string to that contains the name of the counter identifier.

Can be NULL, in which case the app doesn't need the name.

pNameLength [in, out, optional]

An optional pointer to a variable that receives the size, in bytes, of the NULL-terminated string that the pszName parameter specifies.

Here are limitations on the values of the pNameLength and pszName parameters:

  • pNameLength can be NULL, in which case the app doesn't need the name or name length.
  • If pszName is NULL and pNameLength is not NULL, the input value of pNameLength is ignored, and the length of the string (including terminating NULL character) must be returned through the pNameLength parameter.
  • If both pszName and pNameLength are not NULL, the driver must check the input value of pNameLength to ensure that there's enough room in the allocated buffer, and then the length of the pszName string (including terminating NULL character) is passed out through the pNameLength parameter.
pszUnits [out, optional]

An optional pointer that the driver returns a NULL-terminated string to that contains the name of the units that the counter identifier measures.

Can be NULL, in which case the app doesn't need the units info. See more info in the explanation of the pUnitsLength parameter.

pUnitsLength [in, out, optional]

An optional pointer to a variable that receives the size, in bytes, of the NULL-terminated string that the pszUnits parameter specifies.

Here are limitations on the values of the pUnitsLength and pszUnits parameters:

  • pUnitsLength can be NULL, in which case the app doesn't need the unit name or unit name length.
  • If pszUnits is NULL and pUnitsLength is not NULL, the input value of pUnitsLength is ignored, and the length of the string (including terminating NULL character) must be returned through the pUnitsLength parameter.
  • If both pszUnits and pUnitsLength are not NULL, the driver must check the input value of pUnitsLength to ensure that there's enough room in the allocated buffer, and then the length of the pszUnits string (including terminating NULL character) is passed out through the pUnitsLength parameter.
pszDescription [out, optional]

An optional pointer that the driver returns a NULL-terminated string to that contains the description of what the counter identifier measures.

Can be NULL, in which case the app doesn't need the description info. See more info in the explanation of the pDescriptionLength parameter.

pDescriptionLength [in, out, optional]

An optional pointer to a variable that receives the size, in bytes, of the NULL-terminated string that the pszDescription parameter specifies.

Here are limitations on the values of the pDescriptionLength and pszDescription parameters:

  • pDescriptionLength can be NULL, in which case the app doesn't need the unit name or unit name length.
  • If pszDescription is NULL and pDescriptionLength is not NULL, the input value of pDescriptionLength is ignored, and the length of the string (including terminating NULL character) must be returned through the pDescriptionLength parameter.
  • If both pszDescription and pDescriptionLength are not NULL, the driver must check the input value of pDescriptionLength to ensure that there's enough room in the allocated buffer, and then the length of the pszDescription string (including terminating NULL character) is passed out through the pDescriptionLength parameter.

Return value

If this routine succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code, including the following:

Return codeDescription
E_INVALIDARG

An out-of-range device-dependent counter is requested, or a string length is not large enough for a buffer to contain the entire string.

Even though all strings used in this function are based on Unicode, they are always in the English locale and are not localized to other locales.

 

Remarks

This function should behave similarly to the CheckCounter function that supports Microsoft Direct3D 10 and later.

Counters are typically used by tools that capture a frame and play it back multiple times. The pass that records accurate timing info is separate from other passes. In later passes, a different set of counters is used each time. The priority should be to obtain an accurate correlation of counter results to draw calls, and the overhead incurred during playback can be sacrificed. The driver must insert flush calls or wait-for-idle calls to ensure an accurate correlation.

Typically an app can simultaneously monitor only a small number of possible native counters, which might number in the hundreds. Additionally, the driver must indicate the number of active counters used by monitoring each supported counter ID from the D3DDDIQUERYTYPE enumeration (both well-known counter IDs and device-specific counter IDs). For example, the driver can indicate that monitoring a FillRateUtilized variable requires 3 of the maximum 4 simultaneously active counters (indicated by the pActiveCounters parameter). The app can therefore also monitor another counter ID, as long as that counter ID requires one or fewer active counters.

If a counter ID can always be monitored (and it doesn't interfere with monitoring any other counter IDs), the number of simultaneous active counters required by the counter ID can be zero.

Requirements

Minimum supported client

Windows 8.1

Minimum supported server

Windows Server 2012 R2

Target platform

Desktop

Header

D3dumddi.h (include D3d10umddi.h)

See also

CheckCounter
D3DDDIQUERYTYPE

 

 

Send comments about this topic to Microsoft

Show: