Método IDCompositionSurface::BeginDraw (dcomp.h)

Inicia o desenho neste objeto de superfície do Microsoft DirectComposition. O retângulo de atualização deve estar dentro dos limites da superfície; caso contrário, esse método falhará.

Sintaxe

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

Parâmetros

[in, optional] updateRect

Tipo: const RECT*

O retângulo a ser atualizado. Se esse parâmetro for NULL, todo o bitmap será atualizado.

[in] iid

Tipo: REFIID

O identificador da interface a ser recuperada.

[out] updateObject

Tipo: void**

Recebe um ponteiro de interface do tipo especificado no parâmetro iid . Esse parâmetro não deve ser NULL.

Nota Em Windows 8, esse parâmetro era surface.

 

[out] updateOffset

Tipo: POINT*

O deslocamento para a superfície em que o aplicativo deve desenhar o conteúdo atualizado. Esse deslocamento fará referência ao canto superior esquerdo do retângulo de atualização.

Retornar valor

Tipo: HRESULT

Se a função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Esse método permite que um aplicativo atualize incrementalmente o conteúdo de um objeto de superfície DirectComposition. O aplicativo deve usar a seguinte sequência:

1. Chame BeginDraw para iniciar a atualização incremental.
2. Use a superfície recuperada como um destino de renderização e desenhe o conteúdo atualizado no deslocamento recuperado.
3. Chame o método IDCompositionSurface::EndDraw para concluir a atualização.

O objeto update retornado por esse método é um contexto de dispositivo Direct2D ou uma superfície DXGI, dependendo do valor do parâmetro iid e de como o objeto de superfície DirectComposition foi criado. Se o parâmetro iid for __uuidof(ID2D1DeviceContext), o objeto retornado será um Direct2D contexto do dispositivo que já tem a superfície DirectComposition selecionada como um destino de renderização. Caso contrário, é uma superfície DXGI que o aplicativo pode usar como um destino de renderização. Em ambos os casos, o objeto retornado está associado ao dispositivo Direct2D ou DXGI passado pelo aplicativo para a função DCompositionCreateDevice2 ou o método IDCompositionDevice2::CreateSurfaceFactory.

O parâmetro iid só poderá ser __uuidof(ID2D1DeviceContext) se o objeto de superfície DirectComposition tiver sido criado a partir de um dispositivo DirectComposition ou de uma fábrica de superfície que foi, por si só, criada com um dispositivo Direct2D associado. Em particular, o aplicativo deve ter chamado a função DCompositionCreateDevice2 ou o método IDCompositionDevice2::CreateSurfaceFactory com um dispositivo Direct2D como o parâmetro renderingDevice. Se a superfície DirectComposition foi criada por meio de uma fábrica de superfície que não estava associada a um dispositivo Direct2D ou se foi criada diretamente por meio da interface IDCompositionDevice2 e o dispositivo não estava diretamente associado a um dispositivo Direct2D, passar __uuidof(ID2D1DeviceContext) como o parâmetro iid faz com que esse método retorne E_INVALIDARG.

Se o aplicativo recuperar com êxito um contexto de dispositivo Direct2D como objeto de atualização, o aplicativo não deverá chamar os métodos ID2D1DeviceContext::BeginDraw ou ID2D1DeviceContext::EndDraw no contexto de dispositivo Direct2D retornado.

O deslocamento recuperado não é necessariamente o mesmo que o canto superior esquerdo do retângulo de atualização solicitado. O aplicativo deve transformar seus primitivos de renderização para desenhar dentro de um retângulo da mesma largura e altura que o retângulo de entrada, mas no deslocamento fornecido. O aplicativo não deve desenhar fora desse retângulo.

Se o parâmetro updateRectangle for NULL, toda a superfície será atualizada. Nesse caso, como o deslocamento recuperado ainda pode não ser (0,0), o aplicativo ainda precisa transformar seus primitivos de renderização adequadamente.

Se a superfície não for uma superfície virtual, a primeira vez que o aplicativo chamar esse método para uma superfície não virtual específica, o retângulo de atualização deverá cobrir toda a superfície, especificando a superfície completa no retângulo de atualização solicitado ou especificando NULL como o parâmetro updateRectangle . Para superfícies virtuais, a primeira chamada pode ser qualquer subtângulo da superfície.

Como cada chamada a esse método pode recuperar um objeto diferente na superfície updateObject , o aplicativo não deve armazenar em cache o ponteiro de superfície recuperado. O aplicativo deve liberar o ponteiro recuperado assim que concluir o desenho.

O retângulo de superfície recuperado não contém o conteúdo anterior do bitmap. O aplicativo deve atualizar cada pixel no retângulo de atualização, primeiro limpando o destino de renderização ou emitindo primitivos de renderização suficientes para cobrir totalmente o retângulo de atualização. Como o conteúdo inicial da superfície de atualização é indefinido, a falha ao atualizar cada pixel leva a um comportamento indefinido.

Somente uma superfície DirectComposition pode ser atualizada por vez. Um aplicativo deve suspender o desenho em uma superfície antes de começar ou retomar para desenhar em outra superfície. Se o aplicativo chamar BeginDraw duas vezes, seja para a mesma superfície ou para outra superfície pertencente ao mesmo dispositivo DirectComposition, sem uma chamada intervindo para IDCompositionSurface::EndDraw, a segunda chamada falhará. Se o aplicativo chamar IDCompositionDevice2::Commit sem chamar EndDraw, a atualização permanecerá pendente. A atualização entra em vigor somente depois que o aplicativo chama EndDraw e, em seguida, chama o método IDCompositionDevice2::Commit .

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2012 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	dcomp.h
Biblioteca	Dcomp.lib
DLL	Dcomp.dll

Confira também

IDCompositionSurface

IDCompositionSurface::EndDraw