🖼️

CanvasRenderingContext2D関連メソッド一覧

に公開
JavaScript
canvas
Web API
一覧表
tech

『RPGツクールMZ』関連記事 目次

はじめに

『RPGツクールMZ』のJavaScriptで図形を描くという記事で Canvas API について調べたのですが、長くなりすぎたので、メソッド・プロパティを表にしたところを別記事にしました。
なので、このページは純粋に JavaScript(というか Web API)の情報で『RPGツクールMZ』と直接の関係はない情報です。

MDNのページに全部解説はしてあるんですが、一覧性が良くないというか、自分がなかなか把握できなかったのでメモがてら。

基本情報

  • CanvasクラスでgetContext("2d")すると2D描画するためのコンテキストCanvasRenderingContext2Dが取れる
  • CanvasRenderingContext2Dの各種メソッドでパスを生成できる
  • Path2Dでデータを作ってCanvasRenderingContext2Dにfill()やstroke()メソッドで追加する方法もある
  • パスデータを保持しておくPath2Dは、数値、文字列のような値のパス版みたいなもの
  • Path2Dには数値に+で数値を足せるのと同様にPath2DをaddPath()メソッドで追加できる
  • addPath()で追加する際にDOMMatrixを使って拡大・回転などの変形を加えられる
  • DOMMatrixの変形メソッドはCanvasRenderingContext2Dにも類似のものがある
ざっくり言えば`CanvasRenderingContext2D`についているメソッドで基本的なことはできるが、複雑な図形を描くなら`Path2D`と`DOMMatrix`を併用する、という感じ。

詳細はMDNの Canvas API、CanvasRenderingContext2D、Path2D、DOMMatrix をご参照ください。

CanvasRenderingContext2D

かなり多くのメソッドがあるので、ジャンル分けして単純な表にしました。
MDNを見ればわかると言えばわかるのですが、概要を掴みやすいように圧縮しました。
CanvasRenderingContext2D -MDN

前述の通り、コンストラクターではなくcanvas.getContext("2d")で生成します。

スタイル設定

色など、どのような表示をするかの設定をするメソッド・プロパティ。

線スタイル

