Funzione DrvStretchBlt (winddi.h)

Articolo
08/27/2023

La funzione DrvStretchBlt offre funzionalità di trasferimento a blocchi di bit di estensione tra qualsiasi combinazione di superfici gestite dal dispositivo e gestite da GDI.

Sintassi

BOOL DrvStretchBlt(
  [in, out]      SURFOBJ         *psoDest,
  [in, out]      SURFOBJ         *psoSrc,
  [in, optional] SURFOBJ         *psoMask,
  [in]           CLIPOBJ         *pco,
  [in, optional] XLATEOBJ        *pxlo,
  [in, optional] COLORADJUSTMENT *pca,
  [in]           POINTL          *pptlHTOrg,
  [in]           RECTL           *prclDest,
  [in]           RECTL           *prclSrc,
  [in, optional] POINTL          *pptlMask,
  [in]           ULONG           iMode
);

Parametri

[in, out] psoDest

Puntatore alla struttura SURFOBJ che identifica la superficie su cui disegnare.

[in, out] psoSrc

Puntatore alla struttura SURFOBJ che definisce l'origine per l'operazione di trasferimento a blocchi di bit.

[in, optional] psoMask

Puntatore facoltativo a una struttura SURFOBJ che definisce una superficie che fornisce una maschera per l'origine. La maschera è definita da una mappa logica, ovvero una bitmap con 1 bit per pixel.

La maschera limita l'area dell'origine copiata. Se questo parametro viene specificato, ha un rop4 implicito di 0xCCAA, ovvero l'origine deve essere copiata ovunque la maschera sia una, ma la destinazione deve essere lasciata da sola ovunque la maschera sia zero.

Quando questo parametro è NULL, è presente un rop4 implicito di 0xCCCC, il che significa che l'origine deve essere copiata ovunque nel rettangolo di origine.

La maschera sarà sempre sufficientemente grande da contenere la fonte pertinente; la tiling non è necessaria.

[in] pco

Puntatore a una struttura CLIPOBJ che limita l'area da modificare nella destinazione. I servizi GDI vengono forniti per enumerare l'area di ritaglio come set di rettangoli.

Quando possibile, GDI semplifica il ritaglio. Tuttavia, a differenza di DrvBitBlt, DrvStretchBlt può essere chiamato con un singolo rettangolo di ritaglio. In questo modo si evitano errori di arrotondamento nell'ritaglio dell'output.

[in, optional] pxlo

Puntatore a una struttura XLATEOBJ che specifica la modalità di conversione degli indici di colore tra le superfici di origine e di destinazione. Se pxlo è NULL, non è necessaria alcuna traduzione.

È anche possibile eseguire una query sulla struttura XLATEOBJ per trovare il colore RGB per qualsiasi indice di origine. Un trasferimento a blocchi di bit di alta qualità deve interpolare i colori in alcuni casi.

[in, optional] pca

Puntatore a una struttura COLORADJUSTMENT che definisce i valori di regolazione del colore da applicare alla bitmap di origine prima di estendere i bit. Vedere la documentazione di Microsoft Windows SDK.

[in] pptlHTOrg

Puntatore a una struttura POINTL che specifica l'origine del pennello mezzotone. I driver di dispositivo che usano pennelli mezzotone devono allineare il pixel superiore sinistro del motivo del pennello con questo punto sulla superficie del dispositivo.

[in] prclDest

Puntatore a una struttura RECTL che definisce l'area da modificare nel sistema di coordinate della superficie di destinazione. Questo rettangolo è definito da due punti che non sono necessariamente ben ordinati, ovvero le coordinate del secondo punto non sono necessariamente maggiori di quelle del primo punto. Il rettangolo descritto non include i bordi inferiore e destro. Questa funzione non viene mai chiamata con un rettangolo di destinazione vuoto.

DrvStretchBlt deve interscambiare i due valori x e/o i due valori y quando il rettangolo di destinazione non è ordinato correttamente.

[in] prclSrc

Puntatore a una struttura RECTL che definisce l'area che verrà copiata nel sistema di coordinate della superficie di origine. Il rettangolo è definito da due punti e verrà eseguito il mapping al rettangolo definito da prclDest. I punti del rettangolo di origine sono ordinati correttamente. Questa funzione non viene mai assegnata a un rettangolo di origine vuoto.

Il mapping è definito da prclSrc e prclDest. I punti specificati in prclDest e prclSrc si trovano sulle coordinate integer, che corrispondono ai centri pixel. Un rettangolo definito da due punti di questo tipo è considerato un rettangolo geometrico con due vertici le cui coordinate sono i punti specificati, ma con 0,5 sottratte da ogni coordinata. Le strutture POINTL devono essere considerate una notazione abbreviata per specificare questi vertici delle coordinate frazionarie.

I bordi di qualsiasi rettangolo non intersecano mai un pixel, ma si spostano intorno a un set di pixel. I pixel all'interno del rettangolo sono quelli previsti per un rettangolo "esclusivo in basso a destra". DrvStretchBlt eseguirà il mapping del rettangolo di origine geometrica esattamente sul rettangolo di destinazione geometrico.

[in, optional] pptlMask

Puntatore a una struttura POINTL che specifica il pixel nella maschera specificata corrisponde al pixel superiore sinistro nel rettangolo di origine. Ignorare questo parametro se non viene specificata alcuna maschera.

[in] iMode

Specifica la modalità di combinazione dei pixel di origine per ottenere i pixel di output. La modalità HALFTONE è più lenta rispetto alle altre modalità, ma produce immagini di qualità superiore.

Valore	Significato
BLACKONWHITE	In un trasferimento a blocchi di bit ridotto, i pixel devono essere combinati con un'operazione AND booleana. In un trasferimento a blocchi di bit esteso, i pixel devono essere replicati.
COLORONCOLOR	In un trasferimento di blocchi di bit compattabile, è necessario ignorare un numero sufficiente di pixel in modo che i pixel non debbano essere combinati. In un trasferimento a blocchi di bit esteso, i pixel devono essere replicati.
SEMITONO	Il driver può usare gruppi di pixel nella superficie di output per approssimare al meglio il colore o il livello grigio dell'input.
WHITEONBLACK	In un trasferimento a blocchi di bit ridotto, i pixel devono essere combinati con un'operazione OR booleana. In un trasferimento a blocchi di bit esteso, i pixel devono essere replicati.

Valore restituito

Il valore restituito è TRUE se la funzione ha esito positivo. In caso contrario, è FALSE e viene registrato un codice di errore.

Commenti

DrvStretchBlt consente al driver di dispositivo di scrivere nelle bitmap GDI, soprattutto quando il driver può eseguire il halftoning. Questa funzione consente di applicare lo stesso algoritmo di halftoning alle bitmap GDI e alle superfici del dispositivo.

Questa funzione può essere fornita per gestire solo determinate forme di estensione, ad esempio per multipli integer. Se il driver ha collegato la chiamata e viene chiesto di eseguire un'operazione che non supporta, il driver deve inoltrare i dati a EngStretchBlt per gestire GDI.

Se il driver vuole che GDI gestisca il halftoning e voglia garantire il valore iMode appropriato, il driver può associare DrvStretchBlt, impostare iMode su HALFTONE e richiamare GDI con EngStretchBlt con il valore iMode impostato.

DrvStretchBlt è facoltativo per i driver di visualizzazione.