ID2D1CommandList 接口 (d2d1_1.h)

项目
08/22/2023

表示可以录制和播放的命令序列。

继承

ID2D1CommandList 接口继承自 ID2D1Image。 ID2D1CommandList 还具有以下类型的成员：

方法

ID2D1CommandList 接口具有这些方法。


ID2D1CommandList：：Close 指示命令列表停止接受命令，以便你可以将其用作效果的输入，或者在调用 ID2D1DeviceContext：:D rawImage 时使用它。
ID2D1CommandList：：Stream 将命令列表的内容流式传输到指定的命令接收器。

备注

命令列表不包括包含记录的命令集的资源的静态副本。所有位图、效果和几何图形都存储为对实际资源的引用，所有画笔都按值存储。所有资源创建和销毁都发生在命令列表之外。下表列出了资源及其在命令列表中处理的方式。

资源	命令列表如何处理它
纯色画笔	按值传递。
位图画笔	画笔按值传递，但实际上引用用于创建画笔的位图。
渐变画笔 - 线性渐变和径向渐变	画笔按值传递，但引用渐变停止集合本身。渐变停止集合对象是不可变的。
位图	由引用传递。
绘图状态块	设备上下文上的实际状态将转换为 set 转换等集函数，并按值传递。
Geometry	按值传递的不可变对象。
笔划样式	按值传递的不可变对象。
网格	按值传递的不可变对象。

使用 CommandList 作为目标

以下伪代码演示了将目标设置为命令列表或位图的不同情况。

//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();

将位图设置为目标：在这种情况下，将呈现到位图的所有内容都光栅化。如果此位图在其他位置使用，则它与分辨率无关，如果使用 “高质量刻度 ”等转换，则不会保持保真度。
将命令列表设置为目标：在这种情况下，将记录所有命令，而不是对场景进行光栅化。稍后使用 ID2D1DeviceContext：:D rawImage 将命令列表用于屏幕绘制或传递给 XPS 打印控件时，将重播矢量内容，且不会丢失保真度。
将命令列表绘制到位图目标：在这种情况下，由于目标是位图，因此命令列表将绘制到位图中，并且不再独立于分辨率。

保留矢量内容以供以后完全保真播放的唯一方法是将目标类型设置为命令列表。将位图设置为目标时，该目标上的任何绘图都将得到光栅化。

使用 CommandList 创建画笔

命令列表是支持模式画笔的好方法，因为它们能够在重播时保持保真度。所需的模式可以存储为命令列表，该列表可用于创建图像画笔。然后，可以使用此画笔绘制路径。

支持使用命令列表填充路径的画笔类型称为图像画笔。

以下 psuedocode 演示了将命令列表与图像画笔配合使用的过程。

//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();

由于画笔接受图像，因此它还具有以下其他优势：

由于效果图的输出是图像，因此此图像可用于创建图像画笔，从而有效地提供使用效果作为填充的功能。
由于命令列表是一种图像，因此矢量内容可以插入到效果图中，也可以平铺或操作。例如，可以在具有虚拟化图像的图形上插入大型版权声明，然后进行编码。

使用 CommandList 作为兼容呈现器目标的替换

兼容的呈现目标经常用于将屏幕外呈现为中间位图，该位图稍后会与实际场景复合。特别是在打印的情况下，使用兼容的呈现目标会增加内存占用量，因为所有内容都将光栅化并发送到 XPS，而不是保留实际基元。在这种情况下，开发人员最好将兼容的呈现目标替换为中间命令列表。以下伪代码说明了这一点。

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();

使用其他 API

Direct2D 在与 GDI 和 Direct3D/DXGI API 互操作时使用简单的模型。命令列表不会记录这些命令。而是将就地的内容光栅化，并将其存储为 ID2D1Bitmap。由于内容已光栅化，因此这些互操作点不保持高保真度。

Gdi： 命令接收器接口不支持 Get/ReleaseDC () 调用。调用 ID2D1GdiInteropRenderTarget：：ReleaseDC 时，Direct2D 会将更新区域的内容呈现为 D2D1Bitmap。这将在复制复合模式下作为别名 DrawBitmap 调用重播。若要以正确的 DPI 对位图进行光栅化，请在播放命令时使用 SetDPI () 函数设置的任何 DPI 值。这是接收器遵循 SetDPI () 调用的唯一情况。

Dx： Direct3D 无法直接呈现到命令列表。在这种情况下，若要呈现 Direct3D 内容，应用程序可以使用由 Direct3D 图面支持的 ID2D1Bitmap 调用 DrawBitmap。

要求


最低受支持的客户端	适用于 Windows 7 的 Windows 8 和平台更新 [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows Server 2012 和适用于 Windows Server 2008 R2 的平台更新 [桌面应用 \|UWP 应用]
目标平台	Windows
标头	d2d1_1.h