영역 캡처

이 문서에서 제시하는 자르기 메커니즘 (cropTo)은 직접적인 노드 참조가 아니라 Crop-session 대상에 의존합니다. 이는 두 가지 목적에 기여합니다.

• 한 문서가 다른 문서에 지정된 좌표로 자르기를 수행할 수 있게 합니다.

• 태그 지정을 통해 Element를 잠재적 자르기 대상으로 만들면, 사용자 에이전트가 경계 상자 계산 및 그러한 좌표의 cross-process 전송과 같은, 다른 모든 요소에 대한 불필요한 작업을 피할 수 있습니다.

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 생성자를 통해 수행해야 하는지에 대해서는 아직 합의가 없습니다. 이는 이슈 #17에서 더 논의됩니다.

element를 입력으로 사용하여 CropTarget을 생성하려면, 다음 단계를 실행합니다:

1. cropTarget을 CropTarget 타입의 새 객체로 둡니다.

2. weakRef를 element에 대한 약한 참조로 둡니다.

   cropTarget.[[Element]]를 weakRef로 초기화하여 생성합니다.

   참고

   cropTarget은 자신이 나타내는 요소에 대한 약한 참조를 유지합니다. 다시 말해, cropTarget은 해당 요소의 가비지 컬렉션을 막지 않습니다.

CropTarget 객체는 직렬화 가능합니다. value, serialized 및 불리언 forStorage가 주어졌을 때, 직렬화 단계는 다음과 같습니다:

1. forStorage가 true이면, DOMException 객체를 새로 만들어 throw하며, 그 name 속성은 "DataCloneError" 값을 갖습니다.

2. serialized.[[CropTargetElement]]를 value.[[Element]]로 설정합니다.

serialized 및 value가 주어졌을 때, 역직렬화 단계는 다음과 같습니다:

1. value.[[Element]]를 serialized.[[CropTargetElement]]로 설정합니다.

[SCREEN-CAPTURE]에 따라, getDisplayMedia()가 호출되면, 그것은 Promise<MediaStream>를 반환하며, 이 MediaStream은 정확히 하나의 비디오 트랙을 포함하고, 그 타입은 MediaStreamTrack이라는 점을 떠올리십시오.

사용자가 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의 보이는 viewport로 제한되므로, 캡처되는 영역은 보이는 viewport와 요소의 경계 클라이언트 직사각형의 교차 영역이 됩니다. cropTo가 호출될 때마다, 사용자 에이전트는 다음 알고리즘을 실행해야 MUST 합니다:

1. cropTarget이 유효한 CropTarget도 아니고 null도 아니면, 사용자 에이전트는 UnknownError로 거부된 Promise를 반환해야 MUST 합니다.

2. p를 새 Promise로 둡니다.

3. 다음 단계를 병렬로 실행합니다:

   1. cropTarget이 undefined도 아니고 유효한 CropTarget도 아니면, p를 NotAllowedError로 거부하고 이 단계를 중단합니다.

   2. cropTarget이 undefined이거나 유효한 CropTarget이면, 사용자 에이전트는 this 비디오 트랙의 자르기 상태를 cropTarget에 따라 갱신해야 MUST 합니다:

      • cropTarget이 undefined로 설정되면, 사용자 에이전트는 자르기를 중지해야 MUST 합니다. This 비디오 트랙은 잘리지 않은 상태로 되돌아갑니다.
      • cropTarget이 유효한 CropTarget이면, 사용자 에이전트는 MUST this 비디오 트랙을 이 CropTarget이 참조하는 요소의 윤곽으로 자르기 시작해야 합니다. 이는 트랙에서 생성되는 각각의 새 프레임마다, 사용자 에이전트가 요소에 속하는 픽셀들의 경계 상자를 계산하고, 프레임을 이 경계 상자의 좌표로 자른다는 뜻입니다.

   3. 이 메서드 호출 전의 트랙 상태를 PRE-STATE, 이 메서드 호출 후의 상태를 POST-STATE라고 합니다. 사용자 에이전트는 MUST PRE-STATE에 따라 잘린(또는 잘리지 않은) 프레임이 더 이상 애플리케이션에 전달되지 않으며, 애플리케이션에 전달되는 추가 프레임은 따라서 POST-STATE 또는 이후 상태에 따라 잘린(또는 잘리지 않은) 프레임임이 보장될 때 p를 이행해야 합니다.

      참고

      cropTo promise의 이행 시점과 실제 비디오 프레임 자르기 시점은 MediaStreamTrack transforms를 통해 JavaScript에서 관찰할 수 있습니다. 새로 잘린 첫 번째 비디오 프레임은 cropTo promise가 이행된 직후 MediaStreamTrack ReadableStream에 enqueue될 것으로 예상됩니다.

4. p를 반환합니다.

clone()

BrowserCaptureMediaStreamTrack가 복제되면, 사용자 에이전트는 원본 트랙의 자르기 상태와 관계없이 처음에 잘리지 않은 상태인 트랙을 생성해야 MUST 합니다.