PFND3DDDI_RENDERCB fonction de rappel (d3dumddi.h)

Article
08/07/2023

La fonction pfnRenderCb envoie la mémoire tampon de commande actuelle pour le rendu au pilote miniport d’affichage.

Syntaxe

PFND3DDDI_RENDERCB Pfnd3dddiRendercb;

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

Paramètres

hDevice

Handle de l’appareil d’affichage (contexte graphique).

unnamedParam2

pData [in, out]

Pointeur vers une structure de D3DDDICB_RENDER qui décrit la mémoire tampon de commande actuelle à afficher.

Valeur retournée

pfnRenderCb retourne l’une des valeurs suivantes :

Code de retour	Description
S_OK	La mémoire tampon de commande a été correctement affichée.
D3DDDIERR_PRIVILEGEDINSTRUCTION	Le pilote de miniport d’affichage a détecté une instruction privilégiée dans la mémoire tampon de commande ; les instructions privilégiées ne peuvent pas être présentes dans une mémoire tampon de commandes.
D3DDDIERR_ILLEGALINSTRUCTION	Le pilote de miniport d’affichage a détecté des instructions que le matériel graphique ne peut pas prendre en charge.
D3DDDIERR_INVALIDHANDLE	Le pilote miniport d’affichage a détecté un handle non valide dans la mémoire tampon de commande.
D3DDDIERR_CANTRENDERLOCKEDALLOCATION	Le gestionnaire de mémoire vidéo a détecté des références à une allocation verrouillée dans la liste d’allocation. Notez que le gestionnaire de mémoire vidéo retourne cette erreur uniquement s’il n’a pas pu repositionner l’allocation sur un AGP ou un segment de mémoire système.
D3DDDIERR_INVALIDUSERBUFFER	Le pilote de miniport d’affichage a détecté une sous-exécution ou un dépassement de données ou d’instructions. Autrement dit, le pilote a reçu moins ou plus d’instructions ou de données qu’il ne l’attendait.
E_OUTOFMEMORY	pfnRenderCb n’a pas pu se terminer en raison d’une mémoire insuffisante.
E_INVALIDARG	Les paramètres ont été validés et déterminés comme incorrects.

Cette fonction peut également retourner d’autres valeurs HRESULT.

Remarques

Lorsque le pilote d’affichage en mode utilisateur doit envoyer la mémoire tampon de commande actuelle pour le rendu au pilote miniport d’affichage (par exemple, lors d’un appel à la fonction Flush ou Flush (D3D10) du pilote d’affichage en mode utilisateur), le pilote d’affichage en mode utilisateur doit appeler la fonction pfnRenderCb . Le pilote d’affichage en mode utilisateur doit définir le paramètre hDevice sur la valeur du runtime Microsoft Direct3D fourni lors de l’appel CreateDevice ou CreateDevice(D3D10). Dans la structure D3DDDICB_RENDER vers laquelle pointe le paramètre pData , le pilote d’affichage en mode utilisateur doit également définir :

Membre CommandLength au nombre d’octets de commandes dans la mémoire tampon de commandes qui démarrent à partir du décalage zéro.
Le membre CommandOffset est différent de zéro si le pilote d’affichage en mode utilisateur doit spécifier un décalage sur la première commande matérielle dans la mémoire tampon de commande.
Membre NumAllocations du nombre d’éléments dans la liste d’allocation.
Membre NumPatchLocations du nombre d’éléments dans la liste patch-location.

Après un appel à pfnRenderCb, le pilote d’affichage en mode utilisateur doit déterminer l’adresse de base et la taille de la mémoire tampon de commande qu’il doit utiliser pour sa prochaine soumission à partir des valeurs retournées dans les membres pNewCommandBuffer et NewCommandBufferSize de D3DDDICB_RENDER. De même, le pilote doit déterminer l’adresse de base et le nombre d’éléments de la liste d’allocation et de la liste d’emplacements correctives suivantes à partir des valeurs retournées dans les membrespNewAllocationList et NewAllocationListSize respectivement.

Si le pilote d’affichage en mode utilisateur détecte que la plupart des vidages de mémoire tampon de commande sont dus au manque d’espace dans la mémoire tampon de commandes, la liste d’allocation ou la liste d’emplacements correctifs, le pilote peut demander leur redimensionnement. Pour redimensionner la mémoire tampon de commande, le pilote définit l’indicateur de champ bit ResizeCommandBuffer dans le membre Flags de D3DDDICB_RENDER et place la taille demandée dans le membre NewCommandBufferSize de D3DDDICB_RENDER. De même, pour redimensionner la liste d’allocation, le pilote définit l’indicateur de champ bit ResizeAllocationList dans le membre Indicateurs de D3DDDICB_RENDER et place le nombre d’éléments demandé dans le membre NewAllocationListSize de D3DDDICB_RENDER. Pour redimensionner la liste patch-location, le pilote définit l’indicateur de champ bit ResizePatchLocationList dans le membre Flags de D3DDDICB_RENDER et place le nombre d’éléments demandé dans le membre NewPatchLocationListSize de D3DDDICB_RENDER.

Note Même si le pilote peut demander que la mémoire tampon de commande et les listes d’allocation et d’emplacement corrective soient redimensionnées, le gestionnaire de mémoire vidéo peut ne pas être en mesure de se conformer. Par conséquent, que l’appel à pfnRenderCb réussisse ou non, le pilote doit vérifier les valeurs retournées dans les membres NewCommandBufferSize, NewAllocationListSize et NewPatchLocationListSize de D3DDDICB_RENDER.

Si le pilote d’affichage en mode utilisateur définit le membre hContext de la structure D3DDDICB_RENDER pointée sur NULL par le paramètre pData, le runtime Microsoft Direct3D envoie l’opération de rendu au contexte par défaut de l’appareil. Si le pilote d’affichage en mode utilisateur définit hContext sur un handle valide que la fonction pfnCreateContextCb a précédemment retourné et qui représente un contexte d’appareil, le runtime Direct3D envoie l’opération de rendu à ce contexte. Remarque de Direct3D version 11 : Pour plus d’informations sur la façon dont le pilote appelle pfnRenderCb, consultez Modifications de Direct3D 10.

Exemples

L’exemple de code suivant montre comment envoyer la mémoire tampon de commande actuelle pour le rendu sur le pilote miniport d’affichage. Cet exemple de code génère la liste d’allocation après la génération de la mémoire tampon de commande et de la liste de correctifs. Cela n’est pas optimal pour les performances, car la mémoire tampon de commande est analysée plus que nécessaire. Toutefois, cette implémentation est plus facile à afficher. Dans un pilote de production, la génération de la mémoire tampon de commande en même temps que les listes d’allocation et de correctifs est plus efficace.

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;
    }

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et les versions ultérieures des systèmes d’exploitation Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	d3dumddi.h (inclure D3dumddi.h)