サイト内検索

createPattern() メソッド

構文

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 インタフェースを実装するオブジェクトで表されます。

このタイプのオブジェクトを生成するためには、createPattern(image, repetition) メソッドを使います。第一引数には、パターンとして使いたいイメージ(HTMLImageElementHTMLCanvasElementHTMLVideoElement)を与えます。createPattern() メソッドを呼び出した後にこのイメージを変更しても、パターンに影響を及ぼしてはいけません。第二引数は、repeat, repeat-x, repeat-y, no-repeat のいずれかの文字列でなければいけません。もし空の文字列もしくは null が指定されたら、repeat が指定されたとみなさなければいけません。もし認識できない値が指定された場合は、SYNTAX_ERR 例外を発生させなければいけません。ユーザエージェントは正確に前述の 4 つの値を認識しなければいけません(例えば、大文字・小文字は区別されます。)。このメソッドは、適切に初期化された CanvasPattern オブジェクトを返さなければいけません。

引数 image は、HTMLImageElement または HTMLCanvasElement または HTMLVideoElement のいずれかのインスタンスでなければいけません。引数 image に間違ったタイプが指定された場合は、TYPE_MISMATCH_ERR 例外を発生しなければいけません。

image に、complete 属性が false の HTMLImageElement オブジェクトが指定された場合は、INVALID_STATE_ERR 例外を発生させなければいけません。

image に、水平寸法または垂直寸法が 0 に等しい HTMLCanvasElement オブジェクトが指定された場合は、INVALID_STATE_ERR 例外を発生させなければいけません。

パターンは、最初のイメージの左上端が座標空間の基点で固定されるように描画されなければいけません。そして、イメージは左から右に向けて水平に(文字列 repeat-x が指定された場合)、または、上から下に向けて垂直に(文字列 repeat-y が指定された場合)、または、canvas 全体を 4 方向に(文字列 repeat が指定された場合)繰り返し描画されます。このプロセスでは、イメージが伸縮されることはありあせん。イメージの CSS の 1 ピクセル分は、座標空間の 1 単位分に描画されます。もちろん、実際には、輪郭や塗りつぶしされることが要求されたところだけに描画され、現在の変形マトリックスの影響を受けます。

createPattern() メソッドに image 引数としてアニメーション・イメージを渡すと、ユーザーエージェントは、そのアニメーションのポスター・フレームを使わなければいけません。ポスター・フレームがなければ、そのアニメーションの最初のフレームを使わなければいけません。

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


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

サンプル

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 が指定されたものとして扱われます。

ブラウザ対応状況

Firefox Safari Chrome Opera IE ExplorerCanvas
2 △
"repeat"
"no-repeat"
null
空文字
2 △
"repeat"
null
空文字
1 △
"repeat"
空文字
9.2 △
"repeat"
空文字
9 ○
"repeat"
"repeat-x"
"repeat-y"
"no-repeat"
null
空文字
0002 ×
3 △
"repeat"
"no-repeat"
null
空文字
3 △
"repeat"
空文字
2 △
"repeat"
null
空文字
9.5 △
"repeat"
null
空文字
  3 ×
3.5 △
"repeat"
"no-repeat"
null
空文字
4 △
"repeat"
null
空文字
       

3.6 △
"repeat"
"no-repeat"
null
空文字

5 ○
"repeat"
"repeat-x"
"repeat-y"
"no-repeat"
null
空文字
6 ○
"repeat"
"repeat-x"
"repeat-y"
"no-repeat"
null
空文字
10.60 ○
"repeat"
"repeat-x"
"repeat-y"
"no-repeat"
null
空文字
   

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