Interfaz ID2D1CommandList (d2d1_1.h)

Artículo
08/22/2023

Representa una secuencia de comandos que se pueden grabar y reproducir.

Herencia

La interfaz ID2D1CommandList hereda de ID2D1Image. ID2D1CommandList también tiene estos tipos de miembros:

Métodos

La interfaz ID2D1CommandList tiene estos métodos.


ID2D1CommandList::Close Indica a la lista de comandos que deje de aceptar comandos para que pueda usarlo como entrada para un efecto o en una llamada a ID2D1DeviceContext::D rawImage.
ID2D1CommandList::Stream Transmite el contenido de la lista de comandos al receptor de comandos especificado.

Comentarios

La lista de comandos no incluye copias estáticas de recursos con el conjunto registrado de comandos. Todos los mapas de bits, los efectos y las geometrías se almacenan como referencias al recurso real y todos los pinceles se almacenan por valor. Toda la creación y destrucción de recursos se produce fuera de la lista de comandos. En la tabla siguiente se enumeran los recursos y cómo se tratan dentro de una lista de comandos.

Recurso	Cómo se trata mediante la lista de comandos
Pincel de color sólido	Pasado por valor.
Pincel de mapa de bits	El pincel se pasa por valor, pero se hace referencia al mapa de bits que se usa para crear el pincel.
Pinceles de degradado: degradado lineal y radial	El pincel se pasa por valor, pero se hace referencia a la propia colección de detención de degradado. El objeto de colección de detención de degradado es inmutable.
Mapas de bits	Se pasa por referencia.
Bloque de estado de dibujo	El estado real en el contexto del dispositivo se convierte en funciones establecidas como la transformación set y se pasa por valor.
Geometría	Objeto inmutable pasado por valor.
Estilo de trazo	Objeto inmutable pasado por valor.
En malla	Objeto inmutable pasado por valor.

Usar commandList como destino

En el pseudocódigo siguiente se muestran los distintos casos en los que un destino se establece como una lista de comandos o como un mapa de bits.

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

Establezca el mapa de bits como destino:En este caso, todo el contenido representado en el mapa de bits se rasteriza. Si este mapa de bits se usa en otro lugar, no será independiente de la resolución y, si se usa una transformación como escala de alta calidad , no mantendrá la fidelidad.
Establezca la lista de comandos como destino:En este caso, en lugar de la escena que se está rasterizando, se registran todos los comandos. Cuando la lista de comandos se usa más adelante para el dibujo en pantalla mediante ID2D1DeviceContext::D rawImage o se pasa a un control de impresión XPS, el contenido vectorial se reproduce sin pérdida de fidelidad.
Dibujar una lista de comandos en un destino de mapa de bits:En este caso, dado que el destino es un mapa de bits, la lista de comandos se dibuja en el mapa de bits y ya no es independiente de la resolución.

La única manera de conservar el contenido vectorial para la reproducción posterior con fidelidad total es establecer el tipo de destino como una lista de comandos. Cuando se establece un mapa de bits como destino, cualquier dibujo de ese destino se rasterizará.

Usar un objeto CommandList para crear un pincel

Las listas de comandos son una buena manera de admitir pinceles de patrones, ya que son capaces de conservar la fidelidad en la reproducción. El patrón deseado se puede almacenar como una lista de comandos, que se puede usar para crear un pincel de imagen. A continuación, este pincel se puede usar para pintar trazados.

El tipo de pincel que admite rellenar una ruta de acceso con una lista de comandos se denomina pincel de imagen.

En el siguiente psuedocode se muestra el proceso de uso de una lista de comandos con un pincel de imagen.

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

Dado que el pincel acepta una imagen, también tiene las siguientes ventajas:

Dado que la salida de un gráfico de efectos es una imagen, esta imagen se puede usar para crear un pincel de imagen, lo que proporciona eficazmente la capacidad de usar un efecto como relleno.
Dado que la lista de comandos es un tipo de imagen, el contenido vectorial se puede insertar en un gráfico de efectos y también puede ser en mosaico o en el que se puede operar. Por ejemplo, un aviso de copyright grande se puede insertar sobre un grafo con una imagen virtualizada y, a continuación, codificarse.

Usar commandList como reemplazo de un destino de representación compatible

Los destinos de representación compatibles se usan con mucha frecuencia para la representación fuera de la pantalla en un mapa de bits intermedio que se compone posteriormente con la escena real. Especialmente en el caso de la impresión, el uso de destinos de representación compatibles aumentará la superficie de memoria porque todo se rasterizará y enviará a XPS en lugar de conservar los primitivos reales. En este escenario, un desarrollador es mejor reemplazar el destino de representación compatible por una lista de comandos intermedia. El pseudocódigo siguiente ilustra este 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();

Trabajar con otras API

Direct2D emplea un modelo simple al interoperar con las API GDI y Direct3D/DXGI. La lista de comandos no registra estos comandos. En su lugar, rasteriza el contenido en su lugar y los almacena como ID2D1Bitmap. Dado que el contenido está rasterizado, estos puntos de interoperabilidad no mantienen una alta fidelidad.

GDI: La interfaz del receptor de comandos no admite llamadas Get/ReleaseDC(). Cuando se realiza una llamada a ID2D1GdiInteropRenderTarget::ReleaseDC , Direct2D representa el contenido de la región actualizada en un objeto D2D1Bitmap. Se reproducirá como una llamada DrawBitmap con alias con un modo compuesto de copia. Para rasterizar el mapa de bits en el valor de PPP correcto, en el momento de la reproducción de los comandos, se usa cualquier valor de PPP que se establezca mediante la función SetDPI(). Este es el único caso en el que el receptor respeta la llamada SetDPI().

DX: Direct3D no se puede representar directamente en la lista de comandos. Para representar el contenido de Direct3D en este caso, la aplicación puede llamar a DrawBitmap con el ID2D1Bitmap respaldado por una superficie direct3D.

Requisitos


Cliente mínimo compatible	Windows 8 y Platform Update para Windows 7 [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2012 y actualización de plataforma para Windows Server 2008 R2 [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	d2d1_1.h