プロパティ 説明
strokeStyle 色スタイルを指定(既定値:#000)
lineWidth 線の幅(既定値:1.0)
lineCap 線の末端(butt(既定値)、round、square)
lineJoin 頂点(round、bevel、miter(既定値))
miterLimit Miter limit(既定値:10)
lineDashOffset 破線にする位置を指定
メソッド 説明
getLineDash() 破線パターン配列を取得
setLineDash() 破線パターン配列を指定

塗りつぶしスタイル

プロパティ 説明
fillStyle 色スタイルを指定(既定値:#000)
createConicGradient() 扇形グラデーション
createLinearGradient() 線形グラデーション
createRadialGradient() 放射グラデーション
createPattern() 画像繰り返しパターン

影のスタイル

プロパティ 説明
shadowBlur ぼかし(既定値:0)
shadowColor 色(既定値:rgba(0,0,0,0)完全に透明の黒)
shadowOffsetX 横方向の影の長さ(既定値:0)
shadowOffsetY 縦方向の影の長さ(既定値:0)

文字スタイル

プロパティ 説明
font フォント(既定値:10px sans-serif)
textAlign 行揃え(start(既定値)、end、left、right、center)
textBaseline ベースラインの揃え(top、hanging、middle、alphabetic(既定値)、ideographic、bottom)
direction テキストの方向(ltr、rtl、inherit(既定値))

キャンバスの状態

CanvasRenderingContext2D 描画コンテキストは、さまざまな描画スタイルの状態(ラインスタイル、フィルスタイル、シャドウスタイル、テキストスタイルの属性)を含んでいます。以下のメソッドは、その状態を操作するのに役立ちます。

メソッド 説明
save() スタイル(色や線種)を一時保存
restore() save()で保存された状態に復帰
getContextAttributes()
実際のコンテキスト属性を含むオブジェクトを返す
プロパティ 説明
canvas HTMLCanvasElement への参照

パスによる描画

地道に線を引いてその組み合わせで図形を描くための、基本のメソッド・プロパティです。

パス生成

Path2Dと共通するパス生成メソッドです。これらはパスを作るだけなので、最後にfill()やstroke()で描画する必要があります。
ちなみに、面を塗って枠線も描きたいという場合、fill()とstroke()を連続で実行すればいいです。

メソッド 説明
closePath() パスを閉じる
moveTo() 始点を設定
lineTo() 直線
bezierCurveTo() 3次ベジェ曲線
quadraticCurveTo() 2次ベジェ曲線
arc() 円弧
arcTo() 直線 + 角丸
ellipse() 楕円
rect() 矩形
roundRect() 角丸矩形(※)

※ roundRect()は2023年実装なので『RPGツクールMZ』では使えません。

豆知識

ctxにCanvasRenderingContext2Dが代入されているとして、

ctx.roundRect( x, y, w, h, r );

は、次のように書き換えて『RPGツクールMZ』で使えます。

ctx.moveTo( x + r, y );
ctx.arcTo( x + w, y, x + w, y + r, r );// ─╮
ctx.arcTo( x + w, y + h, x + w - r, y + h, r );//│ ╯
ctx.arcTo( x, y + h, x, y + h - r, r );//╰─
ctx.arcTo( x, y, x + r, y, r );// │╭

面倒くさいですね!!roundRect()が導入されるわけです。

パスの描画

引いたパスを描画するためと、その関連メソッドです。

メソッド 説明
beginPath() パスを初期化
fill() パスを塗りつぶす
stroke() パスを線で描く
clip() 切り抜き(マスク)指定

複雑な描画

パスを描く方法はシンプルですが、それなりの図形を描こうとすると大量に記述する必要があります。
そこで、よく使う形状は簡単な記述で描けるよう、専用のメソッドがあります。
現在のパスとは別にキャンバスに直接描画を行うので現在のパスは保持されます。
このためbiginPath()で区切る必要がなく、前後の処理を考えず気軽に使えます。
描画には現在のスタイルが適用されます。

矩形の描画

いくつかのメソッドをまとめた感じのメソッドです。

メソッド 説明
strokeRect() rect();stroke()
fillRect() rect();fill()
clearRect() 透明の矩形

※ clearRect()はfillStyle="rgba(0,0,0,0);rect();fill()

文字列の描画

メソッド 説明
fillText() 塗りつぶしスタイルの文字
strokeText() 線スタイルの袋文字
measureText() TextMetrics オブジェクトを返す

画像の描画

JPEGやPNG、SVGファイルのような、まとまった画像を扱うメソッドです。
直接ファイルを指定できないので、別途読み込みの仕組みが必要です。

メソッド 説明
drawImage() 各種指定画像データを描画
createImageData() 空の ImageDataオブジェクトを返す
getImageData() 矩形で指定した部分を ImageDataオブジェクトとして返す
putImageData() 指定位置・範囲に ImageDataオブジェクトを描画

図形の加工

描いた図形を最終的な出力の前に加工するためのメソッド・プロパティです。

図形の座標変換

変換行列は直接引数の並びとして渡す他にDOMMatrixを使えます。

メソッド 説明
getTransform() DOMMatrixを取得
rotate() ラジアン角の回転を追加
scale() 拡大縮小変換を追加
translate() 平行移動を追加
transform() 変換行列を適用
setTransform() 変換行列を追加適用
resetTransform() 変換行列を初期化

合成

さまざまな合成方法が用意されておりclip()のようなマスクとしても使えます。

プロパティ 説明
globalAlpha 不透明度(既定値:1.0)
globalCompositeOperation 合成タイプを指定

画像フィルタ

プロパティ 説明
imageSmoothingEnabled 画像平滑化(スムージング)モードか
imageSmoothingQuality 画像平滑化の品質を設定
filter CSS や SVG のフィルターを適用

UI関連

メソッド 説明
drawFocusIfNeeded()
指定要素がフォーカスされた時にパスの周囲にフォーカスリングを描画
[scrollPathIntoView()](https://developer.mozilla.org/ja/docs/Web/API/CanvasRenderingContext2D/
scrollPathIntoView) 指定パスが表示範囲に入るまでスクロール
isPointInPath() 指定座標がパス図形の上か
isPointInStroke() 指定座標が線パスの内部か

Path2Dオブジェクト

Path2D はパス保持するためのオブジェクトです。
スタイル情報を持たずパスを保持するだけなので、表示機能はありません。
CanvasRenderingContext2Dに比べるとメソッドが少ないですが、組み合わせによって同じようなパスは描けます。

Path2D - MDN

new Path2D() コンストラクターの引数には SVGテキストか Path2Dインスタンスが指定可能です。

Path2Dコンストラクター - MDN

addPath()以外のパス生成メソッドはCanvasRenderingContext2Dにも含まれています。

メソッド 説明
addPath() パスを追加
closePath() パスを閉じる
moveTo() 始点を設定
lineTo() 直線
bezierCurveTo() 3次ベジェ曲線
quadraticCurveTo() 2次ベジェ曲線
arc() 円弧
arcTo() 直線 + 角丸
ellipse() 楕円
rect() 矩形
roundRect() 角丸矩形

※ roundRect()は2023年実装なので『RPGツクールMZ』では使えません。参考までに。

addPath()の引数には、パス(Path2D)と同時に変形の行列データ(DOMMatrix)を渡せます。
変形を変数で渡す場合、スコープが切れると変形効果も消えるので注意(なんでそうなるのかは理解してません、てへへ)

すでに複雑な形のデータを持っている文字を使う手もあります。
ちなみにctx.fillText()メソッドでも書けますが、コアスクリプトが用意しているthis.bitmap.drawText()を使った方が楽かと思います。

  1. Path2Dクラスを使ってパスを作り、fill()やstroke()でctxを通してパスを追加できる
  2. Path2DにはPath2DをaddPath()メソッドで追加できる(数値に+で数値を足せるように)
  3. addPath()で追加する際に、DOMMatrixを使って変形を加えられる

詳細はMDNのPath2Dを参照ください。

DOMMatrixオブジェクト

Web API には図形の変形(アフィン変換)を行うための行列が用意されていて、それがDOMMatrixオブジェクトです。JavaScriptで行列を扱う方法は二転三転しているようですが、なんとか落ち着いた雰囲気です。
以前は Matrix.js などのライブラリを使う方法が一般的(今も？)だったようです。

DOMMatrix -MDN

2Dと3Dの変換が行えますが、2Dの場合は次のように生成します。

DOMMatrixコンストラクター -MDN

new DOMMatrix([ a, b, c, d, e, f ]);//2D行列の生成

行列としては次の形です。

┌a,c,0,e┐
│b,d,0,f│
│0,0,1,0│
└0,0,0,1┘

コンストラクターに引数を渡さない場合は4×4の単位行列が生成されます。
行列とその座標変換への応用を理解している人は、すでに「なるほど」となっていると思いますが、そうでない人にはちんぷんかんぷんだと思います。
DOMMatrix: 2D / 3D 変形（アフィン変換）の行列を扱う DOM API - KABUKUの記事が詳しいので、詳細を知りたい方はどうぞ。

行列を直接書いて変形を適用するのではなく、メソッドで変形させる方が簡単だし、大抵はそれで事足りると思います。
回転や移動などはCanvasRenderingContext2Dにも類似のメソッドがありますが、DOMMatrixをPath2Dに個別に適用する方が何かと応用が効きます。

ここでは、ざっとメソッドを並べておきます。
invertSelf()以外は自分自身を返すので、ドットで連結するメソッドチェーンが利用できます。
(2024/07/23現在ではリンク先に解説はありません)

インスタンスメソッド

メソッド 説明
invertSelf() 逆行列に変更
multiplySelf() 点積 A⋅B
preMultiplySelf() 点積 B⋅A
translateSelf() ベクトル移動
scaleNonUniformSelf() 非推奨 X、Y、Z 軸に拡大縮小
scaleSelf() 拡大縮小
scale3dSelf() 3つの軸すべてを拡大縮小
rotateSelf() 各軸の周りに回転
rotateAxisAngleSelf() 指定ベクトルの周りに回転
rotateFromVectorSelf() 指定ベクトルと (1, 0) とのなす角だけ回転
setMatrixValue() 指定した変換で記述された行列で置き換え
skewXSelf() X 軸に沿って、指定した傾き変換
skewYSelf() Y 軸に沿って、指定した傾き変換

静的メソッド

メソッド 説明
fromFloat32Array() 単精度浮動小数点数の配列からDOMMatrix オブジェクトを作成
fromFloat64Array() 倍精度浮動小数点数の配列からDOMMatrix オブジェクトを作成
fromMatrix() 既存の行列から新しい変更可能な DOMMatrix オブジェクトを作成

最後に

ということで、単にMDNの該当ページへリンクしたメソッド一覧、という感じの記事ですが、詳しい記事へのリンクもしたからバッチリだね(笑)

Discussion