PFND3DDDI_RENDERCB Rückruffunktion (d3dumddi.h)

Artikel
08/07/2023

Die pfnRenderCb-Funktion übermittelt den aktuellen Befehlspuffer zum Rendern an den Anzeige-Miniporttreiber.

Syntax

PFND3DDDI_RENDERCB Pfnd3dddiRendercb;

HRESULT Pfnd3dddiRendercb(
  HANDLE hDevice,
  D3DDDICB_RENDER *unnamedParam2
)
{...}

Parameter

hDevice

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

unnamedParam2

pData [in, out]

Ein Zeiger auf eine D3DDDICB_RENDER-Struktur , die den aktuellen zu rendernden Befehlspuffer beschreibt.

Rückgabewert

pfnRenderCb gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
S_OK	Der Befehlspuffer wurde erfolgreich gerendert.
D3DDDIERR_PRIVILEGEDINSTRUCTION	Der Anzeige-Miniporttreiber hat eine privilegierte Anweisung im Befehlspuffer erkannt. privilegierte Anweisungen können nicht in einem Befehlspuffer vorhanden sein.
D3DDDIERR_ILLEGALINSTRUCTION	Der Display-Miniporttreiber hat Anweisungen erkannt, die grafikhardware nicht unterstützen kann.
D3DDDIERR_INVALIDHANDLE	Der Anzeige-Miniporttreiber hat ein ungültiges Handle im Befehlspuffer erkannt.
D3DDDIERR_CANTRENDERLOCKEDALLOCATION	Der Videospeicher-Manager hat Verweise auf eine gesperrte Zuordnung in der Zuordnungsliste erkannt. Beachten Sie, dass der Videospeicher-Manager diesen Fehler nur dann zurückgibt, wenn die Zuordnung nicht zu einem AGP- oder Systemspeichersegment neu positioniert werden konnte.
D3DDDIERR_INVALIDUSERBUFFER	Der Anzeige-Miniporttreiber hat einen Unter- oder Überlauf von Daten oder Anweisungen erkannt. Das heißt, der Treiber erhielt weniger oder mehr Anweisungen oder Daten als erwartet.
E_OUTOFMEMORY	pfnRenderCb konnte aufgrund von unzureichendem Arbeitsspeicher nicht abgeschlossen werden.
E_INVALIDARG	Die Parameter wurden überprüft und als falsch ermittelt.

Diese Funktion gibt möglicherweise auch andere HRESULT-Werte zurück.

Hinweise

Wenn der Anzeigetreiber im Benutzermodus den aktuellen Befehlspuffer für das Rendern an den Anzeigeminiporttreiber übermitteln muss (z. B. während eines Aufrufs der Funktion Flush oder Flush(D3D10) des Benutzermodusanzeigetreibers), muss der Benutzermodus-Anzeigetreiber die PfnRenderCb-Funktion aufrufen. Der Anzeigetreiber für den Benutzermodus sollte den hDevice-Parameter auf den Wert festlegen, den die Microsoft Direct3D-Runtime während des CreateDevice- oder CreateDevice(D3D10)-Aufrufs bereitgestellt hat. In der D3DDDICB_RENDER-Struktur , auf die der pData-Parameter verweist, sollte der Benutzermodusanzeigetreiber auch Folgendes festlegen:

Das CommandLength-Element zur Anzahl der Bytes von Befehlen im Befehlspuffer, die mit offset 0 beginnen.
Der CommandOffset-Member auf ungleich null, wenn der Benutzermodusanzeigetreiber einen Offset zum ersten Hardwarebefehl im Befehlspuffer angeben muss.
Der NumAllocations-Member zur Anzahl der Elemente in der Zuordnungsliste.
Der NumPatchLocations-Member zur Anzahl der Elemente in der Patchspeicherortliste.

Nach einem Aufruf von pfnRenderCb muss der Benutzermodusanzeigetreiber die Basisadresse und Größe des Befehlspuffers, den er für die nächste Übermittlung verwenden soll, anhand der Werte bestimmen, die in den pNewCommandBuffer - und NewCommandBufferSize-Membern von D3DDDICB_RENDER zurückgegeben werden. Ebenso muss der Treiber die Basisadresse und die Anzahl der Elemente der nächsten Zuordnungsliste und patch-location-Liste anhand der Werte bestimmen, die in den Membern pNewAllocationList und NewAllocationListSize bzw. pNewPatchLocationList und NewPatchLocationListSize zurückgegeben werden.

