PFND3DDDI_CHECKCOUNTER Rückruffunktion (d3dumddi.h)

Artikel
11/14/2023

PFND3DDDI_CHECKCOUNTER wird von der Direct3D-Runtime aufgerufen, um Informationen abzurufen, die einen Leistungsindikator beschreiben. Muss von Windows Display Driver Model (WDDM) 1.3 und höher im Benutzermodus-Anzeigetreiber implementiert werden.

Syntax

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
)
{...}

Parameter

hDevice

[in] Ein Handle für das Anzeigegerät (Grafikkontext).

unnamedParam2

[in] Counter ist ein Wert vom Typ D3DDDIQUERYTYPE , der den Indikatorbezeichner identifiziert, für den Die Informationen abgerufen werden.

unnamedParam3

[out] pType ist ein Zeiger auf eine Variable, die einen D3DDDI_COUNTER_TYPE Enumerationswert empfängt, der den Datentyp identifiziert, den der Indikator ausgibt.

unnamedParam4

pActiveCounters [out] pActiveCounters ist ein Zeiger auf eine Variable, die die Anzahl gleichzeitig aktiver Indikatoren empfängt, die für die Erstellung des Vom Counter-Parameter identifizierten Indikatorbezeichners zugeordnet sind.

unnamedParam5

[out, optional] pszName ist ein optionaler Zeiger, an den der Treiber eine NULL-beendete Zeichenfolge zurückgibt, die den Namen des Indikatorbezeichners enthält.

Kann NULL sein, in diesem Fall benötigt die App den Namen nicht.

pNameLength

[in, out, optional] Ein optionaler Zeiger auf eine Variable, die die Größe der mit NULL beendeten Zeichenfolge in Byte empfängt, die der pszName-Parameter angibt.

Hier sind Einschränkungen für die Werte der Parameter pNameLength und pszName :

pNameLength kann NULL sein. In diesem Fall benötigt die App weder den Namen noch die Länge des Namens.
Wenn pszName NULL und pNameLength nicht NULL ist, wird der Eingabewert von pNameLength ignoriert, und die Länge der Zeichenfolge (einschließlich des endenden NULL-Zeichens) muss über den pNameLength-Parameter zurückgegeben werden.
Wenn sowohl pszName als auch pNameLength nicht NULL sind, muss der Treiber den Eingabewert von pNameLength überprüfen, um sicherzustellen, dass genügend Platz im zugeordneten Puffer vorhanden ist, und dann wird die Länge der pszName-Zeichenfolge (einschließlich der Beendigung von NULL-Zeichen) über den pNameLength-Parameter übergeben.

unnamedParam7

[out, optional] pszUnits ist ein optionaler Zeiger, an den der Treiber eine NULL-endende Zeichenfolge zurückgibt, die den Namen der Einheiten enthält, die der Indikatorbezeichner misst.

Kann NULL sein, in diesem Fall benötigt die App die Einheiteninformationen nicht. Weitere Informationen finden Sie in der Erklärung des pUnitsLength-Parameters .

pUnitsLength

[in, out, optional] pUnitsLength ist ein optionaler Zeiger auf eine Variable, die die Größe der mit NULL beendeten Zeichenfolge in Bytes empfängt, die der pszUnits-Parameter angibt.

Im Folgenden finden Sie Einschränkungen für die Werte der Parameter pUnitsLength und pszUnits :

pUnitsLength kann NULL sein. In diesem Fall benötigt die App weder den Einheitennamen noch die Länge des Einheitennamens.
Wenn pszUnits NULL und pUnitsLength nicht NULL ist, wird der Eingabewert von pUnitsLength ignoriert, und die Länge der Zeichenfolge (einschließlich des endenden NULL-Zeichens) muss über den pUnitsLength-Parameter zurückgegeben werden.
Wenn sowohl pszUnits als auch pUnitsLength nicht NULL sind, muss der Treiber den Eingabewert von pUnitsLength überprüfen, um sicherzustellen, dass genügend Platz im zugeordneten Puffer vorhanden ist, und dann wird die Länge der pszUnits-Zeichenfolge (einschließlich des beendenden NULL-Zeichens) über den pUnitsLength-Parameter übergeben.

unnamedParam9

[out, optional] pszDescription ist ein optionaler Zeiger, an den der Treiber eine NULL-endende Zeichenfolge zurückgibt, die die Beschreibung der Vom Indikatorbezeichner erfassten Werte enthält.

