ID2D1CommandList 介面 (d2d1_1.h)

發行項
08/22/2023

表示可以記錄和播放的命令序列。

繼承

ID2D1CommandList介面繼承自ID2D1Image。 ID2D1CommandList 也有下列類型的成員：

方法

ID2D1CommandList介面具有這些方法。


ID2D1CommandList：：Close 指示命令清單停止接受命令，以便您可以使用它做為效果的輸入，或是呼叫 ID2D1DeviceCoNtext：:D rawImage。
ID2D1CommandList：：Stream 將命令清單的內容串流至指定的命令接收。

備註

命令清單不包含具有記錄命令集的資源靜態複本。所有點陣圖、效果和幾何都會儲存為實際資源的參考，而且所有筆刷都會以值儲存。所有資源建立和解構都會在命令清單之外發生。下表列出資源，以及如何在命令清單中加以處理。

資源	命令清單處理方式
純色筆刷	以值傳遞。
點陣圖筆刷	筆刷會以值傳遞，但用來建立筆刷的點陣圖實際上是參考的。
漸層筆刷 – 線性和星形漸層	筆刷會以值傳遞，但會參考漸層停止集合本身。漸層停止集合物件是不可變的。
點陣圖	以傳址方式傳遞。
繪圖狀態欄塊	裝置內容上的實際狀態會轉換成集合函式，例如 set transform，並以值傳遞。
幾何形狀	以值傳遞的不可變物件。
筆劃樣式	以值傳遞的不可變物件。
網狀	以值傳遞的不可變物件。

使用 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。由於內容會點陣化，因此這些 Interop 點不會維持高精確度。

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 2008 R2 的 Windows Server 2012 和平臺更新 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	d2d1_1.h