領域キャプチャ

この文書で提示される 切り抜き機構 (cropTo) は、直接的なノード参照ではなく、 Crop-session Target に依存する。 これは二重の目的を果たす。

• ある文書による切り抜きを、別の文書で指定された座標に基づいて行えるようにする。

• タグ付け により、Element を潜在的な切り抜きターゲットとして指定することで、ユーザーエージェントは 境界ボックスの計算や、そのような座標をプロセス間で送信することなど、他のすべての要素に対する 不要な作業を避けられる。

CropTarget は、意図的に空で不透明な識別子である。その目的は、入力として cropTo に渡されることである。

WebIDL[Exposed=(Window,Worker), Serializable]
interface CropTarget {
  [Exposed=Window, SecureContext] static Promise<CropTarget> fromElement(Element element);
};

fromElement()

サポートされる型の Element を指定して fromElement を呼び出すと、その Element は CropTarget に関連付けられる。この CropTarget は、 cropTo への入力として使用できる。 CropTarget.fromElement() の呼び出しによって返され、 かつまだ アクティブな 文書 内にあるものを、 有効な CropTarget と定義する。

指定された element で fromElement が呼び出されたとき、ユーザー エージェントは element を入力として CropTarget を作成する。 ユーザーエージェントは Promise p を返さ MUST。 ユーザーエージェントは、新しい CropTarget に関連付けられた状態の必要な内部伝播をすべて完了した後に限って p を解決し MUST、その時点でユーザーエージェントは、新しい CropTarget を cropTo への有効な パラメーターとして受け取る準備ができていなければ MUST ならない。

以前に fromElement が呼び出された Element をクローンする場合、 そのクローンはいかなる CropTarget とも関連付けられない。後でそのクローンに対して fromElement が呼び出された場合、 新しい CropTarget がそれに割り当てられる。

注記

CropTarget の生成を、 CropTarget.fromElement() のような非同期メソッドの呼び出しによって行うべきか、 それとも 入力として Element を受け取る CropTarget コンストラクターによって行うべきかについては、 まだ合意がない。これは issue #17 でさらに議論されている。

element を入力として CropTarget を作成するには、次の手順を実行する:

1. cropTarget を、型 CropTarget の新しいオブジェクトとする。

2. weakRef を element への弱参照とする。

   weakRef に初期化された cropTarget.[[Element]] を 作成する。

   注記

   cropTarget は、それが表す要素への弱参照を保持する。言い換えると、 cropTarget はその要素のガベージコレクションを妨げない。

CropTarget オブジェクトはシリアライズ可能である。 value、serialized、および真偽値 forStorage が与えられたときの シリアライズ 手順は次のとおりである:

1. forStorage が true の場合、 name 属性の 値が "DataCloneError" である 新しい DOMException オブジェクトで例外を投げる。

2. serialized.[[CropTargetElement]] を value.[[Element]] に設定する。

serialized および value が与えられたときの デシリアライズ 手順は次のとおりである:

1. value.[[Element]] を serialized.[[CropTargetElement]] に設定する。

[SCREEN-CAPTURE] によれば、 getDisplayMedia() が呼び出されたとき、 それは Promise<MediaStream> を返し、 この MediaStream には、 型が MediaStreamTrack である ビデオトラックが正確に 1 つ含まれることを思い出されたい。

ユーザーが browser display-surface のキャプチャを選択した場合、ユーザー エージェントはビデオトラックを MediaStreamTrack、 または MediaStreamTrack の何らかの サブクラスとしてインスタンス化しなければ MUST ならず、 かつ cropTo はこのトラックで公開されなければ MUST ならない、と規定する。簡単のため、この文書では、ユーザーエージェントによって BrowserCaptureMediaStreamTrack と呼ばれるサブクラスが使用されると仮定する。

トラックは初期状態で 未切り抜きでなければ MUST ならない。

WebIDL[Exposed = Window]
interface BrowserCaptureMediaStreamTrack : MediaStreamTrack {
  Promise<undefined> cropTo(CropTarget? cropTarget);
  BrowserCaptureMediaStreamTrack clone();
};

cropTo()

このメソッドの呼び出しは、ビデオトラックを cropTarget.[[Element]] の 境界クライアント矩形 に合わせて切り抜くことを開始/停止するようユーザーエージェントに指示する。トラックは display-surface の可視ビューポートに制限されるため、キャプチャされる 領域は、可視ビューポートと要素の境界クライアント矩形との交差部分になる。 cropTo が呼び出されるたびに、 ユーザーエージェントは次のアルゴリズムを実行しなければ MUST ならない:

1. cropTarget が 有効な CropTarget でも null でもない場合、 ユーザーエージェントは UnknownError で 拒否された Promise を返さなければ MUST ならない。

2. p を新しい Promise とする。

3. 次の手順を並列に実行する:

   1. cropTarget が undefined でも 有効な CropTarget でもない場合、 p を NotAllowedError で拒否し、これらの手順を中止する。

   2. cropTarget が undefined または 有効な CropTarget のいずれかである場合、 ユーザーエージェントは cropTarget に従って this ビデオトラックの 切り抜き状態を更新しなければ MUST ならない:

      • cropTarget が undefined に設定された場合、 ユーザーエージェントは 切り抜きを停止しなければ MUST ならない。This ビデオトラックは 未切り抜き状態に戻る。
      • cropTarget が 有効な CropTarget である場合、ユーザーエージェントは this ビデオトラックを、この CropTarget によって参照される要素の輪郭に合わせて 切り抜き始めなければ MUST ならない。これは、 トラック上で生成される各新しいフレームについて、ユーザーエージェントがその要素に属するピクセルの境界ボックスを計算し、 この境界ボックスの座標に合わせてフレームを切り抜くことを意味する。

   3. このメソッド呼び出し前のトラックの状態を PRE-STATE と呼び、 このメソッド呼び出し後の状態を POST-STATE と呼ぶ。ユーザーエージェントは、 PRE-STATE に従って切り抜かれた（または未切り抜きの）フレームがそれ以上アプリケーションに配信されないこと、 およびアプリケーションに配信される追加のフレームがしたがって POST-STATE または それ以降の状態のいずれかに従って切り抜かれる（または未切り抜きになる）ことが保証されたとき、 p を解決しなければ MUST ならない。

      注記

      cropTo promise の解決タイミングおよびビデオフレームの実際の切り抜きタイミングは、 MediaStreamTrack transforms を通じて JavaScript から観測可能である。 最初の新たに切り抜かれたビデオフレームは、cropTo promise が解決された直後に MediaStreamTrack ReadableStream にキュー投入されることが期待される。

4. p を返す。

clone()

BrowserCaptureMediaStreamTrack がクローンされるとき、ユーザーエージェントは、元のトラックの 切り抜き状態に関係なく、 初期状態で 未切り抜きであるトラックを生成しなければ MUST ならない。