Método IDCompositionSurface::BeginDraw (dcomp.h)
Inicia el dibujo en este objeto de superficie De Microsoft DirectComposition. El rectángulo de actualización debe estar dentro de los límites de la superficie; de lo contrario, se produce un error en este método.
Sintaxis
HRESULT BeginDraw(
[in, optional] const RECT *updateRect,
[in] REFIID iid,
[out] void **updateObject,
[out] POINT *updateOffset
);
Parámetros
[in, optional] updateRect
Tipo: const RECT*
Rectángulo que se va a actualizar. Si este parámetro es NULL, se actualiza todo el mapa de bits.
[in] iid
Tipo: REFIID
Identificador de la interfaz que se va a recuperar.
[out] updateObject
Tipo: void**
Recibe un puntero de interfaz del tipo especificado en el parámetro iid . Este parámetro no debe ser null.
[out] updateOffset
Tipo: POINT*
Desplazamiento en la superficie donde la aplicación debe dibujar contenido actualizado. Este desplazamiento hará referencia a la esquina superior izquierda del rectángulo de actualización.
Valor devuelto
Tipo: HRESULT
Si la función se ejecuta correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.
Comentarios
Este método permite a una aplicación actualizar incrementalmente el contenido de un objeto de superficie DirectComposition. La aplicación debe usar la siguiente secuencia:
- Llame a BeginDraw para iniciar la actualización incremental.
- Use la superficie recuperada como destino de representación y dibuje el contenido actualizado en el desplazamiento recuperado.
- Llame al método IDCompositionSurface::EndDraw para finalizar la actualización.
El parámetro iid solo puede ser __uuidof(ID2D1DeviceContext) si el objeto de superficie DirectComposition se creó a partir de un dispositivo DirectComposition o un generador de superficies que se creó, por sí mismo, con un dispositivo Direct2D asociado. En concreto, la aplicación debe haber llamado a la función DCompositionCreateDevice2 o al método IDCompositionDevice2::CreateSurfaceFactory con un dispositivo Direct2D como parámetro renderingDevice . Si la superficie DirectComposition se creó a través de una fábrica de superficies que no estaba asociada a un dispositivo Direct2D, o si se creó directamente a través de la interfaz IDCompositionDevice2 y el dispositivo no estaba directamente asociado con un dispositivo Direct2D, después pasar __uuidof(ID2D1DeviceContext) como el parámetro iid hace que este método devuelva E_INVALIDARG.
Si la aplicación recupera correctamente un contexto de dispositivo Direct2D como objeto de actualización, la aplicación no debe llamar a los métodos ID2D1DeviceContext::BeginDraw o ID2D1DeviceContext::EndDraw en el contexto del dispositivo Direct2D devuelto.
El desplazamiento recuperado no es necesariamente el mismo que la esquina superior izquierda del rectángulo de actualización solicitado. La aplicación debe transformar sus primitivos de representación para dibujar dentro de un rectángulo del mismo ancho y alto que el rectángulo de entrada, pero en el desplazamiento especificado. La aplicación no debe dibujar fuera de este rectángulo.
Si el parámetro updateRectangle es NULL, se actualiza toda la superficie. En ese caso, dado que el desplazamiento recuperado todavía no puede ser (0,0), la aplicación todavía necesita transformar sus primitivos de representación en consecuencia.
Si la superficie no es una superficie virtual, la primera vez que la aplicación llama a este método para una superficie no virtual determinada, el rectángulo de actualización debe cubrir toda la superficie, ya sea especificando la superficie completa en el rectángulo de actualización solicitado o especificando NULL como el parámetro updateRectangle . En el caso de las superficies virtuales, la primera llamada puede ser cualquier sub rectángulo de la superficie.
Dado que cada llamada a este método podría recuperar un objeto diferente en la superficie updateObject , la aplicación no debe almacenar en caché el puntero de superficie recuperado. La aplicación debe liberar el puntero recuperado tan pronto como finalice el dibujo.
El rectángulo de superficie recuperado no contiene el contenido anterior del mapa de bits. La aplicación debe actualizar todos los píxeles del rectángulo de actualización, ya sea borrando primero el destino de representación o emitiendo suficientes primitivos de representación para cubrir completamente el rectángulo de actualización. Dado que el contenido inicial de la superficie de actualización no está definido, si no se actualiza cada píxel, se produce un comportamiento indefinido.
Solo se puede actualizar una superficie directComposition a la vez. Una aplicación debe suspender el dibujo en una superficie antes de comenzar o reanudarse para dibujar en otra superficie. Si la aplicación llama a BeginDraw dos veces, ya sea para la misma superficie o para otra superficie que pertenezca al mismo dispositivo DirectComposition, sin una llamada intermedia a IDCompositionSurface::EndDraw, se produce un error en la segunda llamada. Si la aplicación llama a IDCompositionDevice2::Commit sin llamar a EndDraw, la actualización permanece pendiente. La actualización solo surte efecto después de que la aplicación llame a EndDraw y, a continuación, llame al método IDCompositionDevice2::Commit .
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 8 [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2012 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | dcomp.h |
| Library | Dcomp.lib |
| Archivo DLL | Dcomp.dll |