SetDIBitsToDevice 関数 (wingdi.h)

[アーティクル]
08/27/2023

SetDIBitsToDevice 関数は、DIB、JPEG、または PNG イメージのカラーデータを使用して、ターゲットデバイスコンテキストに関連付けられているデバイス上の指定された四角形のピクセルを設定します。

構文

int SetDIBitsToDevice(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] DWORD            w,
  [in] DWORD            h,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] UINT             StartScan,
  [in] UINT             cLines,
  [in] const VOID       *lpvBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             ColorUse
);

パラメーター

[in] hdc

デバイスコンテキストへのハンドル。

[in] xDest

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

[in] yDest

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

[in] w

イメージの幅 (論理単位)。

[in] h

イメージの高さ (論理単位)。

[in] xSrc

イメージの左下隅の x 座標 (論理単位)。

[in] ySrc

イメージの左下隅の y 座標 (論理単位)。

[in] StartScan

イメージ内の開始スキャン行。

[in] cLines

lpvBits パラメーターが指す配列に含まれる DIB スキャン行の数。

[in] lpvBits

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

[in] lpbmi

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

[in] ColorUse

BITMAPINFO 構造体の bmiColors メンバーに、明示的な赤、緑、青 (RGB) の値またはインデックスがパレットに含まれているかどうかを示します。詳細については、「解説」を参照してください。

fuColorUse パラメーターは、次のいずれかの値である必要があります。

値	意味
DIB_PAL_COLORS	カラーテーブルは、現在選択されている論理パレットに 16 ビットインデックスの配列で構成されます。
DIB_RGB_COLORS	カラーテーブルには、リテラル RGB 値が含まれています。

戻り値

関数が成功した場合、戻り値は設定されたスキャン行の数です。

スキャン行が 0 に設定されている場合 ( dwHeight が 0 の場合など)、関数が失敗した場合、関数は 0 を返します。

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

注釈

ビットマップビットがシステムパレットのインデックスである場合、最適なビットマップ描画速度が得られます。

アプリケーションは、 GetSystemPaletteEntries 関数を呼び出すことによって、システムパレットの色とインデックスを取得できます。色とインデックスを取得した後、アプリケーションで DIB を作成できます。システムパレットの詳細については、「色」を参照してください。

スキャン行は、RLE 圧縮ビットマップを除き、 DWORD に配置する必要があります。

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

デバイスサーフェイス上の大きな DIB からビットを設定するために必要なメモリ量を減らすために、アプリケーションは SetDIBitsToDevice を繰り返し呼び出して、ビットマップの異なる部分を lpvBits 配列に毎回配置することで、出力をバンド化できます。 uStartScan パラメーターと cScanLines パラメーターの値は、lpvBits 配列に含まれるビットマップの部分を識別します。

SetDIBitsToDevice 関数は、全画面表示 MS-DOS セッションがフォアグラウンドで実行されている間にバックグラウンドで実行されているプロセスによって呼び出された場合にエラーを返します。

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

Icm：色管理は、iEnableICM パラメーターを ICM_ON に設定した SetICMMode の呼び出しでカラー管理が有効になっている場合に実行されます。 lpbmi で指定されたビットマップにガンマとエンドポイントのメンバーを指定する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