Função DrvEnableSurface (winddi.h)

Artigo
08/27/2023

A função DrvEnableSurface configura uma superfície a ser desenhada e a associa a um determinado dispositivo físico.

Sintaxe

HSURF DrvEnableSurface(
  DHPDEV dhpdev
);

Parâmetros

dhpdev

Manipule para o PDEV do dispositivo físico. Esse é o valor retornado de DrvEnablePDEV. O PDEV descreve o dispositivo físico para o qual uma superfície deve ser criada.

Retornar valor

O valor retornado é um identificador que identifica a superfície recém-criada. Caso contrário, será zero e um código de erro será registrado.

Comentários

Há dois métodos para preparar uma superfície para uso.

Nesse método, que é recomendado, o driver cria a superfície por uma chamada para EngCreateDeviceSurface. Depois que a GDI cria a superfície e retorna um identificador para o driver, o driver chama EngModifySurface, que define os sinalizadores de gancho apropriados e, opcionalmente, informa a GDI sobre a localização da superfície.
O segundo método é o usado por drivers Windows NT 4.0. Nesse método, o driver chama EngCreateBitmap. Após essa chamada, o driver chama EngAssociateSurface para associar a superfície ao dispositivo de vídeo físico. Essa função GDI permite que o driver especifique quais rotinas de saída gráfica têm suporte para bitmaps de formato padrão. Uma chamada para essa função só pode ser feita quando nenhuma superfície existe para o dispositivo físico fornecido. Se um driver do Windows 2000 ou posterior for portado novamente para ser executado no Windows NT 4.0, esse método deverá ser usado. Se esse driver também for executado no Windows 2000 ou posterior, um caminho de código separado no driver deverá usar o primeiro método.
Para dispositivos de impressora, a situação usual é que a GDI colete os elementos gráficos diretamente em um bitmap GDI. O driver deve chamar EngCreateBitmap, que permite que o GDI aloque memória para o bitmap.

Qualquer identificador de bitmap GDI existente é um identificador de superfície válido.

Para DLLs de gráficos de impressora que usam superfícies gerenciadas por GDI, a função DrvEnableSurface deve chamar EngCreateBitmap, especificando um tamanho de superfície grande o suficiente para conter uma página física inteira. Se isso falhar, as chamadas repetidas para EngCreateBitmap deverão ser tentadas, com tamanhos de superfície decrescentes, até que uma chamada seja bem-sucedida. O tamanho válido deve ser especificado como entrada para EngMarkBandingSurface, que informa à GDI que a faixa de superfície será necessária.

Depois que DrvEnableSurface retornar um identificador para uma superfície primária, não chame EngModifySurface ou EngAssociateSurface nesse identificador. Isso pode causar um bug marcar em determinadas circunstâncias. Para obter mais informações, consulte o artigo da Base de Dados de Conhecimento Microsoft 330248.

DrvEnableSurface é necessário para drivers gráficos.