Função EngAssociateSurface (winddi.h)

Artigo
08/27/2023

A função EngAssociateSurface marca uma determinada superfície como pertencente a um dispositivo especificado.

Sintaxe

ENGAPI BOOL EngAssociateSurface(
  HSURF hsurf,
  HDEV  hdev,
  FLONG flHooks
);

Parâmetros

hsurf

Identificador para a superfície ou bitmap a ser associado ao hdev. Esse identificador foi retornado por EngCreateBitmap ou EngCreateDeviceBitmap.

hdev

Identificador para o dispositivo ao qual a superfície deve ser associada. Esse é o identificador criado por GDI que foi passado para a função DrvCompletePDEV do driver.

flHooks

Especifica as funções que o driver pode conectar da GDI. O driver deve implementar a função correspondente para cada bit que ele define em flHooks. Esse membro é um OR bit a bit de qualquer um dos seguintes valores:

Sinalizador	Função a ser fisgada
HOOK_ALPHABLEND	DrvAlphaBlend
HOOK_BITBLT	DrvBitBlt
HOOK_COPYBITS	DrvCopyBits
HOOK_FILLPATH	DrvFillPath
HOOK_GRADIENTFILL	DrvGradientFill
HOOK_LINETO	DrvLineTo
HOOK_MOVEPANNING	Obsoleto
HOOK_PAINT	Obsoleto
HOOK_PLGBLT	DrvPlgBlt
HOOK_STRETCHBLT	DrvStretchBlt
HOOK_STRETCHBLTROP	DrvStretchBltROP
HOOK_STROKEANDFILLPATH	DrvStrokeAndFillPath
HOOK_STROKEPATH	DrvStrokePath
HOOK_SYNCHRONIZE	DrvSynchronize ou DrvSynchronizeSurface (ou ambos)
HOOK_SYNCHRONIZEACCESS	Obsoleto
HOOK_TEXTOUT	DrvTextOut
HOOK_TRANSPARENTBLT	DrvTransparentBlt

Valor retornado

O valor retornado será TRUE se a função for bem-sucedida. Caso contrário, o driver deve enviar as informações para a função GDI que está implementando e retornar o valor retornado da GDI.

Comentários

O EngAssociateSurface pode ser usado por drivers de impressora para implementar "regras" ou fontes de dispositivo ou por drivers de exibição para usar hardware blt especial.

Se a superfície identificada pelo hsurf for um bitmap de formato padrão, o driver poderá especificar quais funções de saída para a superfície ele manipulará definindo bits em flHooks. Definir bits em flHooks faz com que funções de saída específicas sejam enviadas para o driver. Isso é conhecido como gancho. Se o driver não conectar uma chamada, a GDI gerenciará automaticamente a operação quando um bitmap de formato padrão estiver sendo desenhado.

Quando a superfície está associada, ela pressupõe as etapas padrão de paleta e estilo do PDEV. Uma superfície deve ser associada antes de ser retornada por DrvEnableSurface.

Por padrão, quando um driver dá suporte a bitmaps de dispositivo implementando DrvCreateDeviceBitmap/DrvDeleteDeviceBitmap, o GDI não sincroniza automaticamente as chamadas de desenho com o bitmap do dispositivo e com a superfície primária. Por exemplo, a GDI pode chamar a função DrvBitBlt do driver para desenhar em um bitmap de dispositivo, enquanto outro thread está desenhando para a superfície primária executando a implementação do driver de DrvTextOut. O driver pode até mesmo ser chamado para desenhar em vários bitmaps de dispositivo ao mesmo tempo.

Depois que DrvEnableSurface retornar um identificador para uma superfície primária, não chame 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.

Requisitos


Cliente mínimo com suporte	Disponível no Windows 2000 e versões posteriores dos sistemas operacionais Windows.
Plataforma de Destino	Universal
Cabeçalho	winddi.h (inclua Winddi.h)
Biblioteca	Win32k.lib
DLL	Win32k.sys