canvas 要素

4.8.11 canvas 要素

カテゴリー
フロー・コンテンツ
フレージング・コンテンツ
エンベッディッド・コンテンツ
この要素を使うことができるコンテキスト：
エンベッディッド・コンテンツが期待される場所
コンテンツ・モデル
トランスペアレント
コンテンツ属性：
グローバル属性
width
height
DOM インタフェース：
interface HTMLCanvasElement : HTMLElement {
           attribute unsigned long width;
           attribute unsigned long height;

  DOMString toDataURL(in optional DOMString type, in any... args);
  void toBlob(in FileCallback, in optional DOMString type, in any... args);

  object getContext(in DOMString contextId, in any... args);
};

canvas 要素は、スクリプトに解像度依存のビットマップ・キャンバスを提供し、グラフ、ゲームグラフィックス、そのほか、ビジュアル・イメージをその場でレンダリングするために使うことができます。

ウェブ制作者は、もっと適切な要素が利用できるなら、そのドキュメントで canvas 要素を使うべきではありません。例えば、ページの見出しをレンダリングするために canvas 要素を使うのは不適切です。もし、その見出しをグラフィックに重点をおいてた表現にしたいなら、適切な要素（通常は h1）を使ってマークアップし、それから、CSS や XBL のようなサポート・テクノロジーを使ってスタイリングするべきです。

ウェブ制作者が canvas 要素を使うときは、コンテンツも提供しなければいけません。そのコンテンツとは、それがユーザーに提供されるとき、ビットマップ・キャンバスと同じ目的や役割を本質的に伝達するものです。このコンテンツは、canvas 要素のコンテンツとして入れることができます。canvas 要素のコンテンツは、もしあれば、その要素のフォールバック・コンテンツとなります。

インタラクティブなビジュアル・メディアでは、canvas 要素に対してスクリプティングが有効なら、そして、canvas 要素のサポートが有効であれば、その canvas 要素は、動的に生成されたイメージから構成されるエンベッディッド・コンテンツを表します。

非インタラクティブで静的なビジュアル・メディアでは、canvas 要素が以前に描画されたなら（例えば、もしページがインタラクティブなビジュアル・メディアで見られ、今、印刷されているなら、または、ページレイアウト処理の途中で実行していたいくつかのスクリプトが、その要素上に描画していたなら）、その canvas 要素は現在のイメージとサイズを持ったエンベッディッド・コンテンツを表します。そうでなければ、この要素は代わりにフォールバック・コンテンツを表します。

非ビジュアルメディア、そして、canvas 要素に対してスクリプティングが無効となっている、または、canvas 要素のサポートが無効になっているビジュアル・メディアでは、canvas 要素は代わりにフォールバック・コンテンツを表します。

canvas 要素がエンベッディッド・コンテンツを表すときでも、ユーザーはその canvas 要素の子孫（フォールバック・コンテンツ）にフォーカスすることができます。要素がフォーカスされたとき、それは、キーボード・インタラクション・イベントのターゲットになります（その要素そのものは見ることすらできませんが）。これによって、ウェブ制作者は、インタラクティブな canvas を、キーボードからアクセスできるようにすることができます。ウェブ制作者は、フォールバック・コンテンツにあるフォーカス可能な要素に、インタラクティブ領域を 1 対 1 に対応付けするべきです。（フォーカスは、マウス・インタラクション・イベントには何も影響を与えません。）[DOMEVENTS]

canvas 要素は、座標空間のサイズをコントロールする2つの属性を持ちます： width と height です。これらの属性は、指定するとき、妥当な非負整数でなければいけません。それらの数値を取得するために、非負整数パース規則を使わなければいけません。属性が指定されなかった、または、その値をパースしたらエラーになったら、代わりにデフォルト値を使わなければいけません。width 属性のデフォルトは 300 で、height 属性のデフォルトは 150 です。

