ペイントタイミング

1. はじめに

const observer = new PerformanceObserver(function(list) {
    const perfEntries = list.getEntries();
    for (const perfEntry of perfEntries) {
        // エントリーの処理
        // 分析や監視のための報告
        // ...
    }
});

// ペイントタイミング通知のためのオブザーバ登録
observer.observe({entryTypes: ["paint"]});

2. 用語

ペイント：ユーザーエージェントが「ペイント」（または「レンダー」）を実行したとは、レンダーツリーを画面上のピクセルに変換したことを指します。正式には、ユーザーエージェントがイベントループのレンダリングの更新ステップを実行したときに「レンダー」されたとみなします。

注意: レンダリング処理は非常に複雑であり、タイムスタンプはユーザーエージェントがこのパイプラインで記録できる最新のタイムスタンプ（ベストエフォート）であるべきです。通常、このAPIではフレームがOSへ表示のため送信される時刻が推奨されます。

生成コンテンツ疑似要素は、以下すべてを満たす場合ペイント可能疑似要素です：

• 疑似要素の 算出済み visibility は visible です。

• 疑似要素の使用済みのopacityは0より大きいです。

• 疑似要素は非空のボックスを生成します。

CSS画像 imgは、以下すべてを満たす場合内容画像です：

• imgがurl値を持つ。

• imgが利用可能である。

DOMString は、非空であるとは、文書の空白文字以外の文字を1文字以上含む場合です。

要素 targetは、次のいずれかを満たす場合内容有りです：

• target は、テキストノード の子を持ち、その子は空でない テキストを表し、かつそのノードの使用 不透明度が 0 より大きい。

  注記: これは、タイポグラフィ疑似要素がテキストノードの不透明度を 上書きする場合を含む。

• target は、置換要素であり、利用可能な 画像を表す。

• target は、background-image を持ち、それがコンテンツを含む画像であり、かつその使用 background-size の幅と高さの値が 0 ではない。

• target は、border-image-source を持ち、それがコンテンツを含む 画像であり、かつその使用 border-image-width の値が 0 ではない。

• target は、 canvas であり、そのコンテキストモードが none 以外の任意の値に設定されている。

• target は、 video 要素であり、その表すものがポスターフレームまたは最初の動画フレームであり、そのフレームが利用可能である。

• target は、レンダリングされる子孫を持つ svg 要素である。

• target は、 input 要素であり、空でない value 属性を持つ。

• target は、起点要素であり、描画可能な 疑似要素の起点となり、その疑似要素はコンテンツを含む画像または空でないテキストを表す。

要素は、以下のいずれかの場合タイミング対象です：

• 1つの img コンテンツフル画像を表す要素。

• 1つの image 要素で、1つの svg 要素内にあるもの。

• 1つの video 要素で、ポスターフレームを持つもの。

• ある要素には background-image があり、それは コンテンツフル画像である。

• テキストノード。

ペイント可能境界矩形を要素targetで計算するには、次の手順を実行します：

1. boundingRectをgetBoundingClientRect() をtargetで実行した結果とする。

2. boundingRect を document の スクロール領域 でクリップする。

3. boundingRectを返す。

注意: overflow: scrollやoverflow: hiddenなボックスに含まれる要素は、ペイント可能境界矩形がクリップされません。どちらの場合でも、要素はスクロール操作で可視化できるためです。

要素 elは、次の全てを満たす場合ペイント可能です：

• el はレンダリングされている。

• el の使用 visibility は visible である。

• el およびそのすべての祖先の使用 不透明度は 0 より大きい。

  注記: 描画可能な要素が ユーザーに見えない場合があり得る。たとえば、テキストがその背景と同じ色である場合がこれに該当する。 これらの要素も、最初の コンテンツフルペイントを計算する目的では、引き続き描画可能であるとみなされる。

• el の描画可能な境界矩形は、スクロール領域とdocumentの交差部分を持つ。

  注記: これは、要素が サイズ 0 に拡大縮小されている場合、display: none である場合、または display: contents であり、その内容が空の 矩形に解決される場合を含む。

  注記: 一般則として、要素は、ビューポート内にある場合、または スクロールもしくはズームの結果としてビューポート内に入る可能性がある場合に描画可能である。

初回ペイントエントリーには、 DOMHighResTimeStamp ナビゲーション後にユーザーエージェントが初めてレンダリングした時刻を報告するものが含まれる。これには既定の背景の ペイントは含まれないが、既定以外の背景のペイントと、ペイント可能な iframe の包含ボックスが含まれる。これは、開発者が ページの読み込み時に重視する最初の重要な時点、すなわちユーザーエージェントがページのレンダリングを開始した時点である。

ブラウジングコンテキスト ctxは、以下のいずれかを満たす場合ペイントタイミング対象です：

• ctxが最上位ブラウジングコンテキストである。

• ctxが入れ子ブラウジングコンテキストで、ユーザーエージェントがctxにペイントタイミング報告を設定している。

  注意: これにより、ユーザーエージェントはメインフレーム以外の一部フレームに対してのみペイントタイミングを有効化できます。例えば、ユーザーエージェントがメインフレームの情報を漏らす可能性がある場合、クロスオリジンiframeに対してペイントタイミングを無効化することもできます。

3. ペイントタイミングミキシン

3.1. PaintTimingMixin インターフェース

