Interface ID2D1CommandList (d2d1_1.h)

Article
08/22/2023

Représente une séquence de commandes qui peuvent être enregistrées et lues.

Héritage

L’interface ID2D1CommandList hérite d’ID2D1Image. ID2D1CommandList a également les types de membres suivants :

Méthodes

L’interface ID2D1CommandList contient ces méthodes.


ID2D1CommandList::Close Indique à la liste de commandes de cesser d’accepter les commandes afin de pouvoir l’utiliser comme entrée à un effet ou dans un appel à ID2D1DeviceContext::D rawImage.
ID2D1CommandList::Stream Diffuse le contenu de la liste de commandes vers le récepteur de commandes spécifié.

Notes

La liste de commandes n’inclut pas de copies statiques des ressources avec l’ensemble de commandes enregistré. Tous les bitmaps, effets et géométries sont stockés en tant que références à la ressource réelle et tous les pinceaux sont stockés par valeur. Toute la création et la destruction des ressources se produisent en dehors de la liste de commandes. Le tableau suivant répertorie les ressources et la façon dont elles sont traitées à l’intérieur d’une liste de commandes.

Ressource	Comment il est traité par la liste de commandes
Pinceau uni	Passé par valeur.
Pinceau bitmap	Le pinceau est passé par valeur, mais l’image bitmap utilisée pour créer le pinceau est en fait référencée.
Pinceaux de dégradé : dégradé linéaire et radial	Le pinceau est passé par valeur, mais la collection de points de dégradé elle-même est référencée. L’objet de collection d’arrêt de dégradé est immuable.
Images bitmap	Passé par référence.
Bloc d’état de dessin	L’état réel sur le contexte de l’appareil est converti en fonctions d’ensemble comme définir la transformation et est passé par valeur.
Géométrie	Objet immuable passé par valeur.
Style de trait	Objet immuable passé par valeur.
Maillage	Objet immuable passé par valeur.

Utilisation d’une liste de commandes en tant que cible

Le pseudocode suivant illustre les différents cas où une cible est définie en tant que liste de commandes ou bitmap.

//create a D2D device from an already created DXGI device 
ID2D1Device *pD2D1Device;
pD2D1Factory->CreateDevice(pDxgiDevice, &amp;pD2D1Device);

//create a D2D device context from the D2D device
ID2D1DeviceContext *pD2D1DeviceContext;
pD2D1Device->CreateD2D1DeviceContext(&amp;pD2D1DeviceContext);

//create command list
ID2D1CommandList *pCommandList1;
pD2D1DeviceContext->CreateCommandList(&amp;pCommandList1);

//CreateBitmap
ID2D1Bitmap *pBitmap1;
ID2D1Bitmap *pBitmap2;
pD2D1DeviceContext->CreateBitmap(…, &amp;pBitmap1);
pD2D1DeviceContext->CreateBitmap(…, &amp;pBitmap2);

//Set the bitmap as the target
pD2D1DeviceContext->SetTarget(pBitmap1);
pD2D1DeviceContext->BeginDraw();
RenderMyVectorContent(pD2D1DeviceContext);
pD2D1DeviceContext->EndDraw();

//Set the command list as the target
pD2D1DeviceContext->SetTarget(pCommandList1);
pD2D1DeviceContext->BeginDraw();
RenderMyVectorContent(pD2D1DeviceContext);
pD2D1DeviceContext->EndDraw();

//Drawing a command list to a bitmap target
pD2D1DeviceContext->SetTarget(pBitmap2);
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->DrawImage(pCommandList1);
pD2D1DeviceContext->EndDraw();

Définissez la bitmap comme cible :Dans ce cas, tout le contenu rendu dans la bitmap est rastérisé. Si cette image bitmap est utilisée ailleurs, elle ne sera pas indépendante de la résolution et si une transformation comme l’échelle de haute qualité est utilisée, elle ne maintient pas la fidélité.
Définissez la liste de commandes comme cible :Dans ce cas, au lieu que la scène soit rastérisée, toutes les commandes sont enregistrées. Lorsque la liste de commandes est utilisée ultérieurement pour le dessin d’écran à l’aide de ID2D1DeviceContext::D rawImage ou passée à un contrôle d’impression XPS, le contenu vectoriel est relu sans perte de fidélité.
Dessin d’une liste de commandes vers une cible bitmap :Dans ce cas, étant donné que la cible est une bitmap, la liste de commandes est dessinée vers l’image bitmap et n’est plus indépendante de la résolution.

La seule façon de conserver le contenu vectoriel pour une lecture ultérieure avec une fidélité totale consiste à définir le type cible en tant que liste de commandes. Lorsqu’une bitmap est définie comme cible, tout dessin sur cette cible est rastérisé.

Utilisation d’une liste de commandes pour créer un pinceau

Les listes de commandes sont un bon moyen de prendre en charge les pinceaux de modèle, car elles sont capables de conserver la fidélité lors de la relecture. Le modèle souhaité peut être stocké sous la forme d’une liste de commandes, qui peut être utilisée pour créer un pinceau d’image. Ce pinceau peut ensuite être utilisé pour peindre les chemins.

Le type de pinceau qui prend en charge le remplissage d’un chemin d’accès avec une liste de commandes est appelé pinceau d’image.

Le psuedocode suivant illustre le processus d’utilisation d’une liste de commandes avec un pinceau d’image.

//Draw the pattern to the command list
ID2D1CommandList *pCommandList;
pD2D1DeviceContext->SetTarget(pCommandList);
pD2D1DeviceContext->BeginDraw();
DrawMyPattern(pD2D1DeviceContext);
pD2D1DeviceContext->EndDraw();

