サイト内検索

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 に指定のイメージを描画します。引数は、次のように解釈されます:

The sx and sy parameters give the x and y coordinates of the source rectangle; the sw and sh arguments give the width and height of the source rectangle; the dx and dy give the x and y coordinates of the destination rectangle; and the dw and dh arguments give the width and height of the destination rectangle.

もし、第 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 のいずれかを取ることができます。

dwdh 引数は、指定がなければ、デフォルトとして swsh の値が適用され、そのイメージの 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 の領域に描画されなければいけません。描画される前に、描画先の矩形の地点に現在の変換マトリックスが適用されます。

描画元のイメージの本来のイメージデータが使われなければいけません。レンダリングされた状態のイメージではありません(例えば、元の要素の widthheight 属性は作用しません。)。イメージ・データは、指定された寸法がマイナスだったとしても、本来の向きで処理されなければいけません。

本仕様では、イメージの伸縮が必要な場合に使うアルゴリズムは定義されていません。

canvas がそれ自身に描画されるとき、描画モデルは、そのイメージが canvas に書き戻される前に、そのソースがコピーされることを要求します。そのため、それ自身の重なる部分に canvas の部分をコピーすることができるのです。

drawImage() メソッドに image 引数としてアニメーション・イメージが与えられたとき、ユーザーエージェントは、そのアニメーションのポスター・フレームを適用しなければいけません。ポスター・フレームがなければ、そのアニメーションの最初のフレームが適用されます。

image 引数が HTMLVideoElement のとき、現在の再生位置におけるフレームが、描画元イメージとして使われなければいけません。描画元イメージの寸法は、該当のメディア・リソースの本来の横幅と本来の縦幅でなければいけません(つまり、アスペクト比補正が適用された後)。

イメージは、現在のパスに影響しませんが、シャドー効果、グローバル・アルファ、クリッピング領域、グローバル・コンポジション演算子の対象になります。


原文:http://www.w3.org/TR/2010/WD-2dcontext-20100624/#images

サンプル

画像を組み込む』をご覧ください。

ブラウザ対応状況

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 ○