Метод ID2D1DeviceContext::SetTarget (d2d1_1.h)

Статья
08/22/2023

Точечный рисунок или список команд, для которого теперь будет отображаться контекст устройства Direct2D .

Синтаксис

void SetTarget(
  [in, optional] ID2D1Image *image
);

Параметры

[in, optional] image

Тип: ID2D1Image*

Поверхность или список команд, в котором будет отображаться контекст устройства Direct2D.

Возвращаемое значение

None

Remarks

Целевой объект можно изменить в любое время, в том числе во время рисования контекста.

Целевой объект может быть либо растровым изображением, созданным с помощью флага D2D1_BITMAP_OPTIONS_TARGET , либо списком команд. Другие типы изображений не могут быть заданы в качестве целевого объекта. Например, нельзя задать выходные данные эффекта в качестве целевого объекта. Если целевой объект недопустим, контекст перейдет в состояние ошибки D2DERR_INVALID_TARGET .

SetTarget нельзя использовать для отрисовки в растровом или командном списке из нескольких контекстов устройств одновременно. Изображение считается "отрисовываемым", если оно когда-либо было задано в контексте устройства в пределах интервала времени BeginDraw/EndDraw . Если предпринята попытка отрисовки изображения через несколько контекстов устройств, все последующие контексты устройства после первого будут переходить в состояние ошибки.

Вызывающие абоненты, желающие подключить изображение ко второму контексту устройства, должны сначала вызвать EndDraw в первом контексте устройства.

Ниже приведен пример правильного порядка вызовов.

pDC1->BeginDraw();
pDC1->SetTarget(pImage);
// …
pDC1->EndDraw();

pDC2->BeginDraw();
pDC2->SetTarget(pImage);
// …
pDC2->EndDraw();

Ниже приведен пример неправильного порядка вызовов.

pDC1->BeginDraw();
pDC2->BeginDraw();

pDC1->SetTarget(pImage);

// ...

pDC1->SetTarget(NULL);

pDC2->SetTarget(pImage); // This call is invalid, even though pImage is no longer set on pDC1.

// ...

pDC1->EndDraw(); // This EndDraw SUCCEEDs.
pDC2->EndDraw(); // This EndDraw FAILs

Примечание Изменение целевого объекта не приводит к изменению растрового изображения, с которым представляется целевой объект отрисовки HWND, а также не изменяет растровое изображение, в которое целевой объект отрисовки контроллера домена возвращается или с него.

Этот API упрощает для приложения использование растрового изображения в качестве источника (например, в DrawBitmap) и в качестве назначения одновременно. Попытка использовать растровое изображение в качестве источника в том же контексте устройства, к которому оно привязано в качестве целевого объекта, приведет к переводу контекста устройства в состояние ошибки D2DERR_BITMAP_BOUND_AS_TARGET.

Допустимо, чтобы растровое изображение было привязано к целевому растровому рисунку на нескольких целевых объектах отрисовки одновременно. Приложения, которые делают это, должны правильно синхронизировать отрисовку с Flush или EndDraw.

Целевой объект можно изменить в любое время, в том числе во время рисования контекста.

Вы можете задать для целевого объекта значение NULL. В этом случае вызовы рисования переведут контекст устройства в состояние ошибки с D2DERR_WRONG_STATE. Вызов SetTarget с целевым объектом NULL не приводит к восстановлению исходного целевого растрового изображения в контексте устройства.

Если контекст устройства имеет неоплаченный HDC, контекст перейдет в состояние ошибки D2DERR_WRONG_STATE . Целевой объект не будет изменен.

Если растровое изображение и контекст устройства находятся не в одном домене ресурсов, контекст перейдет в \ состояние ошибки. Целевой объект не будет изменен.

ID2D1RenderTarget::GetPixelSize возвращает размер текущего целевого растрового изображения (или 0, 0), если растровое изображение не привязано). ID2D1RenderTarget::GetSize возвращает размер в пикселях текущего растрового изображения, масштабируемый по DPI целевого объекта отрисовки. SetTarget не влияет на DPI целевого объекта отрисовки.

ID2D1RenderTarget::GetPixelFormat возвращает формат пикселей текущего целевого растрового изображения (или DXGI_FORMAT_UNKNOWN , D2D1_ALPHA_MODE_UNKNOWN, если его нет).

ID2D1Bitmap::CopyFromRenderTarget копирует из текущего привязанного целевого растрового изображения.

Требования

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

См. также раздел

ID2D1Bitmap1

ID2D1DeviceContext

ID2D1DeviceContext::CreateBitmap

ID2D1DeviceContext::GetTarget