//Create the image brush from the command list
ID2D1ImageBrush *pImageBrush;
pD2D1DeviceContext->CreateImageBrush(
	pCommandList, 
	pImageBrushProperties,
	pBrushProperties,
	&amp;pImageBrush);

//Fill the ellipse with the pattern brush
pD2D1DeviceContext->SetTarget(pTargetBitmap);
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->FillEllipse(pEllipse, pImageBrush);
pD2D1DeviceContext->EndDraw();

Étant donné que le pinceau accepte une image, il présente également les autres avantages suivants :

Étant donné que la sortie d’un graphique d’effets est une image, cette image peut être utilisée pour créer un pinceau d’image, ce qui permet d’utiliser un effet comme remplissage.
Étant donné que la liste de commandes est un type d’image, le contenu vectoriel peut être inséré dans un graphique d’effets et peut également être mis en mosaïque ou utilisé. Par exemple, un avis de copyright volumineux peut être inséré sur un graphique avec une image virtualisée, puis encodé.

Utilisation d’une liste de commandes en remplacement d’une cible de rendu compatible

Les cibles de rendu compatibles sont très souvent utilisées pour le rendu hors écran sur une bitmap intermédiaire qui est ensuite composite avec la scène réelle. En particulier dans le cas de l’impression, l’utilisation de cibles de rendu compatibles augmentera l’empreinte mémoire, car tout sera rastérisé et envoyé à XPS au lieu de conserver les primitives réelles. Dans ce scénario, il est préférable qu’un développeur remplace la cible de rendu compatible par une liste de commandes intermédiaire. Le pseudo-code suivant illustre ce point.

pD2D1Device->CreateDeviceContext(&amp;pD2D1DeviceContext);
pRenderTarget->CreateCompatibleRenderTarget(…, &amp;pCompatibleRenderTarget);

//render to the compatible render target
pCompatibleRenderTarget->BeginDraw();
RenderMyScene1(pCompatibleRenderTarget);
pCompatibleRenderTarget->EndDraw();

//get the bitmap from the compatible render target
pCompatibleRenderTarget->GetBitmap(pCompatBitmap);

//draw this bitmap on the device context
pD2D1DeviceContext->SetTarget(pTargetBitmap)
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->DrawBitmap(pCompatBitmap);
pD2D1DeviceContext->EndDraw();

//draw something else on the compatible render target
pCompatibleRenderTarget->BeginDraw();
pCompatibleRenderTarget->Clear();
pCompatibleRenderTarget&gt;RenderScene2();
pCompatibleRenderTarget->EndDraw();

//get the bitmap from the compatible render target
pCompatibleRenderTarget->GetBitmap(pCompatBitmap);

//draw this bitmap on the device context
pD2D1DeviceContext->SetTarget(pTargetBitmap)
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->DrawBitmap(pCompatBitmap);
pD2D1DeviceContext->EndDraw();


//Use a command list instead for better quality and performance 

//store the original target
pOriginalTarget = pD2D1DeviceContext->GetTarget();

pD2D1DeviceContext->CreateCommandList(pCommandList1);

//draw to command list 1
pD2D1DeviceContext->SetTarget(pCommandList1);
pD2D1DeviceContext->BeginDraw();
RenderMyScene1(pD2D1DeviceContext);
pD2D1DeviceContext->EndDraw();

//draw the command list to the original target
pD2D1DeviceContext->SetTarget(pOriginalTarget);
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->DrawImage(pCommandList1);
pD2D1DeviceContext->EndDraw();

pD2D1DeviceContext->CreateCommandList(pCommandList2);

//draw something else to a new command list
pD2D1DeviceContext->SetTarget(pCommandList2);
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->RenderScene2();
pD2D1DeviceContext->EndDraw();

//draw the new command list on the old command list
pD2D1DeviceContext->SetTarget(pCommandList1);
pD2D1DeviceContext->BeginDraw();
pD2D1DeviceContext->DrawImage(pCommandList2);
pD2D1DeviceContext->EndDraw();

Utilisation d’autres API

Direct2D utilise un modèle simple lors de l’interopérabilité avec les API GDI et Direct3D/DXGI. La liste de commandes n’enregistre pas ces commandes. À la place, il rastérise le contenu en place et le stocke sous la forme d’un ID2D1Bitmap. Étant donné que le contenu est rastérisé, ces points d’interopérabilité ne maintiennent pas une fidélité élevée.

GDI: L’interface du récepteur de commandes ne prend pas en charge les appels Get/ReleaseDC(). Lorsqu’un appel à ID2D1GdiInteropRenderTarget::ReleaseDC est effectué, Direct2D restitue le contenu de la région mise à jour dans un D2D1Bitmap. Cette opération sera relue sous la forme d’un appel DrawBitmap avec alias avec un mode de copie composite. Pour rastériser l’image bitmap au bon ppp, au moment de la lecture des commandes, la valeur DPI définie à l’aide de la fonction SetDPI() est utilisée. Il s’agit du seul cas où le récepteur respecte l’appel SetDPI().

DX: Direct3D ne peut pas être rendu directement dans la liste de commandes. Pour afficher le contenu Direct3D dans ce cas, l’application peut appeler DrawBitmap avec l’ID2D1Bitmap adossé à une surface Direct3D.

Configuration requise


Client minimal pris en charge	Windows 8 et Mise à jour de plateforme pour Windows 7 [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2012 et mise à jour de plateforme pour Windows Server 2008 R2 [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	d2d1_1.h