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.
[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:
- Chame BeginDraw para iniciar a atualização incremental.
- Use a superfície recuperada como um destino de renderização e desenhe o conteúdo atualizado no deslocamento recuperado.
- Chame o método IDCompositionSurface::EndDraw para concluir a atualização.
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 |