canvas 要素の本来の寸法は、座標空間のサイズと等しくなります。その数字は CSS ピクセルで解釈されます。しかし、この要素はスタイルシートを使って自由にサイズを変更することができます。レンダリング中に、そのイメージはこのレイアウトサイズにフィットするよう伸縮されます。

座標空間のサイズは、必ずしも、ユーザーエージェントが初期またはレンダリング中に使うであろう実際のビットマップのサイズを表すとは限りません。高解像度ディスプレーでは、例えば、ユーザーエージェントは内部的に座標空間内の一単位を 2 デバイスピクセルにしたビットマップを使うことができます。こうすることで、レンダリングは全体を通してハイクオリティに維持されます。

canvas 要素が生成され、それに続き、width と height 属性が（新しい値に、または、以前の値に）セットされたらいつでも、そのビットマップと関連コンテンツは初期状態にクリアされ、新たに指定された座標空間の寸法で再び初期化されなければいけません。

canvas が初期化されると、そのビットマップは透明な黒としてクリアされなければいけません。

width と height IDL 属性は、同じ名前の対応するコンテンツ属性を、同じデフォルトを伴い、反映しなければいけません。

次の例では、ひとつの四角形だけが描かれ現れます：

  // canvas is a reference to a <canvas> element
  var context = canvas.getContext('2d');
  context.fillRect(0,0,50,50);
  canvas.setAttribute('width', '300'); // clears the canvas
  context.fillRect(0,100,50,50);
  canvas.width = canvas.width; // clears the canvas
  context.fillRect(100,0,50,50); // only this square remains
context = canvas . getContext(contextId [, ... ])

canvas に描画するための API が利用できるオブジェクトを返します。第一引数は、必要な API を指定します。それ以降の引数は、その API によって扱われます。

定義済みコンテキストのリストは、WHATWG Wiki CanvasContexts ページに掲載されています。 [WHATWGWIKI]

指定のコンテキスト ID が未サポート、または、その canvas がすでに別の（互換性がない）コンテキスト・タイプで初期化されたのであれば（例えば、"webgl" コンテキストを取得した後に、"2d" コンテキストを取得しようとした場合）、null を返します。

canvas 要素は、プライマリー・コンテキストを持つことができます。これは、この要素に対して取得された最初のコンテキストです。canvas 要素は、生成時には、プライマリー・コンテキストを持ってはいけません。

最も一般的に使われるプライマリー・コンテキストは、HTML Canvas 2D Context です。

canvas 要素の getContext(contextId, args...) メソッドは、呼び出されたら、次の手順を実行しなければいけません：

  1. contextId を、このメソッドの第一引数とします。

  2. contextId が、ユーザーエージェントによってサポートされたコンテキストの名前でなければ、null を返し、これらの手順を中止します。

    理論的には、"webgl" 3D コンテキストをサポートしているユーザーエージェントで、プラットフォームのハードウェアが OpenGL をサポートしておらず、ユーザーエージェントがソフトウェア OpenGL を実装していない場合が該当するでしょう。ユーザーエージェントが "webgl" という名前を認識しているにもかかわらず、この手順では null を返すことになります。なぜなら、そのコンテキストは、実際には、呼び出し時にはサポートされないからです。

  3. この要素がプライマリー・コンテキストを持ち、そのコンテキストと互換性があるコンテキストの contextId が WHATWG Wiki CanvasContexts ページに掲載されていなければ、null を返し、これらの手順を中止します。[WHATWGWIKI]

  4. この要素がプライマリー・コンテキストを持たないなら、この要素のプライマリー・コンテキストを contextId とします。

  5. getContext() メソッドが、この要素ですでに同じ contextId で呼び出されたのであれば、そのときに返したのと同じオブジェクトを返し、これらの手順を中止します。追加の引数は無視されます。

  6. contextId 向けに新規のオブジェクトを返します。これは、WHATWG Wiki CanvasContexts ページの contextId のエントリーに指定された仕様で定義されている通りです。 [WHATWGWIKI]