Kann NULL sein, in diesem Fall benötigt die App die Beschreibungsinformationen nicht. Weitere Informationen finden Sie in der Erklärung des pDescriptionLength-Parameters .

pDescriptionLength

[in, out, optional] pDescriptionLength ist ein optionaler Zeiger auf eine Variable, die die Größe der mit NULL beendeten Zeichenfolge in Bytes empfängt, die der parameter pszDescription angibt.

Hier sind Einschränkungen für die Werte der Parameter pDescriptionLength und pszDescription :

pDescriptionLength kann NULL sein. In diesem Fall benötigt die App weder den Einheitennamen noch die Länge des Einheitennamens.
Wenn pszDescription NULL und pDescriptionLength nicht NULL ist, wird der Eingabewert von pDescriptionLength ignoriert, und die Länge der Zeichenfolge (einschließlich des endenden NULL-Zeichens) muss über den pDescriptionLength-Parameter zurückgegeben werden.
Wenn sowohl pszDescription als auch pDescriptionLength nicht NULL sind, muss der Treiber den Eingabewert von pDescriptionLength überprüfen, um sicherzustellen, dass genügend Platz im zugeordneten Puffer vorhanden ist, und dann wird die Länge der pszDescription-Zeichenfolge (einschließlich des beendenden NULL-Zeichens) über den Parameter pDescriptionLength übergeben.

Rückgabewert

Wenn diese Routine erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein HRESULT-Fehlercode zurückgegeben, einschließlich des folgenden:

Rückgabecode	Beschreibung
E_INVALIDARG	Ein geräteabhängiger Zähler außerhalb des Bereichs wird angefordert, oder eine Zeichenfolgenlänge ist nicht groß genug, damit ein Puffer die gesamte Zeichenfolge enthält. Obwohl alle in dieser Funktion verwendeten Zeichenfolgen auf Unicode basieren, befinden sie sich immer im englischen Gebietsschema und werden nicht in andere Gebietsschemas lokalisiert.

Hinweise

Diese Funktion sollte sich ähnlich wie die CheckCounter-Funktion verhalten, die Microsoft Direct3D 10 und höher unterstützt.

Indikatoren werden in der Regel von Tools verwendet, die einen Frame erfassen und mehrmals wiedergeben. Der Durchlauf, der genaue Zeitsteuerungsinformationen aufzeichnet, ist von anderen Durchläufen getrennt. In späteren Durchläufen wird jedes Mal ein anderer Satz von Leistungsindikatoren verwendet. Die Priorität sollte sein, eine genaue Korrelation der Zählerergebnisse zum Zeichnen von Aufrufen zu erhalten, und der während der Wiedergabe anfallende Mehraufwand kann geopfert werden. Der Treiber muss Leeraufrufe oder Warteaufrufe im Leerlauf einfügen, um eine genaue Korrelation sicherzustellen.

In der Regel kann eine App nur eine kleine Anzahl möglicher nativer Leistungsindikatoren gleichzeitig überwachen, die in hunderten fällen können. Darüber hinaus muss der Treiber die Anzahl der aktiven Indikatoren angeben, die von der Überwachung jeder unterstützten Zähler-ID aus der D3DDDIQUERYTYPE-Enumeration verwendet werden (sowohl bekannte Zähler-IDs als auch gerätespezifische Zähler-IDs). Der Treiber kann beispielsweise angeben, dass für die Überwachung einer FillRateUtilized-Variablen drei der maximal vier gleichzeitig aktiven Leistungsindikatoren erforderlich sind (angegeben durch den Parameter pActiveCounters ). Die App kann daher auch eine andere Zähler-ID überwachen, sofern für diese Zähler-ID ein oder weniger aktive Indikatoren erforderlich sind.

Wenn eine Zähler-ID immer überwacht werden kann (und die Überwachung anderer Zähler-IDs nicht beeinträchtigt), kann die Anzahl der gleichzeitig aktiven Indikatoren, die für die Zähler-ID erforderlich sind, null sein.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8.1
Unterstützte Mindestversion (Server)	Windows Server 2012 R2
Zielplattform	Desktop
Kopfzeile	d3dumddi.h (include D3d10umddi.h)

Weitere Informationen

CheckCounter

D3DDDIQUERYTYPE