Funzione DrvBitBlt (winddi.h)

Articolo
08/27/2023

La funzione DrvBitBlt offre funzionalità generali di trasferimento a bit-block tra superfici gestite dal dispositivo, tra bitmap con formato standard gestito da GDI o tra una superficie gestita dal dispositivo e una bitmap con formato standard gestito da GDI.

Sintassi

BOOL DrvBitBlt(
  [in, out]      SURFOBJ  *psoTrg,
  [in, optional] SURFOBJ  *psoSrc,
  [in, optional] SURFOBJ  *psoMask,
  [in]           CLIPOBJ  *pco,
  [in, optional] XLATEOBJ *pxlo,
  [in]           RECTL    *prclTrg,
  [in, optional] POINTL   *pptlSrc,
  [in, optional] POINTL   *pptlMask,
  [in, optional] BRUSHOBJ *pbo,
  [in, optional] POINTL   *pptlBrush,
  [in]           ROP4     rop4
);

Parametri

[in, out] psoTrg

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

[in, optional] psoSrc

Puntatore a una struttura SURFOBJ che descrive l'origine per l'operazione di trasferimento a blocchi bit, se necessario dal parametro rop4 .

[in, optional] psoMask

Puntatore a una struttura SURFOBJ che descrive una superficie da usare come maschera per il parametro rop4 . La maschera è una bitmap con 1 bit per pixel. In genere, una maschera viene usata per limitare l'area da modificare nell'area di destinazione. La maschera viene selezionata impostando il parametro rop4 sul valore 0xAACC. La superficie di destinazione non è influenzata se la maschera è 0x0000.

La maschera sarà abbastanza grande per coprire il rettangolo di destinazione.

Se questo parametro è NULL e una maschera è richiesta dal parametro rop4 , viene usata la maschera implicita nel pennello.

[in] pco

Puntatore a una struttura CLIPOBJ che limita l'area da modificare. Sono disponibili servizi GDI (CLIPOBJXxx) che enumera l'area clip come set di rettangoli. Se possibile, GDI semplifica il ritaglio coinvolto; ad esempio, questa funzione non viene mai chiamata con un singolo rettangolo di ritaglio. GDI clip il rettangolo di destinazione prima di chiamare questa funzione, rendendo il ritaglio aggiuntivo non necessario.

[in, optional] pxlo

Puntatore a una struttura XLATEOBJ che specifica il modo in cui gli indici di colore devono essere convertiti tra le superfici di origine e di destinazione. Se pxlo è NULL, non è necessaria alcuna traduzione.

Se la superficie di origine è gestita dal tavolozza, i relativi colori sono rappresentati dagli indici in una tabella di ricerca dei valori RGB. La struttura XLATEOBJ può essere eseguita una query per un vettore di traduzione che consentirà al driver del dispositivo di convertire qualsiasi indice di origine in un indice di colore per la destinazione.

La situazione è più complessa quando, ad esempio, l'origine è RGB, ma la destinazione è gestita dal tavolozza. In questo caso, la corrispondenza più vicina a ogni valore RGB di origine deve essere trovata nel tavolozza di destinazione. Il driver può chiamare il servizio XLATEOBJ_iXlate per eseguire questa operazione.

Facoltativamente, il driver di dispositivo può corrispondere ai colori quando la tavolozza dei dispositivi è la tavolozza dei dispositivi predefinita.

[in] prclTrg

Puntatore a una struttura RECTL che definisce l'area da modificare. Questa struttura usa il sistema di coordinate della superficie di destinazione. I bordi inferiori e destro di questo rettangolo non fanno parte del trasferimento a blocchi di bit, il che significa che il rettangolo è inferiore destro esclusivo.

DrvBitBlt non viene mai chiamato con un rettangolo di destinazione vuoto. I due punti che definiscono il rettangolo sono sempre ben ordinati. Tuttavia, nei sistemi multimonitor il rettangolo può definire un'area più grande della superficie di destinazione. I driver devono intersecare questo rettangolo con la loro superficie.

[in, optional] pptlSrc

Puntatore a una struttura POINTL che definisce l'angolo superiore sinistro del rettangolo di origine, se esiste un'origine. Questo parametro viene ignorato se non è presente alcuna origine.

[in, optional] pptlMask

Puntatore a una struttura POINTL che definisce quale pixel nella maschera corrisponde all'angolo superiore sinistro del rettangolo di origine, se esiste un'origine. Questo parametro viene ignorato se il parametro psoMask è NULL.

[in, optional] pbo

Puntatore a una struttura BRUSHOBJ che definisce il modello per il trasferimento a blocchi di bit. Il servizio di BRUSHOBJ_pvGetRbrush GDI può essere usato per recuperare la realizzazione del pennello del dispositivo. Questo parametro viene ignorato se il parametro rop4 non richiede un modello.

[in, optional] pptlBrush

Puntatore a una struttura POINTL che definisce l'origine del pennello nell'area di destinazione. Il pixel superiore sinistro del pennello è allineato a questo punto e il pennello si ripete in base alle sue dimensioni. Questo parametro viene ignorato se il parametro rop4 non richiede un modello.

[in] rop4

Specifica un'operazione raster che definisce il modo in cui i pixel di maschera, modello, origine e destinazione vengono combinati per scrivere nell'area di destinazione.

Si tratta di un'operazione raster quaternary, che è un'estensione dell'operazione Rop3 ternaria. Un Rop4 ha 16 bit rilevanti, che sono simili ai 8 bit di una Rop3. Il modo più semplice per implementare un Rop4 consiste nel considerare separatamente i suoi 2 byte: il byte basso specifica un byte Rop3 che deve essere calcolato se la maschera è una e l'alto byte specifica un byte Rop3 che può essere calcolato e applicato se la maschera è 0.

Valore restituito

DrvBitBlt restituisce TRUE se l'operazione di trasferimento a blocchi bit ha esito positivo. In caso contrario, la funzione restituisce FALSE e viene registrato un codice di errore.

Commenti

Se il driver collega DrvBitBlt, GDI chiamerà questa funzione quando deve eseguire un'operazione BitBlt in cui una delle superfici è una superficie gestita dal dispositivo. Se il driver implementa bitmap opache gestite dal dispositivo, deve associare DrvBitBlt; in caso contrario, l'hook di DrvBitBlt è facoltativo. Se il driver non riesce a gestire la chiamata specificata, può richiamare il callback al motore DIB chiamando EngBitBlt.

I servizi CLIPOBJXxx di GDI consentono di ridurre il ritaglio a una serie di rettangoli di ritaglio. Un vettore di traduzione consente di eseguire la traduzione dell'indice dei colori per le tavolozze.

Nota Non dereferenziare i puntatori dei parametri a meno che non sia necessario l'ROP . Ad esempio, non è mai necessario dereferenziare pbo-iSolidColor> perché in questo modo per un ROP come BLACKNESS può causare una violazione di accesso. Questa regola si applica anche a qualsiasi funzione che include un parametro MIX.

Se il driver riceve una chiamata a questa funzione in cui il parametro rop4 è impostato su 0XCCAA, il driver deve attivare la chiamata a EngBitBlt, esponendo le superfici del dispositivo in base alle esigenze della chiamata.

Per altre informazioni sulle operazioni raster, vedere la documentazione di Microsoft Windows SDK.