Interfaccia ID2D1CommandList (d2d1_1.h)

Articolo
08/22/2023

Rappresenta una sequenza di comandi che possono essere registrati e riprodotti.

Ereditarietà

L'interfaccia ID2D1CommandList eredita da ID2D1Image. ID2D1CommandList include anche questi tipi di membri:

Metodi

L'interfaccia ID2D1CommandList include questi metodi.


ID2D1CommandList::Close Indica all'elenco comandi di interrompere l'accettazione dei comandi in modo che sia possibile usarlo come input per un effetto o in una chiamata a ID2D1DeviceContext::D rawImage.
ID2D1CommandList::Stream Invia il contenuto dell'elenco di comandi al sink di comandi specificato.

Commenti

L'elenco dei comandi non include copie statiche delle risorse con il set registrato di comandi. Tutte le bitmap, gli effetti e le geometrie vengono archiviate come riferimenti alla risorsa effettiva e tutti i pennelli vengono archiviati in base al valore. Tutte le operazioni di creazione e distruzione delle risorse vengono eseguite all'esterno dell'elenco di comandi. La tabella seguente elenca le risorse e la modalità di trattamento all'interno di un elenco di comandi.

Risorsa	Come viene trattato dall'elenco dei comandi
Pennello a tinta unita	Passato per valore.
Pennello bitmap	Il pennello viene passato per valore, ma la bitmap usata per creare il pennello viene fatto riferimento.
Pennelli sfumatura: sfumatura lineare e radiale	Il pennello viene passato per valore, ma viene fatto riferimento alla raccolta di interruzioni sfumatura stessa. L'oggetto raccolta di interruzioni sfumatura non è modificabile.
Bitmap	Passato per riferimento.
Blocco stato disegno	Lo stato effettivo nel contesto del dispositivo viene convertito in funzioni impostate come la trasformazione impostata e viene passato per valore.
Geometria	Oggetto non modificabile passato per valore.
Stile tratto	Oggetto non modificabile passato per valore.
Mesh	Oggetto non modificabile passato per valore.

Uso di un commandList come destinazione

Il codice pseudoco seguente illustra i diversi casi in cui una destinazione viene impostata come elenco di comandi o come 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();

Impostare la bitmap come destinazione:In questo caso, tutti i contenuti sottoposti a rendering alla bitmap vengono rasterizzati. Se questa bitmap viene usata altrove, non sarà indipendente dalla risoluzione e, se viene usata una trasformazione come La scalabilità di alta qualità, non manterrà la fedeltà.
Impostare l'elenco di comandi come destinazione:In questo caso, anziché la scena in fase di rasterizzazione, vengono registrati tutti i comandi. Quando l'elenco di comandi viene usato più avanti per la disegno dello schermo usando ID2D1DeviceContext::D rawImage o passato a un controllo di stampa XPS, il contenuto del vettore viene riprodotto senza perdita di fedeltà.
Disegno di un elenco di comandi in una destinazione bitmap:In questo caso perché la destinazione è una bitmap, l'elenco di comandi viene disegnato nella bitmap e non è più indipendente dalla risoluzione.

L'unico modo per conservare il contenuto vettoriale per la riproduzione successiva con fedeltà completa consiste nell'impostare il tipo di destinazione come elenco di comandi. Quando una bitmap viene impostata come destinazione, qualsiasi disegno su tale destinazione otterrà la rasterizzazione.

Uso di un commandList per creare un pennello

Gli elenchi di comandi sono un buon modo per supportare i pennelli dei modelli, perché sono in grado di conservare la fedeltà sulla riproduzione. Il modello desiderato può essere archiviato come elenco di comandi, che può essere usato per creare un pennello di immagine. Questo pennello può quindi essere usato per disegnare percorsi.

Il tipo di pennello che supporta il riempimento di un percorso con un elenco di comandi è denominato pennello immagine.

Il psuedocode seguente illustra il processo di utilizzo di un elenco di comandi con un pennello di immagine.

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

Poiché il pennello accetta un'immagine, offre anche altri vantaggi:

Poiché l'output di un grafico degli effetti è un'immagine, questa immagine può essere usata per creare un pennello di immagine, che offre in modo efficace la possibilità di usare un effetto come riempimento.
Poiché l'elenco di comandi è un tipo di immagine, il contenuto del vettore può essere inserito in un grafico degli effetti e può essere riquadri o gestito. Ad esempio, un avviso di copyright di grandi dimensioni può essere inserito su un grafico con un'immagine virtualizzata e quindi codificata.

Uso di un commandList come sostituzione di una destinazione di rendering compatibile

Le destinazioni di rendering compatibili vengono usate molto spesso per il rendering dello schermo esterno a una bitmap intermedia che viene successivamente composita con la scena effettiva. Soprattutto nel caso della stampa, l'uso di destinazioni di rendering compatibili aumenterà il footprint di memoria perché tutto verrà rasterizzato e inviato a XPS anziché conservare le primitive effettive. In questo scenario, uno sviluppatore è meglio sostituire la destinazione di rendering compatibile con un elenco di comandi intermedi. Il codice pseudo seguente illustra questo punto.

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

Uso di altre API

Direct2D usa un modello semplice durante l'interoperabilità con API GDI e Direct3D/DXGI. L'elenco dei comandi non registra questi comandi. Invece rasterizza il contenuto sul posto e li archivia come ID2D1Bitmap. Poiché il contenuto viene rasterizzato, questi punti di interoperabilità non mantengono alta fedeltà.

GDI: L'interfaccia sink dei comandi non supporta le chiamate Get/ReleaseDC(). Quando viene eseguita una chiamata a ID2D1GdiInteropRenderTarget::ReleaseDC , Direct2D esegue il rendering del contenuto dell'area aggiornata in una mappa D2D1Bitmap. Verrà riprodotto come chiamata DrawBitmap aliased con una modalità composita di copia. Per rasterizzare la bitmap in corrispondenza del valore DPI corretto, al momento della riproduzione dei comandi, viene usato il valore DPI che usa la funzione SetDPI(). Questo è l'unico caso in cui il sink rispetta la chiamata SetDPI().

DX: Direct3D non può eseguire il rendering direttamente nell'elenco dei comandi. Per eseguire il rendering del contenuto Direct3D in questo caso, l'applicazione può chiamare DrawBitmap con l'ID2D1Bitmap supportato da una superficie Direct3D.

Requisiti


Client minimo supportato	Windows 8 e Platform Update per Windows 7 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2012 e Aggiornamento della piattaforma per Windows Server 2008 R2 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	d2d1_1.h