Wenn der Anzeigetreiber im Benutzermodus erkennt, dass die meisten Befehlspufferleerungen darauf zurückzuführen sind, dass dem Treiber in der Befehlspuffer-, Zuordnungsliste oder Patchspeicherortliste nicht mehr platzt, kann der Treiber eine Größenänderung anfordern. Um die Größe des Befehlspuffers zu ändern, legt der Treiber das Bitfeldflag ResizeCommandBuffer im Flags-Element von D3DDDICB_RENDER fest und legt die angeforderte Größe in das NewCommandBufferSize-Element von D3DDDICB_RENDER. Ebenso legt der Treiber zum Ändern der Größe der Zuordnungsliste das Bitfeldflag ResizeAllocationList im Flags-Element von D3DDDICB_RENDER fest und legt die angeforderte Anzahl von Elementen in das NewAllocationListSize-Element von D3DDDICB_RENDER. Um die Größe der Patchspeicherortliste zu ändern, legt der Treiber das Bitfeldflag ResizePatchLocationList im Flags-Element von D3DDDICB_RENDER fest und legt die angeforderte Anzahl von Elementen im NewPatchLocationListSize-Element von D3DDDICB_RENDER.

Hinweis Obwohl der Treiber anfordern kann, dass die Größe des Befehlspuffers und der Zuordnungs- und Patchspeicherorte geändert wird, kann der Videospeicher-Manager möglicherweise nicht konform sein. Daher sollte der Treiber unabhängig davon, ob der Aufruf von pfnRenderCb erfolgreich ist, die Werte überprüfen, die in den Membern NewCommandBufferSize, NewAllocationListSize und NewPatchLocationListSize von D3DDDICB_RENDER zurückgegeben werden.

Wenn der Anzeigetreiber für den Benutzermodus den hContext-Member der D3DDDICB_RENDER-Struktur festlegt, auf die der pData-Parameter verweist, auf NULL, sendet die Microsoft Direct3D-Runtime den Renderingvorgang an den Standardkontext des Geräts. Wenn der Anzeigetreiber für den Benutzermodus hContext auf ein gültiges Handle festlegt, das die pfnCreateContextCb-Funktion zuvor zurückgegeben hat und das einen Gerätekontext darstellt, sendet die Direct3D-Runtime den Renderingvorgang an diesen Kontext. Direct3D Version 11 Hinweis: Weitere Informationen dazu, wie der Treiber pfnRenderCb aufruft, finden Sie unter Änderungen von Direct3D 10.

Beispiele

Das folgende Codebeispiel zeigt, wie Sie den aktuellen Befehlspuffer zum Rendern an den Anzeige-Miniporttreiber übermitteln. In diesem Codebeispiel wird die Zuordnungsliste generiert, nachdem der Befehlspuffer und die Patchliste generiert wurden. Dies ist für die Leistung nicht optimal, da der Befehlspuffer mehr als erforderlich analysiert wird. Diese Implementierung ist jedoch einfacher anzuzeigen. In einem Produktionstreiber ist das Generieren des Befehlspuffers zur gleichen Zeit wie die Zuordnungs- und Patchlisten effizienter.

VOID CD3DContext::SubmitDXVABuffer(DWORD Size) {
    D3DDDICB_RENDER     renderCBData = {0};
    DWORD               dwAllocationListUsed;
    HRESULT             hr;

    if (GenerateAllocationListFromCmdBuf(R200UpdateQSParamsForDXVASubmit(m_pR200Ctx, Size), m_sContexts[MULTI_ENGINE_NODE_VIDEO].pHwCmdBufAllocList, m_dwHwCmdBufAllocListSize, &dwAllocationListUsed) == FALSE)
    {
        DBG_BREAK;
        return;
    }

    // 3-D and video packets must be in sync. If the last packet that was sent went to 
    // the 3-D engine, that packet must finish before the new packet runs on the hardware.

    renderCBData.CommandOffset  = 0;
    renderCBData.CommandLength  = Size + sizeof(UMD_CMDBUF_INFO);
    renderCBData.NumAllocations = dwAllocationListUsed;
    renderCBData.hContext = m_sContexts[MULTI_ENGINE_NODE_VIDEO].hContext;

    // Copy command-buffer data from the internal buffer to the buffer that was created by dxgkrnl
    memcpy(m_sContexts[MULTI_ENGINE_NODE_VIDEO].pHwCmdBuf, m_pHwCmdBuf + GetCmdBufPreambleSize(m_pR200Ctx), renderCBData.CommandLength);
 
    m_d3dCallbacks.pfnRenderCb(m_hD3D, &renderCBData);

        // Makes video the last engine that work was submitted to
        m_LastEngineSubmit = MULTI_ENGINE_NODE_VIDEO;
    }

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows Vista und höheren Versionen der Windows-Betriebssysteme.
Zielplattform	Desktop
Kopfzeile	d3dumddi.h (include D3dumddi.h)