Funzione SetDIBitsToDevice (wingdi.h)

Articolo
03/04/2024

La funzione SetDIBitsToDevice imposta i pixel nel rettangolo specificato nel dispositivo associato al contesto del dispositivo di destinazione usando i dati del colore da un'immagine DIB, JPEG o PNG.

Sintassi

int SetDIBitsToDevice(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] DWORD            w,
  [in] DWORD            h,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] UINT             StartScan,
  [in] UINT             cLines,
  [in] const VOID       *lpvBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             ColorUse
);

Parametri

[in] hdc

Handle nel contesto del dispositivo.

[in] xDest

Coordinata x, in unità logiche, dell'angolo superiore sinistro del rettangolo di destinazione.

[in] yDest

Coordinata y, in unità logiche, dell'angolo superiore sinistro del rettangolo di destinazione.

[in] w

Larghezza, in unità logiche, dell'immagine.

[in] h

Altezza, in unità logiche, dell'immagine.

[in] xSrc

Coordinata x, in unità logiche, dell'angolo inferiore sinistro dell'immagine.

[in] ySrc

Coordinata y, in unità logiche, dell'angolo inferiore sinistro dell'immagine.

[in] StartScan

Riga di analisi iniziale nell'immagine.

[in] cLines

Numero di righe di analisi DIB contenute nella matrice a cui punta il parametro lpvBits .

[in] lpvBits

Puntatore ai dati del colore archiviati come matrice di byte. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in] lpbmi

Puntatore a una struttura BITMAPINFO che contiene informazioni sul DIB.

[in] ColorUse

Indica se il membro bmiColors della struttura BITMAPINFO contiene valori rossi, verdi, blu o indici in una tavolozza. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

Il parametro fuColorUse deve essere uno dei valori seguenti.

Valore	Significato
DIB_PAL_COLORS	La tabella colori è costituita da una matrice di indici a 16 bit nella tavolozza logica attualmente selezionata.
DIB_RGB_COLORS	La tabella dei colori contiene valori RGB letterali.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è il numero di righe di analisi impostate.

Se le righe di analisi zero sono impostate , ad esempio quando dwHeight è 0) o la funzione ha esito negativo, la funzione restituisce zero.

Se il driver non può supportare l'immagine di file JPEG o PNG passata a SetDIBitsToDevice, la funzione avrà esito negativo e restituirà GDI_ERROR. Se si verifica un errore, l'applicazione deve tornare al proprio supporto JPEG o PNG per decomprimere l'immagine in una bitmap e quindi passare la bitmap a SetDIBitsToDevice.

Commenti

La velocità di disegno bitmap ottimale viene ottenuta quando i bit bitmap sono indici nella tavolozza di sistema.

Le applicazioni possono recuperare i colori e gli indici del riquadro di sistema chiamando la funzione GetSystemPaletteEntries . Dopo aver recuperato i colori e gli indici, l'applicazione può creare il DIB. Per altre informazioni sulla tavolozza di sistema, vedere Colori.

Le righe di analisi devono essere allineate su una DWORD , ad eccezione delle bitmap compresse da RLE.

L'origine di un DIB inferiore è l'angolo inferiore sinistro della bitmap; l'origine di un DIB in alto verso il basso è l'angolo superiore sinistro.

Per ridurre la quantità di memoria necessaria per impostare bit da un DIB di grandi dimensioni in un'area del dispositivo, un'applicazione può bandire l'output chiamando ripetutamente SetDIBitsToDevice, posizionando una parte diversa della bitmap nella matrice lpvBits ogni volta. I valori dei parametri uStartScan e cScanLines identificano la parte della bitmap contenuta nella matrice lpvBits .

La funzione SetDIBitsToDevice restituisce un errore se viene chiamato da un processo in esecuzione in background mentre viene eseguita una sessione MS-DOS a schermo intero in primo piano.

Se il membro biCompression di BITMAPINFOHEADER è BI_JPEG o BI_PNG, lpvBits punta a un buffer contenente un'immagine JPEG o PNG. Il membro biSizeImage di specifica le dimensioni del buffer. Il parametro fuColorUse deve essere impostato su DIB_RGB_COLORS.
Per garantire il corretto spooling del metafile durante la stampa, le applicazioni devono chiamare l'escape CHECKJPEGFORMAT o CHECKPNGFORMAT per verificare che la stampante riconosca rispettivamente l'immagine JPEG o PNG, prima di chiamare SetDIBitsToDevice.

ICM: La gestione dei colori viene eseguita se la gestione dei colori è stata abilitata con una chiamata a SetICMMode con il parametro iEnableICM impostato su ICM_ON. Se la bitmap specificata da lpbmi ha un BITMAPV4HEADER che specifica i membri gamma ed endpoint o un BITMAPV5HEADER che specifica i membri gamma ed endpoint o i membri profileData e profileSize, la chiamata considera i pixel della bitmap come espressi nello spazio colori descritto dai membri, anziché nello spazio colore del contesto del dispositivo.

Esempio

Per un esempio, vedere Test di una stampante per il supporto JPEG o PNG.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wingdi.h (include Windows.h)
Libreria	Gdi32.lib
DLL	Gdi32.dll