新規のコンテキスト・タイプは、WHATWG Wiki CanvasContexts ページに登録されていくでしょう。 [WHATWGWIKI]

誰でもいつでも、 WHATWG Wiki CanvasContexts ページを編集して、新たなコンテキスト・タイプを自由に追加することができます。このような新たなコンテキスト・タイプは、次の情報とともに仕様化されなければいけません：

キーワード

新 API 向けのオブジェクトを返す contextID の値

仕様

コンテキスト・タイプの API の公式な仕様へのリンク。該当の Wiki の別のページでも構いませんし、外部のページへのリンクでも構いません。そのタイプが公式な仕様を持っていないなら、公式な仕様が利用できる時まで、非公式な説明文で代用可能です。

互換

互換性があるコンテキスト・タイプの一覧（つまり、同じ下層ビットマップで動作する）。このリストは、推移的かつ対称的でなければいけません。つまり、ひとつのコンテキストが他のものと互換性があるとして定義されるなら、それと互換性があるすべてのタイプは、他方が互換性があると言っているすべてのタイプと互換性がなければいけません。

ベンダーは、vendorname-context という構文を使った実験的なコンテキストを定義することも可能です。例えば moz-3d です。こういったコンテキストは、WHATWG Wiki CanvasContexts ページに登録されるべきです。

url = canvas . toDataURL( [ type, ... ])

canvas イメージの data: URL を返します。

第一引数が与えられたら、それは、返されるべきイメージのタイプを制御します（PNG や JPEG など）。デフォルトは image/png です。このタイプは、指定されたタイプがサポートされなかった場合にも採用されます。他の引数は、該当のタイプに特化したものとなり、下表の通り、イメージ生成方法を制御します。

"image/png" 以外のタイプを使おうとするとき、ウェブ制作者は、そのイメージが、文字列 "data:image/png," か "data:image/png;" で始まる文字列を返すかどうかをチェックすることで、リクエストしたフォーマットで本当に返されたかどうかをチェックすることができます。もしそうなら、そのイメージは PNG です。そして、ゆえに、リクエストされたタイプはサポートされていなかったということになります。（これには例外がひとつあります。それは canvas が高さも幅も持たない場合です。この場合、"data:," だけという結果になります。）

canvas . toBlob(callback [, type, ... ])

canvas のイメージを含んだファイルを表す Blob オブジェクトを生成し、そのオブジェクトへのハンドルとともに callback を呼び出します。

第二引数が指定されたら、それは、返されるべきイメージのタイプを制御します（例えば PNG や JPEG）。デフォルトは image/png です。このタイプは、指定されたタイプがサポートされていなかったときにも使われます。他の引数は、そのタイプに特化したもので、下表の通り、イメージ生成方法を制御します。

toDataURL() メソッドは次の手順を実行しなければいけません：

  1. canvas にピクセルがなければ（つまり、縦も横も寸法が 0）、文字列 "data:," を返し、これらの手順を中止します。（これは最短の data: URL で、text/plain リソースでは空文字列を表します）

  2. file を、このメソッドの引数（もしあれば）を arguments として使って、該当のイメージのファイルとしてのシリアライゼーションとします。

  3. file を表す data: URL を返します。 [RFC2397]

toBlob() メソッドは次の手順を実行しなければいけません：

  1. callback を第一引数とします。

  2. arguments を、第二引数と、後続の引数があれば、それも加えたものとします。

  3. file を、arguments を使って、 イメージのファイルとしてのシリアライゼーションとします。

  4. 返します。しかし、非同期にこれらの手順を続けます。

  5. callback が null なら、これらの手順を中止します。

  6. file を表す Blob オブジェクトを引数にして、FileCallback callback を呼び出すタスクをキューイングします。このタスクに対するタスク・ソースは、canvas blob シリアライゼーション・タスク・ソースです。 [FILESYSTEMAPI] [FILEAPI]

