構文

pattern = context . createPattern(image, repetition)

指定のイメージと repetition 引数に指定された向きの繰り返しを使う CanvasPattern オブジェクトを返します。

repetition に指定できる値は、repeat (両方向), repeat-x (水平方向のみ), repeat-y (垂直方向のみ), no-repeat (なし) です。もし repetition 引数が空か null なら、repeat が採用されます。

第一引数が img, canvas, video 要素でないなら、TYPE_MISMATCH_ERR 例外を投げます。イメージが完全にデコードされていない、または、イメージデータがない場合は、INVALID_STATE_ERR 例外を投げます。第二引数が許容値でないなら、SYNTAX_ERR 例外を投げます。

仕様

パターンは、CanvasPattern インタフェースを実装するオブジェクトで表されます。

原文：http://www.w3.org/TR/2010/WD-2dcontext-20100624/#dom-context-2d-createpattern

サンプル

このサンプルでは、円の中に下図のイメージを繰り返し張り合わせたものです。

まず、上図の画像ファイルの Image オブジェクトを生成します。onload イベントハンドラを使って画像の読み込みが完了してから canvas への処理が実行されるようにします。画像が読み込まれたら、createPattern() メソッドを使ってパターンを生成し、パターンを生成します。そして fillStyle プロパティにパターンをセットしてから円を描くことで、円の内部をパターンで埋めることができます。

var canvas = document.getElementById('c1');
if ( ! canvas || ! canvas.getContext ) { return false; }
var ctx = canvas.getContext('2d');
/* Imageオブジェクトを生成 */
var img = new Image();
img.src = "pattern.png?" + new Date().getTime();
/* 画像が読み込まれるのを待ってから処理を続行 */
img.onload = function() {
  ctx.beginPath();
  /* パターンを生成 */
  var ptn = ctx.createPattern(img, "");
  /* fillStyleにパターンをセット */
  ctx.fillStyle = ptn;
  /* 円を描く */
  ctx.arc(50, 50, 40, 0, 2 * Math.PI, false);
  ctx.fill();
}

[createPatternメソッドの実際のサンプル]

このサンプルでは、createPattern() メソッドの第二引数に空文字を指定していますが、repeat が指定されたものとして扱われます。

ブラウザ対応状況

createPattern() メソッドの第二引数にセットできる文字列はブラウザによって異なります。上表に掲載されている文字列が、第二引数に指定可能です。もし上表に掲載されていない文字列を第二引数に指定すると、JavaScriptエラーとなるか、もしくは意図せぬ結果で描画されます。