Метод IDCompositionSurface::BeginDraw (dcomp.h)
Инициирует рисование этого объекта поверхности 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.
[out] updateOffset
Тип: POINT*
Смещение в поверхности, где приложение должно рисовать обновленное содержимое. Это смещение будет ссылаться на левый верхний угол прямоугольника обновления.
Возвращаемое значение
Тип: HRESULT
Если функция завершается успешно, она возвращает S_OK. В противном случае возвращается код ошибки HRESULT .
Комментарии
Этот метод позволяет приложению постепенно обновлять содержимое объекта поверхности DirectComposition. Приложение должно использовать следующую последовательность:
- Вызовите BeginDraw , чтобы инициировать добавочное обновление.
- Используйте полученную поверхность в качестве целевого объекта отрисовки и нарисуйте обновленное содержимое по полученному смещению.
- Вызовите метод IDCompositionSurface::EndDraw , чтобы завершить обновление.
Параметр 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 |