ユーザーエージェントは、ファイルとしてのイメージのシリアライゼーションを生成することになったとき、オプションで指定された arguments を使いますが、arguments の最初の値によって指定されたフォーマットで、または、arguments がなければ PNG フォーマットで、イメージ・ファイルを生成しなければいけません。 [PNG]

arguments が空でなければ、その最初の値は、採用フォーマットを与える MIME タイプとして解釈されなければいけません。そのタイプにパラメータがあれば、それはサポートされないものとして扱われなければいけません。

例えば、値が "image/png" なら PNG イメージを生成することを意味するでしょうし、値が "image/jpeg" なら JPEG イメージを生成することを意味するでしょう。そして、値が "image/svg+xml" なら SVG イメージを生成することを意味するでしょう（ただし、この場合は、canvas から SVG イメージを確実にレンダリングできるに十分な情報を実際に保持することが実装に求められるでしょう）。

ユーザーエージェントは PNG ("image/png")をサポートしなければいけません。ユーザーエージェントは他のタイプをサポートすることができます。もしユーザーエージェントがリクエストされたタイプをサポートしていないのであれば、PNG フォーマットを使ってファイルを生成しなければいけません。 [PNG]

ユーザーエージェントは、指定されたタイプを小文字に変換してから、そのタイプをサポートしているかどうかを確定しなければいけません。

アルファ・チャネルをサポートしないイメージ・タイプに対して、シリアル化されたイメージは、source-over オペレータを使って無地の黒の背景の上に canvas イメージを合成したものでなければいけません。

arguments の最初の引数が次表の最初のカラムのタイプの一つに一致するタイプであり、かつ、ユーザーエージェントがそのタイプをサポートするなら、それ以降に引数は、もしあれば、その行の二番目のセルで説明された通りに扱われなければいけません。

タイプ 他の引数 リファレンス
image/jpeg 第二引数は、0.0 以上 1.0 以下の範囲の数値なら、品質レベルとして扱われなければいけません。もし数値でなかったり、該当の範囲外なら、ユーザーエージェントは、その引数が省略されたかのように、デフォルト値を使わなければいけません。 [JPEG]

これらの手順の目的においては、引数は、それが Web IDL 仕様で any というタイプの引数を扱う規則によって IDL double 値に変換されるなら、数値であると判断されます。[WEBIDL]

他の引数は無視されなければならず、ユーザーエージェントが例外を発出するようなことがあってはいけません。本仕様の将来のバージョンでは、ウェブ制作者が、圧縮設定やイメージのメタデータなど、より入念に制御できるよう、これらのメソッドに引き渡せるパラメータが他にも定義されるかもしれないでしょう。

4.8.11.1 色空間と色補整

canvas API の色補正は 2 箇所だけで実行されなければいけません：まず、canvas 自身が持つガンマ補整と色空間情報を使って canvas 上にイメージをレンダリングするときです。これは、その canvas で使われている色空間にイメージを変換するためです（例えば、HTMLImageElement オブジェクトを使って、2D コンテキストの drawImage() メソッドを使うなどして）。もうひとつは、出力デバイスに実際の canvas ビットマップをレンダリングするときです。

ゆえに、2D コンテキストでは、canvas 上に図形を描くために使われる色は、getImageData() メソッドを通して得られた色に正確に一致します。

toDataURL()メソッドは、返ってきたリソース内の色空間情報を含めてはいけません。出力フォーマットがそれを許す場合、toDataURL() によって生成されたリソース内のピクセルの色は、getImageData()メソッドによって返されるリソースに一致しなければいけません。

CSS をサポートするユーザーエージェントでは、canvas 要素で使う色空間は、その要素に対して CSS で扱う色を処理するために使われる色空間に一致しなければいけません。

