Funzione StretchDIBits (wingdi.h)

Articolo
03/04/2024

La funzione StretchDIBits copia i dati di colore per un rettangolo di pixel in un'immagine DIB, JPEG o PNG nel rettangolo di destinazione specificato. Se il rettangolo di destinazione è maggiore del rettangolo di origine, questa funzione estende le righe e le colonne dei dati di colore per adattarsi al rettangolo di destinazione. Se il rettangolo di destinazione è inferiore al rettangolo di origine, questa funzione comprime le righe e le colonne usando l'operazione raster specificata.

Sintassi

int StretchDIBits(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] int              DestWidth,
  [in] int              DestHeight,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] int              SrcWidth,
  [in] int              SrcHeight,
  [in] const VOID       *lpBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             iUsage,
  [in] DWORD            rop
);

Parametri

[in] hdc

Handle per il contesto del dispositivo di destinazione.

[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] DestWidth

Larghezza, in unità logiche, del rettangolo di destinazione.

[in] DestHeight

Altezza, in unità logiche, del rettangolo di destinazione.

[in] xSrc

Coordinata x, in pixel, del rettangolo di origine nell'immagine.

[in] ySrc

Coordinata y, in pixel, del rettangolo di origine nell'immagine.

[in] SrcWidth

Larghezza, in pixel, del rettangolo di origine nell'immagine.

[in] SrcHeight

Altezza, in pixel, del rettangolo di origine nell'immagine.

[in] lpBits

Puntatore ai bit dell'immagine, archiviati come matrice di byte. Per altre informazioni, vedere la sezione Osservazioni.

[in] lpbmi

Puntatore a una struttura BITMAPINFO contenente informazioni sul DIB.

[in] iUsage

Specifica se il membro bmiColors della struttura BITMAPINFO è stato fornito e, in tal caso, se bmiColors contiene valori espliciti rosso, verde, blu (RGB) o indici. Il parametro iUsage deve essere uno dei valori seguenti.

Valore	Significato
DIB_PAL_COLORS	La matrice contiene indici a 16 bit nella tavolozza logica del contesto del dispositivo di origine.
DIB_RGB_COLORS	La tabella dei colori contiene valori RGB letterali.

Per altre informazioni, vedere la sezione Osservazioni.

[in] rop

Codice dell'operazione raster che specifica il modo in cui i pixel di origine, il pennello corrente del contesto di dispositivo di destinazione e i pixel di destinazione devono essere combinati per formare la nuova immagine. Per un elenco di alcuni codici di operazione raster comuni, vedere BitBlt.

Valore restituito

Se la funzione ha esito positivo, il valore restituito corrisponde al numero di righe di analisi copiate. Si noti che questo valore può essere negativo per il contenuto con mirroring.

Se la funzione ha esito negativo o non vengono copiate righe di analisi, il valore restituito è 0.

Se il driver non supporta l'immagine del file JPEG o PNG passata a StretchDIBits, la funzione avrà esito negativo e restituirà GDI_ERROR. Se si verifica un errore, l'applicazione deve eseguire il fallback sul proprio supporto JPEG o PNG per decomprimere l'immagine in una bitmap e quindi passare la bitmap a StretchDIBits.

Commenti

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

StretchDIBits crea un'immagine mirror di una bitmap se i segni dei parametri nSrcWidth e nDestWidth o se i parametri nSrcHeight e nDestHeight differiscono. Se nSrcWidth e nDestWidth hanno segni diversi, la funzione crea un'immagine speculare della bitmap lungo l'asse x. Se nSrcHeight e nDestHeight hanno segni diversi, la funzione crea un'immagine mirror della bitmap lungo l'asse y.

StretchDIBits crea un'immagine dall'alto verso il basso se il segno del membro biHeight della struttura BITMAPINFOHEADER per DIB è negativo. Per un esempio di codice, vedere Ridimensionamento di un'immagine JPEG o PNG.

Questa funzione consente di passare un'immagine JPEG o PNG come immagine di origine. La modalità di utilizzo di ogni parametro rimane invariata, ad eccezione di:

Se il membro biCompression di BITMAPINFOHEADER è BI_JPEG o BI_PNG, lpBits punta rispettivamente a un buffer contenente un'immagine JPEG o PNG. Il membro biSizeImage della struttura BITMAPINFOHEADER specifica le dimensioni del buffer. Il parametro iUsage deve essere impostato su DIB_RGB_COLORS. Il parametro dwRop deve essere impostato su SRCCOPY.
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 StretchDIBits.

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 lpBitsInfo ha un BITMAPV4HEADER che specifica i membri gamma ed endpoint oppure 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 dei colori descritto da tali membri, anziché nello spazio dei colori di origine del contesto del dispositivo.

Esempio

Per un esempio, vedere Ridimensionamento di un'immagine 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