Интерфейс ID2D1CommandList (d2d1_1.h)

Статья
08/22/2023

Представляет последовательность команд, которые можно записывать и воспроизводить.

Наследование

Интерфейс ID2D1CommandList наследуется от ID2D1Image. ID2D1CommandList также имеет следующие типы членов:

Методы

Интерфейс ID2D1CommandList содержит следующие методы.


ID2D1CommandList::Close Указывает списку команд прекратить принимать команды, чтобы вы могли использовать его в качестве входных данных для эффекта или в вызове ID2D1DeviceContext::D rawImage.
ID2D1CommandList::Stream Выполняет потоковую передачу содержимого списка команд в указанный приемник команд.

Список команд не включает статические копии ресурсов с записанным набором команд. Все растровые изображения, эффекты и геометрические объекты хранятся в виде ссылок на фактический ресурс, а все кисти хранятся по значению. Создание и уничтожение всех ресурсов происходит за пределами списка команд. В следующей таблице перечислены ресурсы и способы их обработки в списке команд.

Ресурс	Как он обрабатывается в списке команд
Кисть сплошного цвета	Передается по значению.
Битовая кисть	Кисть передается по значению, но на точечный рисунок, используемый для создания кисти, фактически ссылается.
Градиентные кисти — линейный и радиальный градиент	Кисть передается по значению, но на саму коллекцию стоп-градиента ссылается. Объект коллекции градиентных остановок неизменяем.
Растровые изображения	Передается по ссылке.
Блок состояния рисования	Фактическое состояние контекста устройства преобразуется в функции набора, такие как преобразование набора, и передается по значению.
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();

Задайте растровое изображение в качестве целевого объекта:В этом случае все содержимое, отображаемое на растровом рисунке, будет растеризовано. Если это растровое изображение используется в другом месте, оно не будет независимым от разрешения, и если используется такое преобразование, как High Quality Scale , оно не будет поддерживать точность.
Задайте список команд в качестве целевого объекта:В этом случае вместо растеризации сцены записываются все команды. Если позже список команд используется для рисования экрана с помощью 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 использует простую модель при взаимодействии с API GDI и Direct3D/DXGI. Список команд не записывает эти команды. Вместо этого он растеризует содержимое на месте и сохраняет его в виде ID2D1Bitmap. Так как содержимое растеризуется, эти точки взаимодействия не поддерживают высокую точность.

GDI: Интерфейс приемника команд не поддерживает вызовы Get/ReleaseDC(). При вызове ID2D1GdiInteropRenderTarget::ReleaseDC Direct2D преобразует содержимое обновленной области в D2D1Bitmap. Он будет воспроизводиться в виде псевдонима вызова DrawBitmap с режимом копирования составного кода. Для растеризации растрового изображения с правильным DPI во время воспроизведения команд используется любое значение DPI, заданное с помощью функции SetDPI(). Это единственный случай, когда приемник учитывает вызов SetDPI().

DX: Direct3D не может выполнять отрисовку непосредственно в списке команд. Для отрисовки содержимого Direct3D в этом случае приложение может вызвать DrawBitmap с ID2D1Bitmap , поддерживаемым поверхностью Direct3D.

Требования


Минимальная версия клиента	Windows 8 и Обновление платформы для Windows 7 [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2012 и обновление платформы для Windows Server 2008 R2 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	d2d1_1.h