Метод IDCompositionSurface::BeginDraw (dcomp.h)

Статья
03/14/2023

Инициирует рисование этого объекта поверхности Microsoft DirectComposition. Прямоугольник обновления должен находиться в пределах поверхности; В противном случае этот метод завершается ошибкой.

Синтаксис

HRESULT BeginDraw(
  [in, optional] const RECT *updateRect,
  [in]           REFIID     iid,
  [out]          void       **updateObject,
  [out]          POINT      *updateOffset
);

Параметры

[in, optional] updateRect

Тип: const RECT*

Обновляемый прямоугольник. Если этот параметр имеет значение NULL, то обновляется все растровое изображение.

[in] iid

Тип: REFIID

Идентификатор извлекаемого интерфейса.

[out] updateObject

Тип: void**

Получает указатель интерфейса типа, указанного в параметре iid . Этот параметр не должен иметь значение NULL.

Примечание В Windows 8 этот параметр был surface.

[out] updateOffset

Тип: POINT*

Смещение в поверхности, где приложение должно рисовать обновленное содержимое. Это смещение будет ссылаться на левый верхний угол прямоугольника обновления.

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

Тип: HRESULT

Если функция завершается успешно, она возвращает S_OK. В противном случае возвращается код ошибки HRESULT .

Вызовите BeginDraw , чтобы инициировать добавочное обновление.
Используйте полученную поверхность в качестве целевого объекта отрисовки и нарисуйте обновленное содержимое по полученному смещению.
Вызовите метод IDCompositionSurface::EndDraw , чтобы завершить обновление.

Объект обновления, возвращаемый этим методом, является контекстом устройства Direct2D или поверхностью DXGI в зависимости от значения параметра iid и способа создания объекта поверхности DirectComposition. Если параметр iid имеет значение __uuidof(ID2D1DeviceContext), то возвращаемый объект является контекстом устройства Direct2D, для которого в качестве целевого объекта отрисовки уже выбрана поверхность DirectComposition. В противном случае это поверхность DXGI, которую приложение может использовать в качестве целевого объекта отрисовки. В любом случае возвращаемый объект связан с устройством Direct2D или DXGI, передаваемым приложением в функцию DCompositionCreateDevice2 или метод IDCompositionDevice2::CreateSurfaceFactory .

Параметр iid может быть __uuidof(ID2D1DeviceContext), только если объект поверхности DirectComposition был создан из устройства DirectComposition или фабрики поверхности, которая была создана вместе со связанным устройством Direct2D. В частности, приложение должно вызывать либо функцию DCompositionCreateDevice2, либо метод IDCompositionDevice2::CreateSurfaceFactory с устройством Direct2D в качестве параметра renderingDevice . Если поверхность DirectComposition была создана с помощью фабрики поверхности, которая не была связана с устройством Direct2D, или если она была создана непосредственно через интерфейс IDCompositionDevice2 и устройство не было напрямую связано с устройством Direct2D, то передача __uuidof(ID2D1DeviceContext) в качестве параметра iid приводит к тому, что этот метод возвращает E_INVALIDARG.

Если приложение успешно получает контекст устройства Direct2D в качестве объекта обновления, оно не должно вызывать методы ID2D1DeviceContext::BeginDraw или ID2D1DeviceContext::EndDraw в возвращенном контексте устройства Direct2D.

Полученное смещение не обязательно совпадает с левым верхним углом запрошенного прямоугольника обновления. Приложение должно преобразовать свои примитивы отрисовки для рисования в прямоугольнике той же ширины и высоты, что и входной прямоугольник, но с заданным смещением. Приложение не должно рисовать за пределами этого прямоугольника.

Если параметр updateRectangle имеет значение NULL, обновляется вся поверхность. В этом случае, так как полученное смещение по-прежнему может быть не равно (0,0), приложению по-прежнему необходимо соответствующим образом преобразовать свои примитивы отрисовки.

Если поверхность не является виртуальной поверхностью, то при первом вызове этого метода приложением для конкретной не виртуальной поверхности прямоугольник обновления должен охватывать всю поверхность, указав полную поверхность в запрошенном прямоугольнике обновления или указав ЗНАЧЕНИЕ NULL в качестве параметра updateRectangle . Для виртуальных поверхностей первым вызовом может быть любой вложенный прямоугольник поверхности.

Так как каждый вызов этого метода может получить другой объект в области updateObject , приложение не должно кэшировать полученный указатель поверхности. Приложение должно освободить полученный указатель сразу после завершения рисования.

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

Одновременно можно обновить только одну поверхность DirectComposition. Приложение должно приостановить рисование на одной поверхности перед началом или возобновлением рисования на другой поверхности. Если приложение вызывает BeginDraw дважды для той же поверхности или другой поверхности, принадлежащей тому же устройству DirectComposition, без промежуточного вызова IDCompositionSurface::EndDraw, второй вызов завершается ошибкой. Если приложение вызывает IDCompositionDevice2::Commit без вызова EndDraw, обновление остается незавершенным. Обновление вступает в силу только после того, как приложение вызывает Метод EndDraw , а затем вызывает метод IDCompositionDevice2::Commit .

Требования

Требование	Значение
Минимальная версия клиента	Windows 8 [только классические приложения]
Минимальная версия сервера	Windows Server 2012 [только классические приложения]
Целевая платформа	Windows
Header	dcomp.h
Библиотека	Dcomp.lib
DLL	Dcomp.dll

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

IDCompositionSurface

IDCompositionSurface::EndDraw