DrvStretchBlt 関数 (winddi.h)

[アーティクル]
03/13/2024

DrvStretchBlt 関数は、デバイスで管理されるサーフェスと GDI で管理されるサーフェスの任意の組み合わせの間で、ビットブロック転送機能を拡張します。

構文

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
);

パラメーター

[in, out] psoDest

描画するサーフェスを識別する SURFOBJ 構造体へのポインター。

[in, out] psoSrc

ビットブロック転送操作のソースを定義する SURFOBJ 構造体へのポインター。

[in, optional] psoMask

ソースのマスクを提供するサーフェスを定義する SURFOBJ 構造体へのオプションのポインター。マスクは、ピクセルあたり 1 ビットのビットマップであるロジックマップによって定義されます。

マスクは、コピーされるソースの領域を制限します。このパラメーターを指定すると、暗黙的な rop4 が0xCCAAされます。つまり、マスクが 1 の場合はソースをコピーする必要がありますが、マスクが 0 の場合は、コピー先を単独のままにする必要があります。

このパラメーターが NULL の場合、0xCCCCの暗黙的な rop4 が存在します。これは、ソースをソース四角形内のすべての場所にコピーする必要があることを意味します。

マスクは常に、関連するソースを含むのに十分な大きさになります。タイリングは不要です。

[in] pco

変換先で変更する領域を制限する CLIPOBJ 構造体へのポインター。 GDI サービスは、クリップ領域を四角形のセットとして列挙するために提供されます。

可能な限り、GDI は関連するクリッピングを簡略化します。ただし、 DrvBitBlt とは異なり、 DrvStretchBlt は単一のクリッピング四角形で呼び出すことができます。これにより、出力をクリッピングするときの丸めエラーが回避されます。

[in, optional] pxlo

ソースサーフェスとターゲットサーフェスの間でカラーインデックスを変換する方法を指定する XLATEOBJ 構造体へのポインター。 pxlo が NULL の場合、変換は必要ありません。

XLATEOBJ 構造体を照会して、ソースインデックスの RGB 色を検索することもできます。高品質のストレッチビットブロック転送では、場合によっては色を補間する必要があります。

[in, optional] pca

ビットをストレッチする前にソースビットマップに適用する色調整値を定義する COLORADJUSTMENT 構造体へのポインター。 (Microsoft Windows SDKのドキュメントを参照してください。

[in] pptlHTOrg

ハーフトーンブラシの原点を指定する POINTL 構造体へのポインター。ハーフトーンブラシを使用するデバイスドライバーは、ブラシのパターンの左上のピクセルをデバイスサーフェイスのこのポイントに合わせる必要があります。

[in] prclDest

変換先サーフェスの座標系で変更する領域を定義する RECTL 構造体へのポインター。この四角形は、必ずしも適切に順序付けされていない 2 つのポイントによって定義されます。つまり、2 番目のポイントの座標は、必ずしも最初のポイントの座標よりも大きいとは限りません。説明する四角形には、下端と右端は含まれません。この関数は、空の変換先の四角形で呼び出されることはありません。

DrvStretchBlt は、変換先の四角形の順序が適切でない場合は、2 つの x 値と 2 つの y 値を交換する必要があります。

[in] prclSrc

ソースサーフェスの座標系でコピーされる領域を定義する RECTL 構造体へのポインター。四角形は 2 つのポイントで定義され、 prclDest によって定義された四角形にマップされます。ソース四角形のポイントは適切に並べられます。この関数には、空のソース四角形が指定されることはありません。

マッピングは prclSrc と prclDest によって定義されます。 prclDest および prclSrc で指定された点は、ピクセル中心に対応する整数座標上にあります。このような 2 つのポイントによって定義される四角形は、座標が指定されたポイントであるが、各座標から 0.5 が減算された 2 つの頂点を持つ幾何学的な四角形と見なされます。 (POINTL 構造体は、これらの小数座標頂点を指定するための短縮表記と見なす必要があります)。

四角形の端はピクセルと交差することはありませんが、一連のピクセルの周りを移動します。四角形内のピクセルは、"右下の排他的" 四角形で想定されるピクセルです。 DrvStretchBlt は、ジオメトリックソースの四角形を幾何学的な宛先の四角形に正確にマップします。

[in, optional] pptlMask

指定されたマスク内のどのピクセルがソース四角形の左上のピクセルに対応するかを指定する POINTL 構造体へのポインター。マスクが指定されていない場合は、このパラメーターを無視します。

[in] iMode

ソースピクセルを結合して出力ピクセルを取得する方法を指定します。 HALFTONE モードは他のモードよりも遅くなりますが、高品質の画像が生成されます。

値	意味
BLACKONWHITE	縮小ビットブロック転送では、ピクセルをブール値 AND 演算と組み合わせる必要があります。ストレッチビットブロック転送では、ピクセルをレプリケートする必要があります。
COLORONCOLOR	縮小ビットブロック転送では、ピクセルを結合する必要がないように、十分なピクセルを無視する必要があります。ストレッチビットブロック転送では、ピクセルをレプリケートする必要があります。
ハーフトーン	ドライバーは、入力の色または灰色のレベルを最適に近似するために、出力サーフェイスでピクセルのグループを使用できます。
WHITEONBLACK	縮小ビットブロック転送では、ピクセルをブール値 OR 演算と組み合わせる必要があります。ストレッチビットブロック転送では、ピクセルをレプリケートする必要があります。

戻り値

関数が成功した場合、戻り値は TRUE です。それ以外の場合は FALSE になり、エラーコードがログに記録されます。

注釈

DrvStretchBlt を使用すると、特にドライバーがハーフトニングを実行できる場合に、デバイスドライバーが GDI ビットマップに書き込むことができます。この関数を使用すると、GDI ビットマップとデバイスサーフェスに同じハーフトニングアルゴリズムを適用できます。

この関数は、整数の倍数など、特定の形式のストレッチのみを処理するために提供できます。ドライバーが呼び出しをフックし、サポートされていない操作を実行するように求められた場合、ドライバーは GDI が処理するために EngStretchBlt にデータを転送する必要があります。

ドライバーが GDI でハーフトニングを処理し、適切な iMode 値を確保したい場合、ドライバーは DrvStretchBlt をフックし、iMode を HALFTONE に設定し、iMode 値を設定した EngStretchBlt を使用して GDI にコールバックできます。

ディスプレイドライバーの場合、DrvStretchBlt は省略可能です。