Funzione DrvEnableSurface (winddi.h)

Articolo
08/27/2023

La funzione DrvEnableSurface imposta una superficie da disegnare e la associa a un determinato dispositivo fisico.

Sintassi

HSURF DrvEnableSurface(
  DHPDEV dhpdev
);

Parametri

dhpdev

Gestire il PDEV del dispositivo fisico. Si tratta del valore restituito di DrvEnablePDEV. Il PDEV descrive il dispositivo fisico per il quale deve essere creata una superficie.

Valore restituito

Il valore restituito è un handle che identifica la superficie appena creata. In caso contrario, è zero e viene registrato un codice di errore.

Commenti

Esistono due metodi per preparare una superficie da usare.

In questo metodo, consigliato, il driver crea la superficie tramite una chiamata a EngCreateDeviceSurface. Dopo che GDI crea la superficie e restituisce un handle al driver, il driver chiama EngModifySurface, che imposta i flag di hook appropriati e, facoltativamente, informa GDI della posizione della superficie.
Il secondo metodo è quello usato dai driver Windows NT 4.0. In questo metodo il driver chiama EngCreateBitmap. Dopo questa chiamata, il driver chiama EngAssociateSurface per associare la superficie al dispositivo di visualizzazione fisico. Questa funzione GDI consente al driver di specificare quali routine di output grafica sono supportate per le bitmap di formato standard. Una chiamata a questa funzione può essere effettuata solo quando non esiste alcuna superficie per il dispositivo fisico specificato. Se un driver Windows 2000 o versione successiva viene restituito per l'esecuzione in Windows NT 4.0, questo metodo deve essere usato. Se tale driver verrà eseguito anche in Windows 2000 o versioni successive, un percorso di codice separato nel driver deve usare il primo metodo.
Per i dispositivi stampanti, la situazione consueta consiste nel raccogliere la grafica direttamente in una bitmap GDI. Il driver deve chiamare EngCreateBitmap, che consente a GDI di allocare memoria per la bitmap.

Qualsiasi handle bitmap GDI esistente è un handle di superficie valido.

Per le DLL della grafica della stampante che usano superfici gestite da GDI, la funzione DrvEnableSurface deve chiamare EngCreateBitmap, specificando una dimensione di superficie sufficiente per contenere un'intera pagina fisica. In caso contrario, le chiamate ripetute a EngCreateBitmap devono essere tentate, con dimensioni di superficie decrescente, fino a quando una chiamata non riesce. Le dimensioni valide devono essere specificate come input per EngMarkBandingSurface, che informa GDI che il banding della superficie sarà necessario.

Dopo che DrvEnableSurface restituisce un handle in una superficie primaria, non chiamare EngModifySurface o EngAssociateSurface su tale handle. In questo modo può causare un controllo di bug in determinate circostanze. Per altre informazioni, vedere l'articolo di Microsoft Knowledge Base 330248.

DrvEnableSurface è necessario per i driver grafici.