Interface ID2D1CommandList (d2d1_1.h)

Artigo
08/22/2023

Representa uma sequência de comandos que podem ser gravados e reproduzidos.

Herança

A interface ID2D1CommandList herda de ID2D1Image. ID2D1CommandList também tem estes tipos de membros:

Métodos

A interface ID2D1CommandList tem esses métodos.


ID2D1CommandList::Close Instrui a lista de comandos a parar de aceitar comandos para que você possa usá-la como uma entrada para um efeito ou em uma chamada para ID2D1DeviceContext::D rawImage.
ID2D1CommandList::Stream Transmite o conteúdo da lista de comandos para o coletor de comandos especificado.

Comentários

A lista de comandos não inclui cópias estáticas de recursos com o conjunto de comandos gravado. Todos os bitmaps, efeitos e geometrias são armazenados como referências ao recurso real e todos os pincéis são armazenados por valor. Toda a criação e destruição de recursos ocorre fora da lista de comandos. A tabela a seguir lista os recursos e como eles são tratados dentro de uma lista de comandos.

Recurso	Como ele é tratado pela lista de comandos
Pincel de cor sólida	Passado por valor.
Pincel de bitmap	O pincel é passado por valor, mas o bitmap usado para criar o pincel é de fato referenciado.
Pincéis de gradiente – gradiente linear e radial	O pincel é passado por valor, mas a coleção de parada de gradiente em si é referenciada. O objeto de coleção de parada de gradiente é imutável.
Bitmaps	Passado por referência.
Bloco de estado de desenho	O estado real no contexto do dispositivo é convertido em funções definidas, como a transformação de conjunto, e é passado por valor.
Geometry	Objeto imutável passado por valor.
Estilo de traço	Objeto imutável passado por valor.
Malha	Objeto imutável passado por valor.

Usando uma CommandList como um destino

O pseudocódigo a seguir ilustra os diferentes casos em que um destino é definido como uma lista de comandos ou como um 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();

Defina o bitmap como o destino:Nesse caso, todo o conteúdo renderizado para o bitmap é rasterizado. Se esse bitmap for usado em outro lugar, ele não será independente de resolução e, se uma transformação como Escala de Alta Qualidade for usada, ela não manterá a fidelidade.
Defina a lista de comandos como o destino:Nesse caso, em vez de a cena ser rasterizada, todos os comandos são gravados. Quando a lista de comandos é usada posteriormente para desenho de tela usando ID2D1DeviceContext::D rawImage ou passada para um controle de impressão XPS, o conteúdo do vetor é reproduzido sem perda de fidelidade.
Desenhando uma lista de comandos para um destino de bitmap:Nesse caso, como o destino é um bitmap, a lista de comandos é desenhada para o bitmap e não é mais independente de resolução.

A única maneira de reter o conteúdo do vetor para reprodução posterior com fidelidade total é definir o tipo de destino como uma lista de comandos. Quando um bitmap é definido como um destino, qualquer desenho nesse destino será rasterizado.

Usando uma CommandList para criar um pincel

As listas de comandos são uma boa maneira de dar suporte a pincéis de padrão, pois são capazes de manter a fidelidade na reprodução. O padrão desejado pode ser armazenado como uma lista de comandos, que pode ser usada para criar um pincel de imagem. Esse pincel pode ser usado para pintar caminhos.

O tipo de pincel que dá suporte ao preenchimento de um caminho com uma lista de comandos é chamado de pincel de imagem.

O psuedocode a seguir ilustra o processo de usar uma lista de comandos com um pincel de imagem.

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

Como o pincel aceita uma imagem, ele também tem os seguintes outros benefícios:

Como a saída de um grafo de efeito é uma imagem, essa imagem pode ser usada para criar um pincel de imagem, que fornece efetivamente a capacidade de usar um efeito como preenchimento.
Como a lista de comandos é um tipo de imagem, o conteúdo do vetor pode ser inserido em um grafo de efeito e também pode ser lado a lado ou operado. Por exemplo, um aviso de direitos autorais grande pode ser inserido em um grafo com uma imagem virtualizada e, em seguida, codificado.

Usando uma CommandList como uma substituição para um destino de renderização compatível

Destinos de renderização compatíveis são usados com muita frequência para renderização fora da tela para um bitmap intermediário que é composto posteriormente com a cena real. Especialmente no caso de impressão, o uso de destinos de renderização compatíveis aumentará o volume de memória porque tudo será rasterizado e enviado ao XPS em vez de reter os primitivos reais. Nesse cenário, é melhor que um desenvolvedor substitua o destino de renderização compatível por uma lista de comandos intermediária. O pseudocódigo a seguir ilustra esse ponto.

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

Trabalhando com outras APIs

O Direct2D emprega um modelo simples ao interoperar com APIs GDI e Direct3D/DXGI. A lista de comandos não registra esses comandos. Em vez disso, ele rasteriza o conteúdo no local e os armazena como um ID2D1Bitmap. Como o conteúdo é rasterizado, esses pontos de interoperabilidade não mantêm alta fidelidade.

GDI: A interface do coletor de comandos não dá suporte a chamadas Get/ReleaseDC(). Quando uma chamada para ID2D1GdiInteropRenderTarget::ReleaseDC é feita, o Direct2D renderiza o conteúdo da região atualizada em um D2D1Bitmap. Isso será reproduzido como uma chamada DrawBitmap com alias com um modo de composição de cópia. Para rasterizar o bitmap no DPI correto, no momento da reprodução dos comandos, qualquer valor de DPI definido usando a função SetDPI() é usado. Esse é o único caso em que o coletor respeita a chamada SetDPI().

DX: O Direct3D não pode ser renderizado diretamente na lista de comandos. Para renderizar o conteúdo do Direct3D nesse caso, o aplicativo pode chamar DrawBitmap com o ID2D1Bitmap apoiado por uma superfície Direct3D.

Requisitos


Cliente mínimo com suporte	Windows 8 e Platform Update para Windows 7 [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2012 e Platform Update para Windows Server 2008 R2 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	d2d1_1.h