StretchDIBits 関数 (wingdi.h)

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

StretchDIBits 関数は、DIB、JPEG、または PNG イメージ内のピクセルの四角形の色データを、指定したコピー先の四角形にコピーします。変換先の四角形がソース四角形よりも大きい場合、この関数は、色データの行と列を展開先の四角形に合わせて拡大します。変換先の四角形がソース四角形よりも小さい場合、この関数は、指定したラスター演算を使用して行と列を圧縮します。

構文

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

パラメーター

[in] hdc

ターゲットデバイスコンテキストのハンドル。

[in] xDest

コピー先の四角形の左上隅の x 座標を論理単位で指定します。

[in] yDest

コピー先の四角形の左上隅の y 座標を論理単位で指定します。

[in] DestWidth

ターゲットの四角形の幅 (論理単位)。

[in] DestHeight

ターゲットの四角形の高さ (論理単位)。

[in] xSrc

画像内のソース四角形の x 座標 (ピクセル単位)。

[in] ySrc

画像内のソース四角形の y 座標 (ピクセル単位)。

[in] SrcWidth

画像内のソース四角形の幅 (ピクセル単位)。

[in] SrcHeight

画像内のソース四角形の高さ (ピクセル単位)。

[in] lpBits

バイトの配列として格納されるイメージビットへのポインター。詳細については、「解説」を参照してください。

[in] lpbmi

DIB に関する情報を含む BITMAPINFO 構造体へのポインター。

[in] iUsage

BITMAPINFO 構造体の bmiColors メンバーが指定されたかどうかを指定します。その場合、bmiColors に明示的な赤、緑、青 (RGB) の値またはインデックスが含まれているかどうかを指定します。 iUsage パラメーターは、次のいずれかの値である必要があります。

値	意味
DIB_PAL_COLORS	配列には、ソースデバイスコンテキストの論理パレットに 16 ビットのインデックスが含まれています。
DIB_RGB_COLORS	カラーテーブルには、リテラル RGB 値が含まれています。

詳細については、「解説」を参照してください。

[in] rop

ソースピクセル、ターゲットデバイスコンテキストの現在のブラシ、およびターゲットピクセルを結合して新しいイメージを形成する方法を指定するラスター演算コード。一般的なラスター演算コードの一覧については、「 BitBlt」を参照してください。

戻り値

関数が成功した場合、戻り値はコピーされたスキャン行の数です。ミラー化されたコンテンツの場合、この値は負の値になる可能性があることに注意してください。

関数が失敗した場合、またはスキャン行がコピーされない場合、戻り値は 0 です。

ドライバーが StretchDIBits に渡された JPEG または PNG ファイルイメージをサポートできない場合、関数は失敗し、GDI_ERRORを返します。エラーが発生した場合、アプリケーションは独自の JPEG または PNG サポートにフォールバックしてイメージをビットマップに圧縮解除し、ビットマップを StretchDIBits に渡す必要があります。

注釈

ボトムアップ DIB の原点は左下隅です。トップダウン DIB の原点は左上隅です。

StretchDIBits は、nSrcWidth パラメーターと nDestWidth パラメーターの符号が異なる場合、または nSrcHeight パラメーターと nDestHeight パラメーターが異なる場合に、ビットマップのミラーイメージを作成します。 nSrcWidth と nDestWidth の符号が異なる場合、関数は x 軸に沿ってビットマップのミラーイメージを作成します。 nSrcHeight と nDestHeight の符号が異なる場合、関数は y 軸に沿ってビットマップのミラーイメージを作成します。

STRETCHDIBits では、DIB の BITMAPINFOHEADER 構造体の biHeight メンバーの符号が負の場合、トップダウンイメージが作成されます。コード例については、「 JPEG または PNG イメージのサイズ設定」を参照してください。

この関数を使用すると、JPEG または PNG イメージをソースイメージとして渡すことができます。各パラメーターの使用方法は、次を除き、同じままです。

BITMAPINFOHEADER の biCompression メンバーがBI_JPEGまたはBI_PNGの場合、lpBits は、それぞれ JPEG または PNG イメージを含むバッファーを指します。 BITMAPINFOHEADER 構造体の biSizeImage メンバーは、バッファーのサイズを指定します。 iUsage パラメーターは、DIB_RGB_COLORSに設定する必要があります。 dwRop パラメーターは SRCCOPY に設定する必要があります。
印刷中に適切なメタファイルスプーリングを行うには、アプリケーションで CHECKJPEGFORMAT エスケープまたは CHECKPNGFORMAT エスケープを呼び出して、 StretchDIBits を呼び出す前にプリンターが JPEG または PNG イメージをそれぞれ認識していることを確認する必要があります。

Icm：色管理は、iEnableICM パラメーターを ICM_ON に設定した SetICMMode の呼び出しでカラー管理が有効になっている場合に実行されます。 lpBitsInfo で指定されたビットマップにガンマとエンドポイントのメンバーを指定するBITMAPV4HEADERがある場合、または gamma メンバーと endpoints メンバーまたは profileData メンバーと profileSize メンバーのいずれかを指定するBITMAPV5HEADERがある場合、呼び出しはビットマップのピクセルを、デバイスコンテキストのソースカラー空間ではなく、それらのメンバーによって記述された色空間で表現されたものとして扱います。

例

例については、「 JPEG または PNG イメージのサイズ設定」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	wingdi.h (Windows.h を含む)
Library	Gdi32.lib
[DLL]	Gdi32.dll