[Exposed=Window]
interface mixin PaintTimingMixin {
    readonly attribute DOMHighResTimeStamp paintTime;
    readonly attribute DOMHighResTimeStamp? presentationTime;
};

PaintTimingMixin インターフェースミキシンを含むオブジェクトには、関連付けられたペイントタイミング情報（nullまたはペイントタイミング情報）があります。

ペイントタイミング情報は、 構造体です。以下の項目を持ちます:

レンダリング更新終了時刻

DOMHighResTimeStamp

実装依存のプレゼンテーション時刻

Null または DOMHighResTimeStamp

paintTime 属性のゲッターステップは、this の ペイントタイミング情報 の レンダリング更新終了時間 を返します。

presentationTime 属性のゲッターステップは、存在する場合、this の ペイントタイミング情報 の 実装依存の提示時間 を返します。

ペイントタイミング情報 paintTimingInfo のデフォルトペイントタイムスタンプを取得するには、 paintTimingInfo の 実装依存の提示時間 が null でない場合はそれを返し、それ以外の場合は paintTimingInfo の レンダリング更新終了時間 を返します。

4. PerformancePaintTiming インターフェイス

[Exposed=Window]
interface PerformancePaintTiming : PerformanceEntry {
    [Default] object toJSON();
};
PerformancePaintTiming includes PaintTimingMixin;

PerformancePaintTiming は PerformanceEntry インターフェイスの下記属性を拡張します：

• name 属性のgetterは、最小限のフレーム属性付けのために DOMString を返さなければならない。name の値として考えられるものは次の通り：

  • "first-paint": first paint 用

  • "first-contentful-paint": first contentful paint 用

• entryType 属性のgetterは "paint" を返さなければならない。

• startTime 属性のgetterは、塗りが発生した時刻の DOMHighResTimeStamp を返さなければならない。

• duration 属性のgetterは 0 を返さなければならない。

• toJSON が呼び出されたときは、 default toJSON steps を PerformancePaintTiming 用に実行する。

NOTE: PerformancePaintTiming を実装するユーザーエージェントは、"paint" を supportedEntryTypes に含める必要があります。 グローバルオブジェクト の ブラウジングコンテキスト が paint-timing eligible である場合です。 これにより、開発者は特定の ブラウジングコンテキスト に対してペイントタイミングのサポートを検出できます。

5. 処理モデル

5.1. 関連付けられた画像リクエスト

各 Element には 関連付けられた画像リクエスト があり、これは 画像リクエスト または null で、初期値は null です。

Element 型の element の処理モデルが HTMLImageElement, SVGImageElement, または HTMLVideoElement が新しい画像リソース（例：画像やポスター画像として表示されるため）を作成するとき、 element の 関連付けられた画像リクエスト は作成された画像リソースの 画像リクエスト に設定されます。

Note: URLの scheme が "data" である画像リソースは、取得されませんが依然として読み込む必要がある 画像リクエスト を持ちます。このリクエストは Element の 関連付けられた画像リクエスト となり得ます。

Note: 現在の記述は具体的な アルゴリズムには言及していないため曖昧です。該当する処理モデルがより統一された処理モデルを持つ場合、より厳密に記述できます。

全ての Element は 関連付けられた背景画像リクエスト のリストを持ち、初期値は空の配列です。Element element のスタイルが新しい画像リソース（背景画像として表示されるため）を必要とする場合、新しいリソースによって作成された 画像リクエスト が element の 関連付けられた背景画像リクエスト に追加されます。

NOTE: Element は複数の 画像リクエスト を持つことができます。例えば、 background-image プロパティが複数値を持つ場合です。下記例では、一つの background-image プロパティが4つの 画像リクエスト を生成し、それぞれが下記アルゴリズムで記録・報告されます。

<!DOCTYPE html>
<style>
div {
  background-image: url(https://images.example/background1.png),
                    url(https://images.example/background2.png);
}
</style>
<div></div>
<div></div>

5.2. ペイントタイミングの記録

pending image record は、以下の 構造体の 要素を持つものです。

• element、Element

• request、画像リクエスト

• loadTime, DOMHighResTimeStamp

Element は所有テキストノード集合（初期値は空の順序付き集合で、Text ノードを含む）を持ちます。

Document は過去に報告されたペイント集合（初期値は空の順序付き集合で、文字列を含む）を持ちます。

Document はレンダリング待ち画像（初期値は空のリストで、保留画像レコードを含む）を持ちます。

Document は描画済みテキストを持つ要素集合（初期値は空の順序付き集合で、Elementを含む）を持ちます。

5.2.1. CSS仕様への修正

画像リクエストがElementelementの関連背景画像リクエスト内で完全に利用可能となった場合、elementおよび画像リクエストを入力として読み込み完了画像の処理アルゴリズムを実行します。

5.2.2. HTML仕様への修正

Element elementの関連画像リクエストが完全に利用可能となった場合、elementとその関連画像リクエストを入力として読み込み完了画像の処理アルゴリズムを実行します。

5.2.3. 読み込み完了画像の処理

5.3. ペイントタイミングの報告

5.3.1. 最初の内容ペイント

5.3.2. ペイントタイミングのマーク

5.3.3. ペイントタイミングの報告

5.4. 共通アルゴリズム

5.4.1. ペイントタイミング向け公開

6. 謝辞

この仕様の技術的な貢献・提案を通じて改善に導いてくださった全てのコントリビューターに特別な感謝を表します。