drawImage() メソッド
構文
- context .
drawImage(image, dx, dy) - context .
drawImage(image, dx, dy, dw, dh) - context .
drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh) -
canvas に指定のイメージを描画します。引数は、次のように解釈されます:

もし、第 1 引数が
img,canvas,video要素でないなら、TYPE_MISMATCH_ERR例外を投げます。image にイメージ・データがないなら、INVALID_STATE_ERR例外を投げます。数値の引数に矛盾があるなら(例えば、描画先が 0 × 0 の矩形)、INDEX_SIZE_ERRを投げます。image が完全にデコードできていないなら、何も描画されません。
仕様
canvas上に画像を表示するには、drawImage メソッドを使うことができます
このメソッドは、3つの異なる引数セットを使って呼び出すことができます:
drawImage(image, dx, dy)drawImage(image, dx, dy, dw, dh)drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh)
これら3つはそれぞれ、image 引数として HTMLImageElement, HTMLCanvasElement, HTMLVideoElement のいずれかを取ることができます。
dw と dh 引数は、指定がなければ、デフォルトとして sw と sh の値が適用され、そのイメージの CSS ピクセルの 1 単位は、canvas の座標空間の 1 単位として扱われなければいけません。sx, sy, sw, sh 引数が省略されたら、これらはデフォルト値として、それぞれ、0, 0, イメージ固有の幅, イメージ固有の高さでなければいけません。単位は、そのイメージのピクセルです。
image 引数は、HTMLImageElement, HTMLCanvasElement, HTMLVideoElement のいずれかのインスタンスです。image が null だった場合は、TYPE_MISMATCH_ERR 例外を発生させなければいけません。
image 引数が、HTMLImageElement オブジェクトで、その complete 属性が false なら、または、image 引数が HTMLVideoElement オブジェクトで、その readyState 属性が HAVE_NOTHING または HAVE_METADATA のいずれかなら、何も描画せずに返らなければいけません。
image 引数が、HTMLCanvasElement オブジェクトで、横幅または縦幅のいずれかが 0 なら、INVALID_STATE_ERR 例外を発生させなければいけません。
描画元の矩形は、角が 4 つの地点 (sx, sy), (sx+sw, sy), (sx+sw, sy+sh), (sx, sy+sh) となる矩形となります。
描画元の矩形がソースのイメージの中に完全に収まらない、または、sw または sh 引数のいずれかが 0 なら、INDEX_SIZE_ERR 例外を発生させなければいけません。
描画先の矩形は、角が 4 つの地点 (dx, dy), (dx+dw, dy), (dx+dw, dy+dh), (dx, dy+dh) となる矩形となります。
drawImage()メソッドが呼び出されると、描画元の矩形で指定されたイメージの領域は、描画先の矩形で指定された canvas の領域に描画されなければいけません。描画される前に、描画先の矩形の地点に現在の変換マトリックスが適用されます。
描画元のイメージの本来のイメージデータが使われなければいけません。レンダリングされた状態のイメージではありません(例えば、元の要素の width と height 属性は作用しません。)。イメージ・データは、指定された寸法がマイナスだったとしても、本来の向きで処理されなければいけません。
本仕様では、イメージの伸縮が必要な場合に使うアルゴリズムは定義されていません。
canvas がそれ自身に描画されるとき、描画モデルは、そのイメージが canvas に書き戻される前に、そのソースがコピーされることを要求します。そのため、それ自身の重なる部分に canvas の部分をコピーすることができるのです。
drawImage() メソッドに image 引数としてアニメーション・イメージが与えられたとき、ユーザーエージェントは、そのアニメーションのポスター・フレームを適用しなければいけません。ポスター・フレームがなければ、そのアニメーションの最初のフレームが適用されます。
image 引数が HTMLVideoElement のとき、現在の再生位置におけるフレームが、描画元イメージとして使われなければいけません。描画元イメージの寸法は、該当のメディア・リソースの本来の横幅と本来の縦幅でなければいけません(つまり、アスペクト比補正が適用された後)。
イメージは、現在のパスに影響しませんが、シャドー効果、グローバル・アルファ、クリッピング領域、グローバル・コンポジション演算子の対象になります。
サンプル
『画像を組み込む』をご覧ください。
ブラウザ対応状況
| Firefox | Safari | Chrome | Opera | IE | ExplorerCanvas |
|---|---|---|---|---|---|
| 2 ○ | 2 ○ | 1 ○ | 9.2 ○ | 9 ○ | 0002 ○ |
| 3 ○ | 3 ○ | 2 ○ | 9.5 ○ | 3 ○ | |
| 3.5 ○ | 4 ○ | 3 ○ | 10 ○ | ||
| 3.6 ○ | 5 ○ | 6 ○ | 10.60 ○ |