イメージのガンマ補整と色空間情報は、img 要素を使って直接的にレンダリングされるイメージが、canvas 要素上に描画されるものと同じ色を使う、といった方法で扱われなければいけません。さらに、色補正情報を持たないイメージのレンダリング（toDataURL()メソッドによって返される情報など）は、色補正なしにレンダリングされなければいけません。

ゆえに、2D コンテキストでは、drawImage()メソッドを呼び出して、toDataURL()メソッドの出力を canvas にレンダリングしても、適切な寸法を与えれば、ビジュアル効果は一切発生しません。

4.8.11.2 canvas 要素のセキュリティー

あるオリジンのスクリプトが、他のオリジン（同一でないオリジン）のイメージの情報にアクセス（例：ピクセルを読み取る）することができてしまうと、情報漏洩が発生する可能性が出てきてしまいます。

これを低減するために、canvas 要素は、それらが origin-clean かどうかを表すフラグを持つよう定義されています。すべての canvas 要素は origin-clean を true にセットして開始します。このフラグは、次のアクションのいずれかが発生したら、false にセットされなければいけません：

  • 該当の要素の 2D コンテキストの drawImage()メソッドが、その canvas 要素を持つ Document オブジェクトのオリジンと同じでない HTMLImageElement や HTMLVideoElement を使って呼び出された。

  • 該当の要素の 2D コンテキストの drawImage() メソッドが、origin-clean フラグが false となる HTMLCanvasElement を使って呼び出された。

  • 該当の要素の 2D コンテキストの fillStyle 属性に CanvasPattern オブジェクトがセットされた。ただし、そのオブジェクトが、パターン生成時に、該当の canvas 要素を持つ Document オブジェクトのオリジンと同じでない HTMLImageElement や HTMLVideoElement から生成された。

  • 該当の要素の 2D コンテキストの fillStyle 属性に CanvasPattern オブジェクトがセットされた。ただし、そのオブジェクトが、パターン生成時に、origin-clean フラグが false だった HTMLCanvasElement から生成された。

  • 該当の要素の 2D コンテキストの strokeStyle 属性に CanvasPattern オブジェクトがセットされた。ただし、そのオブジェクトが、パターン生成時に、該当の canvas 要素を持つ Document オブジェクトのオリジンと同じでない HTMLImageElement や HTMLVideoElement から生成された。

  • 該当の要素の 2D コンテキストの strokeStyle 属性に CanvasPattern オブジェクトがセットされた。ただし、そのオブジェクトが、パターン生成時に、origin-clean フラグが false だった HTMLCanvasElement から生成された。

  • 該当の要素の 2D コンテキストの fillText() または fillText() メソッドが呼びだれ、該当の canvas 要素を持つ Document オブジェクトと同じでないオリジンを持つフォントを使ったと判断した。（そのフォントが使われている必要すらありません。そのフォントのグリフが描画されたと判断されたかどうかだけが問題なのです。）

origin-clean フラグが false にセットされた canvas 要素の toDataURL()メソッドが呼び出されたら、このメソッドは SECURITY_ERR 例外を発生させなければいけません。

origin-clean フラグが false にセットされた canvas 要素の getImageData()メソッドが不適切な引数を使って呼び出されたら、このメソッドは SECURITY_ERR 例外を発生させなければいけません。

canvas 要素の 2D コンテキストの measureText() メソッドが、その canvas 要素を持つ Document オブジェクトと同じでないオリジンを持つフォントを使っていると分かったら、このメソッドは、SECURITY_ERR 例外を発出しなければいけません。

たとえ、width と height を変更して canvas をリセットしたとしても、origin-clean フラグはリセットされません。

※ 原文：http://www.w3.org/TR/2011/WD-html5-20110525/the-canvas-element.html#the-canvas-element

※ canvas 要素の詳細につきましては、当サイトの「Canvas」コーナーをご覧ください。